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

package/dist/cli.js

@@ -15,6 +15,7 @@ import { use } from "./commands/use.js";
 import { config } from "./commands/config.js";
 import { onboarding } from "./commands/onboarding.js";
 import { devices } from "./commands/devices.js";
+import { placements } from "./commands/placements.js";
 const program = createProgram({
     shell: async (opts) => shell(opts, await buildContext(opts.host)),
     demo: () => { render(_jsx(App, {})); },
@@ -28,5 +29,6 @@ const program = createProgram({
     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)),
+    placements: async (opts) => placements(opts, await buildContext(opts.host)),
 });
 await program.parseAsync(process.argv);

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/placements.js

@@ -0,0 +1,56 @@
+import { corePlacementData, listPlacements } from "../placements/list.js";
+import { configureSdk } from "../sdk/configure.js";
+import { VerifyError } from "../sdk/verify.js";
+import { renderTable } from "./list-output.js";
+const NOT_CONFIGURED = "Nothing is configured yet. Run nami to pick an app and platform, or nami configure --app-platform-id <uuid> to name one directly.";
+/**
+ * The real source: configure the SDK against the persisted selection, then read
+ * `NamiCampaignManager.allCampaigns()`. Paywalls come along because a campaign
+ * rule names its paywall by id only (see `listPlacements`).
+ */
+const configuredSource = async (selection, host) => {
+    await configureSdk({
+        host,
+        appPlatformId: selection.appPlatformId,
+        device: { platformType: selection.platformType, id: selection.device?.id },
+    });
+    return corePlacementData();
+};
+/**
+ * `nami placements [--json]` — the placements the configured SDK can launch.
+ *
+ * Every `nami` run is a fresh process, so "the SDK is configured" means
+ * `config.json` names an app platform to configure against. Without one there is
+ * nothing to read, and the command says what to run instead. Returns the exit code.
+ */
+export async function placements(opts, ctx, deps = {}) {
+    const { config, warning } = await ctx.config.load();
+    if (warning)
+        ctx.err(warning);
+    if (!config.current) {
+        ctx.err(NOT_CONFIGURED);
+        return 2;
+    }
+    let rows;
+    try {
+        const { campaigns, paywalls } = await (deps.source ?? configuredSource)(config.current, ctx.host);
+        rows = listPlacements(campaigns, paywalls);
+    }
+    catch (error) {
+        if (error instanceof VerifyError) {
+            ctx.err(error.message);
+            return error.code === "invalid_id" ? 2 : 1;
+        }
+        throw error;
+    }
+    if (opts.json) {
+        ctx.out(JSON.stringify(rows, null, 2));
+        return 0;
+    }
+    if (rows.length === 0) {
+        ctx.out("No placements — add a campaign in the Control Center, then run nami placements again.");
+        return 0;
+    }
+    ctx.out(renderTable(rows.map((p) => ({ placement: p.label, kind: p.kind, campaign: p.campaignName ?? "", paywall: p.paywallName ?? "" })), ["placement", "kind", "campaign", "paywall"]));
+    return 0;
+}

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/events/bus.js

