@synap-core/cli 1.11.0 → 1.13.0

package/dist/lib/package-wire.d.ts

@@ -0,0 +1,179 @@
+/**
+ * The per-kind wire envelopes and the ONE unwrap — import-free on purpose.
+ *
+ * Re-exported (with the workspace types) by `./wire`, the public subpath
+ * `@synap-core/workspace-templates/wire`. It has no imports so a consumer that
+ * still resolves an older npm copy of this package (the CLI, the CP, the pod)
+ * can carry it as a BYTE-IDENTICAL mirror pinned by a tripwire until it can
+ * import the subpath. Edit it here; the mirror copies it.
+ *
+ * What `GET {CP}/api/packages/:slug` serves as `package.definition`, per kind:
+ * the outputs of this package's producers (`scripts/catalog-lib.mjs`
+ * `toPublishBody`; `toOfficialPublishBody` for workspaces) plus what the CP
+ * adds on store/serve (`_meta.slug` via `withTemplateSlug`,
+ * `capability.contentHash`).
+ *
+ * WHY: a skill package is served as `{ _meta, skill: {…} }`. Read flat, every
+ * field is `undefined`: install refused a "bodiless" skill and the update door
+ * reported "no drift" forever (founder pod 2026-10-13, creative-director). Each
+ * consumer had its own cast; this is the one place the envelope is known.
+ *
+ * Element fields are pinned to the catalog schema (`SKILL_FIELDS`,
+ * `CapabilitySpec`) and `AutomationElement` to `PackageAutomationWire` by
+ * `schema/wire.parity.test.ts` (compile time).
+ */
+/** The kinds whose served definition this module describes. */
+export declare const WIRE_KINDS: readonly ["workspace", "capability", "skill", "automation", "view"];
+export type WireKind = (typeof WIRE_KINDS)[number];
+/**
+ * Other names the same kinds go by: the pod's `market.install` says
+ * `template`, the CP category for an automation is `workflow`, and a pack is
+ * a workspace-shaped definition.
+ */
+export declare const WIRE_KIND_ALIASES: {
+    readonly template: "workspace";
+    readonly pack: "workspace";
+    readonly workflow: "automation";
+};
+export type WireKindName = WireKind | keyof typeof WIRE_KIND_ALIASES;
+/** `template` → `workspace`, `workflow` → `automation`; `null` for a kind with no wire contract here (e.g. `cell`). */
+export declare function toWireKind(kind: string): WireKind | null;
+/**
+ * `definition._meta` as served: the CP stamps `slug` on every row (the pod
+ * keys "which space is this template's?" on it); the CLI adds the `version`
+ * label it installs.
+ */
+export interface WireMeta {
+    slug?: string;
+    version?: string;
+    [key: string]: unknown;
+}
+/** `meta.icon` / `color` / `domain`, mirrored onto the definition by every publish builder. */
+export interface WireIdentity {
+    icon?: string;
+    color?: string;
+    domain?: string;
+}
+/** A composition dependency. */
+export interface WireDependency {
+    slug: string;
+    kind?: "workspace" | "capability" | "skill" | "workflow" | "view" | "cell" | "automation";
+    relation?: "compose" | "require";
+    reason?: string;
+}
+export interface WireEnvelope extends WireIdentity {
+    _meta?: WireMeta;
+    dependencies?: WireDependency[];
+}
+/** The capability itself (`CapabilityDefinition`). */
+export interface CapabilityElement {
+    key: string;
+    name: string;
+    description?: string;
+    params?: Array<Record<string, unknown>>;
+    vault?: Array<Record<string, unknown>>;
+    tools?: Array<Record<string, unknown>>;
+    skills?: Array<Record<string, unknown>>;
+    provides?: string[];
+    playbooks?: Array<Record<string, unknown>>;
+    /** Stamped by the CP on publish; the pod's drift marker. */
+    contentHash?: string;
+    automations?: Array<Record<string, unknown>>;
+    mcpServers?: unknown;
+    metadata?: Record<string, unknown>;
+    _generated?: unknown;
+}
+/** capability: `{ profiles: [], description, capability }`. */
+export interface CapabilityWire extends WireEnvelope {
+    profiles: unknown[];
+    description?: string;
+    capability: CapabilityElement;
+}
+/** ONE standalone skill. Not a workspace's `skills[]` link list. */
+export interface SkillElement {
+    /** The pod-side `load_skill` ref — its own identity, not the package slug. */
+    slug?: string;
+    name?: string;
+    displayName?: string;
+    description?: string;
+    kind?: "instruction" | "code" | "declarative" | "builtin";
+    scope?: "pod" | "user" | "workspace";
+    agentTypes?: string[];
+    body?: string;
+    code?: string;
+    providerSpec?: Record<string, unknown>;
+    parameters?: Record<string, unknown>;
+    category?: string;
+    executionMode?: "sync" | "async";
+    timeoutSeconds?: number;
+    intent?: string;
+    [key: string]: unknown;
+}
+/** skill: `{ skill, icon?, color?, domain?, dependencies? }`. */
+export interface SkillWire extends WireEnvelope {
+    skill: SkillElement;
+}
+/** One graph automation (= `PackageAutomationWire`): `flowDefinition`, not the authored `flow`. */
+export interface AutomationElement {
+    key?: string;
+    name: string;
+    description?: string;
+    triggerType: "event" | "cron" | "webhook" | "manual";
+    triggerConfig?: Record<string, unknown>;
+    flowDefinition?: {
+        nodes: unknown[];
+        edges: unknown[];
+        precondition?: string;
+    };
+    status?: "draft" | "active" | "paused";
+}
+/** automation (CP category `workflow`): `{ profiles: [], automations: [one] }`. */
+export interface AutomationWire extends WireEnvelope {
+    profiles: unknown[];
+    automations: AutomationElement[];
+}
+/** One view, as the pod's view install and update doors read it. */
+export interface ViewElement {
+    slug?: string;
+    name?: string;
+    displayName?: string;
+    description?: string;
+    type?: string;
+    config?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    scopeProfileSlugs?: string[];
+    scopeProfileIds?: string[];
+    [key: string]: unknown;
+}
+/** view: `{ views: [...] }`, or a legacy single view with its fields on top (has its own `type`). No catalog producer today. */
+export type ViewWire = (WireEnvelope & {
+    views: ViewElement[];
+}) | ViewElement;
+/**
+ * What {@link unwrapPackage} returns per kind. `workspace` is the definition
+ * itself; `./wire` narrows it to `WorkspaceWire`.
+ */
+export interface PackageElementByKind<W = Record<string, unknown>> {
+    workspace: W;
+    capability: CapabilityElement;
+    skill: SkillElement;
+    automation: AutomationElement[];
+    view: ViewElement[];
+}
+export type ElementOf<K extends WireKindName, W = Record<string, unknown>> = PackageElementByKind<W>[K extends WireKind ? K : K extends keyof typeof WIRE_KIND_ALIASES ? (typeof WIRE_KIND_ALIASES)[K] : never];
+/**
+ * The installable element(s) inside a served definition:
+ *
+ *   skill      → the `skill` object (a legacy flat definition is the skill itself)
+ *   capability → the `capability` object (a flat `CapabilityDefinition` — the
+ *                pod cache / CP by-key shape — passes through)
+ *   automation → `automations[]` (`[]` when the definition declares none)
+ *   view       → `views[]`, or a legacy flat view (top-level `type`) as `[def]`, else `[]`
+ *   workspace  → the definition itself
+ *
+ * An empty array means the definition declares none; the install doors refuse
+ * that themselves. A definition that is not an object is a failed read, never
+ * an empty one: it throws.
+ */
+export declare function unwrapPackage<K extends WireKindName>(kind: K, definition: unknown): ElementOf<K>;

