@specship/specship 0.11.0

package/dist/server/routes/events.js

@@ -0,0 +1,134 @@
+/**
+ * GET /api/events — cross-project alert stream (REQ-PWA-002).
+ *
+ * A single SSE stream that watches EVERY initialized project (not just the
+ * selected one) and emits an event when an alert-worthy transition happens:
+ *   - `approval`  — a workflow run entered `paused` (an approval gate)
+ *   - `runDone`   — a run entered `completed` or `failed`
+ *   - `drift`     — a spec→code link newly entered drifted/broken/orphaned
+ *
+ * Polls the same SQLite the executor/resolver write to (mirrors the workflow
+ * SSE's 500ms-poll approach), diffing against per-connection seen-state so only
+ * NEW transitions are emitted — never a backlog burst on connect, never a repeat
+ * for the same transition. The client (NotificationsService) turns these into
+ * desktop notifications, gated on permission + per-type toggles.
+ */
+import os from 'node:os';
+import path from 'node:path';
+import { enumerate } from './projects.js';
+const POLL_MS = 3000;
+const KEEPALIVE_MS = 15000;
+// Reflection sweep cadence — high-severity-only, roughly daily (REQ-REFLECT-006).
+// The persisted reflect_proposals store dedupes across sweeps/connections, so a
+// proposal is only ever notified once regardless of how often the sweep runs.
+const SWEEP_MS = 24 * 60 * 60 * 1000;
+export async function registerEventsRoutes(app) {
+    const claudeRoot = path.join(os.homedir(), '.claude', 'projects');
+    app.get('/api/events', async (req, reply) => {
+        reply.raw.setHeader('Content-Type', 'text/event-stream');
+        reply.raw.setHeader('Cache-Control', 'no-cache');
+        reply.raw.setHeader('Connection', 'keep-alive');
+        reply.raw.write(': connected\n\n');
+        // Per-connection seen-state — emit only NEW transitions.
+        const lastStatus = new Map(); // `${slug}:${runId}` -> status
+        const seenDrift = new Set(); // `${slug}:${linkId}`
+        const lastSweep = new Map(); // slug -> last reflection sweep ms
+        let primed = false; // first pass seeds state silently (no burst on connect)
+        let closed = false;
+        const send = (ev) => {
+            if (closed)
+                return;
+            try {
+                reply.raw.write(`data: ${JSON.stringify(ev)}\n\n`);
+            }
+            catch { /* peer gone */ }
+        };
+        const poll = async () => {
+            let projects;
+            try {
+                projects = await enumerate(claudeRoot);
+            }
+            catch {
+                return;
+            }
+            for (const p of projects) {
+                if (!p.initialized || closed)
+                    continue;
+                let cg;
+                try {
+                    cg = await app.projects.getBySlug(p.slug);
+                }
+                catch {
+                    cg = null;
+                }
+                if (!cg)
+                    continue;
+                const sq = cg.getSpecQueries();
+                // Workflow run transitions.
+                let runs = [];
+                try {
+                    runs = sq.getAllWorkflowRuns(50);
+                }
+                catch { /* ignore */ }
+                for (const r of runs) {
+                    const key = `${p.slug}:${r.id}`;
+                    if (lastStatus.get(key) === r.status)
+                        continue;
+                    lastStatus.set(key, r.status);
+                    if (!primed)
+                        continue;
+                    if (r.status === 'paused') {
+                        send({ kind: 'approval', project: p.slug, projectPath: p.path, id: r.id, title: 'Run needs approval', detail: r.workflowName });
+                    }
+                    else if (r.status === 'completed' || r.status === 'failed') {
+                        send({ kind: 'runDone', project: p.slug, projectPath: p.path, id: r.id, title: `Run ${r.status}`, detail: r.workflowName, status: r.status });
+                    }
+                }
+                // Newly-drifted links.
+                let links = [];
+                try {
+                    links = sq.getLinksByState(['drifted', 'broken', 'orphaned']);
+                }
+                catch { /* ignore */ }
+                for (const l of links) {
+                    const key = `${p.slug}:${l.id}`;
+                    if (seenDrift.has(key))
+                        continue;
+                    seenDrift.add(key);
+                    if (!primed)
+                        continue;
+                    send({ kind: 'drift', project: p.slug, projectPath: p.path, id: String(l.id), title: 'Drift detected', detail: `${l.specId} → ${l.targetQualifiedName}` });
+                }
+                // Reflection sweep — throttled to ~daily. Notifies only on NEW
+                // high-severity proposals; the persisted store dedupes, so this is NOT
+                // gated on `primed` (a brand-new finding should alert even on connect,
+                // while an already-seen one never re-fires regardless of connection).
+                const now = Date.now();
+                if (now - (lastSweep.get(p.slug) ?? 0) >= SWEEP_MS) {
+                    lastSweep.set(p.slug, now);
+                    try {
+                        const res = cg.reflectSweep();
+                        for (const prop of res.notify) {
+                            send({ kind: 'reflect', project: p.slug, projectPath: p.path, id: prop.contentHash, title: prop.title, detail: prop.evidence.detail });
+                        }
+                    }
+                    catch { /* ignore — a sweep failure must not break the stream */ }
+                }
+            }
+            primed = true;
+        };
+        await poll(); // prime: seed seen-state without emitting
+        const pollTimer = setInterval(() => { void poll(); }, POLL_MS);
+        const kaTimer = setInterval(() => { if (!closed) {
+            try {
+                reply.raw.write(': ka\n\n');
+            }
+            catch { /* noop */ }
+        } }, KEEPALIVE_MS);
+        req.raw.on('close', () => {
+            closed = true;
+            clearInterval(pollTimer);
+            clearInterval(kaTimer);
+        });
+    });
+}

