devflow-kit 3.7.0 → 3.9.0

package/src/assets/scripts/hooks/json-helper.cjs

@@ -2,10 +2,10 @@
 
 // src/assets/scripts/hooks/json-helper.cjs
 // Provides jq-equivalent operations for hooks when jq is not installed, and the
-// learning ops the Curate agent runs from the project root.
+// curation ops the Curate agent runs from the project root.
 // SECURITY: This is a local CLI helper invoked only by shell hooks and the
 // Curate agent with controlled arguments. No operation takes a file path: a
-// file's content arrives on stdin (json-parse redirects it), and the learning ops
+// file's content arrives on stdin (json-parse redirects it), and the curation ops
 // build every path from the current directory.
 // Usage: node json-helper.cjs <operation> [args...]
 //
@@ -37,13 +37,24 @@
 //   show <anchor|obs_id>                  Read-only: print one entry as pretty JSON
 //   claim-due                             Hand out the entries due for maintenance, leased
 //                                          for a day, after the ref their claims are checked at
-//   claim-queue                           Claim the learning queue for this run; prints
+//   claim-queue                           Claim the curation queue for this run; prints
 //                                          claimed <token>[ takeover] | busy | none
 //   release-claim <token>                 Release the claim the token owns; prints
 //                                          released | not-owner | gone
+//   move-ledger <root>                    Move a project's old ledger folder to the new name,
+//                                          once; prints none | busy | busy claim |
+//                                          skipped tracked | skipped unknown | moved <mode>
+//                                          and its backup, cause and notes
+//   tracked-area <curation|memory|both> <root>
+//                                          Does git track files in the data folders of the area
+//                                          at the root? Prints tracked | untracked | unknown, and
+//                                          for unknown a second line `cause <word>`
 //
-// Every learning op above except claim-queue and release-claim first refreshes
-// the mtime of an existing queue claim — the heartbeat (D-OWNED-CLAIM).
+// Every curation op above except claim-queue, release-claim, move-ledger and tracked-area
+// first refreshes the mtime of an existing queue claim — the heartbeat (D-OWNED-CLAIM).
+// Where git tracks files in the curation data folders, or does not say whether it does,
+// every curation op refuses with kind `tracked`, exit 1 and an empty stdout, and changes
+// nothing; the answer is asked once per process.
 
 'use strict';
 
@@ -53,21 +64,50 @@ const { constants: { MAX_STRING_LENGTH } } = require('buffer');
 const op = process.argv[2];
 const args = process.argv.slice(3);
 
-/** The learning modules, once loaded; see learning(). */
-let learningModules = null;
+/** The curation modules, once loaded; see curation(). */
+let curationModules = null;
 
 /**
- * The learning store, loaded on first use and memoized. The generic ops never
+ * The curation store, loaded on first use and memoized. The generic ops never
  * call it, so a hook that falls back from jq to node never pays for loading it,
  * and the store loads the renderer only when an op renders.
  *
  * @returns {{ store: object }}
  */