package/dist/lib/package-wire.js

@@ -0,0 +1,68 @@
+/**
+ * The per-kind wire envelopes and the ONE unwrap — import-free on purpose.
+ *
+ * Re-exported (with the workspace types) by `./wire`, the public subpath
+ * `@synap-core/workspace-templates/wire`. It has no imports so a consumer that
+ * still resolves an older npm copy of this package (the CLI, the CP, the pod)
+ * can carry it as a BYTE-IDENTICAL mirror pinned by a tripwire until it can
+ * import the subpath. Edit it here; the mirror copies it.
+ *
+ * What `GET {CP}/api/packages/:slug` serves as `package.definition`, per kind:
+ * the outputs of this package's producers (`scripts/catalog-lib.mjs`
+ * `toPublishBody`; `toOfficialPublishBody` for workspaces) plus what the CP
+ * adds on store/serve (`_meta.slug` via `withTemplateSlug`,
+ * `capability.contentHash`).
+ *
+ * WHY: a skill package is served as `{ _meta, skill: {…} }`. Read flat, every
+ * field is `undefined`: install refused a "bodiless" skill and the update door
+ * reported "no drift" forever (founder pod 2026-10-13, creative-director). Each
+ * consumer had its own cast; this is the one place the envelope is known.
+ *
+ * Element fields are pinned to the catalog schema (`SKILL_FIELDS`,
+ * `CapabilitySpec`) and `AutomationElement` to `PackageAutomationWire` by
+ * `schema/wire.parity.test.ts` (compile time).
+ */
+// ─── Kinds ──────────────────────────────────────────────────────────────────
+/** The kinds whose served definition this module describes. */
+export const WIRE_KINDS = ["workspace", "capability", "skill", "automation", "view"];
+/**
+ * Other names the same kinds go by: the pod's `market.install` says
+ * `template`, the CP category for an automation is `workflow`, and a pack is
+ * a workspace-shaped definition.
+ */
+export const WIRE_KIND_ALIASES = {
+    template: "workspace",
+    pack: "workspace",
+    workflow: "automation",
+};
+/** `template` → `workspace`, `workflow` → `automation`; `null` for a kind with no wire contract here (e.g. `cell`). */
+export function toWireKind(kind) {
+    if (WIRE_KINDS.includes(kind))
+        return kind;
+    return WIRE_KIND_ALIASES[kind] ?? null;
+}
+// ─── The ONE unwrap ─────────────────────────────────────────────────────────
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+export function unwrapPackage(kind, definition) {
+    const wireKind = toWireKind(kind);
+    if (!wireKind)
+        throw new Error(`unwrapPackage: "${kind}" has no wire contract`);
+    if (!isRecord(definition)) {
+        throw new TypeError(`unwrapPackage(${kind}): the definition is not an object (${definition === null ? "null" : Array.isArray(definition) ? "array" : typeof definition})`);
+    }
+    switch (wireKind) {
+        case "skill":
+            return isRecord(definition.skill) ? definition.skill : definition;
+        case "capability":
+            return isRecord(definition.capability) ? definition.capability : definition;
+        case "automation":
+            return Array.isArray(definition.automations) ? definition.automations : [];
+        case "view":
+            if (Array.isArray(definition.views) && definition.views.length > 0)
+                return definition.views;
+            return definition.type ? [definition] : [];
+        case "workspace":
+            return definition;
+    }
+}
+//# sourceMappingURL=package-wire.js.map

