@swell/cli 2.6.0 → 2.7.0

package/dist/create-app-command.js

@@ -47,7 +47,7 @@ export class CreateAppCommand extends SwellCommand {
     commandExample = 'swell create app';
     static baseFlags = {
         frontend: Flags.string({
-            description: 'Framework: astro | angular | hono | nuxt | nextjs | none',
+            description: `Framework: ${getFrontendProjectSlugs(true, false).join(' | ')}`,
             options: getFrontendProjectSlugs(true, false),
         }),
         'storefront-app': Flags.string({
@@ -115,6 +115,57 @@ export class CreateAppCommand extends SwellCommand {
     async addAllowedHostsToNuxt(configPath) {
         return this.addViteAllowedHosts(configPath, 'nuxt.config.ts', 'defineNuxtConfig');
     }
+    /**
+     * For frameworks whose dev server is Vite directly. Astro/Nuxt nest the
+     * vite block inside their own defineConfig — see addViteAllowedHosts.
+     */
+    async addAllowedHostsToVite(configPath) {
+        const candidates = [
+            'vite.config.ts',
+            'vite.config.js',
+            'vite.config.mts',
+            'vite.config.mjs',
+        ];
+        let configFilePath;
+        let content;
+        for (const fileName of candidates) {
+            const candidatePath = path.join(configPath, 'frontend', fileName);
+            try {
+                // eslint-disable-next-line no-await-in-loop
+                content = await fs.readFile(candidatePath, 'utf8');
+                configFilePath = candidatePath;
+                break;
+            }
+            catch {
+                /* try next */
+            }
+        }
+        if (!configFilePath || content === undefined) {
+            return;
+        }
+        if (content.includes('allowedHosts')) {
+            return;
+        }
+        const serverBlock = `  server: {
+    allowedHosts: ${JSON.stringify(TUNNEL_ALLOWED_HOSTS)},
+  },`;
+        const emptyConfig = 'defineConfig({})';
+        if (content.includes(emptyConfig)) {
+            content = content.replace(emptyConfig, `defineConfig({\n${serverBlock}\n})`);
+            await fs.writeFile(configFilePath, content, 'utf8');
+            return;
+        }
+        const closingPos = findConfigClosingBrace(content, 'defineConfig');
+        if (closingPos === -1) {
+            return;
+        }
+        const before = content.slice(0, closingPos);
+        const after = content.slice(closingPos);
+        const needsComma = before.trimEnd().slice(-1) !== ',';
+        const separator = needsComma ? ',\n' : '\n';
+        content = before.trimEnd() + separator + serverBlock + '\n' + after;
+        await fs.writeFile(configFilePath, content, 'utf8');
+    }
     /**
      * Add vite allowedHosts configuration to a framework config file.
      * Supports config files that use a defineX({}) pattern (Astro, Nuxt, etc.)
@@ -170,6 +221,7 @@ export class CreateAppCommand extends SwellCommand {
         const configPath = path.dirname(swellConfig.path);
         // use 'none' by default for non-interactive mode
         const inputFrontend = flags.yes ? flags.frontend || 'none' : flags.frontend;
+        const appType = swellConfig.get('type');
         const frameworkType = inputFrontend ||
             (await select({
                 choices: [
@@ -181,7 +233,10 @@ export class CreateAppCommand extends SwellCommand {
                                 value: null,
                             },
                         ]),
-                    ...FrontendProjectTypes.map(({ name, slug }) => ({
+                    ...FrontendProjectTypes.filter((pt) => !pt.appTypes || pt.appTypes.includes(appType))
+                        .sort((a, b) => (a.displayOrder ?? Number.POSITIVE_INFINITY) -
+                        (b.displayOrder ?? Number.POSITIVE_INFINITY))
+                        .map(({ name, slug }) => ({
                         name,
                         value: slug,
                     })),
@@ -192,6 +247,9 @@ export class CreateAppCommand extends SwellCommand {
             }));
         if (frameworkType && frameworkType !== 'none') {
             const projectType = this.getProjectType(frameworkType);
+            if (projectType.appTypes && !projectType.appTypes.includes(appType)) {
+                this.error(`${projectType.name} is not available for '${appType}' apps. Allowed app types: ${projectType.appTypes.join(', ')}.`, { exit: 1 });
+            }
             // Determine package manager - 'none' is not valid for frontend scaffolding
             let pkg = (flags.pkg || 'npm');
             if (flags.pkg === 'none') {
@@ -449,7 +507,7 @@ export class CreateAppCommand extends SwellCommand {
         };
         await writeJsonFile(path.join(configPath, 'package.json'), packageJson);
         await writeJsonFile(path.join(configPath, 'tsconfig.json'), tsConfig);
-        await writeFile(path.join(configPath, '.gitignore'), `node_modules`);
+        await writeFile(path.join(configPath, '.gitignore'), `node_modules\n.wrangler\n.dev.vars\n.dev.vars.*\n`);
         // Create pnpm-workspace.yaml for pnpm (required for workspace support)
         if (pkg === 'pnpm') {
             await writeFile(path.join(configPath, 'pnpm-workspace.yaml'), 'packages:\n  - frontend\n');
@@ -518,6 +576,11 @@ export class CreateAppCommand extends SwellCommand {
                 await this.addAllowedHostsToNuxt(configPath);
                 break;
             }
+            case 'react':
+            case 'react-storefront': {
+                await this.addAllowedHostsToVite(configPath);
+                break;
+            }
             // Other frameworks don't require allowedHosts configuration
         }
     }

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

@@ -0,0 +1,91 @@
+import { InspectScope } from './lib/apps/inspect-scope.js';
+import { GroupInfo } from './lib/inspect/table.js';
+import { SwellCommand } from './swell-command.js';
+export declare const inspectResourceBaseArgs: {
+    identifier: import("@oclif/core/lib/interfaces/parser.js").Arg<string | undefined, Record<string, unknown>>;
+};
+export declare const inspectResourceBaseFlags: {
+    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>;
+};
+export interface InspectResourceCommandParsed {
+    args: {
+        identifier?: string;
+    };
+    flags: {
+        app?: string;
+        json?: boolean;
+        live?: boolean;
+        yes?: boolean;
+    };
+}
+export declare abstract class InspectResourceCommand extends SwellCommand {
+    /** Plural label for preamble + empty state, e.g. 'Webhooks'. */
+    protected abstract resourceLabel: string;
+    /** Singular label for error messages, e.g. 'webhook'. */
+    protected abstract resourceLabelSingular: string;
+    /** Admin path prefix, e.g. '/data/:webhooks'. */
+    protected abstract adminPath: string;
+    /** Subcommand name as used in CLI, e.g. 'webhooks'. */
+    protected abstract commandName: string;
+    /**
+     * Record field used to look up a bare-name identifier. Defaults to 'name';
+     * override for resources that identify records by a different key
+     * (e.g. webhooks use 'alias').
+     */
+    protected nameField: string;
+    /**
+     * Return the strict paste-back identifier for a record. Used as column 1
+     * content so every row is individually pasteable back into a detail query.
+     *
+     * Default implementation:
+     *   - no `app_id` → `record.id` (store-level records have no app-slug form)
+     *   - no name/alias → `record.id` (degenerate, no meaningful slug)
+     *   - otherwise → `app.<slug>.<name>`, using the raw hex when the slug map
+     *     has no entry (still pasteable via the hex appPart branch)
+     */
+    protected keyFor(record: any, appSlugById: Record<string, string>): string;
+    /**
+     * Optional compact meta rendered after the key. Only non-default state
+     * should surface — enabled rows with no failures return undefined so the
+     * listing stays to one key per line.
+     */
+    protected metaFor(_record: any, _appSlugById: Record<string, string>): string | undefined;
+    /**
+     * Post-process raw list results before rendering. Default is identity;
+     * override to drop noise that the API returns unconditionally (e.g.
+     * deprecated system records that have no server-side filter equivalent).
+     * Detail-mode lookups bypass this hook.
+     */
+    protected filterListResults<T>(results: T[]): T[];
+    /**
+     * Return the section grouping for a list record in global mode. Override
+     * to change labels (e.g. content treats no-app_id rows as `<custom>`).
+     */
+    protected groupForRecord(record: any, appSlugById: Record<string, string>): GroupInfo;
+    protected catch(error: Error): Promise<any>;
+    protected runInspect(parsed: InspectResourceCommandParsed): Promise<void>;
+    private showList;
+    protected showDetail(identifier: string, scope: InspectScope, flags: InspectResourceCommandParsed['flags']): Promise<void>;
+    /**
+     * Per-subclass detail-mode hints. Return runnable commands pointing to
+     * runtime/sibling addresses for the inspected record. Interpolated values
+     * must derive from the record's own fields, not constants — that keeps the
+     * hint self-consistent with column 1 and absorbs platform-side renames.
+     * Default is no hints.
+     */
+    protected hints(_record: any): string[];
+    /**
+     * Emit a fetched detail record. Prints JSON unconditionally; in non-`--json`
+     * mode follows with a `Next steps:` block of `hints(record)` lines.
+     *
+     * `--json` is the machine-readable contract — hints belong in the same
+     * stream as the human-facing output and are simply omitted there.
+     */
+    protected emitDetail(record: any, flags: InspectResourceCommandParsed['flags']): void;
+    private lookupByAppAndName;
+    private printPreamble;
+    protected throwNotFound(identifier: string): never;
+}

package/dist/inspect-resource-command.js

@@ -0,0 +1,232 @@
+import { Args, Flags } from '@oclif/core';
+import { FetchError } from 'node-fetch';
+import { getCurrentAppSlugId } from './lib/apps/index.js';
+import { classifyIdentifier, resolveInspectScope, ScopeError, } from './lib/apps/inspect-scope.js';
+import { HEX24 } from './lib/apps/object-id.js';
+import { buildAppSlugMap, resolveAppId } from './lib/apps/resolve.js';
+import { default as localConfig } from './lib/config.js';
+import { renderKeyMetaTable, } from './lib/inspect/table.js';
+import { SwellCommand } from './swell-command.js';
+export const inspectResourceBaseArgs = {
+    identifier: Args.string({
+        description: 'Resource identifier — see "Identifier forms" below.',
+        required: false,
+    }),
+};
+export const inspectResourceBaseFlags = {
+    app: Flags.string({
+        description: 'Filter by app slug, or "." for current swell.json.',
+    }),
+    live: Flags.boolean({
+        description: 'Use live environment (default: test).',
+        default: false,
+    }),
+    json: Flags.boolean({
+        description: 'Emit pure JSON without the "Next steps" footer. Detail mode only.',
+        default: false,
+    }),
+    yes: Flags.boolean({
+        char: 'y',
+        description: 'No-op; accepted for agent compatibility.',
+        default: false,
+        hidden: true,
+    }),
+};
+export class InspectResourceCommand extends SwellCommand {
+    /**
+     * Record field used to look up a bare-name identifier. Defaults to 'name';
+     * override for resources that identify records by a different key
+     * (e.g. webhooks use 'alias').
+     */
+    nameField = 'name';
+    /**
+     * Return the strict paste-back identifier for a record. Used as column 1
+     * content so every row is individually pasteable back into a detail query.
+     *
+     * Default implementation:
+     *   - no `app_id` → `record.id` (store-level records have no app-slug form)
+     *   - no name/alias → `record.id` (degenerate, no meaningful slug)
+     *   - otherwise → `app.<slug>.<name>`, using the raw hex when the slug map
+     *     has no entry (still pasteable via the hex appPart branch)
+     */
+    keyFor(record, appSlugById) {
+        if (!record.app_id) {
+            return record.id ?? '-';
+        }
+        const name = record[this.nameField];
+        if (!name) {
+            return record.id ?? '-';
+        }
+        const slug = appSlugById[record.app_id] ?? record.app_id;
+        return `app.${slug}.${name}`;
+    }
+    /**
+     * Optional compact meta rendered after the key. Only non-default state
+     * should surface — enabled rows with no failures return undefined so the
+     * listing stays to one key per line.
+     */
+    metaFor(_record, _appSlugById) {
+        return undefined;
+    }
+    /**
+     * Post-process raw list results before rendering. Default is identity;
+     * override to drop noise that the API returns unconditionally (e.g.
+     * deprecated system records that have no server-side filter equivalent).
+     * Detail-mode lookups bypass this hook.
+     */
+    filterListResults(results) {
+        return results;
+    }
+    /**
+     * Return the section grouping for a list record in global mode. Override
+     * to change labels (e.g. content treats no-app_id rows as `<custom>`).
+     */
+    groupForRecord(record, appSlugById) {
+        if (!record.app_id) {
+            return { slug: '<store>', order: 0 };
+        }
+        const resolved = appSlugById[record.app_id];
+        if (!resolved) {
+            return { slug: '<not resolved>', order: 2 };
+        }
+        return { slug: resolved };
+    }
+    async catch(error) {
+        if (error instanceof FetchError) {
+            const message = `Could not connect to Swell API. Please try again later: ${error.message}`;
+            return this.error(message, { exit: 2, code: error.code });
+        }
+        if (error instanceof ScopeError) {
+            return this.error(error.message, { exit: 1 });
+        }
+        return this.error(error.message, { exit: 1 });
+    }
+    async runInspect(parsed) {
+        const { args, flags } = parsed;
+        if (flags.json && !args.identifier) {
+            this.error('--json is only valid in detail mode. Pass an identifier to inspect a single record, or drop --json for the list view.', { exit: 1 });
+        }
+        if (!flags.live) {
+            await this.api.setEnv('test');
+        }
+        const scope = await resolveInspectScope({
+            resolveAppId: (slug) => resolveAppId(this.api, slug),
+            readCurrentAppSlug: () => getCurrentAppSlugId(),
+        }, { app: flags.app });
+        if (args.identifier) {
+            await this.showDetail(args.identifier, scope, flags);
+            return;
+        }
+        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);
+        this.printPreamble(flags.live ?? false);
+        if (filtered.length === 0) {
+            this.log();
+            this.log(`  (no ${this.resourceLabel.toLowerCase()} found)`);
+            this.log();
+            return;
+        }
+        const rows = filtered.map((r) => ({
+            key: this.keyFor(r, appSlugById),
+            meta: this.metaFor(r, appSlugById),
+            group: scope.appId ? undefined : this.groupForRecord(r, appSlugById),
+        }));
+        this.log();
+        for (const line of renderKeyMetaTable(rows)) {
+            this.log(line);
+        }
+        this.log();
+        this.log(`Run "swell inspect ${this.commandName} <key>" to view a ${this.resourceLabelSingular}.`);
+        this.log();
+    }
+    async showDetail(identifier, scope, flags) {
+        const kind = classifyIdentifier(identifier);
+        let record = null;
+        switch (kind.kind) {
+            case 'id': {
+                record = await this.api.get({
+                    adminPath: `${this.adminPath}/${kind.id}`,
+                });
+                break;
+            }
+            case 'slug': {
+                const isHex = HEX24.test(kind.appPart);
+                const appId = isHex
+                    ? kind.appPart
+                    : await resolveAppId(this.api, kind.appPart);
+                record = await this.lookupByAppAndName(appId, kind.name);
+                break;
+            }
+            case 'name': {
+                if (!scope.appId) {
+                    this.error(`Bare ${this.resourceLabelSingular} name '${identifier}' requires --app=<slug> or --app=. to scope. ` +
+                        `Alternatively, pass a full slug (app.<app>.<name>) or 24-char id.`, { exit: 1 });
+                }
+                record = await this.lookupByAppAndName(scope.appId, identifier);
+                break;
+            }
+            case 'invalid': {
+                this.error(`Invalid ${this.resourceLabelSingular} identifier '${identifier}'. ` +
+                    `Expected bare name, full slug (app.<app>.<name>), or 24-char id.`, { exit: 1 });
+            }
+        }
+        if (!record) {
+            this.throwNotFound(identifier);
+        }
+        this.emitDetail(record, flags);
+    }
+    /**
+     * Per-subclass detail-mode hints. Return runnable commands pointing to
+     * runtime/sibling addresses for the inspected record. Interpolated values
+     * must derive from the record's own fields, not constants — that keeps the
+     * hint self-consistent with column 1 and absorbs platform-side renames.
+     * Default is no hints.
+     */
+    hints(_record) {
+        return [];
+    }
+    /**
+     * Emit a fetched detail record. Prints JSON unconditionally; in non-`--json`
+     * mode follows with a `Next steps:` block of `hints(record)` lines.
+     *
+     * `--json` is the machine-readable contract — hints belong in the same
+     * stream as the human-facing output and are simply omitted there.
+     */
+    emitDetail(record, flags) {
+        this.log(JSON.stringify(record, null, 2));
+        if (flags.json) {
+            return;
+        }
+        const lines = this.hints(record);
+        if (lines.length === 0) {
+            return;
+        }
+        this.log();
+        this.log('Next steps:');
+        for (const line of lines) {
+            this.log(`  ${line}`);
+        }
+        this.log();
+    }
+    async lookupByAppAndName(appId, name) {
+        const response = await this.api.get({ adminPath: this.adminPath }, { query: { app_id: appId, [this.nameField]: name, limit: 1 } });
+        return response?.results?.[0] ?? null;
+    }
+    printPreamble(live) {
+        const store = localConfig.getDefaultStore();
+        const envLabel = live ? '[live]' : '[test]';
+        this.log(`${this.resourceLabel} in '${store}' ${envLabel}`);
+    }
+    throwNotFound(identifier) {
+        throw new Error(`No ${this.resourceLabelSingular} found for '${identifier}'.\n` +
+            `List available: swell inspect ${this.commandName}`);
+    }
+}

package/dist/lib/apps/index.d.ts

@@ -119,8 +119,10 @@ export declare enum ConfigInputFields {
     VERSION = "version"
 }
 export interface FrontendProjectType {
+    appTypes?: string[];
     buildCommand?: string;
     devCommand: string;
+    displayOrder?: number;
     installCommand?: string;
     mainPackage: string;
     name: string;
@@ -130,7 +132,6 @@ export declare const CUSTOM_FRAMEWORK_SLUG = "custom";
 export declare const FrontendProjectTypes: FrontendProjectType[];
 export declare function getFrontendProjectSlugs(withNone?: boolean, withLegacy?: boolean): string[];
 export declare function getFrontendProjectValidValues(withNone?: boolean, withLegacy?: boolean): string;
-export declare function getAppSlugId(app: App): string | undefined;
 export declare function getFrontendProjectType(appPath: string): FrontendProjectType | undefined;
 /**
  * Get project commands transformed for the detected package manager.

package/dist/lib/apps/index.js

@@ -2,7 +2,6 @@ import { createHash as createBlake3Hash } from 'blake3-wasm';
 import { pluralize, titleize } from 'inflection';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { toAppId } from '../create/index.js';
 import { detectPackageManager, transformCommand } from '../package-manager.js';
 import { AppConfig } from './app-config.js';
 export { AppConfig, FunctionProcessingError, IgnoringFileError, } from './app-config.js';
@@ -116,11 +115,27 @@ export var ConfigInputFields;
 })(ConfigInputFields || (ConfigInputFields = {}));
 // Slug for unrecognized frontend frameworks (manual dev server mode)
 export const CUSTOM_FRAMEWORK_SLUG = 'custom';
-// Frontend project types - all use direct commands run from frontend/ directory
+// Order matters: getFrontendProjectType is first-match-wins on mainPackage.
+// react-storefront precedes hono (chassis ships hono as a peer); base react
+// is last (any react-using framework above must be caught first).
+// Pinned by test/lib/frontend-detection.test.ts.
 export const FrontendProjectTypes = [
+    {
+        // Template ref is `main`; pin to an immutable tag before announcement.
+        // `--no-agents` pre-answers C3's agents-helper prompt so install
+        // doesn't hang behind our spinner.
+        appTypes: ['storefront'],
+        devCommand: 'npm run dev -- --port ${PORT}',
+        displayOrder: 7,
+        installCommand: 'npm create cloudflare@latest -- frontend --template=swellstores/storefront-react-ai-template#main --deploy=false --git=false --no-agents',
+        mainPackage: '@swell/storefront-app-sdk-react',
+        name: 'Swell React Storefront',
+        slug: 'react-storefront',
+    },
     {
         buildCommand: 'npx astro build',
         devCommand: 'npx astro dev --port ${PORT}',
+        displayOrder: 2,
         installCommand: 'npm create cloudflare@latest -- frontend --framework=astro --deploy=false --git=false -- --no-git --yes --skip-houston --typescript strict',
         mainPackage: 'astro',
         name: 'Astro',
@@ -129,6 +144,7 @@ export const FrontendProjectTypes = [
     {
         buildCommand: 'npx ng build',
         devCommand: 'npx ng serve --port ${PORT}',
+        displayOrder: 6,
         installCommand: 'npm create cloudflare@latest -- frontend --framework=angular --deploy=false --git=false -- --style=sass --zoneless --ai-config=none',
         mainPackage: '@angular/core',
         name: 'Angular',
@@ -136,6 +152,7 @@ export const FrontendProjectTypes = [
     },
     {
         devCommand: 'npm run dev -- --port ${PORT}',
+        displayOrder: 5,
         installCommand: 'npm create cloudflare@latest -- frontend --framework=hono  --deploy=false --git=false',
         mainPackage: 'hono',
         name: 'Hono',
@@ -144,6 +161,7 @@ export const FrontendProjectTypes = [
     {
         buildCommand: 'npx nuxt build',
         devCommand: 'npx nuxt dev --port ${PORT}',
+        displayOrder: 3,
         installCommand: 'npm create cloudflare@latest -- frontend --framework=nuxt --deploy=false --git=false -- --no-modules -f',
         mainPackage: 'nuxt',
         name: 'Nuxt',
@@ -152,17 +170,33 @@ export const FrontendProjectTypes = [
     {
         buildCommand: 'npx opennextjs-cloudflare build',
         devCommand: 'npx next dev --turbopack --port ${PORT}',
+        displayOrder: 1,
         installCommand: 'npm create cloudflare@latest -- frontend --framework=next --deploy=false --git=false -- --typescript --use-npm --src-dir --app --eslint --import-alias "@/*" --tailwind --turbopack',
         mainPackage: 'next',
         name: 'Next.js',
         slug: 'nextjs',
     },
+    {
+        // `--variant=react-ts` pre-answers C3's variant prompt (TS Vite +
+        // plugin-react, not SWC) so install doesn't hang behind our spinner.
+        devCommand: 'npm run dev -- --port ${PORT}',
+        displayOrder: 4,
+        installCommand: 'npm create cloudflare@latest -- frontend --framework=react --deploy=false --git=false --variant=react-ts',
+        mainPackage: 'react',
+        name: 'React',
+        slug: 'react',
+    },
 ];
 export function getFrontendProjectSlugs(withNone = true, withLegacy = true) {
     const types = withLegacy
         ? FrontendProjectTypes
         : FrontendProjectTypes.filter((projectType) => projectType.installCommand);
-    const slugs = types.map((projectType) => projectType.slug);
+    // Sort so user-facing surfaces match the prompt; detection order is
+    // independent.
+    const slugs = [...types]
+        .sort((a, b) => (a.displayOrder ?? Number.POSITIVE_INFINITY) -
+        (b.displayOrder ?? Number.POSITIVE_INFINITY))
+        .map((projectType) => projectType.slug);
     if (withNone) {
         slugs.push('none');
     }
@@ -171,9 +205,6 @@ export function getFrontendProjectSlugs(withNone = true, withLegacy = true) {
 export function getFrontendProjectValidValues(withNone = true, withLegacy = true) {
     return getFrontendProjectSlugs(withNone, withLegacy).join(', ');
 }
-export function getAppSlugId(app) {
-    return toAppId(app.private_id) || app.public_id || app.id;
-}
 export function getFrontendProjectType(appPath) {
     // Try frontend/package.json first (workspace structure), then root package.json (legacy)
     const pkgPaths = [
@@ -325,6 +356,12 @@ export function appAssetImage(appPath, fileName) {
 }
 export function appConfigFromFile(filePath, configType, appPath) {
     const { name } = path.parse(filePath);
+    // Notification basenames must not contain dots: the inspect identifier
+    // grammar (app.<slug>.<model>.<name>) splits on '.', so a dotted name
+    // would silently misparse on lookup.
+    if (configType === ConfigType.NOTIFICATION && name.includes('.')) {
+        throw new Error(`Notification file '${filePath}': basename cannot contain '.'. Rename the file.`);
+    }
     const config = AppConfig.create({
         name,
         filePath,

package/dist/lib/apps/inspect-scope.d.ts

@@ -0,0 +1,58 @@
+export interface InspectScope {
+    /** Undefined when scope is global (no app filter applied). */
+    appId?: string;
+    /** Present whenever appId is present; used for section headers and detail lookups. */
+    appSlug?: string;
+    /** Query fragment merged into list requests. Empty object when global. */
+    query: Record<string, any>;
+}
+export interface ResolveScopeContext {
+    resolveAppId: (appIdOrSlug: string) => Promise<string>;
+    readCurrentAppSlug: () => Promise<string | undefined>;
+}
+export declare class ScopeError extends Error {
+    constructor(message: string);
+}
+/**
+ * Resolve the scope of an `inspect` subcommand.
+ *
+ * Grammar:
+ *   (no --app)    → global listing, no filter
+ *   --app=<slug>  → filter by the named app
+ *   --app=.       → filter by the app in the current directory's swell.json
+ *
+ * The `.` sentinel is the only place swell.json influences behavior; the
+ * default is always global so the same invocation produces the same output
+ * regardless of cwd.
+ */
+export declare function resolveInspectScope(ctx: ResolveScopeContext, flags?: {
+    app?: string;
+}): Promise<InspectScope>;
+export type IdentifierKind = {
+    id: string;
+    kind: 'id';
+} | {
+    appPart: string;
+    kind: 'slug';
+    name: string;
+} | {
+    kind: 'name';
+    name: string;
+} | {
+    input: string;
+    kind: 'invalid';
+};
+/**
+ * Classify an inspect-subcommand identifier argument.
+ *
+ * - `id`: 24-char hex (Mongo ObjectId)
+ * - `slug`: dotted form `app.<appPart>.<name>` where appPart can be either
+ *   an ObjectId or a public/private app slug
+ * - `name`: bare identifier (letters, digits, hyphen, underscore) —
+ *   requires app context to resolve
+ *
+ * Resources whose stored ids are non-hex dotted strings (notifications)
+ * handle dispatch in their own `showDetail` override; the base classifier
+ * stays narrow.
+ */
+export declare function classifyIdentifier(identifier: string): IdentifierKind;