@synap-core/cli 1.11.0 → 1.13.0

package/dist/lib/capture-structure.js

@@ -13,10 +13,126 @@
  * ACTUALLY returned (applied vs proposed vs nothing-created) instead of guessing
  * off the planned proposal count.
  *
- * Kept local to the CLI (not imported from @synap/hub-rest-client) because the
+ * Kept local to the CLI (not imported from @synap-core/hub-rest-client) because the
  * CLI resolves the SDK via its built dist — the same reason the previous local
  * mirrors existed. This is now the ONE mirror instead of two.
  */
+/**
+ * ADVISORY hints only — an AI pick proposes, it never places data. A user's
+ * deliberate choice (`--workspace` / `--project`) is NOT a hint.
+ */
+export function captureExecuteRoutingHints(structured) {
+    return {
+        aiWorkspaceId: structured.targetWorkspaceId,
+        aiWorkspaceConfidence: structured.targetWorkspaceConfidence,
+        aiWorkspaceReason: structured.targetWorkspaceReason,
+        aiWorkspaceDecision: structured.targetWorkspaceDecision,
+        aiProjectId: structured.targetProjectId,
+        aiProjectConfidence: structured.targetProjectConfidence,
+        aiProjectReason: structured.targetProjectReason,
+    };
+}
+/** The AI's workspace-side hints only (drop them when the user pinned a workspace). */
+export function workspaceRoutingHints(structured) {
+    const { aiWorkspaceId, aiWorkspaceConfidence, aiWorkspaceReason, aiWorkspaceDecision } = captureExecuteRoutingHints(structured);
+    return { aiWorkspaceId, aiWorkspaceConfidence, aiWorkspaceReason, aiWorkspaceDecision };
+}
+/** The AI's project-side hints only (drop them when the user pinned a project). */
+export function projectRoutingHints(structured) {
+    const { aiProjectId, aiProjectConfidence, aiProjectReason } = captureExecuteRoutingHints(structured);
+    return { aiProjectId, aiProjectConfidence, aiProjectReason };
+}
+/** THE destination rule — see the shared type's docblock. */
+export function deriveWorkspacePlacementView(placement, selection, opts) {
+    if (!placement) {
+        return {
+            destination: { workspaceId: null, workspaceName: null },
+            aiSuggested: false,
+            alternatives: [],
+            canRemove: false,
+            execute: {},
+        };
+    }
+    const suggestion = placement.suggestion;
+    const base = {
+        workspaceId: placement.workspaceId,
+        workspaceName: placement.workspaceName,
+    };
+    const pinBase = () => placement.deterministic && placement.workspaceId
+        ? { targetWorkspaceId: placement.workspaceId }
+        : {};
+    if (selection.kind === "chosen") {
+        return {
+            destination: {
+                workspaceId: selection.workspaceId,
+                workspaceName: selection.workspaceName,
+            },
+            aiSuggested: false,
+            alternatives: suggestion?.alternatives ?? [],
+            canRemove: false,
+            execute: {
+                targetWorkspaceId: selection.workspaceId,
+                ...(suggestion
+                    ? {
+                        workspaceChoice: selection.workspaceId === suggestion.workspaceId ? "accepted" : "changed",
+                    }
+                    : {}),
+            },
+        };
+    }
+    if (selection.kind === "removed" || !suggestion || !opts.interactive) {
+        const choice = !suggestion
+            ? undefined
+            : selection.kind === "removed"
+                ? "removed"
+                : "ignored";
+        return {
+            destination: base,
+            aiSuggested: false,
+            alternatives: suggestion?.alternatives ?? [],
+            canRemove: false,
+            execute: {
+                ...(choice === "removed" && placement.workspaceId
+                    ? { targetWorkspaceId: placement.workspaceId }
+                    : pinBase()),
+                ...(choice ? { workspaceChoice: choice } : {}),
+            },
+        };
+    }
+    return {
+        destination: {
+            workspaceId: suggestion.workspaceId,
+            workspaceName: suggestion.workspaceName,
+        },
+        aiSuggested: true,
+        alternatives: suggestion.alternatives,
+        canRemove: true,
+        execute: { targetWorkspaceId: suggestion.workspaceId, workspaceChoice: "accepted" },
+    };
+}
+/**
+ * The headless placement fields the CLI sends to `/capture/execute` — the ONE
+ * door, so the CLI can never hand-roll a destination. Headless ⇒ an AI
+ * suggestion stays a proposal; a deterministic placement is pinned explicitly.
+ */
+export function headlessPlacementFields(structured) {
+    return deriveWorkspacePlacementView(structured.placement, { kind: "default" }, {
+        interactive: false,
+    }).execute;
+}
+/**
+ * The workspace line for a structure result: the NAME the pod resolved (never
+ * a raw id when a name is known) and the confidence percent, once.
+ */
+export function formatWorkspaceRouting(result) {
+    const label = result.targetWorkspaceName || result.targetWorkspaceId;
+    if (!label)
+        return null;
+    const conf = typeof result.targetWorkspaceConfidence === "number"
+        ? ` (${Math.round(result.targetWorkspaceConfidence * 100)}%)`
+        : "";
+    return `${label}${conf}`;
+}
 /**
  * Interpret a /capture/execute response HONESTLY. Distinguishes applied vs
  * proposed vs nothing-created and surfaces the real proposal/review handle so
@@ -33,25 +149,147 @@ export function readCaptureExecute(res) {
         relationsCreated: Array.isArray(res.relations) ? res.relations.length : 0,
         proposalId: res.proposalId ? String(res.proposalId) : undefined,
         reviewUrl: res.reviewUrl ? String(res.reviewUrl) : undefined,
-        movedToWorkspace: res.movedToWorkspace
-            ? String(res.movedToWorkspace)
-            : undefined,
+        ...(res.pendingWorkspaceSwitch?.suggestedWorkspaceId
+            ? { pendingWorkspaceSwitch: res.pendingWorkspaceSwitch }
+            : {}),
     };
 }
-/** True when the structure step degraded (IS structurer unavailable). */
+/**
+ * The one line every CLI surface prints for an outstanding workspace
+ * suggestion. It says what to DO (re-file with `--workspace`), because the pod
+ * moved nothing — the old "→ filed into workspace X" line reported a move that
+ * never happened.
+ */
+export function formatPendingWorkspaceSwitch(outcome) {
+    const s = outcome.pendingWorkspaceSwitch;
+    if (!s)
+        return null;
+    const label = s.suggestedWorkspaceName || s.suggestedWorkspaceId;
+    const conf = typeof s.confidence === "number" ? ` (${Math.round(s.confidence * 100)}%)` : "";
+    return `AI suggests workspace ${label}${conf} — nothing was moved. Re-file with --workspace ${s.suggestedWorkspaceId} to accept.`;
+}
+/** True when the structure step degraded (nothing usable came back). */
 export function isDegraded(res) {
     return res.degraded === true;
 }
 /**
- * The ONE degraded message. When the structurer is down the server returns a
- * generic `item` stand-in wrapping the raw text — but the CLI does NOT
- * materialize it (the browser does the same via `offlineFallback:false`). We
- * create nothing and tell the user, so a captured note is never silently
- * downgraded to an unstructured blob behind a "success" line. Retry when the
- * structurer is back.
+ * One line of honest copy for a degraded reason: WHAT happened, and WHAT TO DO.
+ *
+ * ── Why this is a second table, deliberately ────────────────────────────────
+ * `@synap-core/capture-pipeline`'s `describeDegradedReason` is the existing
+ * one-door for this copy, and it is the RIGHT door — but the CLI is a separate
+ * pnpm workspace whose only Synap runtime dependencies are
+ * `@synap-core/hub-rest-client` (a file: link into synap-backend) and
+ * `@synap-core/workspace-templates`. It cannot reach a `synap-app` package
+ * without a package.json/lockfile change. Same reason the `StructureResult`
+ * mirror above is local.
+ *
+ * So: the `title` half is COPIED VERBATIM from `describeDegradedReason` and
+ * pinned by a parity test (`test/degraded-message-honesty.test.ts`) that reads
+ * the sibling repo's source, so the two can never drift on WHAT happened.
+ * The `detail` half is deliberately DIFFERENT, because the app's
+ * details end in "saved as a note in the meantime" and the CLI creates nothing
+ * at all — repeating the app's sentence here would be a new lie in place of the
+ * old one.
+ */
+export function describeDegradedReason(reason) {
+    switch (reason) {
+        case "is_auth_error":
+            return {
+                title: "AI intelligence isn't connected",
+                detail: "This pod's Intelligence Service rejected its credentials. Check them with `synap doctor`, then re-run this import.",
+            };
+        case "llm_budget_exceeded":
+            return {
+                title: "The monthly AI budget is used up",
+                detail: "The Intelligence Service's monthly token budget is spent, so nothing was created. Re-run this import once the budget resets next month or an operator raises it.",
+            };
+        case "pdf_scanned_needs_ocr":
+            return {
+                title: "This PDF has no text layer",
+                detail: "It's a scan, not typed text, so there is nothing to read yet. OCR it first, or keep the original with `synap import --keep-raw <file>`.",
+            };
+        case "pdf_missing_binary":
+            return {
+                title: "The PDF file wasn't available to read",
+                detail: "The bytes never reached the pod. Re-run the import for this file.",
+            };
+        case "vision_provider_not_configured":
+            return {
+                title: "Image reading isn't set up on this pod",
+                detail: "No vision-capable model is configured, so images can't be described. Configure one in Settings → Intelligence; until then keep the original with `synap import --keep-raw <file>`.",
+            };
+        case "vision_provider_failed":
+            return {
+                title: "Couldn't reach the AI that reads images",
+                detail: "A vision model is configured but the call failed (an outage, an unfunded key or an unknown model). Re-run this import later; `synap doctor` checks the pod.",
+            };
+        case "image_missing_binary":
+            return {
+                title: "The image file wasn't available to read",
+                detail: "The bytes never reached the pod. Re-run the import for this file.",
+            };
+        case "transcription_provider_not_configured":
+            return {
+                title: "Audio transcription isn't set up on this pod",
+                detail: "No transcription model is configured, so speech can't be turned into text. Configure one in Settings → Intelligence; until then keep the original with `synap import --keep-raw <file>`.",
+            };
+        case "audio_missing_binary":
+            return {
+                title: "The audio file wasn't available to read",
+                detail: "The bytes never reached the pod. Re-run the import for this file.",
+            };
+        case "docx_missing_binary":
+            return {
+                title: "The document file wasn't available to read",
+                detail: "The bytes never reached the pod. Re-run the import for this file.",
+            };
+        case "docx_empty":
+            return {
+                title: "This document has no extractable text",
+                detail: "It parsed cleanly but came back empty. Keep the original with `synap import --keep-raw <file>` if you still want it stored.",
+            };
+        case "html_empty":
+            return {
+                title: "This page has no extractable text",
+                detail: "It parsed cleanly but came back empty — often a JavaScript-rendered page. Save the readable text yourself and pass it to `synap capture`.",
+            };
+        case "unsupported_type":
+            return {
+                title: "This file type isn't supported yet",
+                detail: "Nothing can be extracted from it. Keep the bytes anyway with `synap import --keep-raw <file>`, or `synap upload <file>` to store it as a file entity.",
+            };
+        case "is_invalid_response":
+        case "is_empty_result":
+        case undefined:
+            return {
+                title: "AI structuring is unavailable right now",
+                detail: "Nothing was created. Re-run this import when the structurer is back.",
+            };
+        default:
+            // A reason this list hasn't been taught yet (the IS added one, and the
+            // wire type is an open string). Degrade gracefully — never print the raw
+            // token at a user, and never crash on it.
+            return {
+                title: "This input couldn't be read",
+                detail: "Nothing was created. Run `synap doctor` to check what this pod can extract.",
+            };
+    }
+}
+/**
+ * The ONE degraded message. The CLI does NOT materialize the server's generic
+ * `item` stand-in (the browser does the same via `offlineFallback:false`), so a
+ * captured note is never silently downgraded to an unstructured blob behind a
+ * "success" line.
+ *
+ * It used to print a single sentence for every cause — "AI structuring
+ * unavailable (is_empty_result) — nothing was created. Retry when it's back."
+ * — which leaked a raw machine token AND told users to retry states that never
+ * change (a pod with no vision provider is not going to come back). Now each
+ * reason says what actually happened and what to do about it.
  */
 export function degradedMessage(res) {
-    const why = res.degradedReason ? ` (${res.degradedReason})` : "";
-    return `AI structuring unavailable${why} — nothing was created. Retry when it's back.`;
+    const { title, detail } = describeDegradedReason(res.degradedReason);
+    return `${title} — nothing was created. ${detail}`;
 }
 //# sourceMappingURL=capture-structure.js.map

