@nac3/forge-cli 0.2.0-alpha.1

package/dist/chat/claude.js

@@ -0,0 +1,228 @@
+/**
+ * Yujin Forge -- Claude API client.
+ *
+ * Wraps the Anthropic /v1/messages endpoint with two modes:
+ *
+ *   1. Plain chat: messages + system -> text reply.
+ *   2. Tool-use loop: messages + tools + runTool callback -> the
+ *      client loops, dispatching tool_use blocks via the callback,
+ *      until the model emits no more tool calls (or maxToolRounds
+ *      is exhausted). Returns the final text + an audit trail of
+ *      every tool call.
+ *
+ * The tool-use loop hides the multi-turn dance from external
+ * callers. ChatMessage stays `{role, content: string}` -- the
+ * intermediate tool_use / tool_result turns are managed inside.
+ *
+ * API key resolution order:
+ *   1. options.apiKey (test injection)
+ *   2. process.env.YUJIN_ANTHROPIC_API_KEY
+ *   3. process.env.ANTHROPIC_API_KEY
+ *   4. ~/.yujin-forge/api-key.txt (one line, plain text)
+ *
+ * Falls through with a clear ConfigurationError when none of the
+ * above resolves.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { configDir } from '../license/index.js';
+import { Vault } from '../vault/store.js';
+export class ConfigurationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigurationError';
+    }
+}
+export class ClaudeApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = 'ClaudeApiError';
+        this.status = status;
+    }
+}
+/**
+ * Resolve the Anthropic API key.
+ *
+ * Priority order (first match wins):
+ *   1. Explicitly injected key (test seam).
+ *   2. Vault slot `anthropic` -- the canonical path going
+ *      forward.
+ *   3. process.env.YUJIN_ANTHROPIC_API_KEY -- legacy env var.
+ *   4. process.env.ANTHROPIC_API_KEY -- standard Anthropic env.
+ *   5. ~/.yujin-forge/api-key.txt -- legacy file path.
+ *
+ * Throws ConfigurationError when nothing is found. The error
+ * message lists all the options so the user has a single place
+ * to read where to put the key.
+ *
+ * The vault check is short-circuiting: if the slot exists, the
+ * env vars and the file are ignored. This makes vault-configured
+ * setups deterministic and unaffected by stray env vars.
+ *
+ * The other three paths stay as back-compat for existing users
+ * who already configured Forge via env or file before V0.4
+ * landed. They are NOT deprecated -- they keep working
+ * indefinitely. The vault is just the recommended path.
+ */
+export async function resolveApiKey(injected) {
+    if (injected && injected.trim() !== '')
+        return injected.trim();
+    /* Vault first. Opens cheaply; the cost is dominated by
+       scrypt derivation (~60ms) which is acceptable for the
+       boot of a chat session. */
+    try {
+        const vault = await Vault.open({ configDir: configDir() });
+        if (vault.has('anthropic')) {
+            const value = vault.get('anthropic');
+            if (value && value.trim() !== '')
+                return value.trim();
+        }
+    }
+    catch {
+        /* Vault unavailable (corrupted, permissions, etc) -- do NOT
+           crash here. Fall through to the legacy paths so users with
+           env-var setups still work. The vault corruption surfaces
+           loudly when they explicitly run `yf vault list` or `set`. */
+    }
+    const fromEnv = process.env['YUJIN_ANTHROPIC_API_KEY']
+        ?? process.env['ANTHROPIC_API_KEY'];
+    if (fromEnv && fromEnv.trim() !== '')
+        return fromEnv.trim();
+    const filePath = path.join(configDir(), 'api-key.txt');
+    try {
+        const raw = await fs.readFile(filePath, 'utf-8');
+        const trimmed = raw.trim();
+        if (trimmed !== '')
+            return trimmed;
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+    throw new ConfigurationError('no Anthropic API key found. Configure one of:\n'
+        + '  - yf vault set anthropic   (recommended)\n'
+        + '  - export YUJIN_ANTHROPIC_API_KEY=sk-ant-...\n'
+        + '  - export ANTHROPIC_API_KEY=sk-ant-...\n'
+        + '  - write the key to ~/.yujin-forge/api-key.txt');
+}
+const DEFAULT_MODEL = 'claude-sonnet-4-6';
+const DEFAULT_MAX_TOOL_ROUNDS = 5;
+export class ClaudeClient {
+    apiKey;
+    fetchImpl;
+    defaultModel;
+    constructor(opts = {}) {
+        this.apiKey = opts.apiKey ?? null;
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+        this.defaultModel = opts.defaultModel ?? DEFAULT_MODEL;
+    }
+    async chat(req) {
+        if (this.apiKey === null) {
+            this.apiKey = await resolveApiKey();
+        }
+        if (req.tools && !req.runTool) {
+            throw new Error('ClaudeChatRequest.tools requires a runTool callback');
+        }
+        const model = req.model ?? this.defaultModel;
+        const maxTokens = req.maxTokens ?? 1024;
+        const maxRounds = req.maxToolRounds ?? DEFAULT_MAX_TOOL_ROUNDS;
+        /* Seed the conversation with the caller's history. Each round
+           appends turns; the loop terminates when the model's
+           stop_reason is anything other than 'tool_use'. */
+        const messages = req.messages.map((m) => ({
+            role: m.role,
+            content: m.content,
+        }));
+        const toolRounds = [];
+        let totalTokensIn = 0;
+        let totalTokensOut = 0;
+        let lastText = '';
+        let usedModel = model;
+        for (let round = 0; round <= maxRounds; round++) {
+            const body = {
+                model,
+                max_tokens: maxTokens,
+                messages,
+            };
+            if (req.system)
+                body['system'] = req.system;
+            if (req.tools && req.tools.length > 0) {
+                body['tools'] = req.tools.map((t) => ({
+                    name: t.name,
+                    description: t.description,
+                    input_schema: t.input_schema,
+                }));
+            }
+            const resp = await this.fetchImpl('https://api.anthropic.com/v1/messages', {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    'x-api-key': this.apiKey,
+                    'anthropic-version': '2023-06-01',
+                },
+                body: JSON.stringify(body),
+            });
+            if (!resp.ok) {
+                const detail = await safeText(resp);
+                throw new ClaudeApiError('Claude API ' + resp.status + ': ' + detail.slice(0, 500), resp.status);
+            }
+            const data = await resp.json();
+            totalTokensIn += data.usage?.input_tokens ?? 0;
+            totalTokensOut += data.usage?.output_tokens ?? 0;
+            usedModel = data.model ?? model;
+            const blocks = data.content ?? [];
+            const textBlocks = blocks.filter((b) => b.type === 'text');
+            const toolUses = blocks.filter((b) => b.type === 'tool_use');
+            lastText = textBlocks.map((b) => b.text).join('');
+            if (toolUses.length === 0 || data.stop_reason !== 'tool_use') {
+                /* No tools called -- return whatever the model said. */
+                return {
+                    text: lastText,
+                    tokensIn: totalTokensIn,
+                    tokensOut: totalTokensOut,
+                    model: usedModel,
+                    toolRounds,
+                };
+            }
+            if (round === maxRounds) {
+                throw new ClaudeApiError('tool_use loop exhausted (' + maxRounds + ' rounds). Last text: '
+                    + (lastText ? lastText.slice(0, 200) : '(none)'), 429);
+            }
+            /* Persist the assistant turn (text + tool_use blocks) so
+               Anthropic sees the full history on the next round. */
+            messages.push({ role: 'assistant', content: blocks });
+            /* Dispatch each tool_use, build the user follow-up with one
+               tool_result per call. */
+            const toolResultBlocks = [];
+            for (const tu of toolUses) {
+                const r = await req.runTool(tu.name, tu.input);
+                toolRounds.push({
+                    tool: tu.name,
+                    input: tu.input,
+                    result: r.result,
+                    ...(r.is_error ? { is_error: true } : {}),
+                    tool_use_id: tu.id,
+                });
+                toolResultBlocks.push({
+                    type: 'tool_result',
+                    tool_use_id: tu.id,
+                    content: typeof r.result === 'string' ? r.result : JSON.stringify(r.result),
+                    ...(r.is_error ? { is_error: true } : {}),
+                });
+            }
+            messages.push({ role: 'user', content: toolResultBlocks });
+        }
+        /* Unreachable: the loop exits via return or throw. */
+        throw new ClaudeApiError('tool_use loop terminated unexpectedly', 500);
+    }
+}
+async function safeText(r) {
+    try {
+        return await r.text();
+    }
+    catch {
+        return '(no body)';
+    }
+}
+//# sourceMappingURL=claude.js.map

