@selvakumaresra/specship 0.1.3 → 0.3.0

package/dist/server/routes/spec.js

@@ -0,0 +1,265 @@
+/**
+ * Spec layer routes — list / fetch / link assert / link verify / drift queue.
+ * Plus the v0.2 write endpoints: PUT /api/spec/:id and POST /api/specs,
+ * which let the dashboard's Monaco editor save spec edits back to disk.
+ *
+ * Every route is project-scoped via `?project=<slug>` (falls back to the
+ * boot-time primary). Returns 409 / `no_project` when neither is selectable.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * Resolve a project-relative path to an absolute path under the project
+ * root, refusing anything that escapes the root (path-traversal guard).
+ * Returns null when the resolved path is outside the project — caller
+ * surfaces 400 in that case.
+ */
+function safeProjectPath(projectRoot, relPath) {
+    // Strip leading slashes so absolute paths in user input don't blow past
+    // path.resolve's "drop earlier components" behavior.
+    const cleaned = relPath.replace(/^[/\\]+/, '');
+    const abs = path.resolve(projectRoot, cleaned);
+    const rootResolved = path.resolve(projectRoot);
+    const rel = path.relative(rootResolved, abs);
+    if (rel.startsWith('..') || path.isAbsolute(rel))
+        return null;
+    return abs;
+}
+/**
+ * Atomic file write: tmp + rename. Mirrors `atomicWriteFileSync` in
+ * `src/installer/targets/shared.ts` — kept local here to avoid the
+ * @selvakumaresra/specship deep-import dance for a 10-line helper.
+ */
+function atomicWriteFile(targetPath, content) {
+    const dir = path.dirname(targetPath);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmp = `${targetPath}.tmp.${process.pid}.${Date.now()}`;
+    fs.writeFileSync(tmp, content, 'utf-8');
+    fs.renameSync(tmp, targetPath);
+}
+async function resolveCg(app, req, reply) {
+    const cg = await app.activeCg(req);
+    if (!cg) {
+        reply.code(409).send({ error: 'no project selected', code: 'no_project' });
+        return null;
+    }
+    return cg;
+}
+export async function registerSpecRoutes(app) {
+    app.get('/api/specs', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const docs = cg.getSpecQueries().getAllSpecs();
+        return { specs: docs };
+    });
+    app.get('/api/spec/:id', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const sq = cg.getSpecQueries();
+        const spec = sq.getSpecById(req.params.id);
+        if (!spec)
+            return reply.code(404).send({ error: 'spec not found' });
+        const parent = spec.parentId ? sq.getSpecById(spec.parentId) : null;
+        const children = sq.getSpecsByParent(spec.id);
+        const siblings = parent ? sq.getSpecsByParent(parent.id).filter((s) => s.id !== spec.id) : [];
+        const links = sq.getLinksBySpec(spec.id);
+        // Read the raw source file so the dashboard's Monaco editor can edit
+        // the whole document, not just the DB-parsed body fragment for this
+        // requirement. The `spec.body` field stores per-section content; the
+        // editor needs the file.
+        let source = null;
+        try {
+            const projectRoot = cg.getProjectRoot();
+            const absPath = safeProjectPath(projectRoot, spec.sourcePath);
+            if (absPath && fs.existsSync(absPath)) {
+                source = fs.readFileSync(absPath, 'utf-8');
+            }
+        }
+        catch {
+            // File missing or unreadable — return null so the UI can show a
+            // "source not available" hint without failing the whole fetch.
+        }
+        return { spec, parent, siblings, children, links, source };
+    });
+    app.get('/api/drift', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const sq = cg.getSpecQueries();
+        const validStates = [
+            'drafted', 'implementing', 'implemented', 'verified',
+            'drifted', 'broken', 'orphaned',
+        ];
+        const requested = (req.query.state ?? 'drifted,broken,orphaned')
+            .split(',')
+            .map((s) => s.trim())
+            .filter((s) => validStates.includes(s));
+        const limit = Math.min(parseInt(req.query.limit ?? '100', 10) || 100, 500);
+        const links = sq.getLinksByState(requested).slice(0, limit);
+        const out = links.map((l) => {
+            const spec = sq.getSpecById(l.specId);
+            return { ...l, specTitle: spec?.title ?? null };
+        });
+        return { links: out };
+    });
+    app.post('/api/spec/link-assert', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const body = req.body;
+        if (!body?.spec_id || !body.target_file_path || !body.target_qualified_name) {
+            return reply.code(400).send({ error: 'spec_id, target_file_path, target_qualified_name required' });
+        }
+        const sq = cg.getSpecQueries();
+        const spec = sq.getSpecById(body.spec_id);
+        if (!spec)
+            return reply.code(404).send({ error: 'spec not found' });
+        const now = Date.now();
+        const id = sq.upsertSpecLink({
+            specId: body.spec_id,
+            targetFilePath: body.target_file_path,
+            targetQualifiedName: body.target_qualified_name,
+            targetNodeKind: body.target_node_kind ?? 'function',
+            resolvedNodeId: undefined,
+            kind: body.kind ?? 'implements',
+            state: 'implemented',
+            driftAxis: null,
+            specHashAtLink: spec.contentHash,
+            nodeSigAtLink: undefined,
+            provenance: 'agent-asserted',
+            confidence: 1.0,
+            createdAt: now,
+            updatedAt: now,
+        });
+        cg.getSpecLinkResolver().resolveLinksForFiles([body.target_file_path]);
+        return { id, ok: true };
+    });
+    app.post('/api/spec/link-verify', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const body = req.body;
+        if (typeof body?.link_id !== 'number' || (body.result !== 'pass' && body.result !== 'fail')) {
+            return reply.code(400).send({ error: 'link_id (number) and result ("pass"|"fail") required' });
+        }
+        const sq = cg.getSpecQueries();
+        const link = sq.getLinkById(body.link_id);
+        if (!link)
+            return reply.code(404).send({ error: 'link not found' });
+        sq.updateSpecLinkState(body.link_id, body.result === 'pass' ? 'verified' : 'broken', null);
+        return { ok: true, state: body.result === 'pass' ? 'verified' : 'broken' };
+    });
+    /**
+     * PUT /api/spec/:id — overwrite the spec file backing this spec.
+     *
+     * Resolves the source file path from the existing spec row, validates it's
+     * under the project root (path-traversal guard), atomically writes the new
+     * content, then re-syncs the project so the indexer picks up the change.
+     * Returns the freshly re-parsed spec node. Used by the dashboard's Monaco
+     * editor.
+     */
+    app.put('/api/spec/:id', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const sq = cg.getSpecQueries();
+        const spec = sq.getSpecById(req.params.id);
+        if (!spec)
+            return reply.code(404).send({ error: 'spec not found' });
+        const body = req.body;
+        if (typeof body?.content !== 'string') {
+            return reply.code(400).send({ error: 'content (string) required' });
+        }
+        const projectRoot = cg.getProjectRoot();
+        const absPath = safeProjectPath(projectRoot, spec.sourcePath);
+        if (!absPath) {
+            return reply.code(400).send({
+                error: 'spec.sourcePath resolves outside project root',
+                code: 'path_traversal',
+            });
+        }
+        try {
+            atomicWriteFile(absPath, body.content);
+        }
+        catch (e) {
+            return reply.code(500).send({
+                error: 'failed to write spec file',
+                detail: e instanceof Error ? e.message : String(e),
+            });
+        }
+        // Re-index so the freshly-edited spec replaces the old graph nodes.
+        // The Markdown extractor will rebuild the doc + REQs + acceptance
+        // children, and the link resolver re-runs against the new content
+        // hash so drift states transition correctly.
+        try {
+            await cg.sync();
+        }
+        catch (e) {
+            // Sync errors don't roll back the write — the file is on disk and
+            // the next sync will pick it up. Surface so the UI can show a
+            // "saved but not yet indexed" hint.
+            const updated = sq.getSpecById(req.params.id);
+            return {
+                ok: true,
+                spec: updated ?? spec,
+                syncError: e instanceof Error ? e.message : String(e),
+            };
+        }
+        const updated = sq.getSpecById(req.params.id);
+        return { ok: true, spec: updated ?? spec };
+    });
+    /**
+     * POST /api/specs — create a new spec file under the project's specs/
+     * directory.
+     *
+     * `filePath` is project-relative (e.g. `specs/billing.md`). 409 if the
+     * file already exists. Used by the dashboard's Draft-with-Claude flow
+     * for the optional "finalize via dashboard" path.
+     */
+    app.post('/api/specs', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const body = req.body;
+        if (typeof body?.filePath !== 'string' || typeof body?.content !== 'string') {
+            return reply.code(400).send({ error: 'filePath and content (strings) required' });
+        }
+        const projectRoot = cg.getProjectRoot();
+        const absPath = safeProjectPath(projectRoot, body.filePath);
+        if (!absPath) {
+            return reply.code(400).send({
+                error: 'filePath resolves outside project root',
+                code: 'path_traversal',
+            });
+        }
+        if (fs.existsSync(absPath)) {
+            return reply.code(409).send({
+                error: 'file already exists',
+                code: 'file_exists',
+                filePath: body.filePath,
+            });
+        }
+        try {
+            atomicWriteFile(absPath, body.content);
+        }
+        catch (e) {
+            return reply.code(500).send({
+                error: 'failed to write spec file',
+                detail: e instanceof Error ? e.message : String(e),
+            });
+        }
+        try {
+            await cg.sync();
+        }
+        catch (e) {
+            return {
+                ok: true,
+                filePath: body.filePath,
+                syncError: e instanceof Error ? e.message : String(e),
+            };
+        }
+        return { ok: true, filePath: body.filePath };
+    });
+}

