@synap-core/cli 1.11.0 → 1.13.0

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

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

package/dist/lib/conversation-headers.d.ts

@@ -0,0 +1,33 @@
+export declare const CONVERSATION_HEADER = "X-Synap-Conversation";
+export declare const CONVERSATION_CWD_HEADER = "X-Synap-Conversation-Cwd";
+/**
+ * Which CLIENT program makes the call, `<name>/<version>`: `synap-cli/<v>` for
+ * the CLI's Hub calls, `synap-cli-mcp/<v>` for the stdio MCP bridge (and
+ * `synap-bridge/<v>` from the Claude Code mod). The pod counts calls per client
+ * in its usage telemetry, so two programs sharing one key and one conversation
+ * can be told apart. Never an identity: it only labels the count.
+ */
+export declare const CLIENT_HEADER = "X-Synap-Client";
+export type SynapClientName = "synap-cli" | "synap-cli-mcp";
+/** `{ "X-Synap-Client": "<name>/<version>" }`; the version is the package's. */
+export declare function clientHeader(name: SynapClientName, version?: string): Record<string, string>;
+/** The same two values in a request's `params._meta` (reverse-DNS vendor keys; `io.modelcontextprotocol/` is reserved). */
+export declare const CONVERSATION_META_KEY = "live.synap/conversation";
+export declare const CONVERSATION_CWD_META_KEY = "live.synap/conversationCwd";
+/** `claude-code:<uuid>` for the Claude Code conversation we run in, if any. */
+export declare function claudeCodeConversation(sessionId: string | undefined): string | undefined;
+/**
+ * `synap-cli:<id>` for a run outside Claude Code: `SYNAP_RUN_ID` when the caller
+ * names one (a multi-command script), else a UUID minted once per process. An
+ * unusable `SYNAP_RUN_ID` falls back to the process id rather than failing.
+ */
+export declare function cliConversation(env?: NodeJS.ProcessEnv): string;
+/**
+ * The headers for `sessionId` (pass it explicitly: the CLI's live id is
+ * `getClaudeSessionId()`, a stdio server's is its spawn env). Empty without a
+ * real Claude Code id the run names itself (`cliConversation`); the cwd rides
+ * only with a Claude Code conversation (the one a person can reopen).
+ */
+export declare function conversationHeaders(sessionId: string | undefined, cwd?: string): Record<string, string>;
+/** Every header the stdio MCP bridge sends: its client name plus the conversation. */
+export declare function mcpBridgeHeaders(sessionId: string | undefined, cwd?: string): Record<string, string>;

package/dist/lib/conversation-headers.js

