@nac3/forge-cli 0.2.0-alpha.9 → 1.0.0

package/dist/core/desktop_open.js

@@ -0,0 +1,114 @@
+/**
+ * desktop.open -- open a document or URL in its NATIVE OS application.
+ *
+ *   .xlsx/.xls/.csv  -> Excel (or the system spreadsheet app)
+ *   .docx/.doc       -> Word
+ *   .pdf             -> the PDF viewer
+ *   .pptx/.ppt       -> PowerPoint
+ *   http(s) URL      -> the default browser (e.g. a Google Sheets link)
+ *   .gsheet/.gdoc    -> Google Drive shortcut files carry a URL -> browser
+ *
+ * Cross-platform: Windows `start`, macOS `open`, Linux `xdg-open`.
+ *
+ * This is for SHOWING a file to the user in the right tool -- NOT for
+ * parsing data (use office.excel.read / office.word.read for that).
+ * It only makes sense when Forge runs on the user's own machine (a
+ * local GUI app gets launched).
+ *
+ * Security: files are gated to the project root, and executable /
+ * script extensions are refused outright (start/ShellExecute would
+ * RUN them). URLs are limited to http(s).
+ *
+ * ASCII-only.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+/* Extensions start/ShellExecute would EXECUTE -- never open these. */
+const DANGEROUS_EXT = new Set([
+    '.exe', '.bat', '.cmd', '.com', '.scr', '.msi', '.msp', '.ps1', '.psm1',
+    '.vbs', '.vbe', '.jse', '.wsf', '.wsh', '.sh', '.bash', '.zsh', '.app',
+    '.jar', '.reg', '.lnk', '.hta', '.cpl', '.dll', '.pif', '.gadget', '.inf',
+]);
+/* Common office / document extensions -> a friendly app hint. */
+const APP_HINT = {
+    '.xlsx': 'Excel', '.xls': 'Excel', '.xlsm': 'Excel', '.csv': 'Excel', '.ods': 'spreadsheet',
+    '.docx': 'Word', '.doc': 'Word', '.odt': 'Word', '.rtf': 'Word',
+    '.pptx': 'PowerPoint', '.ppt': 'PowerPoint', '.odp': 'PowerPoint',
+    '.pdf': 'PDF viewer', '.txt': 'text editor', '.md': 'editor',
+    '.html': 'browser', '.htm': 'browser', '.png': 'image viewer', '.jpg': 'image viewer',
+};
+function appHintFor(ext) {
+    return APP_HINT[ext] || 'the default app';
+}
+/** Launch the OS shell-open for a file path or URL. Detached + unref
+ *  so the launched app never blocks the Forge process. */
+function shellOpen(target) {
+    if (process.platform === 'win32') {
+        /* cmd start: the first quoted arg is the window TITLE (empty), then
+         * the target. Quoting handles spaces. */
+        return { command: 'cmd', args: ['/c', 'start', '', target] };
+    }
+    if (process.platform === 'darwin') {
+        return { command: 'open', args: [target] };
+    }
+    return { command: 'xdg-open', args: [target] };
+}
+function launch(target) {
+    const { command, args } = shellOpen(target);
+    const child = spawn(command, args, { detached: true, stdio: 'ignore', windowsHide: false });
+    child.unref();
+}
+/** Resolve a Google Drive shortcut file (.gsheet/.gdoc/.gslides), which
+ *  is a small JSON carrying the doc URL. Returns the URL or null. */
+function googleShortcutUrl(absPath) {
+    try {
+        const j = JSON.parse(readFileSync(absPath, 'utf-8'));
+        if (j.url && /^https?:\/\//i.test(j.url))
+            return j.url;
+        const id = j.doc_id || j.resource_id;
+        if (id)
+            return 'https://docs.google.com/spreadsheets/d/' + encodeURIComponent(id) + '/edit';
+    }
+    catch { /* not a JSON shortcut */ }
+    return null;
+}
+/** Open `target` (a project-relative/absolute path, or an http(s) URL)
+ *  in its native application. `launchFn` is injectable for tests. */
+export async function openNative(target, projectRoot, launchFn = launch) {
+    const t = String(target ?? '').trim();
+    if (!t)
+        return { ok: false, error: 'target is required' };
+    /* URL -> browser. Only http(s) (no file://, javascript:, etc.). */
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(t) || /^[a-z]+:/i.test(t)) {
+        if (!/^https?:\/\//i.test(t)) {
+            return { ok: false, error: 'only http(s) URLs are allowed (got a different scheme)' };
+        }
+        launchFn(t);
+        return { ok: true, opened: t, kind: 'url', app_hint: 'browser' };
+    }
+    /* File path -- gate to the project root. */
+    const abs = path.resolve(path.isAbsolute(t) ? t : path.join(projectRoot, t));
+    const rel = path.relative(path.resolve(projectRoot), abs);
+    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+        return { ok: false, error: 'path escapes the project root: ' + t };
+    }
+    if (!existsSync(abs))
+        return { ok: false, error: 'file not found: ' + rel };
+    const ext = path.extname(abs).toLowerCase();
+    if (DANGEROUS_EXT.has(ext)) {
+        return { ok: false, error: 'refused: "' + ext + '" is an executable/script extension, not a document' };
+    }
+    /* Google Drive shortcut -> open its URL in the browser. */
+    if (ext === '.gsheet' || ext === '.gdoc' || ext === '.gslides') {
+        const url = googleShortcutUrl(abs);
+        if (url) {
+            launchFn(url);
+            return { ok: true, opened: url, kind: 'url', app_hint: 'browser (Google)' };
+        }
+        return { ok: false, error: 'Google shortcut without a resolvable URL: ' + rel };
+    }
+    launchFn(abs);
+    return { ok: true, opened: rel, kind: 'file', app_hint: appHintFor(ext) };
+}
+//# sourceMappingURL=desktop_open.js.map

