primitive-admin 1.1.0-alpha.4 → 1.1.0-alpha.40

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 * as TOML from "@iarna/toml";
+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 TOML.stringify(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 = TOML.parse(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: TOML.stringify(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 = TOML.parse(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/cli-manifest.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Machine-readable CLI command manifest (issue #983).
+ *
+ * Serializes the full commander command tree (commands, subcommands, args,
+ * options, aliases, global options, version) into a stable JSON shape so that
+ * external tooling — e.g. `primitive-docs` CI — can drift-gate documented CLI
+ * invocations against the *published* CLI rather than scraping `--help` text.
+ *
+ * The walker uses only commander v12 public accessors, so it is decoupled from
+ * commander internals:
+ *   - `cmd.name()`, `cmd.description()`, `cmd.aliases()`
+ *   - `cmd.commands` (recurse into subcommands)
+ *   - `cmd.registeredArguments` (positional args)
+ *   - `cmd.options` (per-command options)
+ *
+ * `globalOptions` is the top-level program's own options (e.g. `-e, --env`),
+ * reported once at the root rather than repeated on every command.
+ *
+ * `schemaVersion` is the contract knob: consumers assert they understand the
+ * shape and fail loud if a future CLI bumps it. Bumping it is a breaking change
+ * for downstream tooling.
+ */
+import type { Command } from "commander";
+/** Current manifest schema version. Bump on any breaking shape change. */
+export declare const CLI_MANIFEST_SCHEMA_VERSION = 1;
+export interface ManifestArg {
+    name: string;
+    required: boolean;
+    variadic: boolean;
+    description: string;
+}
+export interface ManifestOption {
+    flags: string;
+    description: string;
+    required: boolean;
+    defaultValue: unknown;
+}
+export interface ManifestCommand {
+    name: string;
+    description: string;
+    aliases: string[];
+    args: ManifestArg[];
+    options: ManifestOption[];
+    commands: ManifestCommand[];
+}
+export interface CliManifest {
+    schemaVersion: number;
+    name: string;
+    version: string;
+    globalOptions: ManifestOption[];
+    commands: ManifestCommand[];
+}
+/**
+ * Build the JSON manifest for a fully-built commander program.
+ *
+ * @param program The root commander `Command` after all subcommands are
+ *   registered.
+ * @param version The CLI version (typically `pkg.version`).
+ */
+export declare function buildCliManifest(program: Command, version: string): CliManifest;

package/dist/src/lib/cli-manifest.js

@@ -0,0 +1,70 @@
+/**
+ * Machine-readable CLI command manifest (issue #983).
+ *
+ * Serializes the full commander command tree (commands, subcommands, args,
+ * options, aliases, global options, version) into a stable JSON shape so that
+ * external tooling — e.g. `primitive-docs` CI — can drift-gate documented CLI
+ * invocations against the *published* CLI rather than scraping `--help` text.
+ *
+ * The walker uses only commander v12 public accessors, so it is decoupled from
+ * commander internals:
+ *   - `cmd.name()`, `cmd.description()`, `cmd.aliases()`
+ *   - `cmd.commands` (recurse into subcommands)
+ *   - `cmd.registeredArguments` (positional args)
+ *   - `cmd.options` (per-command options)
+ *
+ * `globalOptions` is the top-level program's own options (e.g. `-e, --env`),
+ * reported once at the root rather than repeated on every command.
+ *
+ * `schemaVersion` is the contract knob: consumers assert they understand the
+ * shape and fail loud if a future CLI bumps it. Bumping it is a breaking change
+ * for downstream tooling.
+ */
+/** Current manifest schema version. Bump on any breaking shape change. */
+export const CLI_MANIFEST_SCHEMA_VERSION = 1;
+function serializeArg(arg) {
+    return {
+        name: arg.name(),
+        required: !!arg.required,
+        variadic: !!arg.variadic,
+        description: arg.description || "",
+    };
+}
+function serializeOption(opt) {
+    return {
+        flags: opt.flags,
+        description: opt.description || "",
+        required: !!opt.required,
+        defaultValue: opt.defaultValue ?? null,
+    };
+}
+function serializeCommand(cmd) {
+    return {
+        name: cmd.name(),
+        description: cmd.description() || "",
+        aliases: cmd.aliases() || [],
+        args: (cmd.registeredArguments || []).map(serializeArg),
+        options: (cmd.options || []).map(serializeOption),
+        commands: (cmd.commands || []).map(serializeCommand),
+    };
+}
+/**
+ * Build the JSON manifest for a fully-built commander program.
+ *
+ * @param program The root commander `Command` after all subcommands are
+ *   registered.
+ * @param version The CLI version (typically `pkg.version`).
+ */
+export function buildCliManifest(program, version) {
+    const root = program;
+    return {
+        schemaVersion: CLI_MANIFEST_SCHEMA_VERSION,
+        name: root.name(),
+        version,
+        // Top-level program options are the "global" options (e.g. -e, --env);
+        // per-command options live under each command in `commands[]`.
+        globalOptions: (root.options || []).map(serializeOption),
+        commands: (root.commands || []).map(serializeCommand),
+    };
+}
+//# sourceMappingURL=cli-manifest.js.map

package/dist/src/lib/cli-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-manifest.js","sourceRoot":"","sources":["../../../src/lib/cli-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,0EAA0E;AAC1E,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC;AAiC7C,SAAS,YAAY,CAAC,GAAQ;IAC5B,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE;QAChB,QAAQ,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ;QACxB,QAAQ,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ;QACxB,WAAW,EAAE,GAAG,CAAC,WAAW,IAAI,EAAE;KACnC,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,GAAQ;IAC/B,OAAO;QACL,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,WAAW,EAAE,GAAG,CAAC,WAAW,IAAI,EAAE;QAClC,QAAQ,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ;QACxB,YAAY,EAAE,GAAG,CAAC,YAAY,IAAI,IAAI;KACvC,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CAAC,GAAQ;IAChC,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE;QAChB,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE,IAAI,EAAE;QACpC,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,IAAI,EAAE;QAC5B,IAAI,EAAE,CAAC,GAAG,CAAC,mBAAmB,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC;QACvD,OAAO,EAAE,CAAC,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC;QACjD,QAAQ,EAAE,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,gBAAgB,CAAC;KACrD,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgB,EAAE,OAAe;IAChE,MAAM,IAAI,GAAG,OAAc,CAAC;IAC5B,OAAO;QACL,aAAa,EAAE,2BAA2B;QAC1C,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE;QACjB,OAAO;QACP,uEAAuE;QACvE,+DAA+D;QAC/D,aAAa,EAAE,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC;QACxD,QAAQ,EAAE,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,gBAAgB,CAAC;KACtD,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,53 @@
+/**
+ * Thin compatibility shim over the new project-scoped config system.
+ *
+ * Historically the CLI had one global credentials file at
+ * ~/.primitive/credentials.json and a handful of helpers here. After the
+ * project-config overhaul (issue #373) credentials live per-environment
+ * inside `<projectRoot>/.primitive/credentials.json` when a
+ * .primitive/config.json is in scope, and fall back to the legacy global
+ * file otherwise.
+ *
+ * The rest of the CLI continues to import from this module, so we keep
+ * the original public API (loadCredentials, saveCredentials, etc.) and
+ * just delegate to the new stores.
+ */
+import type { Credentials } from "../types/index.js";
+export declare function loadCredentials(): Credentials | null;
+export declare function saveCredentials(credentials: Credentials): void;
+export declare function clearCredentials(): void;
+export declare function isTokenExpired(credentials: Credentials): boolean;
+export declare function isTokenExpiringSoon(credentials: Credentials): boolean;
+export declare function setCurrentApp(appId: string, appName?: string): void;
+export declare function clearCurrentApp(): void;
+export declare function getCurrentAppId(): string | undefined;
+export declare function resolveAppId(appId: string | undefined, options: {
+    app?: string;
+}): string;
+/**
+ * Returns the API base URL for the active environment (project mode) or
+ * the serverUrl saved in the legacy credentials file.
+ */
+export declare function getServerUrl(): string;
+/**
+ * Resolves the API base URL to authenticate against, used by `primitive login`
+ * (issue #1343).
+ *
+ * Unlike getServerUrl(), this must work *before* any credentials exist (first
+ * login), so it never falls back to the stored credentials' serverUrl:
+ *
+ *   - Project mode → the active environment's `apiUrl` (canonical). Lets
+ *     getCurrentEnvironment() throw on an unresolvable env (ambiguous/unknown
+ *     --env) so the caller can fail loudly instead of silently targeting prod.
+ *   - Legacy mode (no .primitive/config.json) → DEFAULT_SERVER_URL, which
+ *     honors the PRIMITIVE_SERVER_URL escape hatch (constants.ts).
+ *
+ * The trailing slash is stripped so callers can build `${url}/admin/api/...`.
+ */
+export declare function getConfiguredServerUrl(): string;
+/**
+ * Exposed so commands can check whether there's a pre-project-config
+ * credentials file at ~/.primitive/credentials.json (used by migration
+ * prompts).
+ */
+export declare function legacyCredentialsExist(): boolean;