@namiml/cli 3.4.11-dev.202609230009 → 3.4.11-dev.202609230307

package/dist/commands/configure.js

@@ -1,5 +1,6 @@
 import { configureSdk } from "../sdk/configure.js";
 import { SDK_DISABLED_MESSAGE, VerifyError, verifyAppPlatform } from "../sdk/verify.js";
+import { configureSummaryLines } from "../sdk/summary.js";
 /** `nami configure --app-platform-id <uuid>` — headless verify + configure. Returns the exit code. */
 export async function configure(opts, ctx, deps = {}) {
     const verify = deps.verify ?? verifyAppPlatform;
@@ -27,8 +28,8 @@ export async function configure(opts, ctx, deps = {}) {
         ctx.out(JSON.stringify(result, null, 2));
     }
     else {
-        ctx.out(`Configured ${result.appPlatformId} on ${result.host}: ${result.configureState}${result.sdkEnabled ? "" : " (SDK disabled)"}${result.device ? ` · ${result.device.displayName}` : ""}`);
-        ctx.out(`placements ${result.counts.placements} · products ${result.counts.products} · paywalls ${result.counts.paywalls}${result.deviceId ? ` · device ${result.deviceId}` : ""}`);
+        for (const line of configureSummaryLines(result))
+            ctx.out(line);
     }
     return result.sdkInitialized ? 0 : 1;
 }

package/dist/commands/onboarding.js

@@ -1,10 +1,20 @@
-/** `nami onboarding [--reset]` — show or reset the onboarding state. Tokens are never touched. */
-export async function onboarding(opts, ctx) {
+import { runOnboarding } from "../onboarding/run.js";
+/** The flags that switch `nami onboarding` from a status print to a headless run (`--host` is global, so it does not). */
+const HEADLESS_FLAGS = ["org", "app", "platform", "appPlatformId", "fromSdkconfig", "device", "yes", "json"];
+const isHeadless = (opts) => HEADLESS_FLAGS.some((flag) => opts[flag] !== undefined);
+/**
+ * `nami onboarding` — show the onboarding state, `--reset` it, or run the whole
+ * thing headlessly when any of the named flags is passed (see `runOnboarding`).
+ * Tokens are never touched.
+ */
+export async function onboarding(opts, ctx, deps = {}) {
     if (opts.reset) {
         await ctx.config.resetOnboarding();
         ctx.out("Onboarding reset — run nami to pick an app and platform again. Your sign-in was kept (nami logout removes it).");
         return 0;
     }
+    if (isHeadless(opts))
+        return runOnboarding(opts, ctx, deps);
     const { config } = await ctx.config.load();
     ctx.out(`Onboarding step: ${config.onboarding.step}${config.onboarding.completedAt ? ` (completed ${config.onboarding.completedAt})` : ""}`);
     if (config.onboarding.step !== "done")

package/dist/config/sdkconfig.js

@@ -0,0 +1,69 @@
+import { readFile } from "node:fs/promises";
+/**
+ * `nami_host` → the CLI's host, or `null` when this CLI cannot express it.
+ *
+ * Derived from `sdkconfig.schema.json` at the repo root
+ * (`$defs.connection.nami_host.x-ui-host-urls`): staging is
+ * `https://app-staging.namiml.com` and uspod1 is `https://app.namiml.com`, which are
+ * exactly the two `CONTROL_CENTER_HOSTS`. The rest point at base URLs a
+ * `ResolvedHost` has no name for, so they map to `null` rather than widening it.
+ */
+export const SDKCONFIG_HOSTS = {
+    staging: "staging",
+    uspod1: "production",
+    uspod2: null,
+    localhost: null,
+    synchronoss: null,
+    custom: null,
+};
+/** The schema's own default for `nami_host`. */
+const DEFAULT_SDKCONFIG_HOST = "staging";
+export class SdkConfigError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "SdkConfigError";
+    }
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const trimmed = (value) => (typeof value === "string" ? value.trim() : "");
+/**
+ * Read the `connection` block of a test app's `sdkconfig.json`. Every failure is an
+ * `SdkConfigError` whose message names the file and one thing to do next — the caller
+ * renders it verbatim.
+ */
+export function parseSdkConfig(text, path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new SdkConfigError("unreadable", `${path} is not valid JSON. Fix the file, or paste the App Platform ID instead.`);
+    }
+    const connection = isRecord(parsed) ? parsed.connection : undefined;
+    if (!isRecord(connection)) {
+        throw new SdkConfigError("no_connection", `${path} has no "connection" block, so there is no App Platform ID to read. Point at the test app's sdkconfig.json, or paste the App Platform ID instead.`);
+    }
+    const appPlatformId = trimmed(connection.custom_app_platform_id) || trimmed(connection.app_platform_id);
+    if (!appPlatformId) {
+        throw new SdkConfigError("no_id", `The "connection" block in ${path} has no app_platform_id. Pick an app platform in the test app's settings and save, or paste the App Platform ID instead.`);
+    }
+    const namiHost = trimmed(connection.nami_host) || DEFAULT_SDKCONFIG_HOST;
+    const host = SDKCONFIG_HOSTS[namiHost] ?? null;
+    if (!host) {
+        throw new SdkConfigError("unsupported_host", `${path} is set to the "${namiHost}" host; this CLI only talks to production and staging. Switch the test app to staging or uspod1 (production), or paste an App Platform ID on one of those hosts.`);
+    }
+    return { appPlatformId, host };
+}
+/** `parseSdkConfig` over a file; an unreadable path is an `unreadable` error, never a throw from fs. */
+export async function readSdkConfig(path) {
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch {
+        throw new SdkConfigError("unreadable", `Could not read ${path}. Check the path to the test app's sdkconfig.json, or paste the App Platform ID instead.`);
+    }
+    return parseSdkConfig(text, path);
+}

