@nick848/fet 0.1.0

package/dist/tasks.js

@@ -0,0 +1,69 @@
+import { readFileSync } from "node:fs";
+/** Parse OpenSpec-style tasks.md: markdown checkboxes with leading task ids. */
+export function parseTasksMd(content) {
+    const lines = content.split(/\r?\n/);
+    const tasks = [];
+    const boxRe = /^(\s*)-\s*\[([ xX])\]\s*(.+)$/;
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i].match(boxRe);
+        if (!m)
+            continue;
+        const done = m[2].toLowerCase() === "x";
+        const rest = m[3].trim();
+        const idMatch = rest.match(/^(\d+(?:\.\d+)+)\b\s*(.*)$/);
+        const id = idMatch ? idMatch[1] : rest.split(/\s+/)[0] ?? rest;
+        const title = idMatch ? idMatch[2].trim() : rest;
+        let autoNext = false;
+        for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
+            const t = lines[j].trim();
+            if (!t)
+                continue;
+            if (/^-\s*\[/.test(lines[j]))
+                break;
+            if (/auto_next\s*:\s*true/i.test(t)) {
+                autoNext = true;
+                break;
+            }
+            if (/auto_next\s*:\s*false/i.test(t)) {
+                autoNext = false;
+                break;
+            }
+        }
+        if (/auto_next\s*:\s*true/i.test(lines[i]))
+            autoNext = true;
+        tasks.push({ id, title, done, autoNext, lineIndex: i });
+    }
+    return tasks;
+}
+export function listCompletedTaskIds(content) {
+    return parseTasksMd(content).filter((t) => t.done).map((t) => t.id);
+}
+export function firstIncompleteTask(content) {
+    for (const t of parseTasksMd(content)) {
+        if (!t.done)
+            return t;
+    }
+    return null;
+}
+export function markTaskDoneInMarkdown(content, taskId) {
+    const lines = content.split(/\r?\n/);
+    const boxRe = /^(\s*)-\s*\[([ xX])\]\s*(.+)$/;
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i].match(boxRe);
+        if (!m)
+            continue;
+        const rest = m[3].trim();
+        const idMatch = rest.match(/^(\d+(?:\.\d+)+)\b/);
+        const id = idMatch ? idMatch[1] : null;
+        if (id !== taskId)
+            continue;
+        if (m[2].toLowerCase() === "x")
+            return content;
+        lines[i] = `${m[1]}- [x] ${m[3]}`;
+        return lines.join("\n");
+    }
+    return content;
+}
+export function readTasksFile(path) {
+    return readFileSync(path, "utf8");
+}

package/dist/types.d.ts