package/dist/server/routes/graph.js

@@ -0,0 +1,248 @@
+/**
+ * Graph routes — node detail + explore + search.
+ *
+ * These are thin wrappers around methods on a SpecShip instance. Every
+ * route resolves the active instance via `app.activeCg(req)`, which honors
+ * `?project=<slug>` and falls back to the boot-time primary. When neither
+ * is available, returns 409 / `no_project` so the desktop UI can show its
+ * project picker instead of an opaque 500.
+ *
+ * The MCP layer's `specship_*` tools are markdown-formatted for agents;
+ * here we return raw JSON so the UI can render visually.
+ */
+/** Returns the active SpecShip or sends a 409. */
+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;
+}
+/** Dig the raw SQLite handle off a SpecShip instance (same shape as routes/claude.ts). */
+function getDb(cg) {
+    const anyCg = cg;
+    if (anyCg.db?.getDb)
+        return anyCg.db.getDb();
+    if (anyCg.queries?.db)
+        return anyCg.queries.db;
+    throw new Error('specship DB handle not accessible from server context');
+}
+export async function registerGraphRoutes(app) {
+    app.get('/api/graph/stats', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        return cg.getStats();
+    });
+    /**
+     * List nodes with optional kind / file / limit filtering. For node-explorer
+     * UI surfaces that want a flat paginated list.
+     */
+    app.get('/api/graph/nodes', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const limit = Math.min(Math.max(parseInt(req.query.limit ?? '100', 10) || 100, 1), 1000);
+        const offset = Math.max(parseInt(req.query.offset ?? '0', 10) || 0, 0);
+        const results = cg.searchNodes(req.query.kind ?? '', { limit: limit + offset });
+        return {
+            total: results.length,
+            offset,
+            limit,
+            nodes: results.slice(offset, offset + limit).map((r) => r.node),
+        };
+    });
+    /**
+     * GET /api/graph/node — by symbol name (with optional file/line disambiguation)
+     * or by exact id. Returns the node + callers + callees + linked specs.
+     */
+    app.get('/api/graph/node', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const { symbol, id, file, line } = req.query;
+        if (!symbol && !id) {
+            return reply.code(400).send({ error: 'symbol or id is required' });
+        }
+        let matches = [];
+        if (id) {
+            const node = cg.getNode(id);
+            if (node)
+                matches = [node];
+        }
+        else if (symbol) {
+            matches = cg.searchNodes(symbol, { limit: 50 }).map((r) => r.node);
+            if (file) {
+                const f = file.toLowerCase();
+                const narrowed = matches.filter((n) => n.filePath.toLowerCase().includes(f));
+                if (narrowed.length > 0)
+                    matches = narrowed;
+            }
+            if (line) {
+                const ln = parseInt(line, 10);
+                if (Number.isFinite(ln)) {
+                    const containing = matches.filter((n) => n.startLine <= ln && (n.endLine ?? n.startLine) >= ln);
+                    matches = containing.length > 0 ? containing : matches.slice(0, 1);
+                }
+            }
+        }
+        if (matches.length === 0)
+            return reply.code(404).send({ error: 'not found' });
+        const enriched = matches.map((n) => {
+            const callers = cg.getCallers(n.id).map((e) => e.node);
+            const callees = cg.getCallees(n.id).map((e) => e.node);
+            const links = cg.getSpecQueries().getLinksByNode(n.id);
+            return { ...n, callers, callees, linkedSpecs: links };
+        });
+        return { matches: enriched };
+    });
+    app.post('/api/graph/explore', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const { query, maxFiles } = req.body ?? { query: '' };
+        if (!query)
+            return reply.code(400).send({ error: 'query is required' });
+        void maxFiles;
+        const ctx = await cg.buildContext(query, {
+            maxNodes: 80,
+            includeCode: true,
+            format: 'markdown',
+        });
+        return ctx;
+    });
+    app.get('/api/graph/search', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const q = req.query.q ?? '';
+        const limit = Math.min(parseInt(req.query.limit ?? '20', 10) || 20, 200);
+        if (!q)
+            return { results: [] };
+        const kinds = req.query.kind ? [req.query.kind] : undefined;
+        const results = cg.searchNodes(q, { kinds, limit });
+        return { results };
+    });
+    app.get('/api/graph/callers/:id', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const node = cg.getNode(req.params.id);
+        if (!node)
+            return reply.code(404).send({ error: 'node not found' });
+        return { callers: cg.getCallers(req.params.id).map((e) => e.node) };
+    });
+    app.get('/api/graph/callees/:id', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const node = cg.getNode(req.params.id);
+        if (!node)
+            return reply.code(404).send({ error: 'node not found' });
+        return { callees: cg.getCallees(req.params.id).map((e) => e.node) };
+    });
+    app.get('/api/graph/impact/:id', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const depth = Math.min(parseInt(req.query.depth ?? '2', 10) || 2, 5);
+        return { impact: cg.getImpactRadius(req.params.id, depth) };
+    });
+    app.get('/api/graph/files', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        return { files: cg.getFiles() };
+    });
+    /**
+     * GET /api/graph/health — feeds the Graph overview panel:
+     *   - linkHealth: spec-link counts per state (verified/drifted/broken/orphaned/…)
+     *   - edgeKinds:  edge counts grouped into calls / implements-documents / tests
+     *   - hubs:       the most-connected nodes (by total degree), for the "Most connected" list
+     */
+    app.get('/api/graph/health', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        // Spec-link health — count by state off the spec_links table.
+        const linkHealth = {};
+        for (const l of cg.getSpecQueries().getAllLinks()) {
+            linkHealth[l.state] = (linkHealth[l.state] ?? 0) + 1;
+        }
+        const db = getDb(cg);
+        // Edge kinds — bucket by the node kinds the edge connects, mirroring the
+        // design's "calls / implements / tests" legend. spec endpoints → implements,
+        // test endpoints → tests, everything else → calls.
+        const edgeKinds = db.prepare(`
+      SELECT
+        CASE
+          WHEN ns.kind = 'spec' OR nt.kind = 'spec' THEN 'implements'
+          WHEN ns.kind = 'test' OR nt.kind = 'test' THEN 'tests'
+          ELSE 'calls'
+        END as bucket,
+        COUNT(*) as count
+      FROM edges e
+      JOIN nodes ns ON ns.id = e.source
+      JOIN nodes nt ON nt.id = e.target
+      GROUP BY bucket
+    `).all();
+        const edgeKindMap = { calls: 0, implements: 0, tests: 0 };
+        for (const r of edgeKinds)
+            edgeKindMap[r.bucket] = r.count;
+        // Synthesized (heuristic) edge count — dashed in the legend.
+        const synth = db.prepare(`SELECT COUNT(*) as c FROM edges WHERE provenance = 'heuristic'`).get();
+        edgeKindMap['synth'] = synth.c ?? 0;
+        // Most-connected hubs — total degree (in + out) per node, top 8.
+        const hubs = db.prepare(`
+      SELECT n.id, n.name, n.kind, n.file_path as filePath, deg.degree
+      FROM (
+        SELECT node, COUNT(*) as degree FROM (
+          SELECT source as node FROM edges
+          UNION ALL
+          SELECT target as node FROM edges
+        ) GROUP BY node ORDER BY degree DESC LIMIT 8
+      ) deg
+      JOIN nodes n ON n.id = deg.node
+      ORDER BY deg.degree DESC
+    `).all();
+        return { linkHealth, edgeKinds: edgeKindMap, hubs };
+    });
+    /**
+     * Full-graph overview for the Graph page's whole-repo view. The graph can be
+     * huge (10k+ nodes) and the canvas + client-side force layout are O(n²), so
+     * we return the top-N most-connected nodes (by total degree) plus the edges
+     * among them. Isolated (degree-0) nodes are omitted — an overview shows the
+     * connected core. `total` reports the full node count so the UI can say
+     * "showing N of M".
+     */
+    app.get('/api/graph/full', async (req, reply) => {
+        const cg = await resolveCg(app, req, reply);
+        if (!cg)
+            return;
+        const db = getDb(cg);
+        const limit = Math.min(Math.max(parseInt(req.query.limit ?? '250', 10) || 250, 1), 400);
+        const nodeRows = db.prepare(`
+      SELECT n.id, n.name, n.kind, n.file_path as filePath, deg.degree
+      FROM (
+        SELECT node, COUNT(*) as degree FROM (
+          SELECT source as node FROM edges
+          UNION ALL
+          SELECT target as node FROM edges
+        ) GROUP BY node ORDER BY degree DESC LIMIT ?
+      ) deg
+      JOIN nodes n ON n.id = deg.node
+      ORDER BY deg.degree DESC
+    `).all(limit);
+        const keep = new Set(nodeRows.map((n) => n.id));
+        const allEdges = db.prepare(`SELECT source as "from", target as "to", kind, provenance FROM edges`).all();
+        const edges = allEdges.filter((e) => keep.has(e.from) && keep.has(e.to));
+        const totalRow = db.prepare(`SELECT COUNT(*) as c FROM nodes`).get();
+        return {
+            nodes: nodeRows.map((n) => ({ id: n.id, name: n.name, kind: n.kind, filePath: n.filePath, degree: n.degree })),
+            edges,
+            total: totalRow.c ?? nodeRows.length,
+            shown: nodeRows.length,
+        };
+    });
+}