package/dist/chat/claude.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude.js","sourceRoot":"","sources":["../../src/chat/claude.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAG1C,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,MAAM,CAAS;IACf,YAAY,OAAe,EAAE,MAAc;QACzC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAkED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,QAAiB;IACnD,IAAI,QAAQ,IAAI,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC;IAE/D;;iCAE6B;IAC7B,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,CAAC,CAAC;QAC3D,IAAI,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC;YAC3B,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;YACrC,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE;gBAAE,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC;QACxD,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP;;;uEAG+D;IACjE,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC;WACvC,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;IAChD,IAAI,OAAO,IAAI,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;IAE5D,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,aAAa,CAAC,CAAC;IACvD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACjD,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;QAC3B,IAAI,OAAO,KAAK,EAAE;YAAE,OAAO,OAAO,CAAC;IACrC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,GAAG,CAAC;IAClE,CAAC;IAED,MAAM,IAAI,kBAAkB,CAC1B,iDAAiD;UAC/C,8CAA8C;UAC9C,iDAAiD;UACjD,2CAA2C;UAC3C,iDAAiD,CACpD,CAAC;AACJ,CAAC;AAED,MAAM,aAAa,GAAG,mBAAmB,CAAC;AAC1C,MAAM,uBAAuB,GAAG,CAAC,CAAC;AAgBlC,MAAM,OAAO,YAAY;IACf,MAAM,CAAgB;IACtB,SAAS,CAAe;IACxB,YAAY,CAAS;IAE7B,YAAY,OAA4B,EAAE;QACxC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC;QAClC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,KAAK,CAAC;QACzC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,aAAa,CAAC;IACzD,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,GAAsB;QAC/B,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;YACzB,IAAI,CAAC,MAAM,GAAG,MAAM,aAAa,EAAE,CAAC;QACtC,CAAC;QACD,IAAI,GAAG,CAAC,KAAK,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;QACzE,CAAC;QACD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,IAAI,IAAI,CAAC,YAAY,CAAC;QAC7C,MAAM,SAAS,GAAG,GAAG,CAAC,SAAS,IAAI,IAAI,CAAC;QACxC,MAAM,SAAS,GAAG,GAAG,CAAC,aAAa,IAAI,uBAAuB,CAAC;QAE/D;;4DAEoD;QACpD,MAAM,QAAQ,GAAiB,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACtD,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,OAAO,EAAE,CAAC,CAAC,OAAO;SACnB,CAAC,CAAC,CAAC;QAEJ,MAAM,UAAU,GAAgB,EAAE,CAAC;QACnC,IAAI,aAAa,GAAG,CAAC,CAAC;QACtB,IAAI,cAAc,GAAG,CAAC,CAAC;QACvB,IAAI,QAAQ,GAAG,EAAE,CAAC;QAClB,IAAI,SAAS,GAAG,KAAK,CAAC;QAEtB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,IAAI,SAAS,EAAE,KAAK,EAAE,EAAE,CAAC;YAChD,MAAM,IAAI,GAA4B;gBACpC,KAAK;gBACL,UAAU,EAAE,SAAS;gBACrB,QAAQ;aACT,CAAC;YACF,IAAI,GAAG,CAAC,MAAM;gBAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC;YAC5C,IAAI,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACtC,IAAI,CAAC,OAAO,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBACpC,IAAI,EAAE,CAAC,CAAC,IAAI;oBACZ,WAAW,EAAE,CAAC,CAAC,WAAW;oBAC1B,YAAY,EAAE,CAAC,CAAC,YAAY;iBAC7B,CAAC,CAAC,CAAC;YACN,CAAC;YAED,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,uCAAuC,EAAE;gBACzE,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,cAAc,EAAO,kBAAkB;oBACvC,WAAW,EAAU,IAAI,CAAC,MAAgB;oBAC1C,mBAAmB,EAAE,YAAY;iBAClC;gBACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;aAC3B,CAAC,CAAC;YACH,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;gBACb,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;gBACpC,MAAM,IAAI,cAAc,CACtB,aAAa,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EACzD,IAAI,CAAC,MAAM,CACZ,CAAC;YACJ,CAAC;YACD,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAK3B,CAAC;YACF,aAAa,IAAK,IAAI,CAAC,KAAK,EAAE,YAAY,IAAK,CAAC,CAAC;YACjD,cAAc,IAAI,IAAI,CAAC,KAAK,EAAE,aAAa,IAAI,CAAC,CAAC;YACjD,SAAS,GAAG,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC;YAEhC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;YAClC,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAuC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC;YAChG,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAuF,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC;YAClJ,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAElD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,WAAW,KAAK,UAAU,EAAE,CAAC;gBAC7D,wDAAwD;gBACxD,OAAO;oBACL,IAAI,EAAE,QAAQ;oBACd,QAAQ,EAAG,aAAa;oBACxB,SAAS,EAAE,cAAc;oBACzB,KAAK,EAAM,SAAS;oBACpB,UAAU;iBACX,CAAC;YACJ,CAAC;YAED,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,MAAM,IAAI,cAAc,CACtB,2BAA2B,GAAG,SAAS,GAAG,uBAAuB;sBAC/D,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAChD,GAAG,CACJ,CAAC;YACJ,CAAC;YAED;oEACwD;YACxD,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;YAEtD;uCAC2B;YAC3B,MAAM,gBAAgB,GAAsB,EAAE,CAAC;YAC/C,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;gBAC1B,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,OAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC;gBAChD,UAAU,CAAC,IAAI,CAAC;oBACd,IAAI,EAAE,EAAE,CAAC,IAAI;oBACb,KAAK,EAAE,EAAE,CAAC,KAAK;oBACf,MAAM,EAAE,CAAC,CAAC,MAAM;oBAChB,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBACzC,WAAW,EAAE,EAAE,CAAC,EAAE;iBACnB,CAAC,CAAC;gBACH,gBAAgB,CAAC,IAAI,CAAC;oBACpB,IAAI,EAAE,aAAa;oBACnB,WAAW,EAAE,EAAE,CAAC,EAAE;oBAClB,OAAO,EAAE,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC;oBAC3E,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBAC1C,CAAC,CAAC;YACL,CAAC;YACD,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAE,CAAC,CAAC;QAC7D,CAAC;QAED,sDAAsD;QACtD,MAAM,IAAI,cAAc,CAAC,uCAAuC,EAAE,GAAG,CAAC,CAAC;IACzE,CAAC;CACF;AAED,KAAK,UAAU,QAAQ,CAAC,CAAW;IACjC,IAAI,CAAC;QAAC,OAAO,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,WAAW,CAAC;IAAC,CAAC;AAC9D,CAAC"}

