devflow-kit 3.7.0 → 3.8.0

package/src/assets/scripts/hooks/lib/tracked-areas.cjs

@@ -0,0 +1,259 @@
+// src/assets/scripts/hooks/lib/tracked-areas.cjs
+//
+// Does git track any entry under one of devflow's data folders at a root? One
+// `git ls-files` call over a fixed set of pathspecs answers `tracked`, `untracked` or
+// `unknown`. The one-time ledger move and the backup sweep ask it before they lock, read
+// or rename anything: a folder that git tracks is the repository's content, so they leave
+// it alone.
+//
+// DESIGN: a leaf. It loads node built-ins and project-paths.cjs (which loads node
+// built-ins only) and requires neither the store nor the move module (the move requires
+// the store; the store never requires the move), so either of them, and a check for
+// another folder, can use it. No function here prints or exits, and nothing throws:
+// every failure is the answer `unknown`, with a cause from the closed set UNKNOWN_CAUSES.
+//
+// The folder names come from project-paths.cjs, which owns them: AREA_FOLDERS lists the
+// data folders and the backup prefix names the folders the move leaves behind. To cover
+// another folder, add its name to AREA_FOLDERS.
+//
+// The decision is the repository's index, never the disk. A root with no `.git` entry
+// (a file or a folder) is not a git working tree and gets no git call. A root with one
+// gets exactly one call, and every failure of that call (git missing, a timeout, a
+// non-zero exit with nothing listed) is `unknown`: the caller cannot tell what git
+// tracks and must change nothing. git's error text is never read.
+
+'use strict';
+
+const childProcess = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const { LEGACY_NAMES, CURATION_DIR_NAME } = require('./project-paths.cjs');
+
+/** The data folders under `.devflow` that the check covers, by the names the path helpers hold. */
+const AREA_FOLDERS = Object.freeze([LEGACY_NAMES.folder, CURATION_DIR_NAME]);
+
+/**
+ * The spellings a case-folding file system opens as `.devflow` beyond ASCII letter case.
+ * git's `icase` folds ASCII letters only, but APFS (the macOS default) compares names by
+ * full Unicode case folding, so it also opens `.devflow` (U+FB02 folds to "fl"). The code
+ * is written with an escape, so the code point is named.
+ */
+const DEVFLOW_SPELLINGS = Object.freeze(['.devflow', '.dev\u{FB02}ow']);
+
+/**
+ * The pathspecs of the check, each matched without regard to ASCII letter case, whatever
+ * the file system or `core.ignorecase`, and each spelled every way DEVFLOW_SPELLINGS lists:
+ *   - each folder of AREA_FOLDERS, as a literal path: an index entry at the folder, or
+ *     anywhere below it, matches
+ *   - an entry named like a backup folder (`<backup prefix>*`), and every entry below one
+ *     (`<backup prefix>*` + `/**`): the move leaves its old folder there, and the sweep
+ *     merges the queue files in it into the new folder. The prefix has no glob character.
+ *   - an index entry named `.devflow` ITSELF, which git records only for a symlink, a
+ *     gitlink (submodule) or a plain file, never for a directory: the character class
+ *     keeps `glob` from matching as a leading directory, so the many files under a
+ *     normal `.devflow/` are not listed. Committed content then stands at the path where
+ *     the folders are opened.
+ */
+const TRACKED_AREA_PATHSPECS = Object.freeze([
+  ...DEVFLOW_SPELLINGS.flatMap(dir => [
+    ...AREA_FOLDERS.map(area => ':(icase,literal)' + dir + '/' + area),
+    ':(icase,glob)' + dir + '/' + LEGACY_NAMES.backupPrefix + '*',
+    ':(icase,glob)' + dir + '/' + LEGACY_NAMES.backupPrefix + '*/**',
+  ]),
+  ...DEVFLOW_SPELLINGS.map(dir => ':(icase,glob)[.]' + dir.slice(1)),
+]);
+
+/**
+ * Why a check answered `unknown`, as one fixed word. The words come from this list
+ * alone: they name a spawn error code, a time out, a signal, an exit status or the step
+ * that failed, and never carry git's own text or a path.
+ */
+const UNKNOWN_CAUSES = Object.freeze({
+  rootNotAbsolute: 'root-not-absolute',
+  gitEntryUnreadable: 'git-entry-unreadable',
+  ceilingUnusable: 'ceiling-unusable',
+  checkFailed: 'check-failed',
+  gitNotFound: 'git-not-found',
+  gitTimedOut: 'git-timed-out',
+  gitStopped: 'git-stopped',
+  gitExitStatus: 'git-exit-status',
+  gitNotRun: 'git-not-run',
+});
+
+/** The longest the git call may run (ms). */
+const TRACKED_AREAS_GIT_TIMEOUT_MS = 5000;
+
+/**
+ * The most output the git call may return, in bytes. A normal answer is empty; a
+ * listing past this bound (ENOBUFS) means entries exist, which reads as tracked.
+ */
+const TRACKED_AREAS_GIT_MAX_BUFFER = 4096;
+
+/**
+ * The variables that make git read another repository, another index or other pathspec
+ * rules than the root's own. The call runs without them.
+ */
+const GIT_REDIRECT_VARIABLES = Object.freeze([
+  'GIT_DIR',
+  'GIT_WORK_TREE',
+  'GIT_INDEX_FILE',
+  'GIT_COMMON_DIR',
+  'GIT_OBJECT_DIRECTORY',
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+  'GIT_NAMESPACE',
+  'GIT_LITERAL_PATHSPECS',
+  'GIT_GLOB_PATHSPECS',
+  'GIT_NOGLOB_PATHSPECS',
+  'GIT_ICASE_PATHSPECS',
+]);
+
+/**
+ * The environment of the git call: the process environment without the redirecting
+ * variables, with a fixed locale, no optional lock and a ceiling directory. Answers a new
+ * object. The ceiling is the folder that holds the root: git reads the root's own `.git`
+ * and never looks in a folder above it, so an empty or broken `.git` at the root is not
+ * answered from a work tree around the project.
+ *
+ * @param {NodeJS.ProcessEnv} base
+ * @param {string} ceiling - an absolute path with no list separator in it
+ * @returns {NodeJS.ProcessEnv}
+ */
+function trackedAreasGitEnv(base, ceiling) {
+  const env = { ...base };
+  for (const name of GIT_REDIRECT_VARIABLES) delete env[name];
+  env.LC_ALL = 'C';
+  env.GIT_OPTIONAL_LOCKS = '0';
+  env.GIT_CEILING_DIRECTORIES = ceiling;
+  return env;
+}
+
+/**
+ * The answer of one `git ls-files` call, from the result `spawnSync` gave, with the
+ * cause when the answer is `unknown` (null otherwise):
+ *   tracked    any output byte, whatever the exit status or error (the call listed an
+ *              entry), and an output past the buffer cap (ENOBUFS)
+ *   untracked  exit 0 with nothing listed
+ *   unknown    every other result, with the cause: git-not-found (spawn error ENOENT),
+ *              git-timed-out (ETIMEDOUT), git-not-run (another spawn error, or a result
+ *              of the wrong shape), git-stopped (a signal ended it), git-exit-status (a
+ *              non-zero exit with nothing listed)
+ * Pure: it reads only the fields `error.code`, `status`, `signal` and `stdout`.
+ *
+ * @param {unknown} result
+ * @returns {{ answer: 'tracked' | 'untracked' | 'unknown', cause: string | null }}
+ */
+function judgeTrackedAreas(result) {
+  if (result === null || typeof result !== 'object') return unknownBecause(UNKNOWN_CAUSES.gitNotRun);
+  const { error, status, signal, stdout } = /** @type {{ error?: { code?: unknown }, status?: unknown, signal?: unknown, stdout?: unknown }} */ (result);
+  if (error && error.code === 'ENOBUFS') return { answer: 'tracked', cause: null };
+  const listed = (typeof stdout === 'string' || Buffer.isBuffer(stdout)) && stdout.length > 0;
+  if (listed) return { answer: 'tracked', cause: null };
+  if (error) {
+    if (error.code === 'ENOENT') return unknownBecause(UNKNOWN_CAUSES.gitNotFound);
+    return unknownBecause(error.code === 'ETIMEDOUT' ? UNKNOWN_CAUSES.gitTimedOut : UNKNOWN_CAUSES.gitNotRun);
+  }
+  if (status === 0) return { answer: 'untracked', cause: null };
+  if (typeof status === 'number') return unknownBecause(UNKNOWN_CAUSES.gitExitStatus);
+  return unknownBecause(typeof signal === 'string' ? UNKNOWN_CAUSES.gitStopped : UNKNOWN_CAUSES.gitNotRun);
+}
+
+/**
+ * @param {string} cause - a value of UNKNOWN_CAUSES
+ * @returns {{ answer: 'unknown', cause: string }}
+ */
+function unknownBecause(cause) {
+  return { answer: 'unknown', cause };
+}
+
+/**
+ * The answer of {@link judgeTrackedAreas}, without its cause.
+ *
+ * @param {unknown} result
+ * @returns {'tracked' | 'untracked' | 'unknown'}
+ */
+function classifyTrackedAreas(result) {
+  return judgeTrackedAreas(result).answer;
+}
+
+/**
+ * Whether anything (a file, a folder, a link) stands at `target`: true, false, or null
+ * when the probe failed for a reason other than absence.
+ *
+ * @param {string} target
+ * @returns {boolean | null}
+ */
+function entryExists(target) {
+  try {
+    fs.lstatSync(target);
+    return true;
+  } catch (err) {
+    return err && (err.code === 'ENOENT' || err.code === 'ENOTDIR') ? false : null;
+  }
+}
+
+/**
+ * Whether git tracks any entry under the covered folders at `root`, or an entry named
+ * `.devflow` itself (a link, a gitlink or a file). The index decides, not the disk, and
+ * a staged entry counts. The answer carries the cause (a value of UNKNOWN_CAUSES) when
+ * it is `unknown`, and null otherwise.
+ *
+ *   untracked  no `.git` entry at the root (no git call is made), or git listed nothing
+ *   tracked    git listed an entry
+ *   unknown    a `.git` entry stands and git did not answer (see judgeTrackedAreas),
+ *              the `.git` entry could not be probed, or the root is not an absolute path
+ *              string (no git call is made)
+ *
+ * The call is `git --no-literal-pathspecs -c core.fsmonitor=false ls-files -z -- <paths>`
+ * with the root as its working directory: an argv with no shell, a time bound and an
+ * output bound. `--no-literal-pathspecs` leads the argv, so a forced literal-pathspec
+ * setting cannot turn the magic off and hide an entry. Reading the index makes git run
+ * the command a repository's config names in `core.fsmonitor`, so the call turns that off
+ * for itself and stays a pure read. The folder above the root's real path is a ceiling
+ * directory (trackedAreasGitEnv); a parent path that holds the list separator can not be
+ * named as one, and answers `unknown`.
+ *
+ * @param {unknown} root - an absolute path
+ * @returns {{ answer: 'tracked' | 'untracked' | 'unknown', cause: string | null }}
+ */
+function inspectTrackedAreas(root) {
+  if (typeof root !== 'string' || !path.isAbsolute(root)) return unknownBecause(UNKNOWN_CAUSES.rootNotAbsolute);
+  try {
+    const gitEntry = entryExists(path.join(root, '.git'));
+    if (gitEntry === null) return unknownBecause(UNKNOWN_CAUSES.gitEntryUnreadable);
+    if (gitEntry === false) return { answer: 'untracked', cause: null };
+    const ceiling = path.dirname(fs.realpathSync(root));
+    if (ceiling.includes(path.delimiter)) return unknownBecause(UNKNOWN_CAUSES.ceilingUnusable);
+    const result = childProcess.spawnSync('git', ['--no-literal-pathspecs', '-c', 'core.fsmonitor=false', 'ls-files', '-z', '--', ...TRACKED_AREA_PATHSPECS], {
+      cwd: root,
+      env: trackedAreasGitEnv(process.env, ceiling),
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: TRACKED_AREAS_GIT_TIMEOUT_MS,
+      maxBuffer: TRACKED_AREAS_GIT_MAX_BUFFER,
+      windowsHide: true,
+      shell: false,
+    });
+    return judgeTrackedAreas(result);
+  } catch (_) {
+    return unknownBecause(UNKNOWN_CAUSES.checkFailed);
+  }
+}
+
+/**
+ * The answer of {@link inspectTrackedAreas}, without its cause.
+ *
+ * @param {unknown} root - an absolute path
+ * @returns {'tracked' | 'untracked' | 'unknown'}
+ */
+function checkTrackedAreas(root) {
+  return inspectTrackedAreas(root).answer;
+}
+
+module.exports = {
+  TRACKED_AREA_PATHSPECS,
+  UNKNOWN_CAUSES,
+  judgeTrackedAreas,
+  classifyTrackedAreas,
+  inspectTrackedAreas,
+  checkTrackedAreas,
+};

