riskrails 4.0.1 → 4.2.0

package/skills/ai-task/rr_state/memory_cmd.py

@@ -1,4 +1,4 @@
-"""memory_cmd: the `memory` and `recall` commands over the memory_store and memory_sync modules -- the actions, the human's route, the risk record.
+"""memory_cmd: the `memory` and `recall` commands over the memory_store module and the owner modules memory_io, memory_config, memory_verify, memory_hook, memory_risks, memory_cleanup, memory_migrate, memory_export and memory_status -- the actions, the human's route, the risk record.
 
 shell: memory_modules, memory_config, memory_human, memory_confirm, cmd_recall, cmd_memory, memory_status, memory_enable, memory_disable, memory_export, memory_verify, memory_show, memory_search, risk_scope, memory_risk, memory_risks, memory_migrate, memory_rebuild, memory_cleanup, memory_restore, memory_pack, memory_redact
 core: MEMORY_ACTIONS
@@ -9,6 +9,7 @@ import json
 import os
 import shlex
 import sys
+import types
 
 from rr_state import fs, journal, task
 from rr_state import dialog as rr_dialog
@@ -22,26 +23,39 @@ except ImportError:                       # an old install that shipped state.py
 
 
 def memory_modules():
-    """memory_sync and memory_store, imported only by the commands that use them."""
+    """The owner modules of the memory commands as one namespace (mem.io, mem.config, mem.verify, mem.hook,
+    mem.risks, mem.cleanup, mem.migrate, mem.export, mem.status -- each name is read on its owner at call time)
+    and memory_store, imported only by the commands that use them."""
     try:
         import memory_store               # pylint: disable=import-outside-toplevel
-        import memory_sync                # pylint: disable=import-outside-toplevel
+        import memory_cleanup as cleanup  # pylint: disable=import-outside-toplevel
+        import memory_config as config  # pylint: disable=import-outside-toplevel
+        import memory_export as export  # pylint: disable=import-outside-toplevel
+        import memory_hook as hook  # pylint: disable=import-outside-toplevel
+        import memory_io as io  # pylint: disable=import-outside-toplevel
+        import memory_migrate as migrate  # pylint: disable=import-outside-toplevel
+        import memory_risks as risks  # pylint: disable=import-outside-toplevel
+        import memory_status as status  # pylint: disable=import-outside-toplevel
+        import memory_verify as verify  # pylint: disable=import-outside-toplevel
     except ImportError as exc:
         fs.die("the memory modules are not installed beside state.py (%s)" % exc, 2)
-    return memory_sync, memory_store
+    mem = types.SimpleNamespace(cleanup=cleanup, config=config, export=export, hook=hook, io=io, migrate=migrate,
+                                risks=risks, status=status, verify=verify)
+    return mem, memory_store
 
 
-def memory_config(sync, root):
+def memory_config(mem, root):
     try:
-        return sync.load_config(root)
-    except sync.MemoryError_ as exc:
+        return mem.config.load_config(root)
+    except mem.io.MemoryError_ as exc:
         fs.die(str(exc), exc.code)
     return None
 
 
