@specship/specship 0.11.0

package/dist/server/ingest/pricing.js

@@ -0,0 +1,78 @@
+/**
+ * Cost calculation from Claude Code usage records.
+ *
+ * Pricing is per-model and per-token-bucket (input / output / cache write /
+ * cache read). The DB seeds defaults for the current Anthropic public tiers;
+ * users can override via the UI / CLI. The seeded rates live in the
+ * `claude_pricing` table — see the v6 migration in specship core.
+ *
+ * Model name matching is loose: Claude sometimes reports versioned model
+ * names like `claude-opus-4-7-20260601`. We strip the date suffix and try
+ * exact match first, then fall back to family-level rates (e.g. any
+ * `claude-opus-*` falls back to a generic Opus rate).
+ */
+const FAMILY_FALLBACKS = {
+    opus: 'claude-opus-4',
+    sonnet: 'claude-sonnet-4',
+    haiku: 'claude-haiku-4',
+};
+/**
+ * Normalize a Claude model ID:
+ *   - Lower-case
+ *   - Strip trailing -YYYYMMDD or -YYYY-MM-DD date markers
+ *   - Strip [1m] context-window suffixes (e.g. claude-opus-4-7[1m])
+ */
+export function normalizeModelId(model) {
+    if (!model)
+        return '';
+    let m = model.toLowerCase();
+    m = m.replace(/\[\d+[a-z]+\]$/, '');
+    m = m.replace(/-(\d{8}|\d{4}-\d{2}-\d{2})$/, '');
+    return m;
+}
+/**
+ * Look up a PricingRow for a model. Tries:
+ *   1. exact match on normalized model id
+ *   2. exact match on the original id
+ *   3. family fallback (opus / sonnet / haiku → generic v4 rate)
+ *   4. null (caller should treat cost as 0)
+ */
+export function resolvePricing(model, rows) {
+    if (!model)
+        return null;
+    const norm = normalizeModelId(model);
+    for (const r of rows) {
+        if (r.model.toLowerCase() === norm)
+            return r;
+    }
+    for (const r of rows) {
+        if (r.model.toLowerCase() === model.toLowerCase())
+            return r;
+    }
+    // Family fallback.
+    for (const [family, fallbackModel] of Object.entries(FAMILY_FALLBACKS)) {
+        if (norm.includes(family)) {
+            for (const r of rows) {
+                if (r.model.toLowerCase() === fallbackModel)
+                    return r;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Compute USD cost for one assistant turn's usage record. Returns 0 if no
+ * pricing row resolves — the caller will report that separately.
+ */
+export function computeCost(usage, pricing) {
+    if (!usage || !pricing)
+        return 0;
+    const input = usage.input_tokens ?? 0;
+    const output = usage.output_tokens ?? 0;
+    const cacheCreate = usage.cache_creation_input_tokens ?? 0;
+    const cacheRead = usage.cache_read_input_tokens ?? 0;
+    return ((input * pricing.input_per_mtok) / 1_000_000 +
+        (output * pricing.output_per_mtok) / 1_000_000 +
+        (cacheCreate * pricing.cache_creation_per_mtok) / 1_000_000 +
+        (cacheRead * pricing.cache_read_per_mtok) / 1_000_000);
+}

package/dist/server/ingest/specship-classify.js

@@ -0,0 +1,153 @@
+/**
+ * Pure classifiers and symbol-extraction helpers for SpecShip Token Impact.
+ *
+ * SERVER-LOCAL COPY. The lib has the canonical version at
+ * `src/analytics/specship-impact.ts`; this file is duplicated here on purpose
+ * so the server never carries a runtime `import … from '@selvakumaresra/specship'`
+ * — a bare-package value import does NOT resolve in bundled / different-cwd
+ * mode and silently drops the server back to a stale build (the same failure
+ * mode `server.ts`/`workflow.ts` already guard against). These functions are
+ * pure (no I/O, no deps), so duplication is cheap; `__tests__/specship-impact-parity.test.ts`
+ * asserts the two copies stay behaviourally identical.
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Prefix shared by every MCP tool routed through the specship server. */
+const MCP_SPECSHIP_PREFIX = 'mcp__specship__';
+/**
+ * Strip-prefix base names of SpecShip tools that return code-graph source.
+ * These are the tools a SpecShip call can displace a native Read/Grep with.
+ * Excluded: designer_*, specship_link_assert, specship_link_verify,
+ * specship_spec, specship_drifted, specship_status — they don't return
+ * indexed source symbols.
+ */
+const SOURCE_RETURNING_TOOLS = new Set([
+    'specship_explore',
+    'specship_node',
+    'specship_callers',
+    'specship_callees',
+    'specship_impact',
+    'specship_search',
+    'specship_files',
+]);
+/**
+ * Tools whose input carries a `symbol` key (single identifier string).
+ * Verified against src/mcp/tools.ts inputSchema `required: ['symbol']`.
+ */
+const SYMBOL_KEY_TOOLS = new Set([
+    'specship_node',
+    'specship_callers',
+    'specship_callees',
+    'specship_impact',
+]);
+/**
+ * Regex for a single valid identifier token (with optional Class.method
+ * qualifier).
+ */
+const SYMBOL_TOKEN_RE = /^[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*)?$/;
+/**
+ * Regex a token must match to be considered "code-ish" rather than prose.
+ * Real symbol names almost always contain an uppercase letter, underscore,
+ * dollar sign, digit, or a dot; pure lowercase words look like prose.
+ */
+const CODE_SIGNAL_RE = /[A-Z_$\d.]/;
+/** Cap on how many symbol-shaped tokens we pull from one query. */
+const MAX_SYMBOLS_PER_QUERY = 16;
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/** True iff `name` is routed through the SpecShip MCP server. */
+export function isSpecshipTool(name) {
+    return name.startsWith(MCP_SPECSHIP_PREFIX);
+}
+/** True iff the tool returns code-graph source that can displace a Read/Grep. */
+export function isSourceReturningTool(name) {
+    if (!name.startsWith(MCP_SPECSHIP_PREFIX))
+        return false;
+    const base = name.slice(MCP_SPECSHIP_PREFIX.length);
+    return SOURCE_RETURNING_TOOLS.has(base);
+}
+/**
+ * Extracts the symbol names a tool call asked about from its serialised input
+ * JSON. Returns `[]` when no symbols are resolvable (bad JSON, prose query,
+ * non-symbol tool).
+ */
+export function extractRequestedSymbols(toolName, inputJson) {
+    if (!inputJson)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(inputJson);
+    }
+    catch {
+        return [];
+    }
+    if (parsed === null || typeof parsed !== 'object')
+        return [];
+    const args = parsed;
+    if (!toolName.startsWith(MCP_SPECSHIP_PREFIX))
+        return [];
+    const base = toolName.slice(MCP_SPECSHIP_PREFIX.length);
+    if (SYMBOL_KEY_TOOLS.has(base)) {
+        const sym = args['symbol'];
+        return typeof sym === 'string' && sym.length > 0 ? [sym] : [];
+    }
+    if (base === 'specship_explore' || base === 'specship_search') {
+        const q = args['query'];
+        if (typeof q !== 'string' || q.length === 0)
+            return [];
+        return symbolBagFromQuery(q);
+    }
+    return [];
+}
+/**
+ * Classify one tool call → the three ingest columns
+ * (`isSpecship`, `resolution`, `displacedFiles`). A graph-estimate failure
+ * degrades to 'unresolved' (it must NEVER break core transcript ingest).
+ */
+export function classifyToolCall(call, graph) {
+    const { toolName, inputJson, resultLength } = call;
+    if (!isSpecshipTool(toolName)) {
+        return { isSpecship: 0, resolution: null, displacedFiles: null };
+    }
+    if (isSourceReturningTool(toolName) && resultLength > 0) {
+        const symbols = extractRequestedSymbols(toolName, inputJson);
+        if (symbols.length === 0) {
+            return { isSpecship: 1, resolution: 'unresolved', displacedFiles: null };
+        }
+        if (graph === null) {
+            return { isSpecship: 1, resolution: 'unresolved', displacedFiles: null };
+        }
+        let files;
+        let resolved;
+        try {
+            ({ files, resolved } = graph.estimateReadEquivalent(symbols));
+        }
+        catch {
+            return { isSpecship: 1, resolution: 'unresolved', displacedFiles: null };
+        }
+        if (resolved) {
+            return {
+                isSpecship: 1,
+                resolution: 'resolved',
+                displacedFiles: JSON.stringify(files.map((f) => [f.path, f.size])),
+            };
+        }
+        return { isSpecship: 1, resolution: 'unresolved', displacedFiles: null };
+    }
+    return { isSpecship: 1, resolution: 'n/a', displacedFiles: null };
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+// Real explore/search queries are MIXED bags (symbol names + lowercase
+// keywords, often 10+ tokens). FILTER the symbol-shaped tokens out rather than
+// rejecting the whole query; pure prose yields []. Capped to bound graph work.
+function symbolBagFromQuery(query) {
+    const symbols = query
+        .trim()
+        .split(/\s+/)
+        .filter((t) => SYMBOL_TOKEN_RE.test(t) && CODE_SIGNAL_RE.test(t));
+    return symbols.slice(0, MAX_SYMBOLS_PER_QUERY);
+}

package/dist/server/ingest/types.js

@@ -0,0 +1,9 @@
+/**
+ * Type definitions for Claude Code JSONL transcript ingest.
+ *
+ * These mirror the fields we actually use — Claude Code's JSONL format has
+ * many more fields than these (parentUuid, isSidechain, version, gitBranch,
+ * userType, …); we capture only what drives analytics + cost. Unknown fields
+ * pass through silently.
+ */
+export {};

package/dist/server/ingest/watcher.js

@@ -0,0 +1,77 @@
+/**
+ * Filesystem watcher that re-runs the ingestor on JSONL changes.
+ *
+ * Strategy:
+ *   - One initial full pass on start (catches everything written while the
+ *     watcher wasn't running — same offset state, no duplicates).
+ *   - fs.watch on the ~/.claude/projects/ tree, debounced 300ms — Claude
+ *     Code writes one line at a time during a session, so we don't want to
+ *     re-ingest on every keystroke.
+ *   - On change, re-run ingestAll. The state table makes this cheap: only
+ *     new bytes are read + parsed.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { ingestAll } from './ingestor.js';
+export function startWatcher(db, options = {}) {
+    const claudeRoot = options.claudeRoot ?? path.join(os.homedir(), '.claude', 'projects');
+    const debounceMs = options.debounceMs ?? 300;
+    const verbose = options.verbose ?? false;
+    let pending = null;
+    const triggerSoon = () => {
+        if (pending)
+            clearTimeout(pending);
+        pending = setTimeout(() => {
+            pending = null;
+            try {
+                ingestAll(db, { ...options, claudeRoot });
+            }
+            catch (err) {
+                if (verbose) {
+                    // eslint-disable-next-line no-console
+                    console.error('[ingest watcher] pass failed:', err instanceof Error ? err.message : String(err));
+                }
+            }
+        }, debounceMs);
+    };
+    // Initial pass.
+    if (options.initialIngest !== false) {
+        triggerSoon();
+    }
+    // fs.watch on the root, recursive. On macOS + Linux this gives us per-file
+    // events; on Windows the recursive flag is supported as of recent Node.
+    let watcher = null;
+    try {
+        watcher = fs.watch(claudeRoot, { recursive: true, persistent: true }, (eventType, filename) => {
+            if (!filename)
+                return;
+            const f = filename.toString();
+            if (!f.toLowerCase().endsWith('.jsonl'))
+                return;
+            triggerSoon();
+        });
+    }
+    catch (err) {
+        // Directory doesn't exist (user hasn't run Claude Code) — just no-op.
+        if (verbose) {
+            // eslint-disable-next-line no-console
+            console.error('[ingest watcher] could not watch', claudeRoot, ':', err instanceof Error ? err.message : String(err));
+        }
+    }
+    return {
+        stop: () => {
+            if (pending) {
+                clearTimeout(pending);
+                pending = null;
+            }
+            if (watcher) {
+                try {
+                    watcher.close();
+                }
+                catch { /* ignore */ }
+            }
+        },
+        ingestNow: () => ingestAll(db, { ...options, claudeRoot }),
+    };
+}