package/src/assets/scripts/hooks/memory-worker

@@ -43,7 +43,7 @@ MEMORY_DIR="$PROJECT_DEVFLOW_DIR/memory"
 
 # Memory gate: the machine switch, narrowed by this checkout's project.json /
 # config.json `features.memory`, gates this hook entirely -- read by the helper
-# every memory/learning gate shares (D-FEATURES-NARROW-ONLY, see queue-append).
+# every memory/curation gate shares (D-FEATURES-NARROW-ONLY, see queue-append).
 source "$SCRIPT_DIR/queue-append" || { echo "memory-worker: failed to source queue-append" >&2; exit 1; }
 queue_read_gates "$DEVFLOW_MANIFEST" "$PROJECT_ROOT"
 MEMORY_ENABLED="$_QG_MEMORY"

package/src/assets/scripts/hooks/pre-compact-memory

@@ -54,7 +54,7 @@ MEMORY_DIR="$PROJECT_DEVFLOW_DIR/memory"
 source "$SCRIPT_DIR/hook-log-init" "pre-compact-memory"
 
 # Memory gate: the machine switch, narrowed by this checkout's project.json /
-# config.json `features.memory`, read by the helper every memory/learning gate
+# config.json `features.memory`, read by the helper every memory/curation gate
 # shares (D-FEATURES-NARROW-ONLY, see queue-append).
 source "$SCRIPT_DIR/queue-append" || { echo "pre-compact-memory: failed to source queue-append" >&2; exit 1; }
 queue_read_gates "$DEVFLOW_MANIFEST" "$PROJECT_ROOT"