package/dist/lib/capture-structure.js.map

@@ -1 +1 @@
-{"version":3,"file":"capture-structure.js","sourceRoot":"","sources":["../../src/lib/capture-structure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAmGH;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAkB;IACnD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9D,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,KAAK,UAAU,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACtE,OAAO;QACL,QAAQ;QACR,eAAe,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM;QACxD,cAAc,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM;QACtD,gBAAgB,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACzE,UAAU,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS;QAC/D,SAAS,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS;QAC5D,gBAAgB,EAAE,GAAG,CAAC,gBAAgB;YACpC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC;YAC9B,CAAC,CAAC,SAAS;KACd,CAAC;AACJ,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,UAAU,CAAC,GAAoB;IAC7C,OAAO,GAAG,CAAC,QAAQ,KAAK,IAAI,CAAC;AAC/B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,GAAoB;IAClD,MAAM,GAAG,GAAG,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACjE,OAAO,6BAA6B,GAAG,+CAA+C,CAAC;AACzF,CAAC"}
+{"version":3,"file":"capture-structure.js","sourceRoot":"","sources":["../../src/lib/capture-structure.ts"],"names":[],"mappings":"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"}

package/dist/lib/catalog-templates.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Where `synap bridge setup` reads the agency skills and the bridge automations.
+ *
+ * Their home is the catalog package (`@synap-core/catalog`, or
+ * `@synap-core/workspace-templates` before the rename): `skills/<name>/SKILL.md`
+ * and `automations/*.automation.json`. The CLI keeps copies under `templates/`
+ * for installs whose catalog package does not ship them yet. Resolution is per
+ * item: the INSTALLED package wins when it ships the item, the CLI copy is the
+ * fallback. The runtime skills (`authoring-*`, `coordinating-*`) have no catalog
+ * copy and always come from the CLI.
+ *
+ * Retirement: once the installed package ships an item, its CLI copy is dead
+ * weight that can silently fork. `catalogRetirementViolations` names those
+ * copies; `test/catalog-templates.test.ts` fails on any, so the pin bump that
+ * brings them in also deletes the CLI copies.
+ */
+/** Package names the catalog may be installed under (new name first). */
+export declare const CATALOG_TEMPLATE_PACKAGES: readonly ["@synap-core/catalog", "@synap-core/workspace-templates"];
+/**
+ * The agency/domain skills whose home is the catalog. Every other bundled skill
+ * is a CLI runtime skill. Pinned (not derived from the catalog) so the set
+ * bridge-setup seeds does not grow because the catalog gained a skill.
+ */
+export declare const AGENCY_SKILLS: readonly ["bookmark-enrichment", "mapping-the-server", "reading-client-progress", "routing-to-channels", "stellar-scf-grants-advisor"];
+/** `<cli package root>/templates` (same depth from `src/lib` and `dist/lib`). */
+export declare const CLI_TEMPLATES_DIR: string;
+/**
+ * Root directory of the installed catalog package, or null when none resolves.
+ * Resolves the package's entry point and walks up to its package.json, because
+ * older versions do not export `./package.json`.
+ */
+export declare function resolveInstalledCatalogRoot(resolve?: (id: string) => string): string | null;
+/**
+ * The SKILL.md directories bridge-setup seeds: each agency skill from the
+ * installed catalog when it ships it, else from the CLI; plus every CLI runtime
+ * skill. `fromCatalog` names the skills read from the catalog.
+ */
+export declare function resolveAgencySkillDirs(opts: {
+    cliSkillsDir: string | null;
+    catalogRoot: string | null;
+}): {
+    dirs: string[];
+    fromCatalog: string[];
+};
+/**
+ * The automation templates directory: the `override` (AUTOMATION_TEMPLATES_DIR)
+ * when set (null if it does not exist), else the installed catalog's
+ * `automations/` when it ships any `*.automation.json`, else the CLI copy.
+ */
+export declare function resolveAutomationTemplatesDir(opts: {
+    override?: string;
+    catalogRoot: string | null;
+    cliDir: string;
+}): string | null;
+/**
+ * CLI copies the installed catalog makes redundant, as paths relative to the CLI
+ * package root (`templates/skills/<name>`, `templates/automations/<file>`).
+ */
+export declare function catalogRetirementViolations(catalogRoot: string | null, cliTemplatesDir: string): string[];

package/dist/lib/catalog-templates.js

@@ -0,0 +1,126 @@
+/**
+ * Where `synap bridge setup` reads the agency skills and the bridge automations.
+ *
+ * Their home is the catalog package (`@synap-core/catalog`, or
+ * `@synap-core/workspace-templates` before the rename): `skills/<name>/SKILL.md`
+ * and `automations/*.automation.json`. The CLI keeps copies under `templates/`
+ * for installs whose catalog package does not ship them yet. Resolution is per
+ * item: the INSTALLED package wins when it ships the item, the CLI copy is the
+ * fallback. The runtime skills (`authoring-*`, `coordinating-*`) have no catalog
+ * copy and always come from the CLI.
+ *
+ * Retirement: once the installed package ships an item, its CLI copy is dead
+ * weight that can silently fork. `catalogRetirementViolations` names those
+ * copies; `test/catalog-templates.test.ts` fails on any, so the pin bump that
+ * brings them in also deletes the CLI copies.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { discoverSkillDirs } from "./skill-import.js";
+/** Package names the catalog may be installed under (new name first). */
+export const CATALOG_TEMPLATE_PACKAGES = ["@synap-core/catalog", "@synap-core/workspace-templates"];
+/**
+ * The agency/domain skills whose home is the catalog. Every other bundled skill
+ * is a CLI runtime skill. Pinned (not derived from the catalog) so the set
+ * bridge-setup seeds does not grow because the catalog gained a skill.
+ */
+export const AGENCY_SKILLS = [
+    "bookmark-enrichment",
+    "mapping-the-server",
+    "reading-client-progress",
+    "routing-to-channels",
+    "stellar-scf-grants-advisor",
+];
+/** `<cli package root>/templates` (same depth from `src/lib` and `dist/lib`). */
+export const CLI_TEMPLATES_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "templates");
+/**
+ * Root directory of the installed catalog package, or null when none resolves.
+ * Resolves the package's entry point and walks up to its package.json, because
+ * older versions do not export `./package.json`.
+ */
+export function resolveInstalledCatalogRoot(resolve = createRequire(import.meta.url).resolve) {
+    for (const name of CATALOG_TEMPLATE_PACKAGES) {
+        let entry;
+        try {
+            entry = resolve(name);
+        }
+        catch {
+            continue; // not installed under this name
+        }
+        for (let dir = path.dirname(entry); dir !== path.dirname(dir); dir = path.dirname(dir)) {
+            const pj = path.join(dir, "package.json");
+            if (!fs.existsSync(pj))
+                continue;
+            if (JSON.parse(fs.readFileSync(pj, "utf8")).name === name)
+                return dir;
+        }
+    }
+    return null;
+}
+function catalogSkillDir(catalogRoot, name) {
+    if (!catalogRoot)
+        return null;
+    const dir = path.join(catalogRoot, "skills", name);
+    return fs.existsSync(path.join(dir, "SKILL.md")) ? dir : null;
+}
+function catalogAutomationFiles(catalogRoot) {
+    const dir = catalogRoot ? path.join(catalogRoot, "automations") : null;
+    if (!dir || !fs.existsSync(dir))
+        return [];
+    return fs.readdirSync(dir).filter((f) => f.endsWith(".automation.json"));
+}
+/**
+ * The SKILL.md directories bridge-setup seeds: each agency skill from the
+ * installed catalog when it ships it, else from the CLI; plus every CLI runtime
+ * skill. `fromCatalog` names the skills read from the catalog.
+ */
+export function resolveAgencySkillDirs(opts) {
+    const agency = new Set(AGENCY_SKILLS);
+    const dirs = [];
+    const fromCatalog = [];
+    const cliDirs = opts.cliSkillsDir ? discoverSkillDirs(opts.cliSkillsDir) : [];
+    for (const cliDir of cliDirs)
+        if (!agency.has(path.basename(cliDir)))
+            dirs.push(cliDir);
+    for (const name of AGENCY_SKILLS) {
+        const fromPkg = catalogSkillDir(opts.catalogRoot, name);
+        if (fromPkg) {
+            dirs.push(fromPkg);
+            fromCatalog.push(name);
+            continue;
+        }
+        const cliDir = cliDirs.find((d) => path.basename(d) === name);
+        if (cliDir)
+            dirs.push(cliDir);
+    }
+    return { dirs, fromCatalog };
+}
+/**
+ * The automation templates directory: the `override` (AUTOMATION_TEMPLATES_DIR)
+ * when set (null if it does not exist), else the installed catalog's
+ * `automations/` when it ships any `*.automation.json`, else the CLI copy.
+ */
+export function resolveAutomationTemplatesDir(opts) {
+    if (opts.override)
+        return fs.existsSync(opts.override) ? opts.override : null;
+    if (opts.catalogRoot && catalogAutomationFiles(opts.catalogRoot).length > 0)
+        return path.join(opts.catalogRoot, "automations");
+    return fs.existsSync(opts.cliDir) ? opts.cliDir : null;
+}
+/**
+ * CLI copies the installed catalog makes redundant, as paths relative to the CLI
+ * package root (`templates/skills/<name>`, `templates/automations/<file>`).
+ */
+export function catalogRetirementViolations(catalogRoot, cliTemplatesDir) {
+    const out = [];
+    for (const name of AGENCY_SKILLS)
+        if (catalogSkillDir(catalogRoot, name) && fs.existsSync(path.join(cliTemplatesDir, "skills", name)))
+            out.push(`templates/skills/${name}`);
+    for (const file of catalogAutomationFiles(catalogRoot))
+        if (fs.existsSync(path.join(cliTemplatesDir, "automations", file)))
+            out.push(`templates/automations/${file}`);
+    return out;
+}
+//# sourceMappingURL=catalog-templates.js.map

