workspace: version the root CLAUDE.md + InstructionsLoaded hook, and report which rules fire (R-229)
gates / gates (push) Successful in 8s
gates / gates (push) Successful in 8s
install_workspace.py lays down the two things that shaped every session while existing on one host only. Unlike install_skills.py the targets are LIVE CONFIG, so: timestamped backup before every write, settings.json MERGED (this script owns exactly one key), a diverged CLAUDE.md reported rather than silently resolved, and an unparseable settings.json refused outright. Proven: all 7 top-level settings keys survived byte-identically, and run 2 wrote nothing. rules_report.py surfaces the column that matters -- rules that have NEVER fired, which are mis-globbed or dead. 6 of 9 on first run. The hook now self-rotates at 5 MB. The memory store is BACKED UP, NOT COMMITTED (auto-written, may name hosts/paths): added to dooplex-backup.service's User Data component. /opt/backup/scripts/ is itself unversioned host state -- filed, not fixed here.
This commit is contained in:
@@ -0,0 +1,193 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
"""Lay down the workspace files that live outside every repo, from their versioned copies.
|
||||
|
||||
Usage: python3 scripts/install_workspace.py [--dry-run] [--workspace DIR] [--settings FILE]
|
||||
|
||||
WHAT THIS EXISTS FOR. Claude Code runs from /mnt/5_hdd/felhom.eu/git, which is not a git repository.
|
||||
The workspace-root CLAUDE.md and the InstructionsLoaded hook shape every session and existed on ONE
|
||||
machine — the one host that cannot be rebuilt from anything else. This restores them.
|
||||
|
||||
WHAT IT DOES NOT TOUCH. The auto-memory store. That is backed up, not versioned — see
|
||||
workspace/README.md for why, and /opt/backup/scripts/backup-config.sh for where.
|
||||
|
||||
THE ONE WAY THIS DIFFERS FROM install_skills.py, AND IT IS THE IMPORTANT ONE. That script's targets
|
||||
are disposable: a skill directory can be deleted and re-linked with nothing lost. These targets are
|
||||
LIVE CONFIGURATION. ~/.claude/settings.json holds permissions, plugins and effort level that this
|
||||
repo knows nothing about, and the workspace CLAUDE.md may have been edited on the machine since the
|
||||
last sync. So:
|
||||
|
||||
- every write is preceded by a TIMESTAMPED BACKUP of the file being replaced;
|
||||
- settings.json is MERGED, never rewritten from a template — this script owns exactly one key,
|
||||
hooks.InstructionsLoaded, and every other key is carried through untouched;
|
||||
- a diverging CLAUDE.md is reported, not silently resolved in either direction.
|
||||
|
||||
IDEMPOTENT. A second run writes nothing and says so. That is asserted by the caller in the session
|
||||
report, because "it ran twice without error" and "it changed nothing the second time" are different
|
||||
claims and only the second one means idempotent.
|
||||
"""
|
||||
import argparse
|
||||
import datetime
|
||||
import json
|
||||
import os
|
||||
import shutil
|
||||
import sys
|
||||
|
||||
REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
||||
# Canonical source of the workspace instructions. Deliberately NOT workspace/ — see workspace/README.md.
|
||||
CLAUDE_SRC = os.path.join(REPO, "documentation", "runbooks", "workspace-CLAUDE.md")
|
||||
HOOK_SRC = os.path.join(REPO, "workspace", "hooks", "instructions-loaded.json")
|
||||
|
||||
changed = []
|
||||
unchanged = []
|
||||
problems = []
|
||||
|
||||
|
||||
def stamp():
|
||||
return datetime.datetime.now().strftime("%Y%m%d-%H%M%S")
|
||||
|
||||
|
||||
def backup(path):
|
||||
dst = "%s.bak-%s" % (path, stamp())
|
||||
shutil.copy2(path, dst)
|
||||
return dst
|
||||
|
||||
|
||||
def read(path):
|
||||
with open(path, "r", encoding="utf-8") as fh:
|
||||
return fh.read()
|
||||
|
||||
|
||||
def install_claude_md(workspace, dry_run):
|
||||
target = os.path.join(workspace, "CLAUDE.md")
|
||||
if not os.path.exists(CLAUDE_SRC):
|
||||
problems.append("versioned source missing: %s" % CLAUDE_SRC)
|
||||
return
|
||||
src_text = read(CLAUDE_SRC)
|
||||
|
||||
if os.path.exists(target):
|
||||
if read(target) == src_text:
|
||||
unchanged.append("CLAUDE.md (already byte-identical to the versioned copy)")
|
||||
return
|
||||
# Diverged. Back up FIRST, install, and report the direction so a human can judge which
|
||||
# side was right — this script must not silently pick one.
|
||||
if dry_run:
|
||||
changed.append("CLAUDE.md WOULD back up and overwrite (live file differs from source)")
|
||||
return
|
||||
b = backup(target)
|
||||
with open(target, "w", encoding="utf-8") as fh:
|
||||
fh.write(src_text)
|
||||
changed.append(
|
||||
"CLAUDE.md DIVERGED -> backed up to %s, installed from %s.\n"
|
||||
" If the LIVE file was the newer one, restore it and re-sync the versioned "
|
||||
"copy instead; instructions_gate check 5 enforces they match." % (os.path.basename(b), CLAUDE_SRC)
|
||||
)
|
||||
return
|
||||
|
||||
if dry_run:
|
||||
changed.append("CLAUDE.md WOULD create (absent)")
|
||||
return
|
||||
with open(target, "w", encoding="utf-8") as fh:
|
||||
fh.write(src_text)
|
||||
changed.append("CLAUDE.md created from %s" % CLAUDE_SRC)
|
||||
|
||||
|
||||
def install_hook(settings_path, dry_run):
|
||||
if not os.path.exists(HOOK_SRC):
|
||||
problems.append("versioned source missing: %s" % HOOK_SRC)
|
||||
return
|
||||
fragment = json.loads(read(HOOK_SRC))
|
||||
want = fragment.get("hooks", {}).get("InstructionsLoaded")
|
||||
if not want:
|
||||
problems.append("%s declares no hooks.InstructionsLoaded" % HOOK_SRC)
|
||||
return
|
||||
|
||||
if os.path.exists(settings_path):
|
||||
try:
|
||||
settings = json.loads(read(settings_path))
|
||||
except ValueError as e:
|
||||
# A broken settings.json silently disables EVERY setting in it. Never overwrite one we
|
||||
# could not parse — that would destroy whatever the user was mid-way through fixing.
|
||||
problems.append(
|
||||
"%s is not valid JSON (%s). Refusing to write: a malformed settings file disables "
|
||||
"every setting in it, and overwriting would destroy the original." % (settings_path, e)
|
||||
)
|
||||
return
|
||||
else:
|
||||
settings = {}
|
||||
|
||||
have = settings.get("hooks", {}).get("InstructionsLoaded")
|
||||
if have == want:
|
||||
unchanged.append("settings.json (hooks.InstructionsLoaded already current)")
|
||||
return
|
||||
|
||||
if dry_run:
|
||||
changed.append("settings.json WOULD merge hooks.InstructionsLoaded (%s)"
|
||||
% ("replacing an existing one" if have else "adding"))
|
||||
return
|
||||
|
||||
before_keys = sorted(settings.keys())
|
||||
if os.path.exists(settings_path):
|
||||
b = backup(settings_path)
|
||||
else:
|
||||
b = None
|
||||
os.makedirs(os.path.dirname(settings_path), exist_ok=True)
|
||||
|
||||
settings.setdefault("hooks", {})["InstructionsLoaded"] = want
|
||||
with open(settings_path, "w", encoding="utf-8") as fh:
|
||||
json.dump(settings, fh, indent=2, ensure_ascii=False)
|
||||
fh.write("\n")
|
||||
|
||||
after_keys = sorted(json.loads(read(settings_path)).keys())
|
||||
lost = set(before_keys) - set(after_keys)
|
||||
if lost:
|
||||
problems.append("MERGE LOST KEYS from settings.json: %s" % ", ".join(sorted(lost)))
|
||||
changed.append(
|
||||
"settings.json %s hooks.InstructionsLoaded%s; %d top-level key(s) carried through unchanged"
|
||||
% ("replaced" if have else "added",
|
||||
(" (backup %s)" % os.path.basename(b)) if b else "",
|
||||
len(before_keys))
|
||||
)
|
||||
|
||||
|
||||
def main(argv):
|
||||
ap = argparse.ArgumentParser()
|
||||
ap.add_argument("--dry-run", action="store_true",
|
||||
help="report what would change; write nothing")
|
||||
ap.add_argument("--workspace", default=os.path.dirname(REPO),
|
||||
help="workspace root (default: the parent of this repo)")
|
||||
ap.add_argument("--settings",
|
||||
default=os.path.join(os.path.expanduser("~"), ".claude", "settings.json"))
|
||||
args = ap.parse_args(argv[1:])
|
||||
|
||||
print("install_workspace%s" % (" [--dry-run]" if args.dry_run else ""))
|
||||
print(" workspace : %s" % args.workspace)
|
||||
print(" settings : %s" % args.settings)
|
||||
print("")
|
||||
|
||||
if not os.path.isdir(args.workspace):
|
||||
print("FAIL: workspace root does not exist: %s" % args.workspace)
|
||||
return 2
|
||||
|
||||
install_claude_md(args.workspace, args.dry_run)
|
||||
install_hook(args.settings, args.dry_run)
|
||||
|
||||
for c in changed:
|
||||
print("CHANGED %s" % c)
|
||||
for u in unchanged:
|
||||
print("unchanged %s" % u)
|
||||
for p in problems:
|
||||
print("PROBLEM %s" % p)
|
||||
|
||||
print("")
|
||||
if problems:
|
||||
print("install_workspace: %d PROBLEM(S)" % len(problems))
|
||||
return 1
|
||||
if not changed:
|
||||
print("install_workspace: nothing to do — already installed (idempotent)")
|
||||
else:
|
||||
print("install_workspace: %d change(s)" % len(changed))
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main(sys.argv))
|
||||
Reference in New Issue
Block a user