package/dist/onboarding/run.js

@@ -0,0 +1,146 @@
+import { AuthError } from "../auth/errors.js";
+import { appFrom, platformFrom, selectionFrom } from "../config/selection.js";
+import { readSdkConfig, SdkConfigError } from "../config/sdkconfig.js";
+import { listApps } from "../control-center/apps.js";
+import { findAppPlatformById, pastedStandIn } from "../control-center/lookup.js";
+import { configureSummaryLines } from "../sdk/summary.js";
+import { listPlatforms } from "../control-center/platforms.js";
+import { findApp, findPlatform, resolve, ResolveError } from "../control-center/resolve.js";
+import { resolveDevice, toSelection } from "../devices/presets.js";
+import { resolveHost } from "../hosts.js";
+import { configureSdk } from "../sdk/configure.js";
+import { SDK_DISABLED_MESSAGE, VerifyError, verifyAppPlatform } from "../sdk/verify.js";
+const NOT_SIGNED_IN = "Not signed in. Run `nami login` first.";
+const NO_APP_PLATFORM = "No app platform to configure. Pass --app-platform-id <uuid>, or --from-sdkconfig <path>, or --app with --platform.";
+const SDK_DISABLED_NEEDS_YES = "Pass --yes to configure against it anyway.";
+/**
+ * Run the onboarding steps with no TTY: resolve an app platform from named
+ * flags, configure the SDK against it and record it as the current selection.
+ *
+ * Every step is a flag, never a prompt — a missing one exits 2 naming the flag
+ * that would supply it, so a script (or a Claude Code skill) never blocks on a
+ * question it cannot answer. Auth is whatever `AuthSession` already has:
+ * `NAMI_TOKEN` in CI, the stored sign-in otherwise. There is deliberately no
+ * credential flag or env var (NAM-4487).
+ *
+ * Returns the process exit code.
+ */
+export async function runOnboarding(input, ctx, deps = {}) {
+    const verify = deps.verify ?? verifyAppPlatform;
+    const run = deps.configure ?? configureSdk;
+    const doListApps = deps.listApps ?? listApps;
+    const doListPlatforms = deps.listPlatforms ?? listPlatforms;
+    const doReadSdkConfig = deps.readSdkConfig ?? readSdkConfig;
+    let host = ctx.host;
+    let appPlatformId = input.appPlatformId;
+    try {
+        if (input.fromSdkconfig) {
+            // The file is the fallback for both: an explicit flag on the command line wins.
+            const connection = await doReadSdkConfig(input.fromSdkconfig);
+            appPlatformId ??= connection.appPlatformId;
+            if (!input.host)
+                host = resolveHost(connection.host);
+        }
+        if (input.org) {
+            const stored = await ctx.store.load();
+            if (!stored) {
+                ctx.err(NOT_SIGNED_IN);
+                return 1;
+            }
+            const profile = await ctx.auth.fetchAccount(stored.accessToken);
+            const org = resolve(profile.orgs, input.org, "organization");
+            const accessToken = await ctx.auth.selectOrg(stored.refreshToken, org.id);
+            const next = { ...stored, accessToken, orgId: org.id, orgName: org.name, savedAt: new Date().toISOString() };
+            await ctx.store.save(next);
+            await ctx.config.setSession({ orgId: org.id, orgName: org.name });
+        }
+        let app;
+        let platform;
+        let verified;
+        if (appPlatformId) {
+            verified = await verify(host.baseUrl, appPlatformId, globalThis.fetch);
+            // The id is verified on a public endpoint; naming it needs a session, so a
+            // failed lookup degrades to the stand-ins instead of refusing a valid id.
+            const named = (await findAppPlatformById(ctx.session, appPlatformId, { listApps: doListApps, listPlatforms: doListPlatforms })) ?? pastedStandIn(appPlatformId);
+            app = named.app;
+            platform = named.platform;
+        }
+        else if (input.app) {
+            app = findApp(await doListApps(ctx.session), input.app);
+            const platforms = await doListPlatforms(ctx.session, app.id);
+            if (input.platform) {
+                platform = findPlatform(platforms, input.platform);
+            }
+            else if (platforms.length === 1) {
+                platform = platforms[0];
+            }
+            else if (platforms.length === 0) {
+                ctx.err(`"${app.name}" has no platforms yet. Add one in the Control Center (${host.baseUrl}), then run nami onboarding again.`);
+                return 2;
+            }
+            else {
+                ctx.err(`"${app.name}" has more than one platform: ${platforms.map((p) => p.name).join(", ")}. Pass --platform too.`);
+                return 2;
+            }
+        }
+        else {
+            // --platform or --device alone target whatever `nami` last configured, the
+            // same way `nami use` does — keep the two surfaces in step.
+            const { config } = await ctx.config.load();
+            if (config.current && (input.platform || input.device)) {
+                app = appFrom(config.current);
+                platform = input.platform ? findPlatform(await doListPlatforms(ctx.session, app.id), input.platform) : platformFrom(config.current);
+            }
+        }
+        if (!app || !platform) {
+            ctx.err(NO_APP_PLATFORM);
+            return 2;
+        }
+        verified ??= await verify(host.baseUrl, platform.id, globalThis.fetch);
+        if (verified.kind === "sdk_disabled") {
+            ctx.err(SDK_DISABLED_MESSAGE);
+            // The interactive flow asks before continuing here; headless, --yes is that answer.
+            if (!input.yes) {
+                ctx.err(SDK_DISABLED_NEEDS_YES);
+                return 2;
+            }
+        }
+        let device = null;
+        if (input.device)
+            device = toSelection(resolveDevice(platform.type, input.device));
+        const result = await run({ host, appPlatformId: platform.id, device: { platformType: platform.type, id: input.device } }, { verified });
+        await ctx.config.setCurrent(selectionFrom(app, platform, device ?? result.device), { host: host.name });
+        await ctx.config.markOnboardingDone();
+        report(result, input, ctx);
+        return result.sdkInitialized ? 0 : 1;
+    }
+    catch (error) {
+        if (error instanceof SdkConfigError) {
+            // The message already names the file and one thing to do next.
+            ctx.err(error.message);
+            return 2;
+        }
+        if (error instanceof ResolveError) {
+            ctx.err(error.message);
+            return 2;
+        }
+        if (error instanceof VerifyError) {
+            ctx.err(error.message);
+            return error.code === "invalid_id" ? 2 : 1;
+        }
+        if (error instanceof AuthError) {
+            ctx.err(error.message);
+            return 1;
+        }
+        throw error;
+    }
+}
+/** The same two lines `nami configure` prints, or the raw result under --json. */
+function report(result, input, ctx) {
+    if (input.json) {
+        ctx.out(JSON.stringify(result, null, 2));
+        return;
+    }
+    for (const line of configureSummaryLines(result))
+        ctx.out(line);
+}

