primitive-admin 1.0.61 → 1.0.63

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":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAC3D,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAEpC,wCAAwC;AACxC,MAAM,CAAC,MAAM,qBAAqB,GAAG,iBAAiB,CAAC;AA6DvD,kFAAkF;AAClF,MAAM,UAAU,SAAS,CAAC,CAAS;IACjC,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACnD,CAAC;AAED,yEAAyE;AACzE,SAAS,WAAW,CAAC,GAAsB;IACzC,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC;IAC3C,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IACxB,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;IAC/E,OAAO,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AAClD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAAgB,EAChB,GAAsB;IAEtB,MAAM,CAAC,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IAC9B,IAAI,CAAC,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IACnC,MAAM,KAAK,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;IAE9B,uEAAuE;IACvE,wEAAwE;IACxE,wBAAwB;IACxB,MAAM,UAAU,GAAG,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACvE,IACE,KAAK,CAAC,QAAQ,CAAC,eAAe,CAAC;QAC/B,KAAK,CAAC,QAAQ,CAAC,gBAAgB,CAAC;QAChC,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC;QACzB,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC;QACxB,CAAC,UAAU,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,UAAU,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,EAChE,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IAC7B,CAAC;IAED,uEAAuE;IACvE,4EAA4E;IAC5E,uEAAuE;IACvE,wCAAwC;IACxC,MAAM,QAAQ,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACjE,IACE,CAAC,QAAQ,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;QAC5D,KAAK,CAAC,QAAQ,CAAC,eAAe,CAAC,EAC/B,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAC7C,CAAC;IAED,iFAAiF;IACjF,0EAA0E;IAC1E,IAAI,KAAK,CAAC,QAAQ,CAAC,oBAAoB,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,CAAC;QACjF,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC5C,CAAC;IAED,wEAAwE;IACxE,IAAI,KAAK,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC;QACrC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC3B,CAAC;IAED,gEAAgE;IAChE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AAC5B,CAAC;AAED;;;;GAIG;AACH,SAAS,0BAA0B,CAAC,SAAiB;IACnD,IAAI,GAAG,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAC7B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC;YAAE,OAAO,MAAM,CAAC;QAC3D,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,mBAAmB,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QAC7D,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG;YAAE,MAAM;QAC1B,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,aAAa,CAAC,OAA6B,EAAE;IAC3D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACpC,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,QAAQ,IAAI,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAC/E,MAAM,cAAc,GAAG,mBAAmB,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QAC1D,IAAI,cAAc,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YACpC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,0BAA0B,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1E,CAAC;QACD,OAAO,cAAc,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IAC7B,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC/D,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACvC,MAAM,UAAU,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAC9F,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,IAAI,CAAC;gBACH,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;oBAAE,OAAO,IAAI,CAAC;YACtD,CAAC;YAAC,MAAM,CAAC;gBACP,wCAAwC;YAC1C,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,sBAAsB,CACpC,GAAsB,EACtB,QAAgB;IAEhB,MAAM,IAAI,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAC3E,IAAI,IAAI,IAAI,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACtF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,oBAAoB,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAC5D,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAClC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,mBAAmB,CAAC,IAA0B;IACrD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC;IACnD,OAAO,YAAY,CAAC,GAAG,CAAC,IAAI,sBAAsB,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;AACrF,CAAC;AAED;;;;GAIG;AACH,SAAS,cAAc,CAAC,GAAW,EAAE,IAA0B;IAC7D,MAAM,QAAQ,GAAG,2BAA2B,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACxD,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,MAAM,CAAC;QAAE,OAAO,MAAM,CAAC;IAC9D,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5D,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAC;AACnC,CAAC;AAED,SAAS,aAAa,CAAC,OAAuB,EAAE,IAAY;IAC1D,OAAO,OAAO,KAAK,MAAM,CAAC,CAAC,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC,CAAC,YAAY,IAAI,EAAE,CAAC;AACzE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAoB,EACpB,GAAW,EACX,OAAe,EACf,OAA6B,EAAE;IAE/B,MAAM,IAAI,GAAG,GAAG,GAAG,IAAI,OAAO,EAAE,CAAC;IACjC,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,QAAQ;YACX,OAAO,aAAa,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC9C,KAAK,OAAO;YACV,OAAO,OAAO,CAAC,OAAO,KAAK,MAAM,CAAC,CAAC,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,IAAI,EAAE,CAAC;QAC1E,KAAK,QAAQ;YACX,wEAAwE;YACxE,sDAAsD;YACtD,OAAO,IAAI,CAAC;QACd,KAAK,SAAS;YACZ,OAAO,aAAa,CAAC,mBAAmB,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;IAC1D,CAAC;AACH,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,WAAW,CACzB,GAAW,EACX,OAA6B,EAAE;IAE/B,MAAM,OAAO,GAAG,cAAc,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAC1C,OAAO,OAAO,KAAK,MAAM;QACvB,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,CAAC,EAAE;QAC/C,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,SAAS,EAAE,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;AACvD,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,cAAc,CAAC,GAAW,EAAE,OAA6B,EAAE;IACzE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACjD,OAAO,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACtC,CAAC;AAED;;;;;GAKG;AACH,SAAS,WAAW,CAAC,IAAY;IAC/B,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,IAAY;IAC/B,IAAI,CAAC;QACH,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,mFAAmF;AACnF,SAAS,sBAAsB,CAAC,IAAY,EAAE,GAAW;IACvD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACxC,IAAI,QAAQ,GAAa,EAAE,CAAC;IAC5B,IAAI,CAAC;QACH,QAAQ,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,QAAQ;SACZ,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,EAAE,cAAc,EAAE,GAAG,CAAC,CAAC;SACpD,MAAM,CAAC,WAAW,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB,CAClC,GAAsB,EACtB,QAAgB;IAEhB,MAAM,IAAI,GAAG;QACX,GAAG,CAAC,SAAS;QACb,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS;QACxD,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS;QAChE,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS;KAC9D,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAElC,MAAM,QAAQ,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC9C,IAAI,GAAG,CAAC,iBAAiB;QAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAChE,KAAK,MAAM,KAAK,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QAC/D,IAAI,KAAK,IAAI,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IACtE,CAAC;IAED,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC;IAC1E,IAAI,GAAG,CAAC,OAAO;QAAE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC;IAEpE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;AAClD,CAAC;AAED,SAAS,MAAM,CAAC,KAAe;IAC7B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;QACxB,MAAM,GAAG,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;QACzB,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QAChC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,2BAA2B,CACzC,GAAW,EACX,OAA6B,EAAE;IAE/B,MAAM,KAAK,GACT,IAAI,CAAC,KAAK,IAAI,oBAAoB,CAAC,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAC;IACjG,MAAM,KAAK,GAAoB,EAAE,CAAC;IAClC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAE/B,MAAM,GAAG,GAAG,CAAC,OAAuB,EAAE,IAAY,EAAE,EAAE;QACpD,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QAC5B,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO;QAC1B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,KAAK,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC7D,CAAC,CAAC;IAEF,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;QAC9B,KAAK,MAAM,IAAI,IAAI,sBAAsB,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;YACrD,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QACpB,CAAC;IACH,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC7B,IAAI,WAAW,CAAC,IAAI,CAAC;YAAE,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC1C,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

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