package/dist/core/desktop_open.js.map

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

package/dist/core/doctrine_resolver.d.ts

@@ -0,0 +1,23 @@
+/** Force-clear cache. Used by tests. */
+export declare function _clearDoctrineCache(): void;
+export interface DoctrineResult {
+    ok: true;
+    slug: string;
+    content: string;
+    source: string;
+}
+export interface DoctrineError {
+    ok: false;
+    slug: string;
+    error: string;
+    available?: string[];
+}
+/** Fetch a single doctrine. Returns the markdown content. */
+export declare function getDoctrine(slug: string): Promise<DoctrineResult | DoctrineError>;
+/** Fetch multiple doctrines in one round (bulk). Same return shape
+ *  as nac3 discover-schemas: keyed object. */
+export declare function getDoctrines(slugs: string[]): Promise<Record<string, DoctrineResult | DoctrineError>>;
+/** List the available doctrine slugs (markdown files in any
+ *  doctrine dir). Used for the discovery verb. */
+export declare function listDoctrineSlugs(): Promise<string[]>;
+//# sourceMappingURL=doctrine_resolver.d.ts.map

package/dist/core/doctrine_resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctrine_resolver.d.ts","sourceRoot":"","sources":["../../src/core/doctrine_resolver.ts"],"names":[],"mappings":"AAsEA,wCAAwC;AACxC,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,KAAK,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,6DAA6D;AAC7D,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,aAAa,CAAC,CAiBvF;AAED;8CAC8C;AAC9C,wBAAsB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,GAAG,aAAa,CAAC,CAAC,CAM3G;AAED;kDACkD;AAClD,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAW3D"}

package/dist/core/doctrine_resolver.js