package/dist/program.js

@@ -110,9 +110,17 @@ export function createProgram(h, options = {}) {
     });
     program
         .command("onboarding")
-        .description("Show the onboarding step, or start over with --reset (keeps your sign-in).")
+        .description("Show the onboarding step, start over with --reset, or onboard headlessly with the flags below.")
         .option(HOST_FLAG, HOST_HELP)
         .option("--reset", "forget the current selection, recent list and onboarding progress")
+        .option("--org <id-or-name>", "organization to onboard into (re-scopes the access token)")
+        .option("--app <id-or-name>", "app id, exact name, or unique substring")
+        .option("--platform <id-or-name>", "platform id, exact name, or unique substring")
+        .option("--app-platform-id <uuid>", "onboard straight onto an App Platform ID")
+        .option("--from-sdkconfig <path>", "read the App Platform ID and host from a test app's sdkconfig.json")
+        .option("--device <id-or-name>", "target device preset, previewer id or name")
+        .option("-y, --yes", "answer yes to anything the interactive run would ask (e.g. an SDK-disabled platform)")
+        .option("--json", "machine-readable result")
         .action(async (_opts, cmd) => {
         process.exitCode = await h.onboarding(cmd.optsWithGlobals());
     });

package/dist/screens/LoginFlow.js