@@ -13,6 +13,56 @@ 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. The deprecated
+ * `cursor` alias (#1316, removal tracked in #1982) is accepted on input but
+ * never re-emitted, so CLI consumers are already on `nextCursor` when the
+ * server drops it.
+ */
+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, cursor }`).
+ * Both are collapsed here to `{ items, hasMore, nextCursor? }` so like verbs
+ * print like envelopes.
+ *
+ * Accepts `items` or `data` as the array key and `nextCursor` or the
+ * deprecated `cursor` alias as the cursor. 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`), whose
+ * cursor contract is the opposite: it *back-fills* the deprecated `cursor`
+ * alias so the client keeps working against pre-#1316 servers, while this one
+ * drops it so CLI consumers are already off it when #1982 lands. 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.
+ *
+ * Note: the list methods in `api-client.ts` that re-emit the deprecated
+ * `cursor` alias are deliberately NOT routed through this helper — they must
+ * keep dual-emitting until #1982 closes its deprecation window, which is the
+ * opposite of this contract. As of this writing that is eight methods (grep
+ * `cursor: nextCursor` in `api-client.ts` for the current set):
+ * `listInvitations`, `listWebhookEvents`, `listWorkflowRuns`,
+ * `listUserWorkflowRuns`, `listAllAdmins`, `listGroups`, `listGroupMembers`,
+ * `listBucketBlobs`. The `listCollection*` methods only *read* the alias and
+ * emit `nextCursor` alone, so they already match this contract.
+ *
+ * `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>;
 export type PageFetcher<T> = (cursor: string | undefined) => Promise<PaginatedPage<T>>;
 export interface PaginateOptions {
     /**

package/dist/src/lib/paginate.js

@@ -9,6 +9,59 @@
  * 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, cursor }`).
