3 files changed, 261 insertions, 56 deletions

diff --git a/app/models/node.rb b/app/models/node.rb
index a2e9981..4dae287 100644
--- a/app/models/node.rb
+++ b/app/models/node.rb
@@ -283,6 +283,87 @@ class Node < ApplicationRecord
     end
   end
 
+
+  # Moves this node and its subtree into the Trash. Demotes every head
+  # in the subtree first (aggregators and search operate on heads
+  # regardless of tree position); where a node has no draft, the former
+  # head becomes its draft so content stays editable and restorable --
+  # otherwise the former head remains a plain revision. One log entry,
+  # at the root, carrying the leaving-public-view snapshot.
+  def trash! current_user = nil
+    return nil if in_trash?
+    raise ActiveRecord::RecordInvalid.new(self), "The Trash node itself cannot be trashed" if trash_node?
+
+    ActiveRecord::Base.transaction do
+      path_before        = unique_name
+      was_published      = head_id.present?
+      final_published_at = head&.published_at
+
+      demoted = 0
+      ([self] + descendants.to_a).each do |node|
+        next unless node.head_id
+        former        = node.head
+        node.head     = nil
+        node.draft_id = former.id if node.draft_id.nil?
+        node.save!
+        demoted += 1
+      end
+
+      self.reload
+      move_to_child_of(Node.trash)
+      self.reload
+      update_unique_name
+      send(:update_unique_names_of_children)
+      unlock!
+
+      metadata = { :path => { "from" => path_before, "to" => unique_name } }
+      metadata[:was_published]      = true if was_published
+      metadata[:final_published_at] = final_published_at.iso8601 if final_published_at
+      metadata[:demoted_heads]      = demoted if demoted > 0
+
+      NodeAction.record!(:node => self, :user => current_user, :action => "trash", **metadata)
+      self
+    end
+  end
+
+  # Returns the node to the living tree under a chosen parent. The
+  # subtree comes back exactly as it sits in the Trash: all drafts,
+  # nothing published. Republication is a separate, witnessed act
+  # per node.
+  def restore_from_trash! new_parent, current_user = nil
+    return nil unless in_trash?
+
+    if new_parent.nil? || new_parent == self || descendants.include?(new_parent) ||
+       new_parent.trash_node? || new_parent.in_trash?
+      raise ActiveRecord::RecordInvalid.new(self), "Restore target must be a living node"
+    end
+
+    ActiveRecord::Base.transaction do
+      path_before = unique_name
+      move_to_child_of(new_parent)
+      self.reload
+      update_unique_name
+      send(:update_unique_names_of_children)
+
+      NodeAction.record!(:node => self, :user => current_user, :action => "restore_from_trash",
+                          :path => { "from" => path_before, "to" => unique_name })
+      self
+    end
+  end
+
+  # Final deletion. Only from inside the Trash, never with children.
+  # The log entry is written first, in the same transaction; node_id
+  # nullifies when the row dies, and the metadata carries what remains.
+  def destroy_from_trash! current_user = nil
+    raise ActiveRecord::RecordInvalid.new(self), "Nodes are only destroyed from the Trash" unless in_trash?
+
+    ActiveRecord::Base.transaction do
+      NodeAction.record!(:node => self, :user => current_user, :action => "destroy",
+                          :path => unique_name)
+      destroy!
+    end
+  end
+
   # returns an array with all parts of a unique_name rather than a string
   def unique_path
     unique_name.to_s.split("/")
diff --git a/app/models/node_action.rb b/app/models/node_action.rb
index 792ae1e..6e09b5b 100644
--- a/app/models/node_action.rb
+++ b/app/models/node_action.rb
@@ -8,79 +8,76 @@ class NodeAction < ApplicationRecord
 
   # == Metadata contract ==
   #
-  # metadata is written once at creation and never updated. It is the
+  # metadata is written once at creation, never updated. It is the
   # single place anything that must survive deletion of the referenced
   # rows lives; node_id/page_id/user_id are lookup and ordering only.
-  # All keys are strings. Pairs are always {"from" => x, "to" => y} --
-  # never _old/_new suffixes. Optional pairs are written only when the
-  # two sides differ; required keys are always present. All titles and
-  # names are read pinned to I18n.default_locale unless inside a
-  # locale-keyed block.
+  # All keys are strings. Pairs are always {"from" => x, "to" => y}.
+  # Optional pairs only when the sides differ; booleans only when
+  # true; required keys always present. Titles and names are read
+  # pinned to I18n.default_locale unless inside a locale-keyed block.
   #
   # Baseline, every entry (written here, not by call sites):
   #   "username"                 -- actor's login at write time
   #   "human_readable_node_name" -- node title, default locale
   #
   # "create":
-  #   "title" -- initial title, default locale
-  #   "path"  -- unique path at creation time. Historical value only:
-  #              later renames/moves do NOT update old entries. Never
-  #              use as a join key; node_id is the join key while the
-  #              node lives.
+  #   "title" -- initial title, flat string (NOT a pair)
+  #   "path"  -- unique path at creation, flat string. Historical
+  #              value only; never a join key.
   #