package/dist/server/routes/maintainability.js

@@ -0,0 +1,18 @@
+/**
+ * GET /api/maintainability (REQ-MAINT-003).
+ *
+ * Returns the active project's graph-derived maintainability report — coupling,
+ * size hotspots, dependency cycles, dead-code candidates. Project-scoped (uses
+ * the active instance, like the graph/spec routes), driven through the instance
+ * method `getMaintainability()` so the server never runtime-imports the package.
+ */
+export async function registerMaintainabilityRoutes(app) {
+    app.get('/api/maintainability', async (req, reply) => {
+        const cg = await app.activeCg(req);
+        if (!cg) {
+            reply.code(409).send({ error: 'no project selected', code: 'no_project' });
+            return;
+        }
+        return cg.getMaintainability();
+    });
+}

package/dist/server/routes/memory.js

@@ -0,0 +1,272 @@
+/**
+ * GET /api/memory — CLAUDE.md hierarchy + ~/.claude/memory notes.
+ *
+ * Walks the standard Claude Code memory locations and returns a flattened
+ * list of MemoryFile records the desktop UI can render directly. Resolves
+ * `@path` imports from each instruction file.
+ *
+ * Levels:
+ *   - enterprise — `/Library/Application Support/ClaudeCode/CLAUDE.md` (read-only)
+ *   - user       — `~/.claude/CLAUDE.md`
+ *   - project    — `<projectRoot>/CLAUDE.md`
+ *   - subdir     — `<projectRoot>/<sub>/CLAUDE.md` (one level deep; common case)
+ *   - import     — files referenced as `@path` from a project/subdir CLAUDE.md
+ *   - note       — `~/.claude/memory/*.md` (agent-written via memory tool)
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { decodeProjectSlug } from '../ingest/ingestor.js';
+const ENTERPRISE_PATHS = [
+    '/Library/Application Support/ClaudeCode/CLAUDE.md',
+    '/etc/ClaudeCode/CLAUDE.md',
+    process.env['ProgramData'] ? path.join(process.env['ProgramData'], 'ClaudeCode', 'CLAUDE.md') : '',
+].filter(Boolean);
+function estimateTokens(body) {
+    // Rough heuristic: ~4 chars per token. Cheap; the UI tolerates approximation.
+    return Math.max(1, Math.round(body.length / 4));
+}
+function relativeTime(ms) {
+    const diff = Date.now() - ms;
+    const sec = Math.round(diff / 1000);
+    if (sec < 60)
+        return `${sec}s ago`;
+    const min = Math.round(sec / 60);
+    if (min < 60)
+        return `${min}m ago`;
+    const hr = Math.round(min / 60);
+    if (hr < 24)
+        return `${hr}h ago`;
+    const day = Math.round(hr / 24);
+    if (day < 7)
+        return `${day}d ago`;
+    const d = new Date(ms);
+    return d.toLocaleDateString();
+}
+async function tryRead(filePath) {
+    try {
+        const [body, stat] = await Promise.all([fs.readFile(filePath, 'utf-8'), fs.stat(filePath)]);
+        return { body, modified: stat.mtimeMs };
+    }
+    catch {
+        return null;
+    }
+}
+function extractImports(body) {
+    const out = [];
+    for (const line of body.split('\n')) {
+        const m = line.match(/^@(\S+)/);
+        if (m && m[1])
+            out.push(m[1]);
+    }
+    return out;
+}
+function expandHome(p) {
+    if (p.startsWith('~/'))
+        return path.join(os.homedir(), p.slice(2));
+    return p;
+}
+function pathForUi(absolute) {
+    const home = os.homedir();
+    if (absolute.startsWith(home + path.sep))
+        return '~/' + absolute.slice(home.length + 1);
+    return absolute;
+}
+function makeFile(opts) {
+    return {
+        id: opts.id,
+        level: opts.level,
+        type: opts.type,
+        name: opts.name,
+        scope: opts.scope,
+        path: pathForUi(opts.absolutePath),
+        tokens: estimateTokens(opts.body),
+        lines: opts.body.split('\n').length,
+        modified: relativeTime(opts.modifiedMs),
+        body: opts.body,
+        readOnly: opts.readOnly,
+        imports: opts.imports?.length ? opts.imports : undefined,
+    };
+}
+async function collectEnterprise() {
+    const out = [];
+    for (const p of ENTERPRISE_PATHS) {
+        const file = await tryRead(p);
+        if (file) {
+            out.push(makeFile({
+                id: 'm-ent',
+                level: 'enterprise',
+                type: 'instruction',
+                name: 'CLAUDE.md',
+                scope: 'managed',
+                absolutePath: p,
+                body: file.body,
+                modifiedMs: file.modified,
+                readOnly: true,
+            }));
+            break;
+        }
+    }
+    return out;
+}
+async function collectUser() {
+    const p = path.join(os.homedir(), '.claude', 'CLAUDE.md');
+    const file = await tryRead(p);
+    if (!file)
+        return [];
+    return [makeFile({
+            id: 'm-user',
+            level: 'user',
+            type: 'instruction',
+            name: 'CLAUDE.md',
+            scope: '~/.claude',
+            absolutePath: p,
+            body: file.body,
+            modifiedMs: file.modified,
+        })];
+}
+async function collectProject(projectRoot) {
+    const out = [];
+    const proj = path.join(projectRoot, 'CLAUDE.md');
+    const projFile = await tryRead(proj);
+    const importMap = new Map();
+    if (projFile) {
+        const imports = extractImports(projFile.body);
+        const resolvedIds = [];
+        for (const imp of imports) {
+            const abs = path.isAbsolute(imp) ? imp : path.join(projectRoot, imp);
+            const sub = await tryRead(abs);
+            if (sub) {
+                const id = 'm-imp-' + Buffer.from(imp).toString('base64').replace(/=/g, '').slice(0, 10);
+                importMap.set(imp, makeFile({
+                    id,
+                    level: 'import',
+                    type: 'import',
+                    name: path.basename(abs),
+                    scope: '@import',
+                    absolutePath: abs,
+                    body: sub.body,
+                    modifiedMs: sub.modified,
+                }));
+                resolvedIds.push(id);
+            }
+        }
+        out.push(makeFile({
+            id: 'm-proj',
+            level: 'project',
+            type: 'instruction',
+            name: 'CLAUDE.md',
+            scope: 'project root',
+            absolutePath: proj,
+            body: projFile.body,
+            modifiedMs: projFile.modified,
+            imports: resolvedIds,
+        }));
+        for (const im of importMap.values())
+            out.push(im);
+    }
+    // Scan one level of subdirectories for nested CLAUDE.md files. Keeps the
+    // walk cheap — going deeper would need ignoring node_modules etc.
+    try {
+        const entries = await fs.readdir(projectRoot, { withFileTypes: true });
+        for (const ent of entries) {
+            if (!ent.isDirectory())
+                continue;
+            if (ent.name.startsWith('.') || ent.name === 'node_modules' || ent.name === 'dist')
+                continue;
+            const subPath = path.join(projectRoot, ent.name, 'CLAUDE.md');
+            const sub = await tryRead(subPath);
+            if (sub) {
+                out.push(makeFile({
+                    id: 'm-sub-' + ent.name,
+                    level: 'subdir',
+                    type: 'instruction',
+                    name: 'CLAUDE.md',
+                    scope: ent.name,
+                    absolutePath: subPath,
+                    body: sub.body,
+                    modifiedMs: sub.modified,
+                }));
+            }
+        }
+    }
+    catch {
+        // Project root not readable — ignore, return what we already have.
+    }
+    return out;
+}
+async function collectNotes() {
+    const dir = path.join(os.homedir(), '.claude', 'memory');
+    const out = [];
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const ent of entries) {
+        if (!ent.isFile() || !ent.name.endsWith('.md'))
+            continue;
+        const abs = path.join(dir, ent.name);
+        const file = await tryRead(abs);
+        if (!file)
+            continue;
+        const tags = Array.from(file.body.matchAll(/#([A-Za-z][A-Za-z0-9_-]*)/g))
+            .map((m) => m[1])
+            .filter((t) => typeof t === 'string')
+            .slice(0, 6);
+        out.push(makeFile({
+            id: 'n-' + ent.name.replace(/\.md$/, ''),
+            level: 'note',
+            type: 'note',
+            name: ent.name,
+            scope: 'memory tool',
+            absolutePath: abs,
+            body: file.body,
+            modifiedMs: file.modified,
+        }));
+        if (tags.length) {
+            const last = out[out.length - 1];
+            if (last)
+                last.tags = tags;
+        }
+    }
+    return out;
+}
+export async function registerMemoryRoutes(app) {
+    app.get('/api/memory', async (req) => {
+        // Memory has three global tiers (enterprise / user / notes) and one
+        // project tier. The global tiers always render; the project tier
+        // requires a project path. We try, in order:
+        //   1. The `?project=<slug>` query arg (decoded from Claude's slug).
+        //   2. The `?projectPath=` arg if the caller has the absolute path handy.
+        //   3. The primary SpecShip's projectRoot, if configured at boot.
+        // When none is available, the response just omits the project tier
+        // (no 409 — the user can still see their global memory).
+        let projectRoot = null;
+        if (req.query.project)
+            projectRoot = decodeProjectSlug(req.query.project);
+        else if (req.query.projectPath)
+            projectRoot = req.query.projectPath;
+        else if (app.primaryCg?.getProjectRoot)
+            projectRoot = app.primaryCg.getProjectRoot();
+        const [enterprise, user, project, notes] = await Promise.all([
+            collectEnterprise(),
+            collectUser(),
+            projectRoot ? collectProject(projectRoot) : Promise.resolve([]),
+            collectNotes(),
+        ]);
+        const files = [...enterprise, ...user, ...project, ...notes];
+        const resp = {
+            totalTokens: files.reduce((a, b) => a + b.tokens, 0),
+            instructionCount: files.filter((f) => f.type === 'instruction').length,
+            noteCount: files.filter((f) => f.type === 'note').length,
+            importCount: files.filter((f) => f.type === 'import').length,
+            files,
+        };
+        return resp;
+    });
+}
+// Re-export the helper for tests
+export const _testing = { expandHome, pathForUi, estimateTokens, extractImports };