@@ -56,7 +56,7 @@ export function LoginFlow({ auth, store, host, totpCode, org, onDone, onFail, ex
             return void finish(signedIn, match);
         }
         if (orgs.length === 0)
-            return fail(new AuthError("org_forbidden", "Your account does not belong to any organization yet."));
+            return fail(new AuthError("org_forbidden", `Your account does not belong to any organization yet. Ask an organization admin to invite you, or create one at ${host.baseUrl}.`));
         if (orgs.length === 1)
             return void finish(signedIn, orgs[0]);
         setStep({ kind: "org", signedIn });

package/dist/screens/NewToNami.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { Box, Text, useInput } from "ink";
+import { openUrl as openUrlInBrowser } from "../utils/open-url.js";
+const STEPS = [
+    "Create an account in the Control Center",
+    "Create an app",
+    "Add a platform to it (Apple, Google, Amazon, Roku, Web)",
+    "Copy that platform's App Platform ID",
+];
+/**
+ * The explainer for a developer with no Nami account yet: the four steps that
+ * end in an App Platform ID, and the Control Center to do them in. Pure — the
+ * only side effect is the browser handoff the caller injects.
+ */
+export function NewToNami({ host, onContinue, onBack, openUrl = openUrlInBrowser }) {
+    const [opened, setOpened] = useState(null);
+    useInput((input, key) => {
+        if (key.escape)
+            return onBack();
+        if (key.return)
+            return onContinue();
+        if (input.toLowerCase() === "o")
+            setOpened(openUrl(host.baseUrl));
+    });
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, children: "New to Nami" }), _jsx(Text, { children: "Four steps in the Control Center and the CLI can connect:" }), STEPS.map((step, i) => (_jsxs(Text, { children: ["  ", i + 1, ". ", step] }, step))), _jsx(Box, { marginTop: 1, children: _jsxs(Text, { children: ["Control Center: ", host.baseUrl] }) }), opened === true && _jsx(Text, { dimColor: true, children: "Control Center opened." }), opened === false && _jsxs(Text, { children: ["Open ", host.baseUrl, " in your browser."] }), _jsx(Text, { dimColor: true, children: "o open the Control Center \u00B7 Enter continue \u00B7 Esc back" })] }));
+}

package/dist/screens/PickOrg.js