-def memory_human(root, what, rt=rr_runtime.Runtime()):
-    """R16: enable, disable, cleanup, pack, redact and move-logs take the human's route, as approve does."""
-    via, why = rr_dialog.human_route(root, rt=rt)
+def memory_human(root, what, allow_dialog=False, rt=rr_runtime.Runtime()):
+    """R16: enable, disable, cleanup, pack, redact and move-logs take the human's route, as approve does. Only
+    enable passes allow_dialog: a live pick of this session that is this very command is the human's answer."""
+    via, why = rr_dialog.human_route(root, allow_dialog=allow_dialog, rt=rt)
     if via is None:
         fs.die("APPROVAL_REFUSED — 'memory %s' is the human's, from their own terminal:\n  python3 %s --root %s "
             "%s\nRefused because %s." % (what, shlex.quote(fs.ENTRY), shlex.quote(root),
@@ -61,8 +75,8 @@ def memory_confirm(cfg, name, what):
 def cmd_recall(args, root, rt=rr_runtime.Runtime()):
     """R10: the open risks, residual findings, decisions, scope changes and task
     one-liners that touch these files, within the budget. Read-only."""
-    sync, store = memory_modules()
-    cfg = memory_config(sync, root)
+    mem, store = memory_modules()
+    cfg = memory_config(mem, root)
     files = fs._split_files(args.files)
     if not files:
         fs.die("recall needs --files \"a,b,dir/**\"", 2)
@@ -81,43 +95,49 @@ def cmd_recall(args, root, rt=rr_runtime.Runtime()):
 
 
 def cmd_memory(args, root, rt=rr_runtime.Runtime()):
-    sync, store = memory_modules()
+    mem, store = memory_modules()
     action = args.memory_action
     try:
-        MEMORY_ACTIONS[action](args, root, sync, store, rt=rt)
-    except sync.MemoryError_ as exc:
+        MEMORY_ACTIONS[action](args, root, mem, store, rt=rt)
+    except mem.io.MemoryError_ as exc:
         fs.die(str(exc), exc.code)
 
 
-def memory_status(args, root, sync, _store, rt=rr_runtime.Runtime()):
-    lines = sync.status_lines(root)
+def memory_status(args, root, mem, _store, rt=rr_runtime.Runtime()):
+    lines = mem.status.status_lines(root)
     if args.json:
         print(json.dumps(dict(line.split(": ", 1) for line in lines), ensure_ascii=False, sort_keys=True))
         return
     print("\n".join(lines))
 
 
-def memory_enable(args, root, sync, _store, rt=rr_runtime.Runtime()):
-    memory_human(root, "enable", rt=rt)
-    hook = sync.enable(root, args.author, args.period, args.index)
-    print("memory: packages mode on (%s); every teammate's next close exports" % sync.POLICY_REL)
-    print("pre-push: %s" % hook)
+def memory_enable(args, root, mem, _store, rt=rr_runtime.Runtime()):
+    if memory_human(root, "enable", allow_dialog=True, rt=rt) == "dialog":
+        pick = rr_dialog.pick_data(rr_dialog.DIALOG_PICK[0])
+        print("memory: via dialog (consent %s, decision %s)" % (pick["consent"], pick["decision"]))
+    hook = mem.hook.enable(root, args.author, args.period, args.index, args.share)
+    print("memory: packages mode on (%s); every teammate's next close exports" % mem.io.POLICY_REL)
+    if hook == "local":
+        print("record: local — .ai/memory/ and .ai/reports/ are git-ignored; 'state.py memory enable --share git' "
+              "in your own terminal shares them through git and checks pushes")
+    else:
+        print("pre-push: %s" % hook)
     if hook in ("foreign", "hookspath"):
         print("not written — %s. Add these lines to your own pre-push hook:\n%s" % (
-            "core.hooksPath is set" if hook == "hookspath" else "a pre-push hook exists", sync.snippet_text()))
-    print("\n".join(sync.status_lines(root)))
+            "core.hooksPath is set" if hook == "hookspath" else "a pre-push hook exists", mem.hook.snippet_text()))
+    print("\n".join(mem.status.status_lines(root)))
 
 
-def memory_disable(_args, root, sync, _store, rt=rr_runtime.Runtime()):
+def memory_disable(_args, root, mem, _store, rt=rr_runtime.Runtime()):
     memory_human(root, "disable", rt=rt)
-    print("memory: files mode; packages and local data kept; pre-push: %s" % sync.disable(root))
+    print("memory: files mode; packages and local data kept; pre-push: %s" % mem.hook.disable(root))
 
 
-def memory_export(args, root, sync, _store, rt=rr_runtime.Runtime()):
-    cfg = memory_config(sync, root)
+def memory_export(args, root, mem, _store, rt=rr_runtime.Runtime()):
+    cfg = memory_config(mem, root)
     ids = "pending" if args.pending or not args.ids else [task.valid_task_id(t, "ID") for t in args.ids]
-    result = sync.export(root, ids, cfg)
-    for line in sync.record_lines(result):
+    result = mem.export.export(root, ids, cfg)
+    for line in mem.export.record_lines(result):
         print(line)
     print("exported: +%d entries%s" % (result.added, "" if result.added else " — nothing pending"))
     for task_id, why in result.failures:
@@ -126,36 +146,39 @@ def memory_export(args, root, sync, _store, rt=rr_runtime.Runtime()):
         sys.exit(1)
 
 