@@ -0,0 +1,38 @@
+export interface GlobalFetState {
+    version: 1;
+    activeChangeId: string | null;
+    openChanges: string[];
+    /** Auto-run approval for validate / verify --auto (DESIGN 6.2, 14.7) */
+    autoRunApproval?: {
+        confirmedAt: string;
+        commandFingerprint: string;
+        packageManager?: string;
+    };
+}
+export interface ChangeVerifyState {
+    status: "pending" | "done";
+    mode?: "manual" | "auto";
+    completedAt?: string;
+    evidencePath?: string;
+    /** DESIGN 14.8: server clock when evidence file was checked */
+    evidenceCheckedAt?: string;
+}
+export interface TaskValidationRecord {
+    openspec?: string;
+    test?: string;
+    tsc?: string;
+    at: string;
+}
+export interface ChangeFetState {
+    version: 1;
+    changeId: string;
+    /** High-level workflow phase label */
+    currentPhase: string;
+    tasksCompleted: string[];
+    currentTaskId: string | null;
+    verify?: ChangeVerifyState;
+    /** DESIGN 5.2 / 6.1: per-task validation outcome */
+    validationResults?: Record<string, TaskValidationRecord>;
+    /** DESIGN 14.8 --strict: user-provided short audit note */
+    verifyStrictSummary?: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/validate.d.ts

@@ -0,0 +1 @@
+export declare function runValidate(cwd: string): Promise<void>;

package/dist/validate.js

@@ -0,0 +1,150 @@
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { ensureAutoRunApproval } from "./approval.js";
+import { writeFileAtomicSameDirTmp } from "./atomic-write.js";
+import { computeCommandFingerprint } from "./fingerprint.js";
+import { FET_VERSION, spawnOpenSpec } from "./openspec.js";
+import { applyInstructionsPath, tasksPath } from "./paths.js";
+import { readChangeState, readGlobalState, reconcileStates, writeChangeState, writeGlobalState, } from "./state.js";
+import { firstIncompleteTask, markTaskDoneInMarkdown, parseTasksMd } from "./tasks.js";
+function npmCmd() {
+    return process.platform === "win32" ? "npm.cmd" : "npm";
+}
+function npxCmd() {
+    return process.platform === "win32" ? "npx.cmd" : "npx";
+}
+function run(cmd, args, cwd) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, { cwd, stdio: "inherit", shell: false });
+        child.on("error", reject);
+        child.on("close", (c) => resolve(c ?? 1));
+    });
+}
+function resolveActiveChangeId(cwd) {
+    const g = readGlobalState(cwd);
+    if (g.activeChangeId)
+        return g.activeChangeId;
+    if (g.openChanges.length === 1)
+        return g.openChanges[0] ?? null;
+    return null;
+}
+export async function runValidate(cwd) {
+    let global = readGlobalState(cwd);
+    const rec = reconcileStates(cwd, global);
+    global = rec.global;
+    writeGlobalState(cwd, global);
+    const changeId = resolveActiveChangeId(cwd);
+    if (!changeId) {
+        console.error("[fet] No active change for validate.");
+        process.exitCode = 1;
+        return;
+    }
+    const fpNow = computeCommandFingerprint(cwd);
+    if (global.autoRunApproval?.commandFingerprint !== fpNow) {
+        global = { ...global, autoRunApproval: undefined };
+        writeGlobalState(cwd, global);
+    }
+    try {
+        await ensureAutoRunApproval(cwd);
+    }
+    catch (e) {
+        console.error(e instanceof Error ? e.message : e);
+        process.exitCode = 1;
+        return;
+    }
+    const code1 = await spawnOpenSpec(["validate", "--type", "change", changeId], {
+        cwd,
+        inheritStdio: true,
+    });
+    if (code1 !== 0) {
+        process.exitCode = code1;
+        return;
+    }
+    let testRan = false;
+    let testOk = true;
+    const pkgPath = join(cwd, "package.json");
+    if (existsSync(pkgPath)) {
+        const pkg = readFileSync(pkgPath, "utf8");
+        const j = JSON.parse(pkg);
+        if (j.scripts?.test) {
+            testRan = true;
+            const c = await run(npmCmd(), ["test"], cwd);
+            testOk = c === 0;
+            if (!testOk) {
+                process.exitCode = c;
+                return;
+            }
+        }
+    }
+    let tscRan = false;
+    let tscOk = true;
+    if (existsSync(join(cwd, "tsconfig.json"))) {
+        tscRan = true;
+        const c = await run(npxCmd(), ["tsc", "--noEmit"], cwd);
+        tscOk = c === 0;
+        if (!tscOk) {
+            process.exitCode = c;
+            return;
+        }
+    }
+    const tp = join(cwd, tasksPath(changeId));
+    const md = readFileSync(tp, "utf8");
+    const current = firstIncompleteTask(md);
+    if (!current) {
+        console.log("[fet] validate: no incomplete task found");
+        return;
+    }
+    const updatedMd = markTaskDoneInMarkdown(md, current.id);
+    writeFileSync(tp, updatedMd, "utf8");
+    let cs = readChangeState(cwd, changeId);
+    if (!cs)
+        return;
+    const doneIds = parseTasksMd(updatedMd)
+        .filter((t) => t.done)
+        .map((t) => t.id);
+    const next = firstIncompleteTask(updatedMd);
+    const at = new Date().toISOString();
+    const vr = { ...(cs.validationResults ?? {}) };
+    vr[current.id] = {
+        openspec: "pass",
+        test: testRan ? (testOk ? "pass" : "fail") : "skip",
+        tsc: tscRan ? (tscOk ? "pass" : "fail") : "skip",
+        at,
+    };
+    cs = {
+        ...cs,
+        tasksCompleted: doneIds,
+        currentTaskId: next?.id ?? null,
+        validationResults: vr,
+    };
+    writeChangeState(cwd, cs);
+    if (next) {
+        const front = [
+            "---",
+            `generatedAt: ${new Date().toISOString()}`,
+            `fetVersion: ${FET_VERSION}`,
+            `changeId: ${changeId}`,
+            `taskId: ${next.id}`,
+            "---",
+            "",
+        ].join("\n");
+        const body = [
+            `# Apply: ${changeId}`,
+            "",
+            `## Next task (${next.id})`,
+            "",
+            next.title,
+            "",
+            "Run `fet apply` again if you need the watcher, or continue in your AI tool. Then `fet validate` after edits.",
+            "",
+        ].join("\n");
+        writeFileAtomicSameDirTmp(join(cwd, applyInstructionsPath(changeId)), front + body);
+        if (!current.autoNext) {
+            console.log("[fet] Task marked done. auto_next is false: trigger /apply or fet apply before next edits.");
+        }
+    }
+    else {
+        console.log("[fet] All tasks validated. Proceed to fet verify.");
+    }
+}

