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

package/dist/cli.js

@@ -11,6 +11,7 @@ import { apps } from "./commands/apps.js";
 import { platforms } from "./commands/platforms.js";
 import { shell } from "./commands/shell.js";
 import { configure } from "./commands/configure.js";
+import { use } from "./commands/use.js";
 import { config } from "./commands/config.js";
 import { onboarding } from "./commands/onboarding.js";
 import { devices } from "./commands/devices.js";
@@ -23,6 +24,7 @@ const program = createProgram({
     apps: async (opts) => apps(opts, await buildContext(opts.host)),
     platforms: async (opts) => platforms(opts, await buildContext(opts.host)),
     configure: async (opts) => configure(opts, await buildContext(opts.host)),
+    use: async (opts) => use(opts, await buildContext(opts.host)),
     config: async (opts) => config(opts, await buildContext(opts.host)),
     onboarding: async (opts) => onboarding(opts, await buildContext(opts.host)),
     devices: async (opts) => devices(opts, await buildContext(opts.host)),

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/commands/use.js

@@ -0,0 +1,131 @@
+import { AuthError } from "../auth/errors.js";
+import { listApps } from "../control-center/apps.js";
+import { listPlatforms } from "../control-center/platforms.js";
+import { findAppPlatformById, pastedStandIn } from "../control-center/lookup.js";
+import { findApp, findPlatform, resolve, ResolveError } from "../control-center/resolve.js";
+import { appFrom, platformFrom, selectionFrom } from "../config/selection.js";
+import { resolveDevice, toSelection } from "../devices/presets.js";
+import { verifyAppPlatform, VerifyError } from "../sdk/verify.js";
+const NOT_SIGNED_IN = "Not signed in. Run `nami login` first.";
+const NO_FLAGS = "nami use needs one of --org, --app, --platform, --app-platform-id or --device. Run nami for the interactive picker.";
+const NO_CURRENT_APP = "No app selected yet. Pass --app too, or run nami once.";
+const summary = (s) => {
+    const device = s.device ? ` · ${s.device.displayName}` : "";
+    return `Now using ${s.appName} · ${s.platformName} (${s.platformType})${device}`;
+};
+/** `nami use` — record and validate a selection (org, app, platform, app-platform-id or device). Never runs the SDK. */
+export async function use(opts, ctx, deps = {}) {
+    const verify = deps.verify ?? verifyAppPlatform;
+    const doListApps = deps.listApps ?? listApps;
+    const doListPlatforms = deps.listPlatforms ?? listPlatforms;
+    if (!opts.org && !opts.app && !opts.platform && !opts.appPlatformId && !opts.device) {
+        ctx.err(NO_FLAGS);
+        return 2;
+    }
+    try {
+        if (opts.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, opts.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 });
+            // Apps are org-scoped: a bare --org switch invalidates whatever app/platform was current.
+            if (!opts.app && !opts.appPlatformId)
+                await ctx.config.clearCurrent();
+            if (!opts.app && !opts.platform && !opts.appPlatformId && !opts.device) {
+                if (opts.json) {
+                    const { config } = await ctx.config.load();
+                    ctx.out(JSON.stringify(config.current, null, 2));
+                }
+                else {
+                    ctx.out(`Now using organization ${org.name}.`);
+                }
+                return 0;
+            }
+        }
+        let app;
+        let platform;
+        if (opts.appPlatformId) {
+            await verify(ctx.host.baseUrl, opts.appPlatformId, deps.fetch ?? 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 the switch.
+            const named = (await findAppPlatformById(ctx.session, opts.appPlatformId, { listApps: doListApps, listPlatforms: doListPlatforms })) ?? pastedStandIn(opts.appPlatformId);
+            app = named.app;
+            platform = named.platform;
+        }
+        else if (opts.app) {
+            app = findApp(await doListApps(ctx.session), opts.app);
+            const platforms = await doListPlatforms(ctx.session, app.id);
+            if (opts.platform) {
+                platform = findPlatform(platforms, opts.platform);
+            }
+            else if (platforms.length === 1) {
+                platform = platforms[0];
+            }
+            else {
+                ctx.err(`"${app.name}" has more than one platform: ${platforms.map((p) => p.name).join(", ")}. Pass --platform too.`);
+                return 2;
+            }
+        }
+        else if (opts.platform) {
+            const { config } = await ctx.config.load();
+            if (!config.current) {
+                ctx.err(NO_CURRENT_APP);
+                return 2;
+            }
+            app = appFrom(config.current);
+            const platforms = await doListPlatforms(ctx.session, app.id);
+            platform = findPlatform(platforms, opts.platform);
+        }
+        else if (opts.device) {
+            // --device with no app/platform/app-platform-id targets the current selection.
+            const { config } = await ctx.config.load();
+            if (!config.current) {
+                ctx.err(NO_CURRENT_APP);
+                return 2;
+            }
+            app = appFrom(config.current);
+            platform = platformFrom(config.current);
+        }
+        if (!app || !platform) {
+            ctx.err(NO_FLAGS);
+            return 2;
+        }
+        let device = null;
+        if (opts.device) {
+            const resolved = resolveDevice(platform.type, opts.device);
+            device = toSelection(resolved);
+        }
+        const selection = selectionFrom(app, platform, device);
+        const next = await ctx.config.setCurrent(selection, { host: ctx.host.name });
+        if (opts.json) {
+            ctx.out(JSON.stringify(next.current, null, 2));
+        }
+        else {
+            ctx.out(summary(selection));
+            ctx.out(`App Platform ID ${selection.appPlatformId} · ${ctx.host.name}`);
+        }
+        return 0;
+    }
+    catch (error) {
+        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;
+    }
+}

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/config/store.js

@@ -30,7 +30,8 @@ function assertNoCredentials(value, path = "config") {
         }
     }
 }