package/dist/lib/catalog-templates.js.map

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

package/dist/lib/cli-build.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Which CLI is running: its version AND the commit it was built from.
+ *
+ * The version alone could not tell an Oct-11 test-branch build from current
+ * main (2026-10-15 devbox incident: same version, old code, wrong success
+ * line). `build` stamps `dist/build-info.json` (`scripts/write-build-info.mjs`);
+ * running from source (`tsx`) there is no stamp, and that is said, not hidden.
+ */
+export interface CliBuild {
+    version: string;
+    sha?: string;
+    branch?: string;
+    /** Built with uncommitted changes under src/. */
+    dirty?: boolean;
+    builtAt?: string;
+}
+export declare function cliBuild(dir?: string): CliBuild;
+/** "1.12.0 (a750d09 main, built 2026-10-15)" — the version stays the first word. */
+export declare function formatCliBuild(b: CliBuild): string;

package/dist/lib/cli-build.js

@@ -0,0 +1,37 @@
+/**
+ * Which CLI is running: its version AND the commit it was built from.
+ *
+ * The version alone could not tell an Oct-11 test-branch build from current
+ * main (2026-10-15 devbox incident: same version, old code, wrong success
+ * line). `build` stamps `dist/build-info.json` (`scripts/write-build-info.mjs`);
+ * running from source (`tsx`) there is no stamp, and that is said, not hidden.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+// dist/lib/cli-build.js → dist/build-info.json, package.json at the package
+// root; the same two hops from src/lib when running from source.
+const here = path.dirname(fileURLToPath(import.meta.url));
+function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function cliBuild(dir = here) {
+    const pkg = readJson(path.join(dir, "..", "..", "package.json"));
+    const stamp = readJson(path.join(dir, "..", "build-info.json"));
+    return { version: pkg?.version ?? "unknown", ...(stamp ?? {}) };
+}
+/** "1.12.0 (a750d09 main, built 2026-10-15)" — the version stays the first word. */
+export function formatCliBuild(b) {
+    if (!b.builtAt)
+        return `${b.version} (no build stamp: running from source or an unstamped build)`;
+    const day = b.builtAt.slice(0, 10);
+    if (!b.sha)
+        return `${b.version} (built ${day}, commit unknown)`;
+    return `${b.version} (${b.sha}${b.dirty ? "+changes" : ""}${b.branch ? ` ${b.branch}` : ""}, built ${day})`;
+}
+//# sourceMappingURL=cli-build.js.map