package/dist/verify.d.ts

@@ -0,0 +1,6 @@
+export declare function runVerify(cwd: string, opts: {
+    auto?: boolean;
+    done?: boolean;
+    evidence?: string;
+    strict?: boolean;
+}): Promise<void>;

package/dist/verify.js

@@ -0,0 +1,193 @@
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import * as readline from "node:readline/promises";
+import { ensureAutoRunApproval } from "./approval.js";
+import { computeCommandFingerprint } from "./fingerprint.js";
+import { spawnOpenSpec } from "./openspec.js";
+import { verifyInstructionsPath } from "./paths.js";
+import { readChangeState, readGlobalState, reconcileStates, writeChangeState, writeGlobalState, } from "./state.js";
+const EVIDENCE_MAX_AGE_MS = 1000 * 60 * 60 * 72; // 72h
+const STRICT_SUMMARY_MAX = 240;
+function npmCmd() {
+    return process.platform === "win32" ? "npm.cmd" : "npm";
+}
+function npxCmd() {
+    return process.platform === "win32" ? "npx.cmd" : "npx";
+}
+function run(cmd, args, cwd) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, { cwd, stdio: "inherit", shell: false });
+        child.on("error", reject);
+        child.on("close", (c) => resolve(c ?? 1));
+    });
+}
+function resolveActiveChangeId(cwd) {
+    const g = readGlobalState(cwd);
+    if (g.activeChangeId)
+        return g.activeChangeId;
+    if (g.openChanges.length === 1)
+        return g.openChanges[0] ?? null;
+    return null;
+}
+function resolveEvidencePath(cwd, p) {
+    if (p.startsWith("/") || /^[a-zA-Z]:[\\/]/.test(p))
+        return p;
+    return join(cwd, p);
+}
+async function readStrictSummary() {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const raw = await rl.question(`[fet] --strict: paste a short summary of verification (max ${STRICT_SUMMARY_MAX} chars): `);
+        return raw.trim().slice(0, STRICT_SUMMARY_MAX);
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function runVerify(cwd, opts) {
+    let global = readGlobalState(cwd);
+    const rec = reconcileStates(cwd, global);
+    global = rec.global;
+    writeGlobalState(cwd, global);
+    const changeId = resolveActiveChangeId(cwd);
+    if (!changeId) {
+        console.error("[fet] No active change for verify.");
+        process.exitCode = 1;
+        return;
+    }
+    const fpNow = computeCommandFingerprint(cwd);
+    if (global.autoRunApproval?.commandFingerprint !== fpNow) {
+        global = { ...global, autoRunApproval: undefined };
+        writeGlobalState(cwd, global);
+    }
+    if (opts.done) {
+        let cs = readChangeState(cwd, changeId);
+        if (!cs) {
+            console.error("[fet] Missing change state");
+            process.exitCode = 1;
+            return;
+        }
+        let evidenceCheckedAt;
+        if (opts.evidence) {
+            const abs = resolveEvidencePath(cwd, opts.evidence);
+            if (!existsSync(abs)) {
+                console.error("[fet] evidence file not found");
+                process.exitCode = 1;
+                return;
+            }
+            const st = statSync(abs);
+            if (st.size === 0) {
+                console.error("[fet] evidence file is empty");
+                process.exitCode = 1;
+                return;
+            }
+            if (Date.now() - st.mtimeMs > EVIDENCE_MAX_AGE_MS) {
+                console.error("[fet] evidence file is older than 72h; provide a fresher log (DESIGN 14.8).");
+                process.exitCode = 1;
+                return;
+            }
+            evidenceCheckedAt = new Date().toISOString();
+        }
+        let verifyStrictSummary;
+        if (opts.strict) {
+            verifyStrictSummary = await readStrictSummary();
+            if (!verifyStrictSummary) {
+                console.error("[fet] strict mode requires a non-empty summary");
+                process.exitCode = 1;
+                return;
+            }
+        }
+        cs = {
+            ...cs,
+            verify: {
+                status: "done",
+                mode: "manual",
+                completedAt: new Date().toISOString(),
+                evidencePath: opts.evidence,
+                evidenceCheckedAt,
+            },
+            verifyStrictSummary,
+        };
+        writeChangeState(cwd, cs);
+        console.log("[fet] Recorded verify --done (honest trust model, DESIGN 14.8). Not a cryptographic audit trail.");
+        return;
+    }
+    if (opts.auto) {
+        try {
+            await ensureAutoRunApproval(cwd);
+        }
+        catch (e) {
+            console.error(e instanceof Error ? e.message : e);
+            process.exitCode = 1;
+            return;
+        }
+        // Current OpenSpec CLI has `validate`, not top-level `verify` (DESIGN 7.1 alias).
+        const c1 = await spawnOpenSpec(["validate", "--type", "change", changeId], { cwd, inheritStdio: true });
+        if (c1 !== 0) {
+            process.exitCode = c1;
+            return;
+        }
+        const pkgPath = join(cwd, "package.json");
+        if (existsSync(pkgPath)) {
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+            if (pkg.scripts?.lint) {
+                const c = await run(npmCmd(), ["run", "lint"], cwd);
+                if (c !== 0) {
+                    process.exitCode = c;
+                    return;
+                }
+            }
+        }
+        if (existsSync(join(cwd, "tsconfig.json"))) {
+            const c = await run(npxCmd(), ["tsc", "--noEmit"], cwd);
+            if (c !== 0) {
+                process.exitCode = c;
+                return;
+            }
+        }
+        if (existsSync(join(cwd, "package.json"))) {
+            const pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8"));
+            if (pkg.scripts?.test) {
+                const c = await run(npmCmd(), ["test"], cwd);
+                if (c !== 0) {
+                    process.exitCode = c;
+                    return;
+                }
+            }
+        }
+        let cs = readChangeState(cwd, changeId);
+        if (!cs)
+            return;
+        cs = {
+            ...cs,
+            verify: { status: "done", mode: "auto", completedAt: new Date().toISOString() },
+        };
+        writeChangeState(cwd, cs);
+        console.log("[fet] verify --auto completed (spec step: openspec validate).");
+        return;
+    }
+    const txt = [
+        `Verify checklist for change: ${changeId}`,
+        "",
+        "1) Run: openspec validate (via `fet validate` or manually)",
+        "2) Run project tests / lint as required by your team",
+        "",
+        "When finished, run:",
+        "",
+        "  fet verify --done",
+        "",
+        "Optional (DESIGN 14.8):",
+        "  fet verify --done --evidence path/to/log.txt   # file must exist, be non-empty, mtime < 72h",
+        "  fet verify --done --strict                     # prompts for a short audit note",
+        "",
+    ].join("\n");
+    const p = join(cwd, verifyInstructionsPath(changeId));
+    writeFileSync(p, txt, "utf8");
+    let cs = readChangeState(cwd, changeId);
+    if (!cs)
+        return;
+    cs = { ...cs, verify: { status: "pending", mode: "manual" } };
+    writeChangeState(cwd, cs);
+    console.log(`[fet] Wrote ${verifyInstructionsPath(changeId)}`);
+}

package/dist/watch-paths.d.ts

@@ -0,0 +1,2 @@
+/** DESIGN 6.3: default + fet.watch_directories + monorepo packages */
+export declare function resolveWatchRoots(cwd: string): string[];

package/dist/watch-paths.js

@@ -0,0 +1,70 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { CONFIG_FILE } from "./paths.js";
+/** DESIGN 6.3: default + fet.watch_directories + monorepo packages */
+export function resolveWatchRoots(cwd) {
+    const seen = new Set();
+    const add = (p) => {
+        if (existsSync(p)) {
+            try {
+                if (statSync(p).isDirectory())
+                    seen.add(p);
+            }
+            catch {
+                /* skip */
+            }
+        }
+    };
+    for (const rel of ["src", "tests", "test", "lib"]) {
+        add(join(cwd, rel));
+    }
+    const cfgPath = join(cwd, CONFIG_FILE);
+    if (existsSync(cfgPath)) {
+        try {
+            const doc = parseYaml(readFileSync(cfgPath, "utf8"));
+            const dirs = doc?.fet?.watch_directories;
+            if (Array.isArray(dirs)) {
+                for (const d of dirs) {
+                    if (typeof d === "string" && d.trim())
+                        add(join(cwd, d.trim()));
+                }
+            }
+        }
+        catch {
+            /* invalid yaml */
+        }
+    }
+    const pkgPath = join(cwd, "package.json");
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+            const patterns = Array.isArray(pkg.workspaces)
+                ? pkg.workspaces
+                : (pkg.workspaces?.packages ?? []);
+            for (const pat of patterns) {
+                if (typeof pat !== "string")
+                    continue;
+                if (pat.includes("*")) {
+                    const packagesDir = join(cwd, "packages");
+                    if (existsSync(packagesDir)) {
+                        for (const name of readdirSync(packagesDir)) {
+                            add(join(packagesDir, name, "src"));
+                            add(join(packagesDir, name, "tests"));
+                        }
+                    }
+                }
+                else {
+                    add(join(cwd, pat, "src"));
+                    add(join(cwd, pat, "tests"));
+                }
+            }
+        }
+        catch {
+            /* skip */
+        }
+    }
+    if (seen.size === 0)
+        add(cwd);
+    return [...seen];
+}

