@hs-x/cli 0.2.7 → 0.3.6

package/dist/commands/dev.js

@@ -1,3 +1,4 @@
+import { randomBytes } from 'node:crypto';
 import { readFile, readdir, stat } from 'node:fs/promises';
 import { createServer } from 'node:http';
 import { join } from 'node:path';
@@ -7,15 +8,16 @@ import * as Options from '@effect/cli/Options';
 import { generateProjectArtifacts } from '@hs-x/codegen';
 import { HttpClientRequest, Schema, schemas } from '@hs-x/types';
 import { Effect, Option } from 'effect';
-import { BRAND_ORANGE_SGR, CLI_VERSION } from '../constants.js';
 import { exitWith } from '../cli-error.js';
+import { cwdOption, jsonOption, runHandler, runQuarantined } from '../cli/kit.js';
+import { formatConfigUrl, loadCliConfig } from '../config.js';
+import { CLI_VERSION } from '../constants.js';
 import { controlPlaneAuthHeaders } from '../control-plane-fetch.js';
 import { executeCliHttp } from '../effect-http.js';
-import { formatConfigUrl, loadCliConfig } from '../config.js';
-import { jsonOption, cwdOption, runHandler, runQuarantined } from '../cli/kit.js';
-import { Cwd } from '../services/cwd.js';
+import { LocalProjectPickerCancelled, resolveLocalProject } from '../local-project-picker.js';
+import { isInteractive, promptMultiSelect, promptSelect } from '../prompt.js';
 import { createReporter } from '../reporter/index.js';