-def memory_verify(args, root, sync, _store, rt=rr_runtime.Runtime()):
+def memory_verify(args, root, mem, _store, rt=rr_runtime.Runtime()):
     stats = None
     if args.range:
         if ".." not in args.range:
             fs.die("--range takes OLD..NEW", 2)
         old, new = args.range.split("..", 1)
-        findings, stats = sync.validate_range(root, sync.rev(root, old), sync.rev(root, new) or new, local=False)
+        findings, stats = mem.verify.validate_range(root, mem.verify.rev(root, old), mem.verify.rev(root, new) or new, local=False)
         findings = findings or []
     elif args.fresh_clone:
-        findings = sync.verify_fresh_clone(root)
+        if not mem.io.shared(root):
+            fs.die("the record is local (.ai/memory/ is git-ignored): a fresh clone has none — "
+                   "'state.py memory enable --share git' shares it", 2)
+        findings = mem.verify.verify_fresh_clone(root)
     else:
-        findings = sync.verify(root, "all", [task.valid_task_id(t, "ID") for t in args.ids] or None)
+        findings = mem.verify.verify(root, "all", [task.valid_task_id(t, "ID") for t in args.ids] or None)
     failing = [f for f in findings if not f.check.endswith("-warn")]
     if args.json:
         print(json.dumps({"findings": [f._asdict() for f in findings], "ok": not failing, "stats": stats},
                          ensure_ascii=False, sort_keys=True))
     else:
         for f in findings:
-            print(sync.format_finding(f))
+            print(mem.verify.format_finding(f))
         print("memory verify: %s" % ("ok" if not failing else "%d finding(s)" % len(failing)))
     if failing:
         sys.exit(1)
 
 
-def memory_show(args, root, sync, _store, rt=rr_runtime.Runtime()):
-    print("\n".join(sync.show(root, task.valid_task_id(args.id, "ID"), "json" if args.json else "md", args.entry)))
+def memory_show(args, root, mem, _store, rt=rr_runtime.Runtime()):
+    print("\n".join(mem.status.show(root, task.valid_task_id(args.id, "ID"), "json" if args.json else "md", args.entry)))
 
 
-def memory_search(args, root, sync, store, rt=rr_runtime.Runtime()):
-    cfg = memory_config(sync, root)
+def memory_search(args, root, mem, store, rt=rr_runtime.Runtime()):
+    cfg = memory_config(mem, root)
     filters = {"kind": args.kind, "by": args.by, "task": args.task, "since": args.since, "until": args.until,
                "files": fs._split_files(args.file) or None}
     history = store.open_history(root, cfg)
@@ -184,8 +207,8 @@ def risk_scope(state):
             6)
 
 
-def memory_risk(args, root, sync, store, rt=rr_runtime.Runtime()):
-    cfg = memory_config(sync, root)
+def memory_risk(args, root, mem, store, rt=rr_runtime.Runtime()):
+    cfg = memory_config(mem, root)
     state = task.in_flight(root, rt=rt)
     if args.risk_action == "add":
         where = fs._split_files(args.where)
@@ -196,17 +219,17 @@ def memory_risk(args, root, sync, store, rt=rr_runtime.Runtime()):
         if not cfg.packages:
             risk_scope(state)
             found = "%s, by %s" % (fs.now()[:10], state["task_id"] if state else "no task")