package/dist/workflow-hints.d.ts

@@ -0,0 +1,2 @@
+/** DESIGN 4.2 / 8.2: post-hook style hints after successful workflow commands */
+export declare function printWorkflowHint(kind: string): void;

package/dist/workflow-hints.js

@@ -0,0 +1,9 @@
+/** DESIGN 4.2 / 8.2: post-hook style hints after successful workflow commands */
+export function printWorkflowHint(kind) {
+    if (kind === "continue" || kind === "ff") {
+        console.log("[fet] Review generated artifacts under openspec/changes/<id>/, then run `fet continue` or `fet ff` as needed.");
+    }
+    else if (kind === "onboard") {
+        console.log("[fet] To enable FET + OpenSpec in this repo, run: `fet init`");
+    }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@nick848/fet",
+  "version": "0.1.0",
+  "description": "Frontend workflow orchestration around OpenSpec (FET)",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "fet": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "fet",
+    "openspec",
+    "cli",
+    "workflow",
+    "cursor",
+    "opencode",
+    "spec-driven"
+  ],
+  "author": "nick848",
+  "license": "MIT",
+  "dependencies": {
+    "chokidar": "^4.0.3",
+    "commander": "^12.1.0",
+    "handlebars": "^4.7.8",
+    "json5": "^2.2.3",
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.5",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5"
+  }
+}