@@ -0,0 +1,108 @@
+/**
+ * Doctrine resolver (alpha.59z.0).
+ *
+ * On-demand fetch of docrine blocks (long-form rules + reference
+ * material) so the system prompt does not have to carry them
+ * every turn. Same pattern as yujin.nac3.discover-schemas: the
+ * LLM sees a short pointer + calls the resolver when it needs
+ * the full text.
+ *
+ * Storage: docs/doctrine/{slug}.md -- one markdown file per
+ * doctrine block. Authored manually. Cached in-process; cache
+ * invalidates by mtime on each lookup (so dev iterations don't
+ * require restart).
+ *
+ * Known slugs (alpha.59z.0):
+ *  - workflow        -- 6 phases / 18 steps reference
+ *  - nac3-attrs      -- the 5 data-nac-* HTML attributes
+ *  - g-doc           -- generation doctrine for adopter apps
+ *
+ * More slugs added in alpha.59z.4 / .5 (pizarron-condensed,
+ * r8-modal, gates).
+ *
+ * ASCII-only.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const DOCTRINE_DIR_HINTS = [
+    /* dist/core -> ../../docs/doctrine (repo root) */
+    path.resolve(__dirname, '..', '..', 'docs', 'doctrine'),
+    /* dist/core -> ../docs/doctrine (after copy_qa_assets bundles them) */
+    path.resolve(__dirname, '..', 'docs', 'doctrine'),
+    /* src/core -> ../../docs/doctrine */
+    path.resolve(__dirname, '..', '..', 'docs', 'doctrine'),
+    /* cwd / docs/doctrine */
+    path.resolve(process.cwd(), 'docs', 'doctrine'),
+];
+const _cache = new Map();
+/** Slug must be kebab-case, no path separators. Defensive against
+ *  path traversal -- the resolver only opens files inside the
+ *  doctrine dirs above. */
+function isValidSlug(slug) {
+    return /^[a-z0-9][a-z0-9-]{0,60}$/.test(slug);
+}
+async function resolveDoctrineFile(slug) {
+    for (const dir of DOCTRINE_DIR_HINTS) {
+        const p = path.join(dir, slug + '.md');
+        try {
+            const stat = await fs.stat(p);
+            if (stat.isFile()) {
+                return { path: p, mtimeMs: stat.mtimeMs };
+            }
+        }
+        catch { /* try next */ }
+    }
+    return null;
+}
+/** Force-clear cache. Used by tests. */
+export function _clearDoctrineCache() {
+    _cache.clear();
+}
+/** Fetch a single doctrine. Returns the markdown content. */
+export async function getDoctrine(slug) {
+    if (!isValidSlug(slug)) {
+        return { ok: false, slug, error: 'invalid slug -- must be kebab-case, max 60 chars' };
+    }
+    const file = await resolveDoctrineFile(slug);
+    if (!file) {
+        const list = await listDoctrineSlugs();
+        return { ok: false, slug, error: 'doctrine not found', available: list };
+    }
+    /* Cache check by mtime. */
+    const cached = _cache.get(slug);
+    if (cached && cached.mtimeMs === file.mtimeMs && cached.resolvedPath === file.path) {
+        return { ok: true, slug, content: cached.content, source: file.path };
+    }
+    const content = await fs.readFile(file.path, 'utf-8');
+    _cache.set(slug, { content, mtimeMs: file.mtimeMs, resolvedPath: file.path });
+    return { ok: true, slug, content, source: file.path };
+}
+/** Fetch multiple doctrines in one round (bulk). Same return shape
+ *  as nac3 discover-schemas: keyed object. */
+export async function getDoctrines(slugs) {
+    const out = {};
+    for (const s of slugs) {
+        out[s] = await getDoctrine(s);
+    }
+    return out;
+}
+/** List the available doctrine slugs (markdown files in any
+ *  doctrine dir). Used for the discovery verb. */
+export async function listDoctrineSlugs() {
+    const seen = new Set();
+    for (const dir of DOCTRINE_DIR_HINTS) {
+        try {
+            const files = await fs.readdir(dir);
+            for (const f of files) {
+                if (f.endsWith('.md'))
+                    seen.add(f.slice(0, -3));
+            }
+        }
+        catch { /* dir missing -- ok */ }
+    }
+    return Array.from(seen).sort();
+}
+//# sourceMappingURL=doctrine_resolver.js.map

package/dist/core/doctrine_resolver.js.map

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

package/dist/core/error_catalog.d.ts