-  # "publish" (any promotion of a page to head; the diff against the
-  # outgoing head is computed BEFORE head is re-pointed, over the
-  # union of both pages' locales, by the shared diff function also
-  # used by the backfill):
-  #   "via"    -- "draft" (ordinary publish) | "revision" (rollback
-  #               via restore_revision!). Always written; absent
-  #               means a pre-contract entry.
-  #   "title"  -- pair, always present. "from" is null on a first
-  #               publish (no outgoing head).
-  #   "author" -- pair, only when the byline (page.user) changed
-  #   "tags"   -- pair of arrays, only when changed
-  #   "assets_changed", "template_changed"
-  #            -- booleans, only when true; page_id links to the
-  #               revision for the real diff (never stored here)
+  # "publish" (any promotion to head; diff computed BEFORE head is
+  # re-pointed, over the union of both pages' locales, by head_diff --
+  # shared with the backfill):
+  #   "via"    -- "draft" | "revision" (rollback). Always written;
+  #               absent means a pre-contract entry.
+  #   "title"  -- pair, always; "from" null on first publish
+  #   "author" -- pair, when the byline changed (incl. first publish)
+  #   "tags"   -- pair of arrays, when changed
+  #   "assets_changed", "template_changed",
   #   "abstract_changed", "body_changed"
-  #            -- booleans for the default locale, only when true
-  #   "translation_diff" -- only when any non-default locale differs:
+  #            -- the last two for the default locale; page_id links
+  #               to the revision for the real diff (never stored)
+  #   "translation_diff" -- only when a non-default locale differs:
   #     { "<locale>" => {
-  #         "status"           -- "added" | "removed" | "changed"
-  #         "title"            -- pair; "from" null when added,
-  #                               "to" null when removed
-  #         "abstract_changed", "body_changed" -- booleans, only when
-  #                               true, only for status "changed"
+  #         "status" -- "added" | "removed" | "changed"
+  #         "title"  -- pair, only when it differs; "from" null when
+  #                     added, "to" null when removed
+  #         "abstract_changed", "body_changed" -- status "changed" only
   #     } }
   #
-  # "move" (reparenting and/or unique-path change; one entry at the
-  # subtree root, descendants get none -- a descendant's own zoomed
-  # view will not show path history):
-  #   "path"  -- pair
+  # "move" (reparent and/or path change; one entry at the subtree
+  # root, descendants get none):
+  #   "path" -- pair
   #
-  # Reserved for the Trash feature, final shape decided there:
-  # "demote" (via "trash" | "depublish"; carries the leaving-public-
-  # view snapshot: head presence, final published_at), "trash",
-  # "restore_from_trash", "destroy" (final path only; publish-state
-  # snapshot lives on the entry that removed it from public view).
-  # Whether trash logs one entry or a trash+demote pair is decided
-  # with that feature.
+  # "trash" (subtree into the Trash; every head in the subtree is
+  # demoted first; one entry at the root; snapshots the
+  # leaving-public-view state, since Trash holds no heads and destroy
+  # can no longer know):
+  #   "path"               -- pair; "from" doubles as the restore hint
+  #   "was_published"      -- boolean
+  #   "demoted_heads"      -- integer count, only when positive
+  #   "final_published_at" -- ISO8601 string, only when present
   #
-  # Backfilled entries mirror this vocabulary exactly. Their diff
-  # content is computed, not guessed (consecutive revisions still
-  # exist); only actor (from page.editor) and occurred_at are
-  # inferred, and inferred_from names the heuristic per entry
-  # ("from_page_revision", "from_published_at_heuristic").
-  # inferred_from null = witnessed live.
+  # "restore_from_trash" (reparent back to a living node; returns as
+  # drafts, republication is a separate witnessed act):
+  #   "path" -- pair
   #
-  # The "locale" column is currently written by no verb (it belonged
-  # to the retired translation_destroy) and is retained for backfill
-  # or future draft-scoped verbs.
+  # "destroy" (only from inside the Trash, never with children; the
+  # entry is written in the same transaction before the row dies):
+  #   "path" -- final path, flat string (create-symmetric)
   #
-  # This log records; it does not undo. Reversibility stays in
-  # restore_revision! and the revisions system. No IP, session, or
-  # user agent, ever. Success only -- rejected attempts are not
-  # logged.
+  # Reserved: "demote" (via "trash" | "depublish") for an explicit
+  # depublish workflow, if ever built.
+  #
+  # Backfilled entries mirror this vocabulary; diff content is
+  # computed, only actor (page.editor) and occurred_at are inferred,
+  # inferred_from names the heuristic ("from_node_created_at",
+  # "from_page_revision"). Null = witnessed live.
+  #
+  # The "locale" column is written by no verb; retained.
+  #
+  # This log records; it does not undo. No IP, session, or user
+  # agent, ever. Success only.
 
   def self.record!(node:, action:, user: nil, page: nil, locale: nil,
                     occurred_at: nil, inferred_from: nil, **extra)