+ * Both are collapsed here to `{ items, hasMore, nextCursor? }` so like verbs
+ * print like envelopes.
+ *
+ * Accepts `items` or `data` as the array key and `nextCursor` or the
+ * deprecated `cursor` alias as the cursor. 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`), whose
+ * cursor contract is the opposite: it *back-fills* the deprecated `cursor`
+ * alias so the client keeps working against pre-#1316 servers, while this one
+ * drops it so CLI consumers are already off it when #1982 lands. 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.
+ *
+ * Note: the list methods in `api-client.ts` that re-emit the deprecated
+ * `cursor` alias are deliberately NOT routed through this helper — they must
+ * keep dual-emitting until #1982 closes its deprecation window, which is the
+ * opposite of this contract. As of this writing that is eight methods (grep
+ * `cursor: nextCursor` in `api-client.ts` for the current set):
+ * `listInvitations`, `listWebhookEvents`, `listWorkflowRuns`,
+ * `listUserWorkflowRuns`, `listAllAdmins`, `listGroups`, `listGroupMembers`,
+ * `listBucketBlobs`. The `listCollection*` methods only *read* the alias and
+ * emit `nextCursor` alone, so they already match this contract.
+ *
+ * `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 ?? page.cursor ?? undefined;
+    const envelope = {
+        items: rawItems,
+        hasMore: typeof page.hasMore === "boolean" ? page.hasMore : Boolean(nextCursor),
+    };
+    if (nextCursor)
+        envelope.nextCursor = nextCursor;
+    return envelope;
+}
 /**
  * Walk every cursor page from `fetchPage` and return the concatenated items.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"paginate.js","sourceRoot":"","sources":["../../../src/lib/paginate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAkBH;;;;;;;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"}
+{"version":3,"file":"paginate.js","sourceRoot":"","sources":["../../../src/lib/paginate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAqBH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;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,IAAK,CAAC,MAAM,IAAI,SAAS,CAAC;IACjE,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;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

@@ -5,9 +5,9 @@
  * 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:
  *
- *   - `sync pull` must not export them (they have no local TOML),
- *   - `sync diff` must not report them (they are not app config),
- *   - `sync push` must not upload them (the hollow export can't round-trip),
+ *   - `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
@@ -35,3 +35,29 @@ export declare function isPlatformOwnedWorkflowKey(key: unknown): boolean;
  * `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

@@ -5,9 +5,9 @@
  * 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:
  *
- *   - `sync pull` must not export them (they have no local TOML),
- *   - `sync diff` must not report them (they are not app config),
- *   - `sync push` must not upload them (the hollow export can't round-trip),
+ *   - `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
@@ -18,6 +18,7 @@
  * 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.";
 /**
@@ -43,4 +44,42 @@ export function isPlatformOwnedWorkflow(item) {
     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

@@ -1 +1 @@
-{"version":3,"file":"platform-owned.js","sourceRoot":"","sources":["../../../src/lib/platform-owned.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,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"}
+{"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"}

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

@@ -34,6 +34,14 @@ export interface ProjectEnvironment {
     apiUrl: string;
     appId?: string;
     appName?: string;
+    /**
+     * The app's web counterpart for this environment, as a normalized origin
+     * (`https://app.example.com`) — the deployment whose `/oauth/callback` the
+     * emailed sign-in link points at, and the origin an incoming universal link
+     * is trusted from (#2982). Per environment, because that deployment has to
+     * talk to the same backend and app as this entry.
+     */
+    webUrl?: string;
     /** Optional notes about this environment. */
     description?: string;
 }