package/dist/lib/cli-build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-build.js","sourceRoot":"","sources":["../../src/lib/cli-build.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAWzC,4EAA4E;AAC5E,iEAAiE;AACjE,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1D,SAAS,QAAQ,CAAI,IAAY;IAC/B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAM,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,GAAG,GAAG,IAAI;IACjC,MAAM,GAAG,GAAG,QAAQ,CAAuB,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC;IACvF,MAAM,KAAK,GAAG,QAAQ,CAA4B,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAC3F,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,IAAI,SAAS,EAAE,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,CAAC;AAClE,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,cAAc,CAAC,CAAW;IACxC,IAAI,CAAC,CAAC,CAAC,OAAO;QAAE,OAAO,GAAG,CAAC,CAAC,OAAO,8DAA8D,CAAC;IAClG,MAAM,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACnC,IAAI,CAAC,CAAC,CAAC,GAAG;QAAE,OAAO,GAAG,CAAC,CAAC,OAAO,WAAW,GAAG,mBAAmB,CAAC;IACjE,OAAO,GAAG,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,GAAG,GAAG,CAAC;AAC9G,CAAC"}

package/dist/lib/client-header.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/client-header.test.js

@@ -0,0 +1,85 @@
+/**
+ * Every call names its client program (`X-Synap-Client: <name>/<version>`), so
+ * the pod's usage telemetry can tell the CLI, its stdio MCP bridge and the
+ * synap-bridge mod apart on one key and one conversation.
+ *
+ * Driven through the real doors: `hubGet` (every Hub call goes through
+ * `sessionHeaders`), the real bridge pump, and the `synap mcp bridge` command.
+ */
+import { readFileSync } from "node:fs";
+import { PassThrough } from "node:stream";
+import { afterEach, describe, expect, it, vi } from "vitest";
+const captured = vi.hoisted(() => ({ opts: undefined }));
+vi.mock("./mcp-bridge.js", async (orig) => {
+    const real = await orig();
+    return {
+        ...real,
+        runMcpBridge: vi.fn(async (opts) => {
+            captured.opts = opts;
+        }),
+    };
+});
+import { hubGet } from "./hub-client.js";
+import { mcpBridgeHeaders, CLIENT_HEADER, clientHeader } from "./conversation-headers.js";
+import { mcpBridge } from "../commands/mcp.js";
+const VERSION = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
+afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.unstubAllEnvs();
+});
+describe("X-Synap-Client", () => {
+    it("names the package version; an unusable version says unknown", () => {
+        expect(VERSION).toMatch(/^\d+\.\d+\.\d+/);
+        expect(clientHeader("synap-cli")).toEqual({ [CLIENT_HEADER]: `synap-cli/${VERSION}` });
+        expect(clientHeader("synap-cli", "1 2")).toEqual({ [CLIENT_HEADER]: "synap-cli/unknown" });
+    });
+    it("every Hub call sends synap-cli/<version>", async () => {
+        const seen = [];
+        vi.stubGlobal("fetch", vi.fn(async (_url, init) => {
+            seen.push(init.headers);
+            return new Response(JSON.stringify({ ok: true }), {
+                status: 200,
+                headers: { "content-type": "application/json" },
+            });
+        }));
+        await hubGet("/workspaces", {}, { podUrl: "https://pod.example", apiKey: "k" });
+        expect(seen).toHaveLength(1);
+        expect(seen[0][CLIENT_HEADER]).toBe(`synap-cli/${VERSION}`);
+    });
+    it("the stdio MCP bridge sends synap-cli-mcp/<version> on every request", async () => {
+        const { runMcpBridge } = await vi.importActual("./mcp-bridge.js");
+        const input = new PassThrough();
+        const output = new PassThrough();
+        const sent = [];
+        const fetchImpl = (async (_u, init) => {
+            sent.push(init.headers);
+            return new Response(JSON.stringify({ jsonrpc: "2.0", id: sent.length, result: {} }), {
+                status: 200,
+                headers: { "content-type": "application/json" },
+            });
+        });
+        const done = runMcpBridge({
+            url: "https://pod/mcp",
+            apiKey: "k",
+            headers: mcpBridgeHeaders(undefined, "/x"),
+            input,
+            output,
+            fetchImpl,
+            log: () => { },
+        });
+        input.write(JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: {} }) + "\n");
+        input.write(JSON.stringify({ jsonrpc: "2.0", id: 2, method: "tools/list" }) + "\n");
+        input.end();
+        await done;
+        expect(sent.length).toBe(2);
+        for (const h of sent)
+            expect(h[CLIENT_HEADER]).toBe(`synap-cli-mcp/${VERSION}`);
+    });
+    it("`synap mcp bridge` hands the bridge those headers", async () => {
+        vi.stubEnv("SYNAP_HUB_API_KEY", "k");
+        await mcpBridge({ url: "https://pod/mcp" });
+        expect(captured.opts?.headers?.[CLIENT_HEADER]).toBe(`synap-cli-mcp/${VERSION}`);
+        expect(captured.opts?.headers?.["X-Synap-Conversation"]).toBeTruthy();
+    });
+});
+//# sourceMappingURL=client-header.test.js.map