package/dist/server/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/server/project-registry.js

@@ -0,0 +1,101 @@
+/**
+ * ProjectRegistry — lazy-opens and caches SpecShip instances per project
+ * path, keyed by absolute path. LRU evicts when the cache exceeds maxOpen
+ * so a long-running server doesn't hold every project's SQLite handle
+ * forever.
+ *
+ * Used by the Fastify routes (via `app.activeCg(req)`) to back the desktop
+ * app's project picker: when the user switches projects in the UI, the
+ * specship-scoped surfaces (graph, specs, drift, workflows, status) start
+ * reading from the matching instance — opened on demand if it isn't
+ * already cached.
+ *
+ * Analytics endpoints (`/api/claude/*`, `/api/memory`) read from a single
+ * "primary" instance instead, since their data (JSONL ingest, CLAUDE.md
+ * hierarchy) is global to the user, not scoped to one project.
+ */
+import { decodeProjectSlug } from './ingest/ingestor.js';
+export class ProjectRegistry {
+    cache = new Map();
+    maxOpen;
+    verbose;
+    openImpl;
+    constructor(opts, defaultOpenImpl) {
+        this.maxOpen = opts.maxOpen ?? 5;
+        this.verbose = opts.verbose ?? false;
+        this.openImpl = opts.openImpl ?? defaultOpenImpl;
+    }
+    /**
+     * Return the cached SpecShip for `projectPath`, opening it on demand.
+     * Returns null when the path isn't initialized (no `.specship/`) or
+     * the open throws — callers surface a friendly UI error.
+     */
+    async get(projectPath) {
+        const existing = this.cache.get(projectPath);
+        if (existing) {
+            existing.lastAccess = Date.now();
+            return existing.cg;
+        }
+        try {
+            const cg = await this.openImpl(projectPath);
+            this.cache.set(projectPath, { cg, lastAccess: Date.now() });
+            this.evictIfNeeded();
+            if (this.verbose)
+                console.error(`[registry] opened ${projectPath} (cache size ${this.cache.size})`);
+            return cg;
+        }
+        catch (err) {
+            if (this.verbose)
+                console.error(`[registry] open failed for ${projectPath}: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    /**
+     * Look up by Claude Code's slug-encoded project name
+     * (`-Users-alice-foo` → `/Users/alice/foo`).
+     */
+    async getBySlug(slug) {
+        return this.get(decodeProjectSlug(slug));
+    }
+    /** Currently-cached project paths (most-recent-access first). */
+    openPaths() {
+        return [...this.cache.entries()]
+            .sort((a, b) => b[1].lastAccess - a[1].lastAccess)
+            .map(([k]) => k);
+    }
+    has(projectPath) { return this.cache.has(projectPath); }
+    /** Close + drop every cached instance. Called on server shutdown. */
+    closeAll() {
+        for (const [, v] of this.cache) {
+            try {
+                v.cg.close();
+            }
+            catch { /* ignore */ }
+        }
+        this.cache.clear();
+    }
+    evictIfNeeded() {
+        if (this.cache.size <= this.maxOpen)
+            return;
+        let oldestKey = null;
+        let oldestTime = Infinity;
+        for (const [k, v] of this.cache) {
+            if (v.lastAccess < oldestTime) {
+                oldestTime = v.lastAccess;
+                oldestKey = k;
+            }
+        }
+        if (oldestKey) {
+            const entry = this.cache.get(oldestKey);
+            if (entry) {
+                try {
+                    entry.cg.close();
+                }
+                catch { /* ignore */ }
+            }
+            this.cache.delete(oldestKey);
+            if (this.verbose)
+                console.error(`[registry] evicted ${oldestKey}`);
+        }
+    }
+}