package/dist/chat/ingest_session.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Spec ingest sessions (V1.40 of HITO 1).
+ *
+ * Holds the NormalisedDocument + flattened-text + extracted
+ * structure for every spec the user has dropped on the chat
+ * panel. The data lives in memory while the chat server runs;
+ * it is not persisted because the user has not yet approved
+ * scaffolding (V1.42).
+ *
+ * Module-scope so V1.38 ingest, V1.40 extract, V1.41 plan,
+ * V1.42 approval, V1.43 scaffold can all see the same doc
+ * without threading state through the HTTP layer.
+ *
+ * ASCII-only.
+ */
+import type { NormalisedDocument } from '../reader/types.js';
+export interface ExtractedRequirement {
+    id: string;
+    text: string;
+    /** 'must' / 'should' / 'may' -- RFC-2119 style. Best-effort
+     *  extraction by the LLM. */
+    level: 'must' | 'should' | 'may' | 'unknown';
+}
+export interface ExtractedEntity {
+    name: string;
+    /** Plain-language description of the entity. */
+    description: string;
+    /** Field names extracted from the spec, when present. */
+    fields?: string[];
+}
+export interface ExtractedEndpoint {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    path: string;
+    description: string;
+}
+export interface ExtractedComponent {
+    name: string;
+    description: string;
+    /** Optional props list when the spec describes a UI
+     *  component. */
+    props?: string[];
+}
+export interface SpecExtraction {
+    requirements: ExtractedRequirement[];
+    entities: ExtractedEntity[];
+    endpoints: ExtractedEndpoint[];
+    components: ExtractedComponent[];
+    /** Free-text summary of what the spec asks for. 1-2
+     *  paragraphs. */
+    summary: string;
+}
+export interface IngestSession {
+    doc_id: string;
+    doc: NormalisedDocument;
+    /** Flattened text contents (all paragraphs + headings joined
+     *  with line breaks). Fed to Claude for extraction; bounded
+     *  by FLATTEN_MAX_CHARS so spec docs over the bound surface
+     *  loud truncation in the extraction prompt. */
+    flat_text: string;
+    /** When V1.40 has run, the extraction is cached here so
+     *  V1.41 (plan), V1.42 (approval), V1.43 (scaffold) can read
+     *  it without re-calling Claude. */
+    extraction?: SpecExtraction;
+    /** When V1.41 has run, the generated file plan is cached. */
+    plan?: import('./spec_plan.js').SpecPlan;
+    /** When V1.43 has run, the scaffold report + rollback log. */
+    scaffold?: import('./spec_scaffold.js').ScaffoldReport;
+    /** ISO timestamp the session was created. */
+    ingested_at: string;
+}
+/** Hard cap on the flattened text we feed to Claude. ~64K
+ *  chars at ~4 chars/token = ~16K tokens, comfortably under
+ *  Claude's input budget for the extraction call. */
+export declare const FLATTEN_MAX_CHARS: number;
+/** Build the flattened-text view of a NormalisedDocument. */
+export declare function flattenDocument(doc: NormalisedDocument): {
+    text: string;
+    truncated: boolean;
+};
+export declare function recordIngest(doc: NormalisedDocument): IngestSession;
+export declare function getIngest(docId: string): IngestSession | null;
+export declare function setExtraction(docId: string, extraction: SpecExtraction): void;
+export declare function setPlan(docId: string, plan: import('./spec_plan.js').SpecPlan): void;
+export declare function setScaffold(docId: string, report: import('./spec_scaffold.js').ScaffoldReport): void;
+export declare function clearScaffold(docId: string): void;
+export declare function listIngest(): {
+    doc_id: string;
+    title: string;
+    format: string;
+    ingested_at: string;
+    has_extraction: boolean;
+    has_plan: boolean;
+    has_scaffold: boolean;
+}[];
+/** Test seam. */
+export declare function _resetIngestForTests(): void;
+//# sourceMappingURL=ingest_session.d.ts.map