-function learning() {
-  if (learningModules === null) {
-    learningModules = { store: require('./lib/learning-store.cjs') };
+function curation() {
+  if (curationModules === null) {
+    curationModules = { store: require('./lib/curation-store.cjs') };
   }
-  return learningModules;
+  return curationModules;
+}
+
+/** The ledger move module, once loaded; see curationMove(). */
+let curationMoveModule = null;
+
+/**
+ * The ledger move module, loaded on first use and memoized. Only the move op calls
+ * it, so no other curation op loads the move code.
+ *
+ * @returns {object}
+ */
+function curationMove() {
+  if (curationMoveModule === null) curationMoveModule = require('./lib/curation-move.cjs');
+  return curationMoveModule;
+}
+
+/** The tracked-areas check, once loaded; see trackedAreas(). */
+let trackedAreasModule = null;
+
+/**
+ * The tracked-areas check, loaded on first use and memoized. Only the tracked-area op
+ * loads it from here: a leaf that requires node built-ins and the path helpers, never
+ * the store.
+ *
+ * @returns {object}
+ */
+function trackedAreas() {
+  if (trackedAreasModule === null) trackedAreasModule = require('./lib/tracked-areas.cjs');
+  return trackedAreasModule;
 }
 
 /** The bytes each read of stdin asks for. */
@@ -84,7 +124,7 @@ const STDIN_WAIT_CELL = new Int32Array(new SharedArrayBuffer(4));
 
 /**
  * Read stdin to its end, keeping at most `maxBytes`. Every op that reads stdin
- * reads it here, so the generic ops and the learning ops cannot read it two ways.
+ * reads it here, so the generic ops and the curation ops cannot read it two ways.
  * Never throws: a failure is a refusal.
  *
  * D-STDIN-FD0: stdin is read from file descriptor 0 itself, in reads repeated
@@ -168,14 +208,16 @@ function parseArgs(argList) {
 }
 
 // ---------------------------------------------------------------------------
-// Learning-op adapter
+// Curation-op adapter
 // ---------------------------------------------------------------------------
 
 /**
- * Print a learning op's Result: `format(value)` and a newline on stdout, or the
+ * Print a curation op's Result: `format(value)` and a newline on stdout, or the
  * error message and a newline on stderr. Returns the exit code for the op to set
  * as process.exitCode, so the process exits once, after the op has returned and
- * every lock it took is released.
+ * every lock it took is released. The error message keeps its line structure (a
+ * refusal lists one problem per line), and each line has no control character, as it
+ * may name a file the repository holds. At most REFUSAL_MAX_LINES lines print.
  *
  * @param {{ ok: true, value: unknown } | { ok: false, error: { message: string } }} result
  * @param {(value: any) => string} format - the stdout text for the value
@@ -186,10 +228,43 @@ function emit(result, format) {
     process.stdout.write(`${format(result.value)}\n`);
     return 0;
   }
-  process.stderr.write(`${result.error.message}\n`);
+  process.stderr.write(`${refusalText(result.error.message)}\n`);
   return 1;
 }
 
+/** The most lines of one refusal message that print. */
+const REFUSAL_MAX_LINES = 200;
+
+/**
+ * A refusal message with each line scrubbed (singleLine) and the line structure kept.
+ * Past REFUSAL_MAX_LINES lines, the rest become one `... N more lines` line.
+ *
+ * @param {string} message
+ * @returns {string}
+ */
+function refusalText(message) {
+  const { singleLine } = curation().store;
+  const lines = String(message).split('\n');
+  if (lines.length <= REFUSAL_MAX_LINES) return lines.map(line => singleLine(line)).join('\n');
+  const shown = lines.slice(0, REFUSAL_MAX_LINES).map(line => singleLine(line));
+  return [...shown, `... ${lines.length - REFUSAL_MAX_LINES} more lines`].join('\n');
+}
+
+/**
+ * The first line of move-ledger's answer: the state, with `moved` followed by its mode,
+ * `busy` followed by `claim` when a fresh queue claim holds the move, and `skipped`
+ * followed by its reason (`tracked` or `unknown`).
+ *
+ * @param {{ state: string, mode?: string, reason?: string }} moved
+ * @returns {string}
+ */
+function moveAnswerWord(moved) {
+  if (moved.state === 'moved') return `moved ${moved.mode}`;
+  if (moved.state === 'busy' && moved.reason === 'claim') return 'busy claim';
+  if (moved.state === 'skipped') return `skipped ${moved.reason}`;
+  return moved.state;
+}
+
 /**
  * Refuse a malformed command line: print `<op>: usage: <usage>` on stderr and exit 1,
  * before the op takes any lock.
@@ -202,11 +277,11 @@ function exitWithUsage(usage) {
   process.exit(1);
 }
 
-/** The most stdin a learning op reads: far above any valid input, so a runaway writer is refused, not parsed. */
+/** The most stdin a curation op reads: far above any valid input, so a runaway writer is refused, not parsed. */
 const STDIN_JSON_MAX_BYTES = 64 * 1024;
 
 /**
- * A learning op's stdin as one JSON object: the one way text reaches a learning
+ * A curation op's stdin as one JSON object: the one way text reaches a curation
  * op, so no field of it ever passes through argv or a shell word. Never throws.
  *
  * @param {string} opName - for the message
@@ -235,30 +310,30 @@ const PUT_MODES = new Map([['--create', 'create'], ['--update', 'update'], ['--r
 const ENTRY_TYPES = new Set(['decision', 'pitfall']);
 
 /**
- * The learning ops whose run sends the claim heartbeat first (D-OWNED-CLAIM).
+ * The curation ops whose run sends the claim heartbeat first (D-OWNED-CLAIM).
  * claim-queue and release-claim manage the claim themselves, and the generic ops
- * never touch it. A new learning op joins this set.
+ * never touch it. A new curation op joins this set.
  */
-const LEARNING_OPS = new Set([
+const CURATION_OPS = new Set([
   'assign-anchor', 'retire-anchor', 'restore-anchor', 'refresh-anchor', 'rotate-observations',
   'put-observation', 'list', 'show', 'claim-due',
 ]);
 
 /** Send the claim heartbeat; a failure is reported on stderr and never stops the op. */
 function heartbeat(root) {
-  const beat = learning().store.touchClaim(root);
+  const beat = curation().store.touchClaim(root);
   if (!beat.ok) process.stderr.write(`${beat.error.message}\n`);
 }
 
-// The learning ops run from the project root and take no path to a learning file:
+// The curation ops run from the project root and take no path to a curation file:
 // each builds its paths from the current directory. Every op that writes takes the
-// store's one learning lock through withDecisionsLock (D-ONE-LEARNING-LOCK) and
-// refuses, creating nothing, when .devflow/learning/ is absent (D-NO-STRAY-TREE)
+// store's one curation lock through withDecisionsLock (D-ONE-LEARNING-LOCK) and
+// refuses, creating nothing, when .devflow/curation/ is absent (D-NO-STRAY-TREE)
 // or when it, or .devflow, is a symbolic link (D-NO-LINKED-TREE).
 // A locked body returns its Result; emit prints it once the lock is released.
 if (require.main === module) {
 try {
-  if (LEARNING_OPS.has(op)) heartbeat(process.cwd());
+  if (CURATION_OPS.has(op)) heartbeat(process.cwd());
   switch (op) {
     case 'get-field': {
       const input = JSON.parse(readStdin());
@@ -338,7 +413,6 @@ try {
       console.log(JSON.stringify({
         timestamp: data.ts || '',
         trigger: 'pre-compact',
-        memory_snapshot: data.memory || '',
         git: {
           branch: data.branch || '',
           status: data.status || '',
@@ -353,12 +427,12 @@ try {
     // assign-anchor <decision|pitfall> <obs_id>
     // Promote a v2 observation no ledger row carries to the next entry of its
     // type, skipping each number a tracked file cites (assignAnchor,
-    // learning-store.cjs: D-LEDGER-REGISTRY, D-E4-SKIP). It never writes the log.
+    // curation-store.cjs: D-LEDGER-REGISTRY, D-E4-SKIP). It never writes the log.
     // stdout: the anchor; stderr: `assign-anchor: skipped <anchor>, cited in
     // <path>:<line>` for each number skipped
     // -------------------------------------------------------------------------
     case 'assign-anchor': {
-      const { store } = learning();
+      const { store } = curation();
       if (args.length !== 2 || !ENTRY_TYPES.has(args[0]) || !store.OBS_ID_RE.test(args[1])) {
         exitWithUsage('assign-anchor <decision|pitfall> <obs_id> (run from the project root)');
       }
@@ -377,12 +451,12 @@ try {
     // Make an active entry inactive with the one JSON object on stdin its status
     // takes: { reason } for Retired and Deprecated, { by } for Superseded, and
     // { at, quote } for Encoded, the quote checked at the verify ref
-    // (retireAnchor, learning-store.cjs: D-ENCODED-QUOTE).
+    // (retireAnchor, curation-store.cjs: D-ENCODED-QUOTE).
     // stdout: the new status in lower case and the anchor, then `repointed
     // <anchor>` for each entry re-pointed to the successor
     // -------------------------------------------------------------------------
     case 'retire-anchor': {
-      const { store } = learning();
+      const { store } = curation();
       if (args.length !== 2 || !store.ANCHOR_ID_RE.test(args[0]) || !store.INACTIVE_STATUSES.includes(args[1])) {
         exitWithUsage('retire-anchor <anchor> <Encoded|Superseded|Retired|Deprecated> (one JSON object on stdin; run from the project root)');
       }
@@ -400,11 +474,11 @@ try {
     // Make an inactive entry active again, its notes, last_verified and
     // last_attempt cleared so it is due for maintenance again, ordered after
     // integrity problems and legacy entries, or among them when it is one
-    // (restoreAnchor, learning-store.cjs: D-DUE-ORDER).
+    // (restoreAnchor, curation-store.cjs: D-DUE-ORDER).
     // stdout: restored <anchor>
     // -------------------------------------------------------------------------
     case 'restore-anchor': {
-      const { store } = learning();
+      const { store } = curation();
       if (args.length !== 1 || !store.ANCHOR_ID_RE.test(args[0])) {
         exitWithUsage('restore-anchor <anchor> (run from the project root)');
       }
@@ -415,12 +489,12 @@ try {
     // -------------------------------------------------------------------------
     // refresh-anchor <anchor> [<anchor>...] [--verified]
     // Re-project active v2 entries from their log rows, or under --verified stamp
-    // them verified today; all or nothing (refreshAnchors, learning-store.cjs).
+    // them verified today; all or nothing (refreshAnchors, curation-store.cjs).
     // stdout: `reprojected <anchor>` or `unchanged <anchor>` per anchor, or
     // `verified <anchor>` under --verified, in the order given
     // -------------------------------------------------------------------------
     case 'refresh-anchor': {
-      const { store } = learning();
+      const { store } = curation();
       const verifiedFlags = args.filter(arg => arg === '--verified').length;
       const anchors = args.filter(arg => arg !== '--verified');
       if (verifiedFlags > 1 || anchors.length === 0 || !anchors.every(arg => store.ANCHOR_ID_RE.test(arg))) {
@@ -435,13 +509,13 @@ try {
     // rotate-observations
     // Archive the log rows no ledger row carries once 30 days have passed since
     // their last activity, and delete the usage telemetry's leftovers
-    // (D-ROTATE-UNREFERENCED, learning-store.cjs). Takes no argument: the log and
+    // (D-ROTATE-UNREFERENCED, curation-store.cjs). Takes no argument: the log and
     // the archive are the project root's.
     // stdout: rotated <N> observations
     // -------------------------------------------------------------------------
     case 'rotate-observations': {
       if (args.length > 0) exitWithUsage('rotate-observations (no arguments; run from the project root)');
-      const result = learning().store.rotateObservations(process.cwd());
+      const result = curation().store.rotateObservations(process.cwd());
       process.exitCode = emit(result, ({ rotated }) => `rotated ${rotated} observations`);
       break;
     }
@@ -449,7 +523,7 @@ try {
     // -------------------------------------------------------------------------
     // put-observation --create|--update|--reinforce
     // Store one observation from the JSON object on stdin (D-PUT-NOT-MERGE,
-    // D-PUT-REPROJECTS, learning-store.cjs). Exactly one mode flag; no other argv.
+    // D-PUT-REPROJECTS, curation-store.cjs). Exactly one mode flag; no other argv.
     // stdout: created <id> | updated <id> | unchanged <id> | reinforced <id> <n>,
     // then one `reprojected <anchor>` line per entry re-projected
     // -------------------------------------------------------------------------
@@ -459,7 +533,7 @@ try {
         exitWithUsage('put-observation --create|--update|--reinforce (one JSON object on stdin; run from the project root)');
       }
       const input = readStdinJson('put-observation');
-      const result = input.ok ? learning().store.putObservation(process.cwd(), mode, input.value) : input;
+      const result = input.ok ? curation().store.putObservation(process.cwd(), mode, input.value) : input;
       process.exitCode = emit(result, put => [
         put.outcome === 'reinforced' ? `reinforced ${put.id} ${put.observations}` : `${put.outcome} ${put.id}`,
         ...put.reprojected.map(anchorId => `reprojected ${anchorId}`),
@@ -470,25 +544,25 @@ try {
     // -------------------------------------------------------------------------
     // list
     // Print the ledger and the log by section, read-only (readListing and
-    // formatListing, learning-store.cjs). Takes no argument.
+    // formatListing, curation-store.cjs). Takes no argument.
     // stdout: the ACTIVE, INACTIVE, OBSERVATIONS and INTEGRITY sections, then
     // MALFORMED when lines were skipped
     // -------------------------------------------------------------------------
     case 'list': {
       if (args.length > 0) exitWithUsage('list (no arguments; run from the project root)');
-      const { store } = learning();
+      const { store } = curation();
       process.exitCode = emit(store.readListing(process.cwd()), store.formatListing);
       break;
     }
 
     // -------------------------------------------------------------------------
     // show <anchor|obs_id>
-    // Print one entry, read-only (showByKey, learning-store.cjs).
+    // Print one entry, read-only (showByKey, curation-store.cjs).
     // stdout: pretty JSON { key, ledger, log, history_versions, flags }, plus
     // malformed when lines were skipped
     // -------------------------------------------------------------------------
     case 'show': {
-      const { store } = learning();
+      const { store } = curation();
       if (args.length !== 1 || !(store.ANCHOR_ID_RE.test(args[0]) || store.OBS_ID_RE.test(args[0]))) {
         exitWithUsage('show <anchor|obs_id> (run from the project root)');
       }
@@ -499,13 +573,13 @@ try {
     // -------------------------------------------------------------------------
     // claim-due
     // Hand out the entries due for maintenance and lease each for a day
-    // (claimDue, learning-store.cjs: D-DUE-ORDER, D-VERIFY-REF). Takes no argument.
+    // (claimDue, curation-store.cjs: D-DUE-ORDER, D-VERIFY-REF). Takes no argument.
     // stdout: ref <origin/HEAD|HEAD> <sha12>, or ref none; then one
     // `<anchor> <reason> <bytes>` line per entry handed out, or due none
     // -------------------------------------------------------------------------
     case 'claim-due': {
       if (args.length > 0) exitWithUsage('claim-due (no arguments; run from the project root)');
-      const { store } = learning();
+      const { store } = curation();
       process.exitCode = emit(store.claimDue(process.cwd()), ({ ref, due }) => [
         ref === null ? 'ref none' : `ref ${ref.ref} ${ref.commit.slice(0, 12)}`,
         ...(due.length > 0 ? due.map(entry => `${store.singleLine(entry.anchor_id)} ${entry.reason} ${entry.bytes}`) : ['due none']),
@@ -515,13 +589,13 @@ try {
 
     // -------------------------------------------------------------------------
     // claim-queue
-    // Claim the learning queue for this run (D-OWNED-CLAIM, learning-store.cjs).
+    // Claim the curation queue for this run (D-OWNED-CLAIM, curation-store.cjs).
     // Takes no argument; mints the token itself.
     // stdout: claimed <token> | claimed <token> takeover | busy | none
     // -------------------------------------------------------------------------
     case 'claim-queue': {
       if (args.length > 0) exitWithUsage('claim-queue (no arguments; run from the project root)');
-      const result = learning().store.claimQueue(process.cwd());
+      const result = curation().store.claimQueue(process.cwd());
       process.exitCode = emit(result, claim => (claim.state === 'claimed'
         ? `claimed ${claim.token}${claim.takeover ? ' takeover' : ''}`
         : claim.state));
@@ -530,11 +604,11 @@ try {
 
     // -------------------------------------------------------------------------
     // release-claim <token>
-    // Release the claim the token owns (D-OWNED-CLAIM, learning-store.cjs).
+    // Release the claim the token owns (D-OWNED-CLAIM, curation-store.cjs).
     // stdout: released | not-owner | gone
     // -------------------------------------------------------------------------
     case 'release-claim': {
-      const { store } = learning();
+      const { store } = curation();
       if (args.length !== 1 || !store.CLAIM_TOKEN_RE.test(args[0])) {
         exitWithUsage('release-claim <token> (the 16 hex characters claim-queue printed)');
       }
@@ -542,12 +616,63 @@ try {
       break;
     }
 
+    // -------------------------------------------------------------------------
+    // move-ledger <root>
+    // Move the project's old ledger folder to the new name, once (moveLedger,
+    // curation-move.cjs). Not a curation op: it sends no heartbeat, because a
+    // heartbeat would refresh a claim the move has to judge stale. Unlike the
+    // curation ops it takes the root as an argument, so a caller outside the project
+    // root can name it; the root stays one argv word, never a shell word. The two
+    // folder names are the path helpers' own: no argument names them.
+    // stdout: none | busy | busy claim | skipped tracked | skipped unknown | moved <mode>,
+    // then `backup <name>` when a backup was made, `cause <word>` for `skipped unknown`
+    // (one fixed word that says why git did not answer), and one `note <text>` line for
+    // each note. `busy claim` means a fresh queue claim holds the move, which can last 15
+    // minutes; plain `busy` means a lock does. `skipped tracked` means git tracks files in
+    // a curation data folder, `skipped unknown` that git did not answer: nothing changed.
+    // Every line is scrubbed here (singleLine):
+    // a note may name a file the repository holds, and no line may carry a control
+    // character or break into two.
+    // -------------------------------------------------------------------------
+    case 'move-ledger': {
+      if (args.length !== 1) exitWithUsage('move-ledger <root> (the root is an absolute path)');
+      const { store } = curation();
+      process.exitCode = emit(curationMove().moveLedger(args[0]), moved => [
+        moveAnswerWord(moved),
+        ...(moved.state === 'moved' && moved.backup !== null ? [`backup ${moved.backup}`] : []),
+        ...(moved.state === 'skipped' && moved.cause !== undefined ? [`cause ${moved.cause}`] : []),
+        ...moved.notes.map(note => `note ${note}`),
+      ].map(line => store.singleLine(line)).join('\n'));
+      break;
+    }
+
+    // -------------------------------------------------------------------------
+    // tracked-area <curation|memory|both> <root>
+    // Does git track files in the data folders of the area at the root
+    // (inspectTrackedAreaOnce, tracked-areas.cjs)? Not a curation op: it sends no
+    // heartbeat and loads only the check. The root is an argument, so the shell gate
+    // names the root it decided on; it stays one argv word, never a shell word. The
+    // answer is asked once per root and area for the life of the process.
+    // stdout: tracked | untracked | unknown, and for unknown a second line
+    // `cause <word>` (one fixed word that says why git did not answer)
+    // -------------------------------------------------------------------------
+    case 'tracked-area': {
+      const { AREA_PATHSPECS, inspectTrackedAreaOnce } = trackedAreas();
+      if (args.length !== 2 || !Object.prototype.hasOwnProperty.call(AREA_PATHSPECS, args[0])) {
+        exitWithUsage('tracked-area <curation|memory|both> <root> (the root is an absolute path)');
+      }
+      const { answer, cause } = inspectTrackedAreaOnce(args[1], args[0]);
+      process.stdout.write(answer === 'unknown' ? `unknown\ncause ${cause}\n` : `${answer}\n`);
+      break;
+    }
+
     default:
       process.stderr.write(`json-helper: unknown operation "${op}"\n`);
       process.exit(1);
   }
 } catch (err) {
-  process.stderr.write(`json-helper error: ${err && err.message ? err.message : String(err)}\n`);
+  const reason = err && err.message ? err.message : String(err);
+  process.stderr.write(`json-helper error: ${curationModules === null ? reason : curationModules.store.singleLine(reason)}\n`);
   process.exit(1);
 }
 } // end if (require.main === module)

package/src/assets/scripts/hooks/json-parse

@@ -170,7 +170,7 @@ json_prompt_output() {
 # Build pre-compact backup JSON. Usage: json_backup_construct --arg ts X --arg branch Y ...
 json_backup_construct() {
   if [ "$_HAS_JQ" = "true" ]; then
-    jq -n "$@" '{timestamp: $ts, trigger: "pre-compact", memory_snapshot: $memory, git: {branch: $branch, status: $status, log: $log, diff_stat: $diff}}'
+    jq -n "$@" '{timestamp: $ts, trigger: "pre-compact", git: {branch: $branch, status: $status, log: $log, diff_stat: $diff}}'
   else
     node "$_JSON_HELPER" backup-construct "$@"
   fi