diff --git a/test/models/node_trash_test.rb b/test/models/node_trash_test.rb
new file mode 100644
index 0000000..b72770b
--- /dev/null
+++ b/test/models/node_trash_test.rb
@@ -0,0 +1,127 @@
+require "test_helper"
+
+class NodeTrashTest < ActiveSupport::TestCase
+
+  def setup
+    @user1 = User.create!(:login => "trasher", :email => "t@example.com",
+                           :password => "foobar", :password_confirmation => "foobar")
+  end
+
+  test "trash! demotes the head into the draft slot when no draft exists" do
+    node = create_node_with_published_page
+    former_head = node.head
+
+    node.trash!(@user1)
+    node.reload
+
+    assert_nil node.head_id
+    assert_equal former_head, node.draft
+    assert node.in_trash?
+  end
+
+  test "trash! keeps an existing draft; the former head stays a plain revision" do
+    node = create_node_with_published_page
+    draft = find_or_create_draft(node, @user1)
+    former_head = node.head
+
+    node.trash!(@user1)
+    node.reload
+
+    assert_nil node.head_id
+    assert_equal draft, node.draft
+    assert_includes node.pages, former_head
+  end
+
+  test "trash! demotes descendant heads and counts them in the log entry" do
+    parent = create_node_with_published_page
+    child  = parent.children.create!(:slug => "trashed_child")
+    child.draft.update!(:title => "Child")
+    child.publish_draft!(@user1)
+
+    parent.trash!(@user1)
+
+    action = NodeAction.where(:action => "trash").last
+    assert_equal parent, action.node
+    assert_equal 2, action.metadata["demoted_heads"]
+    assert action.metadata["was_published"]
+    assert_nil child.reload.head_id
+    assert child.in_trash?
+  end
+
+  test "trash! logs one entry with the path pair and updates unique names" do
+    node = create_node_with_published_page
+    path_before = node.unique_name
+
+    assert_difference "NodeAction.count", 1 do
+      node.trash!(@user1)
+    end
+
+    action = NodeAction.last
+    assert_equal path_before, action.metadata.dig("path", "from")
+    assert_equal node.reload.unique_name, action.metadata.dig("path", "to")
+    assert action.metadata.dig("path", "to").start_with?(CccConventions::TRASH_SLUG)
+  end
+
+  test "trash! on an already trashed node is a logged-nothing no-op" do
+    node = create_node_with_published_page
+    node.trash!(@user1)
+
+    assert_no_difference "NodeAction.count" do
+      assert_nil node.reload.trash!(@user1)
+    end
+  end
+
+  test "restore_from_trash! reparents as drafts without republishing" do
+    node = create_node_with_published_page
+    node.trash!(@user1)
+    target = Node.root.children.create!(:slug => "restore_target")
+
+    node.reload.restore_from_trash!(target, @user1)
+    node.reload
+
+    assert_equal target, node.parent
+    assert_not node.in_trash?
+    assert_nil node.head_id
+    assert_not_nil node.draft_id
+    assert_equal "restore_from_trash", NodeAction.last.action
+  end
+
+  test "restore_from_trash! refuses targets inside the Trash and the Trash itself" do
+    node = create_node_with_published_page
+    node.trash!(@user1)
+    other_trashed = Node.trash.children.create!(:slug => "also_trashed")
+
+    assert_raises(ActiveRecord::RecordInvalid) { node.reload.restore_from_trash!(Node.trash, @user1) }
+    assert_raises(ActiveRecord::RecordInvalid) { node.reload.restore_from_trash!(other_trashed, @user1) }
+  end
+
+  test "destroy_from_trash! refuses nodes outside the Trash" do
+    node = create_node_with_published_page
+
+    assert_raises(ActiveRecord::RecordInvalid) { node.destroy_from_trash!(@user1) }
+    assert Node.exists?(node.id)
+  end
+
+  test "destroy_from_trash! refuses nodes with children" do
+    node = create_node_with_published_page
+    node.children.create!(:slug => "still_here")
+    node.trash!(@user1)
+
+    assert_raises(ActiveRecord::RecordNotDestroyed) { node.reload.destroy_from_trash!(@user1) }
+  end
+
+  test "destroy_from_trash! logs an entry that survives the node" do
+    node = create_node_with_published_page
+    Globalize.with_locale(I18n.default_locale) { node.head.update!(:title => "Doomed") }
+    node.trash!(@user1)
+    final_path = node.reload.unique_name
+
+    node.destroy_from_trash!(@user1)
+
+    action = NodeAction.where(:action => "destroy").last
+    assert_nil action.node_id
+    assert_equal final_path, action.metadata["path"]
+    assert_equal "Doomed", action.subject_name
+    assert_equal @user1, action.user
+  end
+end