@hs-x/cli 0.4.12 → 0.4.13

package/dist/commands/dev.d.ts

@@ -28,6 +28,7 @@ export declare const devCmd: Command.Command<"dev", Cwd, CliError, {
     readonly testingAccount: Option.Option<string>;
     readonly profile: Option.Option<string>;
     readonly preserveState: boolean;
+    readonly localProxy: "auto" | "always" | "never";
     readonly targetOrigin: Option.Option<string>;
     readonly telemetryOrigin: Option.Option<string>;
     readonly accountId: Option.Option<string>;

package/dist/commands/dev.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/commands/dev.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,OAAO,MAAM,qBAAqB,CAAC;AAI/C,OAAO,EAAU,MAAM,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,EAAE,KAAK,QAAQ,EAAY,MAAM,iBAAiB,CAAC;AA2C1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AA6zBzC,wBAAsB,UAAU,CAAC,EAC/B,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,QAAQ,GACT,EAAE;IACD,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;CAC9B,GAAG,OAAO,CAAC,SAAS,CAAC,CAuErB;AA+mFD,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmJlB,CAAC"}
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/commands/dev.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,OAAO,MAAM,qBAAqB,CAAC;AAI/C,OAAO,EAAU,MAAM,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,EAAE,KAAK,QAAQ,EAAY,MAAM,iBAAiB,CAAC;AAwD1D,OAAO,KAAK,EAAE,QAAQ,EAAe,MAAM,sBAAsB,CAAC;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAm9BzC,wBAAsB,UAAU,CAAC,EAC/B,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,QAAQ,GACT,EAAE;IACD,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;CAC9B,GAAG,OAAO,CAAC,SAAS,CAAC,CA0ErB;AA+yFD,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqJlB,CAAC"}

package/dist/commands/dev.js

@@ -15,13 +15,14 @@ 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 { selectHubSpotDirectDevAccounts } from '../dev/account-selection.js';
-import { listHubSpotDevComponentCandidates, resolveHubSpotDevComponentSelectors, resolveHubSpotDevSessionApp, } from '../dev/component-selection.js';
+import { describeHubSpotDevTestingChoice, describeHubSpotDevTestingPlanReason, planHubSpotDevTestingAccount, selectHubSpotDirectDevAccounts, } from '../dev/account-selection.js';
+import { findHubSpotDevApplication, isHubSpotMarketplaceApp, listHubSpotDevComponentCandidates, resolveHubSpotDevComponentSelectors, resolveHubSpotDevSessionApp, } from '../dev/component-selection.js';
+import { resolveHubSpotLocalProxyMode } from '../dev/local-proxy.js';
 import { createManagedDevEventWriter, createManagedDevSession, markManagedDevSessionReady, markManagedDevSessionState, prepareManagedDevSessionRestart, publicManagedDevSession, readManagedDevEvents, readManagedDevSession, reconcileManagedDevSession, setManagedDevSessionPid, stopManagedDevSessionProcess, waitForManagedDevSessionOwner, } from '../dev/managed-session.js';
 import { findListeningProcess, isHubSpotDevPortConflict, stopProcessCommand, terminateProcessGracefully, } from '../dev/port-process.js';
 import { executeCliHttp } from '../effect-http.js';
 import { discoverHubSpotAccounts, exchangePak } from '../hubspot-auth.js';
-import { detectLocalProjectMode, validateHubSpotProject } from '../hubspot-project.js';
+import { detectLocalProjectMode, findContainingProjectRoot, validateHubSpotProject, } from '../hubspot-project.js';
 import { LocalProjectPickerCancelled, resolveLocalProject } from '../local-project-picker.js';
 import { requestMutationConsent } from '../mutation-consent.js';
 import { isMachineOutput } from '../output-context.js';
@@ -281,6 +282,7 @@ async function hubSpotDirectDevCommand({ argv, root, json, }) {
     const reporter = createReporter({ command: 'dev', argv, entry: !json });
     const profile = resolveFlag(argv, '--profile');
     const preserveState = argv.includes('--preserve-state');
+    const yes = argv.some((argument) => argument === '--yes' || argument === '-y');
     const validation = await validateHubSpotProject({ root, ...(profile ? { profile } : {}) });
     if (!validation.ok) {
         const result = {
@@ -363,15 +365,62 @@ async function hubSpotDirectDevCommand({ argv, root, json, }) {
         }
         return { exitCode: 1 };
     }
-    const testingAccount = selectedTestingAccount ?? projectAccount;
+    // Mirror `hs project dev`: recommend a developer test account or sandbox,
+    // and never land on the production project account without saying so.
+    const testingPlan = planHubSpotDevTestingAccount({
+        accounts,
+        projectAccount,
+        // selectHubSpotDirectDevAccounts defaults the testing account to the
+        // project account; only an explicit flag counts as an answer here.
+        selectedTestingAccount: requestedTestingAccount ? selectedTestingAccount : undefined,
+        interactive: !json && !yes && isInteractive(),
+    });
+    let testingAccount;
+    let testingChoice;
+    if (testingPlan.kind === 'prompt') {
+        const picked = await promptSelect({
+            message: 'Choose the account to test on',
+            options: testingPlan.choices.map((choice) => ({
+                value: String(choice.account.portalId),
+                ...describeHubSpotDevTestingChoice(choice),
+            })),
+            default: String(testingPlan.choices[0]?.account.portalId),
+        });
+        if (picked === undefined)
+            return cancelledResult(argv, 'dev');
+        const choice = testingPlan.choices.find((item) => String(item.account.portalId) === picked);
+        if (!choice)
+            return cancelledResult(argv, 'dev');
+        testingAccount = choice.account;
+        testingChoice = choice.kind;
+        reporter.info(`Testing on ${testingAccount.name} (${testingAccount.portalId}) — ${describeTestingChoiceForRow(testingChoice)}`);
+    }
+    else {
+        testingAccount = testingPlan.account;
+        testingChoice = testingPlan.choice;
+        if (!json) {
+            const explanation = describeHubSpotDevTestingPlanReason(testingPlan);
+            if (explanation.level === 'warn') {
+                reporter.warn('HSX_W_DEV_TESTING_ON_PRODUCTION_ACCOUNT', explanation.message);
+            }
+            else {
+                reporter.info(explanation.message);
+            }
+        }
+    }
     if (testingAccount.personalAccessKey) {
+        const credentialStep = json
+            ? undefined
+            : reporter.step(`Checking ${testingAccount.name} (${testingAccount.portalId}) credentials`);
         try {
             const exchanged = await exchangePak(testingAccount.personalAccessKey);
             if (exchanged.portalId !== testingAccount.portalId) {
                 throw new Error(`the configured PAK belongs to account ${exchanged.portalId}, not ${testingAccount.portalId}`);
             }
+            credentialStep?.ok();
         }
         catch (cause) {
+            credentialStep?.fail();
             const message = `HubSpot testing account ${testingAccount.name} (${testingAccount.portalId}) needs fresh authentication: ${cause instanceof Error ? cause.message : String(cause)} Run \`hs account auth\` for that account, then retry.`;
             if (json) {
                 write(`${JSON.stringify({
@@ -394,12 +443,19 @@ async function hubSpotDirectDevCommand({ argv, root, json, }) {
     const existingDevServer = await recoverHubSpotDevPort({ argv, json, reporter });
     if (existingDevServer.kind === 'exit')
         return existingDevServer.result;
+    const probeStep = json ? undefined : reporter.step('Reading HubSpot project components');
     const uiExtensionNodes = await probeHubSpotUiNodes({
         root,
         portalIdFlag: String(projectAccount.portalId),
         accountId: undefined,
         ...(profile ? { profile } : {}),
     });
+    if (uiExtensionNodes) {
+        probeStep?.ok(`${uiExtensionNodes.candidates.length} component${uiExtensionNodes.candidates.length === 1 ? '' : 's'}${uiExtensionNodes.application?.name ? ` · ${uiExtensionNodes.application.name}` : ''}`);
+    }
+    else {
+        probeStep?.warn('no UI-extension components found');
+    }
     const requestedComponents = resolveFlags(argv, '--component');
     const resolvedComponents = resolveHubSpotDevComponentSelectors(uiExtensionNodes?.candidates ?? [], requestedComponents);
     const requestedAppCheck = resolvedComponents.ok && requestedComponents.length > 0
@@ -456,6 +512,48 @@ async function hubSpotDirectDevCommand({ argv, root, json, }) {
             return cancelledResult(argv, 'dev');
         selectedNodeUids = picked;
     }
+    // `hs project dev` warns before developing a marketplace app that real
+    // portals have installed. Same check, same numbers, same default of "no".
+    let productionInstallCount;
+    const application = uiExtensionNodes?.application;
+    if (isHubSpotMarketplaceApp(application) && application && projectAccount.personalAccessKey) {
+        const appLabel = application.name ?? application.uid;
+        const installStep = json
+            ? undefined
+            : reporter.step(`Checking ${appLabel} production installs`);
+        const check = await checkProductionInstallsForDev({
+            root,
+            projectAccount,
+            application,
+        });
+        if (!check.ok) {
+            installStep?.warn('could not check');
+            if (!json)
+                reporter.warn('HSX_W_DEV_PRODUCTION_APP_CHECK_FAILED', check.reason);
+        }
+        else if (check.installCount === 0) {
+            installStep?.ok('none');
+        }
+        else {
+            installStep?.warn(`${check.installCount} ${check.installCount === 1 ? 'account' : 'accounts'}`);
+            productionInstallCount = check.installCount;
+            const { describeHubSpotProductionInstallWarning, HUBSPOT_PRODUCTION_APP_CONFIRMATION } = await import('../dev/production-app-check.js');
+            const warning = describeHubSpotProductionInstallWarning(application.name ?? application.uid, check.installCount);
+            if (!json)
+                reporter.warn('HSX_W_DEV_PRODUCTION_APP_INSTALLS', warning);
+            if (!json && !yes && isInteractive()) {
+                const proceed = await promptConfirm({
+                    message: HUBSPOT_PRODUCTION_APP_CONFIRMATION,
+                    default: false,
+                    // The checks above take seconds; an Enter mashed meanwhile must not
+                    // answer "no" on the user's behalf.
+                    discardTypeAhead: true,
+                });
+                if (!proceed)
+                    return cancelledResult(argv, 'dev');
+            }
+        }
+    }
     let directDevLogStream;
     if (!json) {
         const hsxLogPortValue = resolveFlag(argv, '--hsx-log-port') ?? '9099';
@@ -486,6 +584,7 @@ async function hubSpotDirectDevCommand({ argv, root, json, }) {
             root,
             reporter,
             filter: onlyParsed.filter,
+            hubspotAccount: projectAccount,
             ...(managedSessionId ? { managedSessionId } : {}),
         });
     }
@@ -497,6 +596,16 @@ async function hubSpotDirectDevCommand({ argv, root, json, }) {
         ...(selectedNodeUids ? { selectedNodeUids } : {}),
         ...(profile ? { profile } : {}),
         preserveState,
+        localProxyMode: resolveLocalProxyMode(argv),
+        ...(directDevLogStream
+            ? {
+                relayUrl: directDevLogStream.url,
+                onRelayReady: (handle) => {
+                    if (directDevLogStream)
+                        directDevLogStream.relay.current = handle;
+                },
+            }
+            : {}),
         onHeartbeatError: (failure) => {
             const warning = describeHeartbeatFailure(failure, testingAccount.portalId);
             if (!warning)
@@ -609,11 +718,15 @@ async function hubSpotDirectDevCommand({ argv, root, json, }) {
         portalId: testingAccount.portalId,
         projectAccountId: projectAccount.portalId,
         testingAccountId: testingAccount.portalId,
+        testingAccountKind: testingChoice,
+        ...(productionInstallCount !== undefined ? { productionInstallCount } : {}),
         sessionId: session.sessionId,
         components: session.nodeUids,
         controlPlaneUsed: false,
         cloudflareUsed: false,
-        preserveState,
+        preserveState: preserveState && session.frontendLogs.active,
+        frontendLogs: session.frontendLogs,
+        localProxy: session.localProxy,
     };
     if (json)
         write(`${JSON.stringify(started, null, 2)}\n`);
@@ -622,22 +735,57 @@ async function hubSpotDirectDevCommand({ argv, root, json, }) {
         reporter.rows([
             { key: 'mode', value: 'HubSpot direct' },
             { key: 'project-account', value: `${projectAccount.name} (${projectAccount.portalId})` },
-            { key: 'testing-account', value: `${testingAccount.name} (${testingAccount.portalId})` },
+            {
+                key: 'testing-account',
+                value: `${testingAccount.name} (${testingAccount.portalId})`,
+                detail: describeTestingChoiceForRow(testingChoice),
+                ...(testingChoice === 'production'
+                    ? { status: 'warn' }
+                    : { status: 'ok' }),
+            },
+            ...(productionInstallCount !== undefined
+                ? [
+                    {
+                        key: 'production installs',
+                        value: `${productionInstallCount} ${productionInstallCount === 1 ? 'account' : 'accounts'}`,
+                        detail: 'local changes can affect these installs',
+                        status: 'warn',
+                    },
+                ]
+                : []),
             { key: 'ui-extensions', value: `session ${session.sessionId}`, status: 'ok' },
             { key: 'components', value: String(session.nodeUids.length) },
-            ...(preserveState
+            ...(preserveState && session.frontendLogs.active
                 ? [{ key: 'reload state', value: 'JSON-safe React useState values', status: 'ok' }]
                 : []),
             ...(directDevLogStream
                 ? [
                     {
                         key: 'logs',
-                        value: 'frontend + backend + HubSpot events',
-                        detail: directDevLogStream.url,
+                        value: [
+                            ...(session.frontendLogs.active ? ['frontend'] : []),
+                            'backend',
+                            ...(directDevLogStream.hubspotLane.active ? ['HubSpot events'] : []),
+                        ].join(' + '),
+                        detail: session.frontendLogs.transport === 'fetch'
+                            ? `${directDevLogStream.url} · card logs via HubSpot local proxy`
+                            : directDevLogStream.url,
                         status: 'ok',
                     },
+                    hubspotLogsLaneRow(directDevLogStream.hubspotLane),
+                ]
+                : []),
+            ...(session.frontendLogs.unavailableReason
+                ? [
+                    {
+                        key: 'frontend logs',
+                        value: 'off',
+                        detail: session.frontendLogs.unavailableReason,
+                        status: 'warn',
+                    },
                 ]
                 : []),
+            ...localProxyRows(session.localProxy),
             { key: 'Cloudflare', value: 'not used' },
             { key: 'HS-X control plane', value: 'not used' },
         ]);
@@ -707,6 +855,9 @@ const KNOWN_DEV_SUBCOMMANDS = new Set([...MANAGED_DEV_SUBCOMMANDS, 'invoke', 'cl
 const MANAGED_DEV_LANES = new Set(['frontend', 'backend', 'request', 'hubspot']);
 const MANAGED_DEV_LEVELS = new Set(['debug', 'info', 'warn', 'error']);
 export async function devCommand({ argv, root, json, reporter, }) {
+    // Resolve once before direct/enhanced mode detection and managed-session
+    // creation so starting in src/app uses the same project, bindings, and cwd.
+    root = (await findContainingProjectRoot(root)) ?? root;
     const managedSessionId = resolveFlag(argv, '--managed-session');
     if (managedSessionId) {
         await waitForManagedDevSessionOwner(managedSessionId);
@@ -1023,6 +1174,9 @@ async function devCommandCore({ argv, root, json, }) {
         const requestStarted = Date.now();
         const method = request.method ?? 'GET';
         const path = request.url ?? '/';
+        const capabilityId = capabilityIdFromDevPath(path);
+        const traceHeader = request.headers['x-hsx-trace-id'];
+        const traceId = (Array.isArray(traceHeader) ? traceHeader[0] : traceHeader)?.trim();
         response.on('finish', () => {
             renderRequestLog({
                 method,
@@ -1030,6 +1184,8 @@ async function devCommandCore({ argv, root, json, }) {
                 status: response.statusCode,
                 durationMs: Date.now() - requestStarted,
                 source: 'local',
+                ...(capabilityId ? { capabilityId } : {}),
+                ...(traceId ? { traceId: traceId.slice(0, 128) } : {}),
             });
         });
         if (path === '/_hsx/health') {
@@ -1244,6 +1400,11 @@ async function devCommandCore({ argv, root, json, }) {
             runtimeOrigin: migratedCardTunnel.url,
         })
         : undefined;
+    // The sidecar (below) is what the card's log relay posts to. Its URL is
+    // fixed by --hsx-log-port, so the HubSpot session can be told about it
+    // before it starts; the relay handler lands in this shared slot.
+    const hsxLogPort = Number(resolveFlag(argv, '--hsx-log-port') ?? '9099');
+    const hsxRelay = {};
     // 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
@@ -1254,12 +1415,15 @@ async function devCommandCore({ argv, root, json, }) {
             accountId,
             reporter,
             selectedNodeUids: selectedUiNodeUids,
+            relayUrl: `http://127.0.0.1:${hsxLogPort}`,
+            onRelayReady: (handle) => {
+                hsxRelay.current = handle;
+            },
         })
         : undefined;
     // HS-X dev sidecar — receives frontend logs (and later: backend/request
     // 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');
@@ -1279,16 +1443,29 @@ async function devCommandCore({ argv, root, json, }) {
         root,
         reporter,
         filter: onlyParsed.filter,
+        relay: hsxRelay,
         ...(managedLogSessionId ? { managedSessionId: managedLogSessionId } : {}),
     });
     if (devLogStream) {
         const paint = makeDevLogPaint(process.env, process.stderr);
         requestSink = (entry) => {
+            const effectiveAccountId = entry.accountId ?? accountId;
             devLogStream.bus.emit({
                 lane: 'request',
                 level: entry.status >= 500 ? 'error' : entry.status >= 400 ? 'warn' : 'info',
                 ts: Date.now(),
                 msg: formatDevLogEntry(entry, paint, accountId),
+                fields: {
+                    method: entry.method,
+                    path: entry.path,
+                    status: entry.status,
+                    durationMs: entry.durationMs,
+                    origin: entry.source ?? 'local',
+                    ...(effectiveAccountId ? { accountId: effectiveAccountId } : {}),
+                    ...(entry.capabilityId ? { capabilityId: entry.capabilityId } : {}),
+                    ...(entry.traceId ? { traceId: entry.traceId } : {}),
+                    ...(entry.detail ? { detail: entry.detail } : {}),
+                },
             });
         };
     }
@@ -1376,7 +1553,10 @@ async function devCommandCore({ argv, root, json, }) {
             ]
             : []),
         ...(devLogStream
-            ? [{ status: 'ok', key: 'logs', value: `streaming on ${devLogStream.url}` }]
+            ? [
+                { status: 'ok', key: 'logs', value: `streaming on ${devLogStream.url}` },
+                hubspotLogsLaneRow(devLogStream.hubspotLane),
+            ]
             : []),
         ...(devTunnel ? [{ status: 'ok', key: 'tunnel', value: devTunnel.url }] : []),
         ...(migratedCardDevArtifacts
@@ -1501,6 +1681,17 @@ async function devCommandCore({ argv, root, json, }) {
     });
     return { exitCode: 0 };
 }
+function capabilityIdFromDevPath(path) {
+    const match = /^\/_hsx\/(?:cards|invoke)\/([^/?]+)/.exec(path);
+    if (!match?.[1])
+        return undefined;
+    try {
+        return decodeURIComponent(match[1]);
+    }
+    catch {
+        return match[1];
+    }
+}
 async function managedDevStartCommand(input) {
     const reporter = input.reporter ??
         createReporter({ command: 'dev start', argv: input.argv, entry: !input.json });
@@ -2091,6 +2282,9 @@ function managedDevFollowReadFilter(filter) {
 function delayMs(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+const HUBSPOT_LOGS_POLL_INTERVAL_MS = 30_000;
+/** First poll reaches this far back so the lane shows recent activity at once. */
+const HUBSPOT_LOGS_CATCH_UP_MS = 2 * 60_000;
 async function startHsxDevLogStream(input) {
     try {
         const [{ createDevEventBus }, { startDevLogServer }, { startDevStreamRenderer }] = await Promise.all([
@@ -2100,7 +2294,8 @@ async function startHsxDevLogStream(input) {
         ]);
         const bus = createDevEventBus();
         const authToken = randomBytes(32).toString('base64url');
-        const server = await startDevLogServer({ bus, port: input.port, authToken });
+        const relay = input.relay ?? {};
+        const server = await startDevLogServer({ bus, port: input.port, authToken, relay });
         const renderer = startDevStreamRenderer({
             bus,
             deferStatus: true,
@@ -2117,24 +2312,61 @@ async function startHsxDevLogStream(input) {
         // Missing binding/credentials just means the lane stays off; `hs-x dev`
         // must work without HubSpot credentials.
         let hubspotPoller;
+        let hubspotLane = {
+            active: false,
+            reason: 'HubSpot app logs could not be set up.',
+        };
         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 });
+            const account = input.hubspotAccount;
+            const resolution = await resolveHubSpotLogsSource({
+                cwd: input.root,
+                ...(account?.personalAccessKey
+                    ? {
+                        credentials: {
+                            developerAccountId: account.portalId,
+                            personalAccessKey: account.personalAccessKey,
+                        },
+                    }
+                    : {}),
+            });
             if (resolution.ok) {
-                hubspotPoller = startHubSpotLogsPoller({ bus, source: resolution.source });
+                hubspotPoller = startHubSpotLogsPoller({
+                    bus,
+                    source: resolution.source,
+                    intervalMs: HUBSPOT_LOGS_POLL_INTERVAL_MS,
+                    catchUpMs: HUBSPOT_LOGS_CATCH_UP_MS,
+                });
+                // Poll once now so the lane proves itself (or its first error) within
+                // seconds of startup instead of one interval later.
+                void hubspotPoller.poll();
+                hubspotLane = {
+                    active: true,
+                    appId: resolution.source.appId,
+                    developerAccountId: resolution.source.developerAccountId,
+                };
+            }
+            else {
+                hubspotLane = { active: false, reason: resolution.reason };
             }
         }
-        catch {
+        catch (cause) {
             // The HubSpot lane is additive; never fail the dev stream over it.
+            hubspotLane = {
+                active: false,
+                reason: cause instanceof Error ? cause.message : String(cause),
+            };
         }
         return {
             url: server.url,
             authToken,
             renderer,
             bus,
+            hubspotLane,
+            relay,
             async cleanup() {
                 hubspotPoller?.stop();
                 unsubscribeManagedEvents?.();
@@ -2191,7 +2423,13 @@ async function probeHubSpotUiNodes(input) {
             accountId: portalId,
         }, input.profile ? { profile: input.profile } : {});
         const candidates = listHubSpotDevComponentCandidates(ir.intermediateNodesIndexedByUid);
-        return { uids: candidates.map((candidate) => candidate.uid), candidates, portalId };
+        const application = findHubSpotDevApplication(ir.intermediateNodesIndexedByUid);
+        return {
+            uids: candidates.map((candidate) => candidate.uid),
+            candidates,
+            portalId,
+            ...(application ? { application } : {}),
+        };
     }
     catch {
         // IR translate failed — caller falls back to capability-only behavior.
@@ -2216,6 +2454,9 @@ async function maybeStartHubSpotDevSession(input) {
             selectedNodeUids: input.selectedNodeUids,
             ...(profile ? { profile } : {}),
             preserveState: input.argv.includes('--preserve-state'),
+            localProxyMode: resolveLocalProxyMode(input.argv),
+            ...(input.relayUrl ? { relayUrl: input.relayUrl } : {}),
+            ...(input.onRelayReady ? { onRelayReady: input.onRelayReady } : {}),
             onHeartbeatError: (failure) => {
                 const warning = describeHeartbeatFailure(failure, portalId);
                 if (warning && !input.json)
@@ -2225,6 +2466,16 @@ async function maybeStartHubSpotDevSession(input) {
         input.reporter
             .step('HubSpot UI-extension session')
             .ok(`id ${session.sessionId} · ${session.nodeUids.length} component${session.nodeUids.length === 1 ? '' : 's'}`);
+        if (!input.json) {
+            if (session.frontendLogs.unavailableReason) {
+                input.reporter.warn('HSX_W_DEV_FRONTEND_LOGS_UNAVAILABLE', session.frontendLogs.unavailableReason);
+            }
+            for (const probe of session.localProxy.mappings) {
+                if (probe.applied && probe.reachable)
+                    continue;
+                input.reporter.warn('HSX_W_DEV_LOCAL_PROXY_UNREACHABLE', `local.json proxies ${probe.from} → ${probe.to}: ${describeLocalProxyIssue(session.localProxy, probe)}`);
+            }
+        }
         return session;
     }
     catch (error) {
@@ -2953,6 +3204,59 @@ function formatDevExpiry(now, expiresAt) {
 function isFlagValue(value) {
     return value !== undefined && value.length > 0 && !value.startsWith('-');
 }
+/**
+ * The HubSpot-side lane is the only place renders and proxy executions show
+ * up, so its state must be on the checklist: a silent lane looks identical to
+ * a broken one.
+ */
+function hubspotLogsLaneRow(lane) {
+    if (lane.active) {
+        return {
+            key: 'HubSpot app logs',
+            value: `app ${lane.appId} · renders + proxy executions`,
+            detail: `read from account ${lane.developerAccountId} every ${HUBSPOT_LOGS_POLL_INTERVAL_MS / 1000}s; entries appear shortly after the card acts`,
+            status: 'ok',
+        };
+    }
+    return { key: 'HubSpot app logs', value: 'off', detail: lane.reason, status: 'warn' };
+}
+function describeTestingChoiceForRow(choice) {
+    switch (choice) {
+        case 'developer-test':
+            return 'developer test account';
+        case 'sandbox':
+            return 'sandbox';
+        default:
+            return 'production';
+    }
+}
+/**
+ * Resolve the deployed app and count its non-test installs with the project
+ * account's own credentials — the same lookup `hs project dev` performs.
+ */
+async function checkProductionInstallsForDev(input) {
+    try {
+        const projectConfig = JSON.parse(await readFile(join(input.root, 'hsproject.json'), 'utf8'));
+        if (!projectConfig.name) {
+            return { ok: false, reason: 'hsproject.json has no project name to look the app up by.' };
+        }
+        const [{ createHubSpotDeveloperClient }, { checkHubSpotProductionInstalls }] = await Promise.all([import('@hs-x/hubspot-cli'), import('../dev/production-app-check.js')]);
+        const client = createHubSpotDeveloperClient({
+            developerAccountId: input.projectAccount.portalId,
+            ...(input.projectAccount.personalAccessKey
+                ? { personalAccessKey: input.projectAccount.personalAccessKey }
+                : {}),
+        });
+        return await checkHubSpotProductionInstalls({
+            client,
+            projectName: projectConfig.name,
+            appUid: input.application.uid,
+        });
+    }
+    catch (cause) {
+        return { ok: false, reason: cause instanceof Error ? cause.message : String(cause) };
+    }
+}
 function resolveFlag(argv, flag) {
     const index = argv.indexOf(flag);
     if (index !== -1) {
@@ -3021,6 +3325,7 @@ const projectAccountOption = Options.text('project-account').pipe(Options.option
 const testingAccountOption = Options.text('testing-account').pipe(Options.optional);
 const profileOption = Options.text('profile').pipe(Options.withAlias('p'), Options.optional);
 const preserveStateOption = Options.boolean('preserve-state').pipe(Options.withDefault(false));
+const localProxyOption = Options.choice('local-proxy', ['auto', 'always', 'never']).pipe(Options.withDefault('auto'));
 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);
@@ -3069,6 +3374,7 @@ export const devCmd = Command.make('dev', {
     testingAccount: testingAccountOption,
     profile: profileOption,
     preserveState: preserveStateOption,
+    localProxy: localProxyOption,
     targetOrigin: targetOriginOption,
     telemetryOrigin: telemetryOriginOption,
     accountId: accountIdOption,
@@ -3148,6 +3454,8 @@ export const devCmd = Command.make('dev', {
             argv.push('--profile', opts.profile.value);
         if (opts.preserveState)
             argv.push('--preserve-state');
+        if (opts.localProxy !== 'auto')
+            argv.push('--local-proxy', opts.localProxy);
         if (Option.isSome(opts.targetOrigin)) {
             argv.push('--target-origin', opts.targetOrigin.value);
         }
@@ -3320,4 +3628,48 @@ async function devInvokeRemote(args) {
     reporter.done(ok ? 'Invoked' : 'Failed', ok ? 0 : 1);
     return { exitCode: ok ? 0 : 1 };
 }
+/**
+ * `<app root>/local.json` proxy mappings switch HubSpot's dev server into local
+ * proxy mode for `hubspot.fetch`; a mapping whose target is down fails every
+ * fetch to that origin with an empty error, so show each one up front.
+ */
+function resolveLocalProxyMode(argv) {
+    return resolveHubSpotLocalProxyMode(resolveFlag(argv, '--local-proxy'));
+}
+/**
+ * One short row per local.json mapping, plus one when proxy mode is on with no
+ * mappings (`--local-proxy always`). Details stay one clause long; the mode
+ * semantics live in `hs-x dev --help` and the guide.
+ */
+function localProxyRows(localProxy) {
+    const rows = localProxy.mappings.map((probe) => {
+        const healthy = probe.applied && probe.reachable;
+        return {
+            key: 'local proxy',
+            value: probe.applied ? `${probe.from} → ${probe.to}` : `off · ${probe.from}`,
+            status: healthy ? 'ok' : 'warn',
+            ...(healthy ? {} : { detail: describeLocalProxyIssue(localProxy, probe) }),
+        };
+    });
+    if (localProxy.active && localProxy.mappings.length === 0) {
+        rows.push({
+            key: 'local proxy',
+            value: 'on · no local.json mappings',
+            detail: localProxy.signed
+                ? 'hubspot.fetch leaves this machine signed with the app secret'
+                : 'hubspot.fetch leaves this machine unsigned; set HUBSPOT_CLIENT_SECRET to sign',
+            status: localProxy.signed ? 'ok' : 'warn',
+        });
+    }
+    return rows;
+}
+function describeLocalProxyIssue(localProxy, probe) {
+    if (localProxy.mode === 'never') {
+        return 'ignored (--local-proxy never); hubspot.fetch stays on HubSpot proxy';
+    }
+    if (!probe.applied) {
+        return `${probe.to} not listening; hubspot.fetch stays on HubSpot proxy — start it and restart, or --local-proxy always`;
+    }
+    return `${probe.to} not listening — every hubspot.fetch to this origin fails until it starts (--local-proxy always)`;
+}
 //# sourceMappingURL=dev.js.map