@synap-core/cli 1.7.0 → 1.10.0

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

@@ -0,0 +1,121 @@
+/**
+ * Control-plane package registry client (read-only).
+ * ==================================================
+ *
+ * The ONE authed HTTP client for the CP package registry (`/api/packages`).
+ * Before this file there was NO `/api/packages` client in the CLI — `launch`
+ * read the whole catalog from the bundled `@synap-core/workspace-templates`
+ * package. The ratified architecture is: PUBLIC templates ship in the bundle,
+ * PRIVATE templates live in the CP behind the user's login. This client is the
+ * private half.
+ *
+ * Two list endpoints, one detail endpoint:
+ *   • GET /api/packages            — public browse rows (no auth, `definition` stripped)
+ *   • GET /api/packages/mine       — the caller's own packages (Bearer, incl. private)
+ *   • GET /api/packages/:slug      — full row WITH `definition` (Bearer → private visible to author)
+ *
+ * The row→`RemoteEntry` mapping is NOT here — it is the canonical
+ * `rowToRemoteEntry` in `@synap-core/workspace-templates` (browser + CLI share
+ * the ONE copy; the two hand-copies had already drifted). This file owns only
+ * TRANSPORT: the Bearer token, the base URL (`auth.ts`'s `getCpUrl()`), and the
+ * query params the CP `/api/packages` route supports (`search`/`category`/`tag`/
+ * `verified`).
+ */
+import { type CpPackageRow, type RemoteEntry, type RemoteSourceStatus } from "@synap-core/workspace-templates";
+/**
+ * The server-side filters `GET /api/packages` accepts (CP `routes/packages.ts`).
+ * `category` is a PACKAGE_TYPES value (`workspace`/`capability`/`skill`/…). The
+ * `/mine` route supports none of these — it is the caller's own small set — so
+ * they are applied CLIENT-side there.
+ */
+export interface PackageFilters {
+    search?: string;
+    category?: string;
+    tag?: string;
+    verified?: boolean;
+}
+/** Tier / pricing signal the browse route carries but `RemoteEntry` drops. */
+export interface TierInfo {
+    requiredTier?: string | null;
+    pricingModel?: string | null;
+}
+/**
+ * A public browse row — the canonical `CpPackageRow` PLUS the tier/pricing and
+ * count fields the browse route (`GET /api/packages`) returns but the shared
+ * `RemoteEntry` shape does not carry. Kept local because they are a
+ * discovery-surface concern, not part of the merge door's contract.
+ */
+export interface CpBrowseRow extends CpPackageRow {
+    version?: string;
+    requiredTier?: string | null;
+    pricingModel?: string | null;
+    isVerified?: boolean;
+    installCount?: number;
+}
+/** `/mine` returns `isPublic` (and, like the browse route, `version`) on top of the canonical row shape. */
+export type CpMineRow = CpPackageRow & {
+    isPublic?: boolean;
+    version?: string;
+};
+/**
+ * GET /api/packages — public browse rows, RAW (incl. `requiredTier`/
+ * `pricingModel`/`category`). No auth. Throws on non-2xx / network. This is the
+ * source both the merged launch catalog and the `market` command read from.
+ */
+export declare function fetchPublicBrowseRows(filters?: PackageFilters): Promise<CpBrowseRow[]>;
+/** GET /api/packages — public workspace templates as `RemoteEntry`. No auth. */
+export declare function fetchPublicPackages(filters?: PackageFilters): Promise<RemoteEntry[]>;
+/**
+ * GET /api/packages/mine — the caller's own packages (incl. private). Bearer
+ * required. The route has no `search`/`category` params, so those filters are
+ * applied client-side over this (small) set; `search` is honored, `category`
+ * only when the row actually carries one (the `/mine` select omits it, so a
+ * type filter never silently drops the user's own rows).
+ */
+export declare function fetchMyRows(token: string, filters?: PackageFilters): Promise<CpMineRow[]>;
+export declare function fetchMyPackages(token: string, filters?: PackageFilters): Promise<RemoteEntry[]>;
+/**
+ * GET /api/packages/available — the slugs THIS account's subscription tier can
+ * install (Bearer required; the route reads the user's `subscriptions.tier`).
+ * Used to compute the "locked" set: a public package that declares a
+ * `requiredTier` but is absent here is ungrantable for this account. Only
+ * `category` is a real filter on this route — the others are ignored server-side.
+ */
+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.
+ */
+export declare function fetchPackageDefinition(slug: string, token?: string): Promise<Record<string, unknown> | null>;
+/** The remote half of the catalog, plus the health `mergeCatalog` needs. */
+export interface RemoteCatalog {
+    rows: RemoteEntry[];
+    status: RemoteSourceStatus;
+    loggedIn: boolean;
+    email?: string;
+    /** How many private rows we actually fetched (meaningful only when status === "ok"). */
+    privateCount: number;
+    /** Tier/pricing per public slug — the browse route carries it, `RemoteEntry` drops it. */
+    tierBySlug: Map<string, TierInfo>;
+    /**
+     * Slugs that declare a `requiredTier` this account CANNOT install (browse ∖
+     * `/available`). Empty when logged out or when `/available` couldn't be read
+     * (older pod / failure) — absence means "unknown", never "locked".
+     */
+    lockedSlugs: Set<string>;
+}
+/**
+ * Assemble the remote catalog for `launch`, degrading HONESTLY rather than
+ * failing open empty:
+ *
+ *   • Logged out → NO network. The bundle already IS the public catalog, and
+ *     private templates are invisible without auth. Status "unauthenticated"
+ *     tells the consumer to render the `synap login` path.
+ *   • Logged in → fetch `/mine` (private + own public) and best-effort `/packages`
+ *     (official / third-party public); merge, private-carrying rows win a tie.
+ *   • `/mine` 401/403 → "unauthenticated" (session expired). Network failure →
+ *     "unreachable". Either way `rows` is empty and the door keeps the bundle.
+ */
+export declare function fetchRemoteCatalog(filters?: PackageFilters): Promise<RemoteCatalog>;