package/dist/server/routes/status.js

@@ -0,0 +1,112 @@
+/**
+ * GET /api/status — backend, journal mode, node/edge counts, drift count,
+ * last index time. Drives the UI's persistent status strip.
+ *
+ * POST /api/refresh — force-sync the SpecShip index AND trigger an
+ * immediate Claude Code transcript re-ingest. Wired to the global
+ * refresh button in the dashboard's status strip so users can pull
+ * Sessions / Heatmap / Costs / Memory current without waiting on the
+ * watcher's debounce.
+ *
+ * Project-scoped: accepts `?project=<slug>` and serves the matching
+ * SpecShip instance from the registry. When no project is selectable
+ * (no `?project=`, no primary), returns a 409 with `code: 'no_project'`
+ * so the UI can show the picker without blowing up.
+ */
+export async function registerStatusRoutes(app) {
+    app.get('/api/status', async (req, reply) => {
+        const cg = await app.activeCg(req);
+        if (!cg) {
+            return reply.code(409).send({ error: 'no project selected', code: 'no_project' });
+        }
+        const stats = cg.getStats();
+        const lastIndexed = cg.getLastIndexedAt();
+        const drift = cg
+            .getSpecQueries()
+            .getLinksByState(['drifted', 'broken', 'orphaned']).length;
+        return {
+            projectPath: cg.getProjectRoot ? cg.getProjectRoot() : '',
+            backend: cg.getBackend(),
+            journalMode: cg.getJournalMode(),
+            nodeCount: stats.nodeCount,
+            edgeCount: stats.edgeCount,
+            fileCount: stats.fileCount,
+            drift,
+            lastIndexed: lastIndexed != null ? new Date(lastIndexed).toISOString() : null,
+            nodesByKind: stats.nodesByKind,
+            filesByLanguage: stats.filesByLanguage,
+            dbSizeBytes: stats.dbSizeBytes,
+        };
+    });
+    /**
+     * Force a synchronous re-sync of the project's SpecShip index AND a
+     * fresh Claude Code transcript ingest pass. The status strip's
+     * refresh button calls this so users can pull every project-scoped
+     * surface (Sessions, Heatmap, Costs, Memory, Drift, Graph) to
+     * current without waiting on the JSONL watcher's debounce window or
+     * the next file-watcher tick.
+     *
+     * Returns the same shape as GET /api/status (so the UI can update
+     * its strip and `lastIndexed` label in one round-trip) plus the
+     * ingest stats for surfaces interested in "how many new sessions
+     * landed."
+     *
+     * Both steps run sequentially. Errors in either are surfaced under
+     * `syncError` / `ingestError` so a transient ingest hiccup doesn't
+     * mask a successful index sync (or vice versa) — and the UI can
+     * decide whether to retry or surface the failure.
+     */
+    app.post('/api/refresh', async (req, reply) => {
+        const cg = await app.activeCg(req);
+        if (!cg) {
+            return reply.code(409).send({ error: 'no project selected', code: 'no_project' });
+        }
+        let syncError = null;
+        let ingestError = null;
+        let ingestStats = null;
+        // 1. Re-index the project. Picks up code AND specs/ changes the
+        //    auto-sync hook may not have caught yet.
+        try {
+            await cg.sync();
+        }
+        catch (e) {
+            syncError = e instanceof Error ? e.message : String(e);
+        }
+        // 2. Re-ingest Claude Code transcripts. Skipped silently when the
+        //    server was booted with `--no-ingest` (app.watcher == null).
+        if (app.watcher) {
+            try {
+                ingestStats = await app.watcher.ingestNow();
+            }
+            catch (e) {
+                ingestError = e instanceof Error ? e.message : String(e);
+            }
+        }
+        // 3. Echo the new status so the UI updates its strip + lastIndexed
+        //    label without a separate GET.
+        const stats = cg.getStats();
+        const lastIndexed = cg.getLastIndexedAt();
+        const drift = cg
+            .getSpecQueries()
+            .getLinksByState(['drifted', 'broken', 'orphaned']).length;
+        return {
+            ok: syncError === null && ingestError === null,
+            syncError,
+            ingestError,
+            ingestStats,
+            status: {
+                projectPath: cg.getProjectRoot ? cg.getProjectRoot() : '',
+                backend: cg.getBackend(),
+                journalMode: cg.getJournalMode(),
+                nodeCount: stats.nodeCount,
+                edgeCount: stats.edgeCount,
+                fileCount: stats.fileCount,
+                drift,
+                lastIndexed: lastIndexed != null ? new Date(lastIndexed).toISOString() : null,
+                nodesByKind: stats.nodesByKind,
+                filesByLanguage: stats.filesByLanguage,
+                dbSizeBytes: stats.dbSizeBytes,
+            },
+        };
+    });
+}

