@swell/cli 2.9.0 → 2.9.3

package/dist/commands/inspect/workflow-runs.js

@@ -0,0 +1,319 @@
+import { Args, Flags } from '@oclif/core';
+import { InspectResourceCommand, inspectResourceBaseFlags, } from '../../inspect-resource-command.js';
+import { classifyIdentifier, } from '../../lib/apps/inspect-scope.js';
+import { buildAppSlugMap } from '../../lib/apps/resolve.js';
+import { default as localConfig } from '../../lib/config.js';
+import { renderKeyMetaTable } from '../../lib/inspect/table.js';
+import { isWorkflowInstanceIdentifier, redactWorkflowPayload, resolveWorkflowOperationRef, resolveWorkflowScope, workflowRunDate, workflowDisplayName, workflowRunMeta, WORKFLOW_STATUSES, } from '../../lib/workflows/operations.js';
+export default class WorkflowRuns extends InspectResourceCommand {
+    static summary = 'Workflow runtime instances.';
+    static description = `Lists recent workflow runtime instances, or shows one workflow run by instance id.
+
+Identifier forms:
+  (none)              - recent runs across installed apps, or --app scope
+  wf_inst_<id>         - single run detail
+
+Use --workflow=<workflow> to filter list mode by workflow name, app.<app>.<workflow>, or manifest id.
+`;
+    static args = {
+        identifier: Args.string({
+            description: 'wf_inst_* workflow run instance id.',
+            required: false,
+        }),
+    };
+    static flags = {
+        ...inspectResourceBaseFlags,
+        limit: Flags.integer({
+            default: 10,
+            description: 'Maximum runs to show.',
+        }),
+        status: Flags.string({
+            description: 'Workflow run status.',
+            options: WORKFLOW_STATUSES,
+        }),
+        workflow: Flags.string({
+            description: 'Filter by workflow name, app.<app>.<workflow>, or manifest id.',
+        }),
+    };
+    static examples = [
+        'swell inspect workflow-runs',
+        'swell inspect workflow-runs --app=my-app --status active',
+        'swell inspect workflow-runs --workflow run-import --app=my-app',
+        'swell inspect workflow-runs --workflow app.my-app.run-import --status active',
+        'swell inspect workflow-runs wf_inst_abc123 --app=my-app',
+        'swell inspect workflow-runs wf_inst_abc123',
+    ];
+    resourceLabel = 'Workflow runs';
+    resourceLabelSingular = 'workflow run';
+    adminPath = '/data/:workflows/runs';
+    commandName = 'workflow-runs';
+    detailContext;
+    async run() {
+        const { args, flags } = await this.parse(WorkflowRuns);
+        if (args.identifier && !isWorkflowInstanceIdentifier(args.identifier)) {
+            this.error(`Invalid workflow run identifier '${args.identifier}'. Expected wf_inst_* instance id. Use --workflow=<workflow> to filter run lists.`, { exit: 1 });
+        }
+        if (args.identifier && flags.workflow) {
+            this.error('--workflow is only valid in list mode.', { exit: 1 });
+        }
+        if (!flags.live) {
+            await this.api.setEnv('test');
+        }
+        if (!args.identifier) {
+            if (flags.json) {
+                this.error('--json is only valid when inspecting a single wf_inst_* run.', { exit: 1 });
+            }
+            await this.showRecentRunList(flags);
+            return;
+        }
+        if (isWorkflowInstanceIdentifier(args.identifier)) {
+            await this.showRunDetail(args.identifier, flags);
+        }
+    }
+    hints() {
+        if (!this.detailContext) {
+            return [];
+        }
+        const { appId, appPart, live, run, workflowName } = this.detailContext;
+        const envFlag = live ? ' --live' : '';
+        const lines = [
+            `swell logs --type workflow --app ${appPart} -s ${workflowName}${envFlag}`,
+        ];
+        if (run?.status === 'active' && run.workflow_instance_id) {
+            lines.unshift(buildTerminateApiHint({
+                appId: appId || run.app_id || appPart,
+                instanceId: run.workflow_instance_id,
+                live,
+                workflowName,
+            }));
+        }
+        return lines;
+    }
+    async showRecentRunList(flags) {
+        const { runs, hasMore, skippedApps } = flags.app
+            ? await this.getRecentRunsForScopedApp(flags)
+            : await this.getRecentRunsForInstalledApps(flags);
+        const limitedRuns = sortRunsByDateDesc(runs).slice(0, flags.limit);
+        this.log(`Workflow runs in '${localConfig.getDefaultStore()}' ${flags.live ? '[live]' : '[test]'}`);
+        if (limitedRuns.length === 0) {
+            this.log();
+            this.log(flags.status
+                ? `  (no ${flags.status} workflow runs found)`
+                : '  (no workflow runs found)');
+            this.log();
+            return;
+        }
+        const rows = limitedRuns.map((run) => ({
+            key: run.workflow_instance_id || '-',
+            meta: workflowRunMetaWithContext(run),
+        }));
+        this.log();
+        for (const line of renderKeyMetaTable(rows)) {
+            this.log(line);
+        }
+        if (skippedApps.length > 0) {
+            this.log();
+            this.log(`Skipped inaccessible apps: ${skippedApps.join(', ')}`);
+        }
+        if (hasMore || runs.length > flags.limit) {
+            this.log();
+            this.log(`Showing first ${flags.limit} runs. Increase --limit to see more.`);
+        }
+        this.log();
+        this.log('Run "swell inspect workflow-runs <wf_inst_id>" to view a run.');
+        this.log();
+    }
+    async showRunDetail(instanceId, flags) {
+        const detail = await this.getRunDetail(instanceId, flags);
+        const redacted = redactWorkflowPayload(detail);
+        const manifest = redacted.manifest || {};
+        const appPart = this.detailContext?.appPart || manifest.app_id || '';
+        const workflowName = workflowDisplayName(manifest);
+        this.detailContext = {
+            appId: manifest.app_id,
+            appPart,
+            live: flags.live,
+            run: redacted.run,
+            workflowName,
+        };
+        this.emitDetail(redacted, flags);
+    }
+    async getRunDetail(instanceId, flags) {
+        if (flags.app) {
+            const scope = await this.resolveWorkflowRunScope(flags);
+            this.detailContext = {
+                appPart: scope.appSlug || scope.appId || flags.app,
+                workflowName: '',
+            };
+            return this.getRunDetailForApp(instanceId, scope.appId || '');
+        }
+        const details = await Promise.all(Object.entries(await buildAppSlugMap(this.api)).map(async ([appId, appSlug]) => {
+            try {
+                return {
+                    appPart: appSlug || appId,
+                    detail: await this.getRunDetailForApp(instanceId, appId),
+                };
+            }
+            catch {
+                return null;
+            }
+        }));
+        const match = details.find(Boolean);
+        if (match) {
+            this.detailContext = {
+                appPart: match.appPart,
+                workflowName: '',
+            };
+            return match.detail;
+        }
+        throw new Error(`No workflow run found for '${instanceId}'. Pass --app=<slug> if the app is not listed in this store session.`);
+    }
+    async resolveWorkflowRunScope(flags) {
+        const scope = await resolveWorkflowScope(this.api, { app: flags.app });
+        if (!scope.appId) {
+            throw new Error('Workflow run detail requires --app=<slug> or --app=.');
+        }
+        return scope;
+    }
+    async getRunDetailForApp(instanceId, appId) {
+        return this.api.get({ adminPath: `/data/:workflows/runs/${instanceId}` }, { query: { app_id: appId } });
+    }
+    async getRecentRunsForScopedApp(flags) {
+        const [target] = await this.resolveRunListTargets(flags);
+        if (!target) {
+            throw new Error('Workflow run list requires --app=<slug> or --app=.');
+        }
+        const response = await this.getRunListForApp(target.appId, flags, target.workflowQuery);
+        const runs = (response?.results || []).map((run) => ({
+            ...run,
+        }));
+        return {
+            hasMore: Boolean(response?.has_more),
+            runs,
+            skippedApps: [],
+        };
+    }
+    async getRecentRunsForInstalledApps(flags) {
+        const appSlugById = await buildAppSlugMap(this.api);
+        const targets = await this.resolveRunListTargets(flags, appSlugById);
+        const skippedApps = [];
+        let hasMore = false;
+        const results = await Promise.all(targets.map(async ({ appId, appSlug, workflowQuery }) => {
+            try {
+                const response = await this.getRunListForApp(appId, flags, workflowQuery);
+                hasMore = hasMore || Boolean(response?.has_more);
+                return (response?.results || []).map((run) => ({
+                    ...run,
+                    app_slug: appSlug || appSlugById[appId],
+                }));
+            }
+            catch {
+                skippedApps.push(appSlug || appSlugById[appId] || appId);
+                return [];
+            }
+        }));
+        return {
+            hasMore,
+            runs: results.flat(),
+            skippedApps,
+        };
+    }
+    async resolveRunListTargets(flags, appSlugById) {
+        if (flags.app) {
+            const scope = await resolveWorkflowScope(this.api, { app: flags.app });
+            if (!scope.appId) {
+                throw new Error('Workflow run list requires --app=<slug> or --app=.');
+            }
+            if (!flags.workflow) {
+                return [{ appId: scope.appId, appSlug: scope.appSlug }];
+            }
+            const kind = classifyIdentifier(flags.workflow);
+            if (kind.kind === 'name') {
+                return [
+                    {
+                        appId: scope.appId,
+                        appSlug: scope.appSlug,
+                        workflowQuery: { workflow_name: flags.workflow },
+                    },
+                ];
+            }
+            const ref = await resolveWorkflowOperationRef(this.api, flags.workflow, {
+                app: flags.app,
+            });
+            if (ref.appId !== scope.appId) {
+                throw new Error(`--workflow=${flags.workflow} belongs to a different app than --app=${flags.app}.`);
+            }
+            return [
+                {
+                    appId: ref.appId,
+                    appSlug: scope.appSlug || ref.appSlug,
+                    workflowQuery: ref.query,
+                },
+            ];
+        }
+        if (flags.workflow) {
+            const kind = classifyIdentifier(flags.workflow);
+            if (kind.kind === 'name') {
+                const slugMap = appSlugById || (await buildAppSlugMap(this.api));
+                return Object.entries(slugMap).map(([appId, appSlug]) => ({
+                    appId,
+                    appSlug,
+                    workflowQuery: { workflow_name: flags.workflow },
+                }));
+            }
+            const ref = await resolveWorkflowOperationRef(this.api, flags.workflow, {});
+            return [
+                {
+                    appId: ref.appId,
+                    appSlug: ref.appSlug,
+                    workflowQuery: ref.query,
+                },
+            ];
+        }
+        const slugMap = appSlugById || (await buildAppSlugMap(this.api));
+        return Object.entries(slugMap).map(([appId, appSlug]) => ({
+            appId,
+            appSlug,
+        }));
+    }
+    async getRunListForApp(appId, flags, workflowQuery = {}) {
+        const query = {
+            app_id: appId,
+            ...workflowQuery,
+            limit: flags.limit,
+        };
+        if (flags.status) {
+            query.status = flags.status;
+        }
+        return this.api.get({ adminPath: '/data/:workflows/instances' }, {
+            query,
+        });
+    }
+}
+function sortRunsByDateDesc(runs) {
+    return [...runs].sort((a, b) => {
+        const aDate = Date.parse(workflowRunDate(a) || '') || 0;
+        const bDate = Date.parse(workflowRunDate(b) || '') || 0;
+        return bDate - aDate;
+    });
+}
+function workflowRunMetaWithContext(run) {
+    const context = [
+        run.app_slug ? `app.${run.app_slug}` : null,
+        run.workflow_name,
+    ]
+        .filter(Boolean)
+        .join('.');
+    const meta = workflowRunMeta(run);
+    return [context, meta].filter(Boolean).join(' · ');
+}
+function buildTerminateApiHint({ appId, instanceId, live, workflowName, }) {
+    const body = JSON.stringify({
+        app_id: appId,
+        instance_id: instanceId,
+        source: 'cli',
+        workflow_name: workflowName,
+    });
+    const envFlag = live ? ' --live' : '';
+    return `swell api post '/:workflows/instances/terminate' --body '${body}'${envFlag}`;
+}

