primitive-admin 1.0.61 → 1.0.63

package/dist/src/lib/init-ios-links.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The `CFBundleURLName` the library and the template agree on. Changing it
+ * breaks the manager's scheme resolution, so it is pinned by a test that reads
+ * both files.
+ */
+export declare const PRIMITIVE_AUTH_URL_TYPE_NAME = "PrimitiveAuth";
+/** The library's fallback scheme — reserved, never a derived result. */
+export declare const FALLBACK_CALLBACK_SCHEME = "primitiveapp";
+/**
+ * The custom URL scheme for one scaffolded client: a readable prefix from the
+ * app name, then the full lowercased app ID.
+ *
+ * Deterministic and injective over server-generated app IDs — two apps never
+ * share a scheme, whatever they are called.
+ */
+export declare function deriveCallbackScheme(appName: string, appId: string, clientDirName?: string): string;
+/** The redirect target the emailed sign-in link uses, for one scheme. */
+export declare function iosMagicLinkRedirectUri(scheme: string): string;
+export interface StampResult {
+    /** `not-found` when the plist predates the `PrimitiveAuth` URL type. */
+    outcome: "stamped" | "already" | "not-found";
+}
+/**
+ * Replaces the scheme registered under the `PrimitiveAuth` URL type in a
+ * scaffolded client's `Info-Partial.plist`.
+ *
+ * A targeted text substitution, not a plist rewrite: the file's comments are
+ * the checklist a developer reads when their emailed link does nothing, and a
+ * serializer would drop them.
+ */
+export declare function stampCallbackScheme(clientDir: string, scheme: string): StampResult;
+/**
+ * How to point an environment at the app's web origin — in the shape that
+ * actually works (#2982).
+ *
+ * `primitive env add` CREATES an environment: it requires `--api-url` and
+ * refuses a name the config already has. Every environment anyone reads this
+ * about already exists (init wrote `dev`; `prod` was added when the app was
+ * deployed), so the instruction for those has to be the file, which is also
+ * what the docs describe as the way to edit one. The flag is worth naming only
+ * where a new environment is being created.
+ *
+ * `origin` is the placeholder or real origin to show.
+ */
+export declare function setWebUrlInstruction(origin: string, indent?: string): string[];
+/**
+ * What init prints about email sign-in on the iOS path: it already works, and
+ * this is the one opt-in that adds the link.
+ *
+ * The allow-list step is phrased as a MERGE into the existing array — `app.toml`
+ * is the whole app-settings truth on push (#2880), so a replacement array would
+ * silently drop the web callback the app was seeded with.
+ *
+ * `registered` is false when the scheme could not be stamped (an older template
+ * with no `PrimitiveAuth` URL type). The allow-list entry and the flag are the
+ * same either way, but the closing line must not claim a registration that is
+ * not there: a developer who did only the two steps would be left with a dead
+ * tap and nothing naming the missing piece.
+ */
+export declare function linkOptInGuidance(scheme: string, options?: {
+    registered?: boolean;
+}): string[];
+/**
+ * What init prints for an app with BOTH clients: the emailed sign-in link is
+ * already the web app's https callback, and this is what it takes to make that
+ * link open the iOS app in production (#2982).
+ *
+ * Everything here is a post-deploy step by necessity — the production web
+ * domain does not exist at init time, and the deploy script never learns the
+ * URL it deployed to. The order is load-bearing: the `applinks:` entitlement
+ * is the ONLY thing that makes Apple fetch the association document, and
+ * Apple's CDN caches what it gets, so it goes last — after the deployed
+ * document has been verified.
+ *
+ * `webOrigin` is the dev origin the run seeded — set only when the run also
+ * confirmed that origin's `/oauth/callback` is on the app's allow-list, since
+ * that is what makes the seeded link work.
+ *
+ * `unverifiedDevCallback` is the opposite case: a combined app whose allow-list
+ * this run could not vouch for (an adopted app, or no credentials to ask with).
+ * Nothing was seeded — the app keeps its working code-only email — and the two
+ * steps that turn the link on are printed instead. Neither is set for an
+ * adopting run, which does not own the project config at all.
+ */
+export declare function universalLinkGuidance(options?: {
+    webOrigin?: string;
+    unverifiedDevCallback?: string;
+}): string[];
+/** What init says when the template predates the `PrimitiveAuth` URL type. */
+export declare function missingUrlTypeGuidance(scheme: string): string[];