package/dist/src/lib/project-config.js

@@ -18,6 +18,18 @@
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { dirname, join, resolve } from "path";
+import { detectInstall, installCommand, upgradeCommand, PRIMITIVE_CLI_PACKAGE, } from "./package-manager.js";
+import { validateServerUrl } from "./server-url.js";
+import { normalizeWebUrl, validateWebUrl } from "./web-url.js";
+/**
+ * The command that upgrades the running CLI. Falls back to the first-time
+ * install command when the running copy can't be upgraded by a package
+ * manager (a source checkout).
+ */
+function cliUpgradeCommand() {
+    return (upgradeCommand(detectInstall(), PRIMITIVE_CLI_PACKAGE, "latest") ??
+        installCommand(PRIMITIVE_CLI_PACKAGE));
+}
 /**
  * Current schema version. Increment the major version when making
  * backward-incompatible changes. Older configs will be rejected.
@@ -104,7 +116,7 @@ export function validateProjectConfig(raw, sourcePath) {
     // reject v1 configs and tell the user to migrate.
     if (version !== CURRENT_CONFIG_VERSION) {
         if (version > CURRENT_CONFIG_VERSION) {
-            throw new ProjectConfigError(`${PROJECT_CONFIG_DISPLAY_NAME} has version ${version}, but this CLI only understands version ${CURRENT_CONFIG_VERSION}. Please upgrade the CLI: npm install -g primitive-admin`, sourcePath);
+            throw new ProjectConfigError(`${PROJECT_CONFIG_DISPLAY_NAME} has version ${version}, but this CLI only understands version ${CURRENT_CONFIG_VERSION}. Please upgrade the CLI: ${cliUpgradeCommand()}`, sourcePath);
         }
         throw new ProjectConfigError(`${PROJECT_CONFIG_DISPLAY_NAME} has unsupported version ${version}. This CLI expects version ${CURRENT_CONFIG_VERSION}.`, sourcePath);
     }
@@ -124,10 +136,7 @@ export function validateProjectConfig(raw, sourcePath) {
         if (typeof envObj.apiUrl !== "string" || !envObj.apiUrl) {
             throw new ProjectConfigError(`Environment "${name}" must have a non-empty "apiUrl" string in ${PROJECT_CONFIG_DISPLAY_NAME}.`, sourcePath);
         }
-        try {
-            new URL(envObj.apiUrl);
-        }
-        catch {
+        if (validateServerUrl(envObj.apiUrl) !== true) {
             throw new ProjectConfigError(`Environment "${name}" has invalid apiUrl: ${envObj.apiUrl}`, sourcePath);
         }
         if (envObj.appId !== undefined && typeof envObj.appId !== "string") {
@@ -139,10 +148,26 @@ export function validateProjectConfig(raw, sourcePath) {
         if (envObj.description !== undefined && typeof envObj.description !== "string") {
             throw new ProjectConfigError(`Environment "${name}": "description" must be a string if set.`, sourcePath);
         }
+        // An origin, not any URL: the emailed sign-in link is built from it, so a
+        // value the server's allow-list would refuse — or one whose callback path
+        // neither the web app nor the AASA component names — is a 400 or a dead
+        // link later rather than an error here (#2982).
+        if (envObj.webUrl !== undefined) {
+            if (typeof envObj.webUrl !== "string") {
+                throw new ProjectConfigError(`Environment "${name}": "webUrl" must be a string if set.`, sourcePath);
+            }
+            const problem = validateWebUrl(envObj.webUrl);
+            if (problem !== true) {
+                throw new ProjectConfigError(`Environment "${name}" has invalid webUrl: ${problem}`, sourcePath);
+            }
+        }
         environments[name] = {
             apiUrl: envObj.apiUrl.replace(/\/$/, ""),
             appId: envObj.appId,
             appName: envObj.appName,
+            webUrl: envObj.webUrl === undefined
+                ? undefined
+                : normalizeWebUrl(envObj.webUrl),
             description: envObj.description,
         };
     }