package/dist/commands/inspect/workflows.d.ts

@@ -0,0 +1,33 @@
+import { InspectResourceCommand, InspectResourceCommandParsed } from '../../inspect-resource-command.js';
+import { InspectScope } from '../../lib/apps/inspect-scope.js';
+import { WorkflowManifestRecord } from '../../lib/workflows/operations.js';
+export default class Workflows extends InspectResourceCommand {
+    static summary: string;
+    static description: string;
+    static args: {
+        identifier: import("@oclif/core/lib/interfaces/parser.js").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static flags: {
+        app: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        live: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+        json: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+        yes: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+    };
+    static examples: string[];
+    protected resourceLabel: string;
+    protected resourceLabelSingular: string;
+    protected adminPath: string;
+    protected commandName: string;
+    private appSlugById;
+    private skippedApps;
+    private detailRef?;
+    run(): Promise<void>;
+    protected keyFor(record: WorkflowManifestRecord, appSlugById: Record<string, string>): string;
+    protected metaFor(record: WorkflowManifestRecord): string | undefined;
+    protected getListResults(scope: InspectScope, _flags: InspectResourceCommandParsed['flags']): Promise<WorkflowManifestRecord[]>;
+    protected getAppSlugById(scope: InspectScope): Promise<Record<string, string>>;
+    protected afterList(): void;
+    protected showDetail(identifier: string, _scope: InspectScope, flags: InspectResourceCommandParsed['flags']): Promise<void>;
+    protected hints(): string[];
+    private getWorkflowListForApp;
+}

package/dist/commands/inspect/workflows.js

@@ -0,0 +1,99 @@
+import { InspectResourceCommand, inspectResourceBaseArgs, inspectResourceBaseFlags, } from '../../inspect-resource-command.js';
+import { buildAppSlugMap } from '../../lib/apps/resolve.js';
+import { redactWorkflowPayload, resolveWorkflowOperationRef, workflowDisplayName, workflowListMeta, } from '../../lib/workflows/operations.js';
+export default class Workflows extends InspectResourceCommand {
+    static summary = 'Durable app workflows and runtime state.';
+    static description = `Lists workflow manifests across deployed apps with runtime state. Pass --app=<slug> or --app=. (current swell.json) to scope.
+
+Pass an identifier to view a workflow manifest, summary counts, and failed instance sample as JSON.
+
+Identifier forms:
+  app.<app>.<name>     - full paste-back key (list column 1)
+  <name>               - requires --app= scope
+  <24-char id>         - any scope
+`;
+    static args = { ...inspectResourceBaseArgs };
+    static flags = { ...inspectResourceBaseFlags };
+    static examples = [
+        'swell inspect workflows',
+        'swell inspect workflows --app=my-app',
+        'swell inspect workflows app.my-app.run-import',
+        'swell inspect workflows run-import --app=my-app',
+        'swell inspect workflows --live',
+    ];
+    resourceLabel = 'Workflows';
+    resourceLabelSingular = 'workflow';
+    adminPath = '/data/:workflows';
+    commandName = 'workflows';
+    appSlugById = {};
+    skippedApps = [];
+    detailRef;
+    async run() {
+        const { args, flags } = await this.parse(Workflows);
+        await this.runInspect({ args, flags });
+    }
+    keyFor(record, appSlugById) {
+        const appId = record.app_id || '';
+        const appPart = appSlugById[appId] || appId;
+        return `app.${appPart}.${workflowDisplayName(record)}`;
+    }
+    metaFor(record) {
+        return workflowListMeta(record);
+    }
+    async getListResults(scope, _flags) {
+        this.skippedApps = [];
+        if (scope.appId) {
+            return this.getWorkflowListForApp(scope.appId);
+        }
+        this.appSlugById = await buildAppSlugMap(this.api);
+        const results = await Promise.all(Object.keys(this.appSlugById).map(async (appId) => {
+            try {
+                return await this.getWorkflowListForApp(appId);
+            }
+            catch {
+                this.skippedApps.push(this.appSlugById[appId] || appId);
+                return [];
+            }
+        }));
+        return results.flat();
+    }
+    async getAppSlugById(scope) {
+        if (scope.appId) {
+            return scope.appSlug ? { [scope.appId]: scope.appSlug } : {};
+        }
+        return this.appSlugById;
+    }
+    afterList() {
+        if (this.skippedApps.length > 0) {
+            this.log();
+            this.log(`Skipped inaccessible apps: ${this.skippedApps.join(', ')}`);
+        }
+    }
+    async showDetail(identifier, _scope, flags) {
+        const ref = await resolveWorkflowOperationRef(this.api, identifier, flags);
+        const workflowRef = ref.query.workflow_id || ref.query.workflow_name;
+        const detail = await this.api.get({ adminPath: `/data/:workflows/${workflowRef}` }, { query: { app_id: ref.appId } });
+        const manifest = detail?.manifest || {};
+        const workflowName = workflowDisplayName(manifest);
+        this.detailRef = {
+            appPart: ref.appSlug || ref.appId,
+            workflowName,
+        };
+        this.emitDetail(redactWorkflowPayload(detail), flags);
+    }
+    hints() {
+        if (!this.detailRef) {
+            return [];
+        }
+        const { appPart, workflowName } = this.detailRef;
+        return [
+            `swell inspect workflow-runs --workflow app.${appPart}.${workflowName} --status active`,
+            `swell inspect workflow-runs --workflow app.${appPart}.${workflowName} --status failed`,
+            `swell logs --type workflow --app ${appPart} -s ${workflowName}`,
+        ];
+    }
+    async getWorkflowListForApp(appId) {
+        const response = await this.api.get({ adminPath: '/data/:workflows' }, { query: { app_id: appId } });
+        return response?.results || [];
+    }
+}

package/dist/commands/logs.d.ts

@@ -20,4 +20,5 @@ export default class Logs extends SwellCommand {
     run(): Promise<void>;
     private getLogs;
     private getLogsAndWriteToStream;
+    private resolveWorkflowLogFilters;
 }

package/dist/commands/logs.js

@@ -1,5 +1,6 @@
 import { Flags } from '@oclif/core';
 import { LineOutput, LoggedItem, TableOutput } from '../lib/logs/index.js';
+import { resolveWorkflowScope } from '../lib/workflows/operations.js';
 import { SwellCommand } from '../swell-command.js';
 // the columns available to display in the table
 const OUTPUT_COLUMNS = [
@@ -104,6 +105,7 @@ export default class Logs extends SwellCommand {
         'swell logs',
         'swell logs -f -p -n 10 -c date,req,data',
         'swell logs -s accounts',
+        'swell logs --type workflow --app my-app -s run-import',
         'swell logs --after 2023-08-25T16:01:02.697Z -c date',
         'swell logs --after 2023-08-27',
     ];
@@ -115,7 +117,7 @@ export default class Logs extends SwellCommand {
         }),
         // filters
         app: Flags.string({
-            description: 'filter logs by app id',
+            description: 'filter logs by app id, slug, or "." for current swell.json',
         }),
         before: Flags.string({
             description: 'expected is Javascript Date Time String Format: YYYY-MM-DDTHH:mm:ss.sssZ',
@@ -175,13 +177,14 @@ export default class Logs extends SwellCommand {
         type: Flags.string({
             description: 'filter logs by type',
             multiple: true,
-            options: ['api', 'function', 'webhook', 'transaction'],
+            options: ['api', 'function', 'webhook', 'transaction', 'workflow'],
         }),
     };
     static summary = 'Output or stream store logs to the terminal.';
     output;
     async run() {
         const { flags } = await this.parse(Logs);
+        await this.resolveWorkflowLogFilters(flags);
         // indentify the columns to display
         const columns = flags.columns.split(',');
         // create the output stream
@@ -229,4 +232,19 @@ export default class Logs extends SwellCommand {
         // if the user is following logs, we want to return the last date we received
         return lastDate || flags.startPolling || new Date().toISOString();
     }
+    async resolveWorkflowLogFilters(flags) {
+        if (!flags.type?.includes('workflow') || !flags.app) {
+            return;
+        }
+        const envId = flags.env || 'test';
+        if (envId !== 'live') {
+            await this.api.setEnv(envId);
+        }
+        const scope = await resolveWorkflowScope(this.api, {
+            app: flags.app,
+        });
+        if (scope.appId) {
+            flags.app = scope.appId;
+        }
+    }
 }

package/dist/commands/schema.js

@@ -7,6 +7,7 @@ import * as fs from 'node:fs';
 import parseJson from 'parse-json';
 import { bundleFunction } from '../lib/bundle.js';
 import { SCHEMAS_BASE_URL } from '../lib/constants.js';
+import { analyzeFunctionSource, getFunctionTriggers, hasKindDiagnostic, workflowStaticConfigError, } from '../lib/function-source-analysis.js';
 import { SwellCommand } from '../swell-command.js';
 const SCHEMA_DEFINITIONS = Object.freeze({
     model: {
@@ -25,7 +26,7 @@ const SCHEMA_DEFINITIONS = Object.freeze({
         description: 'Webhook definitions (/webhooks/*.json)',
     },
     function: {
-        description: 'Function definitions (/functions/*.ts or *.js)',
+        description: 'Function and workflow definitions (/functions/*.ts or *.js)',
         hasJsonSchema: false,
     },
 });
@@ -60,6 +61,10 @@ export default class Schema extends SwellCommand {
             description: 'Validate a function file',
             command: '<%= config.bin %> <%= command.id %> function myfunction.ts',
         },
+        {
+            description: 'Validate a workflow file',
+            command: '<%= config.bin %> <%= command.id %> function run-import.ts',
+        },
     ];
     static args = {
         type: Args.string({
@@ -225,6 +230,17 @@ export default class Schema extends SwellCommand {
             throw new Error(`File not found: ${file}`);
         }
         const filePath = fs.realpathSync(file);
+        const analysis = await analyzeFunctionSource(filePath);
+        if (analysis.kind === 'workflow') {
+            if (analysis.diagnostics.length > 0) {
+                throw new Error(`Invalid workflow function:\n•  ${analysis.diagnostics.join('\n•  ')}`);
+            }
+            this.log('Valid workflow function definition');
+            return;
+        }
+        if (hasKindDiagnostic(analysis)) {
+            throw new Error(`Invalid function config:\n•  ${analysis.diagnostics.join('\n•  ')}`);
+        }
         // Attempt to bundle the function (validates syntax, imports, etc.)
         let bundleResult;
         try {
@@ -234,12 +250,15 @@ export default class Schema extends SwellCommand {
             throw new Error(`Function compilation failed:\n•  ${error.message}`);
         }
         const { config } = bundleResult;
+        if (config?.kind === 'workflow') {
+            throw workflowStaticConfigError();
+        }
         // Validate config exists
         if (!config) {
             throw new Error('Invalid function:\n•  Function must export a `config` object');
         }
         // Validate trigger exclusivity
-        const triggers = ['route', 'model', 'cron'].filter((t) => config[t]);
+        const triggers = getFunctionTriggers(config);
         if (triggers.length === 0) {
             throw new Error('Invalid function config:\n•  Config must specify one of: route, model, cron');
         }

package/dist/create-app-command.js

@@ -488,7 +488,7 @@ export class CreateAppCommand extends SwellCommand {
         const packageJson = {
             description: config.get('description'),
             devDependencies: {
-                '@swell/app-types': '^1.0.5',
+                '@swell/app-types': '^1.2.0',
                 typescript: '^5.9.3',
             },
             name,

package/dist/inspect-resource-command.d.ts

@@ -67,7 +67,10 @@ export declare abstract class InspectResourceCommand extends SwellCommand {
     protected groupForRecord(record: any, appSlugById: Record<string, string>): GroupInfo;
     protected catch(error: Error): Promise<any>;
     protected runInspect(parsed: InspectResourceCommandParsed): Promise<void>;
-    private showList;
+    protected showList(scope: InspectScope, flags: InspectResourceCommandParsed['flags']): Promise<void>;
+    protected getListResults(scope: InspectScope, _flags: InspectResourceCommandParsed['flags']): Promise<any[]>;
+    protected getAppSlugById(scope: InspectScope): Promise<Record<string, string>>;
+    protected afterList(_scope: InspectScope, _flags: InspectResourceCommandParsed['flags']): void;
     protected showDetail(identifier: string, scope: InspectScope, flags: InspectResourceCommandParsed['flags']): Promise<void>;
     /**
      * Per-subclass detail-mode hints. Return runnable commands pointing to

package/dist/inspect-resource-command.js

@@ -120,13 +120,9 @@ export class InspectResourceCommand extends SwellCommand {
         await this.showList(scope, flags);
     }
     async showList(scope, flags) {
-        const { results } = await this.api.getAll({ adminPath: this.adminPath }, { query: scope.query });
-        const filtered = this.filterListResults(results ?? []);
-        const appSlugById = scope.appId
-            ? scope.appSlug
-                ? { [scope.appId]: scope.appSlug }
-                : {}
-            : await buildAppSlugMap(this.api);
+        const results = await this.getListResults(scope, flags);
+        const filtered = this.filterListResults(results);
+        const appSlugById = await this.getAppSlugById(scope);
         this.printPreamble(flags.live ?? false);
         if (filtered.length === 0) {
             this.log();
@@ -143,10 +139,22 @@ export class InspectResourceCommand extends SwellCommand {
         for (const line of renderKeyMetaTable(rows)) {
             this.log(line);
         }
+        this.afterList(scope, flags);
         this.log();
         this.log(`Run "swell inspect ${this.commandName} <key>" to view a ${this.resourceLabelSingular}.`);
         this.log();
     }
+    async getListResults(scope, _flags) {
+        const { results } = await this.api.getAll({ adminPath: this.adminPath }, { query: scope.query });
+        return results ?? [];
+    }
+    async getAppSlugById(scope) {
+        if (scope.appId) {
+            return scope.appSlug ? { [scope.appId]: scope.appSlug } : {};
+        }
+        return buildAppSlugMap(this.api);
+    }
+    afterList(_scope, _flags) { }
     async showDetail(identifier, scope, flags) {
         const kind = classifyIdentifier(identifier);
         let record = null;

package/dist/lib/api.js

@@ -12,6 +12,12 @@ export var HttpMethod;
     HttpMethod["DELETE"] = "delete";
 })(HttpMethod || (HttpMethod = {}));
 const GET_ALL_LIMIT = 1000;
+function isHtmlResponse(contentType, data) {
+    if (contentType?.toLowerCase().includes('text/html')) {
+        return true;
+    }
+    return /^\s*<(?:!doctype\s+html|html)[\s>]/i.test(data);
+}
 const defaultHeaders = (opts) => ({
     'Content-Type': 'application/json',
     ...opts,
@@ -84,6 +90,12 @@ export default class Api {
             return res;
         }
         const resData = await res.text();
+        const contentType = res.headers.get('content-type');
+        if (isHtmlResponse(contentType, resData)) {
+            const error = new Error(`Expected JSON from API route '${path}', but received HTML. This usually means the admin API proxy did not match the route.`);
+            error.status = res.status;
+            throw error;
+        }
         if (!res.ok) {
             // Try to parse error message
             let errorJson;