package/dist/lib/cp-packages.js

@@ -0,0 +1,218 @@
+/**
+ * Control-plane package registry client (read-only).
+ * ==================================================
+ *
+ * The ONE authed HTTP client for the CP package registry (`/api/packages`).
+ * Before this file there was NO `/api/packages` client in the CLI — `launch`
+ * read the whole catalog from the bundled `@synap-core/workspace-templates`
+ * package. The ratified architecture is: PUBLIC templates ship in the bundle,
+ * PRIVATE templates live in the CP behind the user's login. This client is the
+ * private half.
+ *
+ * Two list endpoints, one detail endpoint:
+ *   • GET /api/packages            — public browse rows (no auth, `definition` stripped)
+ *   • GET /api/packages/mine       — the caller's own packages (Bearer, incl. private)
+ *   • GET /api/packages/:slug      — full row WITH `definition` (Bearer → private visible to author)
+ *
+ * The row→`RemoteEntry` mapping is NOT here — it is the canonical
+ * `rowToRemoteEntry` in `@synap-core/workspace-templates` (browser + CLI share
+ * the ONE copy; the two hand-copies had already drifted). This file owns only
+ * TRANSPORT: the Bearer token, the base URL (`auth.ts`'s `getCpUrl()`), and the
+ * query params the CP `/api/packages` route supports (`search`/`category`/`tag`/
+ * `verified`).
+ */
+import { rowToRemoteEntry, } from "@synap-core/workspace-templates";
+import { getCpUrl, getStoredToken, isTokenLocallyExpired } from "./auth.js";
+// Packages mount under `/api/packages` (CP `routes/index.ts`), unlike `/auth`
+// and `/pods` which sit at the root — hence the explicit `/api` segment here.
+const packagesBase = () => `${getCpUrl()}/api/packages`;
+const FETCH_TIMEOUT_MS = 10_000;
+/** Build the `/api/packages` query string from filters + any extra params. */
+function buildQuery(filters, extra) {
+    const p = new URLSearchParams(extra);
+    if (filters?.search)
+        p.set("search", filters.search);
+    if (filters?.category)
+        p.set("category", filters.category);
+    if (filters?.tag)
+        p.set("tag", filters.tag);
+    if (filters?.verified)
+        p.set("verified", "true");
+    return p.toString();
+}
+/** An auth failure (401/403) — distinct from an unreachable-network failure. */
+class CpAuthError extends Error {
+    authFailed = true;
+}
+/**
+ * GET /api/packages — public browse rows, RAW (incl. `requiredTier`/
+ * `pricingModel`/`category`). No auth. Throws on non-2xx / network. This is the
+ * source both the merged launch catalog and the `market` command read from.
+ */
+export async function fetchPublicBrowseRows(filters) {
+    const qs = buildQuery(filters, { limit: "100" });
+    const res = await fetch(`${packagesBase()}?${qs}`, {
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    if (!res.ok)
+        throw new Error(`CP GET /api/packages → HTTP ${res.status}`);
+    const data = (await res.json());
+    return data.packages ?? [];
+}
+/** GET /api/packages — public workspace templates as `RemoteEntry`. No auth. */
+export async function fetchPublicPackages(filters) {
+    const rows = await fetchPublicBrowseRows(filters);
+    // Browse rows are all public by construction — pass `isPrivate` undefined.
+    return rows.map((r) => rowToRemoteEntry(r, undefined));
+}
+/**
+ * GET /api/packages/mine — the caller's own packages (incl. private). Bearer
+ * required. The route has no `search`/`category` params, so those filters are
+ * applied client-side over this (small) set; `search` is honored, `category`
+ * only when the row actually carries one (the `/mine` select omits it, so a
+ * type filter never silently drops the user's own rows).
+ */
+export async function fetchMyRows(token, filters) {
+    const res = await fetch(`${packagesBase()}/mine?limit=100`, {
+        headers: { Authorization: `Bearer ${token}` },
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    if (res.status === 401 || res.status === 403) {
+        throw new CpAuthError(`CP GET /api/packages/mine → HTTP ${res.status}`);
+    }
+    if (!res.ok)
+        throw new Error(`CP GET /api/packages/mine → HTTP ${res.status}`);
+    const data = (await res.json());
+    let rows = data.packages ?? [];
+    if (filters?.category) {
+        rows = rows.filter((r) => r.category == null || r.category === filters.category);
+    }
+    if (filters?.search) {
+        const q = filters.search.toLowerCase();
+        rows = rows.filter((r) => r.slug.toLowerCase().includes(q) ||
+            r.displayName.toLowerCase().includes(q) ||
+            (r.description ?? "").toLowerCase().includes(q));
+    }
+    return rows;
+}
+export async function fetchMyPackages(token, filters) {
+    const rows = await fetchMyRows(token, filters);
+    return rows.map((r) => rowToRemoteEntry(r, r.isPublic === false ? true : undefined));
+}
+/**
+ * GET /api/packages/available — the slugs THIS account's subscription tier can
+ * install (Bearer required; the route reads the user's `subscriptions.tier`).
+ * Used to compute the "locked" set: a public package that declares a
+ * `requiredTier` but is absent here is ungrantable for this account. Only
+ * `category` is a real filter on this route — the others are ignored server-side.
+ */
+export async function fetchAvailableSlugs(token, filters) {
+    const qs = buildQuery({ category: filters?.category }, { limit: "100" });
+    const res = await fetch(`${packagesBase()}/available?${qs}`, {
+        headers: { Authorization: `Bearer ${token}` },
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    if (!res.ok)
+        throw new Error(`CP GET /api/packages/available → HTTP ${res.status}`);
+    const data = (await res.json());
+    return new Set((data.packages ?? []).map((p) => p.slug));
+}
+/**
+ * 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.
+ */
+export async function fetchPackageDefinition(slug, token) {
+    const res = await fetch(`${packagesBase()}/${encodeURIComponent(slug)}`, {
+        headers: token ? { Authorization: `Bearer ${token}` } : {},
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+    });
+    if (!res.ok)
+        return null;
+    const data = (await res.json());
+    return data.package?.definition ?? null;
+}
+/**
+ * Assemble the remote catalog for `launch`, degrading HONESTLY rather than
+ * failing open empty:
+ *
+ *   • Logged out → NO network. The bundle already IS the public catalog, and
+ *     private templates are invisible without auth. Status "unauthenticated"
+ *     tells the consumer to render the `synap login` path.
+ *   • Logged in → fetch `/mine` (private + own public) and best-effort `/packages`
+ *     (official / third-party public); merge, private-carrying rows win a tie.
+ *   • `/mine` 401/403 → "unauthenticated" (session expired). Network failure →
+ *     "unreachable". Either way `rows` is empty and the door keeps the bundle.
+ */
+export async function fetchRemoteCatalog(filters) {
+    const creds = getStoredToken();
+    const loggedIn = !!creds && !isTokenLocallyExpired(creds);
+    if (!loggedIn) {
+        return {
+            rows: [],
+            status: "unauthenticated",
+            loggedIn: false,
+            privateCount: 0,
+            tierBySlug: new Map(),
+            lockedSlugs: new Set(),
+        };
+    }
+    let publicRows = [];
+    let mineRows = [];
+    let availableSlugs = null;
+    try {
+        [publicRows, mineRows, availableSlugs] = await Promise.all([
+            // Public is best-effort: a private catalog that resolves is still useful
+            // even if the browse route hiccups.
+            fetchPublicBrowseRows(filters).catch(() => []),
+            fetchMyPackages(creds.token, filters),
+            // Tier gate is best-effort: an older pod without `/available` ⇒ null ⇒
+            // "unknown", never "locked".
+            fetchAvailableSlugs(creds.token, filters).catch(() => null),
+        ]);
+    }
+    catch (e) {
+        const authFailed = e.authFailed === true;
+        return {
+            rows: [],
+            status: authFailed ? "unauthenticated" : "unreachable",
+            loggedIn: true,
+            email: creds.email,
+            privateCount: 0,
+            tierBySlug: new Map(),
+            lockedSlugs: new Set(),
+        };
+    }
+    const tierBySlug = new Map();
+    const lockedSlugs = new Set();
+    for (const r of publicRows) {
+        if (r.requiredTier != null || r.pricingModel != null) {
+            tierBySlug.set(r.slug, {
+                requiredTier: r.requiredTier ?? null,
+                pricingModel: r.pricingModel ?? null,
+            });
+        }
+        // Locked = declares a tier this account's `/available` set doesn't include.
+        if (availableSlugs && r.requiredTier && !availableSlugs.has(r.slug)) {
+            lockedSlugs.add(r.slug);
+        }
+    }
+    // Dedup by slug; `/mine` rows overwrite public ones so the private flag wins.
+    const bySlug = new Map();
+    for (const r of publicRows)
+        bySlug.set(r.slug, rowToRemoteEntry(r, undefined));
+    for (const r of mineRows)
+        bySlug.set(r.slug, r);
+    const rows = [...bySlug.values()];
+    return {
+        rows,
+        status: "ok",
+        loggedIn: true,
+        email: creds.email,
+        privateCount: rows.filter((r) => r.isPrivate).length,
+        tierBySlug,
+        lockedSlugs,
+    };
+}
+//# sourceMappingURL=cp-packages.js.map

package/dist/lib/cp-packages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cp-packages.js","sourceRoot":"","sources":["../../src/lib/cp-packages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EACL,gBAAgB,GAIjB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAE5E,8EAA8E;AAC9E,8EAA8E;AAC9E,MAAM,YAAY,GAAG,GAAW,EAAE,CAAC,GAAG,QAAQ,EAAE,eAAe,CAAC;AAChE,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAsChC,8EAA8E;AAC9E,SAAS,UAAU,CACjB,OAAmC,EACnC,KAA6B;IAE7B,MAAM,CAAC,GAAG,IAAI,eAAe,CAAC,KAAK,CAAC,CAAC;IACrC,IAAI,OAAO,EAAE,MAAM;QAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,IAAI,OAAO,EAAE,QAAQ;QAAE,CAAC,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC3D,IAAI,OAAO,EAAE,GAAG;QAAE,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IAC5C,IAAI,OAAO,EAAE,QAAQ;QAAE,CAAC,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IACjD,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC;AACtB,CAAC;AAED,gFAAgF;AAChF,MAAM,WAAY,SAAQ,KAAK;IACpB,UAAU,GAAG,IAAI,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,OAAwB;IAExB,MAAM,EAAE,GAAG,UAAU,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACjD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,YAAY,EAAE,IAAI,EAAE,EAAE,EAAE;QACjD,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,gBAAgB,CAAC;KAC9C,CAAC,CAAC;IACH,IAAI,CAAC,GAAG,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1E,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAiC,CAAC;IAChE,OAAO,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;AAC7B,CAAC;AAED,gFAAgF;AAChF,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAAwB;IAExB,MAAM,IAAI,GAAG,MAAM,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAClD,2EAA2E;IAC3E,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,KAAa,EACb,OAAwB;IAExB,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,YAAY,EAAE,iBAAiB,EAAE;QAC1D,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,KAAK,EAAE,EAAE;QAC7C,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,gBAAgB,CAAC;KAC9C,CAAC,CAAC;IACH,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QAC7C,MAAM,IAAI,WAAW,CAAC,oCAAoC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1E,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IAC/E,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA+B,CAAC;IAC9D,IAAI,IAAI,GAAG,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;IAC/B,IAAI,OAAO,EAAE,QAAQ,EAAE,CAAC;QACtB,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,IAAI,IAAI,IAAI,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnF,CAAC;IACD,IAAI,OAAO,EAAE,MAAM,EAAE,CAAC;QACpB,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;QACvC,IAAI,GAAG,IAAI,CAAC,MAAM,CAChB,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;YAChC,CAAC,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;YACvC,CAAC,CAAC,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAClD,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,KAAa,EACb,OAAwB;IAExB,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC/C,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,QAAQ,KAAK,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;AACvF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,KAAa,EACb,OAAwB;IAExB,MAAM,EAAE,GAAG,UAAU,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACzE,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,YAAY,EAAE,cAAc,EAAE,EAAE,EAAE;QAC3D,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,KAAK,EAAE,EAAE;QAC7C,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,gBAAgB,CAAC;KAC9C,CAAC,CAAC;IACH,IAAI,CAAC,GAAG,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IACpF,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA2C,CAAC;IAC1E,OAAO,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,IAAY,EACZ,KAAc;IAEd,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,YAAY,EAAE,IAAI,kBAAkB,CAAC,IAAI,CAAC,EAAE,EAAE;QACvE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,UAAU,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE;QAC1D,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,gBAAgB,CAAC;KAC9C,CAAC,CAAC;IACH,IAAI,CAAC,GAAG,CAAC,EAAE;QAAE,OAAO,IAAI,CAAC;IACzB,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAE7B,CAAC;IACF,OAAO,IAAI,CAAC,OAAO,EAAE,UAAU,IAAI,IAAI,CAAC;AAC1C,CAAC;AAoBD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAwB;IAExB,MAAM,KAAK,GAAG,cAAc,EAAE,CAAC;IAC/B,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,qBAAqB,CAAC,KAAK,CAAC,CAAC;IAE1D,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO;YACL,IAAI,EAAE,EAAE;YACR,MAAM,EAAE,iBAAiB;YACzB,QAAQ,EAAE,KAAK;YACf,YAAY,EAAE,CAAC;YACf,UAAU,EAAE,IAAI,GAAG,EAAE;YACrB,WAAW,EAAE,IAAI,GAAG,EAAE;SACvB,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,GAAkB,EAAE,CAAC;IACnC,IAAI,QAAQ,GAAkB,EAAE,CAAC;IACjC,IAAI,cAAc,GAAuB,IAAI,CAAC;IAC9C,IAAI,CAAC;QACH,CAAC,UAAU,EAAE,QAAQ,EAAE,cAAc,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YACzD,yEAAyE;YACzE,oCAAoC;YACpC,qBAAqB,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAmB,CAAC;YAC/D,eAAe,CAAC,KAAM,CAAC,KAAK,EAAE,OAAO,CAAC;YACtC,uEAAuE;YACvE,6BAA6B;YAC7B,mBAAmB,CAAC,KAAM,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,UAAU,GAAI,CAA8B,CAAC,UAAU,KAAK,IAAI,CAAC;QACvE,OAAO;YACL,IAAI,EAAE,EAAE;YACR,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,aAAa;YACtD,QAAQ,EAAE,IAAI;YACd,KAAK,EAAE,KAAM,CAAC,KAAK;YACnB,YAAY,EAAE,CAAC;YACf,UAAU,EAAE,IAAI,GAAG,EAAE;YACrB,WAAW,EAAE,IAAI,GAAG,EAAE;SACvB,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC/C,MAAM,WAAW,GAAG,IAAI,GAAG,EAAU,CAAC;IACtC,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,IAAI,CAAC,CAAC,YAAY,IAAI,IAAI,IAAI,CAAC,CAAC,YAAY,IAAI,IAAI,EAAE,CAAC;YACrD,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE;gBACrB,YAAY,EAAE,CAAC,CAAC,YAAY,IAAI,IAAI;gBACpC,YAAY,EAAE,CAAC,CAAC,YAAY,IAAI,IAAI;aACrC,CAAC,CAAC;QACL,CAAC;QACD,4EAA4E;QAC5E,IAAI,cAAc,IAAI,CAAC,CAAC,YAAY,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;YACpE,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IAED,8EAA8E;IAC9E,MAAM,MAAM,GAAG,IAAI,GAAG,EAAuB,CAAC;IAC9C,KAAK,MAAM,CAAC,IAAI,UAAU;QAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC;IAC/E,KAAK,MAAM,CAAC,IAAI,QAAQ;QAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAChD,MAAM,IAAI,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAElC,OAAO;QACL,IAAI;QACJ,MAAM,EAAE,IAAI;QACZ,QAAQ,EAAE,IAAI;QACd,KAAK,EAAE,KAAM,CAAC,KAAK;QACnB,YAAY,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM;QACpD,UAAU;QACV,WAAW;KACZ,CAAC;AACJ,CAAC"}

package/dist/lib/describe-lens.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared lens display formatter.
+ *
+ * The lens itself — `{ workspaceId, projectId, focusSessionId }` — is resolved
+ * by `resolveActiveLens()` in `session-lens.ts`; this module only answers "how
+ * do we SHOW it". Before this existed, `commands/lens.ts` and
+ * `commands/statusline.ts` each hand-rolled their own "no workspace → pod-wide"
+ * / "no project → none" fallback text. One formatter now owns that logic so
+ * new surfaces (Raycast, `orient`) can render the same lens consistently.
+ *
+ * Colors/links are deliberately NOT baked in here — `lens.ts` uses chalk,
+ * `statusline.ts` uses raw ANSI + OSC-8 hyperlinks, and a future Raycast
+ * consumer will use neither. Callers wrap the plain names/ids this module
+ * resolves in whatever presentation their surface needs.
+ */
+export interface LensEntry {
+    id: string;
+    name?: string;
+}
+export interface ResolvedLens {
+    workspace?: LensEntry;
+    project?: LensEntry;
+    session?: LensEntry;
+}
+export interface DescribedLensField {
+    id: string;
+    /** Display name, falling back to the raw id when no name was resolved. */
+    name: string;
+}
+export interface DescribedLens {
+    structured: {
+        workspace?: DescribedLensField;
+        project?: DescribedLensField;
+        session?: DescribedLensField;
+        /** True iff neither a workspace nor a project is bound — fully pod-wide. */
+        podWide: boolean;
+    };
+    /** One "Label: value" line per field, in workspace/project/session order — value is the
+     * placeholder text when unset, so callers can print it as-is or re-color it. */
+    lines: Array<{
+        label: "Workspace" | "Project" | "Session";
+        value: string;
+        bound: boolean;
+    }>;
+}
+export declare function describeLens(lens: ResolvedLens): DescribedLens;

package/dist/lib/describe-lens.js

@@ -0,0 +1,33 @@
+/**
+ * Shared lens display formatter.
+ *
+ * The lens itself — `{ workspaceId, projectId, focusSessionId }` — is resolved
+ * by `resolveActiveLens()` in `session-lens.ts`; this module only answers "how
+ * do we SHOW it". Before this existed, `commands/lens.ts` and
+ * `commands/statusline.ts` each hand-rolled their own "no workspace → pod-wide"
+ * / "no project → none" fallback text. One formatter now owns that logic so
+ * new surfaces (Raycast, `orient`) can render the same lens consistently.
+ *
+ * Colors/links are deliberately NOT baked in here — `lens.ts` uses chalk,
+ * `statusline.ts` uses raw ANSI + OSC-8 hyperlinks, and a future Raycast
+ * consumer will use neither. Callers wrap the plain names/ids this module
+ * resolves in whatever presentation their surface needs.
+ */
+function describeField(entry) {
+    if (!entry?.id)
+        return undefined;
+    return { id: entry.id, name: entry.name?.trim() || entry.id };
+}
+export function describeLens(lens) {
+    const workspace = describeField(lens.workspace);
+    const project = describeField(lens.project);
+    const session = describeField(lens.session);
+    const podWide = !workspace && !project;
+    const lines = [
+        { label: "Workspace", value: workspace?.name ?? "— (pod-wide)", bound: Boolean(workspace) },
+        { label: "Project", value: project?.name ?? "— none", bound: Boolean(project) },
+        { label: "Session", value: session?.name ?? "— none", bound: Boolean(session) },
+    ];
+    return { structured: { workspace, project, session, podWide }, lines };
+}
+//# sourceMappingURL=describe-lens.js.map

package/dist/lib/describe-lens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-lens.js","sourceRoot":"","sources":["../../src/lib/describe-lens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAgCH,SAAS,aAAa,CAAC,KAAiB;IACtC,IAAI,CAAC,KAAK,EAAE,EAAE;QAAE,OAAO,SAAS,CAAC;IACjC,OAAO,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,KAAK,CAAC,EAAE,EAAE,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAkB;IAC7C,MAAM,SAAS,GAAG,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAChD,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAG,CAAC,SAAS,IAAI,CAAC,OAAO,CAAC;IAEvC,MAAM,KAAK,GAA2B;QACpC,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,IAAI,cAAc,EAAE,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,EAAE;QAC3F,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE;QAC/E,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE;KAChF,CAAC;IAEF,OAAO,EAAE,UAAU,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC;AACzE,CAAC"}

package/dist/lib/hub-client.d.ts

@@ -1,10 +1,73 @@
 import { HubRestClient } from "@synap/hub-rest-client";
+/**
+ * A failed Hub call, carrying the structured facts callers need to branch on.
+ *
+ * `message` is HUMAN-READABLE and is what the many `log.error((err as Error).message)`
+ * sites print. It keeps a literal `(HTTP <status>)` token: several call sites
+ * classify errors by matching that substring, and the token is the contract they
+ * depend on. The raw response body is kept on `rawBody` and never spliced into
+ * `message` — a JSON blob truncated mid-object is unreadable and leaks internals.
+ */
+export declare class HubError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly reason?: string;
+    readonly body?: unknown;
+    readonly rawBody: string;
+    readonly path: string;
+    readonly method: string;
+    constructor(init: {
+        message: string;
+        status: number;
+        code?: string;
+        reason?: string;
+        body?: unknown;
+        rawBody: string;
+        path: string;
+        method: string;
+    });
+}
+/**
+ * A Hub call that never reached the pod — DNS, TCP, TLS or timeout.
+ *
+ * Peer of {@link HubError}: same rendering path, same `message`-is-human-readable
+ * rule. It deliberately carries NO `(HTTP <status>)` token — there was no HTTP
+ * response, and the call sites that classify on that substring must not match.
+ * `podUrl` is the origin we failed to reach and `hint` is the next action.
+ */
+export declare class HubNetworkError extends Error {
+    /** Transport code we classified on: ENOTFOUND, ECONNREFUSED, TIMEOUT, TLS… */
+    readonly code: string;
+    readonly podUrl: string;
+    readonly path: string;
+    readonly method: string;
+    /** The one thing the user should do next. Rendered under the message. */
+    readonly hint: string;
+    constructor(init: {
+        message: string;
+        code: string;
+        podUrl: string;
+        path: string;
+        method: string;
+        hint: string;
+        cause?: unknown;
+    });
+}
+/**
+ * Print a failed Hub call: its humanized message plus a hint for the classes
+ * where the cause is not obvious from the message alone. Lives here rather than
+ * in utils/logger so the logger stays domain-agnostic and the taxonomy and its
+ * presentation sit in one file.
+ */
+export declare function renderHubError(err: unknown): void;
 export interface HubConfig {
     podUrl: string;
     apiKey: string;
     userId: string;
     /** Active workspace — from `synap use`, pod default, or env var. Undefined if none configured. */
     workspaceId?: string;
+    /** Active project — from `synap project use`, pod default, or env var. Peer of workspaceId; independent. */
+    projectId?: string;
     scopes?: string[];
 }
 export declare function resolveUserId(cfg: HubConfig): Promise<string>;
@@ -13,9 +76,29 @@ export declare function resolveHubConfig(opts?: {
     podUrl?: string;
     apiKey?: string;
 }): Promise<HubConfig>;
+/** Read the active session ID for this terminal from CWD or env var. */
+export declare function readActiveSessionId(): string | undefined;
+/** Attach a session to this terminal — writes .synap-session in CWD. */
+export declare function writeActiveSessionId(sessionId: string): void;
+/** Detach the active session from this terminal — removes .synap-session. */
+export declare function clearActiveSessionId(): void;
 export declare function hubGet(path: string, params: Record<string, string | number | undefined>, cfg: HubConfig): Promise<unknown>;
-export declare function hubPost(path: string, body: unknown, cfg: HubConfig): Promise<unknown>;
+export declare function hubPost(path: string, body: unknown, cfg: HubConfig, timeoutMs?: number): Promise<unknown>;
+/**
+ * Multipart POST for Hub doors that accept file uploads (e.g. source-file).
+ * Do NOT set Content-Type — fetch sets the boundary for FormData.
+ *
+ * Note: on 429 retry we cannot re-use a consumed FormData body in all runtimes.
+ * Callers that hit 429 mid-bulk should rebuild FormData — see hubPostMultipartRetryable.
+ */
+export declare function hubPostMultipart(path: string, form: FormData, cfg: HubConfig, timeoutMs?: number): Promise<unknown>;
+/**
+ * Multipart POST that rebuilds the body on each 429 retry (FormData streams
+ * can only be read once).
+ */
+export declare function hubPostMultipartRetryable(path: string, buildForm: () => FormData, cfg: HubConfig, timeoutMs?: number): Promise<unknown>;
 export declare function hubPatch(path: string, body: unknown, cfg: HubConfig): Promise<unknown>;
+export declare function hubDelete(path: string, cfg: HubConfig): Promise<unknown>;
 /**
  * Create a typed HubRestClient from a resolved HubConfig.
  * Use this in new code and shared surfaces (e.g. Raycast) to get full