@@ -112,27 +112,18 @@ if cd "$CWD" 2>/dev/null && git rev-parse --git-dir >/dev/null 2>&1; then
   dbg "GIT_BRANCH=$GIT_BRANCH HEAD=$GIT_HEAD_SHA"
 fi
 
-# Snapshot current WORKING-MEMORY.md (preserves session context through compaction).
-# The snapshot goes into the backup the next session start injects, so a working
-# memory a symbolic link leads to is treated as absent (D-HOOKS-NO-SYMLINK).
-MEMORY_SNAPSHOT=""
-if df_file_below "$PROJECT_ROOT" "$MEMORY_DIR/WORKING-MEMORY.md"; then
-  MEMORY_SNAPSHOT=$(head -c 65536 "$MEMORY_DIR/WORKING-MEMORY.md")
-  dbg "MEMORY_SNAPSHOT_LENGTH=${#MEMORY_SNAPSHOT}"
-fi
-
 # Write backup JSON
 # D-BACKUP-RENAME: the backup is written whole into a copy beside it, then
 # renamed over it; it is never truncated and refilled in place. Reason:
-# session-start-memory reads it twice, and a read landing between a truncate
-# and the write that refills it would meet a partial file; a rename hands every
-# read either the previous backup or the new one. SEC-2: the copy is created
+# a read landing between a truncate and the write that refills it would meet a
+# partial file; a rename hands every read either the previous backup or the new
+# one. SEC-2: the copy is created
 # under umask 077, and only where nothing stands at its name: builtin tests come
 # first, so an entry already there, a link to a FIFO or a device included, is
 # never opened (noclobber alone would open one, as no regular file stands there),
 # and noclobber then makes the create itself exclusive. The rename gives the
-# backup the copy's inode and mode, so the backup, which holds the working
-# memory, is 0600 whatever the caller's umask (as in queue-append). A write or
+# backup the copy's inode and mode, so the Git-state backup is 0600 whatever
+# the caller's umask (as in queue-append). A write or
 # rename that fails removes whatever holds the copy's name and keeps the
 # previous backup; the bootstrap below still runs.
 #
@@ -157,7 +148,6 @@ elif [ ! -e "$BACKUP_TMP" ] && [ ! -L "$BACKUP_TMP" ] && (umask 077 && set -o no
     --arg status "$GIT_STATUS" \
     --arg log "$GIT_LOG" \
     --arg diff "$GIT_DIFF_STAT" \
-    --arg memory "$MEMORY_SNAPSHOT" \
     > "$BACKUP_TMP") && mv "$BACKUP_TMP" "$BACKUP_FILE"; then
   log "Wrote backup: $BACKUP_FILE"
   dbg "Wrote backup: $BACKUP_FILE"