@@ -1,9 +1,9 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Box, Text } from "ink";
 import { SelectList } from "../components/SelectList.js";
 export function PickOrg({ orgs, currentOrgId, onSelect, onCancel }) {
     if (orgs.length === 0) {
-        return (_jsx(Box, { flexDirection: "column", children: _jsx(Text, { bold: true, children: "Your account does not belong to any organization yet." }) }));
+        return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, children: "Your account does not belong to any organization yet." }), _jsx(Text, { children: "Ask an organization admin to invite you, or create one in the Control Center." })] }));
     }
     return (_jsx(SelectList, { title: "Choose an organization", items: orgs.map((o) => ({ key: o.id, label: o.name })), initialKey: currentOrgId ?? undefined, onSelect: (key) => { const org = orgs.find((o) => o.id === key); if (org)
             onSelect(org); }, onCancel: onCancel }));

package/dist/screens/Shell.js

@@ -7,6 +7,8 @@ import { PickPlatform } from "./PickPlatform.js";
 import { PickDevice } from "./PickDevice.js";
 import { PickOrg } from "./PickOrg.js";
 import { SwitchScreen } from "./SwitchScreen.js";
+import { WelcomeScreen } from "./WelcomeScreen.js";
+import { NewToNami } from "./NewToNami.js";
 import { SuccessScreen } from "./SuccessScreen.js";
 import { deviceById, presetsFor, resolveDevice, toSelection } from "../devices/presets.js";
 import { SelectionHeader } from "./SelectionHeader.js";
@@ -19,6 +21,7 @@ import { findApp, findPlatform, ResolveError } from "../control-center/resolve.j
 import { findAppPlatformById, pastedStandIn } from "../control-center/lookup.js";
 import { ConfigureScreen } from "./ConfigureScreen.js";
 import { appFrom, platformFrom, selectionFrom } from "../config/selection.js";
+import { resolveHost } from "../hosts.js";
 import { verifyAppPlatform as verifyAppPlatformFn, VerifyError } from "../sdk/verify.js";
 import TextInput from "ink-text-input";
 /**
@@ -28,7 +31,7 @@ import TextInput from "ink-text-input";
  * pasted App Platform ID. Every path funnels back through `configure`, so the
  * SDK is re-configured in place and each platform keeps its own storage file.
  */