@@ -0,0 +1,80 @@
+/**
+ * F104 -- Error UX Discipline catalog (alpha.59z.15: i18n-aware).
+ *
+ * Every Forge error surface (chat panel, CLI stderr, modal toast,
+ * SSE event, worker HTTP response) MUST produce a ForgeError
+ * object with the 4 mandatory fields below + optional cmd / docs.
+ *
+ * alpha.59z.15 -- catalog entries reference i18n keys instead of
+ * Spanish-only strings. renderForgeError() accepts an optional
+ * `lang` parameter and resolves via tForLang() with Spanish
+ * fallback. The worker emits {code, context} only; the client
+ * hydrates with its user language.
+ *
+ * Codes are append-only. Catalog keys live in
+ * src/i18n/catalogs/<lang>.json under "error.<code>.what|why|fix|cmd"
+ * and "error_ui.*" for the formatter labels.
+ */
+import { type SupportedLanguage } from '../i18n/index.js';
+export type ForgeErrorSeverity = 'info' | 'warning' | 'error' | 'fatal';
+export interface ForgeError {
+    /** Stable machine code. Append-only. Used by telemetry + docs. */
+    code: string;
+    /** Human-readable summary of what happened. Localised. */
+    what: string;
+    /** Root cause -- why this happened. Localised. */
+    why: string;
+    /** Concrete action the user can take to fix or work around. Localised. */
+    fix: string;
+    /** Severity for renderer styling. */
+    severity: ForgeErrorSeverity;
+    /** Optional exact CLI command the user can copy + run. Localised. */
+    cmd?: string;
+    /** Optional path to local doc (resolved by the panel to docs/errors/<code>.html). */
+    docs_path?: string;
+    /** Optional seconds-until-retry-allowed (e.g. for rate limits). */
+    retry_in_sec?: number;
+    /** Optional context: variables interpolated into what/why/fix at render time. */
+    context?: Record<string, string | number | boolean>;
+}
+/** Frontier tier monthly token cap reached (managed brain only). */
+export declare const E_CAP_FRONTIER_EXHAUSTED = "E_CAP_FRONTIER_EXHAUSTED";
+/** Eco tier monthly token cap reached (managed brain only). */
+export declare const E_CAP_ECO_EXHAUSTED = "E_CAP_ECO_EXHAUSTED";
+/** The tier requested is not enabled on this plan. */
+export declare const E_TIER_NOT_IN_PLAN = "E_TIER_NOT_IN_PLAN";
+/** The LLM response was truncated -- ran out of output tokens mid-reply. */
+export declare const E_RESPONSE_TRUNCATED = "E_RESPONSE_TRUNCATED";
+/** The R8 modal trace_id is stale or has no pending approval. */
+export declare const E_MODAL_TRACE_STALE = "E_MODAL_TRACE_STALE";
+/** BYOK key required but missing from the Vault. */
+export declare const E_BYOK_KEY_MISSING = "E_BYOK_KEY_MISSING";
+/** The HITO 4 worker is unreachable (network / DNS / outage). */
+export declare const E_WORKER_UNREACHABLE = "E_WORKER_UNREACHABLE";
+/** Vault decryption failed -- master key wrong or file corrupted. */
+export declare const E_VAULT_DECRYPT_FAILED = "E_VAULT_DECRYPT_FAILED";
+/** shell.exec was classified destructive but user rejected the modal. */
+export declare const E_SHELL_EXEC_REJECTED = "E_SHELL_EXEC_REJECTED";
+/** No active project registered + the verb requires a project root. */
+export declare const E_PROJECT_NOT_REGISTERED = "E_PROJECT_NOT_REGISTERED";
+/** Build a ForgeError from a code + context.
+ *
+ *  @param code     Stable error code (E_*).
+ *  @param context  Variables interpolated into what/why/fix/cmd
+ *                  (e.g. {plan, cap, used, tier, ...}).
+ *  @param lang     Optional target language. Falls back to the
+ *                  current i18n session language; falls back
+ *                  again to 'es' (the canonical source). */
+export declare function renderForgeError(code: string, context?: Record<string, string | number | boolean>, lang?: SupportedLanguage): ForgeError;
+/** Return the list of registered codes (for tests / docs generator). */
+export declare function listErrorCodes(): string[];
+/** Type guard. */
+export declare function isForgeError(x: unknown): x is ForgeError;
+/** Get the catalog entry metadata for a code (severity, docs path, etc).
+ *  Returns null if the code is unknown. */
+export declare function getCatalogEntry(code: string): {
+    severity: ForgeErrorSeverity;
+    docs_path: string;
+    has_cmd: boolean;
+} | null;
+//# sourceMappingURL=error_catalog.d.ts.map