package/dist/src/lib/init-ios-links.js

@@ -0,0 +1,218 @@
+/**
+ * The iOS app's own URL scheme, and the documented opt-in that turns the
+ * sign-in email's LINK on (#2969).
+ *
+ * The Swift template registers one custom URL scheme, under the
+ * `PrimitiveAuth` URL-type name that `PrimitiveAuthManager` reads its callback
+ * scheme from. Shipped, that scheme is `primitiveapp` — which every app
+ * scaffolded from the template would otherwise share, making iOS link routing
+ * between two of them on one device ambiguous. So init stamps an app-unique
+ * scheme in its place.
+ *
+ * The suffix is the WHOLE app ID, not a tail or a hash of it: app IDs are
+ * 26-character ULIDs, and any fixed-width squeeze of them is many-to-one — two
+ * distinct apps could still be handed the same scheme, which is the failure
+ * this stamping exists to prevent.
+ *
+ * Init writes no app settings here. Email sign-in works out of the box because
+ * the manager sends NO redirect target by default, so the email carries the
+ * code alone and the allow-list is not consulted at all. Sending the link is
+ * the developer's opt-in — one allow-list entry plus one flag — and init only
+ * prints what those are.
+ */
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+/**
+ * The `CFBundleURLName` the library and the template agree on. Changing it
+ * breaks the manager's scheme resolution, so it is pinned by a test that reads
+ * both files.
+ */
+export const PRIMITIVE_AUTH_URL_TYPE_NAME = "PrimitiveAuth";
+/** The library's fallback scheme — reserved, never a derived result. */
+export const FALLBACK_CALLBACK_SCHEME = "primitiveapp";
+/** How much of the app name survives into the readable prefix. */
+const PREFIX_MAX_LENGTH = 20;
+/** The app-name placeholder init carries when it never asked for one. */
+const APP_NAME_PLACEHOLDER = "(existing app)";
+/**
+ * A URL-scheme-safe, letter-first fragment of `value`, or `""` when nothing
+ * usable survives (an empty name, an emoji-only one, digits alone).
+ */
+function schemeFragment(value, maxLength) {
+    const sanitized = (value ?? "").toLowerCase().replace(/[^a-z0-9]/g, "");
+    // RFC 3986 schemes start with a letter, and the prefix is what leads.
+    const letterFirst = sanitized.replace(/^[0-9]+/, "");
+    return letterFirst.slice(0, maxLength);
+}
+/**
+ * The custom URL scheme for one scaffolded client: a readable prefix from the
+ * app name, then the full lowercased app ID.
+ *
+ * Deterministic and injective over server-generated app IDs — two apps never
+ * share a scheme, whatever they are called.
+ */
+export function deriveCallbackScheme(appName, appId, clientDirName) {
+    const named = appName === APP_NAME_PLACEHOLDER ? "" : appName;
+    const prefix = schemeFragment(named, PREFIX_MAX_LENGTH) ||
+        schemeFragment(clientDirName, PREFIX_MAX_LENGTH) ||
+        "app";
+    // No truncation: the whole ID is what makes the scheme unique.
+    const suffix = (appId ?? "").toLowerCase().replace(/[^a-z0-9]/g, "");
+    const scheme = suffix ? `${prefix}-${suffix}` : prefix;
+    // Only reachable with no app ID at all, but the reserved scheme is exactly
+    // what a derived one must never collide with.
+    return scheme === FALLBACK_CALLBACK_SCHEME ? `${scheme}-app` : scheme;
+}
+/** The redirect target the emailed sign-in link uses, for one scheme. */
+export function iosMagicLinkRedirectUri(scheme) {
+    return `${scheme}://auth/magic-link`;
+}
+/**
+ * Replaces the scheme registered under the `PrimitiveAuth` URL type in a
+ * scaffolded client's `Info-Partial.plist`.
+ *
+ * A targeted text substitution, not a plist rewrite: the file's comments are
+ * the checklist a developer reads when their emailed link does nothing, and a
+ * serializer would drop them.
+ */
+export function stampCallbackScheme(clientDir, scheme) {
+    const plistPath = join(clientDir, "Info-Partial.plist");
+    if (!existsSync(plistPath))
+        return { outcome: "not-found" };
+    let text;
+    try {
+        text = readFileSync(plistPath, "utf-8");
+    }
+    catch {
+        return { outcome: "not-found" };
+    }
+    const marker = `<string>${PRIMITIVE_AUTH_URL_TYPE_NAME}</string>`;
+    const markerIndex = text.indexOf(marker);
+    if (markerIndex === -1)
+        return { outcome: "not-found" };
+    // Stay inside the URL-type dict the marker names: an app may register other
+    // schemes (a Google reversed client ID, say) and those are not ours to move.
+    const dictStart = text.lastIndexOf("<dict>", markerIndex);
+    const dictEnd = text.indexOf("</dict>", markerIndex);
+    if (dictStart === -1 || dictEnd === -1)
+        return { outcome: "not-found" };
+    const block = text.slice(dictStart, dictEnd);
+    if (!block.includes("<key>CFBundleURLName</key>"))
+        return { outcome: "not-found" };
+    const schemesPattern = /(<key>CFBundleURLSchemes<\/key>\s*<array>\s*<string>)([^<]*)(<\/string>)/;
+    const match = schemesPattern.exec(block);
+    if (!match)
+        return { outcome: "not-found" };
+    if (match[2] === scheme)
+        return { outcome: "already" };
+    const rewritten = block.replace(schemesPattern, `$1${scheme}$3`);
+    writeFileSync(plistPath, text.slice(0, dictStart) + rewritten + text.slice(dictEnd));
+    return { outcome: "stamped" };
+}
+/**
+ * How to point an environment at the app's web origin — in the shape that
+ * actually works (#2982).
+ *
+ * `primitive env add` CREATES an environment: it requires `--api-url` and
+ * refuses a name the config already has. Every environment anyone reads this
+ * about already exists (init wrote `dev`; `prod` was added when the app was
+ * deployed), so the instruction for those has to be the file, which is also
+ * what the docs describe as the way to edit one. The flag is worth naming only
+ * where a new environment is being created.
+ *
+ * `origin` is the placeholder or real origin to show.
+ */
+export function setWebUrlInstruction(origin, indent = "  ") {
+    return [
+        `${indent}add "webUrl": "${origin}" to that environment in .primitive/config.json`,
+        `${indent}(\`primitive env add <name> --api-url … --web-url <origin>\` does this only for an`,
+        `${indent}environment it CREATES — it cannot edit one that already exists).`,
+    ];
+}
+/**
+ * What init prints about email sign-in on the iOS path: it already works, and
+ * this is the one opt-in that adds the link.
+ *
+ * The allow-list step is phrased as a MERGE into the existing array — `app.toml`
+ * is the whole app-settings truth on push (#2880), so a replacement array would
+ * silently drop the web callback the app was seeded with.
+ *
+ * `registered` is false when the scheme could not be stamped (an older template
+ * with no `PrimitiveAuth` URL type). The allow-list entry and the flag are the
+ * same either way, but the closing line must not claim a registration that is
+ * not there: a developer who did only the two steps would be left with a dead
+ * tap and nothing naming the missing piece.
+ */
+export function linkOptInGuidance(scheme, options = {}) {
+    const registered = options.registered !== false;
+    const redirectUri = iosMagicLinkRedirectUri(scheme);
+    return [
+        "Email sign-in works now: the email carries a 6-digit code and needs no app settings.",
+        "When this app gets a web client, prefer the https link: set the environment's `webUrl` —",
+        ...setWebUrlInstruction("https://<your-web-domain>"),
+        "  The email then carries that origin's /oauth/callback instead — one link that opens this",
+        "  app where it is installed and signs in through the browser anywhere else.",
+        `Until then, to ALSO send a sign-in link that opens this app, add "${redirectUri}" to the existing`,
+        "  [auth].emailRedirectUris array in config/app.toml (merge it in — run",
+        "  `primitive config pull --only app` first if that file is not there yet), then run",
+        "  `primitive config push --only app` and set `authManager.sendsEmailSignInLink = true`.",
+        registered
+            ? "The scheme registration and the link routing are already in this client."
+            : `The scheme "${scheme}" is NOT registered in this client yet — register it first (see`
+                + ` the ${PRIMITIVE_AUTH_URL_TYPE_NAME} warning above), or the link stays a dead tap.`,
+        "  Full checklist: `primitive guides get authentication --language swift`, or the",
+        "  authentication.md docs page — 'Make the emailed sign-in link open your app'.",
+    ];
+}
+/**
+ * What init prints for an app with BOTH clients: the emailed sign-in link is
+ * already the web app's https callback, and this is what it takes to make that
+ * link open the iOS app in production (#2982).
+ *
+ * Everything here is a post-deploy step by necessity — the production web
+ * domain does not exist at init time, and the deploy script never learns the
+ * URL it deployed to. The order is load-bearing: the `applinks:` entitlement
+ * is the ONLY thing that makes Apple fetch the association document, and
+ * Apple's CDN caches what it gets, so it goes last — after the deployed
+ * document has been verified.
+ *
+ * `webOrigin` is the dev origin the run seeded — set only when the run also
+ * confirmed that origin's `/oauth/callback` is on the app's allow-list, since
+ * that is what makes the seeded link work.
+ *
+ * `unverifiedDevCallback` is the opposite case: a combined app whose allow-list
+ * this run could not vouch for (an adopted app, or no credentials to ask with).
+ * Nothing was seeded — the app keeps its working code-only email — and the two
+ * steps that turn the link on are printed instead. Neither is set for an
+ * adopting run, which does not own the project config at all.
+ */
+export function universalLinkGuidance(options = {}) {
+    const lines = [
+        "This app has both an iOS and a web client, so its sign-in email carries ONE https link:",
+        "  the web app's /oauth/callback. Tapped where the iOS app is installed it opens the app;",
+        "  anywhere else it is an ordinary web sign-in. The 6-digit code still works everywhere.",
+    ];
+    if (options.webOrigin) {
+        lines.push(`In dev that link is ${options.webOrigin}/oauth/callback — seeded as the environment's`, "  `webUrl`, and allow-listed on the app. Nothing to do.");
+    }
+    else if (options.unverifiedDevCallback) {
+        const origin = options.unverifiedDevCallback.replace(/\/oauth\/callback$/, "");
+        lines.push("The link is NOT on yet in dev: this app already existed, and its sign-in link allow-list", `  does not (or could not be checked to) carry ${options.unverifiedDevCallback}. Nothing was`, "  changed — the email stays code-only, which works. To turn the link on:", `  1. Merge "${options.unverifiedDevCallback}" into the existing [auth].emailRedirectUris`, "     array in config/app.toml (run `primitive config pull --only app` first if that file is", "     not there yet), then `primitive config push --only app`.", `  2. Then ${setWebUrlInstruction(origin, "")[0]}`, "     — the same edit the production steps below describe.");
+    }
+    else {
+        lines.push("Set `webUrl` on this app's environment to turn it on (this run did not write the", "  project config):", ...setWebUrlInstruction("https://<your-web-domain>"), "  Allow-list that origin's /oauth/callback in [auth].emailRedirectUris too.");
+    }
+    lines.push("For production, once the web app is deployed:", "  1. Set that environment's `webUrl` to the deployed origin —", ...setWebUrlInstruction("https://<your-web-domain>", "     "), "  2. Merge \"https://<your-web-domain>/oauth/callback\" into the existing", "     [auth].emailRedirectUris array in config/app.toml (run `primitive config pull --only app`", "     first if that file is not there yet), then `primitive config push --only app`.", "  3. In the web client, fill your Apple team and bundle ids into", "     public/.well-known/apple-app-site-association.example and rename it (drop .example).", "  4. Deploy, then verify: `curl -i https://<your-web-domain>/.well-known/apple-app-site-association`", "     must return 200, application/json and the JSON body — HTML means the SPA fallback answered.", "  5. Only then enable the `applinks:<your-web-domain>` entitlement in the iOS client's", "     project.yml (it needs a real DEVELOPMENT_TEAM) and reinstall the app.", "  Full checklist: the web client's public/.well-known/README.md, or the authentication", "  docs page — 'Make the emailed sign-in link open your app'.");
+    return lines;
+}
+/** What init says when the template predates the `PrimitiveAuth` URL type. */
+export function missingUrlTypeGuidance(scheme) {
+    return [
+        `This template's Info-Partial.plist registers no ${PRIMITIVE_AUTH_URL_TYPE_NAME} URL type, so the`,
+        `  scheme "${scheme}" was not stamped and an emailed sign-in link cannot open this app.`,
+        `  Add a CFBundleURLTypes entry named ${PRIMITIVE_AUTH_URL_TYPE_NAME} with that scheme, then follow`,
+        "  the authentication.md docs page — 'Make the emailed sign-in link open your app'",
+        "  (or `primitive guides get authentication --language swift`).",
+    ];
+}
+//# sourceMappingURL=init-ios-links.js.map

