primitive-admin 1.0.62 → 1.0.64

package/dist/src/commands/init.js

@@ -1,18 +1,21 @@
 import { checkbox, confirm, input, select } from "@inquirer/prompts";
 import { appendFileSync, existsSync, readFileSync, readdirSync, writeFileSync, } from "fs";
 import { basename, join, relative, resolve } from "path";
-import { CURRENT_CONFIG_VERSION, PROJECT_CONFIG_DIR, PROJECT_CONFIG_FILENAME, PROJECT_CONFIG_DISPLAY_NAME, findProjectRoot, saveProjectConfig, loadProjectConfigFromPath, } from "../lib/project-config.js";
+import { CURRENT_CONFIG_VERSION, PROJECT_TREE_DIR, PROJECT_CONFIG_FILENAME, PROJECT_CONFIG_DISPLAY_NAME, findProjectRoot, saveProjectConfig, loadProjectConfigFromPath, } from "../lib/project-config.js";
 import { resolveAdoptedEnvironment } from "../lib/init-adopt.js";
 import { CANONICAL_SCHEMA_HEADER, FALLBACK_STARTER_SCHEMA, platformLabel, rootAgentsMarkdown, } from "../lib/init-assets.js";
 import { checkInitGuards, planInit } from "../lib/init-plan.js";
 import { resolveProductionRuntime } from "../lib/init-production-env.js";
 import { checkClientWiring, composeSchemaContent, declaredModelNames, findClientSchema, wireClientToSchema, writeCanonicalSchema, } from "../lib/init-schema.js";
 import { declareSharedProjectConfig } from "../lib/init-xcode.js";
-import { deriveCallbackScheme, linkOptInGuidance, missingUrlTypeGuidance, stampCallbackScheme, } from "../lib/init-ios-links.js";
+import { deriveCallbackScheme, linkOptInGuidance, missingUrlTypeGuidance, stampCallbackScheme, universalLinkGuidance, } from "../lib/init-ios-links.js";
+import { appHasBothPlatforms, detectClientPlatform, discoverClientPlatforms, } from "../lib/init-client-platforms.js";
+import { planEmailRedirectUriMerge } from "../lib/init-email-redirect-uris.js";
 import { getExplicitEnvName } from "../lib/env-resolver.js";
 import { ApiClient } from "../lib/api-client.js";
 import { browserLogin } from "../lib/auth-flow.js";
-import { loadCredentials, setCurrentApp } from "../lib/config.js";
+import { loadCredentials } from "../lib/config.js";
+import { allowGlobalCredentials } from "../lib/credentials-store.js";
 import { isProjectMode, seedCredentialsForEnvInProject, } from "../lib/credentials-store.js";
 import { getCurrentEnvironment, getProjectConfig } from "../lib/env-resolver.js";
 import { normalizeServerUrl } from "../lib/channel.js";
@@ -26,30 +29,86 @@ import { divider, error, info, keyValue, success, warn, } from "../lib/output.js
 import { installCommand, PRIMITIVE_CLI_PACKAGE } from "../lib/package-manager.js";
 import { gitInitialCommit, gitInitRepo, installPnpmGlobally, installPrimitiveCli, isDirectoryEmpty, isPnpmInstalled, isPortFree, isPrimitiveCliInstalled, isXcodeInstalled, iosTemplateUrl, vueTemplateUrl, resolveTemplateBranch, prepareTemplate, runPnpmInstall, runSwiftPackageResolve, updateEnvFile, updateEnvPort, configurePrimitiveJson, updateViteConfig, } from "../lib/template.js";
 /**
- * The .gitignore lines `init` writes for Primitive CLI local state.
+ * The origin a local dev server is served from. ONE spelling: the app's CORS
+ * origins, its `emailRedirectUris` seed and the environment's `webUrl` all
+ * name this, and a second spelling would be a 400 on the scaffolded app's
+ * first sign-in (#2982).
+ */
+export function localDevOrigin(port) {
+    return `http://localhost:${port}`;
+}
+/**
+ * Point an existing environment at the app's web counterpart.
  *
- * Pre-pull sync snapshots (issue #578) are per-machine local recovery state and
- * must never be committed. They can land in three places depending on how the
- * sync dir resolves (see `resolveSnapshotsRoot` in `lib/sync-paths.ts`):
- *   - project mode:        `<projectRoot>/.primitive/sync-backups/<env>/<appId>/`
- *   - legacy `--dir <p>`:  `<p>/.snapshots/`        (sibling of the user dir)
- *   - no-project fallback: `./config-snapshots/`
- * The bare `.snapshots/` and `config-snapshots/` entries (no leading slash)
- * match those directories wherever `--dir` points, so backup copies — including
- * the restored `.primitive-sync.json` baseline — can never surface as untracked
- * files in a tracked custom config dir.
+ * Returns false — and writes nothing — when there is no config to write, the
+ * environment is not in it, or the file cannot be read: an adopting run does
+ * not own the project config, and a seed is never worth failing an init over.
  */
