@selvakumaresra/specship 0.1.0

package/dist/server/routes/graph.js

@@ -0,0 +1,149 @@
+/**
+ * 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;
+}
+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() };
+    });
+}

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 };

package/dist/server/routes/projects.js

@@ -0,0 +1,197 @@
+/**
+ * GET /api/projects        — enumerate every project visible to Claude Code
+ *                            (every dir under ~/.claude/projects/).
+ * GET /api/projects/events  — SSE stream that pushes a refresh whenever the
+ *                            watcher sees the project list change. Used by
+ *                            the desktop UI's Project picker so newly opened
+ *                            projects appear without a refresh.
+ *
+ * Why this lives in its own route file: the rest of the analytics endpoints
+ * already read ~/.claude/projects/ via the ingest pipeline. This route adds
+ * a *navigation* primitive on top of that data — "what projects does the
+ * user have at all?" — without coupling to the specship instance.
+ */
+import { EventEmitter } from 'node:events';
+import { promises as fs, watch } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { decodeProjectSlug } from '../ingest/ingestor.js';
+const projectsBus = new EventEmitter();
+projectsBus.setMaxListeners(0); // many SSE subscribers + internal
+async function enumerate(claudeRoot) {
+    let entries;
+    try {
+        entries = await fs.readdir(claudeRoot, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const ent of entries) {
+        if (!ent.isDirectory())
+            continue;
+        const slug = ent.name;
+        const decoded = decodeProjectSlug(slug);
+        const projDir = path.join(claudeRoot, slug);
+        let sessionCount = 0;
+        let lastModifiedMs = 0;
+        try {
+            const inside = await fs.readdir(projDir, { withFileTypes: true });
+            for (const f of inside) {
+                if (f.isFile() && f.name.toLowerCase().endsWith('.jsonl')) {
+                    sessionCount++;
+                    try {
+                        const stat = await fs.stat(path.join(projDir, f.name));
+                        if (stat.mtimeMs > lastModifiedMs)
+                            lastModifiedMs = stat.mtimeMs;
+                    }
+                    catch { /* ignore */ }
+                }
+            }
+        }
+        catch { /* project dir disappeared mid-scan — skip its files */ }
+        let exists = false;
+        let initialized = false;
+        try {
+            const st = await fs.stat(decoded);
+            exists = st.isDirectory();
+            if (exists) {
+                try {
+                    const cg = await fs.stat(path.join(decoded, '.specship'));
+                    initialized = cg.isDirectory();
+                }
+                catch { /* not initialized — OK */ }
+            }
+        }
+        catch { /* path missing — OK, still surface it so UI can flag it */ }
+        out.push({ slug, path: decoded, exists, initialized, sessionCount, lastModifiedMs });
+    }
+    // Recent activity first; ties broken by path.
+    out.sort((a, b) => {
+        if (b.lastModifiedMs !== a.lastModifiedMs)
+            return b.lastModifiedMs - a.lastModifiedMs;
+        return a.path.localeCompare(b.path);
+    });
+    return out;
+}
+// --- Watcher (singleton across the process) ---------------------------------
+let watcher = null;
+let lastSlugs = new Set();
+let debounceHandle = null;
+let watchedRoot = null;
+function startWatcher(claudeRoot, verbose) {
+    if (watcher)
+        return;
+    watchedRoot = claudeRoot;
+    try {
+        watcher = watch(claudeRoot, { persistent: true }, () => {
+            scheduleRescan(claudeRoot);
+        });
+        if (verbose)
+            console.error(`[projects] watching ${claudeRoot}`);
+        // Warm the cache so the first SSE snapshot has accurate state and the
+        // first change diff is meaningful.
+        void enumerate(claudeRoot).then((list) => {
+            lastSlugs = new Set(list.map((p) => p.slug));
+        });
+    }
+    catch (err) {
+        if (verbose)
+            console.error(`[projects] watch failed for ${claudeRoot}:`, err instanceof Error ? err.message : String(err));
+        // Directory may not exist yet — that's OK, every /api/projects GET
+        // returns [] until it does. We don't retry here; if the watcher is
+        // critical the user can restart the server after creating it.
+    }
+}
+function scheduleRescan(claudeRoot) {
+    if (debounceHandle)
+        clearTimeout(debounceHandle);
+    debounceHandle = setTimeout(async () => {
+        debounceHandle = null;
+        const list = await enumerate(claudeRoot);
+        const newSlugs = new Set(list.map((p) => p.slug));
+        const added = list.filter((p) => !lastSlugs.has(p.slug));
+        const removed = [...lastSlugs].filter((s) => !newSlugs.has(s));
+        lastSlugs = newSlugs;
+        if (added.length || removed.length) {
+            projectsBus.emit('change', { added, removed, list });
+        }
+        // Refresh is always emitted so subscribers can pick up lastModified /
+        // sessionCount drift even without slug-level changes.
+        projectsBus.emit('refresh', { list });
+    }, 350);
+}
+function stopWatcher() {
+    if (watcher) {
+        try {
+            watcher.close();
+        }
+        catch { /* ignore */ }
+        watcher = null;
+    }
+    if (debounceHandle) {
+        clearTimeout(debounceHandle);
+        debounceHandle = null;
+    }
+    watchedRoot = null;
+}
+// --- Route registration -----------------------------------------------------
+export async function registerProjectsRoutes(app) {
+    const claudeRoot = path.join(os.homedir(), '.claude', 'projects');
+    startWatcher(claudeRoot, false);
+    app.addHook('onClose', async () => { stopWatcher(); });
+    app.get('/api/projects', async () => {
+        return { claudeRoot, projects: await enumerate(claudeRoot) };
+    });
+    app.get('/api/projects/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.flushHeaders();
+        let closed = false;
+        const onClose = () => {
+            closed = true;
+            projectsBus.off('change', onChange);
+            projectsBus.off('refresh', onRefresh);
+            clearInterval(hb);
+        };
+        req.raw.on('close', onClose);
+        const writeEvent = (event, data) => {
+            if (closed)
+                return;
+            try {
+                reply.raw.write(`event: ${event}\n`);
+                reply.raw.write(`data: ${JSON.stringify(data)}\n\n`);
+            }
+            catch { /* socket gone */
+                closed = true;
+            }
+        };
+        const initial = await enumerate(claudeRoot);
+        lastSlugs = new Set(initial.map((p) => p.slug));
+        writeEvent('snapshot', { claudeRoot, projects: initial });
+        const onChange = (payload) => {
+            writeEvent('change', payload);
+        };
+        const onRefresh = (payload) => {
+            writeEvent('refresh', payload);
+        };
+        projectsBus.on('change', onChange);
+        projectsBus.on('refresh', onRefresh);
+        // Heartbeat keeps proxies / NATs from dropping the idle connection.
+        const hb = setInterval(() => {
+            if (closed) {
+                clearInterval(hb);
+                return;
+            }
+            try {
+                reply.raw.write(`: ping\n\n`);
+            }
+            catch {
+                onClose();
+            }
+        }, 30000);
+    });
+}
+/** Test seam — re-export so __tests__ can stop the watcher between cases. */
+export const _testing = { stopWatcher, watchedRoot: () => watchedRoot };