package/dist/chat/ingest_session.d.ts.map

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

package/dist/chat/ingest_session.js

@@ -0,0 +1,99 @@
+/**
+ * Spec ingest sessions (V1.40 of HITO 1).
+ *
+ * Holds the NormalisedDocument + flattened-text + extracted
+ * structure for every spec the user has dropped on the chat
+ * panel. The data lives in memory while the chat server runs;
+ * it is not persisted because the user has not yet approved
+ * scaffolding (V1.42).
+ *
+ * Module-scope so V1.38 ingest, V1.40 extract, V1.41 plan,
+ * V1.42 approval, V1.43 scaffold can all see the same doc
+ * without threading state through the HTTP layer.
+ *
+ * ASCII-only.
+ */
+/** Hard cap on the flattened text we feed to Claude. ~64K
+ *  chars at ~4 chars/token = ~16K tokens, comfortably under
+ *  Claude's input budget for the extraction call. */
+export const FLATTEN_MAX_CHARS = 64 * 1024;
+const SESSIONS = new Map();
+/** Build the flattened-text view of a NormalisedDocument. */
+export function flattenDocument(doc) {
+    const parts = [];
+    for (const s of doc.sections) {
+        if (s.heading)
+            parts.push('## ' + s.heading);
+        for (const b of s.blocks) {
+            if ('text' in b && typeof b.text === 'string') {
+                parts.push(b.text);
+            }
+            else if ('summary' in b) {
+                parts.push('[' + b.kind + ': '
+                    + b.summary + ']');
+            }
+        }
+    }
+    const joined = parts.join('\n');
+    if (joined.length <= FLATTEN_MAX_CHARS) {
+        return { text: joined, truncated: false };
+    }
+    return {
+        text: joined.slice(0, FLATTEN_MAX_CHARS) + '\n\n[... truncated, original was ' + joined.length + ' chars]',
+        truncated: true,
+    };
+}
+export function recordIngest(doc) {
+    const flat = flattenDocument(doc);
+    const session = {
+        doc_id: doc.id,
+        doc,
+        flat_text: flat.text,
+        ingested_at: new Date().toISOString(),
+    };
+    SESSIONS.set(doc.id, session);
+    return session;
+}
+export function getIngest(docId) {
+    return SESSIONS.get(docId) ?? null;
+}
+export function setExtraction(docId, extraction) {
+    const s = SESSIONS.get(docId);
+    if (!s)
+        throw new Error('ingest_session: no session for ' + docId);
+    s.extraction = extraction;
+}
+export function setPlan(docId, plan) {
+    const s = SESSIONS.get(docId);
+    if (!s)
+        throw new Error('ingest_session: no session for ' + docId);
+    s.plan = plan;
+}
+export function setScaffold(docId, report) {
+    const s = SESSIONS.get(docId);
+    if (!s)
+        throw new Error('ingest_session: no session for ' + docId);
+    s.scaffold = report;
+}
+export function clearScaffold(docId) {
+    const s = SESSIONS.get(docId);
+    if (!s)
+        throw new Error('ingest_session: no session for ' + docId);
+    delete s.scaffold;
+}
+export function listIngest() {
+    return Array.from(SESSIONS.values()).map((s) => ({
+        doc_id: s.doc_id,
+        title: s.doc.title,
+        format: s.doc.format,
+        ingested_at: s.ingested_at,
+        has_extraction: s.extraction !== undefined,
+        has_plan: s.plan !== undefined,
+        has_scaffold: s.scaffold !== undefined,
+    }));
+}
+/** Test seam. */
+export function _resetIngestForTests() {
+    SESSIONS.clear();
+}
+//# sourceMappingURL=ingest_session.js.map

package/dist/chat/ingest_session.js.map

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

package/dist/chat/panel.d.ts

@@ -0,0 +1,15 @@
+import { type SupportedLanguage } from '../i18n/index.js';
+export interface PanelConfig {
+    projectRoot: string;
+    projectName: string;
+    port: number;
+    /** Language override for this single render. When provided
+     *  (e.g. resolved from a per-request cookie or query string)
+     *  it makes the render stateless -- two concurrent requests
+     *  with different languages do NOT step on each other. When
+     *  omitted, falls back to the server-wide current_language
+     *  for back-compat. */
+    lang?: SupportedLanguage;
+}
+export declare function renderPanelHtml(cfg: PanelConfig): string;
+//# sourceMappingURL=panel.d.ts.map

package/dist/chat/panel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"panel.d.ts","sourceRoot":"","sources":["../../src/chat/panel.ts"],"names":[],"mappings":"AAkBA,OAAO,EAEL,KAAK,iBAAiB,EAEvB,MAAM,kBAAkB,CAAC;AAG1B,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb;;;;;2BAKuB;IACvB,IAAI,CAAC,EAAE,iBAAiB,CAAC;CAC1B;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CA49CxD"}