strikethroo 3.0.2 → 3.2.0

package/README.md

@@ -3,8 +3,6 @@
 [![npm version](https://img.shields.io/npm/v/strikethroo.svg)](https://www.npmjs.com/package/strikethroo)
 [![License](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 
-![Dashboard](./docs/img/dashboard.svg)
-
 **Strikethroo: extensible AI-powered plan and task management with customizable workflows and structured development processes.**
 
 Transform complex AI prompts into organized, executable workflows through customizable hooks, templates, and progressive refinement. Works seamlessly within your existing AI subscriptions for Claude Code, Gemini CLI, and Open Code.
@@ -25,6 +23,24 @@ The skills give your assistant the planning, decomposition, and execution workfl
 
 The CLI's `init` emits the shared workspace plus harness-specific agents (e.g., `.claude/agents/` for Claude). Other harnesses rely entirely on the installed skills.
 
+## 🌐 Serve the Workspace
+
+Run a local web app over an initialized `.ai/strikethroo/` workspace:
+
+```bash
+npx strikethroo serve
+```
+
+`serve` boots a dependency-light Node server that hosts the prebuilt single-page app as static files, exposes a read-only JSON API over the workspace model, and streams a coalesced `changed` event over Server-Sent Events whenever the workspace mutates on disk. Run it from inside an initialized workspace; if none is found it prints guidance to run `init` and exits without binding.
+
+The viewer is read-only **except for one permitted mutation: the archive action.** A plan whose tasks are all complete (derived state `done`) shows an **Archive** control; confirming it issues `POST /api/plans/:id/archive`, which moves that plan's directory from `plans/` to `archive/`. It is strictly a directory move — no files are deleted or edited, and only `done` plans are accepted. This is the manual escape hatch for plans that are done but not yet archived; it does **not** replace the automatic archival the `st-execute-blueprint` skill performs on successful completion.
+
+Flags:
+
+- `--port <n>` — port to bind (default `4317`).
+- `--no-open` — do not open the browser on start.
+- `--workspace <path>` — override workspace root discovery.
+
 ## ✨ Key Benefits
 
 - **🔧 Fully Customizable**: Tailor hooks, templates, and workflows to your project's specific needs

package/dist/cli.js

@@ -9,6 +9,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
 const index_1 = require("./index");
+const root_1 = require("./serve/root");
+const server_1 = require("./serve/server");
 const program = new commander_1.Command();
 program.name('strikethroo').version('0.1.0').description('AI-powered task management CLI tool');
 program
@@ -34,6 +36,32 @@ program
         process.exit(1);
     }
 });
+program
+    .command('serve')
+    .description('Serve the workspace as a local web app (static SPA, JSON API, SSE change stream)')
+    .option('--port <n>', 'port to bind', '4317')
+    .option('--no-open', 'do not open the browser on start')
+    .option('--workspace <path>', 'override workspace root discovery')
+    .action(async (opts) => {
+    try {
+        const resolved = (0, root_1.resolveWorkspaceRoot)({ workspace: opts.workspace });
+        if ((0, root_1.isResolveError)(resolved)) {
+            console.error(resolved.error);
+            process.exit(1);
+        }
+        const handle = await (0, server_1.startServer)({
+            root: resolved.root,
+            port: Number(opts.port),
+            open: opts.open,
+            assetsDir: (0, server_1.defaultAssetsDir)(),
+        });
+        console.log(`Serving ${handle.url}`);
+    }
+    catch (error) {
+        console.error(`Failed to start serve: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    }
+});
 // Error handling for unknown commands
 program.on('command:*', async (operands) => {
     console.error(`Unknown command: ${operands[0]}`);

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;AACA;;;;;GAKG;;AAEH,yCAAoC;AACpC,mCAA+B;AAG/B,MAAM,OAAO,GAAG,IAAI,mBAAO,EAAE,CAAC;AAE9B,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,WAAW,CAAC,qCAAqC,CAAC,CAAC;AAEhG,OAAO;KACJ,OAAO,CAAC,MAAM,CAAC;KACf,WAAW,CAAC,sCAAsC,CAAC;KACnD,cAAc,CACb,qBAAqB,EACrB,6FAA6F,CAC9F;KACA,MAAM,CACL,gCAAgC,EAChC,uEAAuE,CACxE;KACA,MAAM,CAAC,SAAS,EAAE,6CAA6C,CAAC;KAChE,MAAM,CAAC,KAAK,EAAE,OAAoB,EAAE,EAAE;IACrC,IAAI,CAAC;QACH,2BAA2B;QAC3B,MAAM,MAAM,GAAG,MAAM,IAAA,YAAI,EAAC,OAAO,CAAC,CAAC;QAEnC,6CAA6C;QAC7C,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,qBAAqB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC7F,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,sCAAsC;AACtC,OAAO,CAAC,EAAE,CAAC,WAAW,EAAE,KAAK,EAAC,QAAQ,EAAC,EAAE;IACvC,OAAO,CAAC,KAAK,CAAC,oBAAoB,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACjD,OAAO,CAAC,GAAG,CAAC,sCAAsC,CAAC,CAAC;IACpD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC;AAEH,+BAA+B;AAC/B,OAAO,CAAC,KAAK,EAAE,CAAC;AAEhB,sCAAsC;AACtC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAClC,OAAO,CAAC,UAAU,EAAE,CAAC;IACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/serve/archive.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Archive operation for `npx strikethroo serve`.
+ *
+ * The serve web app is a read-only viewer over `.ai/strikethroo/` with exactly
+ * one sanctioned mutation: moving a plan that has reached the derived `done`
+ * state from `plans/NN--slug/` to `archive/NN--slug/`. This module is that
+ * mutation's authoritative guard — a single, HTTP-free function the route
+ * handler and the tests both call.
+ *
+ * It validates three preconditions, in order — the plan exists, currently lives
+ * under `plans/` (not already archived), and is `done` per the derived state in
+ * `workspace-model.ts` — then performs a single atomic `fs.rename` of the whole
+ * plan directory. It never deletes files, never edits file contents, and never
+ * falls back to a non-atomic copy-then-delete. Expected precondition failures
+ * are returned as a typed result, not thrown; only an unexpected filesystem
+ * error surfaces as the `fs-error` variant. Node built-ins only.
+ */
+import { PlanDetail } from './workspace-model';
+/**
+ * Outcome of an {@link archivePlan} call. A discriminated union mirroring the
+ * serve layer's existing result convention (see `self-review.ts`): callers map
+ * `reason` to HTTP status codes without re-deriving anything.
+ */
+export type ArchiveResult = {
+    ok: true;
+    plan: PlanDetail;
+} | {
+    ok: false;
+    reason: 'not-found' | 'already-archived' | 'not-done' | 'destination-exists' | 'fs-error';
+    message: string;
+};
+/**
+ * Validates the archive preconditions for plan `planId` under `root` (the
+ * absolute `.ai/strikethroo` directory) and, if they pass, atomically renames
+ * its directory from `plans/` into `archive/`, returning the refreshed model.
+ *
+ * On any precondition failure it performs zero filesystem changes and returns a
+ * typed failure with an actionable message. The only write it performs beyond
+ * the rename is creating the `archive/` directory if it does not yet exist,
+ * which is required for the rename's destination parent to resolve.
+ */
+export declare const archivePlan: (root: string, planId: number) => Promise<ArchiveResult>;
+//# sourceMappingURL=archive.d.ts.map

package/dist/serve/archive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../src/serve/archive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,EAAiB,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE9D;;;;GAIG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC9B;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,WAAW,GAAG,kBAAkB,GAAG,UAAU,GAAG,oBAAoB,GAAG,UAAU,CAAC;IAC1F,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEN;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GAAU,MAAM,MAAM,EAAE,QAAQ,MAAM,KAAG,OAAO,CAAC,aAAa,CA6DrF,CAAC"}

package/dist/serve/archive.js

@@ -0,0 +1,124 @@
+"use strict";
+/**
+ * Archive operation for `npx strikethroo serve`.
+ *
+ * The serve web app is a read-only viewer over `.ai/strikethroo/` with exactly
+ * one sanctioned mutation: moving a plan that has reached the derived `done`
+ * state from `plans/NN--slug/` to `archive/NN--slug/`. This module is that
+ * mutation's authoritative guard — a single, HTTP-free function the route
+ * handler and the tests both call.
+ *
+ * It validates three preconditions, in order — the plan exists, currently lives
+ * under `plans/` (not already archived), and is `done` per the derived state in
+ * `workspace-model.ts` — then performs a single atomic `fs.rename` of the whole
+ * plan directory. It never deletes files, never edits file contents, and never
+ * falls back to a non-atomic copy-then-delete. Expected precondition failures
+ * are returned as a typed result, not thrown; only an unexpected filesystem
+ * error surfaces as the `fs-error` variant. Node built-ins only.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.archivePlan = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const workspace_model_1 = require("./workspace-model");
+/**
+ * Validates the archive preconditions for plan `planId` under `root` (the
+ * absolute `.ai/strikethroo` directory) and, if they pass, atomically renames
+ * its directory from `plans/` into `archive/`, returning the refreshed model.
+ *
+ * On any precondition failure it performs zero filesystem changes and returns a
+ * typed failure with an actionable message. The only write it performs beyond
+ * the rename is creating the `archive/` directory if it does not yet exist,
+ * which is required for the rename's destination parent to resolve.
+ */
+const archivePlan = async (root, planId) => {
+    const detail = (0, workspace_model_1.getPlanDetail)(root, planId);
+    if (!detail) {
+        return {
+            ok: false,
+            reason: 'not-found',
+            message: `Plan ${planId} was not found.`,
+        };
+    }
+    if (detail.archived) {
+        return {
+            ok: false,
+            reason: 'already-archived',
+            message: `Plan ${planId} is already archived.`,
+        };
+    }
+    if (detail.state !== 'done') {
+        return {
+            ok: false,
+            reason: 'not-done',
+            message: `Plan ${planId} is not in the done state and cannot be archived.`,
+        };
+    }
+    const src = detail.dir;
+    const dest = path.join(root, 'archive', detail.name);
+    if (fs.existsSync(dest)) {
+        return {
+            ok: false,
+            reason: 'destination-exists',
+            message: `Plan ${planId} cannot be archived: a directory already exists at its archive location.`,
+        };
+    }
+    try {
+        // The destination's parent (`archive/`) must exist for the rename to land.
+        // Creating it is benign and never touches plan contents.
+        await fs.promises.mkdir(path.join(root, 'archive'), { recursive: true });
+        await fs.promises.rename(src, dest);
+    }
+    catch {
+        return {
+            ok: false,
+            reason: 'fs-error',
+            message: `Plan ${planId} could not be archived due to a filesystem error.`,
+        };
+    }
+    // Re-resolve so the returned model reflects the new archive/ location.
+    const moved = (0, workspace_model_1.getPlanDetail)(root, planId);
+    if (!moved) {
+        return {
+            ok: false,
+            reason: 'fs-error',
+            message: `Plan ${planId} was moved but could not be re-read.`,
+        };
+    }
+    return { ok: true, plan: moved };
+};
+exports.archivePlan = archivePlan;
+//# sourceMappingURL=archive.js.map

package/dist/serve/archive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.js","sourceRoot":"","sources":["../../src/serve/archive.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,uCAAyB;AACzB,2CAA6B;AAC7B,uDAA8D;AAe9D;;;;;;;;;GASG;AACI,MAAM,WAAW,GAAG,KAAK,EAAE,IAAY,EAAE,MAAc,EAA0B,EAAE;IACxF,MAAM,MAAM,GAAG,IAAA,+BAAa,EAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,WAAW;YACnB,OAAO,EAAE,QAAQ,MAAM,iBAAiB;SACzC,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACpB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,kBAAkB;YAC1B,OAAO,EAAE,QAAQ,MAAM,uBAAuB;SAC/C,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC;QAC5B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,UAAU;YAClB,OAAO,EAAE,QAAQ,MAAM,mDAAmD;SAC3E,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC;IACvB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IAErD,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,oBAAoB;YAC5B,OAAO,EAAE,QAAQ,MAAM,0EAA0E;SAClG,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,2EAA2E;QAC3E,yDAAyD;QACzD,MAAM,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACzE,MAAM,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,UAAU;YAClB,OAAO,EAAE,QAAQ,MAAM,mDAAmD;SAC3E,CAAC;IACJ,CAAC;IAED,uEAAuE;IACvE,MAAM,KAAK,GAAG,IAAA,+BAAa,EAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC1C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,UAAU;YAClB,OAAO,EAAE,QAAQ,MAAM,sCAAsC;SAC9D,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACnC,CAAC,CAAC;AA7DW,QAAA,WAAW,eA6DtB"}

package/dist/serve/derivation.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Per-plan derivation layer for the serve data layer.
+ *
+ * Scans a plan directory's `tasks/*.md` into structured task records, computes
+ * the derived plan lifecycle state (`drafted` -> `ready` -> `doing` -> `done`)
+ * with done/total counts, and resolves execution phases (from a blueprint
+ * document when present, otherwise inferred from task `group` + `dependencies`).
+ *
+ * Everything is synchronous and read-only: file reads only, no watches, no
+ * network, no writes.
+ */
+import { type MarkdownSection } from './markdown';
+/** A single task parsed from a plan's `tasks/` directory. */
+export interface Task {
+    id: number | undefined;
+    /** Task title (first `# ` heading), falling back to the filename. */
+    name: string;
+    group: string | undefined;
+    dependencies: number[];
+    status: string | undefined;
+    skills: string[];
+    /** Source filename (basename). */
+    file: string;
+    /** Raw markdown body after frontmatter. */
+    body: string;
+    /** Ordered named `##` sections of the body (via `sectionBody`, mirrors
+     * `PlanDetail.sections`). Additive to `body`, which is retained. */
+    sections: MarkdownSection[];
+}
+/** Derived lifecycle state of a plan. */
+export type PlanState = 'drafted' | 'ready' | 'doing' | 'done';
+/** Derived state plus done/total counts. */
+export interface DerivedState {
+    state: PlanState;
+    done: number;
+    total: number;
+}
+/** An execution phase: an ordered group of task ids that run together. */
+export interface Phase {
+    /** 1-based phase index. */
+    index: number;
+    /** Optional descriptive name (from a blueprint doc). */
+    name?: string;
+    /** Task ids scheduled in this phase. */
+    taskIds: number[];
+    /** True when the phase holds more than one task. */
+    parallel: boolean;
+}
+/** Reads a plan directory's `tasks/*.md` into structured records. Missing dir -> []. */
+export declare const scanTasks: (planDir: string) => Task[];
+/**
+ * Computes the derived plan state and counts. Never throws on unknown statuses.
+ *
+ * - empty list -> `drafted`
+ * - tasks present, none started or done -> `ready`
+ * - all done -> `done`
+ * - otherwise -> `doing`
+ */
+export declare const deriveState: (tasks: Task[]) => DerivedState;
+/**
+ * Parses phases from an "## Execution Blueprint" section if the plan body
+ * contains one. Returns undefined when no blueprint section is present.
+ */
+export declare const parseBlueprintPhases: (planBody: string) => Phase[] | undefined;
+/**
+ * Infers phases from tasks by grouping on satisfied dependencies. Tasks whose
+ * dependencies are all already emitted (or absent from the task set) form a
+ * phase; dependents fall into later phases. Best-effort and cycle-safe: if no
+ * progress is made, the remaining tasks are emitted as a final phase rather
+ * than looping forever. Never throws.
+ */
+export declare const inferPhases: (tasks: Task[]) => Phase[];
+/**
+ * Resolves a plan's phases: parses a blueprint document's phase list when the
+ * plan body contains one, otherwise infers phases from task dependencies.
+ */
+export declare const resolvePhases: (planBody: string, tasks: Task[]) => Phase[];
+//# sourceMappingURL=derivation.d.ts.map

package/dist/serve/derivation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derivation.d.ts","sourceRoot":"","sources":["../../src/serve/derivation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EAKL,KAAK,eAAe,EACrB,MAAM,YAAY,CAAC;AAEpB,6DAA6D;AAC7D,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;IACvB,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb;wEACoE;IACpE,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B;AAED,yCAAyC;AACzC,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;AAE/D,4CAA4C;AAC5C,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,0EAA0E;AAC1E,MAAM,WAAW,KAAK;IACpB,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,oDAAoD;IACpD,QAAQ,EAAE,OAAO,CAAC;CACnB;AAKD,wFAAwF;AACxF,eAAO,MAAM,SAAS,GAAI,SAAS,MAAM,KAAG,IAAI,EAuC/C,CAAC;AASF;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,IAAI,EAAE,KAAG,YA4B3C,CAAC;AAMF;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAAI,UAAU,MAAM,KAAG,KAAK,EAAE,GAAG,SA6CjE,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,IAAI,EAAE,KAAG,KAAK,EA0BhD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAI,UAAU,MAAM,EAAE,OAAO,IAAI,EAAE,KAAG,KAAK,EAIpE,CAAC"}

package/dist/serve/derivation.js

@@ -0,0 +1,237 @@
+"use strict";
+/**
+ * Per-plan derivation layer for the serve data layer.
+ *
+ * Scans a plan directory's `tasks/*.md` into structured task records, computes
+ * the derived plan lifecycle state (`drafted` -> `ready` -> `doing` -> `done`)
+ * with done/total counts, and resolves execution phases (from a blueprint
+ * document when present, otherwise inferred from task `group` + `dependencies`).
+ *
+ * Everything is synchronous and read-only: file reads only, no watches, no
+ * network, no writes.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvePhases = exports.inferPhases = exports.parseBlueprintPhases = exports.deriveState = exports.scanTasks = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const markdown_1 = require("./markdown");
+const STATUS_DONE = 'completed';
+const STATUS_NOT_STARTED = 'pending';
+/** Reads a plan directory's `tasks/*.md` into structured records. Missing dir -> []. */
+const scanTasks = (planDir) => {
+    const tasksDir = path.join(planDir, 'tasks');
+    let entries;
+    try {
+        entries = fs.readdirSync(tasksDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter(e => e.isFile() && e.name.endsWith('.md'))
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .flatMap(e => {
+        const filePath = path.join(tasksDir, e.name);
+        let content;
+        try {
+            content = fs.readFileSync(filePath, 'utf8');
+        }
+        catch {
+            return [];
+        }
+        const fm = (0, markdown_1.parseFrontmatter)(content);
+        const body = (0, markdown_1.extractBody)(content);
+        const dependencies = fm.dependencies
+            .map(d => (typeof d === 'number' ? d : parseInt(d, 10)))
+            .filter((d) => !Number.isNaN(d));
+        return [
+            {
+                id: fm.id,
+                name: (0, markdown_1.extractTitle)(body) ?? e.name.replace(/\.md$/, ''),
+                group: fm.group,
+                dependencies,
+                status: fm.status,
+                skills: fm.skills,
+                file: e.name,
+                body,
+                sections: (0, markdown_1.sectionBody)(body).sections,
+            },
+        ];
+    });
+};
+exports.scanTasks = scanTasks;
+/** Classifies a task status. Unknown/in-progress values count as "started". */
+const classify = (status) => {
+    if (status === STATUS_DONE)
+        return 'done';
+    if (status === STATUS_NOT_STARTED)
+        return 'notStarted';
+    return 'started';
+};
+/**
+ * Computes the derived plan state and counts. Never throws on unknown statuses.
+ *
+ * - empty list -> `drafted`
+ * - tasks present, none started or done -> `ready`
+ * - all done -> `done`
+ * - otherwise -> `doing`
+ */
+const deriveState = (tasks) => {
+    const total = tasks.length;
+    if (total === 0) {
+        return { state: 'drafted', done: 0, total: 0 };
+    }
+    let done = 0;
+    let started = 0;
+    for (const task of tasks) {
+        const klass = classify(task.status);
+        if (klass === 'done') {
+            done += 1;
+            started += 1;
+        }
+        else if (klass === 'started') {
+            started += 1;
+        }
+    }
+    let state;
+    if (done === total) {
+        state = 'done';
+    }
+    else if (started === 0) {
+        state = 'ready';
+    }
+    else {
+        state = 'doing';
+    }
+    return { state, done, total };
+};
+exports.deriveState = deriveState;
+const BLUEPRINT_SECTION_RE = /^##[ \t]+Execution Blueprint[ \t]*$/m;
+const PHASE_HEADING_RE = /^###[ \t]+(?:✅[ \t]*)?Phase[ \t]+(\d+)[ \t]*:?[ \t]*(.*?)[ \t]*$/gm;
+const TASK_REF_RE = /Task[ \t]+0*(\d+)/i;
+/**
+ * Parses phases from an "## Execution Blueprint" section if the plan body
+ * contains one. Returns undefined when no blueprint section is present.
+ */
+const parseBlueprintPhases = (planBody) => {
+    const sectionMatch = planBody.match(BLUEPRINT_SECTION_RE);
+    if (!sectionMatch || sectionMatch.index === undefined)
+        return undefined;
+    const blueprint = planBody.slice(sectionMatch.index);
+    const headings = [];
+    PHASE_HEADING_RE.lastIndex = 0;
+    let m;
+    while ((m = PHASE_HEADING_RE.exec(blueprint)) !== null) {
+        headings.push({
+            index: m.index,
+            afterHeading: m.index + m[0].length,
+            name: (m[2] ?? '').trim(),
+        });
+    }
+    if (headings.length === 0)
+        return undefined;
+    const phases = [];
+    for (let i = 0; i < headings.length; i++) {
+        const current = headings[i];
+        const next = headings[i + 1];
+        const end = next ? next.index : blueprint.length;
+        const segment = blueprint.slice(current.afterHeading, end);
+        const taskIds = [];
+        for (const line of segment.split(/\r?\n/)) {
+            const trimmed = line.trim();
+            // Only consider bulleted task references to avoid matching prose.
+            if (!trimmed.startsWith('-') && !trimmed.startsWith('*'))
+                continue;
+            const ref = trimmed.match(TASK_REF_RE);
+            if (ref && ref[1] !== undefined) {
+                const id = parseInt(ref[1], 10);
+                if (!Number.isNaN(id) && !taskIds.includes(id))
+                    taskIds.push(id);
+            }
+        }
+        phases.push({
+            index: i + 1,
+            name: current.name.length > 0 ? current.name : undefined,
+            taskIds,
+            parallel: taskIds.length > 1,
+        });
+    }
+    return phases;
+};
+exports.parseBlueprintPhases = parseBlueprintPhases;
+/**
+ * Infers phases from tasks by grouping on satisfied dependencies. Tasks whose
+ * dependencies are all already emitted (or absent from the task set) form a
+ * phase; dependents fall into later phases. Best-effort and cycle-safe: if no
+ * progress is made, the remaining tasks are emitted as a final phase rather
+ * than looping forever. Never throws.
+ */
+const inferPhases = (tasks) => {
+    const withIds = tasks.filter((t) => typeof t.id === 'number');
+    if (withIds.length === 0)
+        return [];
+    const idSet = new Set(withIds.map(t => t.id));
+    const emitted = new Set();
+    const phases = [];
+    let remaining = [...withIds];
+    while (remaining.length > 0) {
+        const ready = remaining.filter(t => t.dependencies.every(dep => !idSet.has(dep) || emitted.has(dep)));
+        const batch = ready.length > 0 ? ready : remaining; // no progress -> emit the rest
+        const taskIds = batch.map(t => t.id);
+        phases.push({
+            index: phases.length + 1,
+            taskIds,
+            parallel: taskIds.length > 1,
+        });
+        for (const id of taskIds)
+            emitted.add(id);
+        remaining = remaining.filter(t => !emitted.has(t.id));
+    }
+    return phases;
+};
+exports.inferPhases = inferPhases;
+/**
+ * Resolves a plan's phases: parses a blueprint document's phase list when the
+ * plan body contains one, otherwise infers phases from task dependencies.
+ */
+const resolvePhases = (planBody, tasks) => {
+    const fromBlueprint = (0, exports.parseBlueprintPhases)(planBody);
+    if (fromBlueprint && fromBlueprint.length > 0)
+        return fromBlueprint;
+    return (0, exports.inferPhases)(tasks);
+};
+exports.resolvePhases = resolvePhases;
+//# sourceMappingURL=derivation.js.map

package/dist/serve/derivation.js.map

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

package/dist/serve/events.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Server-Sent Events change stream for `npx strikethroo serve`.
+ *
+ * Provides `GET /api/events`: a `text/event-stream` that broadcasts a single
+ * coalesced `changed` ping whenever the workspace mutates on disk. The event
+ * carries no diff payload — clients refetch the affected API data (the browser
+ * consumer is a later plan).
+ *
+ * Exposes an {@link EventsHub} that owns the connected-client set and the
+ * workspace watcher, plus an `ApiHandler` the server registers so this module
+ * stays decoupled from routing. Connections are cleaned up on disconnect so no
+ * listeners or sockets leak. Node built-ins only.
+ */
+import * as http from 'http';
+/**
+ * Owns the SSE client set and the workspace watcher. One hub per server. Start
+ * the watcher with {@link start} after the server is listening; release it with
+ * {@link close} when the server closes.
+ */
+export declare class EventsHub {
+    private readonly workspaceDir;
+    private readonly debounceMs?;
+    private readonly clients;
+    private watcher;
+    constructor(workspaceDir: string, debounceMs?: number | undefined);
+    /** Begins watching the workspace; coalesced changes broadcast to all clients. */
+    start(): void;
+    /** Stops the watcher and ends every open client connection. */
+    close(): void;
+    /** Number of currently connected SSE clients (used by tests). */
+    get clientCount(): number;
+    /** Sends a single coalesced `changed` event to every connected client. */
+    private broadcast;
+    /** Attaches an SSE response: writes headers, registers cleanup on close. */
+    handleConnection(req: http.IncomingMessage, res: http.ServerResponse): void;
+    /** An {@link ApiHandler} for `GET /api/events`; returns false otherwise. */
+    apiHandler: (req: http.IncomingMessage, res: http.ServerResponse, ctx: {
+        pathname: string;
+    }) => boolean;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/serve/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/serve/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAM7B;;;;GAIG;AACH,qBAAa,SAAS;IAKlB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;IAL9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,OAAO,CAAiC;gBAG7B,YAAY,EAAE,MAAM,EACpB,UAAU,CAAC,EAAE,MAAM,YAAA;IAGtC,iFAAiF;IACjF,KAAK,IAAI,IAAI;IASb,+DAA+D;IAC/D,KAAK,IAAI,IAAI;IAWb,iEAAiE;IACjE,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,0EAA0E;IAC1E,OAAO,CAAC,SAAS;IAMjB,4EAA4E;IAC5E,gBAAgB,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,GAAG,EAAE,IAAI,CAAC,cAAc,GAAG,IAAI;IAyB3E,4EAA4E;IAC5E,UAAU,GACR,KAAK,IAAI,CAAC,eAAe,EACzB,KAAK,IAAI,CAAC,cAAc,EACxB,KAAK;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,KACxB,OAAO,CAMR;CACH"}