package/dist/core/error_catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error_catalog.d.ts","sourceRoot":"","sources":["../../src/core/error_catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAY,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAEpE,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;AAExE,MAAM,WAAW,UAAU;IACzB,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC;IACZ,qCAAqC;IACrC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,qEAAqE;IACrE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CACrD;AAMD,oEAAoE;AACpE,eAAO,MAAM,wBAAwB,6BAA6B,CAAC;AACnE,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,wBAAwB,CAAC;AACzD,sDAAsD;AACtD,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AACvD,4EAA4E;AAC5E,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAC3D,iEAAiE;AACjE,eAAO,MAAM,mBAAmB,wBAAwB,CAAC;AACzD,oDAAoD;AACpD,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AACvD,iEAAiE;AACjE,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAC3D,qEAAqE;AACrE,eAAO,MAAM,sBAAsB,2BAA2B,CAAC;AAC/D,yEAAyE;AACzE,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAC7D,uEAAuE;AACvE,eAAO,MAAM,wBAAwB,6BAA6B,CAAC;AA2EnE;;;;;;;4DAO4D;AAC5D,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAM,EACvD,IAAI,CAAC,EAAE,iBAAiB,GACvB,UAAU,CA4BZ;AAcD,wEAAwE;AACxE,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAEzC;AAED,kBAAkB;AAClB,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,UAAU,CAOxD;AAED;2CAC2C;AAC3C,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,kBAAkB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAI1H"}

package/dist/core/error_catalog.js