package/dist/lib/package-wire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-wire.js","sourceRoot":"","sources":["../../src/lib/package-wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,+EAA+E;AAE/E,+DAA+D;AAC/D,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,WAAW,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,CAAU,CAAC;AAG9F;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,QAAQ,EAAE,WAAW;IACrB,IAAI,EAAE,WAAW;IACjB,QAAQ,EAAE,YAAY;CACqB,CAAC;AAG9C,uHAAuH;AACvH,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,IAAK,UAAgC,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAgB,CAAC;IAC9E,OAAQ,iBAA8C,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;AACvE,CAAC;AA8ID,+EAA+E;AAE/E,MAAM,QAAQ,GAAG,CAAC,CAAU,EAAgC,EAAE,CAC5D,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAiB3D,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,UAAmB;IAC7D,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,CAAC,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,wBAAwB,CAAC,CAAC;IAChF,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,SAAS,CACjB,iBAAiB,IAAI,uCAAuC,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,UAAU,GAAG,CACtJ,CAAC;IACJ,CAAC;IACD,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,OAAO;YACV,OAAO,QAAQ,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC;QACpE,KAAK,YAAY;YACf,OAAO,QAAQ,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC;QAC9E,KAAK,YAAY;YACf,OAAO,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7E,KAAK,MAAM;YACT,IAAI,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;gBAAE,OAAO,UAAU,CAAC,KAAK,CAAC;YAC5F,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,KAAK,WAAW;YACd,OAAO,UAAU,CAAC;IACtB,CAAC;AACH,CAAC"}