-import { isInteractive, promptMultiSelect, promptSelect, promptText } from '../prompt.js';
+import { Cwd } from '../services/cwd.js';
 async function hostedHttp(input) {
     const headers = { ...(input.headers ?? {}) };
     let request = HttpClientRequest.make(input.method ?? 'GET')(input.url).pipe(HttpClientRequest.setHeaders(headers));
@@ -31,40 +33,46 @@ function isRecord(value) {
 function isErrnoException(value) {
     return value instanceof Error && typeof value.code === 'string';
 }
-function renderDevHeader(env, stderr, { subject, url }) {
+function makeDevLogPaint(env, stderr) {
     const isTTY = Boolean(stderr.isTTY);
     const color = isTTY && env.NO_COLOR !== '1';
-    const orange = (s) => (color ? `\x1b[${BRAND_ORANGE_SGR}m${s}\x1b[0m` : s);
-    const bold = (s) => (color ? `\x1b[1m${s}\x1b[0m` : s);
-    const dim = (s) => (color ? `\x1b[2m${s}\x1b[0m` : s);
-    const arrow = '▲';
-    const sep = '→';
-    stderr.write(`\n  ${orange(arrow)} ${bold('hs-x dev')}   ${bold(subject)}   ${dim(sep)}   ${url}\n\n`);
+    const wrap = (open) => (s) => (color ? `\x1b[${open}m${s}\x1b[0m` : s);
+    return {
+        dim: wrap('2'),
+        green: wrap('32'),
+        red: wrap('31'),
+        yellow: wrap('33'),
+        cyan: wrap('36'),
+        magenta: wrap('35'),
+    };
+}
+/**
+ * One request-summary line (plus an optional `└ detail` second line), colored
+ * via `paint`. Shared by the direct fallback logger and the event-bus lane so
+ * the columns look identical wherever the line lands.
+ */
+function formatDevLogEntry(entry, paint, defaultAccountId) {
+    const { method, path, status, durationMs, source = 'local', accountId, detail } = entry;
+    const statusColor = status >= 500 ? paint.red : status >= 400 ? paint.yellow : paint.green;
+    const symbol = status >= 400 ? '✗' : '✓';
+    const methodStr = method.padEnd(5);
+    const pathStr = path.length > 35 ? path : path.padEnd(35);
+    const statusStr = statusColor(String(status).padStart(3));
+    const durationStr = `${durationMs}ms`.padStart(7);
+    const effectiveAccountId = accountId ?? defaultAccountId;
+    const acct = effectiveAccountId ? `  ${paint.dim(effectiveAccountId)}` : '';
+    const sourceColor = source === 'prod' ? paint.magenta : paint.cyan;
+    const sourceLabel = sourceColor(source.padEnd(5));
+    const line = `${methodStr}  ${pathStr}   ${statusStr}  ${durationStr}${acct}  ${statusColor(symbol)}  ${sourceLabel}`;
+    return detail ? `${line}\n      ${paint.dim('└')} ${paint.dim(detail)}` : line;
 }
 function makeDevRequestLogger(env, stderr, defaultAccountId) {
-    const isTTY = Boolean(stderr.isTTY);
-    const color = isTTY && env.NO_COLOR !== '1';
-    const dim = (s) => (color ? `\x1b[2m${s}\x1b[0m` : s);
-    const green = (s) => (color ? `\x1b[32m${s}\x1b[0m` : s);
-    const red = (s) => (color ? `\x1b[31m${s}\x1b[0m` : s);
-    const yellow = (s) => (color ? `\x1b[33m${s}\x1b[0m` : s);
-    const cyan = (s) => (color ? `\x1b[36m${s}\x1b[0m` : s);
-    const magenta = (s) => (color ? `\x1b[35m${s}\x1b[0m` : s);
-    return ({ method, path, status, durationMs, source = 'local', accountId, detail }) => {
-        const statusColor = status >= 500 ? red : status >= 400 ? yellow : green;
-        const symbol = status >= 400 ? '✗' : '✓';
-        const methodStr = method.padEnd(5);
-        const pathStr = path.length > 35 ? path : path.padEnd(35);
-        const statusStr = statusColor(String(status).padStart(3));
-        const durationStr = `${durationMs}ms`.padStart(7);
-        const effectiveAccountId = accountId ?? defaultAccountId;
-        const acct = effectiveAccountId ? `  ${dim(effectiveAccountId)}` : '';
-        const sourceColor = source === 'prod' ? magenta : cyan;
-        const sourceLabel = sourceColor(source.padEnd(5));
-        stderr.write(`  ${methodStr}  ${pathStr}   ${statusStr}  ${durationStr}${acct}  ${statusColor(symbol)}  ${sourceLabel}\n`);
-        if (detail) {
-            stderr.write(`        ${dim('└')} ${dim(detail)}\n`);
-        }
+    const paint = makeDevLogPaint(env, stderr);
+    return (entry) => {
+        const [line, detailLine] = formatDevLogEntry(entry, paint, defaultAccountId).split('\n');
+        stderr.write(`  ${line}\n`);
+        if (detailLine)
+            stderr.write(`  ${detailLine}\n`);
     };
 }
 async function resolveAccountIdOrPrompt(input) {
@@ -87,14 +95,18 @@ async function resolveAccountIdOrPrompt(input) {
     if (ids.length === 0)
         return { fromPrompt: false };
     const defaultId = store.defaultAccountId;
-    // Non-interactive, --json, or --yes: accept the configured default rather than
-    // silently degrading to "no account picked" — that path led deploy to exit 0
-    // after building artifacts only, looking like success.
-    const yes = input.argv.includes('--yes') || input.argv.includes('-y');
-    if (input.json || !isInteractive() || yes) {
-        if (defaultId && ids.includes(defaultId)) {
-            return { accountId: defaultId, fromPrompt: false };
-        }
+    // A configured default — or a single account — is an answer, not a question:
+    // use it silently, exactly like non-interactive runs. `--account-id` and
+    // `hs-x accounts switch` override; the picker remains only for the genuinely
+    // ambiguous case (multiple accounts, no default).
+    if (defaultId && ids.includes(defaultId)) {
+        return { accountId: defaultId, fromPrompt: false };
+    }
+    const soleAccount = ids.length === 1 ? ids[0] : undefined;
+    if (soleAccount) {
+        return { accountId: soleAccount, fromPrompt: false };
+    }
+    if (input.json || !isInteractive()) {
         return { fromPrompt: false };
     }
     const picked = await promptSelect({
@@ -113,15 +125,6 @@ async function resolveAccountIdOrPrompt(input) {
     });
     return picked ? { accountId: picked, fromPrompt: true } : { fromPrompt: false };
 }
-async function promptMissingText(message, current, validate) {
-    if (current && current.length > 0)
-        return current;
-    const answer = await promptText({
-        message,
-        ...(validate ? { validate } : {}),
-    });
-    return answer === undefined ? undefined : answer;
-}
 async function readHsxConfigProjectId(root) {
     try {
         const contents = await readFile(join(root, 'hsx.config.ts'), 'utf8');
@@ -144,6 +147,36 @@ function cancelledResult(argv, command) {
     reporter.info('Cancelled.');
     return { exitCode: 130 };
 }
+/**
+ * The default portal for a dev session, discovered rather than prompted:
+ * the resolved HS-X account's bound portal first (that pairing is explicit),
+ * then the HubSpot CLI config's default account — the same portal
+ * `hs project dev` would use. Undefined means local-only dev.
+ */
+async function resolveDefaultPortalId(input) {
+    try {
+        const { loadStore } = await import('../account-store.js');
+        const store = await loadStore();
+        const account = (input.accountId ? store.accounts[input.accountId] : undefined) ??
+            (store.defaultAccountId ? store.accounts[store.defaultAccountId] : undefined);
+        if (account?.hubspotPortalId)
+            return String(account.hubspotPortalId);
+    }
+    catch {
+        // fall through to the HubSpot CLI config
+    }
+    try {
+        const { discoverHubSpotAccounts } = await import('../hubspot-auth.js');
+        const discovered = await discoverHubSpotAccounts(input.root);
+        const account = discovered?.accounts.find((a) => a.isDefault) ?? discovered?.accounts[0];
+        if (account)
+            return String(account.portalId);
+    }
+    catch {
+        // no portal anywhere — run local-only
+    }
+    return undefined;
+}
 export async function devCommand({ argv, root, json, }) {
     if (argv[1] === 'cleanup') {
         return await devCleanupCommand({ argv, json });
@@ -151,6 +184,24 @@ export async function devCommand({ argv, root, json, }) {
     if (argv[1] === 'status') {
         return await devStatusCommand({ argv, json });
     }
+    if (!json && isInteractive()) {
+        try {
+            const selected = await resolveLocalProject({
+                root,
+                allowPrompt: true,
+                message: 'Which local project should run in dev mode?',
+                prompts: { select: promptSelect },
+            });
+            if (selected && selected.root !== root) {
+                return await devCommand({ argv, root: selected.root, json });
+            }
+        }
+        catch (error) {
+            if (error instanceof LocalProjectPickerCancelled)
+                return cancelledResult(argv, 'dev');
+            throw error;
+        }
+    }
     if (argv[1] === 'invoke') {
         return await devInvokeCommand({ argv, root, json });
     }
@@ -169,7 +220,9 @@ export async function devCommand({ argv, root, json, }) {
     const workers = await discoverWorkerManifests(root);
     await generateProjectArtifacts({ root, workers });
     let portalId = resolveFlag(argv, '--portal');
-    let targetOrigin = resolveFlag(argv, '--target-origin');
+    const targetOrigin = resolveFlag(argv, '--target-origin');
+    const telemetryOrigin = resolveFlag(argv, '--telemetry-origin');
+    const forceDevOverride = argv.includes('--force');
     const resolvedDevAcct = await resolveAccountIdOrPrompt({
         argv,
         json,
@@ -191,11 +244,10 @@ export async function devCommand({ argv, root, json, }) {
     // Control plane is a single deployed instance; default to it. Overrides
     // (env or flag) exist for self-host / local-cp test runs only.
     const controlPlaneUrl = formatConfigUrl(devCliConfig.controlPlaneUrl);
-    const developerId = resolveFlag(argv, '--developer-id') ??
-        devCliConfig.userId;
+    const developerId = resolveFlag(argv, '--developer-id') ?? devCliConfig.userId;
     const sessionId = resolveFlag(argv, '--session-id') ??
         `devsess_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
-    let ttlSeconds = Number(resolveFlag(argv, '--ttl-seconds') ?? '7200');
+    const ttlSeconds = Number(resolveFlag(argv, '--ttl-seconds') ?? '7200');
     const selectedCapabilities = resolveFlags(argv, '--capability');
     const allCapabilities = workers.flatMap((worker) => worker.capabilities
         .filter((capability) => capability.runtimeNeeds.includes('worker'))
@@ -205,37 +257,23 @@ export async function devCommand({ argv, root, json, }) {
         worker: worker.name,
     })));
     const allCapabilityIds = allCapabilities.map((c) => c.id);
-    if (!json && isInteractive() && (controlPlaneUrl || portalId || targetOrigin)) {
-        portalId = await promptMissingText('HubSpot portal id for dev override', portalId, (value) => /^\d+$/.test(value) ? undefined : 'Portal id must be numeric.');
-        if (portalId === undefined)
-            return cancelledResult(argv, 'dev');
-        targetOrigin = await promptMissingText('Public dev target origin', targetOrigin, (value) => {
-            try {
-                const url = new URL(value);
-                return url.protocol === 'https:' || url.hostname === '127.0.0.1' || url.hostname === 'localhost'
-                    ? undefined
-                    : 'Use an https URL, localhost, or 127.0.0.1.';
-            }
-            catch {
-                return 'Enter a valid URL.';
-            }
+    // Zero-prompt startup, like `hs project dev`: the portal id resolves from
+    // --portal → the HS-X account store → the HubSpot CLI config default; the
+    // override defaults to observe mode (no public target origin needed) and
+    // the TTL to 2h. --target-origin/--ttl-seconds stay as advanced flags, and
+    // nothing here ever blocks on a question.
+    if (portalId && !/^\d+$/.test(portalId)) {
+        const reporter = createReporter({ command: 'dev', argv });
+        const code = 'HSX_E_INPUT_BAD_FIELD';
+        reporter.error(code, `--portal must be numeric (got \`${portalId}\`).`, {
+            hint: 'Example: hs-x dev --portal 46993937',
+            docs_url: `https://hs-x.dev/errors/${code}`,
         });
-        if (targetOrigin === undefined)
-            return cancelledResult(argv, 'dev');
-        if (!resolveFlag(argv, '--ttl-seconds')) {
-            const ttl = await promptSelect({
-                message: 'Dev override TTL',
-                default: '7200',
-                options: [
-                    { value: '3600', label: '1 hour', description: 'short local session' },
-                    { value: '7200', label: '2 hours', description: 'default' },
-                    { value: '14400', label: '4 hours', description: 'long pairing/debugging session' },
-                ],
-            });
-            if (ttl === undefined)
-                return cancelledResult(argv, 'dev');
-            ttlSeconds = Number(ttl);
-        }
+        reporter.done(undefined, 10);
+        return { exitCode: 10 };
+    }
+    if (!portalId) {
+        portalId = await resolveDefaultPortalId({ root, accountId });
     }
     // Probe the HubSpot project IR up front so the picker can show UI-extension
     // nodes alongside HS-X capabilities. No-op if hsproject.json isn't present.
@@ -250,6 +288,7 @@ export async function devCommand({ argv, root, json, }) {
     const totalCandidates = allCapabilities.length + (uiExtensionNodes?.uids.length ?? 0);
     if (portalId &&
         !json &&
+        argv.includes('--pick') &&
         selectedCapabilities.length === 0 &&
         totalCandidates > 1 &&
         isInteractive()) {
@@ -284,16 +323,23 @@ export async function devCommand({ argv, root, json, }) {
             .map((v) => v.slice(UI_PREFIX.length));
     }
     let devOverrideRegistration;
+    let forcedDevOverrideCleanup = [];
     // We register a dev override whenever the user has a HubSpot portal in
     // play. `hs-x connect` gives us the portal id implicitly; only edge cases
     // (no connected account, no --portal flag) skip registration.
     const shouldRegisterOverride = Boolean(portalId);
     if (shouldRegisterOverride) {
+        const portalIdForOverride = portalId;
+        if (!portalIdForOverride) {
+            throw new Error('Dev override needs a HubSpot portal id. Pass --portal <id>.');
+        }
         if (!accountId) {
-            throw new Error('Dev override needs a connected HubSpot account. Run `hs-x connect` or pass --account-id.');
+            throw new Error('Dev override needs a connected HubSpot account. An authenticated personal access key ' +
+                '(what `hs-x doctor` reports) is not the same thing — dev needs the account bound to ' +
+                'this machine. Run `hs-x connect hubspot` or pass --account-id.');
         }
         if (!projectId) {
-            throw new Error('Could not determine project id. Add `name: "..."` to `hsx.config.ts`, set `HSX_PROJECT_ID`, or pass --project-id.');
+            throw new Error('Could not find an HS-X source project. Run from a directory containing `hsx.config.ts`, pass --cwd <project>, or set --project-id/HSX_PROJECT_ID for scripted override registration.');
         }
         if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0) {
             throw new Error('--ttl-seconds must be a positive number.');
@@ -309,13 +355,23 @@ export async function devCommand({ argv, root, json, }) {
             if (!targetOrigin) {
                 throw new Error('Dev override registration in --json mode requires --target-origin <url>.');
             }
+            forcedDevOverrideCleanup = forceDevOverride
+                ? await forceClearDevOverrideSessions({
+                    controlPlaneUrl,
+                    accountId,
+                    userId: developerId,
+                    projectId,
+                    portalId: portalIdForOverride,
+                    capabilityIds,
+                })
+                : [];
             devOverrideRegistration = await requestDevOverrideRegistration({
                 controlPlaneUrl,
                 accountId,
                 userId: developerId,
                 request: Schema.decodeUnknownSync(schemas.DevOverrideRegisterRequest)({
                     projectId,
-                    portalId,
+                    portalId: portalIdForOverride,
                     targetOrigin,
                     developerId,
                     sessionId,
@@ -331,6 +387,10 @@ export async function devCommand({ argv, root, json, }) {
             command: 'dev',
             url: `http://127.0.0.1:${port}`,
             workers,
+            ...(telemetryOrigin ? { telemetryOrigin } : {}),
+            ...(forcedDevOverrideCleanup.length > 0
+                ? { forcedCleanup: forcedDevOverrideCleanup }
+                : {}),
             ...(devOverrideRegistration
                 ? { mode: 'control-plane-dev-override', devOverrideRegistration }
                 : {}),
@@ -338,7 +398,17 @@ export async function devCommand({ argv, root, json, }) {
         return { exitCode: 0 };
     }
     const startupBegan = Date.now();
-    const renderRequestLog = makeDevRequestLogger(process.env, process.stderr, accountId);
+    // Requests print directly until the log-stream bus exists, then route
+    // through it as the `request` lane — so they respect the active filter and
+    // never trample the pinned status line.
+    const directRequestLog = makeDevRequestLogger(process.env, process.stderr, accountId);
+    let requestSink;
+    const renderRequestLog = (entry) => {
+        if (requestSink)
+            requestSink(entry);
+        else
+            directRequestLog(entry);
+    };
     const server = createServer((request, response) => {
         const requestStarted = Date.now();
         const method = request.method ?? 'GET';
@@ -362,6 +432,79 @@ export async function devCommand({ argv, root, json, }) {
             response.end(JSON.stringify({ workers }, null, 2));
             return;
         }
+        // Migrated UI-extension compatibility bridge. During `hs-x dev` its
+        // temporary trycloudflare.com origin points here, preserving the same
+        // /_hsx/cards/<id> contract as the deployed runtime while dispatching the
+        // current local handler body.
+        const cardMatch = /^\/_hsx\/cards\/([^/?]+)$/.exec(path.split('?', 1)[0] ?? path);
+        if (cardMatch && method === 'POST') {
+            const capabilityId = decodeURIComponent(cardMatch[1] ?? '');
+            const isCardBackend = allCapabilities.some((capability) => capability.id === capabilityId && capability.kind === 'card-backend');
+            if (!isCardBackend) {
+                response.writeHead(404, { 'content-type': 'application/json' });
+                response.end(JSON.stringify({ ok: false, error: 'unknown_card_backend', capabilityId }));
+                return;
+            }
+            const chunks = [];
+            request.on('data', (chunk) => chunks.push(chunk));
+            request.on('end', () => {
+                void (async () => {
+                    const respond = (status, body) => {
+                        response.writeHead(status, { 'content-type': 'application/json' });
+                        response.end(JSON.stringify(body, null, 2));
+                    };
+                    let parsed;
+                    try {
+                        const raw = Buffer.concat(chunks).toString('utf8');
+                        const value = raw.length > 0 ? JSON.parse(raw) : {};
+                        parsed = isRecord(value) ? value : {};
+                    }
+                    catch {
+                        respond(400, { ok: false, error: 'invalid_json' });
+                        return;
+                    }
+                    try {
+                        const { invokeCapabilityLocally, DevInvokeError, describeInvocationError } = await import('../dev/invoke.js');
+                        try {
+                            const outcome = await invokeCapabilityLocally({
+                                root,
+                                capabilityId,
+                                ...(parsed.input !== undefined ? { input: parsed.input } : {}),
+                                ...(parsed.enrolledObject !== undefined
+                                    ? { enrolledObject: parsed.enrolledObject }
+                                    : {}),
+                                ...(parsed.install !== undefined ? { install: parsed.install } : {}),
+                            });
+                            respond(outcome.status, outcome.body ?? null);
+                        }
+                        catch (error) {
+                            if (error instanceof DevInvokeError) {
+                                respond(error.code === 'HSX_E_DEV_UNKNOWN_CAPABILITY' ? 404 : 500, {
+                                    ok: false,
+                                    error: error.code,
+                                    message: error.message,
+                                    ...(error.hint ? { hint: error.hint } : {}),
+                                });
+                                return;
+                            }
+                            respond(500, {
+                                ok: false,
+                                error: 'HSX_E_INTERNAL',
+                                message: describeInvocationError(error),
+                            });
+                        }
+                    }
+                    catch (error) {
+                        respond(500, {
+                            ok: false,
+                            error: 'HSX_E_INTERNAL',
+                            message: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                })();
+            });
+            return;
+        }
         // Invocation harness over HTTP (P2): same engine as `hs-x dev invoke`,
         // for agents/CI/programs. Body: {input?, enrolledObject?, install?}.
         const invokeMatch = /^\/_hsx\/invoke\/([^/?]+)$/.exec(path.split('?', 1)[0] ?? path);
@@ -472,6 +615,25 @@ export async function devCommand({ argv, root, json, }) {
     const capabilityCount = workers.reduce((c, w) => c + w.capabilities.length, 0);
     const subject = devOverrideRegistration ? `portal ${devOverrideRegistration.portalId}` : 'local';
     const url = `http://127.0.0.1:${port}`;
+    // A freshly migrated card has no deployed Worker origin yet. Give its
+    // generated compatibility shim a public quick-tunnel origin that points at
+    // this local server, and stamp the source/allow-list before HubSpot's
+    // UI-extension dev session translates and bundles the project.
+    const { hasMigratedCardServerlessShim, prepareMigratedCardDevArtifacts } = await import('../dev/migrated-card.js');
+    const shouldStartMigratedCardTunnel = Boolean(selectedUiNodeUids?.length) && (await hasMigratedCardServerlessShim(root));
+    const migratedCardTunnel = shouldStartMigratedCardTunnel
+        ? await startHsxDevTunnel({
+            port,
+            reporter,
+            label: 'Migrated card backend tunnel',
+        })
+        : undefined;
+    const migratedCardDevArtifacts = migratedCardTunnel
+        ? await prepareMigratedCardDevArtifacts({
+            root,
+            runtimeOrigin: migratedCardTunnel.url,
+        })
+        : undefined;
     // Optional: start a HubSpot UI-extension dev session if this directory
     // contains an hsproject.json AND the user selected at least one UI node.
     const hubSpotDevSession = selectedUiNodeUids && selectedUiNodeUids.length > 0
@@ -488,22 +650,64 @@ export async function devCommand({ argv, root, json, }) {
     // events) from inside the card iframe and surfaces them in the terminal.
     // Stable default port 9099 so card code can hard-default the dev-log URL.
     const hsxLogPort = Number(resolveFlag(argv, '--hsx-log-port') ?? '9099');
+    // `--only` selectors pre-filter the stream (same grammar as the interactive
+    // keyboard, see dev/stream-filter.ts). Invalid selectors are a usage error.
+    const { parseOnlySelectors } = await import('../dev/stream-filter.js');
+    const onlyParsed = parseOnlySelectors(resolveFlags(argv, '--only'));
+    if (!onlyParsed.ok) {
+        const code = 'HSX_E_DEV_BAD_ONLY';
+        reporter.error(code, onlyParsed.message, {
+            hint: 'Selectors: frontend, backend, request, hubspot, errors, warnings, cap:<id>, or free text. Repeat --only to combine.',
+            docs_url: `https://hs-x.dev/errors/${code}`,
+        });
+        reporter.done(undefined, 2);
+        return { exitCode: 2 };
+    }
     const devLogStream = await startHsxDevLogStream({
         port: hsxLogPort,
+        root,
         reporter,
+        filter: onlyParsed.filter,
     });
+    if (devLogStream) {
+        const paint = makeDevLogPaint(process.env, process.stderr);
+        requestSink = (entry) => {
+            devLogStream.bus.emit({
+                lane: 'request',
+                level: entry.status >= 500 ? 'error' : entry.status >= 400 ? 'warn' : 'info',
+                ts: Date.now(),
+                msg: formatDevLogEntry(entry, paint, accountId),
+            });
+        };
+    }
     // Auto-managed Cloudflare quick tunnel — gives the deployed Worker a public
     // URL to POST telemetry envelopes to the local sidecar. The developer must
     // never have to run cloudflared themselves; that's a non-negotiable default.
-    const devTunnel = shouldRegisterOverride
+    const devTunnel = shouldRegisterOverride && !telemetryOrigin
         ? await startHsxDevTunnel({ port: hsxLogPort, reporter })
         : undefined;
+    const telemetryBaseUrl = telemetryOrigin ?? devTunnel?.url;
     // Now register the dev override. If the developer didn't pass
     // `--target-origin`, default to observe mode and let the deployed Worker
     // run as normal — we only need the tunnel for the telemetry tee.
     if (shouldRegisterOverride && controlPlaneUrl && portalId && accountId && projectId) {
+        if (forceDevOverride) {
+            forcedDevOverrideCleanup = await forceClearDevOverrideSessions({
+                controlPlaneUrl,
+                accountId,
+                userId: developerId,
+                projectId,
+                portalId,
+                capabilityIds,
+            });
+            if (forcedDevOverrideCleanup.length > 0) {
+                reporter
+                    .step(`Cleared ${forcedDevOverrideCleanup.reduce((count, item) => count + item.cleared.length, 0)} existing dev override${forcedDevOverrideCleanup.length === 1 ? '' : 's'}`)
+                    .ok();
+            }
+        }
         const overrideMode = targetOrigin ? 'proxy' : 'observe';
-        const effectiveTargetOrigin = targetOrigin ?? devTunnel?.url ?? `http://127.0.0.1:${hsxLogPort}`;
+        const effectiveTargetOrigin = targetOrigin ?? telemetryBaseUrl ?? `http://127.0.0.1:${hsxLogPort}`;
         devOverrideRegistration = await requestDevOverrideRegistration({
             controlPlaneUrl,
             accountId,
@@ -517,18 +721,86 @@ export async function devCommand({ argv, root, json, }) {
                 capabilityIds,
                 ttlSeconds,
                 mode: overrideMode,
-                ...(devTunnel ? { telemetryUrl: `${devTunnel.url}/__hsx/event` } : {}),
+                ...(telemetryBaseUrl && devLogStream
+                    ? { telemetryUrl: devTelemetryUrl(telemetryBaseUrl, devLogStream.authToken) }
+                    : {}),
             }),
         });
     }
-    // Vercel-style header: arrow, command, subject, → URL
-    renderDevHeader(process.env, process.stderr, { subject, url });
-    reporter.info(`Ready in ${elapsed}ms — ${workers.length} worker${workers.length === 1 ? '' : 's'} · ${capabilityCount} capabilit${capabilityCount === 1 ? 'y' : 'ies'}${devOverrideRegistration ? ` · portal ${devOverrideRegistration.portalId}` : ''}${hubSpotDevSession ? ` · ui-extension session ${hubSpotDevSession.sessionId}` : ''}${devLogStream ? ` · log stream ${devLogStream.url}` : ''}${devTunnel ? ` · tunnel ${devTunnel.url}` : ''}`);
-    reporter.info('');
-    reporter.info('Press Ctrl+C to stop');
+    // Railed startup checklist: identity header, then one row per surface.
+    reporter.header(subject);
+    reporter.rows([
+        { status: 'ok', key: 'server', value: url, detail: `ready in ${elapsed}ms` },
+        {
+            status: 'ok',
+            key: 'workers',
+            value: `${workers.length} worker${workers.length === 1 ? '' : 's'} · ${capabilityCount} capabilit${capabilityCount === 1 ? 'y' : 'ies'}`,
+        },
+        ...(devOverrideRegistration
+            ? [
+                {
+                    status: 'ok',
+                    key: 'portal',
+                    value: String(devOverrideRegistration.portalId),
+                    detail: 'dev override registered',
+                },
+            ]
+            : []),
+        ...(hubSpotDevSession
+            ? [
+                {
+                    status: 'ok',
+                    key: 'ui-extensions',
+                    value: `session ${hubSpotDevSession.sessionId}`,
+                },
+            ]
+            : []),
+        ...(devLogStream
+            ? [{ status: 'ok', key: 'logs', value: `streaming on ${devLogStream.url}` }]
+            : []),
+        ...(devTunnel ? [{ status: 'ok', key: 'tunnel', value: devTunnel.url }] : []),
+        ...(migratedCardDevArtifacts
+            ? [
+                {
+                    status: 'ok',
+                    key: 'card backends',
+                    value: migratedCardDevArtifacts.runtimeOrigin,
+                    detail: 'temporary dev origin',
+                },
+            ]
+            : []),
+        ...(telemetryOrigin
+            ? [{ status: 'ok', key: 'telemetry', value: telemetryOrigin }]
+            : []),
+    ]);
+    if (!portalId) {
+        reporter.info('No HubSpot portal found — running local-only. Pass `--portal <id>` (or set a default with `hs auth` / `hs-x login`) to mirror a live portal.');
+    }
+    // The pinned status line carries the key map (incl. quit); repeating it in
+    // an info line doubled the hints. Only sessions without the status line
+    // (non-TTY, NO_COLOR) get a stop instruction.
+    if (!devLogStream?.renderer.hasStatusLine()) {
+        reporter.info('');
+        reporter.info('Press Ctrl+C to stop');
+    }
     reporter.info('');
+    // Interactive stream controls — single keystrokes filter/pause the unified
+    // log stream. No-op when stdin is not a TTY.
+    const keyboard = devLogStream
+        ? (await import('../dev/keyboard.js')).attachDevKeyboard({
+            renderer: devLogStream.renderer,
+            onQuit: () => process.kill(process.pid, 'SIGINT'),
+        })
+        : undefined;
+    devLogStream?.renderer.ready();
     await new Promise((resolveClose) => {
         const close = async () => {
+            keyboard?.stop();
+            // Signal-driven shutdown can terminate the Bun process before awaited
+            // cleanup settles. Restore temporarily stamped migration sources
+            // synchronously first; the remaining network/process cleanup is
+            // best-effort and may safely await.
+            migratedCardDevArtifacts?.restoreSync();
             if (hubSpotDevSession) {
                 try {
                     await hubSpotDevSession.cleanup();
@@ -552,6 +824,22 @@ export async function devCommand({ argv, root, json, }) {
                     // best-effort: tunnel cleanup failures should not block exit.
                 }
             }
+            if (migratedCardDevArtifacts) {
+                try {
+                    await migratedCardDevArtifacts.restore();
+                }
+                catch {
+                    // best-effort: source restoration should not block shutdown.
+                }
+            }
+            if (migratedCardTunnel) {
+                try {
+                    await migratedCardTunnel.cleanup();
+                }
+                catch {
+                    // best-effort: tunnel cleanup failures should not block exit.
+                }
+            }
             if (devLogStream) {
                 try {
                     await devLogStream.cleanup();
@@ -575,11 +863,44 @@ async function startHsxDevLogStream(input) {
             import('../dev/stream-renderer.js'),
         ]);
         const bus = createDevEventBus();
-        const server = await startDevLogServer({ bus, port: input.port });
-        const renderer = startDevStreamRenderer({ bus });
+        const authToken = randomBytes(32).toString('base64url');
+        const server = await startDevLogServer({ bus, port: input.port, authToken });
+        const renderer = startDevStreamRenderer({
+            bus,
+            deferStatus: true,
+            ...(input.filter ? { filter: input.filter } : {}),
+        });
+        // HubSpot-side lane: renders/proxy failures that never reach our Worker
+        // only exist in HubSpot's app logs — poll them into the same stream.
+        // Missing binding/credentials just means the lane stays off; `hs-x dev`
+        // must work without HubSpot credentials.
+        let hubspotPoller;
+        try {
+            const [{ resolveHubSpotLogsSource }, { startHubSpotLogsPoller }] = await Promise.all([
+                import('../hubspot-app-logs.js'),
+                import('../dev/hubspot-logs-poller.js'),
+            ]);
+            const resolution = await resolveHubSpotLogsSource({ cwd: input.root });
+            if (resolution.ok) {
+                hubspotPoller = startHubSpotLogsPoller({ bus, source: resolution.source });
+                bus.emit({
+                    lane: 'hubspot',
+                    level: 'debug',
+                    ts: Date.now(),
+                    msg: `lane active — polling HubSpot app logs for app ${resolution.source.appId}`,
+                });
+            }
+        }
+        catch {
+            // The HubSpot lane is additive; never fail the dev stream over it.
+        }
         return {
             url: server.url,
+            authToken,
+            renderer,
+            bus,
             async cleanup() {
+                hubspotPoller?.stop();
                 renderer.stop();
                 await server.close();
             },
@@ -590,8 +911,13 @@ async function startHsxDevLogStream(input) {
         return undefined;
     }
 }
+function devTelemetryUrl(tunnelUrl, authToken) {
+    const url = new URL('/__hsx/event', tunnelUrl);
+    url.searchParams.set('hsx_dev_token', authToken);
+    return url.toString();
+}
 async function startHsxDevTunnel(input) {
-    const step = input.reporter.step('Cloudflare quick tunnel');
+    const step = input.reporter.step(input.label ?? 'Cloudflare quick tunnel');
     try {
         const { startCloudflaredTunnel } = await import('../dev/tunnel.js');
         const tunnel = await startCloudflaredTunnel({ port: input.port });
@@ -803,12 +1129,45 @@ async function devInvokeCommand({ argv, root, json, }) {
     else {
         step.fail(`status ${outcome.status}`);
     }
-    for (const line of JSON.stringify(responseBody ?? null, null, 2).split('\n')) {
-        reporter.info(`  ${line}`);
+    // Human view: the handler's output fields on the rail at full brightness —
+    // the wire envelope stays on `--json`. Falls back to the raw body when the
+    // response has no extractable output record (errors, bespoke shapes).
+    const outputRecord = extractInvokeOutput(responseBody);
+    if (invocationOk && outputRecord) {
+        reporter.rows(Object.entries(outputRecord).map(([key, value]) => ({
+            key,
+            value: typeof value === 'string' ? value : JSON.stringify(value),
+        })));
+        reporter.info('');
+        reporter.info('Full payload: re-run with `--json`');
+    }
+    else {
+        for (const line of JSON.stringify(responseBody ?? null, null, 2).split('\n')) {
+            reporter.info(`  ${line}`);
+        }
     }
     reporter.done(invocationOk ? 'Invoked' : 'Failed', invocationOk ? 0 : 1);
     return { exitCode: invocationOk ? 0 : 1 };
 }
+/**
+ * Pull the handler's own output out of the invoke response envelope:
+ * tools/actions nest it at `result.output`; card backends return the
+ * handler's object as the body. Returns undefined when there is nothing
+ * row-shaped to show.
+ */
+function extractInvokeOutput(body) {
+    if (!isRecordValue(body))
+        return undefined;
+    const result = body.result;
+    if (isRecordValue(result) && isRecordValue(result.output)) {
+        return result.output;
+    }
+    if (isRecordValue(result) && !('output' in result))
+        return result;
+    if (!('ok' in body) && !('result' in body))
+        return body;
+    return undefined;
+}
 function isRecordValue(value) {
     return typeof value === 'object' && value !== null;
 }
@@ -1009,6 +1368,27 @@ async function requestDevOverrideCleanup({ controlPlaneUrl, accountId, userId, s
     }
     return Schema.decodeUnknownSync(schemas.DevOverrideClearResponse)(body);
 }
+async function forceClearDevOverrideSessions({ controlPlaneUrl, accountId, userId, projectId, portalId, capabilityIds, }) {
+    const active = await requestDevOverrideStatus({ controlPlaneUrl, accountId, userId });
+    const wantedCapabilities = new Set(capabilityIds);
+    const sessions = [
+        ...new Set(active.overrides
+            .filter((override) => override.projectId === projectId &&
+            override.portalId === portalId &&
+            wantedCapabilities.has(override.capabilityId))
+            .map((override) => override.sessionId)),
+    ];
+    const cleared = [];
+    for (const sessionId of sessions) {
+        cleared.push(await requestDevOverrideCleanup({
+            controlPlaneUrl,
+            accountId,
+            userId,
+            sessionId,
+        }));
+    }
+    return cleared;
+}
 async function discoverWorkerManifests(root, options = {}) {
     const files = await collectFiles(join(root, 'src'));
     const workers = [];
@@ -1355,6 +1735,7 @@ const devUrlOption = Options.text('url').pipe(Options.optional);
 const portOption = Options.text('port').pipe(Options.optional);
 const portalOption = Options.text('portal').pipe(Options.optional);
 const targetOriginOption = Options.text('target-origin').pipe(Options.optional);
+const telemetryOriginOption = Options.text('telemetry-origin').pipe(Options.optional);
 const accountIdOption = Options.text('account-id').pipe(Options.optional);
 const projectIdOption = Options.text('project-id').pipe(Options.optional);
 const developerIdOption = Options.text('developer-id').pipe(Options.optional);
@@ -1365,9 +1746,12 @@ const hsxLogPortOption = Options.text('hsx-log-port').pipe(Options.optional);
 const controlPlaneUrlOption = Options.text('control-plane-url').pipe(Options.optional);
 const runtimeControlPlaneUrlOption = Options.text('runtime-control-plane-url').pipe(Options.optional);
 const capabilityOption = Options.text('capability').pipe(Options.repeated);
+const onlyOption = Options.text('only').pipe(Options.repeated);
+const pickOption = Options.boolean('pick').pipe(Options.withDefault(false));
 const noHubspotOption = Options.boolean('no-hubspot').pipe(Options.withDefault(false));
 const noUiExtensionsOption = Options.boolean('no-ui-extensions').pipe(Options.withDefault(false));
 const yesOption = Options.boolean('yes').pipe(Options.withAlias('y'), Options.withDefault(false));
+const forceOption = Options.boolean('force').pipe(Options.withDefault(false));
 export const devCmd = Command.make('dev', {
     json: jsonOption,
     cwd: cwdOption,
@@ -1382,6 +1766,7 @@ export const devCmd = Command.make('dev', {
     port: portOption,
     portal: portalOption,
     targetOrigin: targetOriginOption,
+    telemetryOrigin: telemetryOriginOption,
     accountId: accountIdOption,
     projectId: projectIdOption,
     developerId: developerIdOption,
@@ -1392,9 +1777,12 @@ export const devCmd = Command.make('dev', {
     controlPlaneUrl: controlPlaneUrlOption,
     runtimeControlPlaneUrl: runtimeControlPlaneUrlOption,
     capability: capabilityOption,
+    only: onlyOption,
+    pick: pickOption,
     noHubspot: noHubspotOption,
     noUiExtensions: noUiExtensionsOption,
     yes: yesOption,
+    force: forceOption,
 }, (opts) => runHandler('dev', { json: opts.json }, Effect.gen(function* () {
     // root: injected cwd, overridden by --cwd.
     const injectedCwd = yield* Cwd;
@@ -1428,6 +1816,9 @@ export const devCmd = Command.make('dev', {
     if (Option.isSome(opts.targetOrigin)) {
         argv.push('--target-origin', opts.targetOrigin.value);
     }
+    if (Option.isSome(opts.telemetryOrigin)) {
+        argv.push('--telemetry-origin', opts.telemetryOrigin.value);
+    }
     if (Option.isSome(opts.accountId))
         argv.push('--account-id', opts.accountId.value);
     if (Option.isSome(opts.projectId))
@@ -1451,13 +1842,19 @@ export const devCmd = Command.make('dev', {
     }
     for (const capability of opts.capability)
         argv.push('--capability', capability);
+    for (const only of opts.only)
+        argv.push('--only', only);
+    if (opts.pick)
+        argv.push('--pick');
     if (opts.noHubspot)
         argv.push('--no-hubspot');
     if (opts.noUiExtensions)
         argv.push('--no-ui-extensions');
     if (opts.yes)
         argv.push('--yes');
-    yield* runQuarantined(opts.json, () => devCommand({ argv, root, json: opts.json }));
+    if (opts.force)
+        argv.push('--force');
+    yield* runQuarantined('dev', opts.json, () => devCommand({ argv, root, json: opts.json }));
 })));
 /**
  * `hs-x dev invoke --remote`: dispatch at the DEPLOYED Worker, where install
@@ -1520,9 +1917,7 @@ async function devInvokeRemote(args) {
     });
     const durationMs = Date.now() - startedAt;
     const body = outcome.body;
-    const ok = outcome.status >= 200 &&
-        outcome.status < 300 &&
-        (!isRecordValue(body) || body.ok !== false);
+    const ok = outcome.status >= 200 && outcome.status < 300 && (!isRecordValue(body) || body.ok !== false);
     const reporter = createReporter({ command: 'dev invoke', argv, entry: !json });
     if (json) {
         process.stdout.write(`${JSON.stringify({