-export function Shell({ ctx, appQuery, platformQuery, deviceQuery, onExit, exitWhenDone = true, phase, verify, configure }) {
+export function Shell({ ctx, appQuery, platformQuery, deviceQuery, onExit, exitWhenDone = true, phase, hostWasExplicit = false, verify, configure }) {
     const { exit } = useApp();
     const [state, setState] = useState({ kind: "boot" });
     const [orgName, setOrgName] = useState(null);
@@ -36,6 +39,8 @@ export function Shell({ ctx, appQuery, platformQuery, deviceQuery, onExit, exitW
     const step = (name) => void ctx.config.setOnboardingStep(name).catch(() => { });
     const [queries, setQueries] = useState({ app: appQuery, platform: platformQuery, device: deviceQuery });
     const [pasted, setPasted] = useState("");
+    // The paste route may retry on another host after a 404, without re-typing the id.
+    const [pasteHost, setPasteHost] = useState(ctx.host);
     const finish = (code) => {
         onExit?.(code);
         if (exitWhenDone)
@@ -120,22 +125,37 @@ export function Shell({ ctx, appQuery, platformQuery, deviceQuery, onExit, exitW
      * its name by scanning the apps this account can see. An id from another org
      * still works — it just shows as a pasted id until the device step.
      */
-    const usePastedId = async (home, raw) => {
+    const usePastedId = async (home, raw, host = pasteHost) => {
         const id = raw.trim();
         if (!id)
             return;
+        setPasteHost(host);
         setState({ kind: "busy", label: "Checking that ID…" });
         try {
-            await (verify ?? verifyAppPlatformFn)(ctx.host.baseUrl, id);
+            await (verify ?? verifyAppPlatformFn)(host.baseUrl, id);
         }
         catch (error) {
-            if (error instanceof VerifyError)
-                return setState({ kind: "paste-id", home, notice: error.message });
+            if (error instanceof VerifyError) {
+                // A first-run id pasted against production is most often a staging id.
+                const offer = error.code === "not_found" && host.name === "production" && !hostWasExplicit ? id : undefined;
+                const notice = offer ? `${error.message}\nPress s to try staging instead.` : error.message;
+                return setState({ kind: "paste-id", home, notice, offerStaging: offer });
+            }
             return handleError(error);
         }
         const named = (await findAppPlatformById(ctx.session, id)) ?? pastedStandIn(id);
         chooseDevice(named.app, named.platform);
     };
+    const onWelcomeChoice = (choice) => {
+        if (choice === "signin") {
+            step("signin");
+            return setState({ kind: "signin" });
+        }
+        if (choice === "new")
+            return setState({ kind: "new-to-nami" });
+        step("configure");
+        setState({ kind: "paste-id", home: null });
+    };
     const onSwitchChoice = (home, action) => {
         if (action.kind === "recent")
             return useRecent(home, action.selection);
@@ -187,11 +207,18 @@ export function Shell({ ctx, appQuery, platformQuery, deviceQuery, onExit, exitW
             setOrgName(stored?.orgName ?? null);
             setOrgId(stored?.orgId ?? null);
             const signedIn = Boolean(stored || ctx.env.NAMI_TOKEN);
+            const { config } = await ctx.config.load();
+            const asked = Boolean(queries.app || queries.platform || queries.device);
+            // First run only: the step is still `welcome` and nothing has been chosen.
+            // Any later step resumes where it left off, so quitting mid-onboarding
+            // never re-greets you.
+            if (config.onboarding.step === "welcome" && !config.current && !asked) {
+                return setState({ kind: "welcome" });
+            }
             if (!signedIn) {
                 step("signin");
                 return setState({ kind: "signin" });
             }
-            const { config } = await ctx.config.load();
             // Zero-prompt re-run: a persisted selection (and no --app/--platform override) goes straight to configure.
             if (config.current && !queries.app && !queries.platform) {
                 const platform = platformFrom(config.current);
@@ -208,12 +235,16 @@ export function Shell({ ctx, appQuery, platformQuery, deviceQuery, onExit, exitW
         if (state.kind === "fatal")
             finish(state.code);
     }, [state.kind]);
-    useInput((_input, key) => {
+    useInput((input, key) => {
         if (state.kind !== "paste-id")
             return;
+        if (state.offerStaging && input === "s") {
+            const id = state.offerStaging;
+            return void usePastedId(state.home, id, resolveHost("staging"));
+        }
         if (key.escape) {
             setPasted("");
-            setState(state.home);
+            setState(state.home ?? { kind: "welcome" });
         }
     }, { isActive: state.kind === "paste-id" });
     useInput((input, key) => {
@@ -232,7 +263,7 @@ export function Shell({ ctx, appQuery, platformQuery, deviceQuery, onExit, exitW
     }, { isActive: state.kind === "home" });
     // The hub and its sub-screens keep the home state they came from, so the header
     // keeps showing what is loaded while you choose what to switch to.
-    const shown = "home" in state ? state.home : "app" in state ? state : {};
+    const shown = ("home" in state ? state.home : "app" in state ? state : null) ?? {};
     const header = (_jsx(SelectionHeader, { orgName: orgName, appName: shown.app?.name, platformName: shown.platform?.name, platformType: shown.platform?.typeLabel, deviceName: shown.device?.displayName, host: ctx.host.name }));
     return (_jsxs(Box, { flexDirection: "column", children: [header, _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [state.kind === "boot" && _jsx(Thinking, { label: "Starting\u2026", phase: phase }), state.kind === "signin" && (_jsxs(Box, { flexDirection: "column", children: [state.notice && _jsx(Text, { color: palette.aqua, children: state.notice }), _jsx(LoginFlow, { auth: ctx.auth, store: ctx.store, host: ctx.host, exitWhenDone: false, phase: phase, onDone: (session) => { setOrgName(session.orgName); setOrgId(session.orgId); void loadApps(); }, onFail: (e) => fatal(e.message) })] })), state.kind === "busy" && _jsx(Thinking, { label: state.label, phase: phase }), state.kind === "pick-app" && (_jsx(PickApp, { apps: state.apps, orgName: orgName, baseUrl: ctx.host.baseUrl, currentAppId: state.current?.id, onSelect: (app) => void loadPlatforms(app), onCancel: () => finish(0) })), state.kind === "pick-platform" && (_jsx(PickPlatform, { appName: state.app.name, platforms: state.platforms, currentPlatformId: state.current?.id, onSelect: (platform) => chooseDevice(state.app, platform), onCancel: () => void loadApps(state.app) })), state.kind === "pick-device" && (_jsx(PickDevice, { platformType: state.platform.type, platformName: state.platform.name, currentDeviceId: state.current?.id, onSelect: (device) => { step("configure"); setState({ kind: "configure", app: state.app, platform: state.platform, device }); }, onCancel: () => void loadPlatforms(state.app, state.platform) })), state.kind === "configure" && (_jsx(ConfigureScreen, { host: ctx.host, appPlatformId: state.platform.id, device: state.device ? { platformType: state.platform.type, id: state.device.id } : undefined, phase: phase, verify: verify, configure: configure, onDone: (result) => {
                             void ctx.config
@@ -240,5 +271,5 @@ export function Shell({ ctx, appQuery, platformQuery, deviceQuery, onExit, exitW
                                 .then(() => ctx.config.markOnboardingDone())
                                 .catch(() => { });
                             setState({ kind: "home", app: state.app, platform: state.platform, device: state.device, result });
-                        }, onBack: () => chooseDevice(state.app, state.platform, state.device ?? undefined) })), state.kind === "home" && (_jsx(SuccessScreen, { app: state.app, platform: state.platform, device: state.device, result: state.result, host: ctx.host, canSwitchDevice: presetsFor(state.platform.type).length > 1, launchHint: state.launchHint })), state.kind === "switch" && (_jsx(SwitchScreen, { recent: state.recent, current: state.current, orgName: orgName, canSwitchDevice: presetsFor(state.home.platform.type).length > 1, canSwitchOrg: true, onChoose: (action) => onSwitchChoice(state.home, action), onCancel: () => setState(state.home) })), state.kind === "pick-org" && (_jsx(PickOrg, { orgs: state.orgs, currentOrgId: orgId, onSelect: (org) => void switchOrg(org), onCancel: () => setState(state.home) })), state.kind === "paste-id" && (_jsxs(Box, { flexDirection: "column", children: [state.notice && _jsx(Text, { color: palette.coral, children: state.notice }), _jsxs(Box, { children: [_jsx(Text, { children: "App Platform ID: " }), _jsx(TextInput, { value: pasted, onChange: setPasted, onSubmit: (v) => { setPasted(""); void usePastedId(state.home, v); } })] }), _jsx(Text, { dimColor: true, children: "nami platforms --app <app> lists them. Esc to go back." })] })), state.kind === "fatal" && _jsx(Text, { color: palette.coral, children: state.message })] })] }));
+                        }, onBack: () => chooseDevice(state.app, state.platform, state.device ?? undefined) })), state.kind === "home" && (_jsx(SuccessScreen, { app: state.app, platform: state.platform, device: state.device, result: state.result, host: ctx.host, canSwitchDevice: presetsFor(state.platform.type).length > 1, launchHint: state.launchHint })), state.kind === "welcome" && (_jsx(WelcomeScreen, { host: ctx.host, onChoose: onWelcomeChoice, onCancel: () => finish(0) })), state.kind === "new-to-nami" && (_jsx(NewToNami, { host: ctx.host, onContinue: () => { step("configure"); setState({ kind: "paste-id", home: null }); }, onBack: () => setState({ kind: "welcome" }) })), state.kind === "switch" && (_jsx(SwitchScreen, { recent: state.recent, current: state.current, orgName: orgName, canSwitchDevice: presetsFor(state.home.platform.type).length > 1, canSwitchOrg: true, onChoose: (action) => onSwitchChoice(state.home, action), onCancel: () => setState(state.home) })), state.kind === "pick-org" && (_jsx(PickOrg, { orgs: state.orgs, currentOrgId: orgId, onSelect: (org) => void switchOrg(org), onCancel: () => setState(state.home) })), state.kind === "paste-id" && (_jsxs(Box, { flexDirection: "column", children: [state.notice && _jsx(Text, { color: palette.coral, children: state.notice }), _jsxs(Box, { children: [_jsx(Text, { children: "App Platform ID: " }), _jsx(TextInput, { value: pasted, onChange: setPasted, onSubmit: (v) => { setPasted(""); void usePastedId(state.home, v); } })] }), _jsxs(Text, { dimColor: true, children: ["Checking ", pasteHost.name, ". nami platforms --app <app> lists them. Esc to go back."] })] })), state.kind === "fatal" && _jsx(Text, { color: palette.coral, children: state.message })] })] }));
 }

package/dist/screens/WelcomeScreen.js

@@ -0,0 +1,15 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+import { SelectList } from "../components/SelectList.js";
+const CHOICES = [
+    { key: "signin", label: "Sign in to pick my app", hint: "your Control Center account" },
+    { key: "paste", label: "I have an App Platform ID", hint: "no sign-in needed" },
+    { key: "new", label: "I'm new to Nami", hint: "start here" },
+];
+/**
+ * First-run welcome: sign in, paste an App Platform ID, or read the explainer.
+ * Pure — it never fetches and never exits; `Shell` owns every transition.
+ */
+export function WelcomeScreen({ host, onChoose, onCancel }) {
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { dimColor: true, children: [host.name, " \u00B7 ", host.baseUrl] }), _jsx(SelectList, { title: "Welcome to Nami", items: CHOICES, initialKey: "signin", onSelect: (key) => onChoose(key), onCancel: onCancel })] }));
+}

