primitive-admin 1.1.0-alpha.6 → 1.1.0-alpha.60

package/dist/src/lib/block-layout.js

@@ -0,0 +1,451 @@
+/**
+ * Sync v2 "unified block" layout — issue #1183, Phase 3.
+ *
+ * The current (legacy) sync layout stores each managed block type in its own
+ * flat directory:
+ *
+ *   config/
+ *     prompts/<key>.toml
+ *     integrations/<key>.toml
+ *     workflows/<key>.toml
+ *     transforms/<name>.rhai            # scripts
+ *
+ * The v2 layout introduced by the unified block model groups every block type
+ * under one `blocks/` tree keyed by type and block key, with a single
+ * `block.toml` envelope per block (and a sibling `source.rhai` for scripts):
+ *
+ *   config/
+ *     blocks/
+ *       prompts/<key>/block.toml
+ *       integrations/<key>/block.toml
+ *       workflows/<key>/block.toml
+ *       scripts/<key>/block.toml
+ *       scripts/<key>/source.rhai
+ *
+ * Per the proposal (docs/proposals/unified-block-model.md, "Phase 3: Sync v2"),
+ * the CLI must:
+ *   - Read both legacy and v2 layouts.
+ *   - Preserve the legacy layout as the default until v2 is proven.
+ *   - Provide a migration command to convert legacy sync directories.
+ *
+ * This module is the pure, side-effect-light core of that work: the v2 path
+ * builders, the `block.toml` codec, layout detection, and the legacy -> v2
+ * migration. It stores the *verbatim* legacy TOML body under
+ * `[[versions]].spec`, so the transform is loss-free and a v2 block round-trips
+ * back to a byte-for-byte-equivalent legacy object (see `reconstructLegacyBlock`).
+ * That is what lets a later pass read a v2 directory through the same push path
+ * the legacy layout uses without re-deriving every type's field mapping.
+ */
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, } from "fs";
+import { createHash } from "crypto";
+import { basename, join } from "path";
+import { parseConfigToml, stringifyConfigToml } from "./config-toml.js";
+export const BLOCK_TYPES = [
+    "prompt",
+    "integration",
+    "workflow",
+    "script",
+];
+/** The `schemaVersion` string written at the top of every v2 `block.toml`. */
+export const BLOCK_SCHEMA_VERSION = "block/v1";
+/** The filename of the script body written next to a v2 script `block.toml`. */
+export const SCRIPT_SOURCE_FILENAME = "source.rhai";
+/**
+ * The named top-level TOML table each legacy block file wraps its header in
+ * (`[prompt]`, `[integration]`, `[workflow]`). Scripts have no header table —
+ * their legacy form is a raw `.rhai` body — so they are handled separately.
+ */
+const LEGACY_HEADER_KEY = {
+    prompt: "prompt",
+    integration: "integration",
+    workflow: "workflow",
+};
+/** Legacy per-type directory names (flat layout). */
+const LEGACY_DIR = {
+    prompt: "prompts",
+    integration: "integrations",
+    workflow: "workflows",
+    script: "transforms",
+};
+/**
+ * v2 per-type directory names under `blocks/`. Note scripts move from the
+ * legacy `transforms/` name to `scripts/` to match the block vocabulary.
+ */
+const V2_TYPE_DIR = {
+    prompt: "prompts",
+    integration: "integrations",
+    workflow: "workflows",
+    script: "scripts",
+};
+const V2_TYPE_DIR_TO_TYPE = {
+    prompts: "prompt",
+    integrations: "integration",
+    workflows: "workflow",
+    scripts: "script",
+};
+export function isBlockType(value) {
+    return (typeof value === "string" && BLOCK_TYPES.includes(value));
+}
+// ---------------------------------------------------------------------------
+// Path builders
+// ---------------------------------------------------------------------------
+/** `<configDir>/blocks` — the root of the v2 tree. */
+export function v2BlocksRoot(configDir) {
+    return join(configDir, "blocks");
+}
+/** `<configDir>/blocks/<typeDir>/<key>` — a single v2 block's directory. */
+export function v2BlockDir(configDir, type, key) {
+    return join(configDir, "blocks", V2_TYPE_DIR[type], key);
+}
+/** `<configDir>/blocks/<typeDir>/<key>/block.toml`. */
+export function v2BlockTomlPath(configDir, type, key) {
+    return join(v2BlockDir(configDir, type, key), "block.toml");
+}
+/** `<configDir>/blocks/scripts/<key>/source.rhai`. */
+export function v2ScriptSourcePath(configDir, key) {
+    return join(v2BlockDir(configDir, "script", key), SCRIPT_SOURCE_FILENAME);
+}
+/** `<configDir>/<legacyDir>` for a block type (flat layout). */
+export function legacyBlockDir(configDir, type) {
+    return join(configDir, LEGACY_DIR[type]);
+}
+function pruneUndefined(obj) {
+    for (const k of Object.keys(obj)) {
+        if (obj[k] === undefined)
+            delete obj[k];
+    }
+    return obj;
+}
+/**
+ * Serialize a v2 block into `block.toml` text. Key order is fixed
+ * (`schemaVersion`, `[block]`, `[[versions]]`) so a pull/migrate followed by a
+ * re-serialize is stable and produces no spurious diffs.
+ */
+export function serializeBlockToml(block) {
+    const data = {
+        schemaVersion: block.schemaVersion || BLOCK_SCHEMA_VERSION,
+        block: pruneUndefined({
+            type: block.block.type,
+            key: block.block.key,
+            displayName: block.block.displayName,
+            description: block.block.description,
+            status: block.block.status,
+            activeVersion: block.block.activeVersion,
+        }),
+        versions: block.versions.map((v) => pruneUndefined({
+            key: v.key,
+            status: v.status,
+            contentHash: v.contentHash,
+            spec: v.spec,
+        })),
+    };
+    return stringifyConfigToml(data);
+}
+/**
+ * Parse `block.toml` text into a `BlockToml`. Throws with a clear message when
+ * the envelope is malformed (missing/invalid `[block].type`, no versions).
+ */
+export function parseBlockToml(text) {
+    const parsed = parseConfigToml(text);
+    const header = parsed?.block;
+    if (!header || typeof header !== "object") {
+        throw new Error("block.toml is missing the [block] table");
+    }
+    if (!isBlockType(header.type)) {
+        throw new Error(`block.toml has an invalid [block].type: ${JSON.stringify(header.type)}`);
+    }
+    if (!header.key || typeof header.key !== "string") {
+        throw new Error("block.toml is missing a [block].key");
+    }
+    const rawVersions = Array.isArray(parsed.versions) ? parsed.versions : [];
+    const versions = rawVersions.map((v, i) => {
+        if (!v || typeof v !== "object") {
+            throw new Error(`block.toml version #${i} is not a table`);
+        }
+        return {
+            key: typeof v.key === "string" ? v.key : String(i),
+            status: typeof v.status === "string" ? v.status : undefined,
+            contentHash: typeof v.contentHash === "string" ? v.contentHash : undefined,
+            spec: v.spec && typeof v.spec === "object"
+                ? v.spec
+                : {},
+        };
+    });
+    if (versions.length === 0) {
+        throw new Error("block.toml has no [[versions]]");
+    }
+    return {
+        schemaVersion: typeof parsed.schemaVersion === "string"
+            ? parsed.schemaVersion
+            : BLOCK_SCHEMA_VERSION,
+        block: {
+            type: header.type,
+            key: header.key,
+            displayName: typeof header.displayName === "string"
+                ? header.displayName
+                : undefined,
+            description: typeof header.description === "string"
+                ? header.description
+                : undefined,
+            status: typeof header.status === "string" ? header.status : undefined,
+            activeVersion: typeof header.activeVersion === "string"
+                ? header.activeVersion
+                : undefined,
+        },
+        versions,
+    };
+}
+/** `sha256:<hex>` content identity over the canonical JSON of a spec object. */
+export function specContentHash(spec) {
+    return "sha256:" + createHash("sha256").update(canonicalJson(spec)).digest("hex");
+}
+function canonicalJson(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return "[" + value.map(canonicalJson).join(",") + "]";
+    }
+    const obj = value;
+    return ("{" +
+        Object.keys(obj)
+            .sort()
+            .map((k) => JSON.stringify(k) + ":" + canonicalJson(obj[k]))
+            .join(",") +
+        "}");
+}
+// ---------------------------------------------------------------------------
+// Legacy <-> v2 conversion (loss-free)
+// ---------------------------------------------------------------------------
+/**
+ * Wrap a parsed legacy block object into a v2 `BlockToml`. The full legacy
+ * object is stored verbatim as the single version's `spec`, so the transform
+ * loses nothing. The `[block]` header is a projection derived from the legacy
+ * header table for the unified vocabulary; the spec remains the source of truth
+ * for reconstructing the legacy file.
+ */
+export function legacyObjectToBlock(type, legacy, fallbackKey) {
+    const headerTable = legacy[LEGACY_HEADER_KEY[type]] ||
+        {};
+    const key = typeof headerTable.key === "string" && headerTable.key
+        ? headerTable.key
+        : fallbackKey;
+    const status = typeof headerTable.status === "string" ? headerTable.status : undefined;
+    const displayName = typeof headerTable.displayName === "string"
+        ? headerTable.displayName
+        : typeof headerTable.name === "string"
+            ? headerTable.name
+            : undefined;
+    const description = typeof headerTable.description === "string"
+        ? headerTable.description
+        : undefined;
+    const versionKey = "default";
+    return {
+        schemaVersion: BLOCK_SCHEMA_VERSION,
+        block: {
+            type,
+            key,
+            displayName,
+            description,
+            status,
+            activeVersion: versionKey,
+        },
+        versions: [
+            {
+                key: versionKey,
+                status: status || "draft",
+                contentHash: specContentHash(legacy),
+                spec: legacy,
+            },
+        ],
+    };
+}
+/** Wrap a raw Rhai script body into a v2 script `BlockToml`. */
+export function scriptSourceToBlock(key, source) {
+    const spec = { sourceFile: SCRIPT_SOURCE_FILENAME };
+    return {
+        schemaVersion: BLOCK_SCHEMA_VERSION,
+        block: {
+            type: "script",
+            key,
+            status: "active",
+            activeVersion: "default",
+        },
+        versions: [
+            {
+                key: "default",
+                status: "active",
+                contentHash: specContentHash(source),
+                spec,
+            },
+        ],
+    };
+}
+/**
+ * Reverse `legacyObjectToBlock` / `scriptSourceToBlock`: rebuild the legacy
+ * on-disk content from a v2 block. This is the read half of dual-layout
+ * support — a v2 directory can be projected back to the exact legacy object a
+ * legacy consumer (e.g. the push path) expects. `sourceText` is required for
+ * scripts (the body lives in `source.rhai`, not the `block.toml`).
+ */
+export function reconstructLegacyBlock(block, sourceText) {
+    const version = block.versions.find((v) => v.key === block.block.activeVersion) ||
+        block.versions[0];
+    if (block.block.type === "script") {
+        return { rhai: sourceText ?? "" };
+    }
+    const spec = (version?.spec ?? {});
+    return { toml: stringifyConfigToml(spec) };
+}
+// ---------------------------------------------------------------------------
+// Layout detection + enumeration
+// ---------------------------------------------------------------------------
+function dirHasBlockFiles(dir, ext) {
+    if (!existsSync(dir))
+        return false;
+    try {
+        return readdirSync(dir).some((name) => {
+            if (!name.endsWith(ext))
+                return false;
+            return statSync(join(dir, name)).isFile();
+        });
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Report which layouts a config directory currently holds. A directory can
+ * hold both during/after a migration (legacy preserved, v2 written).
+ */
+export function detectLayout(configDir) {
+    const legacy = BLOCK_TYPES.some((type) => {
+        const dir = legacyBlockDir(configDir, type);
+        const ext = type === "script" ? ".rhai" : ".toml";
+        return dirHasBlockFiles(dir, ext);
+    });
+    const v2 = listV2Blocks(configDir).length > 0;
+    return { legacy, v2 };
+}
+/** Enumerate every v2 block present under `<configDir>/blocks/`. */
+export function listV2Blocks(configDir) {
+    const root = v2BlocksRoot(configDir);
+    if (!existsSync(root))
+        return [];
+    const refs = [];
+    for (const typeDir of readdirSync(root)) {
+        const type = V2_TYPE_DIR_TO_TYPE[typeDir];
+        if (!type)
+            continue;
+        const typePath = join(root, typeDir);
+        if (!statSync(typePath).isDirectory())
+            continue;
+        for (const key of readdirSync(typePath)) {
+            const blockDir = join(typePath, key);
+            const tomlPath = join(blockDir, "block.toml");
+            if (!existsSync(tomlPath) || !statSync(blockDir).isDirectory())
+                continue;
+            const sourcePath = join(blockDir, SCRIPT_SOURCE_FILENAME);
+            refs.push({
+                type,
+                key,
+                tomlPath,
+                sourcePath: existsSync(sourcePath) ? sourcePath : undefined,
+            });
+        }
+    }
+    return refs;
+}
+function listLegacyBlockFiles(configDir) {
+    const files = [];
+    for (const type of BLOCK_TYPES) {
+        const dir = legacyBlockDir(configDir, type);
+        if (!existsSync(dir))
+            continue;
+        const ext = type === "script" ? ".rhai" : ".toml";
+        for (const name of readdirSync(dir)) {
+            if (!name.endsWith(ext))
+                continue;
+            const path = join(dir, name);
+            if (!statSync(path).isFile())
+                continue;
+            files.push({ type, key: basename(name, ext), path });
+        }
+    }
+    return files;
+}
+/**
+ * Convert a legacy sync directory into the v2 `blocks/<type>/<key>/block.toml`
+ * layout. Non-destructive: the legacy files are left in place (the legacy
+ * layout stays the default until v2 is proven). Test-case directories
+ * (`<key>.tests/`) are copied verbatim into `blocks/<type>/<key>/tests/` so a
+ * tested block migrates without losing its cases.
+ */
+export function migrateLegacyToV2(configDir, options = {}) {
+    const dryRun = !!options.dryRun;
+    const blocks = [];
+    const skipped = [];
+    for (const file of listLegacyBlockFiles(configDir)) {
+        const tomlPath = v2BlockTomlPath(configDir, file.type, file.key);
+        if (existsSync(tomlPath) && !options.force) {
+            skipped.push({
+                type: file.type,
+                key: file.key,
+                reason: "v2 block.toml already exists (use --force to overwrite)",
+            });
+            continue;
+        }
+        let block;
+        let sourceText;
+        if (file.type === "script") {
+            sourceText = readFileSync(file.path, "utf-8");
+            block = scriptSourceToBlock(file.key, sourceText);
+        }
+        else {
+            let legacy;
+            try {
+                legacy = parseConfigToml(readFileSync(file.path, "utf-8"));
+            }
+            catch (err) {
+                skipped.push({
+                    type: file.type,
+                    key: file.key,
+                    reason: `could not parse legacy TOML: ${err.message}`,
+                });
+                continue;
+            }
+            block = legacyObjectToBlock(file.type, legacy, file.key);
+        }
+        const blockDir = v2BlockDir(configDir, file.type, file.key);
+        const sourcePath = file.type === "script"
+            ? v2ScriptSourcePath(configDir, file.key)
+            : undefined;
+        // Copy sibling test cases: legacy `<legacyDir>/<key>.tests/` ->
+        // `blocks/<type>/<key>/tests/`.
+        const legacyTestsDir = join(legacyBlockDir(configDir, file.type), `${file.key}.tests`);
+        let testsCopied = 0;
+        const v2TestsDir = join(blockDir, "tests");
+        if (existsSync(legacyTestsDir) && statSync(legacyTestsDir).isDirectory()) {
+            testsCopied = readdirSync(legacyTestsDir).filter((n) => n.endsWith(".toml")).length;
+        }
+        if (!dryRun) {
+            mkdirSync(blockDir, { recursive: true });
+            writeFileSync(tomlPath, serializeBlockToml(block));
+            if (sourcePath && sourceText !== undefined) {
+                writeFileSync(sourcePath, sourceText);
+            }
+            if (testsCopied > 0) {
+                cpSync(legacyTestsDir, v2TestsDir, { recursive: true });
+            }
+        }
+        blocks.push({
+            type: file.type,
+            key: file.key,
+            tomlPath,
+            sourcePath,
+            testsCopied,
+        });
+    }
+    return { blocks, skipped, dryRun };
+}
+//# sourceMappingURL=block-layout.js.map

package/dist/src/lib/block-layout.js.map

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

package/dist/src/lib/canonical-json.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Canonical JSON serialization used for content comparison and hashing.
+ *
+ * Key order is normalized (sorted) so two structurally identical objects
+ * always produce the same string, while array order is preserved (step order
+ * matters in workflows).
+ *
+ * Lives in `lib/` rather than inside `commands/sync.ts` so both the sync
+ * command and the workflow-include reconciliation helper can compare values
+ * the same way without a circular import.
+ */
+export declare function canonicalJsonStringify(value: any): string;

package/dist/src/lib/canonical-json.js

@@ -0,0 +1,35 @@
+/**
+ * Canonical JSON serialization used for content comparison and hashing.
+ *
+ * Key order is normalized (sorted) so two structurally identical objects
+ * always produce the same string, while array order is preserved (step order
+ * matters in workflows).
+ *
+ * Lives in `lib/` rather than inside `commands/sync.ts` so both the sync
+ * command and the workflow-include reconciliation helper can compare values
+ * the same way without a circular import.
+ */
+export function canonicalJsonStringify(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return "[" + value.map((v) => canonicalJsonStringify(v)).join(",") + "]";
+    }
+    // Honor `toJSON` before the key walk. A `Date` — or smol-toml's `TomlDate`,
+    // what a TOML datetime literal parses to — has no enumerable own keys, so
+    // the `Object.keys()` walk below would collapse it to "{}" and every
+    // datetime would hash identically (issue #1919). Both implement `toJSON`,
+    // returning the ISO string; recursing on it makes date-like values (nested
+    // ones too) participate in the hash. Matches JSON.stringify's own semantics.
+    if (typeof value.toJSON === "function") {
+        return canonicalJsonStringify(value.toJSON());
+    }
+    const keys = Object.keys(value).sort();
+    return ("{" +
+        keys
+            .map((k) => JSON.stringify(k) + ":" + canonicalJsonStringify(value[k]))
+            .join(",") +
+        "}");
+}
+//# sourceMappingURL=canonical-json.js.map

package/dist/src/lib/canonical-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-json.js","sourceRoot":"","sources":["../../../src/lib/canonical-json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAU;IAC/C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IAC3E,CAAC;IACD,4EAA4E;IAC5E,0EAA0E;IAC1E,qEAAqE;IACrE,0EAA0E;IAC1E,2EAA2E;IAC3E,6EAA6E;IAC7E,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QACvC,OAAO,sBAAsB,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IAChD,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;IACvC,OAAO,CACL,GAAG;QACH,IAAI;aACD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,sBAAsB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;aACtE,IAAI,CAAC,GAAG,CAAC;QACZ,GAAG,CACJ,CAAC;AACJ,CAAC"}

package/dist/src/lib/channel.d.ts

@@ -0,0 +1,30 @@
+export declare const DEFAULT_CHANNEL_BRANCH = "main";
+/**
+ * Normalize a server URL for comparison: keep the scheme/host/port, strip all
+ * trailing slashes from the pathname. Returns null for an unparseable value.
+ * `http` vs `https` intentionally does NOT normalize to the same string
+ * (scheme is significant).
+ */
+export declare function normalizeServerUrl(raw: string): string | null;
+/**
+ * Is `value` a plausible git branch ref that is safe to interpolate into a
+ * GitHub URL path? Deliberately strict — only ASCII letters/digits and
+ * `._/-`, no leading dash, no `..`, capped length. This guards the branch
+ * override env vars so no arbitrary string reaches a URL.
+ */
+export declare function isValidBranchName(value: string): boolean;
+/**
+ * Resolve which channel branch to fetch from. Precedence:
+ *   1. `override` (an undocumented, internal env var — `overrideName` is
+ *      only used in the error message). An empty value is ignored; a value
+ *      that is not a plausible git ref is rejected (throws).
+ *   2. Alpha detection: a normalized-URL match of the resolved server URL
+ *      against `ALPHA_SERVER_URL` → `alpha`.
+ *   3. Otherwise `main` (production / local / any non-alpha target, or no
+ *      target at all when the CLI is logged out).
+ *
+ * Pure and side-effect free: the caller passes the resolved server URL (or
+ * `undefined` when `getServerUrl()` threw) and the override, so this is
+ * fully unit-testable without config/credentials.
+ */
+export declare function resolveChannelBranch(serverUrl: string | undefined, override: string | undefined, overrideName: string): string;

package/dist/src/lib/channel.js

@@ -0,0 +1,68 @@
+import { ALPHA_SERVER_URL } from "./constants.js";
+// Channel resolution shared by every surface that fetches from a
+// branch-as-channel repo (issue #1934): `primitive guides` (the
+// primitive-docs-site repo) and `primitive init` (the template mirrors).
+// Branches are named after the deploy environment they describe: `main` =
+// production, `alpha` = the alpha environment.
+export const DEFAULT_CHANNEL_BRANCH = "main";
+/**
+ * Normalize a server URL for comparison: keep the scheme/host/port, strip all
+ * trailing slashes from the pathname. Returns null for an unparseable value.
+ * `http` vs `https` intentionally does NOT normalize to the same string
+ * (scheme is significant).
+ */
+export function normalizeServerUrl(raw) {
+    try {
+        const u = new URL(raw);
+        const path = u.pathname.replace(/\/+$/, "");
+        return `${u.protocol}//${u.host}${path}`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Is `value` a plausible git branch ref that is safe to interpolate into a
+ * GitHub URL path? Deliberately strict — only ASCII letters/digits and
+ * `._/-`, no leading dash, no `..`, capped length. This guards the branch
+ * override env vars so no arbitrary string reaches a URL.
+ */
+export function isValidBranchName(value) {
+    if (value.length === 0 || value.length > 100)
+        return false;
+    if (value.includes(".."))
+        return false;
+    return /^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(value);
+}
+/**
+ * Resolve which channel branch to fetch from. Precedence:
+ *   1. `override` (an undocumented, internal env var — `overrideName` is
+ *      only used in the error message). An empty value is ignored; a value
+ *      that is not a plausible git ref is rejected (throws).
+ *   2. Alpha detection: a normalized-URL match of the resolved server URL
+ *      against `ALPHA_SERVER_URL` → `alpha`.
+ *   3. Otherwise `main` (production / local / any non-alpha target, or no
+ *      target at all when the CLI is logged out).
+ *
+ * Pure and side-effect free: the caller passes the resolved server URL (or
+ * `undefined` when `getServerUrl()` threw) and the override, so this is
+ * fully unit-testable without config/credentials.
+ */
+export function resolveChannelBranch(serverUrl, override, overrideName) {
+    const trimmedOverride = override?.trim();
+    if (trimmedOverride) {
+        if (!isValidBranchName(trimmedOverride)) {
+            throw new Error(`Invalid ${overrideName} "${override}": must be a plausible git branch name.`);
+        }
+        return trimmedOverride;
+    }
+    if (serverUrl) {
+        const target = normalizeServerUrl(serverUrl);
+        const alpha = normalizeServerUrl(ALPHA_SERVER_URL);
+        if (target !== null && alpha !== null && target === alpha) {
+            return "alpha";
+        }
+    }
+    return DEFAULT_CHANNEL_BRANCH;
+}
+//# sourceMappingURL=channel.js.map

package/dist/src/lib/channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.js","sourceRoot":"","sources":["../../../src/lib/channel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD,iEAAiE;AACjE,gEAAgE;AAChE,yEAAyE;AACzE,0EAA0E;AAC1E,+CAA+C;AAE/C,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QACvB,MAAM,IAAI,GAAG,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAC5C,OAAO,GAAG,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,IAAI,GAAG,IAAI,EAAE,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,GAAG;QAAE,OAAO,KAAK,CAAC;IAC3D,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACvC,OAAO,+BAA+B,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,oBAAoB,CAClC,SAA6B,EAC7B,QAA4B,EAC5B,YAAoB;IAEpB,MAAM,eAAe,GAAG,QAAQ,EAAE,IAAI,EAAE,CAAC;IACzC,IAAI,eAAe,EAAE,CAAC;QACpB,IAAI,CAAC,iBAAiB,CAAC,eAAe,CAAC,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CACb,WAAW,YAAY,KAAK,QAAQ,yCAAyC,CAC9E,CAAC;QACJ,CAAC;QACD,OAAO,eAAe,CAAC;IACzB,CAAC;IAED,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,MAAM,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;QAC7C,MAAM,KAAK,GAAG,kBAAkB,CAAC,gBAAgB,CAAC,CAAC;QACnD,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;YAC1D,OAAO,OAAO,CAAC;QACjB,CAAC;IACH,CAAC;IAED,OAAO,sBAAsB,CAAC;AAChC,CAAC"}