package/dist/lib/pair-link.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Phone pairing — the link `synap init` prints as a QR so Relay can reach this pod.
+ *
+ * Contract (Relay is the receiver; it owns the screen that consumes it):
+ *
+ *   synap://pair?v=1&pod=<url-encoded pod origin>[&email=<CP account>]
+ *
+ *   - `v`     grammar version. A receiver that sees an unknown `v` must refuse
+ *             and say "update Relay", never guess.
+ *   - `pod`   the pod's ORIGIN only (scheme + host + port, no path). https, or
+ *             http for a LAN host only: a public host over plain http would
+ *             send the phone's sign-in in the clear, so it is refused. Relay
+ *             pre-fills its sign-in with this pod; it never trusts it for auth.
+ *   - `email` OPTIONAL: the Synap account the CLI is signed in to. Relay
+ *             pre-fills the sign-in email with it. Not a credential.
+ *
+ * `token` is RESERVED by Relay's parser (it ignores it) for a future
+ * short-lived pairing token. No pod or CP door mints one yet, so the builder
+ * takes none; add the parameter when that door exists.
+ *
+ * The scheme is `synap` (relay's app.json declares `["synap", "relay"]`), and a
+ * single-segment host (`pair`) is what relay's `useDeepLinkHandler` reads as
+ * `deepLinkPath === "pair"`.
+ */
+export declare const PAIR_LINK_VERSION = "1";
+export type PairLinkResult = {
+    ok: true;
+    link: string;
+} | {
+    ok: false;
+    reason: "invalid-url" | "loopback" | "insecure";
+};
+export declare function buildPairLink(opts: {
+    podUrl: string;
+    email?: string;
+}): PairLinkResult;
+/** The link as a terminal QR code (half-block characters, fits ~30 rows). */
+export declare function renderTerminalQr(text: string): Promise<string>;

package/dist/lib/pair-link.js

@@ -0,0 +1,68 @@
+/**
+ * Phone pairing — the link `synap init` prints as a QR so Relay can reach this pod.
+ *
+ * Contract (Relay is the receiver; it owns the screen that consumes it):
+ *
+ *   synap://pair?v=1&pod=<url-encoded pod origin>[&email=<CP account>]
+ *
+ *   - `v`     grammar version. A receiver that sees an unknown `v` must refuse
+ *             and say "update Relay", never guess.
+ *   - `pod`   the pod's ORIGIN only (scheme + host + port, no path). https, or
+ *             http for a LAN host only: a public host over plain http would
+ *             send the phone's sign-in in the clear, so it is refused. Relay
+ *             pre-fills its sign-in with this pod; it never trusts it for auth.
+ *   - `email` OPTIONAL: the Synap account the CLI is signed in to. Relay
+ *             pre-fills the sign-in email with it. Not a credential.
+ *
+ * `token` is RESERVED by Relay's parser (it ignores it) for a future
+ * short-lived pairing token. No pod or CP door mints one yet, so the builder
+ * takes none; add the parameter when that door exists.
+ *
+ * The scheme is `synap` (relay's app.json declares `["synap", "relay"]`), and a
+ * single-segment host (`pair`) is what relay's `useDeepLinkHandler` reads as
+ * `deepLinkPath === "pair"`.
+ */
+import QRCode from "qrcode";
+export const PAIR_LINK_VERSION = "1";
+/** Hosts a phone can never reach: the pod is only on this computer. */
+function isLoopbackHost(h) {
+    return h === "localhost" || h.endsWith(".localhost") || h === "::1" || h === "0.0.0.0" || /^127\./.test(h);
+}
+/** A host only reachable on the local network, where plain http is tolerable. */
+function isLanHost(h) {
+    if (h.endsWith(".local") || h.endsWith(".lan") || h.endsWith(".home.arpa"))
+        return true;
+    const m = /^(\d{1,3})\.(\d{1,3})\.\d{1,3}\.\d{1,3}$/.exec(h);
+    if (m) {
+        const a = Number(m[1]);
+        const b = Number(m[2]);
+        return a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254);
+    }
+    // IPv6 unique-local (fc00::/7) and link-local (fe80::/10).
+    return /^f[cd][0-9a-f]{2}:/.test(h) || /^fe[89ab][0-9a-f]:/.test(h);
+}
+export function buildPairLink(opts) {
+    let url;
+    try {
+        url = new URL(opts.podUrl);
+    }
+    catch {
+        return { ok: false, reason: "invalid-url" };
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:")
+        return { ok: false, reason: "invalid-url" };
+    const host = url.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    if (isLoopbackHost(host))
+        return { ok: false, reason: "loopback" };
+    if (url.protocol === "http:" && !isLanHost(host))
+        return { ok: false, reason: "insecure" };
+    const params = new URLSearchParams({ v: PAIR_LINK_VERSION, pod: url.origin });
+    if (opts.email)
+        params.set("email", opts.email);
+    return { ok: true, link: `synap://pair?${params.toString()}` };
+}
+/** The link as a terminal QR code (half-block characters, fits ~30 rows). */
+export async function renderTerminalQr(text) {
+    return QRCode.toString(text, { type: "terminal", small: true });
+}
+//# sourceMappingURL=pair-link.js.map

package/dist/lib/pair-link.js.map

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

package/dist/lib/pod-moved.d.ts

@@ -0,0 +1,70 @@
+/**
+ * A pod that moved to a new address.
+ *
+ * Hosted pods move from `{name}.synap.live` to `{name}.pod.synap.live`
+ * (Control Plane "tenant domains v2"). For 90 days the old name answers every
+ * request with a redirect to the new one. The CLI NEVER follows a redirect to
+ * another host for an API call: the request carries the pod key, and a
+ * redirect is something any server on the old name can send. Instead:
+ *
+ *   1. every pod call goes through `podFetch`, which refuses a cross-host
+ *      redirect with `PodMovedError` (one line: what happened, what to run);
+ *   2. `synap doctor` asks the Control Plane where the pod lives now —
+ *      `POST {cp}/pods/handshake {targetUrl: <old url>}` answers
+ *      `410 {code: "POD_MOVED", podId, podUrl, consoleUrl}` for a moved pod
+ *      (CP `src/routes/pods.ts`, `src/lib/pod-handshake-problem.ts`) —
+ *      and `synap doctor --fix` rewrites the saved profile through the one
+ *      door for a URL change (`synap pods update`).
+ *
+ * The new address comes ONLY from the Control Plane, never from the redirect.
+ */
+/** What to run when a pod has moved. */
+export declare const POD_MOVED_HINT = "Run: synap doctor --fix   (it finds the new address and updates your settings)";
+/** The one line a command prints when its pod has moved. */
+export declare function podMovedMessage(podUrl: string): string;
+export declare class PodMovedError extends Error {
+    /** The address the CLI holds (origin). */
+    readonly podUrl: string;
+    /** Where the old address redirected — informational only, never used. */
+    readonly redirectedTo: string;
+    constructor(podUrl: string, redirectedTo: string);
+}
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/**
+ * `fetch` for calls to a pod: redirects within the same host are followed (at
+ * most 5), a redirect to another host throws `PodMovedError`. Network errors
+ * propagate unchanged, so callers keep their own transport classification.
+ */
+export declare function podFetch(url: string, init?: RequestInit, fetchImpl?: FetchLike): Promise<Response>;
+/** What the Control Plane says about a pod address. */
+export type PodMoveAnswer = {
+    kind: "moved";
+    podUrl: string;
+    consoleUrl?: string;
+    podId?: string;
+}
+/** The CP knows this address as the pod's own (or knows nothing to move). */
+ | {
+    kind: "not-moved";
+    code?: string;
+}
+/** No Control Plane sign-in on this computer, or it expired. */
+ | {
+    kind: "signed-out";
+}
+/** The CP could not be asked, or answered something unreadable. */
+ | {
+    kind: "unknown";
+    reason: string;
+};
+/**
+ * Ask the Control Plane where a pod lives now. Needs the CP sign-in from
+ * `synap login` (a bearer token); without one the answer is `signed-out`.
+ */
+export declare function askControlPlaneWherePodIs(params: {
+    podUrl: string;
+    cpUrl: string;
+    cpToken: string | undefined;
+    fetchImpl?: FetchLike;
+}): Promise<PodMoveAnswer>;
+export {};

package/dist/lib/pod-moved.js

@@ -0,0 +1,146 @@
+/**
+ * A pod that moved to a new address.
+ *
+ * Hosted pods move from `{name}.synap.live` to `{name}.pod.synap.live`
+ * (Control Plane "tenant domains v2"). For 90 days the old name answers every
+ * request with a redirect to the new one. The CLI NEVER follows a redirect to
+ * another host for an API call: the request carries the pod key, and a
+ * redirect is something any server on the old name can send. Instead:
+ *
+ *   1. every pod call goes through `podFetch`, which refuses a cross-host
+ *      redirect with `PodMovedError` (one line: what happened, what to run);
+ *   2. `synap doctor` asks the Control Plane where the pod lives now —
+ *      `POST {cp}/pods/handshake {targetUrl: <old url>}` answers
+ *      `410 {code: "POD_MOVED", podId, podUrl, consoleUrl}` for a moved pod
+ *      (CP `src/routes/pods.ts`, `src/lib/pod-handshake-problem.ts`) —
+ *      and `synap doctor --fix` rewrites the saved profile through the one
+ *      door for a URL change (`synap pods update`).
+ *
+ * The new address comes ONLY from the Control Plane, never from the redirect.
+ */
+/** What to run when a pod has moved. */
+export const POD_MOVED_HINT = "Run: synap doctor --fix   (it finds the new address and updates your settings)";
+/** The one line a command prints when its pod has moved. */
+export function podMovedMessage(podUrl) {
+    return `The pod at ${podUrl} has a new address. Run: synap doctor --fix`;
+}
+export class PodMovedError extends Error {
+    /** The address the CLI holds (origin). */
+    podUrl;
+    /** Where the old address redirected — informational only, never used. */
+    redirectedTo;
+    constructor(podUrl, redirectedTo) {
+        super(podMovedMessage(podUrl));
+        this.name = "PodMovedError";
+        this.podUrl = podUrl;
+        this.redirectedTo = redirectedTo;
+    }
+}
+const MAX_SAME_HOST_HOPS = 5;
+function isRedirect(status) {
+    return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
+}
+/**
+ * A redirect the CLI may follow: the same origin, or the same host upgraded
+ * from http to https (default ports). Anything else is another host.
+ */
+function isSameHost(from, to) {
+    if (from.origin === to.origin)
+        return true;
+    return (from.protocol === "http:" &&
+        to.protocol === "https:" &&
+        from.hostname === to.hostname &&
+        from.port === "" &&
+        to.port === "");
+}
+/**
+ * `fetch` for calls to a pod: redirects within the same host are followed (at
+ * most 5), a redirect to another host throws `PodMovedError`. Network errors
+ * propagate unchanged, so callers keep their own transport classification.
+ */
+export async function podFetch(url, init = {}, fetchImpl = fetch) {
+    const start = new URL(url);
+    let current = start;
+    let currentInit = init;
+    for (let hop = 0;; hop++) {
+        const res = await fetchImpl(current.toString(), { ...currentInit, redirect: "manual" });
+        if (!isRedirect(res.status))
+            return res;
+        const location = res.headers.get("location");
+        if (!location)
+            return res;
+        let next;
+        try {
+            next = new URL(location, current);
+        }
+        catch {
+            return res;
+        }
+        if (!isSameHost(start, next)) {
+            throw new PodMovedError(start.origin, next.origin);
+        }
+        if (hop >= MAX_SAME_HOST_HOPS)
+            return res;
+        if (res.status === 303 && (currentInit.method ?? "GET").toUpperCase() !== "GET") {
+            const { body: _body, ...rest } = currentInit;
+            currentInit = { ...rest, method: "GET" };
+        }
+        current = next;
+    }
+}
+/**
+ * Ask the Control Plane where a pod lives now. Needs the CP sign-in from
+ * `synap login` (a bearer token); without one the answer is `signed-out`.
+ */
+export async function askControlPlaneWherePodIs(params) {
+    if (!params.cpToken)
+        return { kind: "signed-out" };
+    const fetchImpl = params.fetchImpl ?? fetch;
+    let res;
+    try {
+        res = await fetchImpl(`${params.cpUrl.replace(/\/+$/, "")}/pods/handshake`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${params.cpToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ targetUrl: params.podUrl }),
+            redirect: "manual",
+            signal: AbortSignal.timeout(10_000),
+        });
+    }
+    catch (err) {
+        return { kind: "unknown", reason: err instanceof Error ? err.message : String(err) };
+    }
+    if (res.status === 401)
+        return { kind: "signed-out" };
+    const body = (await res.json().catch(() => null));
+    if (res.status === 410 && body?.code === "POD_MOVED") {
+        const podUrl = typeof body.podUrl === "string" ? safeHttpsOrigin(body.podUrl) : null;
+        if (!podUrl)
+            return { kind: "unknown", reason: "the Control Plane named no usable new address" };
+        return {
+            kind: "moved",
+            podUrl,
+            ...(typeof body.consoleUrl === "string" ? { consoleUrl: body.consoleUrl } : {}),
+            ...(typeof body.podId === "string" ? { podId: body.podId } : {}),
+        };
+    }
+    if (res.ok || res.status === 403 || res.status === 409) {
+        return { kind: "not-moved", ...(typeof body?.code === "string" ? { code: body.code } : {}) };
+    }
+    return { kind: "unknown", reason: `the Control Plane answered ${res.status}` };
+}
+/** An https origin, or null. A new pod address is never plain http. */
+function safeHttpsOrigin(value) {
+    try {
+        const url = new URL(value);
+        if (url.protocol !== "https:" || url.username || url.password)
+            return null;
+        return url.origin;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=pod-moved.js.map

package/dist/lib/pod-moved.js.map

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

package/dist/lib/pod-reach.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Why a pod probe failed, told apart: the network between this machine and the
+ * pod (egress proxy, DNS, firewall, TLS) versus the pod itself answering badly.
+ *
+ * `checkPodHealth` used to fold every failure into `healthy: false`, so `synap
+ * init` behind an egress proxy that answers 403 to CONNECT printed a pod-side
+ * checklist ("is the container running?") for a pod that was never contacted.
+ * This is the one place that taxonomy lives for the probe.
+ */
+export type ReachKind = 
+/** An egress proxy refused the CONNECT tunnel — the pod was never contacted. */
+"proxy"
+/** DNS, refused, reset, unroutable, timeout, TLS — no HTTP answer from anything. */
+ | "network"
+/** The pod host answered, but not with a healthy /health. */
+ | "pod";
+export interface ReachFailure {
+    kind: ReachKind;
+    /** The underlying error, one line: status / error code / message. */
+    detail: string;
+    /** Env variable whose proxy this process used, with credentials stripped. */
+    proxy?: {
+        env: string;
+        url: string;
+    };
+}
+/** The env proxy that applies to `podUrl`, credentials removed. Honors NO_PROXY. */
+export declare function proxyInUse(podUrl: string, env?: NodeJS.ProcessEnv): {
+    env: string;
+    url: string;
+} | undefined;
+/** Classify a fetch that threw (no HTTP answer from the pod). */
+export declare function classifyFetchError(err: unknown, podUrl: string, env?: NodeJS.ProcessEnv): ReachFailure;
+/** Classify a /health that answered with a non-2xx status. */
+export declare function classifyHttpStatus(status: number, podUrl: string, env?: NodeJS.ProcessEnv): ReachFailure;
+/** The lines `synap init` / `synap doctor` print under "not reachable", by cause. */
+export declare function reachChecklist(f: ReachFailure | undefined): string[];
+/** The one-line headline: names the underlying error, not just "not reachable". */
+export declare function unreachableMessage(podUrl: string, failure?: ReachFailure): string;