package/dist/src/lib/init-ios-links.js.map

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

package/dist/src/lib/init-plan.d.ts

@@ -0,0 +1,80 @@
+import type { Platform } from "./resolve-platform.js";
+export type InitMode = "standalone" | "multi-client" | "add-client";
+export interface ClientPlan {
+    platform: Platform;
+    /** Absolute directory this client's template is installed into. */
+    dir: string;
+}
+export interface InitPlan {
+    mode: InitMode;
+    /** Every client this run scaffolds, in processing order (web first). */
+    clients: ClientPlan[];
+    /** The directory holding the ONE `.primitive/` for this app. */
+    projectRoot: string;
+    /**
+     * Whether this run writes `.primitive/config.json` and seeds the
+     * environment's credential slot. False when adopting: the config is already
+     * there and is not this run's to rewrite.
+     */
+    writesProjectConfig: boolean;
+    /**
+     * Whether this run may create the app and point the CLI's global "current
+     * app" at it. False when adopting — the app already exists and belongs to the
+     * project config.
+     */
+    ownsApp: boolean;
+    /**
+     * Whether this run creates the git repository and its initial commit. False
+     * when adopting: the surrounding repository owns the history, and the new
+     * files are left for the user to review and commit.
+     */
+    initsGit: boolean;
+    /**
+     * The one schema both clients read, or `null` in standalone mode where the
+     * client keeps the template's own copy (spec decision 1: single-client output
+     * is unchanged).
+     */
+    canonicalSchemaPath: string | null;
+    /**
+     * Whether this run may write an app-wide `AGENTS.md` at the project root.
+     * Never over an existing file — client `AGENTS.md` files ship with their
+     * templates and an adopted repo's root file is the user's.
+     */
+    writesRootAgents: boolean;
+}
+export interface PlanInitInput {
+    /** The resolved platforms, in canonical order. */
+    platforms: Platform[];
+    /** Absolute directory the command was pointed at. */
+    targetDir: string;
+    /**
+     * The nearest ancestor project root, passed ONLY when it differs from
+     * `targetDir` — `primitive init .` at an existing project root keeps its
+     * merge behavior rather than adopting itself.
+     */
+    ancestorProjectRoot?: string | null;
+}
+/** Resolve the layout for this run. */
+export declare function planInit(input: PlanInitInput): InitPlan;
+export interface InitGuardInput {
+    /** The init config's `action`, when a non-interactive config is in effect. */
+    action?: "create" | "use-existing" | "add-client";
+    /** Whether an init config is in effect at all. */
+    hasConfig: boolean;
+    /** The nearest ancestor project root, or null/undefined outside a project. */
+    ancestorProjectRoot?: string | null;
+    /** `app_id` from a `use-existing` init config. */
+    configAppId?: string;
+    /** `--use-existing-app-id`. */
+    flagAppId?: string;
+    /** The adopted environment's `appId`, when adopting. */
+    environmentAppId?: string;
+    /** The adopted environment's name, for the error messages. */
+    environmentName?: string;
+}
+/**
+ * Everything a run must be refused for, checked before any download, any API
+ * call and any write. Returns the user-facing message, or `null` when the run
+ * may proceed.
+ */
+export declare function checkInitGuards(input: InitGuardInput): string | null;