@@ -0,0 +1,69 @@
+/**
+ * The headers that name the calling CONVERSATION to the pod — the agent's own
+ * id, the one a person can reopen (`claude --resume <id>`). The pod reads
+ * `X-Synap-Conversation` as the conversation half of the client key, so every
+ * session the conversation touches records it (`resolveAgentConversation`,
+ * @synap-core/types/agents). Sent by every Hub call (`hub-client.ts`) and by
+ * the stdio MCP bridge (`mcp-bridge.ts`). Outside Claude Code the conversation is
+ * this process's own run (`synap-cli:<uuid>`, or `SYNAP_RUN_ID` to span a script).
+ */
+import { randomUUID } from "node:crypto";
+import { cliBuild } from "./cli-build.js";
+export const CONVERSATION_HEADER = "X-Synap-Conversation";
+export const CONVERSATION_CWD_HEADER = "X-Synap-Conversation-Cwd";
+/**
+ * Which CLIENT program makes the call, `<name>/<version>`: `synap-cli/<v>` for
+ * the CLI's Hub calls, `synap-cli-mcp/<v>` for the stdio MCP bridge (and
+ * `synap-bridge/<v>` from the Claude Code mod). The pod counts calls per client
+ * in its usage telemetry, so two programs sharing one key and one conversation
+ * can be told apart. Never an identity: it only labels the count.
+ */
+export const CLIENT_HEADER = "X-Synap-Client";
+/** `{ "X-Synap-Client": "<name>/<version>" }`; the version is the package's. */
+export function clientHeader(name, version = cliBuild().version) {
+    // A header value must be visible ASCII; an odd version never fails the call.
+    const v = /^[\x21-\x7E]{1,64}$/.test(version) ? version : "unknown";
+    return { [CLIENT_HEADER]: `${name}/${v}` };
+}
+/** The same two values in a request's `params._meta` (reverse-DNS vendor keys; `io.modelcontextprotocol/` is reserved). */
+export const CONVERSATION_META_KEY = "live.synap/conversation";
+export const CONVERSATION_CWD_META_KEY = "live.synap/conversationCwd";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** `claude-code:<uuid>` for the Claude Code conversation we run in, if any. */
+export function claudeCodeConversation(sessionId) {
+    const id = sessionId?.trim();
+    return id && UUID.test(id) ? `claude-code:${id.toLowerCase()}` : undefined;
+}
+const RUN_ID = /^[A-Za-z0-9_.-]{1,128}$/;
+/** One id per process, so every Hub call of one CLI run lands in one conversation. */
+const PROCESS_RUN_ID = randomUUID();
+/**
+ * `synap-cli:<id>` for a run outside Claude Code: `SYNAP_RUN_ID` when the caller
+ * names one (a multi-command script), else a UUID minted once per process. An
+ * unusable `SYNAP_RUN_ID` falls back to the process id rather than failing.
+ */
+export function cliConversation(env = process.env) {
+    const named = env.SYNAP_RUN_ID?.trim();
+    return `synap-cli:${named && RUN_ID.test(named) ? named : PROCESS_RUN_ID}`;
+}
+/**
+ * The headers for `sessionId` (pass it explicitly: the CLI's live id is
+ * `getClaudeSessionId()`, a stdio server's is its spawn env). Empty without a
+ * real Claude Code id the run names itself (`cliConversation`); the cwd rides
+ * only with a Claude Code conversation (the one a person can reopen).
+ */
+export function conversationHeaders(sessionId, cwd = process.cwd()) {
+    const conversation = claudeCodeConversation(sessionId);
+    if (!conversation)
+        return { [CONVERSATION_HEADER]: cliConversation() };
+    // HTTP header values must be ByteStrings; a non-ASCII cwd is dropped rather
+    // than letting fetch throw and take the whole request down with it.
+    return /^[\x20-\x7E]{1,1024}$/.test(cwd)
+        ? { [CONVERSATION_HEADER]: conversation, [CONVERSATION_CWD_HEADER]: cwd }
+        : { [CONVERSATION_HEADER]: conversation };
+}
+/** Every header the stdio MCP bridge sends: its client name plus the conversation. */
+export function mcpBridgeHeaders(sessionId, cwd = process.cwd()) {
+    return { ...clientHeader("synap-cli-mcp"), ...conversationHeaders(sessionId, cwd) };
+}
+//# sourceMappingURL=conversation-headers.js.map

package/dist/lib/conversation-headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-headers.js","sourceRoot":"","sources":["../../src/lib/conversation-headers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,MAAM,CAAC,MAAM,mBAAmB,GAAG,sBAAsB,CAAC;AAC1D,MAAM,CAAC,MAAM,uBAAuB,GAAG,0BAA0B,CAAC;AAElE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,gBAAgB,CAAC;AAG9C,gFAAgF;AAChF,MAAM,UAAU,YAAY,CAC1B,IAAqB,EACrB,UAAkB,QAAQ,EAAE,CAAC,OAAO;IAEpC,6EAA6E;IAC7E,MAAM,CAAC,GAAG,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IACpE,OAAO,EAAE,CAAC,aAAa,CAAC,EAAE,GAAG,IAAI,IAAI,CAAC,EAAE,EAAE,CAAC;AAC7C,CAAC;AAED,2HAA2H;AAC3H,MAAM,CAAC,MAAM,qBAAqB,GAAG,yBAAyB,CAAC;AAC/D,MAAM,CAAC,MAAM,yBAAyB,GAAG,4BAA4B,CAAC;AAEtE,MAAM,IAAI,GAAG,iEAAiE,CAAC;AAE/E,+EAA+E;AAC/E,MAAM,UAAU,sBAAsB,CAAC,SAA6B;IAClE,MAAM,EAAE,GAAG,SAAS,EAAE,IAAI,EAAE,CAAC;IAC7B,OAAO,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,eAAe,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7E,CAAC;AAED,MAAM,MAAM,GAAG,yBAAyB,CAAC;AAEzC,sFAAsF;AACtF,MAAM,cAAc,GAAG,UAAU,EAAE,CAAC;AAEpC;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,MAAyB,OAAO,CAAC,GAAG;IAClE,MAAM,KAAK,GAAG,GAAG,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC;IACvC,OAAO,aAAa,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC;AAC7E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAA6B,EAC7B,MAAc,OAAO,CAAC,GAAG,EAAE;IAE3B,MAAM,YAAY,GAAG,sBAAsB,CAAC,SAAS,CAAC,CAAC;IACvD,IAAI,CAAC,YAAY;QAAE,OAAO,EAAE,CAAC,mBAAmB,CAAC,EAAE,eAAe,EAAE,EAAE,CAAC;IACvE,4EAA4E;IAC5E,oEAAoE;IACpE,OAAO,uBAAuB,CAAC,IAAI,CAAC,GAAG,CAAC;QACtC,CAAC,CAAC,EAAE,CAAC,mBAAmB,CAAC,EAAE,YAAY,EAAE,CAAC,uBAAuB,CAAC,EAAE,GAAG,EAAE;QACzE,CAAC,CAAC,EAAE,CAAC,mBAAmB,CAAC,EAAE,YAAY,EAAE,CAAC;AAC9C,CAAC;AAGD,sFAAsF;AACtF,MAAM,UAAU,gBAAgB,CAC9B,SAA6B,EAC7B,MAAc,OAAO,CAAC,GAAG,EAAE;IAE3B,OAAO,EAAE,GAAG,YAAY,CAAC,eAAe,CAAC,EAAE,GAAG,mBAAmB,CAAC,SAAS,EAAE,GAAG,CAAC,EAAE,CAAC;AACtF,CAAC"}