-export const GITIGNORE_LOCAL_STATE_ENTRIES = [
-    ".primitive/credentials.json",
-    // This machine's Primitive environment selection (`primitive env use`).
-    // The committed `defaultEnvironment` is the team default; the selection is
-    // per-machine and must never be committable (#2873).
-    ".primitive/local.json",
-    ".primitive/sync/**/.primitive-sync.json",
-    ".primitive/sync-backups/",
-    ".snapshots/",
-    "config-snapshots/",
-];
+export function seedEnvironmentWebUrl(projectRoot, environment, webUrl) {
+    const configPath = join(projectRoot, PROJECT_TREE_DIR, PROJECT_CONFIG_FILENAME);
+    if (!existsSync(configPath))
+        return false;
+    let config;
+    try {
+        config = loadProjectConfigFromPath(configPath);
+    }
+    catch {
+        return false;
+    }
+    const entry = config.environments[environment];
+    if (!entry)
+        return false;
+    if (entry.webUrl === webUrl)
+        return true;
+    entry.webUrl = webUrl;
+    saveProjectConfig(configPath, config);
+    return true;
+}
+/**
+ * Make sure this app allows the dev sign-in callback, so pointing the
+ * environment at the web client cannot break email sign-in (#2982).
+ *
+ * Returns true when the callback is on the app's `emailRedirectUris` — already
+ * there, or merged in here. Returns false when it is not and this run must not
+ * put it there: no credentials to ask the server with, an app whose allow-list
+ * would be NARROWED by writing one (see `planEmailRedirectUriMerge`), or an API
+ * call that failed. A false answer costs nothing but the automatic seed: the
+ * caller prints the manual step instead, and the app keeps working code-only.
+ */
+async function devCallbackIsAllowListed(appId, callbackUri, credentials) {
+    if (!credentials)
+        return false;
+    try {
+        const apiClient = new ApiClient();
+        const settings = await apiClient.getAppSettings(appId);
+        const plan = planEmailRedirectUriMerge(settings?.emailRedirectUris, callbackUri);
+        if (plan.action === "already-listed")
+            return true;
+        if (plan.action === "leave-alone") {
+            warn(`Not touching this app's sign-in link allow-list: ${plan.reason}.`);
+            return false;
+        }
+        await apiClient.updateAppSettings(appId, { emailRedirectUris: plan.uris });
+        success(`Allow-listed the dev sign-in link: ${callbackUri}`);
+        return true;
+    }
+    catch (err) {
+        warn(`Could not check this app's sign-in link allow-list: ${err.message}`);
+        return false;
+    }
+}
+/**
+ * The .gitignore lines `init` writes for Primitive CLI local state — one line,
+ * with no per-file exception (#3153, intent criterion 2).
+ *
+ * That is the whole point of the move: `primitive/` is committed (the config
+ * and every environment's TOML, including the shared `.sync-state.json`
+ * baseline) and `.primitive/` is machine-local (credentials, this machine's
+ * `primitive env use` selection, pre-pull snapshot backups). Before the move
+ * one directory meant both things, so the list needed six entries and a
+ * comment explaining which files inside it were committed anyway.
+ */
+export const GITIGNORE_LOCAL_STATE_ENTRIES = [".primitive/"];
 /**
  * Ensures the project root's .gitignore lists the Primitive CLI's local state.
  *
@@ -58,47 +117,19 @@ export const GITIGNORE_LOCAL_STATE_ENTRIES = [
  * per-machine state a new client's environment produces cannot be committed.
  */
 export function ensureGitignoreLocalState(targetDir) {
-    // Ensure .primitive/ local state (credentials, per-machine sync state) is
-    // gitignored. The config.json itself lives in .primitive/ too, but we
-    // gitignore only the sensitive / per-machine artifacts — config.json and
-    // the exported TOML files under .primitive/sync/<env>/<appId>/ are meant
-    // to be committed. Only `.primitive-sync.json` (the auto-managed sync
-    // state baseline) is per-machine local state; everything else in the
-    // sync directory is the version-controllable export.
-    //
-    // Legacy note: an earlier version of init wrote `.primitive/sync/` here,
-    // which incorrectly hid the TOML export tree from `git status`. If we see
-    // that legacy entry, replace it with the targeted pattern in-place so
-    // users who re-run init pick up the fix.
+    // One rule: `.primitive/` is machine-local and never committed, `primitive/`
+    // is the committed tree. Narrower `.primitive/...` entries left over from an
+    // older init are harmless subsets of this line, so they are left alone — the
+    // migration document owns tidying an adopted project's .gitignore.
     const gitignorePath = join(targetDir, ".gitignore");
-    const LEGACY_SYNC_IGNORE = ".primitive/sync/";
     const gitignoreEntries = [...GITIGNORE_LOCAL_STATE_ENTRIES];
     let linesToAdd = [];
     if (existsSync(gitignorePath)) {
-        const existing = readFileSync(gitignorePath, "utf-8");
-        const trimmedLines = existing.split(/\r?\n/).map((l) => l.trim());
-        // Migrate the legacy `.primitive/sync/` entry to the targeted pattern,
-        // if present. Preserve original line endings/formatting elsewhere.
-        if (trimmedLines.includes(LEGACY_SYNC_IGNORE)) {
-            const rewritten = existing
-                .split(/\r?\n/)
-                .map((line) => line.trim() === LEGACY_SYNC_IGNORE
-                ? ".primitive/sync/**/.primitive-sync.json"
-                : line)
-                .join("\n");
-            try {
-                writeFileSync(gitignorePath, rewritten);
-            }
-            catch {
-                // Non-fatal
-            }
-        }
-        // Re-read after potential migration so we don't double-add entries.
-        const refreshed = readFileSync(gitignorePath, "utf-8")
+        const existing = readFileSync(gitignorePath, "utf-8")
             .split(/\r?\n/)
             .map((l) => l.trim());
         for (const entry of gitignoreEntries) {
-            if (!refreshed.includes(entry)) {
+            if (!existing.includes(entry)) {
                 linesToAdd.push(entry);
             }
         }
@@ -117,13 +148,13 @@ export function ensureGitignoreLocalState(targetDir) {
     }
 }
 /**
- * Writes .primitive/config.json into the project directory and ensures the
+ * Writes primitive/config.json into the project directory and ensures the
  * .gitignore entry for local state exists. Safe to call in a directory that
  * already has a config — in that case we add/update the "dev" environment
  * instead of overwriting the file.
  */
 async function scaffoldProjectConfig(opts) {
-    const configPath = join(opts.targetDir, PROJECT_CONFIG_DIR, PROJECT_CONFIG_FILENAME);
+    const configPath = join(opts.targetDir, PROJECT_TREE_DIR, PROJECT_CONFIG_FILENAME);
     let config;
     if (existsSync(configPath)) {
         // Respect an existing config: merge in the new dev env if missing.
@@ -218,7 +249,7 @@ async function ensureAuthenticated(credentials, serverUrl, serverChanged, contex
  * matches `serverUrl`, so the project-mode "not logged in" remedy can name a
  * real, working environment instead of a placeholder. Comparison uses the
  * same canonicalization as `resolveInitServer` (trailing-slash-insensitive)
- * so `https://host/` in `.primitive/config.json` still matches.
+ * so `https://host/` in `primitive/config.json` still matches.
  */
 function findEnvironmentForServer(serverUrl) {
     const project = getProjectConfig();
@@ -294,9 +325,9 @@ Examples:
 
 One app, several clients:
   Selecting more than one platform scaffolds them side by side under one project:
-  each client in its own directory (web/, ios/), with .primitive/config.json, the
+  each client in its own directory (web/, ios/), with primitive/config.json, the
   git repository and the shared models/models.toml at the root. Run inside a
-  directory that already has an ancestor .primitive/config.json and init ADDS the
+  directory that already has an ancestor primitive/config.json and init ADDS the
   client to that app instead: it reuses the selected environment's app, writes no
   nested .primitive/ or .git/, makes no commit, and leaves the files for you to
   review and commit in the outer repository.
@@ -347,6 +378,11 @@ This command will:
         .action(handleInit);
 }
 async function handleInit(projectDirArg, options) {
+    // `init` is what CREATES a project, so by definition it runs before one
+    // exists — and it has to call the API to do it. One of the four commands
+    // permitted to reach the global credentials file with no project in scope
+    // (#3154, intent criterion 5).
+    allowGlobalCredentials();
     // Validate an explicitly-passed `--platform` flag up front. Only `web` and
     // `ios` are supported (#1009 removed `macos`), and the flag names a LIST —
     // `--platform web,ios` scaffolds both clients of one app (#2890). An omitted
@@ -448,7 +484,7 @@ async function handleInit(projectDirArg, options) {
     const defaultAppName = projectDir === "." ? basename(targetDir) : basename(projectDir);
     // ── Which layout is this run producing? (#2890) ────────────────────────
     //
-    // A `.primitive/config.json` in an ANCESTOR of the target means this app
+    // A `primitive/config.json` in an ANCESTOR of the target means this app
     // already exists and this run adds a client to it. Passing the ancestor only
     // when it differs from the target keeps `primitive init .` at a project root
     // on its existing merge behavior.
@@ -633,7 +669,7 @@ async function handleInit(projectDirArg, options) {
             }
             else {
                 error(`This project has no environment configured for ${serverUrl}. ` +
-                    `Add one (\`primitive env add <name> --api-url ${serverUrl}\`) and ` +
+                    `Add one (\`primitive env add <name> --api-url ${serverUrl} --app-id <app-id>\`) and ` +
                     `re-run with \`-e <name>${serverFlag}\`, or re-run init outside the project directory.`);
             }
         }
@@ -699,6 +735,14 @@ async function handleInit(projectDirArg, options) {
     let credentials = existingCredentials;
     let appId;
     let appName;
+    /**
+     * Whether THIS run created the app. A created app is seeded with
+     * `http://localhost:5173/oauth/callback` in `emailRedirectUris`; an adopted
+     * one carries whatever allow-list it already had, which is why the combined
+     * app's `webUrl` seed asks the server before pointing the sign-in link at a
+     * dev callback (#2982).
+     */
+    let appWasCreatedByThisRun = false;
     const preparedTemplates = new Map();
     const cleanupPreparedTemplate = () => {
         for (const prepared of preparedTemplates.values()) {
@@ -847,6 +891,7 @@ async function handleInit(projectDirArg, options) {
                 throw new Error("App created but no appId returned");
             }
             appId = id;
+            appWasCreatedByThisRun = true;
             success(`App created: ${appName}`);
             keyValue("App ID", appId);
         }
@@ -1024,20 +1069,7 @@ async function handleInit(projectDirArg, options) {
             // Non-fatal: git may not be installed, or already a git repo
         }
     }
-    // Step 4.5: Update CLI to point at this app. Adopting does not: the app is
-    // already the project's, and the CLI's global selection is not this run's to
-    // move.
-    if (plan.ownsApp) {
-        try {
-            setCurrentApp(appId, appName);
-            info(`CLI now using app: ${appName} (${appId})`);
-        }
-        catch (err) {
-            // Not critical - user may not be logged in (e.g. used --use-existing-app-id without login)
-            warn(`Could not set current app in CLI config: ${err.message}`);
-        }
-    }
-    // Step 4.6: Scaffold .primitive/config.json with a "dev" environment bound
+    // Step 4.6: Scaffold primitive/config.json with a "dev" environment bound
     // to this app, and seed its credential slot with the session we just
     // authenticated — so `primitive` commands run from inside the project pick
     // up project mode without a second login.
@@ -1052,10 +1084,10 @@ async function handleInit(projectDirArg, options) {
             if (credentials) {
                 seedCredentialsForEnvInProject(plan.projectRoot, "dev", credentials);
             }
-            success(`Project environment "dev" configured (.primitive/config.json).`);
+            success(`Project environment "dev" configured (primitive/config.json).`);
         }
         catch (err) {
-            warn(`Could not scaffold .primitive/config.json: ${err.message}`);
+            warn(`Could not scaffold primitive/config.json: ${err.message}`);
         }
     }
     else {
@@ -1117,6 +1149,23 @@ async function handleInit(projectDirArg, options) {
      * candidate scheme rather than a registered one.
      */
     const iosCallbackSchemes = [];
+    /**
+     * An app with BOTH clients emails ONE https sign-in link — the web app's
+     * callback, which opens the iOS app where it is installed (#2982). "Both"
+     * counts the clients already in the repository, including one that IS the
+     * project root (the flat single-client layout gaining its second platform).
+     */
+    const combinedApp = appHasBothPlatforms(plan.clients.map((client) => client.platform), discoverClientPlatforms(plan.projectRoot));
+    /** The web dev origin this run settled on, for the environment's `webUrl`. */
+    let webDevOrigin = null;
+    /**
+     * Whether that origin's `/oauth/callback` is known to be on the app's
+     * magic-link allow-list already — because the app was created here with the
+     * default-port seed, or because the dev-port step merged it (#2982). Anything
+     * else has to be asked about before the environment points a sign-in link at
+     * it.
+     */
+    let devCallbackAllowListed = false;
     for (const client of plan.clients) {
         if (client.platform === "ios") {
             // ── Apple (SwiftUI) path ────────────────────────────────────────
@@ -1129,13 +1178,13 @@ async function handleInit(projectDirArg, options) {
             if (resolve(client.dir) !== resolve(plan.projectRoot)) {
                 const declared = declareSharedProjectConfig(client.dir, plan.projectRoot);
                 if (declared.length > 0) {
-                    success(`Xcode build phases read ${relative(client.dir, join(plan.projectRoot, ".primitive", "config.json"))}.`);
+                    success(`Xcode build phases read ${relative(client.dir, join(plan.projectRoot, PROJECT_TREE_DIR, PROJECT_CONFIG_FILENAME))}.`);
                 }
             }
             // Step 5: Generate primitive.json from the environment.
             //
             // In a current template the file is a build product, written by
-            // `scripts/resolve-primitive-config.sh` from `.primitive/config.json`
+            // `scripts/resolve-primitive-config.sh` from `primitive/config.json`
             // (#2873) — it walks up to the project root, so a client inside a
             // composed repository resolves the same one every other command does. A
             // template that predates the change has no such script and a tracked
@@ -1150,7 +1199,7 @@ async function handleInit(projectDirArg, options) {
                     environmentName: adopted?.name,
                 });
                 if (result.outcome === "generated") {
-                    success("primitive.json generated from .primitive/config.json.");
+                    success("primitive.json generated from primitive/config.json.");
                 }
                 else if (result.outcome === "filled") {
                     success("primitive.json configured.");
@@ -1163,7 +1212,7 @@ async function handleInit(projectDirArg, options) {
                     // Neither the resolve script nor a template primitive.json — an
                     // unexpectedly old or trimmed template. The remedy is still never
                     // "type the app ID somewhere else": it is already in
-                    // .primitive/config.json, which is where every reader looks.
+                    // primitive/config.json, which is where every reader looks.
                     warn("This template has neither scripts/resolve-primitive-config.sh nor a primitive.json.");
                     warn(`The project config holds the app ID; update the template to generate primitive.json from it.`);
                 }
@@ -1219,7 +1268,7 @@ async function handleInit(projectDirArg, options) {
         // Step 5: Fill in an OLD template's .env identity keys.
         //
         // A current template does not author them at all — `primitiveEnv()` reads
-        // `.primitive/config.json`, which it finds by walking up — so "no keys to
+        // `primitive/config.json`, which it finds by walking up — so "no keys to
         // replace" is the expected outcome, not a problem (#2873). The fill-in
         // survives only so a new CLI still produces a working scaffold from a
         // template that predates the change.
@@ -1227,7 +1276,7 @@ async function handleInit(projectDirArg, options) {
         try {
             const envResult = updateEnvFile(client.dir, appId, serverUrl, appName, production);
             if (!envResult.envUpdated) {
-                info("No .env file in this template — identity comes from .primitive/config.json.");
+                info("No .env file in this template — identity comes from primitive/config.json.");
             }
             else {
                 success("Environment configured.");
@@ -1243,7 +1292,7 @@ async function handleInit(projectDirArg, options) {
         // ERR_USE_AFTER_CLOSE into the catch below (#2720).
         try {
             const defaultPort = DEFAULT_DEV_PORT;
-            const defaultOrigin = `http://localhost:${defaultPort}`;
+            const defaultOrigin = localDevOrigin(defaultPort);
             const resolvedPort = await resolveDevPort({
                 configPort: initConfig?.dev_port,
                 hasConfig: initConfig != null,
@@ -1271,11 +1320,18 @@ async function handleInit(projectDirArg, options) {
                 },
             });
             const chosenPort = resolvedPort.port;
+            // The same origin the app's CORS list and `emailRedirectUris` are seeded
+            // with, so a combined app's first sign-in link is already allow-listed.
+            webDevOrigin = localDevOrigin(chosenPort);
+            // …but only for an app this run created: that seed happens at creation.
+            // An adopted app on the default port has been through neither the seed
+            // nor the port step below, so nothing here can vouch for its allow-list.
+            devCallbackAllowListed = appWasCreatedByThisRun && chosenPort === defaultPort;
             if (resolvedPort.source === "config") {
                 info(`Dev server port: ${chosenPort} (from config)`);
             }
             if (chosenPort !== defaultPort) {
-                const devOrigin = `http://localhost:${chosenPort}`;
+                const devOrigin = localDevOrigin(chosenPort);
                 // Pin the port in vite.config.ts and update .env. A vite config whose
                 // shape we can't patch must be said out loud — otherwise the dev
                 // server keeps 5173 while .env and the redirect URIs point elsewhere.
@@ -1351,6 +1407,9 @@ async function handleInit(projectDirArg, options) {
                             };
                         }
                         await apiClient.updateAppSettings(appId, settingsUpdate);
+                        // This merge is what puts the chosen port's callback on the
+                        // allow-list, whoever created the app (#2982).
+                        devCallbackAllowListed = true;
                         success(`Dev port set to ${chosenPort}: ${viteUpdated ? "vite.config.ts, " : ""}.env, CORS, redirect URIs, and base URL updated.`);
                     }
                     catch (err) {
@@ -1448,6 +1507,32 @@ async function handleInit(projectDirArg, options) {
             }
         }
     }
+    // The combined app's dev sign-in link (#2982): the environment learns the
+    // web origin this run settled on, so the iOS client's emailed link opens the
+    // local web app instead of a scheme that is dead in the Simulator. Only when
+    // this run owns the project config — an adopting run gets the guidance and
+    // decides for itself.
+    //
+    // And only once the app actually allows that callback. Setting `webUrl` is
+    // what turns a code-only email into a link, and a link the server refuses is
+    // a 400 on every sign-in request — strictly worse than the code-only default
+    // this app has today. An app created here was seeded with the callback; an
+    // adopted one is asked about, and when the answer is no or unavailable the
+    // seed is skipped in favour of printing the step.
+    let seededWebOrigin = null;
+    let unverifiedDevCallback = null;
+    if (combinedApp && plan.writesProjectConfig && webDevOrigin) {
+        const devCallback = `${webDevOrigin}/oauth/callback`;
+        const allowed = devCallbackAllowListed ||
+            (await devCallbackIsAllowListed(appId, devCallback, credentials));
+        if (allowed && seedEnvironmentWebUrl(plan.projectRoot, "dev", webDevOrigin)) {
+            seededWebOrigin = webDevOrigin;
+            success(`Environment "dev" points at the web client: webUrl ${webDevOrigin}`);
+        }
+        else if (!allowed) {
+            unverifiedDevCallback = devCallback;
+        }
+    }
     // Step 10: Offer to install Claude Code skill if not already installed
     try {
         const { isSkillInstalled, installSkillExplicit, checkSkillStatus } = await import("../lib/skill-installer.js");
@@ -1505,12 +1590,25 @@ async function handleInit(projectDirArg, options) {
     }
     divider();
     // Email sign-in already works for the scaffolded app — code-only, no app
-    // settings — so this is an opt-in, not a step (#2969).
-    for (const { scheme, registered } of iosCallbackSchemes) {
-        for (const line of linkOptInGuidance(scheme, { registered }))
+    // settings — so this is an opt-in, not a step (#2969). An app with both
+    // clients gets the https link instead, which needs a different checklist
+    // (#2982).
+    if (combinedApp) {
+        for (const line of universalLinkGuidance({
+            webOrigin: seededWebOrigin ?? undefined,
+            unverifiedDevCallback: unverifiedDevCallback ?? undefined,
+        })) {
             info(line);
+        }
         divider();
     }
+    else {
+        for (const { scheme, registered } of iosCallbackSchemes) {
+            for (const line of linkOptInGuidance(scheme, { registered }))
+                info(line);
+            divider();
+        }
+    }
     if (plan.mode === "add-client") {
         info(`No .primitive/ and no .git/ were created inside the new client — this app has one of each, at ${plan.projectRoot}.`);
         info(`The new files are uncommitted: review them with \`git status\` in ${plan.projectRoot} and commit when you are happy.`);
@@ -1550,7 +1648,7 @@ async function handleInit(projectDirArg, options) {
 }
 /** Where a project root's environments live, for the production derivation. */
 function readProjectEnvironments(projectRoot) {
-    const configPath = join(projectRoot, PROJECT_CONFIG_DIR, PROJECT_CONFIG_FILENAME);
+    const configPath = join(projectRoot, PROJECT_TREE_DIR, PROJECT_CONFIG_FILENAME);
     if (!existsSync(configPath))
         return undefined;
     try {
@@ -1581,22 +1679,12 @@ function discoverExistingClients(projectRoot) {
     for (const entry of entries) {
         if (!entry.isDirectory() || entry.name.startsWith("."))
             continue;
-        const dir = join(projectRoot, entry.name);
-        const hasXcodeProject = (() => {
-            try {
-                return readdirSync(dir).some((name) => name.endsWith(".xcodeproj"));
-            }
-            catch {
-                return false;
-            }
-        })();
-        if (existsSync(join(dir, "Package.swift")) || hasXcodeProject) {
-            found.push({ platform: "ios", dir: entry.name });
-        }
-        else if (existsSync(join(dir, "package.json")) &&
-            existsSync(join(dir, "vite.config.ts"))) {
-            found.push({ platform: "web", dir: entry.name });
-        }
+        // The same template signals the both-platforms predicate reads, so the
+        // layout description and the universal-link wiring cannot disagree about
+        // what counts as a client.
+        const platform = detectClientPlatform(join(projectRoot, entry.name));
+        if (platform)
+            found.push({ platform, dir: entry.name });
     }
     return found;
 }