@@ -0,0 +1,168 @@
+/**
+ * F104 -- Error UX Discipline catalog (alpha.59z.15: i18n-aware).
+ *
+ * Every Forge error surface (chat panel, CLI stderr, modal toast,
+ * SSE event, worker HTTP response) MUST produce a ForgeError
+ * object with the 4 mandatory fields below + optional cmd / docs.
+ *
+ * alpha.59z.15 -- catalog entries reference i18n keys instead of
+ * Spanish-only strings. renderForgeError() accepts an optional
+ * `lang` parameter and resolves via tForLang() with Spanish
+ * fallback. The worker emits {code, context} only; the client
+ * hydrates with its user language.
+ *
+ * Codes are append-only. Catalog keys live in
+ * src/i18n/catalogs/<lang>.json under "error.<code>.what|why|fix|cmd"
+ * and "error_ui.*" for the formatter labels.
+ */
+import { tForLang } from '../i18n/index.js';
+/* ===================================================================
+ * Error code catalog
+ * ================================================================ */
+/** Frontier tier monthly token cap reached (managed brain only). */
+export const E_CAP_FRONTIER_EXHAUSTED = 'E_CAP_FRONTIER_EXHAUSTED';
+/** Eco tier monthly token cap reached (managed brain only). */
+export const E_CAP_ECO_EXHAUSTED = 'E_CAP_ECO_EXHAUSTED';
+/** The tier requested is not enabled on this plan. */
+export const E_TIER_NOT_IN_PLAN = 'E_TIER_NOT_IN_PLAN';
+/** The LLM response was truncated -- ran out of output tokens mid-reply. */
+export const E_RESPONSE_TRUNCATED = 'E_RESPONSE_TRUNCATED';
+/** The R8 modal trace_id is stale or has no pending approval. */
+export const E_MODAL_TRACE_STALE = 'E_MODAL_TRACE_STALE';
+/** BYOK key required but missing from the Vault. */
+export const E_BYOK_KEY_MISSING = 'E_BYOK_KEY_MISSING';
+/** The HITO 4 worker is unreachable (network / DNS / outage). */
+export const E_WORKER_UNREACHABLE = 'E_WORKER_UNREACHABLE';
+/** Vault decryption failed -- master key wrong or file corrupted. */
+export const E_VAULT_DECRYPT_FAILED = 'E_VAULT_DECRYPT_FAILED';
+/** shell.exec was classified destructive but user rejected the modal. */
+export const E_SHELL_EXEC_REJECTED = 'E_SHELL_EXEC_REJECTED';
+/** No active project registered + the verb requires a project root. */
+export const E_PROJECT_NOT_REGISTERED = 'E_PROJECT_NOT_REGISTERED';
+const CATALOG = {
+    [E_CAP_FRONTIER_EXHAUSTED]: {
+        key_prefix: 'error.cap_frontier_exhausted',
+        has_cmd: true, severity: 'error',
+        docs_path: 'docs/errors/E_CAP_FRONTIER_EXHAUSTED.html',
+    },
+    [E_CAP_ECO_EXHAUSTED]: {
+        key_prefix: 'error.cap_eco_exhausted',
+        has_cmd: true, severity: 'error',
+        docs_path: 'docs/errors/E_CAP_ECO_EXHAUSTED.html',
+    },
+    [E_TIER_NOT_IN_PLAN]: {
+        key_prefix: 'error.tier_not_in_plan',
+        has_cmd: true, severity: 'error',
+        docs_path: 'docs/errors/E_TIER_NOT_IN_PLAN.html',
+    },
+    [E_RESPONSE_TRUNCATED]: {
+        key_prefix: 'error.response_truncated',
+        has_cmd: true, severity: 'warning',
+        docs_path: 'docs/errors/E_RESPONSE_TRUNCATED.html',
+    },
+    [E_MODAL_TRACE_STALE]: {
+        key_prefix: 'error.modal_trace_stale',
+        has_cmd: true, severity: 'warning',
+        docs_path: 'docs/errors/E_MODAL_TRACE_STALE.html',
+    },
+    [E_BYOK_KEY_MISSING]: {
+        key_prefix: 'error.byok_key_missing',
+        has_cmd: true, severity: 'error',
+        docs_path: 'docs/errors/E_BYOK_KEY_MISSING.html',
+    },
+    [E_WORKER_UNREACHABLE]: {
+        key_prefix: 'error.worker_unreachable',
+        has_cmd: true, severity: 'error',
+        docs_path: 'docs/errors/E_WORKER_UNREACHABLE.html',
+    },
+    [E_VAULT_DECRYPT_FAILED]: {
+        key_prefix: 'error.vault_decrypt_failed',
+        has_cmd: true, severity: 'fatal',
+        docs_path: 'docs/errors/E_VAULT_DECRYPT_FAILED.html',
+    },
+    [E_SHELL_EXEC_REJECTED]: {
+        key_prefix: 'error.shell_exec_rejected',
+        has_cmd: false, severity: 'info',
+        docs_path: 'docs/errors/E_SHELL_EXEC_REJECTED.html',
+    },
+    [E_PROJECT_NOT_REGISTERED]: {
+        key_prefix: 'error.project_not_registered',
+        has_cmd: true, severity: 'error',
+        docs_path: 'docs/errors/E_PROJECT_NOT_REGISTERED.html',
+    },
+};
+/* ===================================================================
+ * Public API
+ * ================================================================ */
+/** Build a ForgeError from a code + context.
+ *
+ *  @param code     Stable error code (E_*).
+ *  @param context  Variables interpolated into what/why/fix/cmd
+ *                  (e.g. {plan, cap, used, tier, ...}).
+ *  @param lang     Optional target language. Falls back to the
+ *                  current i18n session language; falls back
+ *                  again to 'es' (the canonical source). */
+export function renderForgeError(code, context = {}, lang) {
+    const entry = CATALOG[code];
+    if (!entry) {
+        /* Unknown code -- emit a stub from the i18n catalog so the
+         * message is also localised. */
+        return {
+            code,
+            what: lang ? tForLang(lang, 'error_ui.unknown.what', { code }) : tForLang('es', 'error_ui.unknown.what', { code }),
+            why: lang ? tForLang(lang, 'error_ui.unknown.why', { code }) : tForLang('es', 'error_ui.unknown.why', { code }),
+            fix: lang ? tForLang(lang, 'error_ui.unknown.fix', { code }) : tForLang('es', 'error_ui.unknown.fix', { code }),
+            severity: 'error',
+            context,
+        };
+    }
+    const params = ctxToParams(context);
+    const resolveKey = (suffix) => lang ? tForLang(lang, entry.key_prefix + '.' + suffix, params)
+        : tForLang('es', entry.key_prefix + '.' + suffix, params);
+    return {
+        code,
+        what: resolveKey('what'),
+        why: resolveKey('why'),
+        fix: resolveKey('fix'),
+        cmd: entry.has_cmd ? resolveKey('cmd') : undefined,
+        severity: entry.severity,
+        docs_path: entry.docs_path,
+        context,
+    };
+}
+/** The i18n interpolate() helper accepts string | number; coerce
+ *  booleans to "true"/"false" so callers can pass {is_admin: true}
+ *  without TypeScript yelling. */
+function ctxToParams(context) {
+    const out = {};
+    for (const [k, v] of Object.entries(context)) {
+        if (typeof v === 'boolean')
+            out[k] = v ? 'true' : 'false';
+        else
+            out[k] = v;
+    }
+    return out;
+}
+/** Return the list of registered codes (for tests / docs generator). */
+export function listErrorCodes() {
+    return Object.keys(CATALOG);
+}
+/** Type guard. */
+export function isForgeError(x) {
+    if (!x || typeof x !== 'object')
+        return false;
+    const e = x;
+    return typeof e.code === 'string'
+        && typeof e.what === 'string'
+        && typeof e.why === 'string'
+        && typeof e.fix === 'string';
+}
+/** Get the catalog entry metadata for a code (severity, docs path, etc).
+ *  Returns null if the code is unknown. */
+export function getCatalogEntry(code) {
+    const entry = CATALOG[code];
+    if (!entry)
+        return null;
+    return { severity: entry.severity, docs_path: entry.docs_path, has_cmd: entry.has_cmd };
+}
+//# sourceMappingURL=error_catalog.js.map

