@synap-core/cli 1.10.0 → 1.12.2

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-wide.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Pod-wide vocabulary — ONE canonical spelling for "not scoped to a workspace".
+ *
+ * The CLI had four different spellings of the pod-wide idea:
+ *
+ *   1. `--global`            boolean flag on `capture` (index.ts:648 → knowledge.ts:628)
+ *   2. omitting `--workspace` documented as "(omit for pod-wide)" on ask/capture/
+ *                            knowledge/cell (index.ts:318, 623, 896, 1858)
+ *   3. omitting `--pin-workspace` documented as "(default: pod-wide lens)" (index.ts:116)
+ *   4. `__pod_wide__`        internal sentinel in the launch picker (launch.ts:576)
+ *
+ * Only #1 is a knob the user TYPES to opt in; #2 and #3 are absences (a
+ * different mechanism — you cannot alias "not passing a flag"), and #4 never
+ * leaves the process. So the unification here is narrow and honest: canonicalise
+ * the typed opt-in, and leave the absences alone rather than pretend they are
+ * spellings of the same switch.
+ *
+ * CANONICAL: `--pod-wide`. Chosen over `--global` because "global" is already
+ * overloaded in this CLI to mean "durable rather than per-session" — `synap use`
+ * and `synap project use` both report `scope: "global"` for exactly that other
+ * meaning (data.ts:229,281; lens.ts:227,355,396). "Pod-wide" is the term the
+ * data model and every help string already use for the scope axis, so it is the
+ * one that cannot be misread.
+ *
+ * `--global` remains an accepted ALIAS — it is what every existing script and
+ * the `synap capture --global` line in CLAUDE.md types, and breaking that to win
+ * a naming argument would be a worse defect than the inconsistency.
+ */
+/** Every accepted spelling of the pod-wide opt-in. First entry is canonical. */
+export declare const POD_WIDE_FLAGS: readonly ["pod-wide", "global"];
+/** True when a user-supplied scope value spells "pod-wide" rather than naming a workspace. */
+export declare function isPodWideToken(value: string | undefined | null): boolean;
+/**
+ * Resolve the pod-wide opt-in from parsed options, accepting every spelling.
+ * Commander camel-cases `--pod-wide` to `podWide`.
+ */
+export declare function resolvePodWide(opts: {
+    podWide?: boolean;
+    global?: boolean;
+}): boolean;

package/dist/lib/pod-wide.js

@@ -0,0 +1,46 @@
+/**
+ * Pod-wide vocabulary — ONE canonical spelling for "not scoped to a workspace".
+ *
+ * The CLI had four different spellings of the pod-wide idea:
+ *
+ *   1. `--global`            boolean flag on `capture` (index.ts:648 → knowledge.ts:628)
+ *   2. omitting `--workspace` documented as "(omit for pod-wide)" on ask/capture/
+ *                            knowledge/cell (index.ts:318, 623, 896, 1858)
+ *   3. omitting `--pin-workspace` documented as "(default: pod-wide lens)" (index.ts:116)
+ *   4. `__pod_wide__`        internal sentinel in the launch picker (launch.ts:576)
+ *
+ * Only #1 is a knob the user TYPES to opt in; #2 and #3 are absences (a
+ * different mechanism — you cannot alias "not passing a flag"), and #4 never
+ * leaves the process. So the unification here is narrow and honest: canonicalise
+ * the typed opt-in, and leave the absences alone rather than pretend they are
+ * spellings of the same switch.
+ *
+ * CANONICAL: `--pod-wide`. Chosen over `--global` because "global" is already
+ * overloaded in this CLI to mean "durable rather than per-session" — `synap use`
+ * and `synap project use` both report `scope: "global"` for exactly that other
+ * meaning (data.ts:229,281; lens.ts:227,355,396). "Pod-wide" is the term the
+ * data model and every help string already use for the scope axis, so it is the
+ * one that cannot be misread.
+ *
+ * `--global` remains an accepted ALIAS — it is what every existing script and
+ * the `synap capture --global` line in CLAUDE.md types, and breaking that to win
+ * a naming argument would be a worse defect than the inconsistency.
+ */
+/** Every accepted spelling of the pod-wide opt-in. First entry is canonical. */
+export const POD_WIDE_FLAGS = ["pod-wide", "global"];
+/** Accepted string tokens meaning "pod-wide" where a scope VALUE is parsed. */
+const POD_WIDE_TOKENS = new Set(["pod", "pod-wide", "podwide", "pod_wide", "global"]);
+/** True when a user-supplied scope value spells "pod-wide" rather than naming a workspace. */
+export function isPodWideToken(value) {
+    if (!value)
+        return false;
+    return POD_WIDE_TOKENS.has(value.trim().toLowerCase());
+}
+/**
+ * Resolve the pod-wide opt-in from parsed options, accepting every spelling.
+ * Commander camel-cases `--pod-wide` to `podWide`.
+ */
+export function resolvePodWide(opts) {
+    return Boolean(opts.podWide || opts.global);
+}
+//# sourceMappingURL=pod-wide.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pod-wide.js","sourceRoot":"","sources":["../../src/lib/pod-wide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,gFAAgF;AAChF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAU,CAAC;AAE9D,+EAA+E;AAC/E,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC;AAEtF,8FAA8F;AAC9F,MAAM,UAAU,cAAc,CAAC,KAAgC;IAC7D,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,OAAO,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;AACzD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,IAA6C;IAC1E,OAAO,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC;AAC9C,CAAC"}