@@ -0,0 +1,58 @@
+/**
+ * The recorder behind the Events pane.
+ *
+ * Everything the SDK emits while a placement is on screen lands here: paywall
+ * actions, flow events and handoffs. The bus is deliberately plain — no React,
+ * no `@namiml/sdk-core` import — so the adapters can feed it, the screens can
+ * read it and the tests can drive it without any of them dragging the others in.
+ */
+/**
+ * How many events a session keeps. A long paywall session emits thousands;
+ * the pane only ever shows the recent tail, so the oldest are dropped first.
+ */
+export const EVENT_BUFFER_MAX = 500;
+export class EventBus {
+    #now;
+    #buffer = [];
+    #subscribers = new Set();
+    #seq = 0;
+    constructor({ now = () => new Date() } = {}) {
+        this.#now = now;
+    }
+    /** Stamp, store and fan out one event. Never throws on a subscriber's behalf. */
+    record(input) {
+        this.#seq += 1;
+        const event = { ...input, seq: this.#seq, at: this.#now().toISOString() };
+        this.#buffer.push(event);
+        while (this.#buffer.length > EVENT_BUFFER_MAX)
+            this.#buffer.shift();
+        for (const subscriber of [...this.#subscribers]) {
+            try {
+                subscriber(event);
+            }
+            catch {
+                // A broken listener is not allowed to stop the others, drop the event or
+                // take down the render loop. There is no log sink in a TUI to report to.
+            }
+        }
+        return event;
+    }
+    /** A copy, oldest first — callers cannot reach into the buffer. */
+    all() {
+        return [...this.#buffer];
+    }
+    /** Empty the buffer. `seq` keeps climbing: it identifies events, it is not a count. */
+    clear() {
+        this.#buffer.length = 0;
+    }
+    subscribe(fn) {
+        this.#subscribers.add(fn);
+        return () => {
+            this.#subscribers.delete(fn);
+        };
+    }
+    /** One JSON object per line, carrying the SDK's own field names verbatim. */
+    toJsonl() {
+        return this.#buffer.map((event) => JSON.stringify(event)).join("\n");
+    }
+}

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/placements/launch.js

@@ -0,0 +1,160 @@
+import { getPaywallDataFromLabel, NamiCampaignManager, NamiEventEmitter, NamiFlowManager, NamiPaywallAction, NamiPaywallManager, PAYWALL_ACTION_EVENT, } from "@namiml/sdk-core";
+import { compositeForPage, currentPageName } from "../render/composite.js";
+import { actionForOnTap, noEventReason } from "../render/action-map.js";
+/**
+ * Purchase outcomes. The CLI registers `TerminalPurchaseAdapter` and nothing
+ * else, so every one of these it ever sees was simulated — and a simulated
+ * PURCHASE_SUCCESS read as a real one is exactly the misreading to prevent.
+ */
+const SIMULATED_ACTIONS = new Set([
+    NamiPaywallAction.PURCHASE_SUCCESS,
+    NamiPaywallAction.PURCHASE_FAILED,
+    NamiPaywallAction.PURCHASE_CANCELLED,
+    NamiPaywallAction.PURCHASE_PENDING,
+    NamiPaywallAction.PURCHASE_UNKNOWN,
+    NamiPaywallAction.PURCHASE_DEFERRED,
+]);
+/** Keys a flow author may have named their event with; the first one present wins. */
+const FLOW_NAME_KEYS = ["name", "event", "eventName", "type"];
+/** A flow event has no schema, so its name is the author's own or a neutral stand-in. */
+function flowEventName(event) {
+    for (const key of FLOW_NAME_KEYS) {
+        const value = event[key];
+        if (typeof value === "string" && value.trim() !== "")
+            return value;
+    }
+    return "flow event";
+}
+/** Subscribes the three sources into the bus and launches the placement. */
+export async function startLaunch(label, bus, deps = {}) {
+    const flow = deps.flowManager ?? NamiFlowManager;
+    const paywalls = deps.paywallManager ?? NamiPaywallManager;
+    const emitter = deps.emitter ?? NamiEventEmitter.getInstance();
+    const unsubscribes = [
+        flow.registerEventHandler((event) => {
+            const payload = { ...event };
+            bus.record({ source: "flow", name: flowEventName(payload), payload });
+        }),
+        flow.registerStepHandoff((tag, data, complete) => {
+            bus.record({
+                source: "handoff",
+                name: tag,
+                payload: {
+                    tag,
+                    data,
+                    outcome: "done",
+                    handler: "NamiFlowManager.registerStepHandoff",
+                    note: "the CLI completed this handoff so the flow could continue — your app decides the real outcome",
+                },
+            });
+            // A flow waits on `complete`; leaving it uncalled would wedge the launch.
+            // Handlers written against the pre-outcome signature get no `complete`.
+            if (typeof complete === "function")
+                complete();
+        }),
+        paywalls.registerDeeplinkActionHandler((url) => {
+            bus.record({
+                source: "paywall",
+                name: NamiPaywallAction.DEEPLINK,
+                payload: {
+                    deeplinkUrl: url,
+                    handler: "NamiPaywallManager.registerDeeplinkActionHandler",
+                    note: "this arrived on the deeplink handler, not the paywall action event — namiDeeplink never reports as an action",
+                },
+            });
+        }),
+    ];
+    const dispose = () => {
+        for (const unsubscribe of unsubscribes) {
+            try {
+                unsubscribe();
+            }
+            catch {
+                // One broken unregister is not allowed to strand the others.
+            }
+        }
+        unsubscribes.length = 0;
+    };
+    const record = (event) => {
+        const payload = { ...event };
+        delete payload.action;
+        const name = String(event.action);
+        bus.record({ source: "paywall", name, payload, ...(SIMULATED_ACTIONS.has(name) ? { simulated: true } : {}) });
+    };
+    try {
+        if (deps.launch)
+            deps.launch(label, record);
+        else
+            NamiCampaignManager.launch(label, undefined, undefined, undefined, record);
+    }
+    catch (error) {
+        dispose();
+        throw error;
+    }
+    // `sdk/web`'s PaywallScreen reports SHOW_PAYWALL the moment the paywall
+    // renders (`postPaywallScreenData`). The CLI is the renderer here, so it owes
+    // the same event — and it goes out on the shared emitter, which is where
+    // `launch` just added the action callback.
+    emitter.emit(PAYWALL_ACTION_EVENT, { action: NamiPaywallAction.SHOW_PAYWALL, campaignLabel: label });
+    return { dispose };
+}
+/** Nothing to outline: a flow placement, or a paywall core could not resolve. */
+const NO_PAGE = { pageName: "", sections: [], truncated: 0, unresolved: true };
+/**
+ * The page outline for a placement, from core's own lookup.
+ *
+ * `getPaywallDataFromLabel` is the same lookup `NamiCampaignManager.launch`
+ * performs, so the pane outlines the page the launch actually served. A flow
+ * placement carries no paywall here — its screens report as flow events.
+ */
+/**
+ * The outline for a placement, or an `unresolved` composite.
+ *
+ * A placement only resolves a paywall when that paywall was in the set the SDK
+ * fetched for the **configured device's form factor**. Verified against staging
+ * Test Nami: as a host desktop only 12 paywalls come back and this label
+ * resolves nothing, while as an iPhone 150 come back and it resolves — and even
+ * then 12 of 103 paywall placements stay unresolved because they are authored
+ * for other form factors. So an empty outline is usually a device mismatch, not
+ * an authoring mistake, and the screen has to say which.
+ */
+export function compositeForPlacement(label) {
+    try {
+        const { paywall } = getPaywallDataFromLabel(label, "label");
+        if (!paywall)
+            return NO_PAGE;
+        return compositeForPage(paywall, currentPageName(paywall));
+    }
+    catch {
+        // A placement the SDK cannot resolve is an empty outline, never a crash:
+        // the events pane is still the point of the screen.
+        return NO_PAGE;
+    }
+}
+/**
+ * Press one node the way the web SDK does: map its `onTap`, then report the
+ * action on the shared emitter so it reaches the developer's own
+ * `actionCallback` on exactly the path a real app uses.
+ *
+ * A control the SDK maps to no action reports nothing and says why — inventing
+ * an event the SDK would never have sent is the one thing this screen must not do.
+ */
+export function pressNode(node, deps = {}) {
+    const fn = node.onTap?.function;
+    if (fn === undefined)
+        return { reason: "This part of the page is not a control — there is nothing to press." };
+    const mapped = actionForOnTap(node.onTap);
+    if (!mapped)
+        return { reason: noEventReason(fn) };
+    if (mapped.requiresSku) {
+        return {
+            reason: `${fn} needs a SKU in play, and the CLI has no product selected — the SDK sends nothing without one.`,
+        };
+    }
+    const emitter = deps.emitter ?? NamiEventEmitter.getInstance();
+    emitter.emit(PAYWALL_ACTION_EVENT, {
+        action: mapped.action,
+        ...(mapped.componentChange ? { componentChange: mapped.componentChange } : {}),
+    });
+    return { action: mapped.action };
+}

package/dist/placements/list.js

@@ -0,0 +1,52 @@
+import { isNamiFlowCampaign, NamiCampaignManager, NamiPaywallManager } from "@namiml/sdk-core";
+import { placementLabel } from "../sdk/summary.js";
+/**
+ * One row per campaign rule, de-duplicated by label and sorted, mirroring
+ * `summarizePlacements()` — both take the label from `placementLabel()`.
+ *
+ * `kind` comes from the campaign's own `flow` field, which core's exported
+ * `isNamiFlowCampaign()` guard is defined on: a rule that carries a flow object
+ * serves a flow, everything else serves a paywall. Nothing is inferred.
+ *
+ * `paywallName` needs `paywalls` because a rule carries only the paywall's **id**
+ * (`NamiCampaign.paywall`), never its name; without the list it stays unset.
+ */
+export function listPlacements(campaigns, paywalls) {
+    if (!Array.isArray(campaigns))
+        return [];
+    const names = new Map();
+    for (const p of paywalls ?? [])
+        if (p?.id && p.name)
+            names.set(p.id, p.name);
+    const byLabel = new Map();
+    for (const campaign of campaigns) {
+        const label = placementLabel(campaign);
+        // First rule wins: `allCampaigns()` returns API rules before initial-config ones.
+        if (!label || byLabel.has(label))
+            continue;
+        const paywallName = typeof campaign.paywall === "string" ? names.get(campaign.paywall) : undefined;
+        byLabel.set(label, {
+            label,
+            kind: isNamiFlowCampaign(campaign) ? "flow" : "paywall",
+            ...(campaign.name?.trim() ? { campaignName: campaign.name.trim() } : {}),
+            ...(campaign.segment === undefined ? {} : { segmentId: campaign.segment }),
+            ...(paywallName ? { paywallName } : {}),
+        });
+    }
+    return [...byLabel.values()].sort((a, b) => a.label.localeCompare(b.label));
+}
+/**
+ * What the configured core currently holds: its campaign rules and its paywalls.
+ *
+ * One pair, read in one place, so `nami placements` and the Shell's launch
+ * picker can never end up listing different things. Paywalls come along because
+ * a rule names its paywall by id only (see `listPlacements`).
+ */
+export function corePlacementData() {
+    return { campaigns: NamiCampaignManager.allCampaigns(), paywalls: NamiPaywallManager.allPaywalls() };
+}
+/** `corePlacementData()` as rows. Throws if the SDK is not configured in this process. */
+export function corePlacements() {
+    const { campaigns, paywalls } = corePlacementData();
+    return listPlacements(campaigns, paywalls);
+}

package/dist/program.js

@@ -79,6 +79,14 @@ export function createProgram(h, options = {}) {
         .action(async (_opts, cmd) => {
         process.exitCode = await h.configure(cmd.optsWithGlobals());
     });
+    program
+        .command("placements")
+        .description("List the placements the configured SDK can launch. Needs a current selection (run nami or nami configure first).")
+        .option(HOST_FLAG, HOST_HELP)
+        .option("--json", "machine-readable output")
+        .action(async (_opts, cmd) => {
+        process.exitCode = await h.placements(cmd.optsWithGlobals());
+    });
     program
         .command("use")
         .description("Switch the current organization, app, app platform or device (headless).")
@@ -110,9 +118,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());
     });