-            rkey = sync.risk_add_files(root, args.title, where, args.label, args.what, args.likely, args.fix,
+            rkey = mem.risks.risk_add_files(root, args.title, where, args.label, args.what, args.likely, args.fix,
                                        args.status, found)
             print("risk: %s added to .ai/project/known-risks.md" % rkey)
             return
-        data = sync.risk_data(args.title, where, args.label, args.what, args.likely, args.fix, args.status)
+        data = mem.risks.risk_data(args.title, where, args.label, args.what, args.likely, args.fix, args.status)
     else:
         if args.status not in ("fixed", "accepted", "ticketed"):
             fs.die("--status takes fixed, accepted or ticketed", 2)
         if not cfg.packages:
             risk_scope(state)
-            sync.risk_close_files(root, args.rkey, args.status, args.why)
+            mem.risks.risk_close_files(root, args.rkey, args.status, args.why)
             print("risk: %s is %s" % (args.rkey, args.status))
             return
         history = store.FileHistory(root, cfg)
@@ -214,7 +237,7 @@ def memory_risk(args, root, sync, store, rt=rr_runtime.Runtime()):
         if not found:
             fs.die("no risk %s ('state.py memory risks --status all')" % args.rkey, 1)
         last = found[0]
-        data = sync.risk_data(last["title"], last.get("where"), last.get("label"), last.get("what"),
+        data = mem.risks.risk_data(last["title"], last.get("where"), last.get("label"), last.get("what"),
                               last.get("likelihood"), last.get("fix"), args.status, args.why, last["rid"])
     if state:
         state = task.load(root, rt=rt)
@@ -222,12 +245,12 @@ def memory_risk(args, root, sync, store, rt=rr_runtime.Runtime()):
         task.save(root, state)
         print("risk: %s recorded in %s's journal (exported at close)" % (data["rkey"], state["task_id"]))
         return
-    entry = sync.standalone_risk(root, cfg, data, rt.name)
+    entry = mem.risks.standalone_risk(root, cfg, data, rt.name)
     print("risk: %s recorded (%s)" % (data["rkey"], entry["rid"]))
 
 
-def memory_risks(args, root, sync, store, rt=rr_runtime.Runtime()):
-    cfg = memory_config(sync, root)
+def memory_risks(args, root, mem, store, rt=rr_runtime.Runtime()):
+    cfg = memory_config(mem, root)
     risks = store.open_history(root, cfg).risks(args.status)
     if args.json:
         for e in risks:
@@ -250,57 +273,57 @@ def memory_risks(args, root, sync, store, rt=rr_runtime.Runtime()):
                                           e.get("title"), e.get("rkey")))
 
 
-def memory_migrate(args, root, sync, _store, rt=rr_runtime.Runtime()):
-    cfg = memory_config(sync, root)
+def memory_migrate(args, root, mem, _store, rt=rr_runtime.Runtime()):
+    cfg = memory_config(mem, root)
     if args.move_logs:
         memory_human(root, "migrate --move-logs", rt=rt)
         memory_confirm(cfg, args.confirm_delete, "migrate --move-logs")
-        moved, command = sync.move_logs(root)
+        moved, command = mem.migrate.move_logs(root)
         print("moved %d committed log(s) into .ai/state/logs/<id>/legacy/; now, as its own commit (C3):\n  %s"
               % (len(moved), command))
         return
     if args.apply:
-        print("\n".join(sync.migrate_apply(root, risks=args.risks)))
+        print("\n".join(mem.migrate.migrate_apply(root, risks=args.risks)))
         return
-    report = sync.migrate_report(root)
+    report = mem.migrate.migrate_report(root)
     print("report: %s (%d lines) — read it, then 'state.py memory migrate --apply'"
-          % (os.path.join(sync.LOCAL_REL, "migration-report.md"), report.count("\n")))
+          % (os.path.join(mem.io.LOCAL_REL, "migration-report.md"), report.count("\n")))
 
 
-def memory_rebuild(_args, root, sync, store, rt=rr_runtime.Runtime()):
-    cfg = memory_config(sync, root)
+def memory_rebuild(_args, root, mem, store, rt=rr_runtime.Runtime()):
+    cfg = memory_config(mem, root)
     print("index: rebuilt from %d sources (%s)" % (store.SqliteHistory(root, cfg).rebuild(), store.INDEX_REL))
 
 
-def memory_cleanup(args, root, sync, _store, rt=rr_runtime.Runtime()):
-    cfg = memory_config(sync, root)
+def memory_cleanup(args, root, mem, _store, rt=rr_runtime.Runtime()):
+    cfg = memory_config(mem, root)
     memory_human(root, "cleanup", rt=rt)
     memory_confirm(cfg, args.confirm_delete, "cleanup")
     if not args.all and not args.ids:
         fs.die("memory cleanup takes IDs or --all", 2)
-    print("\n".join(sync.cleanup(root, "all" if args.all else [task.valid_task_id(t, "ID") for t in args.ids])))
+    print("\n".join(mem.cleanup.cleanup(root, "all" if args.all else [task.valid_task_id(t, "ID") for t in args.ids])))
 
 
-def memory_restore(args, root, sync, _store, rt=rr_runtime.Runtime()):
+def memory_restore(args, root, mem, _store, rt=rr_runtime.Runtime()):
     if not args.all and not args.ids:
         fs.die("memory restore takes IDs or --all", 2)
