@synap-core/cli 1.10.0 → 1.12.2

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

@@ -22,6 +22,7 @@
  * `verified`).
  */
 import { type CpPackageRow, type RemoteEntry, type RemoteSourceStatus } from "@synap-core/workspace-templates";
+import type { PackageDefinitionLike } from "./template-file.js";
 /**
  * The server-side filters `GET /api/packages` accepts (CP `routes/packages.ts`).
  * `category` is a PACKAGE_TYPES value (`workspace`/`capability`/`skill`/…). The
@@ -63,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[]>;
 /**
@@ -83,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[];
@@ -119,3 +183,151 @@ export interface RemoteCatalog {
  *     "unreachable". Either way `rows` is empty and the door keeps the bundle.
  */
 export declare function fetchRemoteCatalog(filters?: PackageFilters): Promise<RemoteCatalog>;
+/**
+ * A CP write failure carrying the server's OWN message + status, so the caller
+ * can surface `detail` (never swallow it — the `readErrorBody`/`detail` lesson)
+ * and special-case a 403 reserved-slug rejection.
+ */
+export declare class CpWriteError extends Error {
+    readonly status: number;
+    readonly serverMessage: string;
+    constructor(status: number, serverMessage: string);
+}
+/** Test seams — inject a fetch + token + base URL instead of touching the network / `~/.synap`. */
+export interface CpWriteDeps {
+    fetchImpl?: typeof fetch;
+    token?: string;
+    cpUrl?: string;
+}
+export interface PublishResult {
+    /** `created` (201) · `updated` (200, content changed) · `no-op` (200, identical content). */
+    outcome: "created" | "updated" | "no-op";
+    slug: string;
+    displayName: string;
+    /** 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
+ * account. `isPublic` decides visibility (default private — the command flips it
+ * with `--public`). The version is DERIVED server-side from the definition, so
+ * identical content re-published is a no-op. Surfaces a 403 reserved-slug
+ * rejection (and any other failure) as a `CpWriteError` carrying the server's
+ * own message.
+ *
+ * The definition's identity (`slug`, `displayName`) is read off its `_meta`/
+ * `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.
+ *
+ * ✅ 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;
+    isPublic: boolean;
+}>;