package/dist/server/routes/workflow.js

@@ -0,0 +1,212 @@
+/**
+ * Workflow routes — discover / run / resume / cancel / approve / reject /
+ * runs list / run detail + SSE event stream.
+ *
+ * All project-scoped via `?project=<slug>` (falls back to primary). Each
+ * handler resolves the active SpecShip instance from the registry and
+ * constructs the WorktreeProvider + WorkflowExecutor on demand against
+ * that instance's queries. Construction is cheap (both classes just stash
+ * references), and pinning a single executor across all projects would
+ * tie the entire surface to whichever instance loaded first.
+ *
+ * The SSE endpoint streams workflow_events as they're appended to the DB
+ * (polling 500ms). For v1 polling the same SQLite the executor writes to is
+ * faster + more reliable than wiring an in-process event bus across packages.
+ */
+import path from 'node:path';
+import { existsSync } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+async function resolveCg(app, req, reply) {
+    const cg = await app.activeCg(req);
+    if (!cg) {
+        reply.code(409).send({ error: 'no project selected', code: 'no_project' });
+        return null;
+    }
+    return cg;
+}
+export async function registerWorkflowRoutes(app) {
+    // Lazy import — keeps the server bootable even if the workflow engine
+    // is disabled in the current build profile.
+    //
+    // Two delivery shapes (same pattern as loadSpecShip() in ../server.ts):
+    //   1. **Bundled** — `dist/server/routes/workflow.js` sits two levels under
+    //      `dist/`, so the core workflow modules live at `../../workflows/*.js`
+    //      and `../../isolation/*.js`. We try this relative path first because
+    //      the bundled tarball stages the specship core without a resolvable
+    //      `@selvakumaresra/specship` package on Node's module graph (offline
+    //      installs hit this — see scripts/offline-install.sh).
+    //   2. **Workspace / dev** — the `file:../..` workspace dep resolves the
+    //      named import via Node's normal package resolution.
+    let discovery;
+    let executorMod;
+    let worktreeMod;
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const bundledDiscovery = path.resolve(here, '..', '..', 'workflows', 'discovery.js');
+    if (existsSync(bundledDiscovery)) {
+        discovery = await import(pathToFileURL(bundledDiscovery).href);
+        executorMod = await import(pathToFileURL(path.resolve(here, '..', '..', 'workflows', 'executor.js')).href);
+        worktreeMod = await import(pathToFileURL(path.resolve(here, '..', '..', 'isolation', 'worktree.js')).href);
+    }
+    else {
+        discovery = await import('@selvakumaresra/specship/dist/workflows/discovery.js');
+        executorMod = await import('@selvakumaresra/specship/dist/workflows/executor.js');
+        worktreeMod = await import('@selvakumaresra/specship/dist/isolation/worktree.js');
+    }
+    const { discoverWorkflows, loadWorkflowByName } = discovery;
+    const { WorkflowExecutor } = executorMod;
+    const { WorktreeProvider } = worktreeMod;
+    const executorCache = new WeakMap();
+    /** Build (or fetch cached) executor + worktree provider for a project. */
+    function executorFor(cg) {
+        const sq = cg.getSpecQueries();
+        const cached = executorCache.get(sq);
+        if (cached)
+            return { sq, executor: cached.executor, projectRoot: cached.projectRoot };
+        const projectRoot = cg.getProjectRoot ? cg.getProjectRoot() : process.cwd();
+        const worktrees = new WorktreeProvider(sq);
+        const executor = new WorkflowExecutor(sq, worktrees);
+        executorCache.set(sq, { executor, projectRoot });
+        return { sq, executor, projectRoot };
+    }
+    app.get('/api/workflows', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const { projectRoot } = executorFor(cg);
+        return discoverWorkflows(projectRoot);
+    });
+    app.post('/api/workflows/runs', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const { executor, projectRoot } = executorFor(cg);
+        const body = req.body;
+        if (!body?.workflowName)
+            return reply.code(400).send({ error: 'workflowName required' });
+        const loaded = loadWorkflowByName(projectRoot, body.workflowName);
+        if (!loaded)
+            return reply.code(404).send({ error: 'workflow not found' });
+        const startPromise = executor.start(loaded.workflow, {
+            projectRoot,
+            inputs: body.inputs,
+            variables: body.variables,
+        });
+        const result = await Promise.race([
+            startPromise,
+            new Promise((resolve) => setTimeout(() => resolve({ run: { id: 'pending', status: 'starting' } }), 50)),
+        ]);
+        startPromise.catch(() => { });
+        return { runId: result.run.id, status: result.run.status };
+    });
+    app.get('/api/workflows/runs', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const { sq } = executorFor(cg);
+        const limit = Math.min(parseInt(req.query.limit ?? '50', 10) || 50, 500);
+        return { runs: sq.getAllWorkflowRuns(limit) };
+    });
+    app.get('/api/workflows/runs/:id', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const { sq } = executorFor(cg);
+        const run = sq.getWorkflowRunById(req.params.id);
+        if (!run)
+            return reply.code(404).send({ error: 'run not found' });
+        const events = sq.getEventsByRun(req.params.id, 500);
+        return { run, events };
+    });
+    /**
+     * SSE event stream. Polls the events table every 500ms for any events
+     * newer than the last id sent. Closes when the run hits a terminal state.
+     */
+    app.get('/api/workflows/runs/:id/events', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const { sq } = executorFor(cg);
+        const runId = req.params.id;
+        let lastId = parseInt(req.query.since ?? '0', 10) || 0;
+        reply.raw.setHeader('Content-Type', 'text/event-stream');
+        reply.raw.setHeader('Cache-Control', 'no-cache');
+        reply.raw.setHeader('Connection', 'keep-alive');
+        reply.raw.flushHeaders();
+        let closed = false;
+        req.raw.on('close', () => { closed = true; });
+        const tick = async () => {
+            if (closed)
+                return;
+            const events = sq.getEventsByRun(runId, 1000);
+            const fresh = events.filter((e) => e.id > lastId);
+            for (const e of fresh) {
+                reply.raw.write(`id: ${e.id}\n`);
+                reply.raw.write(`event: ${e.eventType}\n`);
+                reply.raw.write(`data: ${JSON.stringify(e)}\n\n`);
+                lastId = e.id;
+            }
+            const run = sq.getWorkflowRunById(runId);
+            if (!run || ['completed', 'failed', 'cancelled'].includes(run.status)) {
+                reply.raw.write(`event: done\ndata: ${JSON.stringify({ status: run?.status })}\n\n`);
+                reply.raw.end();
+                return;
+            }
+            setTimeout(() => { void tick(); }, 500);
+        };
+        void tick();
+    });
+    app.post('/api/workflows/runs/:id/approve', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const { executor } = executorFor(cg);
+        try {
+            executor.approve(req.params.id, req.body?.comment);
+            return { ok: true };
+        }
+        catch (err) {
+            return reply.code(400).send({ error: err instanceof Error ? err.message : String(err) });
+        }
+    });
+    app.post('/api/workflows/runs/:id/reject', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const { executor } = executorFor(cg);
+        try {
+            executor.reject(req.params.id, req.body?.reason);
+            return { ok: true };
+        }
+        catch (err) {
+            return reply.code(400).send({ error: err instanceof Error ? err.message : String(err) });
+        }
+    });
+    app.post('/api/workflows/runs/:id/cancel', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const { executor } = executorFor(cg);
+        try {
+            executor.cancel(req.params.id, req.body?.reason);
+            return { ok: true };
+        }
+        catch (err) {
+            return reply.code(400).send({ error: err instanceof Error ? err.message : String(err) });
+        }
+    });
+    app.post('/api/workflows/runs/:id/resume', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const { sq, executor, projectRoot } = executorFor(cg);
+        const run = sq.getWorkflowRunById(req.params.id);
+        if (!run)
+            return reply.code(404).send({ error: 'run not found' });
+        const loaded = loadWorkflowByName(projectRoot, run.workflowName);
+        if (!loaded)
+            return reply.code(404).send({ error: 'workflow definition missing' });
+        const promise = executor.resume(loaded.workflow, req.params.id, { projectRoot });
+        promise.catch(() => { });
+        return { ok: true };
+    });
+}