-    print("\n".join(sync.restore(root, "all" if args.all else [task.valid_task_id(t, "ID") for t in args.ids])))
+    print("\n".join(mem.cleanup.restore(root, "all" if args.all else [task.valid_task_id(t, "ID") for t in args.ids])))
 
 
-def memory_pack(args, root, sync, _store, rt=rr_runtime.Runtime()):
-    cfg = memory_config(sync, root)
+def memory_pack(args, root, mem, _store, rt=rr_runtime.Runtime()):
+    cfg = memory_config(mem, root)
     memory_human(root, "pack", rt=rt)
     memory_confirm(cfg, args.confirm_delete, "pack")
-    target, removed, count = sync.pack(root, args.period)
-    print("pack: %s (%d records; %d batch(es) removed)" % (os.path.join(sync.MEMORY_REL, target), count,
+    target, removed, count = mem.cleanup.pack(root, args.period)
+    print("pack: %s (%d records; %d batch(es) removed)" % (os.path.join(mem.io.MEMORY_REL, target), count,
                                                           len(removed)))
 
 
-def memory_redact(args, root, sync, _store, rt=rr_runtime.Runtime()):
+def memory_redact(args, root, mem, _store, rt=rr_runtime.Runtime()):
     via = memory_human(root, "redact", rt=rt)
-    rid, name = sync.redact(root, args.rid, args.field, args.why, by="%s via %s" % (os.environ.get("USER") or
+    rid, name = mem.cleanup.redact(root, args.rid, args.field, args.why, by="%s via %s" % (os.environ.get("USER") or
                                                                                    "unknown", via))
-    print("redacted: %s in %s (new rid %s)" % (args.field, os.path.join(sync.MEMORY_REL, name), rid))
+    print("redacted: %s in %s (new rid %s)" % (args.field, os.path.join(mem.io.MEMORY_REL, name), rid))
 
 
 MEMORY_ACTIONS = {"status": memory_status, "enable": memory_enable, "disable": memory_disable,

package/skills/project-update/history/blobs/8ec171f0fbdf38cc6996d496f01491fd1f21f04a435a118ad979b127a8be06f1

@@ -0,0 +1,85 @@
+# Safety policy
+
+This is the file every agent reads first. It is short on purpose. It binds every
+agent in every runtime — Claude Code and Codex alike.
+
+## The one rule
+
+**Production behaviour is the source of truth until proven otherwise.** Code that
+looks wrong, dead, or badly written may be load-bearing. The repository's history
+is evidence; your intuition about how the code "should" look is not.
+
+## What an agent must never do
+
+- Change application code that the current task did not ask about.
+- Rename, move, reorganise or "clean up" anything as a side effect.
+- Remove code because it looks unused. Find the callers first; if there are none,
+  say so in the report and leave the code alone.
+- Combine a refactoring with a feature change in the same step.
+- Modify database schemas, dependencies or framework versions outside a task that
+  is explicitly about that.
+- Weaken a test, a linter rule or a static-analysis level to make a check pass.
+- Commit, push, merge or deploy on its own initiative.
+- Read production secrets or customer data into the model context.
+
+If you find a problem outside the current task: **write it down, do not fix it.**
+Unrelated findings are recorded with `state.py memory risk add` (in files mode it
+writes `.ai/project/known-risks.md`) or go into the report's "observations"
+section, and the human decides whether they become their own task.
+
+The compact record is the human's to switch: `state.py memory enable`, `disable`,
+`cleanup`, `pack`, `redact` and `migrate --move-logs` take the human route, as
+`approve` does. `enable` may also run as the command the human picked in the
+`/rr-setup` dialog; the rest have no dialog route. `.ai/memory/` and
+`.ai/local/memory/` are written by `state.py` alone — an agent never edits them
+(`state.py memory --help`; the plugin's `docs/local-memory.md`).
+
+## Scope
+
+Every implementation step names the files it may touch. Editing anything else is
+refused by `ai-scope-guard` and must be answered with `SCOPE_CHANGE_REQUIRED`:
+stop, say which file you need and why, and let the plan be amended. A step whose
+scope keeps growing is a step that was planned wrong.
+
+`ai-git-guard`, `ai-path-guard` and `ai-scope-guard` all run in both runtimes. A
+multi-file edit in one call — Codex's `apply_patch` — is checked path by path, so
+a single out-of-scope or protected file rejects the whole patch. What a guard
+refuses is not a hint: do not reword the command to get past it.
+
+A guard is a backstop, not the policy. Some checks exist in only one runtime —
+Codex has no hookable read tool, so the large-read cap is Claude-only there — and
+an agent that behaves correctly only because a hook is watching is not behaving
+correctly. The rules above hold whether or not a hook enforces them.
+
+**The guards' threat model.** The guards defend against an agent's mistakes — a
+careless `rm`, a write to a frozen policy during a task, a commit with a
+secret — not against an agent that constructs a command to exhaust them. A
+command built to time the guard out is visible in the transcript and in the
+journal, and the human gate in full and full_irreversible mode is the boundary
+for anything that matters.
+Approval rests on a guard plus a ledger: a command the agent constructs to pass
+for the human's pick is outside the threat model, and `state.py consent audit`
+detects it afterwards.
+
+## Evidence labels
+
+Anything an agent writes into `.ai/project/` carries one of four labels:
+
+- **KNOWN FACT** — read from the code, a config file, a migration or a test.
+  Cite `file:line`.
+- **INFERENCE** — a conclusion drawn from facts. Say what it is drawn from.
+- **UNKNOWN** — something that matters and could not be determined. Say what
+  would answer it.
+- **RISK** — something that looks dangerous. Say what could go wrong.
+
+Never present an inference as a fact. When documentation and code disagree,
+record both under "Documented behaviour" and "Observed behaviour", with the
+evidence for each, and let the human decide which is the bug.
+
+## When in doubt
+
+Stop and ask. An agent that pauses costs a message; an agent that guesses on a
+payment path costs an incident.
+
+Doubt on reversibility or domain is a blocker; other doubt is written to
+`task.md` and the work continues.

package/skills/project-update/history/blobs/fa0cb370b024e1a30e1355912032657b08f609e47773a603c193b1e609b0f997

@@ -0,0 +1,8 @@
+# claude-agentic (.ai)
+.ai/state/*.json
+.ai/state/handoff.md
+.ai/state/*.tmp
+.ai/state/*.jsonl
+.ai/local/
+.ai/memory/
+.ai/reports/

package/skills/project-update/history/index.json

@@ -171,7 +171,8 @@
   "ae9a22907ba9acbb7e80fac1ba4e3d1ff09e5f1df5c4456afb9099d7090fcaa6",
   "fae3064e648cdc55be4aeb1177525b302a5e34ebd752e4a904f47dc0f4557b96",
   "e9adb7a9905eb719ac78ab96671f055da53e5001810f5ad6d6c94306b0323fe7",
-  "ae5ce131d6bae401199ff32d8c3dc4d8aec188010a9111624ac64506e2116ff4"
+  "ae5ce131d6bae401199ff32d8c3dc4d8aec188010a9111624ac64506e2116ff4",
+  "8ec171f0fbdf38cc6996d496f01491fd1f21f04a435a118ad979b127a8be06f1"
  ],
  "ai-init/.ai/policies/security.md": [
   "cc808d5b940109f1703abfb3ca0334a3fcfd34267feefb2323627d0decc8b89a",
@@ -394,7 +395,8 @@
  "ai-init/gitignore.snippet": [
   "5c0619c1ee059477c9d92cf70b72da5d238d9176fc27ab0d38104ecba795624c",
   "a00db51859bb7943174017a34b4a100f98e53d6c3b32f73d8f87d6072016a709",
-  "5a93f78b4ed4d416c171139b2ce610a117f9c1dd46fbb56ca86729cb4c53d10c"
+  "5a93f78b4ed4d416c171139b2ce610a117f9c1dd46fbb56ca86729cb4c53d10c",
+  "fa0cb370b024e1a30e1355912032657b08f609e47773a603c193b1e609b0f997"
  ],
  "ai-init/junie-guidelines.block.md": [
   "e8df28f07cb784d768bcafbced70fd15771afa61dbec7dc4c1c3f858f9002fec",

package/skills/project-update/rr_update/__init__.py

@@ -0,0 +1 @@
+"""rr_update: the pieces of skills/project-update/update.py, one module per concern, lower layers first."""

package/skills/project-update/rr_update/apply.py

@@ -0,0 +1,188 @@
+"""Writing the plan: the preconditions, the atomic write, the record of what was taken away, and the abort.
+
+shell: current_sha, check, default_mode, write_file, keep_original, record_run, apply, apply_item, prune_empty
+core: Abort
+"""
+
+import json
+import os
+import tempfile
+from collections import OrderedDict
+
+from rr_update import files
+from rr_update import paths
+
+
+class Abort(Exception):
+    """A precondition failed: the project is not what the dry run described."""
+
+    def __init__(self, item, why):
+        super().__init__(why)
+        self.item, self.why = item, why
+
+
+def current_sha(root, target):
+    """The sha of a target now, or None when it is absent. A path that is not a
+    regular file has no content this tool may replace."""
+    path = os.path.join(root, target)
+    if os.path.islink(path) or (os.path.exists(path) and not os.path.isfile(path)):
+        raise Abort(None, "%s is not a regular file" % target)
+    return files.sha(files.read(path)) if os.path.isfile(path) else None
+
+
+def check(plan, item, target, expect, written):
+    """The target must still be what the dry run read, or what this run wrote."""
+    try:
+        now_sha = current_sha(plan.root, target)
+    except Abort as exc:
+        raise Abort(item, exc.why) from exc
+    want = written.get(target, expect)
+    if now_sha != want:
+        raise Abort(item, "%s changed since the dry run read it" % target)
+
+
+def default_mode():
+    mask = os.umask(0)
+    os.umask(mask)
+    return 0o666 & ~mask
+
+
+def write_file(root, target, content, mode=None):
+    """Atomic, like state.py: a crash leaves the old file or the new one, never
+    half of one. The temp file is created with mkstemp in the target's directory,
+    so a planted name cannot redirect the write, and a symlinked target is
+    refused rather than followed. The target keeps the mode it had. A symlinked
+    *directory* on the way to it is still followed, as every writer here always
+    has."""
+    path = os.path.join(root, target)
+    if os.path.islink(path) or (os.path.exists(path) and not os.path.isfile(path)):
+        raise Abort(None, "%s is not a regular file" % target)
+    parent = os.path.dirname(path) or "."
+    os.makedirs(parent, exist_ok=True)
+    if mode is None:
+        mode = os.stat(path).st_mode & 0o7777 if os.path.isfile(path) else default_mode()
+    fd, tmp = tempfile.mkstemp(dir=parent, prefix=os.path.basename(path) + ".", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "wb") as fh:
+            fh.write(content)
+        os.chmod(tmp, mode)
+        os.replace(tmp, path)
+    except BaseException:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+        raise
+
+
+def keep_original(plan, target):
+    """A faithful copy of what a move or a delete takes away, mode included.
+    Nothing else is ever lost, so nothing else is copied."""
+    path = os.path.join(plan.root, target)
+    write_file(plan.root, os.path.join(plan.report_dir, "original", target),
+               files.read(path), mode=os.stat(path).st_mode & 0o7777)
+
+
+
+def record_run(plan, ops, deletions):
+    """The record of what was taken away or overwritten, rewritten after every such operation:
+    an abort must not lose the note of a change a human approved. A second run on the same
+    day appends to the record instead of replacing it."""
+    path = os.path.join(plan.report_dir, "migration.json")
+    existing = {}
+    full = os.path.join(plan.root, path)
+    if os.path.isfile(full):
+        try:
+            existing = json.loads(files.read(full), object_pairs_hook=OrderedDict)
+        except (ValueError, RecursionError):  # too deep reads as malformed
+            existing = {}
+        if not isinstance(existing, dict):  # hand-edited into another shape
+            existing = {}
+    record = OrderedDict()
+    record["from"] = existing.get("from", plan.version_from)
+    # The version the project is actually at now, read from the disk: this record is
+    # written before the files change, and an aborted run never reaches the template's.
+    version_path = os.path.join(plan.root, paths.VERSION_FILE)
+    on_disk = files.read(version_path).decode().strip() if os.path.isfile(version_path) else ""
+    record["to"] = int(on_disk) if on_disk.isdigit() else record["from"]
+    record["applied_at"] = files.utc_now()
+    # A recovery re-run replays the same operation: record it once.
+    record["ops"] = list(existing.get("ops", []))
+    record["ops"] += [o for o in ops if o not in record["ops"]]
+    record["deletions"] = list(existing.get("deletions", []))
+    record["deletions"] += [d for d in deletions
+                            if not any(e.get("path") == d["path"] for e in record["deletions"])]
+    if existing and all(existing.get(k) == record[k] for k in ("from", "to", "ops", "deletions")):
+        return  # a run that changed nothing leaves the record as it was
+    write_file(plan.root, path, files.dump_json(record))
+
+
+def apply(plan):
+    """Write the plan, in order. Every item checks its target first; a violation
+    or a failed write aborts before the next item, leaving everything after it
+    unwritten. Every operation is idempotent, so the re-run is the recovery."""
+    written, recorded = {}, []
+    for item in plan.items:
+        try:
+            apply_item(plan, item, written, recorded)
+        except Abort as exc:
+            raise Abort(exc.item or item, exc.why) from exc
+        except OSError as exc:
+            raise Abort(item, str(exc)) from exc
+    # The run finished: say which version it actually reached.
+    try:
+        if recorded or os.path.isfile(os.path.join(plan.root, plan.report_dir, "migration.json")):
+            record_run(plan, [], [])
+    except OSError as exc:
+        raise Abort(None, str(exc)) from exc
+
+
+def apply_item(plan, item, written, recorded):
+    target, action = item["target"], item["action"]
+    reason = item.get("reason") or ""
+    cleanup = reason.startswith("[cleanup]")
+    if action in ("delete?", "regenerate?"):  # listed only, until a human confirms it
+        return
+    by = dict(confirmed_by=plan.confirm_cleanup if cleanup else plan.confirm_delete,
+              via=plan.cleanup_via if cleanup else plan.confirm_via, at=files.utc_now())
+    if action == "delete":
+        # the plan-time symlink check is repeated: a path swapped since is refused
+        why = files.unsafe_path(plan.root, target)
+        if why:
+            raise Abort(item, why)
+        check(plan, item, target, item["expect"], written)
+        # git-ignored task state: a [cleanup] deletion of it is NOT recoverable through git, and
+        # copying what it removes would defeat the cleanup, so no original/ copy is kept. A report
+        # file git tracks, or should, is kept like any other deletion.
+        if not target.startswith(".ai/state/") and (not cleanup or target in plan.git_kept):
+            keep_original(plan, target)
+        recorded.append(target)
+        # Recorded before the file is gone: an abort later must not lose the note
+        # of what was taken away, or of who approved it.
+        record_run(plan, [dict(action=action, path=target)], [dict(path=target, **by)])
+        os.remove(os.path.join(plan.root, target))
+        written[target] = None
+        if reason.startswith(("[cleanup]", "[local]")):
+            prune_empty(plan.root, target)
+        return
+    check(plan, item, target, item["expect"], written)
+    if item["keep"] and item["expect"] is not None and target not in written:
+        # A change a human confirmed overwrites what they wrote: keep it, so it can be read back.
+        if not os.path.exists(os.path.join(plan.root, plan.original_of(target))):
+            keep_original(plan, target)
+        recorded.append(target)
+        record_run(plan, [dict(action=action, path=target, **by)], [])
+    write_file(plan.root, target, item["content"])
+    written[target] = files.sha(item["content"])
+
+
+def prune_empty(root, target):
+    """The directories a cleanup or cache deletion left empty, up to (not including)
+    .ai/reports, .ai/state/logs and .ai/local; a directory with anything in it stays."""
+    top = ".ai/state/logs" if target.startswith(".ai/state/logs/") else \
+        ".ai/local" if target.startswith(paths.LOCAL_CACHE + "/") else ".ai/reports"
+    here = os.path.dirname(target)
+    while here.startswith(top + "/"):
+        try:
+            os.rmdir(os.path.join(root, here))
+        except OSError:
+            return
+        here = os.path.dirname(here)