package/dist/lib/cp-packages.d.ts

@@ -64,6 +64,17 @@ export type CpMineRow = CpPackageRow & {
  * source both the merged launch catalog and the `market` command read from.
  */
 export declare function fetchPublicBrowseRows(filters?: PackageFilters): Promise<CpBrowseRow[]>;
+/**
+ * The workspace-template slugs the CP marks RETIRED (template lifecycle). The
+ * default browse route hides tombstones, so a stale bundled copy of a retired
+ * template (the npm `@synap-core/workspace-templates` this CLI ships) would
+ * otherwise survive the merge and be offered or suggested. Asks once with
+ * `includeRetired=true`.
+ * - An older CP refuses the param (400): it cannot retire anything → empty set.
+ * - Any other failure → `null` (unknown): the caller keeps today's behaviour
+ *   rather than guessing which templates are retired.
+ */
+export declare function fetchRetiredWorkspaceSlugs(): Promise<Set<string> | null>;
 /** GET /api/packages — public workspace templates as `RemoteEntry`. No auth. */
 export declare function fetchPublicPackages(filters?: PackageFilters): Promise<RemoteEntry[]>;
 /**
@@ -84,12 +95,64 @@ export declare function fetchMyPackages(token: string, filters?: PackageFilters)
  */
 export declare function fetchAvailableSlugs(token: string, filters?: PackageFilters): Promise<Set<string>>;
 /**
- * GET /api/packages/:slug — the full row, INCLUDING `definition` (the install
- * payload). Authed when a token is given, which is REQUIRED for a private
- * template (the author-only visibility gate 404s otherwise). Returns `null` if
- * the package is absent / not visible.
+ * The single-package row `GET /api/packages/:slug` returns. The CP hands back
+ * the WHOLE `synap_packages` row (`getTableColumns`), so unlike the `/mine`
+ * list projection this one DOES carry `category` — which is why it is the door
+ * that can answer "what kind of package is this private thing I own?".
+ */
+export interface CpPackageRecord {
+    slug: string;
+    category?: string | null;
+    definition?: Record<string, unknown> | null;
+    isPublic?: boolean;
+    displayName?: string;
+}
+/**
+ * GET /api/packages/:slug — the full row (definition + `category` + visibility).
+ * Authed when a token is given, which is REQUIRED for a private package (the
+ * author-only visibility gate 404s otherwise). Returns `null` if the package is
+ * absent / not visible / unreachable.
+ *
+ * This is the ONE authed single-package read; `fetchPackageDefinition` and the
+ * category hydration below both go through it rather than re-rolling the fetch.
+ */
+export declare function fetchPackageRecord(slug: string, token?: string): Promise<CpPackageRecord | null>;
+/**
+ * GET /api/packages/:slug — just the `definition` (the install payload).
+ * Delegates to {@link fetchPackageRecord}; kept as its own name because most
+ * call sites want only the payload.
  */
 export declare function fetchPackageDefinition(slug: string, token?: string): Promise<Record<string, unknown> | null>;
+/**
+ * How many `/mine` rows will be hydrated over the network in one catalog build.
+ * Bounded so a prolific author's `synap market --list` can't fan out to 100
+ * detail requests. Beyond the cap the extra rows keep an ABSENT category —
+ * honest under-resolution, which the install refusal then catches.
+ */
+export declare const MINE_CATEGORY_HYDRATION_CAP = 25;
+/**
+ * Fill in the `category` the `/mine` LIST PROJECTION does not select.
+ *
+ * `GET /api/packages/mine` projects ~15 columns and `category` is not one of
+ * them (`synap-control-plane-api/src/routes/packages.ts`), so every row the
+ * caller owns arrives type-less. Downstream that is not cosmetic: the CLI's
+ * display default turns an absent category into "workspace", which is exactly
+ * how a published CELL package was listed as a workspace, filtered out of
+ * `--type cell`, and installed as an empty "New Workspace".
+ *
+ * Resolution order per row, cheapest first:
+ *   1. the row already declares a category → untouched;
+ *   2. `fallbackBySlug` — a category already known from the PUBLIC browse rows
+ *      this catalog build fetched anyway (free, no extra request);
+ *   3. `GET /api/packages/:slug` with the caller's Bearer — the only door that
+ *      can see a PRIVATE row's category.
+ *
+ * A failure at step 3 leaves the category ABSENT. It never invents one: "I
+ * don't know" must stay distinguishable from "workspace".
+ */
+export declare function hydrateMineCategories(rows: CpMineRow[], token: string, fallbackBySlug?: Map<string, string | undefined>, deps?: {
+    fetchRecord?: typeof fetchPackageRecord;
+}): Promise<CpMineRow[]>;
 /** The remote half of the catalog, plus the health `mergeCatalog` needs. */
 export interface RemoteCatalog {
     rows: RemoteEntry[];
@@ -144,6 +207,18 @@ export interface PublishResult {
     /** The `h-<hash>` version the CP derived from the definition. */
     version: string;
     isPublic: boolean;
+    /**
+     * Whether the package was attributed to a publisher profile. False means the
+     * author has no vendor yet, so this package will never appear on
+     * `GET /api/vendors/:slug` — the command says so and points at
+     * `synap vendor create`, because the CP never back-fills attribution later.
+     */
+    vendorAttached: boolean;
+    /**
+     * True when the caller's vendor is `synap-official` and it was therefore NOT
+     * attached: a file publish is never an official write.
+     */
+    officialVendorWithheld: boolean;
 }
 /**
  * `POST /api/packages` — publish (upsert) a package definition under the caller's
@@ -154,22 +229,103 @@ export interface PublishResult {
  * own message.
  *
  * The definition's identity (`slug`, `displayName`) is read off its `_meta`/
- * `workspaceName`; `_meta.icon`/`.color`/`.domain` are hoisted onto the
+ * `workspaceName` by default (the workspace-template shape); `opts.slug`/
+ * `opts.displayName` override that for a standalone (non-workspace) package —
+ * e.g. a `category: "cell"` file, which has neither field (see
+ * `lib/kind-package.ts`). `_meta.icon`/`.color`/`.domain` are hoisted onto the
  * definition's top level because the CP reads those off `definition.icon`/… for
  * the list DTO (it strips the unknown `_meta` key).
  */
+/**
+ * The caller's vendor (publisher) profile, or null if they have never created one.
+ *
+ * `GET /api/vendors/mine` — an existing authed door; this adds no new endpoint.
+ *
+ * WHY publish needs it: the CP's publish handler is `if (body.vendorId) { … }`
+ * with NO else (`routes/packages.ts:1465`) — it never auto-creates and never
+ * infers one. The CLI has never sent the field, so every CLI-published package
+ * is permanently ORPHANED from its author's publisher profile and can never
+ * appear on `GET /api/vendors/:slug`. Vendor identity is already load-bearing
+ * elsewhere (reserved bedrock slugs gate on `isOfficialVendor`), so an orphaned
+ * package is not cosmetic.
+ *
+ * Failure is non-fatal by design: publishing must not break because a publisher
+ * profile does not exist yet. No vendor ⇒ publish exactly as before.
+ */
+export declare function fetchMyVendorId(base: string, token: string, fetchImpl?: typeof fetch): Promise<string | null>;
+/**
+ * The official publisher's vendor slug. Official content has ONE door — the
+ * catalog (`synap catalog publish --official`, which validates the process
+ * contract, the lifecycle ratchet and the goal grammar first). A file publish
+ * must never carry this vendor, or `synap market publish x.yaml` run from the
+ * founder's login becomes an unvalidated official write.
+ */
+export declare const OFFICIAL_VENDOR_SLUG = "synap-official";
+/** The one line shown when a file publish withholds the official vendor. */
+export declare const OFFICIAL_USE_CATALOG_HINT = "Official templates are published from the catalog: synap catalog publish --official";
+/**
+ * A publisher (vendor) profile — the author identity a package is attributed to.
+ * Only the fields the CLI prints; the CP returns the whole row.
+ */
+export interface VendorProfile {
+    id: string;
+    slug: string;
+    displayName: string;
+}
+/**
+ * `POST /api/vendors` — create the caller's publisher profile.
+ *
+ * WHY the CLI needs its own verb: the endpoint is self-serve and the BROWSER
+ * already calls it inline (`PublishWizard.tsx`'s Publisher step, which blocks
+ * the wizard until a vendor exists). The CLI only ever READ one
+ * (`fetchMyVendorId`), so a CLI-only author had no way to make one and every
+ * package they published was attributed to nobody — no `/superpowers/by/<slug>`
+ * page, permanently, since the CP never auto-creates or back-fills a vendor.
+ *
+ * The contract mirrors the wizard's call exactly — same endpoint, same field
+ * names (`slug`, `displayName`, `description`, `website`) — with ONE deliberate
+ * difference: empty optionals are OMITTED rather than sent as `""`. The CP
+ * declares `website: z.string().url().optional()`, so an empty string is a 400;
+ * the wizard sends its blank fields unconditionally and hits that.
+ *
+ * Errors surface as `CpWriteError` carrying the server's own message: the CP
+ * returns 409 both for "you already have a vendor profile" and for a taken slug,
+ * and those are the two an author actually hits.
+ */
+export declare function createVendor(input: {
+    slug: string;
+    displayName: string;
+    description?: string;
+    website?: string;
+}, deps?: CpWriteDeps): Promise<VendorProfile>;
 export declare function publishPackage(def: PackageDefinitionLike, opts: {
     isPublic: boolean;
+    category?: string;
+    slug?: string;
+    displayName?: string;
+    /**
+     * Pricing stamp for the CP row. `one_time` + `priceUsd` (USD cents) marks
+     * a paid listing. Settlement/Stripe is NOT this client — columns only.
+     */
+    pricingModel?: "free" | "tier_included" | "one_time";
+    /** Price in USD cents. */
+    priceUsd?: number | null;
 }, deps?: CpWriteDeps): Promise<PublishResult>;
 /**
  * `PATCH /api/packages/:slug` — owner-gated flip of a package to private.
  *
- * ⚠️ TODO(cp): the CP PATCH handler's body validator is
- * `z.object({ podId: z.string().min(1).nullable() })` TODAY — it does NOT accept
- * `isPublic`, so this call currently fails (400) until the CP adds `isPublic` to
- * that PATCH allow-list. This is deliberately the INTENDED endpoint (not a
- * faked flip): it will start working the moment the CP door is widened. The
- * command surfaces the CP's message honestly meanwhile.
+ * ✅ RESOLVED 2026-09-05 — this block used to carry a TODO saying the CP's PATCH
+ * validator accepted only `podId` and that this call therefore 400'd. That is no
+ * longer true: the handler declares `isPublic: z.boolean().optional()`
+ * (`synap-control-plane-api/src/routes/packages.ts:1618`) and the flip works.
+ * Kept as a tombstone rather than deleted because the stale warning outlived its
+ * fix and would otherwise keep sending readers to "widen the CP door" work that
+ * is already done — the same way a stale comment sent an auditor down the wrong
+ * path on `kind-package.ts` a day earlier.
+ *
+ * Note the browser uses `DELETE /api/packages/:slug` for the same act; both
+ * doors now route through the CP's shared owned-package helpers and both are a
+ * SOFT delist (`is_public = false`), never a destroy.
  */
 export declare function unpublishPackage(slug: string, deps?: CpWriteDeps): Promise<{
     slug: string;