primitive-admin 1.1.0-alpha.9 → 1.2.0-alpha.0

package/dist/src/lib/package-manager.js

@@ -0,0 +1,305 @@
+import { existsSync, readdirSync, realpathSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+/** The npm package name of this CLI. */
+export const PRIMITIVE_CLI_PACKAGE = "primitive-admin";
+/** Normalize separators and drop a trailing slash so path matching is uniform. */
+export function normalize(p) {
+    return p.replace(/\\/g, "/").replace(/\/+$/, "");
+}
+/** The entries of PATH, split on the separator this environment uses. */
+function pathEntries(env) {
+    const pathVar = env.PATH || env.Path || "";
+    if (!pathVar)
+        return [];
+    const separator = pathVar.includes(";") && !pathVar.includes(":/") ? ";" : ":";
+    return pathVar.split(separator).filter(Boolean);
+}
+/**
+ * Classifies an already-resolved absolute path to a file inside the installed
+ * package. Pure over (path, env) — no filesystem access, no child processes.
+ */
+export function classifyInstallPath(realPath, env) {
+    const p = normalize(realPath);
+    if (!p)
+        return { kind: "unknown" };
+    const lower = p.toLowerCase();
+    // Global roots we deliberately do not support (yarn, bun): classify as
+    // unknown so the caller renders the safe fallback command instead of an
+    // invalid yarn/bun one.
+    const bunInstall = env.BUN_INSTALL ? normalize(env.BUN_INSTALL) : null;
+    if (lower.includes("/yarn/global/") ||
+        lower.includes("/.config/yarn/") ||
+        lower.includes("/.yarn/") ||
+        lower.includes("/.bun/") ||
+        (bunInstall && lower.startsWith(`${bunInstall.toLowerCase()}/`))) {
+        return { kind: "unknown" };
+    }
+    // pnpm global: $PNPM_HOME, or one of the well-known pnpm global roots.
+    // (A bare `/.pnpm/` virtual-store segment is not a global signal on its own
+    // — a project's own node_modules/.pnpm store has one too — so it falls
+    // through to the "local" branch below.)
+    const pnpmHome = env.PNPM_HOME ? normalize(env.PNPM_HOME) : null;
+    if ((pnpmHome && lower.startsWith(`${pnpmHome.toLowerCase()}/`)) ||
+        lower.includes("/pnpm/global/")) {
+        return { kind: "global", manager: "pnpm" };
+    }
+    // npm global: `<prefix>/lib/node_modules` on POSIX, `<AppData>/npm/node_modules`
+    // on Windows. Covers homebrew, /usr/local, nvm, and volta-style prefixes.
+    if (lower.includes("/lib/node_modules/") || lower.includes("/npm/node_modules/")) {
+        return { kind: "global", manager: "npm" };
+    }
+    // Anything else under a node_modules directory is a project dependency.
+    if (lower.includes("/node_modules/")) {
+        return { kind: "local" };
+    }
+    // No node_modules segment at all — running from a git checkout.
+    return { kind: "source" };
+}
+/**
+ * Picks the manager for a project-local install from the nearest lockfile,
+ * walking up from the installed file. Touches the filesystem, so it lives
+ * outside the pure classifier.
+ */
+function managerFromNearestLockfile(startPath) {
+    let dir = dirname(startPath);
+    for (let i = 0; i < 64; i++) {
+        if (existsSync(join(dir, "pnpm-lock.yaml")))
+            return "pnpm";
+        if (existsSync(join(dir, "package-lock.json")))
+            return "npm";
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return "npm";
+}
+/** Classifies the copy of the CLI that is executing right now. */
+export function detectInstall(opts = {}) {
+    const env = opts.env ?? process.env;
+    try {
+        const selfPath = realpathSync(opts.selfPath ?? fileURLToPath(import.meta.url));
+        const classification = classifyInstallPath(selfPath, env);
+        if (classification.kind === "local") {
+            return { kind: "local", manager: managerFromNearestLockfile(selfPath) };
+        }
+        return classification;
+    }
+    catch {
+        return { kind: "unknown" };
+    }
+}
+/**
+ * True when a `pnpm` executable is found on PATH (no child process spawned).
+ *
+ * `template.ts` has a separate `isPnpmInstalled` that shells out to
+ * `pnpm --version`. Both exist on purpose: this module must not spawn child
+ * processes (it runs on every command, inside the version check), while
+ * `template.ts` needs to know pnpm actually *runs*, not just that a file with
+ * that name is on PATH. The two can therefore disagree — a broken pnpm binary
+ * satisfies this one and not that one.
+ */
+export function isPnpmOnPath(env = process.env) {
+    const entries = pathEntries(env);
+    if (entries.length === 0)
+        return false;
+    const candidates = process.platform === "win32" ? ["pnpm.cmd", "pnpm.exe", "pnpm"] : ["pnpm"];
+    for (const entry of entries) {
+        for (const candidate of candidates) {
+            try {
+                if (existsSync(join(entry, candidate)))
+                    return true;
+            }
+            catch {
+                // Unreadable PATH entry — keep looking.
+            }
+        }
+    }
+    return false;
+}
+/**
+ * True when pnpm has somewhere to put a global install.
+ *
+ * `pnpm add -g` fails with `ERR_PNPM_NO_GLOBAL_BIN_DIR` when pnpm has no
+ * global bin directory — the state a machine is in when pnpm was installed
+ * with `npm install -g pnpm` and `pnpm setup` was never run, which is exactly
+ * what `primitive init` does when it bootstraps pnpm. A `pnpm` binary on PATH
+ * is therefore not enough to conclude that pnpm can install globally.
+ *
+ * Two signals count:
+ * - `PNPM_HOME` is set *and* on PATH. `pnpm setup` sets both together; when
+ *   the directory is set but not on PATH the install succeeds and leaves a
+ *   binary the user can't run.
+ * - A pnpm global root already exists on disk — pnpm has installed globals
+ *   here before, so it has a working global bin directory.
+ */
+export function canPnpmInstallGlobally(env, execPath) {
+    const home = env.PNPM_HOME ? normalize(env.PNPM_HOME).toLowerCase() : null;
+    if (home && pathEntries(env).some((entry) => normalize(entry).toLowerCase() === home)) {
+        return true;
+    }
+    return globalRootCandidates(env, execPath).pnpm.some((root) => existingDir(join(root, "global")));
+}
+/**
+ * The manager to use when nothing else identifies one: pnpm when it is on
+ * PATH *and* able to install globally, else npm. Never suggest or run a
+ * command the user's machine can't carry out.
+ */
+function pathFallbackManager(opts) {
+    const env = opts.env ?? process.env;
+    const execPath = opts.execPath ?? process.execPath;
+    return isPnpmOnPath(env) && canPnpmInstallGlobally(env, execPath) ? "pnpm" : "npm";
+}
+/**
+ * The manager to install `pkg` globally with: whichever one already owns a
+ * global copy (so we upgrade that copy instead of creating a second one),
+ * else the PATH fallback.
+ */
+function installManager(pkg, opts) {
+    const existing = findDuplicateGlobalInstalls(pkg, opts);
+    if (existing.some((e) => e.manager === "pnpm"))
+        return "pnpm";
+    if (existing.some((e) => e.manager === "npm"))
+        return "npm";
+    return pathFallbackManager(opts);
+}
+function globalUpgrade(manager, spec) {
+    return manager === "pnpm" ? `pnpm add -g ${spec}` : `npm i -g ${spec}`;
+}
+/**
+ * The command that upgrades this install to `distTag` ("latest", "alpha", …),
+ * or null when there is nothing sensible to suggest (a source checkout).
+ */
+export function upgradeCommand(install, pkg, distTag, opts = {}) {
+    const spec = `${pkg}@${distTag}`;
+    switch (install.kind) {
+        case "global":
+            return globalUpgrade(install.manager, spec);
+        case "local":
+            return install.manager === "pnpm" ? `pnpm up ${spec}` : `npm i ${spec}`;
+        case "source":
+            // A git checkout can't be upgraded by a package manager, and suggesting
+            // one there is how a user ends up with an extra copy.
+            return null;
+        case "unknown":
+            return globalUpgrade(pathFallbackManager(opts), spec);
+    }
+}
+/** The argv for a first-time global install of `pkg`. */
+export function installArgv(pkg, opts = {}) {
+    const manager = installManager(pkg, opts);
+    return manager === "pnpm"
+        ? { command: "pnpm", args: ["add", "-g", pkg] }
+        : { command: "npm", args: ["install", "-g", pkg] };
+}
+/** The command a user should run for a first-time global install of `pkg`. */
+export function installCommand(pkg, opts = {}) {
+    const { command, args } = installArgv(pkg, opts);
+    return [command, ...args].join(" ");
+}
+/**
+ * The install's location with symlinks resolved, or the path itself when it
+ * can't be resolved. pnpm's global `node_modules/<pkg>` is a link into
+ * `<root>/global/<version>/.pnpm/<pkg>@<version>/node_modules/<pkg>`, and only
+ * the resolved form matches the resolved path of the running CLI file.
+ */
+function resolveLink(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+function existingDir(path) {
+    try {
+        return existsSync(path);
+    }
+    catch {
+        return false;
+    }
+}
+/** pnpm keeps its global installs under `<root>/global/<version>/node_modules`. */
+function pnpmGlobalPackagePaths(root, pkg) {
+    const globalRoot = join(root, "global");
+    let versions = [];
+    try {
+        versions = readdirSync(globalRoot);
+    }
+    catch {
+        return [];
+    }
+    return versions
+        .map((v) => join(globalRoot, v, "node_modules", pkg))
+        .filter(existingDir);
+}
+/**
+ * The directories each manager could hold a global install in, derived from
+ * the environment and the running node executable. Pure — it only builds
+ * candidate paths; `findDuplicateGlobalInstalls` decides which ones exist.
+ *
+ * - pnpm keeps globals under `<pnpm root>/global/<version>/node_modules`.
+ * - npm keeps them under `<prefix>/lib/node_modules` (or
+ *   `<AppData>/npm/node_modules` on Windows). The prefix is derived from the
+ *   node executable and from every `.../bin` entry on PATH, which is what
+ *   catches layouts like homebrew's, where the executable lives in a
+ *   versioned Cellar directory but globals land in `/opt/homebrew`.
+ */
+export function globalRootCandidates(env, execPath) {
+    const pnpm = [
+        env.PNPM_HOME,
+        env.HOME ? join(env.HOME, "Library", "pnpm") : undefined,
+        env.HOME ? join(env.HOME, ".local", "share", "pnpm") : undefined,
+        env.LOCALAPPDATA ? join(env.LOCALAPPDATA, "pnpm") : undefined,
+    ].filter((r) => !!r);
+    const prefixes = [dirname(dirname(execPath))];
+    if (env.npm_config_prefix)
+        prefixes.push(env.npm_config_prefix);
+    for (const entry of (env.PATH || env.Path || "").split(/[:;]/)) {
+        if (entry && /[\\/]bin$/.test(entry))
+            prefixes.push(dirname(entry));
+    }
+    const npm = prefixes.map((prefix) => join(prefix, "lib", "node_modules"));
+    if (env.APPDATA)
+        npm.push(join(env.APPDATA, "npm", "node_modules"));
+    return { pnpm: unique(pnpm), npm: unique(npm) };
+}
+function unique(paths) {
+    const seen = new Set();
+    return paths.filter((p) => {
+        const key = normalize(p);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+/**
+ * Finds global copies of `pkg` in the global roots of each supported manager.
+ * Path checks only — no child processes.
+ */
+export function findDuplicateGlobalInstalls(pkg, opts = {}) {
+    const roots = opts.roots ?? globalRootCandidates(opts.env ?? process.env, opts.execPath ?? process.execPath);
+    const found = [];
+    const seen = new Set();
+    const add = (manager, path) => {
+        const key = normalize(path);
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        found.push({ manager, path, realPath: resolveLink(path) });
+    };
+    for (const root of roots.pnpm) {
+        for (const path of pnpmGlobalPackagePaths(root, pkg)) {
+            add("pnpm", path);
+        }
+    }
+    for (const root of roots.npm) {
+        const path = join(root, pkg);
+        if (existingDir(path))
+            add("npm", path);
+    }
+    return found;
+}
+//# sourceMappingURL=package-manager.js.map

package/dist/src/lib/package-manager.js.map

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

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

@@ -0,0 +1,82 @@
+/**
+ * Cursor-pagination helper used by the CLI's API client.
+ *
+ * The server exposes cursor-paginated endpoints (e.g. GET /admin/api/admins/me/apps)
+ * that return `{ items, nextCursor? }` pages. Callers historically only fetched
+ * the first page, silently truncating results (see issue #436). This helper
+ * walks every page and aggregates the items in order.
+ *
+ * Exported separately so the looping contract can be unit-tested without
+ * stubbing the full ApiClient.
+ */
+export interface PaginatedPage<T> {
+    items: T[];
+    nextCursor?: string | null;
+}
+/**
+ * The one list envelope the CLI prints (issue #2357).
+ *
+ * `nextCursor` is present only when there is a next page.
+ */
+export interface ListEnvelope<T = any> {
+    items: T[];
+    hasMore: boolean;
+    nextCursor?: string;
+}
+/**
+ * Normalize an endpoint's list response into the CLI's own output contract.
+ *
+ * The records read paths speak two different wire shapes: js-bao's Durable
+ * Object envelope (`{ data, hasMore, nextCursor?, prevCursor? }`) and the
+ * server's unified list payload (`{ items, hasMore, nextCursor? }`). Both are
+ * collapsed here to `{ items, hasMore, nextCursor? }` so like verbs print like
+ * envelopes.
+ *
+ * Accepts `items` or `data` as the array key and reads the continuation from
+ * `nextCursor` only. Throws when neither array key is present so an error body
+ * is never coerced into an empty result.
+ *
+ * Named `normalizeCliListEnvelope` to keep it distinct from the JS client's
+ * `normalizeListEnvelope` (`src/client/internal/listEnvelope.ts`). The two are
+ * unrelated — the client helper is not re-exported from `src/client/index.ts`
+ * and the CLI does not depend on the client package.
+ *
+ * `databases operations execute` routes through here too, but conditionally: a
+ * registered operation is only sometimes a list, so
+ * `normalizeDatabaseOperationResult()` (`api-client.ts`) tests the result shape
+ * first and calls this helper only for a Durable Object query page (#2440).
+ */
+export declare function normalizeCliListEnvelope<T = any>(raw: unknown): ListEnvelope<T>;
+/**
+ * The envelope for a list whose route does not paginate (#3646).
+ *
+ * Every `<noun> list --json` prints the same three keys, so the two kinds of
+ * list differ only in what they say, not in what a script has to read: a paged
+ * route's page goes through `normalizeCliListEnvelope()` and reports the
+ * server's `hasMore`/`nextCursor`; an unpaged route's whole set comes through
+ * here and says `hasMore: false`. A cursor a caller has no flag to spend is
+ * never surfaced.
+ *
+ * Accepts the array itself, or `null`/`undefined` from a route that answers an
+ * empty body — an empty list prints `{ items: [], hasMore: false }`, never
+ * `null` and never a bare `[]`.
+ */
+export declare function wholeListEnvelope<T = any>(items: readonly T[] | null | undefined): ListEnvelope<T>;
+export type PageFetcher<T> = (cursor: string | undefined) => Promise<PaginatedPage<T>>;
+export interface PaginateOptions {
+    /**
+     * Safety net: if the server hands out a non-advancing cursor (same cursor
+     * returned repeatedly, or an implausibly long chain), stop after this many
+     * pages and throw. Default: 1000.
+     */
+    maxPages?: number;
+}
+/**
+ * Walk every cursor page from `fetchPage` and return the concatenated items.
+ *
+ * Detects two failure modes that would otherwise hang the CLI:
+ *   - A cursor that repeats (server returned the same `nextCursor` twice).
+ *   - A cursor chain longer than `maxPages` (default 1000).
+ * Both throw so the caller fails loudly rather than looping forever.
+ */
+export declare function paginateAll<T>(fetchPage: PageFetcher<T>, options?: PaginateOptions): Promise<T[]>;

package/dist/src/lib/paginate.js

@@ -0,0 +1,99 @@
+/**
+ * Cursor-pagination helper used by the CLI's API client.
+ *
+ * The server exposes cursor-paginated endpoints (e.g. GET /admin/api/admins/me/apps)
+ * that return `{ items, nextCursor? }` pages. Callers historically only fetched
+ * the first page, silently truncating results (see issue #436). This helper
+ * walks every page and aggregates the items in order.
+ *
+ * Exported separately so the looping contract can be unit-tested without
+ * stubbing the full ApiClient.
+ */
+/**
+ * Normalize an endpoint's list response into the CLI's own output contract.
+ *
+ * The records read paths speak two different wire shapes: js-bao's Durable
+ * Object envelope (`{ data, hasMore, nextCursor?, prevCursor? }`) and the
+ * server's unified list payload (`{ items, hasMore, nextCursor? }`). Both are
+ * collapsed here to `{ items, hasMore, nextCursor? }` so like verbs print like
+ * envelopes.
+ *
+ * Accepts `items` or `data` as the array key and reads the continuation from
+ * `nextCursor` only. Throws when neither array key is present so an error body
+ * is never coerced into an empty result.
+ *
+ * Named `normalizeCliListEnvelope` to keep it distinct from the JS client's
+ * `normalizeListEnvelope` (`src/client/internal/listEnvelope.ts`). The two are
+ * unrelated — the client helper is not re-exported from `src/client/index.ts`
+ * and the CLI does not depend on the client package.
+ *
+ * `databases operations execute` routes through here too, but conditionally: a
+ * registered operation is only sometimes a list, so
+ * `normalizeDatabaseOperationResult()` (`api-client.ts`) tests the result shape
+ * first and calls this helper only for a Durable Object query page (#2440).
+ */
+export function normalizeCliListEnvelope(raw) {
+    const page = raw;
+    const rawItems = page && typeof page === "object" && !Array.isArray(page)
+        ? (page.items ?? page.data)
+        : undefined;
+    if (!Array.isArray(rawItems)) {
+        throw new Error("Unexpected list response: expected an object with an `items` or `data` array.");
+    }
+    const nextCursor = page.nextCursor ?? undefined;
+    const envelope = {
+        items: rawItems,
+        hasMore: typeof page.hasMore === "boolean" ? page.hasMore : Boolean(nextCursor),
+    };
+    if (nextCursor)
+        envelope.nextCursor = nextCursor;
+    return envelope;
+}
+/**
+ * The envelope for a list whose route does not paginate (#3646).
+ *
+ * Every `<noun> list --json` prints the same three keys, so the two kinds of
+ * list differ only in what they say, not in what a script has to read: a paged
+ * route's page goes through `normalizeCliListEnvelope()` and reports the
+ * server's `hasMore`/`nextCursor`; an unpaged route's whole set comes through
+ * here and says `hasMore: false`. A cursor a caller has no flag to spend is
+ * never surfaced.
+ *
+ * Accepts the array itself, or `null`/`undefined` from a route that answers an
+ * empty body — an empty list prints `{ items: [], hasMore: false }`, never
+ * `null` and never a bare `[]`.
+ */
+export function wholeListEnvelope(items) {
+    return { items: Array.isArray(items) ? [...items] : [], hasMore: false };
+}
+/**
+ * Walk every cursor page from `fetchPage` and return the concatenated items.
+ *
+ * Detects two failure modes that would otherwise hang the CLI:
+ *   - A cursor that repeats (server returned the same `nextCursor` twice).
+ *   - A cursor chain longer than `maxPages` (default 1000).
+ * Both throw so the caller fails loudly rather than looping forever.
+ */
+export async function paginateAll(fetchPage, options = {}) {
+    const maxPages = options.maxPages ?? 1000;
+    const all = [];
+    const seenCursors = new Set();
+    let cursor;
+    for (let page = 0; page < maxPages; page++) {
+        const resp = await fetchPage(cursor);
+        if (Array.isArray(resp.items)) {
+            all.push(...resp.items);
+        }
+        const next = resp.nextCursor ?? undefined;
+        if (!next) {
+            return all;
+        }
+        if (seenCursors.has(next)) {
+            throw new Error(`Pagination cursor did not advance (cursor ${next} repeated); aborting to avoid an infinite loop.`);
+        }
+        seenCursors.add(next);
+        cursor = next;
+    }
+    throw new Error(`Pagination exceeded ${maxPages} pages without terminating; server cursor may not be advancing.`);
+}
+//# sourceMappingURL=paginate.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"paginate.js","sourceRoot":"","sources":["../../../src/lib/paginate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAkBH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,wBAAwB,CAAU,GAAY;IAC5D,MAAM,IAAI,GAAG,GAA6C,CAAC;IAC3D,MAAM,QAAQ,GACZ,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QACtD,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC;QAC3B,CAAC,CAAC,SAAS,CAAC;IAEhB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,+EAA+E,CAChF,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,IAAK,CAAC,UAAU,IAAI,SAAS,CAAC;IACjD,MAAM,QAAQ,GAAoB;QAChC,KAAK,EAAE,QAAe;QACtB,OAAO,EACL,OAAO,IAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,IAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;KAC3E,CAAC;IACF,IAAI,UAAU;QAAE,QAAQ,CAAC,UAAU,GAAG,UAAU,CAAC;IACjD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAsC;IAEtC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAC3E,CAAC;AAaD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,SAAyB,EACzB,UAA2B,EAAE;IAE7B,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,IAAI,CAAC;IAC1C,MAAM,GAAG,GAAQ,EAAE,CAAC;IACpB,MAAM,WAAW,GAAG,IAAI,GAAG,EAAU,CAAC;IACtC,IAAI,MAA0B,CAAC;IAE/B,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,QAAQ,EAAE,IAAI,EAAE,EAAE,CAAC;QAC3C,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,MAAM,CAAC,CAAC;QACrC,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9B,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,IAAI,SAAS,CAAC;QAC1C,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,GAAG,CAAC;QACb,CAAC;QACD,IAAI,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CACb,6CAA6C,IAAI,iDAAiD,CACnG,CAAC;QACJ,CAAC;QACD,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACtB,MAAM,GAAG,IAAI,CAAC;IAChB,CAAC;IAED,MAAM,IAAI,KAAK,CACb,uBAAuB,QAAQ,iEAAiE,CACjG,CAAC;AACJ,CAAC"}

package/dist/src/lib/platform-owned.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared predicate for platform-owned workflows (#1660).
+ *
+ * The platform owns workflow keys in the reserved `__internal.` namespace (see
+ * the server's `src/workflows/reserved-workflow-keys.ts`). These rows are
+ * created and managed by the platform, never authored in an app's config tree:
+ *
+ *   - `config pull` must not export them (they have no local TOML),
+ *   - `config diff` must not report them (they are not app config),
+ *   - `config push` must not upload them (the hollow export can't round-trip),
+ *   - `workflows codegen` must not generate an invoker for them.
+ *
+ * The CLI cannot import from `src/`, so this module mirrors the server's prefix
+ * policy in ONE place. The codegen skip and the sync filters both call it, so
+ * they can never drift from each other or from the server.
+ *
+ * The generic cross-resource `isPlatformOwnedEntity` abstraction is deliberately
+ * NOT here — it is deferred until a second resource type has a platform-owned
+ * contract (human decision, 2026-07-17).
+ */
+/** Prefix marking a platform-owned workflow key (mirrors the server). */
+export declare const INTERNAL_WORKFLOW_KEY_PREFIX = "__internal.";
+/**
+ * True when `key` is in the platform-owned `__internal.` namespace. Trims and
+ * lowercases first (mirrors the server's `isReservedWorkflowKey`) so a padded
+ * or upper-cased value such as `  __Internal.Foo ` can't slip past the filter.
+ */
+export declare function isPlatformOwnedWorkflowKey(key: unknown): boolean;
+/**
+ * True when a workflow list/detail item is platform-owned.
+ *
+ * Prefers the server's derived `platformOwned` flag (#1660) when present, then
+ * falls back to the key prefix so an older server that doesn't emit the flag is
+ * still filtered (edge case 1). `workflowKey` is the admin list-item field;
+ * `key` covers a locally-parsed `[workflow]` table.
+ */
+export declare function isPlatformOwnedWorkflow(item: any): boolean;
+/**
+ * Why the authoring surface refuses a platform-owned key (#2645).
+ *
+ * `config create`, `config set` and `config push --only` all name an object by
+ * `<type>/<key>`, and `config push` skips the reserved namespace — so scaffolding
+ * or selecting one produces a file that is never uploaded, or a push that
+ * reports success having applied nothing. With configuration authored in TOML
+ * only, those are the two failures the surface has to make impossible: a flag
+ * that was rejected was visible, a file that is silently ignored is not.
+ *
+ * Returns the operator-facing reason, or `undefined` when the key is authorable.
+ * Pure, so every caller can be unit-tested without a live server.
+ */
+export declare function platformOwnedAuthoringError(type: string, key: string): string | undefined;
+/**
+ * Why the authoring surface refuses `<type>/<key>` — or `undefined` when it
+ * doesn't.
+ *
+ * The same question `config create`, `config set` and `config push --only`
+ * each ask before touching a file, now with two answers: a platform-owned
+ * workflow key (#1660/#2645) and a retired email type (#2884). Both fail the
+ * same way if unchecked — a file that is written locally and then either
+ * skipped silently or refused at the far end of a push — so both are refused
+ * at the point the key is named, with the sentence that says what to do.
+ */
+export declare function configAuthoringError(type: string, key: string): string | undefined;

package/dist/src/lib/platform-owned.js

@@ -0,0 +1,85 @@
+/**
+ * Shared predicate for platform-owned workflows (#1660).
+ *
+ * The platform owns workflow keys in the reserved `__internal.` namespace (see
+ * the server's `src/workflows/reserved-workflow-keys.ts`). These rows are
+ * created and managed by the platform, never authored in an app's config tree:
+ *
+ *   - `config pull` must not export them (they have no local TOML),
+ *   - `config diff` must not report them (they are not app config),
+ *   - `config push` must not upload them (the hollow export can't round-trip),
+ *   - `workflows codegen` must not generate an invoker for them.
+ *
+ * The CLI cannot import from `src/`, so this module mirrors the server's prefix
+ * policy in ONE place. The codegen skip and the sync filters both call it, so
+ * they can never drift from each other or from the server.
+ *
+ * The generic cross-resource `isPlatformOwnedEntity` abstraction is deliberately
+ * NOT here — it is deferred until a second resource type has a platform-owned
+ * contract (human decision, 2026-07-17).
+ */
+import { isRetiredEmailType, retiredEmailTypeGuidance, } from "./generated-config-surfaces.js";
+/** Prefix marking a platform-owned workflow key (mirrors the server). */
+export const INTERNAL_WORKFLOW_KEY_PREFIX = "__internal.";
+/**
+ * True when `key` is in the platform-owned `__internal.` namespace. Trims and
+ * lowercases first (mirrors the server's `isReservedWorkflowKey`) so a padded
+ * or upper-cased value such as `  __Internal.Foo ` can't slip past the filter.
+ */
+export function isPlatformOwnedWorkflowKey(key) {
+    return (typeof key === "string" &&
+        key.trim().toLowerCase().startsWith(INTERNAL_WORKFLOW_KEY_PREFIX));
+}
+/**
+ * True when a workflow list/detail item is platform-owned.
+ *
+ * Prefers the server's derived `platformOwned` flag (#1660) when present, then
+ * falls back to the key prefix so an older server that doesn't emit the flag is
+ * still filtered (edge case 1). `workflowKey` is the admin list-item field;
+ * `key` covers a locally-parsed `[workflow]` table.
+ */
+export function isPlatformOwnedWorkflow(item) {
+    if (item && item.platformOwned === true)
+        return true;
+    const key = item?.workflowKey ?? item?.key;
+    return isPlatformOwnedWorkflowKey(key);
+}
+/**
+ * Why the authoring surface refuses a platform-owned key (#2645).
+ *
+ * `config create`, `config set` and `config push --only` all name an object by
+ * `<type>/<key>`, and `config push` skips the reserved namespace — so scaffolding
+ * or selecting one produces a file that is never uploaded, or a push that
+ * reports success having applied nothing. With configuration authored in TOML
+ * only, those are the two failures the surface has to make impossible: a flag
+ * that was rejected was visible, a file that is silently ignored is not.
+ *
+ * Returns the operator-facing reason, or `undefined` when the key is authorable.
+ * Pure, so every caller can be unit-tested without a live server.
+ */
+export function platformOwnedAuthoringError(type, key) {
+    if (type !== "workflow" || !isPlatformOwnedWorkflowKey(key))
+        return undefined;
+    return `'${key}' is a platform-owned workflow — the reserved '${INTERNAL_WORKFLOW_KEY_PREFIX}' namespace is managed by the platform. 'config pull' does not export these and 'config push' skips them, so a file here would never reach the server.`;
+}
+/**
+ * Why the authoring surface refuses `<type>/<key>` — or `undefined` when it
+ * doesn't.
+ *
+ * The same question `config create`, `config set` and `config push --only`
+ * each ask before touching a file, now with two answers: a platform-owned
+ * workflow key (#1660/#2645) and a retired email type (#2884). Both fail the
+ * same way if unchecked — a file that is written locally and then either
+ * skipped silently or refused at the far end of a push — so both are refused
+ * at the point the key is named, with the sentence that says what to do.
+ */
+export function configAuthoringError(type, key) {
+    const platformOwned = platformOwnedAuthoringError(type, key);
+    if (platformOwned)
+        return platformOwned;
+    if (type === "email-template" && isRetiredEmailType(key)) {
+        return retiredEmailTypeGuidance(key);
+    }
+    return undefined;
+}
+//# sourceMappingURL=platform-owned.js.map

package/dist/src/lib/platform-owned.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-owned.js","sourceRoot":"","sources":["../../../src/lib/platform-owned.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EACL,kBAAkB,EAClB,wBAAwB,GACzB,MAAM,gCAAgC,CAAC;AAExC,yEAAyE;AACzE,MAAM,CAAC,MAAM,4BAA4B,GAAG,aAAa,CAAC;AAE1D;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CAAC,GAAY;IACrD,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,4BAA4B,CAAC,CAClE,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAS;IAC/C,IAAI,IAAI,IAAI,IAAI,CAAC,aAAa,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACrD,MAAM,GAAG,GAAG,IAAI,EAAE,WAAW,IAAI,IAAI,EAAE,GAAG,CAAC;IAC3C,OAAO,0BAA0B,CAAC,GAAG,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,2BAA2B,CACzC,IAAY,EACZ,GAAW;IAEX,IAAI,IAAI,KAAK,UAAU,IAAI,CAAC,0BAA0B,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC9E,OAAO,IAAI,GAAG,kDAAkD,4BAA4B,wJAAwJ,CAAC;AACvP,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAY,EACZ,GAAW;IAEX,MAAM,aAAa,GAAG,2BAA2B,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC7D,IAAI,aAAa;QAAE,OAAO,aAAa,CAAC;IACxC,IAAI,IAAI,KAAK,gBAAgB,IAAI,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC;QACzD,OAAO,wBAAwB,CAAC,GAAG,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}