package/dist/src/lib/init-plan.js

@@ -0,0 +1,95 @@
+/**
+ * What shape does this `primitive init` run produce? (#2890)
+ *
+ * One Primitive app can have several clients — a web client and a native
+ * client — and they are one app: one appId, one project config, one exported
+ * server-config tree, one model schema. `init` therefore composes one of three
+ * layouts, and the choice decides everything downstream:
+ *
+ *   standalone   — one client, no surrounding project. Today's flat scaffold,
+ *                  unchanged: the client IS the project root.
+ *   multi-client — several clients, no surrounding project. Each client gets a
+ *                  platform-named subdirectory; the project config, the git
+ *                  repository and the canonical schema live at the root.
+ *   add-client   — an ancestor `.primitive/config.json` already exists. The run
+ *                  ADOPTS it: no nested project config, no nested git
+ *                  repository, no app creation, no commit. This is the path the
+ *                  issue opens with — running init in a subdirectory used to
+ *                  scaffold a second project that had to be partly undone.
+ *
+ * Pure on purpose: the layout and the guards are the part that is expensive to
+ * get wrong and impossible to assert from a half-written scaffold.
+ */
+import { join } from "path";
+import { PROJECT_CONFIG_DISPLAY_NAME } from "./project-config.js";
+/** Resolve the layout for this run. */
+export function planInit(input) {
+    const adopting = Boolean(input.ancestorProjectRoot);
+    const projectRoot = adopting ? input.ancestorProjectRoot : input.targetDir;
+    const composed = adopting || input.platforms.length > 1;
+    // One client in an adopt run lands exactly where the user pointed the
+    // command; anything else gets a platform-named subdirectory, which is what
+    // makes `web/` and `ios/` siblings under one root.
+    const useSubdirectories = input.platforms.length > 1;
+    const clients = input.platforms.map((platform) => ({
+        platform,
+        dir: useSubdirectories ? join(input.targetDir, platform) : input.targetDir,
+    }));
+    const mode = adopting
+        ? "add-client"
+        : input.platforms.length > 1
+            ? "multi-client"
+            : "standalone";
+    return {
+        mode,
+        clients,
+        projectRoot,
+        writesProjectConfig: !adopting,
+        ownsApp: !adopting,
+        initsGit: !adopting,
+        canonicalSchemaPath: composed
+            ? join(projectRoot, "models", "models.toml")
+            : null,
+        writesRootAgents: composed,
+    };
+}
+/**
+ * Everything a run must be refused for, checked before any download, any API
+ * call and any write. Returns the user-facing message, or `null` when the run
+ * may proceed.
+ */
+export function checkInitGuards(input) {
+    const root = input.ancestorProjectRoot;
+    if (!root) {
+        // `add-client` describes adopting a project that is not there.
+        if (input.action === "add-client") {
+            return (`action = "add-client" adds a client to an existing Primitive app, but there is no ` +
+                `${PROJECT_CONFIG_DISPLAY_NAME} in this directory or any parent. ` +
+                `Run init from inside the app's repository, or use action = "create" to start a new app.`);
+        }
+        return null;
+    }
+    const envName = input.environmentName ?? "the selected environment";
+    // Creating a SECOND app inside a repository that already has one is the
+    // nesting this change removes.
+    if (input.action === "create") {
+        return (`action = "create" would create a second Primitive app inside the existing project at ${root}. ` +
+            `Use action = "add-client" to add this client to the app that project already targets.`);
+    }
+    if (!input.environmentAppId) {
+        return (`The "${envName}" environment in ${root}/${PROJECT_CONFIG_DISPLAY_NAME} has no appId, so there is no app to add this client to. ` +
+            `Set one with \`primitive env add <name> --api-url <url> --app-id <appId>\`, or select an environment that has one with \`primitive env use <name>\`.`);
+    }
+    // Naming an app explicitly is allowed only when it is the SAME app: a
+    // different one would wire this client to a backend the rest of the repo does
+    // not target.
+    const named = input.flagAppId ?? (input.action === "use-existing" ? input.configAppId : undefined);
+    if (named && named !== input.environmentAppId) {
+        const source = input.flagAppId ? "--use-existing-app-id" : '`app_id` (action = "use-existing")';
+        return (`${source} names app ${named}, but the "${envName}" environment of the project at ${root} targets app ${input.environmentAppId}. ` +
+            `A client added to this repository belongs to that app — drop the app id and use action = "add-client", ` +
+            `or run init outside this project to scaffold a separate app.`);
+    }
+    return null;
+}
+//# sourceMappingURL=init-plan.js.map