package/dist/sdk/summary.js

@@ -10,3 +10,13 @@ export function summarizePlacements(campaigns) {
     }
     return [...labels].sort((a, b) => a.localeCompare(b));
 }
+/**
+ * The two lines every non-JSON configure path prints. `nami configure`, `nami
+ * onboarding` and any future caller share this so their output cannot drift.
+ */
+export function configureSummaryLines(result) {
+    return [
+        `Configured ${result.appPlatformId} on ${result.host}: ${result.configureState}${result.sdkEnabled ? "" : " (SDK disabled)"}${result.device ? ` · ${result.device.displayName}` : ""}`,
+        `placements ${result.counts.placements} · products ${result.counts.products} · paywalls ${result.counts.paywalls}${result.deviceId ? ` · device ${result.deviceId}` : ""}`,
+    ];
+}

package/dist/utils/open-url.js

@@ -0,0 +1,33 @@
+import { spawn } from "node:child_process";
+const nodeSpawn = (cmd, args, opts) => spawn(cmd, args, opts);
+/** The platform's "open this in the default handler" command, or null when we have none. */
+function opener(platform, url) {
+    switch (platform) {
+        case "darwin":
+            return { cmd: "open", args: [url] };
+        case "win32":
+            // The empty string is `start`'s title argument; without it a quoted URL becomes the title.
+            return { cmd: "cmd", args: ["/c", "start", "", url] };
+        case "linux":
+            return { cmd: "xdg-open", args: [url] };
+        default:
+            return null;
+    }
+}
+/**
+ * Best effort: open `url` in the developer's browser. Never throws and never blocks —
+ * returns false when we have no opener for this platform or spawning fails, so the
+ * caller can print the URL instead.
+ */
+export function openUrl(url, platform = process.platform, spawnImpl = nodeSpawn) {
+    const target = opener(platform, url);
+    if (!target)
+        return false;
+    try {
+        spawnImpl(target.cmd, target.args, { stdio: "ignore", detached: true }).unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/version.js

@@ -1,2 +1,2 @@
 /** CLI package version. Stamped by scripts/version.sh from the repo VERSION file — do not hand-edit. */
-export const NAMI_CLI_VERSION = "3.4.11-dev.202609230009";
+export const NAMI_CLI_VERSION = "3.4.11-dev.202609230307";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namiml/cli",
-  "version": "3.4.11-dev.202609230009",
+  "version": "3.4.11-dev.202609230307",
   "description": "Nami SDK developer CLI — terminal test app, implementation and flow checks",
   "keywords": [
     "nami",
@@ -35,7 +35,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@namiml/sdk-core": "3.4.11-dev.202609230009",
+    "@namiml/sdk-core": "3.4.11-dev.202609230307",
     "commander": "^15",
     "env-paths": "^4",
     "ink": "^6.0.0",