package/dist/core/error_catalog.js.map

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

package/dist/core/error_formatter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * F104 -- Renderers for ForgeError surfaces.
+ *
+ * Three surfaces:
+ *   1. CLI stderr: formatForgeErrorCli(err) -> ANSI-coloured block.
+ *   2. Chat panel HTML: formatForgeErrorHtml(err) -> red block with
+ *      copy-cmd button. Safe HTML (escaped).
+ *   3. JSON wire (SSE / HTTP body): formatForgeErrorJson(err) ->
+ *      the ForgeError object itself, ready to JSON.stringify.
+ *
+ * ASCII-only.
+ */
+import type { ForgeError } from './error_catalog.js';
+import { type SupportedLanguage } from '../i18n/index.js';
+/** Format a ForgeError for CLI stderr output.
+ *  @param err   The error.
+ *  @param lang  Optional UI language for the labels. Default 'es'. */
+export declare function formatForgeErrorCli(err: ForgeError, lang?: SupportedLanguage): string;
+/** Format a ForgeError as safe HTML for the chat panel. The panel
+ *  is expected to have CSS for .forge-err / .forge-err--{severity}
+ *  / .forge-err__copy-btn etc; this returns ONLY the markup.
+ *  @param err   The error.
+ *  @param lang  Optional UI language for the labels. Default 'es'. */
+export declare function formatForgeErrorHtml(err: ForgeError, lang?: SupportedLanguage): string;
+/** Strip undefined keys for clean JSON serialisation. */
+export declare function formatForgeErrorJson(err: ForgeError): Record<string, unknown>;
+/** Serialise a ForgeError as a Server-Sent-Events block.
+ *  Stream consumers should listen for event: forge_error. */
+export declare function forgeErrorAsSseEvent(err: ForgeError): string;
+//# sourceMappingURL=error_formatter.d.ts.map

package/dist/core/error_formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error_formatter.d.ts","sourceRoot":"","sources":["../../src/core/error_formatter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAsB,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAY,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AA+BpE;;sEAEsE;AACtE,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,GAAE,iBAAwB,GAAG,MAAM,CA4B3F;AAwBD;;;;sEAIsE;AACtE,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,GAAE,iBAAwB,GAAG,MAAM,CA4B5F;AAMD,yDAAyD;AACzD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAa7E;AAMD;6DAC6D;AAC7D,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAG5D"}