package/dist/src/lib/init-plan.js.map

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

package/dist/src/lib/init-production-env.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Which backend a scaffolded client's PRODUCTION build talks to (#2890).
+ *
+ * `init` used to write the hosted production URL into `.env.production`
+ * unconditionally, alongside the app ID of the app it had just created. On the
+ * hosted server those agree. On any other one — a self-hosted server, a staging
+ * server, an alpha channel — they do not: the production build points at a
+ * backend the app ID does not exist on, and the mismatch only shows up after a
+ * deploy.
+ *
+ * So a composed run derives the pair from the project's own environments
+ * instead, and only falls back to the old behavior where it was right anyway:
+ *
+ *   1. a `prod` environment, then a `production` one — the team already said
+ *      which backend/app pair production means
+ *   2. otherwise, when this run targets the hosted production server, the
+ *      hosted production URL with this app (today's output)
+ *   3. otherwise the selected environment's own server and app — one backend,
+ *      one app, consistently
+ *
+ * Standalone runs keep calling the old path verbatim, so a single-client
+ * scaffold's output is unchanged (spec decision 1).
+ */
+export interface ProductionRuntime {
+    serverUrl: string;
+    appId: string;
+    appName?: string;
+    /** Which rule chose it, for the message init prints. */
+    source: "environment" | "hosted-production" | "selected";
+    /** The environment name, when one was used. */
+    environmentName?: string;
+}
+export interface ResolveProductionRuntimeInput {
+    /** The project's environments, keyed by name. */
+    environments?: Record<string, {
+        apiUrl?: string;
+        appId?: string;
+        appName?: string;
+    } | undefined>;
+    /** The server this run targets. */
+    selectedServerUrl: string;
+    /** The app this run scaffolds against. */
+    selectedAppId: string;
+    selectedAppName?: string;
+    /** The hosted production server URL. */
+    productionServerUrl: string;
+}
+export declare function resolveProductionRuntime(input: ResolveProductionRuntimeInput): ProductionRuntime;

package/dist/src/lib/init-production-env.js

@@ -0,0 +1,59 @@
+/**
+ * Which backend a scaffolded client's PRODUCTION build talks to (#2890).
+ *
+ * `init` used to write the hosted production URL into `.env.production`
+ * unconditionally, alongside the app ID of the app it had just created. On the
+ * hosted server those agree. On any other one — a self-hosted server, a staging
+ * server, an alpha channel — they do not: the production build points at a
+ * backend the app ID does not exist on, and the mismatch only shows up after a
+ * deploy.
+ *
+ * So a composed run derives the pair from the project's own environments
+ * instead, and only falls back to the old behavior where it was right anyway:
+ *
+ *   1. a `prod` environment, then a `production` one — the team already said
+ *      which backend/app pair production means
+ *   2. otherwise, when this run targets the hosted production server, the
+ *      hosted production URL with this app (today's output)
+ *   3. otherwise the selected environment's own server and app — one backend,
+ *      one app, consistently
+ *
+ * Standalone runs keep calling the old path verbatim, so a single-client
+ * scaffold's output is unchanged (spec decision 1).
+ */
+/** Trailing-slash-insensitive comparison, as elsewhere in init. */
+function sameServer(a, b) {
+    return a.replace(/\/+$/, "") === b.replace(/\/+$/, "");
+}
+export function resolveProductionRuntime(input) {
+    const environments = input.environments ?? {};
+    // `prod` first, deliberately: a repo with both names has one of them as the
+    // real one, and `prod` is what `primitive init` and the templates use.
+    for (const name of ["prod", "production"]) {
+        const env = environments[name];
+        if (env?.apiUrl && env?.appId) {
+            return {
+                serverUrl: env.apiUrl,
+                appId: env.appId,
+                appName: env.appName ?? input.selectedAppName,
+                source: "environment",
+                environmentName: name,
+            };
+        }
+    }
+    if (sameServer(input.selectedServerUrl, input.productionServerUrl)) {
+        return {
+            serverUrl: input.productionServerUrl,
+            appId: input.selectedAppId,
+            appName: input.selectedAppName,
+            source: "hosted-production",
+        };
+    }
+    return {
+        serverUrl: input.selectedServerUrl,
+        appId: input.selectedAppId,
+        appName: input.selectedAppName,
+        source: "selected",
+    };
+}
+//# sourceMappingURL=init-production-env.js.map

package/dist/src/lib/init-production-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init-production-env.js","sourceRoot":"","sources":["../../../src/lib/init-production-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AA2BH,mEAAmE;AACnE,SAAS,UAAU,CAAC,CAAS,EAAE,CAAS;IACtC,OAAO,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,KAAoC;IAEpC,MAAM,YAAY,GAAG,KAAK,CAAC,YAAY,IAAI,EAAE,CAAC;IAC9C,4EAA4E;IAC5E,uEAAuE;IACvE,KAAK,MAAM,IAAI,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,EAAE,CAAC;QAC1C,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,GAAG,EAAE,MAAM,IAAI,GAAG,EAAE,KAAK,EAAE,CAAC;YAC9B,OAAO;gBACL,SAAS,EAAE,GAAG,CAAC,MAAM;gBACrB,KAAK,EAAE,GAAG,CAAC,KAAK;gBAChB,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,KAAK,CAAC,eAAe;gBAC7C,MAAM,EAAE,aAAa;gBACrB,eAAe,EAAE,IAAI;aACtB,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,UAAU,CAAC,KAAK,CAAC,iBAAiB,EAAE,KAAK,CAAC,mBAAmB,CAAC,EAAE,CAAC;QACnE,OAAO;YACL,SAAS,EAAE,KAAK,CAAC,mBAAmB;YACpC,KAAK,EAAE,KAAK,CAAC,aAAa;YAC1B,OAAO,EAAE,KAAK,CAAC,eAAe;YAC9B,MAAM,EAAE,mBAAmB;SAC5B,CAAC;IACJ,CAAC;IAED,OAAO;QACL,SAAS,EAAE,KAAK,CAAC,iBAAiB;QAClC,KAAK,EAAE,KAAK,CAAC,aAAa;QAC1B,OAAO,EAAE,KAAK,CAAC,eAAe;QAC9B,MAAM,EAAE,UAAU;KACnB,CAAC;AACJ,CAAC"}