devflow-kit 2.4.0 → 3.0.0

package/dist/core/ledger-root.js

@@ -0,0 +1,102 @@
+/**
+ * @file ledger-root.ts
+ *
+ * Where the learning ledger lives for a working directory — the TypeScript twin of
+ * `df_resolve_roots`' DF_LEDGER_ROOT in src/assets/scripts/hooks/resolve-project-root.
+ *
+ * D-LEDGER-MAIN-WORKTREE: the ledger is one per REPOSITORY, not per checkout. In a
+ * linked worktree the hooks queue and render into the main worktree's
+ * `.devflow/learning/`, so `devflow learning` and the HUD must read and clear that
+ * same directory — resolving the worktree's own toplevel (getGitRoot) would show an
+ * empty ledger and drain a queue nothing writes to. The rule, from ONE git call:
+ *
+ *   git rev-parse --path-format=absolute --show-toplevel --git-common-dir
+ *
+ *   - exactly two absolute lines, the common dir ends in `/.git`, `<main>/.devflow`
+ *     is a directory and `<main>` is not HOME (physical paths, like the hooks'
+ *     df_is_project_root) → `<main>`;
+ *   - two absolute lines otherwise → the toplevel;
+ *   - git before 2.31 echoes `--path-format=absolute` back as its own line → the
+ *     toplevel it printed after it (the hooks fall back to the toplevel too);
+ *   - git failed (not a work tree) → null: the caller keeps its non-git fallback;
+ *   - any other output → getGitRoot(), the hooks' df_resolve_root fallback.
+ *
+ * Memory is NOT resolved here: working memory stays per checkout (getGitRoot).
+ * Parity with the shell helper is pinned by tests/core/ledger-root.test.ts, which
+ * runs df_resolve_roots on the same fixtures.
+ */
+import { execFile } from 'child_process';
+import { promises as fs } from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { getGitRoot } from './git.js';
+/** The one git call, as argv (no shell). */
+const LEDGER_ROOT_GIT_ARGS = ['rev-parse', '--path-format=absolute', '--show-toplevel', '--git-common-dir'];
+/** What git before 2.31 prints first: the flag it does not know, echoed back. */
+const PATH_FORMAT_ECHO = '--path-format=absolute';
+/** Classify the git call's stdout. Pure. */
+export function parseLedgerRootOutput(stdout) {
+    const lines = stdout.replace(/\n$/, '').split('\n');
+    if (lines.length === 2 && lines.every(l => path.isAbsolute(l))) {
+        return { kind: 'roots', toplevel: lines[0], commonDir: lines[1] };
+    }
+    if (lines.length === 3 && lines[0] === PATH_FORMAT_ECHO && path.isAbsolute(lines[1])) {
+        return { kind: 'toplevel', toplevel: lines[1] };
+    }
+    return { kind: 'unrecognised' };
+}
+/** stdout of the one git call from `cwd`, or null when git failed. */
+function runRevParse(cwd, timeoutMs) {
+    return new Promise((resolve) => {
+        execFile('git', LEDGER_ROOT_GIT_ARGS, { cwd, timeout: timeoutMs, encoding: 'utf-8' }, (err, stdout) => {
+            resolve(err ? null : stdout);
+        });
+    });
+}
+/** A path's physical location, or null when it cannot be resolved. */
+async function physical(target) {
+    try {
+        return await fs.realpath(target);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether the main worktree `main` holds the ledger: it has a `.devflow/` directory
+ * and is not HOME. An unresolvable `main` is refused (the ledger stays in this
+ * checkout); an unresolvable HOME cannot equal it, so it refuses nothing — both as
+ * df_is_project_root decides.
+ */
+async function mainHoldsLedger(main, home) {
+    const stat = await fs.stat(path.join(main, '.devflow')).catch(() => null);
+    if (!stat?.isDirectory())
+        return false;
+    const [mainReal, homeReal] = await Promise.all([physical(main), physical(home)]);
+    return mainReal !== null && mainReal !== homeReal;
+}
+/**
+ * The learning ledger root for `cwd` — the main worktree or this checkout's
+ * toplevel — or null outside a git work tree.
+ */
+export async function getLedgerRoot(cwd = process.cwd(), options = {}) {
+    const stdout = await runRevParse(cwd, options.timeoutMs ?? 0);
+    if (stdout === null)
+        return null;
+    const parsed = parseLedgerRootOutput(stdout);
+    switch (parsed.kind) {
+        case 'toplevel':
+            return parsed.toplevel;
+        case 'unrecognised':
+            return getGitRoot(cwd);
+        case 'roots': {
+            if (!parsed.commonDir.endsWith('/.git'))
+                return parsed.toplevel;
+            const main = parsed.commonDir.slice(0, -'/.git'.length);
+            if (main && await mainHoldsLedger(main, options.home ?? os.homedir()))
+                return main;
+            return parsed.toplevel;
+        }
+    }
+}
+//# sourceMappingURL=ledger-root.js.map

package/dist/core/manifest.js

@@ -3,6 +3,7 @@ import * as path from 'path';
 import { LEGACY_PLUGIN_NAMES, DELETED_PLUGIN_NAMES } from './plugins.js';
 import { VIEW_MODES, migrateLegacyFlagsToRecord, sanitizeFlagsRecord, } from './flags.js';
 import { normalizeComplianceFeature } from './compliance.js';
+import { normalizeTrackerFeature } from './tracker.js';
 import { writeFileAtomicExclusive } from './fs-atomic.js';
 /**
  * Parse features.flags across the three on-disk shapes; reports whether a heal is owed.
@@ -54,13 +55,14 @@ function parseManifestFlags(features, knownFlags) {
  * Read and parse the manifest file. Returns null if missing or corrupt.
  *
  * Self-heals the following on-disk inconsistencies (applies ADR-014):
- * - features.kb → features.knowledge rename
- * - features.decisions → features.learning rename
+ * - features.kb → features.knowledge rename (both absent → true, D-FEATURES-ABSENT-ON)
+ * - features.decisions → features.learning rename (both absent → true, D-FEATURES-ABSENT-ON)
  * - features.flags as string[] → FlagsRecord (via migrateLegacyFlagsToRecord)
  * - features.viewMode folded into flags['view-mode'] and stripped from result
  * - features.knownFlags stripped from result (folded into FlagsRecord key-presence)
  * - features.proxy absent → false
  * - features.compliance absent/malformed → {enabled:false, frameworks:[]}
+ * - features.tracker absent/malformed → {provider:'github'}
  *
  * D39: heal-write failure returns the migrated in-memory manifest (not null).
  * The on-disk format remains unhealed; next read triggers another attempt.
@@ -73,7 +75,6 @@ export async function readManifest(devflowDir) {
         const features = data.features;
         if (!data.version ||
             !Array.isArray(data.plugins) ||
-            !data.scope ||
             typeof features !== 'object' ||
             features === null ||
             typeof features.ambient !== 'boolean' ||
@@ -82,15 +83,33 @@ export async function readManifest(devflowDir) {
             typeof data.updatedAt !== 'string') {
             return null;
         }
-        // Self-heal: rename features.kb → features.knowledge on disk
+        // D-FEATURES-ABSENT-ON (a sub-decision of D-FEATURES-NARROW-ONLY,
+        // src/core/feature-switch.ts): knowledge and learning are machine-wide
+        // switches, and every runtime gate — queue_read_gates in the hooks,
+        // isMachineFeatureOn in the CLI, the knowledge write-back prose gate — reads
+        // an ABSENT key as ON. This reader must agree: init seeds from it and every
+        // syncManifestFeature toggle writes its result back, so a `false` default
+        // here would persist "off" for a feature the runtime is running — a plain
+        // re-init or `devflow hud --enable` on an older manifest silently switching
+        // it off machine-wide. Explicit booleans (and their legacy names) are kept
+        // as they are. memory needs no default: it is in the hard-null set above,
+        // so a manifest without it reads as no prior install and init seeds
+        // FEATURE_DEFAULTS.memory (true).
+        //
+        // Self-heal: rename features.kb → features.knowledge on disk.
+        // Coalesce: features.knowledge wins; fall back to features.kb; default ON.
+        // D-KNOWLEDGE-LEGACY-KB: isMachineFeatureOn applies this exact precedence,
+        // so the legacy key is honoured before the heal lands.
         const knowledge = typeof features.knowledge === 'boolean' ? features.knowledge
             : typeof features.kb === 'boolean' ? features.kb
-                : false;
-        // Self-heal: rename features.decisions → features.learning on disk
-        // Coalesce: features.learning wins; fall back to features.decisions; default false.
+                : true;
+        // Self-heal: rename features.decisions → features.learning on disk (ADR-011).
+        // Coalesce: features.learning wins; fall back to features.decisions; default ON.
+        // D-LEARNING-LEGACY-DECISIONS: isMachineFeatureOn and queue_read_gates apply
+        // this exact precedence, so the legacy key is honoured before the heal lands.
         const learning = typeof features.learning === 'boolean' ? features.learning
             : typeof features.decisions === 'boolean' ? features.decisions
-                : false;
+                : true;
         // Self-heal: non-string-array or absent knownFlags/knownPlugins → undefined (never partial/garbage)
         const asStringArray = (val) => Array.isArray(val) && val.every(e => typeof e === 'string')
             ? val
@@ -115,7 +134,8 @@ export async function readManifest(devflowDir) {
         const manifest = {
             version: data.version,
             plugins: data.plugins,
-            scope: data.scope,
+            // D-MANIFEST-SCOPE-PINNED: the on-disk value is not consulted.
+            scope: 'user',
             knownPlugins,
             features: {
                 ambient: features.ambient,
@@ -138,6 +158,12 @@ export async function readManifest(devflowDir) {
                 proxy: typeof features.proxy === 'boolean' ? features.proxy : false,
                 // Self-heal: absent/malformed compliance → {enabled:false, frameworks:[]}
                 compliance: normalizeComplianceFeature(features.compliance),
+                // Self-heal: absent/malformed/unknown tracker → {provider:'github'} (AC-3.21).
+                // Deliberately NOT in the hard-null set above — see the field's doc comment.
+                // Healing here is silent and emits no DEGRADED: that is the correct
+                // ADR-014 behaviour, and a different condition from a per-repo config
+                // value outside the domain (which does emit `unknown tracker provider`).
+                tracker: normalizeTrackerFeature(features.tracker),
             },
             installedAt: data.installedAt,
             updatedAt: data.updatedAt,
@@ -168,7 +194,9 @@ export async function readManifest(devflowDir) {
 export async function writeManifest(devflowDir, data) {
     await fs.mkdir(devflowDir, { recursive: true });
     const manifestPath = path.join(devflowDir, 'manifest.json');
-    await writeFileAtomicExclusive(manifestPath, JSON.stringify(data, null, 2) + '\n');
+    // D-MANIFEST-SCOPE-PINNED: every write records 'user', whatever the caller holds.
+    const pinned = { ...data, scope: 'user' };
+    await writeFileAtomicExclusive(manifestPath, JSON.stringify(pinned, null, 2) + '\n');
 }
 /**
  * Update a single feature field in the manifest. No-op when no manifest exists.