@momentiq/dark-factory-cli 2.17.0 → 3.0.0

package/dist/mode/apply.js

@@ -0,0 +1,118 @@
+// Cycle 27 Phase B — `df mode apply <name>`: generate the per-user Claude
+// Code overlay in `.claude/settings.local.json` (git-ignored — engineers on
+// the same repo are untouched; the designer opts in on their own machine).
+//
+// Merge discipline: read-modify-write JSON that only ADDS what the mode
+// needs — env.DF_MODE, the two df hooks, a destructive-git deny belt, and
+// MCP enablement — and never disturbs unrelated user keys. Idempotent by
+// containment checks, not by rewriting.
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { parseDarkFactoryConfig } from "@momentiq/dark-factory-schemas";
+import { resolveModeWithConfig } from "./resolve.js";
+const GUARD_COMMAND = '"$CLAUDE_PROJECT_DIR"/node_modules/.bin/df mode guard --hook';
+const CONTEXT_COMMAND = '"$CLAUDE_PROJECT_DIR"/node_modules/.bin/df mode context --hook';
+const DENY_BELT = [
+    "Bash(git push --force:*)",
+    "Bash(git push -f:*)",
+    "Bash(git reset --hard:*)",
+    "Bash(git clean:*)",
+];
+function ensureHook(hooks, event, command, matcher) {
+    const entries = (hooks[event] ??= []);
+    const present = entries.some((e) => e.hooks.some((h) => h.command === command));
+    if (present)
+        return;
+    const entry = { hooks: [{ type: "command", command }] };
+    if (matcher !== undefined)
+        entry.matcher = matcher;
+    entries.push(entry);
+}
+export function applyMode(repoRoot, modeName) {
+    // Validate against the catalog first — applying an unknown mode would
+    // produce a session that immediately fail-closes every file tool.
+    const configPath = join(repoRoot, "darkfactory.yaml");
+    const raw = existsSync(configPath)
+        ? (parseYaml(readFileSync(configPath, "utf8")) ?? {})
+        : {};
+    resolveModeWithConfig(parseDarkFactoryConfig(raw), modeName);
+    const dir = join(repoRoot, ".claude");
+    const settingsPath = join(dir, "settings.local.json");
+    const created = !existsSync(settingsPath);
+    const settings = created
+        ? {}
+        : JSON.parse(readFileSync(settingsPath, "utf8"));
+    settings.env = { ...(settings.env ?? {}), DF_MODE: modeName };
+    const hooks = (settings.hooks ??= {});
+    ensureHook(hooks, "PreToolUse", GUARD_COMMAND, "Edit|Write|MultiEdit|NotebookEdit|Bash");
+    ensureHook(hooks, "SessionStart", CONTEXT_COMMAND);
+    const permissions = (settings.permissions ??= {});
+    const deny = new Set(permissions.deny ?? []);
+    for (const rule of DENY_BELT)
+        deny.add(rule);
+    permissions.deny = [...deny];
+    const servers = new Set(settings.enabledMcpjsonServers ?? []);
+    servers.add("dark-factory");
+    settings.enabledMcpjsonServers = [...servers];
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+    ensureLocallyIgnored(repoRoot);
+    return { status: "applied", modeName, settingsPath, created };
+}
+const OVERLAY_IGNORE_ENTRY = ".claude/settings.local.json";
+/**
+ * Resolve the git **common** directory for `repoRoot` — the directory that
+ * owns `info/exclude`. In a normal clone this is `<repoRoot>/.git`, but in a
+ * linked worktree (or a submodule) `<repoRoot>/.git` is a POINTER FILE
+ * (`gitdir: …`), not a directory, and the per-clone exclude lives in the
+ * SHARED common dir, never under the worktree-private git dir. `git rev-parse
+ * --git-common-dir` reports the right path in every layout — absolute for a
+ * linked worktree, relative (`.git`) for a normal clone — and `resolve`
+ * returns an absolute segment as-is while joining the relative one onto
+ * `repoRoot`, so a single call covers both. Best-effort: returns null when git
+ * is unavailable or `repoRoot` is not a work tree, so apply skips ignoring
+ * rather than crashing.
+ */
+function resolveGitCommonDir(repoRoot) {
+    try {
+        const out = execFileSync("git", ["rev-parse", "--git-common-dir"], {
+            cwd: repoRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        return out.length === 0 ? null : resolve(repoRoot, out);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The overlay is documented as per-user and git-ignored. Claude Code's own
+ * scaffolds usually ignore it, but nothing guarantees a given consumer repo
+ * does — so make it true structurally via the git common dir's `info/exclude`,
+ * which is per-clone (never committed), exactly matching the overlay's per-user
+ * semantics. Best-effort: a non-git directory — or a linked worktree whose git
+ * dir cannot be resolved — is left untouched, never crashing apply.
+ */
+function ensureLocallyIgnored(repoRoot) {
+    // Fast local guard: only act when THIS directory roots a work tree (`.git`
+    // is a dir in a normal clone, a pointer FILE in a linked worktree/submodule).
+    // Skipping the git probe for a plain directory keeps apply best-effort and
+    // stops git's parent search from writing to an unrelated ancestor repo.
+    if (!existsSync(join(repoRoot, ".git")))
+        return;
+    const gitCommonDir = resolveGitCommonDir(repoRoot);
+    if (gitCommonDir === null)
+        return;
+    const infoDir = join(gitCommonDir, "info");
+    const excludePath = join(infoDir, "exclude");
+    const current = existsSync(excludePath) ? readFileSync(excludePath, "utf8") : "";
+    if (current.split(/\r?\n/).includes(OVERLAY_IGNORE_ENTRY))
+        return;
+    mkdirSync(infoDir, { recursive: true });
+    const separator = current.length === 0 || current.endsWith("\n") ? "" : "\n";
+    writeFileSync(excludePath, `${current}${separator}${OVERLAY_IGNORE_ENTRY}\n`);
+}
+//# sourceMappingURL=apply.js.map

package/dist/mode/apply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.js","sourceRoot":"","sources":["../../src/mode/apply.ts"],"names":[],"mappings":"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"}

package/dist/mode/context.d.ts

@@ -0,0 +1,50 @@
+import type { ModeConfig } from "@momentiq/dark-factory-schemas";
+/**
+ * Load the baseline persona asset. Lives alongside this module in both src
+ * (tests) and dist (runtime — the build's copy-assets step ships it), so an
+ * import.meta.url-relative read works in both.
+ */
+export declare function loadBaselinePersona(): string;
+export interface ResolvedModeLike {
+    modeName: string;
+    mode: ModeConfig;
+}
+/**
+ * The strict repo-relative path predicate used for the DISPLAY path only —
+ * pure lexical, no filesystem access. `buildModeContext` echoes the configured
+ * `designMd` into the LLM-consumed SessionStart note, so it gates on this and
+ * shows a neutral placeholder for anything that is not a genuine strict
+ * repo-relative path. True only for a non-empty, length-bounded value built
+ * from safe path characters (letters, digits, `.` `_` `-` `/`) that is NOT
+ * absolute and contains NO empty/current/parent (`.`/`..`) segments. The
+ * character grammar keeps the value free of spaces, newlines, backticks, and
+ * markdown metacharacters, so a hostile catalog value cannot express multi-word
+ * instructions or open a new markdown block in the injected context.
+ *
+ * This is deliberately STRICTER than what `safeDesignMdPath` accepts for reads:
+ * read-safety asks "is this a real file inside the repo?" (spaces are fine);
+ * display-safety asks "is this safe to echo into model context?" (they are not).
+ * Keeping them separate avoids narrowing the public `designSystem.designMd`
+ * string contract while still hardening the injected note.
+ */
+export declare function isStrictRepoRelativePath(p: string): boolean;
+/**
+ * Resolve the catalog's `designSystem.designMd` value safely: it is a
+ * REPO-RELATIVE path by contract, and this hook injects the file's contents
+ * into session context — so the check must hold against the REAL filesystem,
+ * not just lexically. Returns the resolved path only when:
+ *   - the value is relative and its lexical resolution stays under repoRoot,
+ *   - the file exists and is a regular file, and
+ *   - its realpath (symlinks followed) still lives under the repo's realpath
+ *     (a repo-local DESIGN.md symlinked to ~/.ssh/id_rsa returns null).
+ * A missing file also returns null — "unseeded" is a normal state the
+ * caller narrates; it must never be distinguishable from "blocked" in ways
+ * that leak what exists outside the repo.
+ *
+ * This accepts ANY real repo-relative file (paths with spaces included): it
+ * enforces filesystem safety, NOT the stricter display grammar, so it does not
+ * narrow the public `designSystem.designMd` string contract.
+ */
+export declare function safeDesignMdPath(repoRoot: string, designMd: string): string | null;
+export declare function buildModeContext(resolved: ResolvedModeLike, designMdContent: string | undefined): string;
+//# sourceMappingURL=context.d.ts.map

package/dist/mode/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/mode/context.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAIjE;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;CAClB;AAID;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAQ3D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAoBlF;AAED,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,gBAAgB,EAC1B,eAAe,EAAE,MAAM,GAAG,SAAS,GAClC,MAAM,CAqCR"}

package/dist/mode/context.js

@@ -0,0 +1,127 @@
+// Cycle 27 Phase B — `df mode context --hook`: build the SessionStart
+// additionalContext for an operator-mode session. Persona (baseline tier,
+// shipped as a dist asset with the DF-PROFILE sentinel) + live mode summary
+// + the repo's DESIGN.md as design doctrine.
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+const HERE = dirname(fileURLToPath(import.meta.url));
+/**
+ * Load the baseline persona asset. Lives alongside this module in both src
+ * (tests) and dist (runtime — the build's copy-assets step ships it), so an
+ * import.meta.url-relative read works in both.
+ */
+export function loadBaselinePersona() {
+    return readFileSync(resolve(HERE, "prompts", "designer-baseline.md"), "utf8");
+}
+const STRICT_REL_PATH = /^[A-Za-z0-9._\/-]+$/;
+/**
+ * The strict repo-relative path predicate used for the DISPLAY path only —
+ * pure lexical, no filesystem access. `buildModeContext` echoes the configured
+ * `designMd` into the LLM-consumed SessionStart note, so it gates on this and
+ * shows a neutral placeholder for anything that is not a genuine strict
+ * repo-relative path. True only for a non-empty, length-bounded value built
+ * from safe path characters (letters, digits, `.` `_` `-` `/`) that is NOT
+ * absolute and contains NO empty/current/parent (`.`/`..`) segments. The
+ * character grammar keeps the value free of spaces, newlines, backticks, and
+ * markdown metacharacters, so a hostile catalog value cannot express multi-word
+ * instructions or open a new markdown block in the injected context.
+ *
+ * This is deliberately STRICTER than what `safeDesignMdPath` accepts for reads:
+ * read-safety asks "is this a real file inside the repo?" (spaces are fine);
+ * display-safety asks "is this safe to echo into model context?" (they are not).
+ * Keeping them separate avoids narrowing the public `designSystem.designMd`
+ * string contract while still hardening the injected note.
+ */
+export function isStrictRepoRelativePath(p) {
+    if (p.length === 0 || p.length > 200)
+        return false;
+    if (!STRICT_REL_PATH.test(p))
+        return false;
+    if (isAbsolute(p))
+        return false;
+    for (const segment of p.split("/")) {
+        if (segment === "" || segment === "." || segment === "..")
+            return false;
+    }
+    return true;
+}
+/**
+ * Resolve the catalog's `designSystem.designMd` value safely: it is a
+ * REPO-RELATIVE path by contract, and this hook injects the file's contents
+ * into session context — so the check must hold against the REAL filesystem,
+ * not just lexically. Returns the resolved path only when:
+ *   - the value is relative and its lexical resolution stays under repoRoot,
+ *   - the file exists and is a regular file, and
+ *   - its realpath (symlinks followed) still lives under the repo's realpath
+ *     (a repo-local DESIGN.md symlinked to ~/.ssh/id_rsa returns null).
+ * A missing file also returns null — "unseeded" is a normal state the
+ * caller narrates; it must never be distinguishable from "blocked" in ways
+ * that leak what exists outside the repo.
+ *
+ * This accepts ANY real repo-relative file (paths with spaces included): it
+ * enforces filesystem safety, NOT the stricter display grammar, so it does not
+ * narrow the public `designSystem.designMd` string contract.
+ */
+export function safeDesignMdPath(repoRoot, designMd) {
+    if (isAbsolute(designMd))
+        return null;
+    const resolved = resolve(repoRoot, designMd);
+    const rel = relative(repoRoot, resolved);
+    // Reject only TRUE parent-traversal: the bare `..`, or a path whose first
+    // segment is `..` (`../x`). `rel.startsWith("..")` alone would also reject a
+    // legitimate repo-local path whose first segment merely BEGINS with `..`
+    // (e.g. `..docs/DESIGN.md`), so key on the separator — matching the realpath
+    // check below.
+    if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`))
+        return null;
+    try {
+        if (!statSync(resolved).isFile())
+            return null;
+        const realTarget = realpathSync(resolved);
+        const realRoot = realpathSync(repoRoot);
+        const realRel = relative(realRoot, realTarget);
+        if (realRel === "" || realRel === ".." || realRel.startsWith(`..${sep}`))
+            return null;
+        return resolved;
+    }
+    catch {
+        return null; // missing, unreadable, or unresolvable — treat as unseeded
+    }
+}
+export function buildModeContext(resolved, designMdContent) {
+    const { modeName, mode } = resolved;
+    const persona = loadBaselinePersona();
+    const summary = [
+        `## Active operator mode: ${modeName}`,
+        "",
+        `- Editable areas (writeScopes): ${(mode.writeScopes ?? []).join(", ") || "(none configured)"}`,
+        `- Protected areas (always off-limits, they win on overlap): ${(mode.protectedPaths ?? []).join(", ") || "(none)"}`,
+        `- Dependency policy: ${mode.dependencyPolicy ?? "(unset)"} — dependency changes ${mode.dependencyPolicy === "none" ? "always escalate via handoff" : "may escalate"}`,
+        mode.devServer?.command
+            ? `- Dev server for visual verification: \`${mode.devServer.command}\`${mode.devServer.url ? ` → ${mode.devServer.url}` : ""}`
+            : `- Dev server: not configured — ask an engineer to set modes.${modeName}.devServer before visual work`,
+        `- Visual evidence: ${mode.evidence?.visual ?? "(unset)"}`,
+    ].join("\n");
+    // designSystem.designMd is a repo-relative path that may be nested (not
+    // necessarily the repo root), so the "unseeded" note names the configured
+    // location rather than hardcoding "the repo root". This value is echoed into
+    // the LLM-consumed SessionStart context, where markdown fencing is NOT a
+    // prompt-injection boundary — so echo it only when it is a strict
+    // repo-relative path (isStrictRepoRelativePath); anything else (absolute,
+    // `.`/`..` traversal, or containing spaces/newlines/markdown metachars) is
+    // shown as a neutral placeholder rather than echoed, so it can neither leak a
+    // non-repo-relative path nor inject text. This display gate is intentionally
+    // stricter than the read resolver, which accepts any real repo-relative file.
+    const rawDesignMd = mode.designSystem?.designMd ?? "DESIGN.md";
+    const designMdRel = isStrictRepoRelativePath(rawDesignMd)
+        ? rawDesignMd
+        : "(configured path omitted: unsafe characters)";
+    const designDoc = designMdContent
+        ? `## DESIGN.md (design source of truth)\n\n${designMdContent}`
+        : `## DESIGN.md\n\nNo DESIGN.md was found at \`${designMdRel}\` — it has not been seeded yet. ` +
+            `Follow the repo's existing visual patterns strictly, and suggest running ` +
+            `\`df onboard\` to an engineer so design doctrine gets a home.`;
+    return [persona, summary, designDoc].join("\n\n---\n\n");
+}
+//# sourceMappingURL=context.js.map

package/dist/mode/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/mode/context.ts"],"names":[],"mappings":"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"}

package/dist/mode/critic-registration.d.ts

@@ -0,0 +1,66 @@
+/** The critic id used for the ModeScope critic in `.agent-review/config.json`. */
+export declare const MODE_SCOPE_CRITIC_ID = "mode-scope-critic";
+export interface ModeScopeRegistrationResult {
+    /** Whether the config was modified (false = already registered / idempotent). */
+    changed: boolean;
+    /** Human-readable descriptions of each mutation, for `df mode init` output. */
+    changes: string[];
+}
+/**
+ * The critic entry appended to `critics[]`. Deterministic critic: no auth,
+ * no vendor SDK. `required: true` — the scope critic is a HARD GATE, so its
+ * blockers must block under EVERY aggregation policy. Under `block-if-any`
+ * the gate demotes `required: false` critics' findings to warnings (report.ts
+ * / gate.ts key on `config.critics.filter(c => c.required)`), so a
+ * `required: false` scope critic would NOT block an out-of-scope `Mode:` PR
+ * there. `required: true` is also safe under `min-complete-quorum`: that path
+ * (`quorumAggregateVerdict`) never consults the `required` flag, and because
+ * the adapter ALWAYS completes it never trips the "required critic errored →
+ * block" rule — so it only ever adds the veto its blocker already carries, and
+ * the per-path quorum bumps below stay exact. `runtime: "local"` is metadata —
+ * the same deterministic entry is referenced by both the local and cloud
+ * profiles (mirrors how `cursor-*` is shared across profiles).
+ */
+export declare function buildModeScopeCriticEntry(): Record<string, unknown>;
+/**
+ * Register the ModeScope critic into a raw parsed `.agent-review/config.json`
+ * object. Mutates `raw` in place AND returns a change report. The caller
+ * validates the mutated object through `parseAgentReviewConfig` before
+ * persisting it.
+ *
+ * "Present" is NOT "safe". A pre-existing mode-scope entry can itself be
+ * UNSAFE — an older CLI (or a hand edit) may have added it `required: false`
+ * (its blockers are demoted to warnings under block-if-any) or left it out of a
+ * profile (it does not run at all under profile-filtered runs). So rather than
+ * no-op the instant an entry is present, we CONVERGE it to the required shape:
+ * promote `required: true`, repair a missing id, and ensure the id is in every
+ * profile. Only a FULLY compliant entry is a true no-op (`changed: false`).
+ *
+ * Quorum is preserved EXACTLY ONCE per scope, keyed on the absent→present
+ * transition (`bumpRootQuorum` for the root fleet, `ensureCriticInEveryProfile`
+ * per profile), so a converge re-run never double-counts.
+ */
+export declare function registerModeScopeCritic(raw: unknown): ModeScopeRegistrationResult;
+export interface CriticRegistrationOutcome {
+    /** Resolved path to `.agent-review/config.json`. */
+    configPath: string;
+    status: "registered" | "already-registered" | "absent" | "error";
+    /** Change descriptions when status === "registered". */
+    changes: string[];
+    /** Present when status === "error". */
+    error?: string;
+}
+/**
+ * Register the ModeScope critic into `<repoRoot>/.agent-review/config.json`.
+ *
+ *  - `absent`: no config.json — the consumer hasn't run `df onboard`. Skipped
+ *    (not an error): the catalog seed still stands and re-running init after
+ *    onboarding completes registration.
+ *  - `already-registered`: the critic is already present — idempotent no-op.
+ *  - `registered`: patched + written.
+ *  - `error`: the config is malformed OR the patched config fails canonical
+ *    validation. The on-disk file is left UNTOUCHED (fail-closed); the error
+ *    is reported, not thrown, so `df mode init` degrades gracefully.
+ */
+export declare function applyModeScopeCriticRegistration(repoRoot: string): CriticRegistrationOutcome;
+//# sourceMappingURL=critic-registration.d.ts.map

package/dist/mode/critic-registration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"critic-registration.d.ts","sourceRoot":"","sources":["../../src/mode/critic-registration.ts"],"names":[],"mappings":"AAwCA,kFAAkF;AAClF,eAAO,MAAM,oBAAoB,sBAAsB,CAAC;AAExD,MAAM,WAAW,2BAA2B;IAC1C,iFAAiF;IACjF,OAAO,EAAE,OAAO,CAAC;IACjB,+EAA+E;IAC/E,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASnE;AAqED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG,2BAA2B,CA4FjF;AAKD,MAAM,WAAW,yBAAyB;IACxC,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,YAAY,GAAG,oBAAoB,GAAG,QAAQ,GAAG,OAAO,CAAC;IACjE,wDAAwD;IACxD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gCAAgC,CAAC,QAAQ,EAAE,MAAM,GAAG,yBAAyB,CA4C5F"}