-const recentKey = (s) => `${s.appPlatformId}::${s.device?.id ?? ""}`;
+/** Identity of a selection in `recent`: the platform plus the device it was used on. */
+export const recentKey = (s) => `${s.appPlatformId}::${s.device?.id ?? ""}`;
 /** Upgrade older shapes; unknown versions fall back to defaults (with a warning from load()). */
 export function migrate(raw) {
     if (!raw || typeof raw !== "object")
@@ -111,6 +112,24 @@ export class ConfigStore {
             return next;
         });
     }
+    /** Forget the active selection (e.g. after switching org); `recent` is untouched. */
+    clearCurrent() {
+        return this.enqueue(async () => {
+            const { config } = await this.load();
+            const next = { ...config, current: null };
+            await this.save(next);
+            return next;
+        });
+    }
+    /** Replace the session block (org context) only. */
+    setSession(session) {
+        return this.enqueue(async () => {
+            const { config } = await this.load();
+            const next = { ...config, session };
+            await this.save(next);
+            return next;
+        });
+    }
     setOnboardingStep(step) {
         return this.enqueue(async () => {
             const { config } = await this.load();

package/dist/control-center/lookup.js

@@ -0,0 +1,42 @@
+import { listApps } from "./apps.js";
+import { listPlatforms, platformTypeLabel } from "./platforms.js";
+/**
+ * Find the app and platform behind an App Platform ID.
+ *
+ * There is no "platform by id" endpoint in this client, so this walks the apps
+ * the session can see. Naming is a convenience on top of the public verify
+ * call: any failure (signed out, another org's id, an unreachable list) returns
+ * null so the caller can fall back to `pastedStandIn` rather than refuse a valid id.
+ */
+export async function findAppPlatformById(session, appPlatformId, deps = {}) {
+    const apps = deps.listApps ?? listApps;
+    const platforms = deps.listPlatforms ?? listPlatforms;
+    try {
+        for (const app of await apps(session)) {
+            const platform = (await platforms(session, app.id)).find((p) => p.id === appPlatformId);
+            if (platform)
+                return { app, platform };
+        }
+    }
+    catch {
+        // Naming is optional; the id itself was already verified.
+    }
+    return null;
+}
+/** What an unnamed App Platform ID looks like until the device step narrows it down. */
+export function pastedStandIn(appPlatformId) {
+    return {
+        app: { id: appPlatformId, name: "Pasted ID", archived: false, defaultLanguage: null, logo: null },
+        platform: {
+            id: appPlatformId,
+            appId: null,
+            name: "App Platform",
+            type: "web",
+            typeLabel: platformTypeLabel("web"),
+            sdkEnabled: true,
+            isConfigValid: true,
+            archived: false,
+            marketplaceAppId: null,
+        },
+    };
+}

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

@@ -79,6 +79,19 @@ export function createProgram(h, options = {}) {
         .action(async (_opts, cmd) => {
         process.exitCode = await h.configure(cmd.optsWithGlobals());
     });
+    program
+        .command("use")
+        .description("Switch the current organization, app, app platform or device (headless).")
+        .option("--org <id-or-name>", "switch organization (re-scopes the access token; clears the current selection)")
+        .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>", "select by App Platform ID directly")
+        .option("--device <id-or-name>", "target device preset, previewer id or name")
+        .option(HOST_FLAG, HOST_HELP)
+        .option("--json", "machine-readable result")
+        .action(async (_opts, cmd) => {
+        process.exitCode = await h.use(cmd.optsWithGlobals());
+    });
     program
         .command("devices")
         .description("List the target device presets and the full previewer device list for a platform type.")
@@ -97,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

@@ -0,0 +1,10 @@
+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 (_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

@@ -5,6 +5,10 @@ import { LoginFlow } from "./LoginFlow.js";
 import { PickApp } from "./PickApp.js";
 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";
@@ -14,20 +18,29 @@ import { AuthError } from "../auth/errors.js";
 import { listApps } from "../control-center/apps.js";
 import { listPlatforms } from "../control-center/platforms.js";
 import { findApp, findPlatform, ResolveError } from "../control-center/resolve.js";
+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";
 /**
- * Bare `nami`: sign in if needed → pick app → pick platform → home.
- * Selection is in-memory for now (persistence: NAM-4501; configure: NAM-4500;
- * full Switch with Recent/org switching: NAM-4503).
+ * Bare `nami`: sign in if needed → pick app → platform → device → home.
+ * `s` opens the Switch hub, which reaches every axis `nami use` can switch
+ * headlessly: a recent selection, app, platform, device, organization, or a
+ * 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);
     const [orgId, setOrgId] = useState(null);
     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)
@@ -62,6 +75,100 @@ export function Shell({ ctx, appQuery, platformQuery, deviceQuery, onExit, exitW
         }
         setState({ kind: "pick-device", app, platform, current });
     };
+    /** Open the Switch hub over the current home state; recent/current come from config.json. */
+    const openSwitch = async (home) => {
+        const { config } = await ctx.config.load();
+        setState({ kind: "switch", home, recent: config.recent, current: config.current });
+    };
+    /** A recent entry is a selection we already know — rebuild it and reconfigure, no network call. */
+    const useRecent = (home, selection) => {
+        const sameDevice = (selection.device?.id ?? null) === (home.device?.id ?? null);
+        if (selection.appPlatformId === home.platform.id && sameDevice)
+            return setState(home);
+        const device = selection.device ? deviceById(selection.device.id) ?? null : null;
+        step("configure");
+        setState({ kind: "configure", app: appFrom(selection), platform: platformFrom(selection), device });
+    };
+    const openOrgs = async (home) => {
+        setState({ kind: "busy", label: "Loading your organizations…" });
+        try {
+            const stored = await ctx.store.load();
+            if (!stored)
+                return setState({ kind: "signin" });
+            const profile = await ctx.auth.fetchAccount(stored.accessToken);
+            setState({ kind: "pick-org", home, orgs: profile.orgs });
+        }
+        catch (error) {
+            handleError(error);
+        }
+    };
+    /** Re-scope the token to another org. No re-login; the old selection no longer applies. */
+    const switchOrg = async (org) => {
+        setState({ kind: "busy", label: `Switching to ${org.name}…` });
+        try {
+            const stored = await ctx.store.load();
+            if (!stored)
+                return setState({ kind: "signin" });
+            const accessToken = await ctx.auth.selectOrg(stored.refreshToken, org.id);
+            await ctx.store.save({ ...stored, accessToken, orgId: org.id, orgName: org.name, savedAt: new Date().toISOString() });
+            setOrgName(org.name);
+            setOrgId(org.id);
+            await ctx.config.clearCurrent().catch(() => { });
+            await loadApps();
+        }
+        catch (error) {
+            handleError(error);
+        }
+    };
+    /**
+     * A pasted App Platform ID: verify it on the public config endpoint, then find
+     * 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, host = pasteHost) => {
+        const id = raw.trim();
+        if (!id)
+            return;
+        setPasteHost(host);
+        setState({ kind: "busy", label: "Checking that ID…" });
+        try {
+            await (verify ?? verifyAppPlatformFn)(host.baseUrl, id);
+        }
+        catch (error) {
+            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);
+        if (action.kind === "app")
+            return void loadApps(home.app);
+        if (action.kind === "platform")
+            return void loadPlatforms(home.app, home.platform);
+        if (action.kind === "device")
+            return setState({ kind: "pick-device", app: home.app, platform: home.platform, current: home.device ?? undefined });
+        if (action.kind === "org")
+            return void openOrgs(home);
+        setState({ kind: "paste-id", home });
+    };
     const loadApps = async (current) => {
         setState({ kind: "busy", label: "Loading your apps…" });
         try {
@@ -100,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);
@@ -121,13 +235,25 @@ export function Shell({ ctx, appQuery, platformQuery, deviceQuery, onExit, exitW
         if (state.kind === "fatal")
             finish(state.code);
     }, [state.kind]);
+    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 ?? { kind: "welcome" });
+        }
+    }, { isActive: state.kind === "paste-id" });
     useInput((input, key) => {
         if (state.kind !== "home")
             return;
         if (input === "q" || key.escape)
             return finish(0);
         if (input === "s")
-            return void loadApps(state.app);
+            return void openSwitch(state);
         if (input === "p")
             return void loadPlatforms(state.app, state.platform);
         if (input === "d" && presetsFor(state.platform.type).length > 1)
@@ -135,12 +261,15 @@ export function Shell({ ctx, appQuery, platformQuery, deviceQuery, onExit, exitW
         if (input === "l")
             return setState({ ...state, launchHint: true });
     }, { isActive: state.kind === "home" });
-    const header = (_jsx(SelectionHeader, { orgName: orgName, appName: "app" in state ? state.app.name : undefined, platformName: "platform" in state ? state.platform.name : undefined, platformType: "platform" in state ? state.platform.typeLabel : undefined, deviceName: "device" in state ? state.device?.displayName : undefined, host: ctx.host.name }));
+    // 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 : 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
                                 .setCurrent(selectionFrom(state.app, state.platform, state.device ? toSelection(state.device) : null), { host: ctx.host.name, session: { orgId, orgName } })
                                 .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 === "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/SwitchScreen.js

@@ -0,0 +1,46 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+import { SelectList } from "../components/SelectList.js";
+import { recentKey as selectionKey } from "../config/store.js";
+/** `recent:` + `ConfigStore`'s own de-dup key, so the two can never drift apart. */
+const recentKey = (s) => `recent:${selectionKey(s)}`;
+const isCurrent = (s, current) => current !== null && s.appPlatformId === current.appPlatformId && (s.device?.id ?? null) === (current.device?.id ?? null);
+export function switchItems({ recent, current, canSwitchDevice, canSwitchOrg, }) {
+    const recentItems = recent.map((s) => {
+        const hintParts = [s.device?.displayName, isCurrent(s, current) ? "current" : undefined].filter((v) => Boolean(v));
+        return {
+            key: recentKey(s),
+            label: `${s.appName} · ${s.platformName}`,
+            badge: s.platformType,
+            hint: hintParts.length > 0 ? hintParts.join(" · ") : undefined,
+        };
+    });
+    const actionItems = [
+        { key: "action:app", label: "Switch app" },
+        { key: "action:platform", label: "Switch platform" },
+        ...(canSwitchDevice ? [{ key: "action:device", label: "Change device" }] : []),
+        ...(canSwitchOrg ? [{ key: "action:org", label: "Change organization" }] : []),
+        { key: "action:paste", label: "Paste an App Platform ID" },
+    ];
+    return [...recentItems, ...actionItems];
+}
+/** The Switch hub: recent selections plus app/platform/device/org/paste actions. Pure — never fetches. */
+export function SwitchScreen({ recent, current, orgName, canSwitchDevice, canSwitchOrg, onChoose, onCancel }) {
+    const items = switchItems({ recent, current, canSwitchDevice, canSwitchOrg });
+    const handleSelect = (key) => {
+        if (key === "action:app")
+            return onChoose({ kind: "app" });
+        if (key === "action:platform")
+            return onChoose({ kind: "platform" });
+        if (key === "action:device")
+            return onChoose({ kind: "device" });
+        if (key === "action:org")
+            return onChoose({ kind: "org" });
+        if (key === "action:paste")
+            return onChoose({ kind: "paste" });
+        const selection = recent.find((s) => recentKey(s) === key);
+        if (selection)
+            onChoose({ kind: "recent", selection });
+    };
+    return (_jsxs(Box, { flexDirection: "column", children: [orgName && _jsx(Text, { dimColor: true, children: orgName }), _jsx(SelectList, { title: "Switch", items: items, initialKey: "action:app", onSelect: handleSelect, onCancel: onCancel, footer: "Esc to go back" })] }));
+}

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.202609222238";
+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.202609222238",
+  "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.202609222238",
+    "@namiml/sdk-core": "3.4.11-dev.202609230307",
     "commander": "^15",
     "env-paths": "^4",
     "ink": "^6.0.0",