spexcode 0.6.2 → 0.6.6

package/node_modules/@spexcode/spec-cli/dist/commit-surgery.d.ts

@@ -0,0 +1 @@
+export declare function commitSurgery(proj?: string): void;

package/node_modules/@spexcode/spec-cli/dist/commit-surgery.js

@@ -0,0 +1,90 @@
+import { execFileSync } from 'node:child_process';
+import { relative } from 'node:path';
+import { materialize, stripSpexcodeBlock, GENERATED_MARK } from './materialize.js';
+import { HARNESSES } from './harness.js';
+import { gitBinary } from '@spexcode/spec-core';
+// GIT ENV, deliberately INVERTED from git.ts's git(): every call here PRESERVES the hook's environment —
+// GIT_INDEX_FILE must be honored so the surgery reads/writes the EXACT index this commit is being built
+// from (a `git commit <path>` pathspec commit and `git commit -a` both run hooks against a TEMPORARY index;
+// operating on the real one would silently miss them). git.ts strips that env for repo DISCOVERY reasons;
+// index surgery is the one place the env is the point.
+const raw = (args, input) => execFileSync(gitBinary(process.env), args, { input, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+function inHead(p) {
+    try {
+        raw(['cat-file', '-e', `HEAD:${p}`]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function stagedBlob(p) {
+    try {
+        return raw(['show', `:${p}`]);
+    }
+    catch {
+        return null;
+    }
+}
+function evict(p, why) {
+    raw(['update-index', '--force-remove', '--', p]);
+    console.error(`spexcode: unstaged ${p} (${why} — generated artifacts are never tracked; the file stays on disk)`);
+}
+function replaceBlob(p, content) {
+    const stage = raw(['ls-files', '--stage', '--', p]).trim(); // "100644 <sha> 0\t<p>"
+    const mode = stage.split(/\s/)[0] || '100644';
+    const sha = raw(['hash-object', '-w', '--stdin'], content).trim();
+    raw(['update-index', '--cacheinfo', `${mode},${sha},${p}`]);
+    console.error(`spexcode: stripped the <!-- spexcode --> block from staged ${p} (the block is working-tree context, never history)`);
+}
+export function commitSurgery(proj = process.cwd()) {
+    // (1) unconditional materialize — machine-fixable state (exclude entries, filter binding, kind flips)
+    // is repaired BEFORE the index is inspected, so the inspection below judges against fresh masks.
+    try {
+        materialize(proj);
+    }
+    catch (e) {
+        console.error(`spexcode: pre-commit materialize failed (${e.message}) — footprint may be stale this commit`);
+    }
+    const staged = raw(['diff', '--cached', '--name-only', '-z']).split('\0').filter(Boolean);
+    if (!staged.length)
+        return;
+    const rel = (f) => relative(proj, f);
+    const contracts = new Set(HARNESSES.flatMap((h) => h.contractFiles(proj)).map(rel));
+    const machine = new Set(['spexcode.local.json', '.session']);
+    for (const h of HARNESSES) {
+        machine.add(rel(h.shimFile(proj)));
+        const a = h.worktreeHookAnchor(proj);
+        if (a)
+            machine.add(rel(a));
+    }
+    const generatedDirs = HARNESSES.flatMap((h) => [h.skillDir(proj), h.agentDir(proj)])
+        .filter((d) => !!d).map((d) => `${rel(d)}/`);
+    for (const p of staged) {
+        if (contracts.has(p)) {
+            const blob = stagedBlob(p);
+            if (blob === null)
+                continue;
+            const stripped = stripSpexcodeBlock(blob);
+            if (stripped === blob)
+                continue; // no block staged — clean already did its job
+            if (!stripped.trim() && !inHead(p))
+                evict(p, 'wholly a spexcode materialized artifact');
+            else
+                replaceBlob(p, stripped);
+        }
+        else if (machine.has(p) || p.startsWith('.worktrees/')) {
+            if (!inHead(p))
+                evict(p, 'a machine-local spexcode file');
+            else
+                console.error(`spexcode: ${p} is a machine-local spexcode file but HEAD already tracks it — not touching a tracked file; untrack it yourself (git rm --cached ${p})`);
+        }
+        else if (generatedDirs.some((d) => p.startsWith(d))) {
+            if (inHead(p))
+                continue; // historically tracked — the host's call
+            const blob = stagedBlob(p);
+            if (blob !== null && blob.includes(GENERATED_MARK))
+                evict(p, 'a generated skill/agent artifact');
+        }
+    }
+}

package/node_modules/@spexcode/spec-cli/dist/contract-filter.d.ts

@@ -0,0 +1,14 @@
+export type ContractFilterPayload = {
+    file: string;
+    content: string;
+};
+export type ContractFilterBinding = {
+    file: string;
+    start: string;
+    end: string;
+};
+export declare function plantContractFilter(proj: string, payloads: ContractFilterPayload[], bindings: ContractFilterBinding[], changedFiles?: readonly string[]): boolean;
+export declare function settleIndexStat(proj: string, files: string[]): void;
+export declare function clearContractFilterPayload(proj: string, files?: string[]): void;
+export declare function removeContractFilter(proj: string, files?: string[], final?: boolean): void;
+export declare function contractFilterPlanted(proj: string): boolean;

package/node_modules/@spexcode/spec-cli/dist/contract-filter.js

@@ -0,0 +1,219 @@
+import { mkdirSync, readFileSync, rmSync, chmodSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { git, gitBinary } from '@spexcode/spec-core';
+import { writeManagedBlock, removeManagedBlock } from './harness.js';
+import { encodeProject, runtimeRoot, treeSlotDir } from '@spexcode/spec-core';
+import { writeFileIfChanged } from './file-write.js';
+// the three field-sharpened edges this module owes ([[content-filter]]):
+//   ① the configured command points at a STABLE shim path and degrades to `cat` (identity) when the shim is
+//     missing — a bare missing filter command makes git spray "cannot fork" fatals on EVERY operation;
+//   ② a changed contract does NOT propagate by itself (git re-smudges only on checkout) — materialize's
+//     re-materialize writes the managed block straight into the working file (writeManagedBlock IS the re-smudge),
+//     and this module refreshes the block file the shim reads so future checkouts agree;
+//   ③ unplanting must strip the block from the WORKING FILES before the config goes away, or the block
+//     residue surfaces as an uncommitted modification — the caller (dematerialize) removes the managed
+//     blocks first and only then calls removeContractFilter.
+function commonDirOf(proj) {
+    return git(['-C', proj, 'rev-parse', '--path-format=absolute', '--git-common-dir']).trim();
+}
+const filterDir = (common) => join(common, 'spexcode');
+const shimPath = (common) => join(filterDir(common), 'contract-filter.sh');
+const rootPath = (common) => join(filterDir(common), 'contract-filter-root');
+const bindingsPath = (common) => join(filterDir(common), 'contract-filter-bindings');
+const treeFilterDir = (proj) => join(treeSlotDir(proj), 'contract-filter');
+const attributesPath = (common) => join(common, 'info', 'attributes');
+// The common shim both filter directions run through. Pure shell/awk (no node boot on git's hot path), it
+// resolves the invoking checkout to that tree's payload before mirroring managed-block normalization:
+//   clean : drop the sentinel block (+ the blank line smudge printed before it) → the pristine host prose.
+//   smudge: clean first (a block already in the index can never double-inject), then append the tree payload.
+// Byte-exactness holds for text ending in exactly one newline (git's own well-formed-text shape); a pristine
+// file ending in zero or 2+ newlines is normalized to one on the first round-trip and stable after.
+const SHIM = `#!/usr/bin/env bash
+# spexcode managed-text filter (generated by spex materialize; see [[content-filter]]).
+# One common driver selects the payload belonging to the Git checkout that invoked it.
+set -u
+mode="\${1:?usage: contract-filter.sh smudge|clean <path>}"
+path="\${2:?usage: contract-filter.sh smudge|clean <path>}"
+here="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+binding="$(awk -F '\t' -v p="$path" '$1 == p { print $2 "\t" $3; exit }' "$here/contract-filter-bindings" 2>/dev/null)"
+[ -n "$binding" ] || { cat; exit 0; }
+start="\${binding%%$'\t'*}"; rest="\${binding#*$'\t'}"
+end="$rest"
+top="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+root="$(cat "$here/contract-filter-root" 2>/dev/null || true)"
+key="$(printf '%s' "$top" | sed 's#[/.]#-#g')"
+manifest="$root/trees/$key/contract-filter/manifest"
+payload="$(awk -F '\t' -v p="$path" '$1 == p { print $2; exit }' "$manifest" 2>/dev/null)"
+strip() {
+  awk -v sline="$start" -v eline="$end" 'BEGIN { n = 0 }
+    { lines[n++] = $0 }
+    END {
+      s = -1; e = -1
+      for (i = 0; i < n; i++) {
+        if (lines[i] == sline && s < 0) s = i
+        if (lines[i] == eline && s >= 0 && e < 0) e = i
+      }
+      if (s >= 0 && e >= s) {
+        a = s; while (a > 0 && lines[a-1] == "") a--
+        b = e; while (b + 1 < n && lines[b+1] == "") b++
+        j = 0
+        for (i = 0; i < n; i++) if (i < a || i > b) lines[j++] = lines[i]
+        n = j
+      }
+      for (i = 0; i < n; i++) print lines[i]
+    }'
+}
+case "$mode" in
+  clean) strip ;;
+  smudge)
+    if [ ! -r "$payload" ]; then strip; exit 0; fi
+    strip | awk -v b="$payload" -v sline="$start" -v eline="$end" 'BEGIN { n = 0 }
+      { lines[n++] = $0 }
+      END {
+        while (n > 0 && lines[n-1] == "") n--
+        for (i = 0; i < n; i++) print lines[i]
+        if (n > 0) print ""
+        print sline
+        while ((getline l < b) > 0) print l
+        print eline
+      }' ;;
+  *) echo "contract-filter.sh: unknown mode $mode" >&2; exit 1 ;;
+esac
+`;
+// edge ①: the command git runs is a tolerant wrapper — the shim path is an ARGUMENT ($0), and a missing/
+// unreadable shim degrades to `cat` (identity) instead of a per-operation fatal.
+const filterCmd = (shim, mode) => `sh -c 'test -r "$0" && exec bash "$0" ${mode} "$1" || exec cat' '${shim.replace(/'/g, `'\\''`)}' %f`;
+// plant (or refresh) the filter for the given contract files (tracked, or untracked-with-host-content —
+// pre-armed): the shim + the block content it smudges, the per-clone git config, and the attribute lines
+// binding each file to the filter. `contract` is the assembled block body (guide + surface:system).
+// settleIndexStat skips untracked entries (no index blob) by design and only runs after a real filter change.
+export function plantContractFilter(proj, payloads, bindings, changedFiles = []) {
+    const common = commonDirOf(proj);
+    mkdirSync(filterDir(common), { recursive: true });
+    let changed = writeFileIfChanged(shimPath(common), SHIM);
+    if (changed || (statSync(shimPath(common)).mode & 0o777) !== 0o755)
+        chmodSync(shimPath(common), 0o755);
+    const commands = new Map([
+        ['filter.spexcode.smudge', filterCmd(shimPath(common), 'smudge')],
+        ['filter.spexcode.clean', filterCmd(shimPath(common), 'clean')],
+    ]);
+    const configured = new Map();
+    try {
+        for (const row of git(['-C', proj, 'config', '--get-regexp', '^filter\\.spexcode\\.(smudge|clean)$']).trimEnd().split('\n')) {
+            const at = row.indexOf(' ');
+            if (at > 0)
+                configured.set(row.slice(0, at), row.slice(at + 1));
+        }
+    }
+    catch { }
+    for (const [key, command] of commands) {
+        if (configured.get(key) === command)
+            continue;
+        git(['-C', proj, 'config', key, command]);
+        changed = true;
+    }
+    changed = writeFileIfChanged(bindingsPath(common), bindings.map((b) => `${b.file}\t${b.start}\t${b.end}`).join('\n') + '\n') || changed;
+    const dir = treeFilterDir(proj);
+    mkdirSync(dir, { recursive: true });
+    const manifest = [];
+    const wanted = new Set(['manifest']);
+    for (const [i, payload] of payloads.entries()) {
+        const target = join(dir, String(i));
+        wanted.add(String(i));
+        changed = writeFileIfChanged(target, payload.content.endsWith('\n') ? payload.content : `${payload.content}\n`) || changed;
+        manifest.push(`${payload.file}\t${target}`);
+    }
+    for (const entry of readdirSync(dir)) {
+        if (!wanted.has(entry)) {
+            rmSync(join(dir, entry), { recursive: true, force: true });
+            changed = true;
+        }
+    }
+    const manifestPath = join(dir, 'manifest');
+    changed = writeFileIfChanged(manifestPath, manifest.join('\n') + (manifest.length ? '\n' : '')) || changed;
+    changed = writeFileIfChanged(rootPath(common), `${runtimeRoot(proj)}\n`) || changed;
+    // Attribute patterns are checkout-relative; the stable binding set is safe in the common git dir because
+    // the driver selects a payload from the invoking checkout's tree slot.
+    const entries = bindings.map((b) => `/${b.file} filter=spexcode`).sort().join('\n');
+    mkdirSync(join(common, 'info'), { recursive: true });
+    changed = writeManagedBlock(attributesPath(common), entries, ['# ', '']) || changed;
+    const settle = changed ? payloads.map((p) => join(proj, p.file)) : changedFiles;
+    if (settle.length)
+        settleIndexStat(proj, [...new Set(settle)]);
+    return changed;
+}
+// settle the index STAT for each file — the famous filtered-path phantom-`M`: git cannot verify a
+// clean-filtered path by stat alone (worktree size ≠ blob size by design), and `git status` reports such an
+// entry modified FOREVER without ever content-checking it (field-verified on git 2.43; `git diff` meanwhile
+// runs the filter and shows nothing; even `update-index --really-refresh` leaves it). The block-strip side of
+// a mode switch/backout leaves the same stale stat on the then-unfiltered path. `git add --renormalize`
+// re-cleans the file and refreshes the cached stat — run ONLY when the (possibly filtered) worktree already
+// EQUALS the index blob, so it is a pure stat refresh that can never stage a user's real unstaged edit (a
+// genuine edit keeps its honest `M`). Exported for dematerialize (the unplant side); plant calls it below.
+// Best-effort: an unsettled stat is cosmetic noise, never corruption.
+export function settleIndexStat(proj, files) {
+    const env = { ...process.env };
+    delete env.GIT_DIR;
+    delete env.GIT_WORK_TREE;
+    delete env.GIT_INDEX_FILE;
+    delete env.GIT_OBJECT_DIRECTORY;
+    for (const f of files) {
+        const rel = relative(proj, f);
+        try {
+            const indexBlob = git(['-C', proj, 'rev-parse', `:${rel}`]).trim();
+            const filtered = execFileSync(gitBinary(env), ['-C', proj, 'hash-object', '--path', rel, '--stdin'], { input: readFileSync(f), env, stdio: ['pipe', 'pipe', 'ignore'] }).toString().trim();
+            if (indexBlob === filtered)
+                git(['-C', proj, 'add', '--renormalize', '--', rel]);
+        }
+        catch { /* best-effort */ }
+    }
+}
+// the full inverse (edge ③ — call AFTER the managed blocks left the working files): attribute lines out,
+// config keys unset, shim + block content removed. `<common>/spexcode/` may host other spexcode data
+// (evidence blobs), so only OUR two files go, never the dir.
+export function clearContractFilterPayload(proj, files = []) {
+    try {
+        rmSync(treeFilterDir(proj), { recursive: true, force: true });
+    }
+    catch { /* inaccessible tree */ }
+    settleIndexStat(proj, files);
+}
+export function removeContractFilter(proj, files = [], final = false) {
+    let common;
+    try {
+        common = commonDirOf(proj);
+    }
+    catch {
+        return;
+    } // not a git repo → nothing was ever planted
+    clearContractFilterPayload(proj, files);
+    const anotherPayload = final ? false : (() => {
+        const rows = git(['-C', proj, 'worktree', 'list', '--porcelain', '-z']).split('\0');
+        const root = runtimeRoot(proj);
+        return rows
+            .filter((row) => row.startsWith('worktree '))
+            .map((row) => row.slice('worktree '.length))
+            .some((tree) => existsSync(join(root, 'trees', encodeProject(tree), 'contract-filter', 'manifest')));
+    })();
+    if (!final && anotherPayload)
+        return;
+    removeManagedBlock(attributesPath(common), ['# ', ''], true);
+    for (const key of ['filter.spexcode.smudge', 'filter.spexcode.clean']) {
+        try {
+            git(['-C', proj, 'config', '--unset-all', key]);
+        }
+        catch { /* not set — already clean */ }
+    }
+    for (const path of [shimPath(common), rootPath(common), bindingsPath(common)])
+        rmSync(path, { force: true });
+}
+// is the filter currently planted? (the assert-side probe tests use; cheap: one config read)
+export function contractFilterPlanted(proj) {
+    try {
+        return git(['-C', proj, 'config', 'filter.spexcode.clean']).trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}

package/node_modules/@spexcode/spec-cli/dist/dashboard-assets.d.ts

@@ -0,0 +1,6 @@
+export type DashboardArtifact = 'dist' | 'dist-public';
+export declare class DashboardAssetError extends Error {
+    constructor(message: string);
+}
+export declare function dashboardArtifactDir(artifact: DashboardArtifact): string;
+export declare function ensureDashboardArtifact(artifact: DashboardArtifact): string;

package/node_modules/@spexcode/spec-cli/dist/dashboard-assets.js

@@ -0,0 +1,50 @@
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+export class DashboardAssetError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DashboardAssetError';
+    }
+}
+const PACKAGE = '@spexcode/spec-dashboard';
+const INSTALL = `npm install ${PACKAGE}`;
+function dashboardRoot() {
+    try {
+        return dirname(createRequire(import.meta.url).resolve(`${PACKAGE}/package.json`));
+    }
+    catch {
+        throw new DashboardAssetError(`dashboard UI is not installed (${PACKAGE}). Install it with: ${INSTALL}`);
+    }
+}
+// Dashboard assets belong to the dashboard package. Resolving its manifest handles both an npm dependency
+// and a workspace link without teaching CLI code where either layout happens to live.
+export function dashboardArtifactDir(artifact) {
+    const root = dashboardRoot();
+    const dir = join(root, artifact);
+    if (existsSync(join(dir, 'index.html')))
+        return dir;
+    const repair = existsSync(join(root, 'src'))
+        ? `build the dashboard package before running this command`
+        : `reinstall ${PACKAGE}`;
+    throw new DashboardAssetError(`dashboard UI package is incomplete: missing ${artifact}/index.html at ${root}. To repair, ${repair}.`);
+}
+export function ensureDashboardArtifact(artifact) {
+    try {
+        return dashboardArtifactDir(artifact);
+    }
+    catch (error) {
+        if (!(error instanceof DashboardAssetError))
+            throw error;
+        const root = dashboardRoot();
+        if (!existsSync(join(root, 'src')))
+            throw error;
+        const script = artifact === 'dist' ? 'build' : 'build:public';
+        console.log(`[dashboard] ${artifact} is not built — running npm run ${script} in ${PACKAGE}…`);
+        const result = spawnSync('npm', ['run', script], { cwd: root, stdio: 'inherit' });
+        if (result.status === 0)
+            return dashboardArtifactDir(artifact);
+        throw new DashboardAssetError(`dashboard UI build failed for ${PACKAGE}. Repair it with: (cd ${root} && npm run ${script})`);
+    }
+}

package/node_modules/@spexcode/spec-cli/dist/doctor.d.ts

@@ -0,0 +1,9 @@
+export type HealthFinding = {
+    check: string;
+    spec: string;
+    summary: string;
+    evidence: string[];
+    repair: string;
+};
+export declare function specHealthDiagnosis(root: string): Promise<HealthFinding[]>;
+export declare function runDoctor(args: string[]): Promise<number>;