@swell/cli 2.6.0 → 2.7.0

package/dist/lib/apps/inspect-scope.js

@@ -0,0 +1,60 @@
+import { HEX24 } from './object-id.js';
+export class ScopeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ScopeError';
+    }
+}
+/**
+ * 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 async function resolveInspectScope(ctx, flags = {}) {
+    if (!flags.app) {
+        return { query: {} };
+    }
+    if (flags.app === '.') {
+        const slug = await ctx.readCurrentAppSlug();
+        if (!slug) {
+            throw new ScopeError(`--app=. requires a swell.json with an 'id' field in the current directory. Pass --app=<slug> or cd into an app.`);
+        }
+        const appId = await ctx.resolveAppId(slug);
+        return { appId, appSlug: slug, query: { app_id: appId } };
+    }
+    const appId = await ctx.resolveAppId(flags.app);
+    return { appId, appSlug: flags.app, query: { app_id: appId } };
+}
+/**
+ * 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 function classifyIdentifier(identifier) {
+    if (HEX24.test(identifier)) {
+        return { kind: 'id', id: identifier };
+    }
+    const slugMatch = identifier.match(/^app\.([^.]+)\.(.+)$/);
+    if (slugMatch) {
+        return { kind: 'slug', appPart: slugMatch[1], name: slugMatch[2] };
+    }
+    if (/^[\w-]+$/i.test(identifier)) {
+        return { kind: 'name', name: identifier };
+    }
+    return { kind: 'invalid', input: identifier };
+}

package/dist/lib/apps/object-id.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Mongo ObjectId shape — 24 hex chars, case-insensitive. The CLI accepts
+ * either-case input (curl/jq users tend to lowercase, admin URLs sometimes
+ * upper). All inspect grammars use the same pattern, so it lives here.
+ */
+export declare const HEX24: RegExp;
+export declare function isObjectId(value: string): boolean;

package/dist/lib/apps/object-id.js

@@ -0,0 +1,9 @@
+/**
+ * Mongo ObjectId shape — 24 hex chars, case-insensitive. The CLI accepts
+ * either-case input (curl/jq users tend to lowercase, admin URLs sometimes
+ * upper). All inspect grammars use the same pattern, so it lives here.
+ */
+export const HEX24 = /^[\da-f]{24}$/i;
+export function isObjectId(value) {
+    return HEX24.test(value);
+}

package/dist/lib/apps/paths.js

@@ -9,13 +9,20 @@ function globOptions(appPath, options) {
         gitignore: true,
         ...options,
         expandDirectories: true,
-        // Explicitly ignore node_modules and lock files just in case
+        // .dev.vars can hold real credentials — ignored here in case the
+        // user's .gitignore doesn't cover it.
         ignore: [
             '**/.swellrc',
             '**/.git/**',
             '**/node_modules/**',
             '**/package-lock.json',
             '**/yarn.lock',
+            '**/pnpm-lock.yaml',
+            '**/bun.lockb',
+            '**/bun.lock',
+            '**/.wrangler/**',
+            '**/.dev.vars',
+            '**/.dev.vars.*',
             ...(options?.ignore || []),
         ],
     };

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

@@ -0,0 +1,16 @@
+import Api from '../api.js';
+/**
+ * Resolve an app's ObjectId from a public slug or private slug; pass through
+ * a value that already looks like an ObjectId.
+ *
+ * Priority mirrors schema-api-server installer.js:3596 `getAppBySlugId`:
+ * private match (`_<slug>`) wins over public match. For typical apps the
+ * order is invisible (a single record matches both branches), but it
+ * matters when two apps share a slug across publish state.
+ */
+export declare function resolveAppId(api: Api, appIdOrSlug: string): Promise<string>;
+/**
+ * Build a map of installed-app ObjectId -> friendly slug, using the shared
+ * server-canonical slug priority (see `slug.ts`).
+ */
+export declare function buildAppSlugMap(api: Api): Promise<Record<string, string>>;

package/dist/lib/apps/resolve.js

@@ -0,0 +1,39 @@
+import { isObjectId } from './object-id.js';
+import { slugFromInstalledApp } from './slug.js';
+/**
+ * Resolve an app's ObjectId from a public slug or private slug; pass through
+ * a value that already looks like an ObjectId.
+ *
+ * Priority mirrors schema-api-server installer.js:3596 `getAppBySlugId`:
+ * private match (`_<slug>`) wins over public match. For typical apps the
+ * order is invisible (a single record matches both branches), but it
+ * matters when two apps share a slug across publish state.
+ */
+export async function resolveAppId(api, appIdOrSlug) {
+    if (isObjectId(appIdOrSlug)) {
+        return appIdOrSlug;
+    }
+    const installedApps = await api.get({ adminPath: `/client/apps` });
+    const records = (installedApps?.results ?? []);
+    const privateMatch = records.find((a) => a.app_private_id === `_${appIdOrSlug}`);
+    const app = privateMatch ?? records.find((a) => a.app_public_id === appIdOrSlug);
+    if (!app) {
+        throw new Error(`App '${appIdOrSlug}' not found`);
+    }
+    return app.app_id;
+}
+/**
+ * Build a map of installed-app ObjectId -> friendly slug, using the shared
+ * server-canonical slug priority (see `slug.ts`).
+ */
+export async function buildAppSlugMap(api) {
+    const installedApps = await api.get({ adminPath: `/client/apps` });
+    const map = {};
+    for (const a of (installedApps?.results ?? [])) {
+        const slug = slugFromInstalledApp(a);
+        if (a.app_id && slug) {
+            map[a.app_id] = slug;
+        }
+    }
+    return map;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Compute an app's display slug.
+ *
+ * Mirrors the server-canonical priority in
+ * schema-api-server/api/admin/features/apps/installer.js:213 — private_id
+ * (with the leading underscore stripped) wins over public_id. The orders
+ * agree for the typical case where `private_id === '_' + public_id`, but
+ * diverge for theme-collision suffixes (`_my_theme_1`) and any app where
+ * `public_id` was set independently of `private_id`. Following the server
+ * keeps CLI labels in sync with what the admin UI shows for the same row.
+ *
+ * No id fallback: an app with neither slug returns `undefined`. Callers
+ * that want a "show something" guarantee (e.g. the push-app picker) should
+ * append `?? app.id` themselves; the slug map deliberately filters such
+ * records out so downstream code can flag them as `<not resolved>`.
+ */
+export interface SlugSource {
+    privateId?: string;
+    publicId?: string;
+}
+export declare function appSlug(source: SlugSource): string | undefined;
+export declare function slugFromApp(app: {
+    private_id?: string;
+    public_id?: string;
+}): string | undefined;
+export declare function slugFromInstalledApp(rec: {
+    app_private_id?: string;
+    app_public_id?: string;
+}): string | undefined;

package/dist/lib/apps/slug.js

@@ -0,0 +1,12 @@
+export function appSlug(source) {
+    return source.privateId?.replace(/^_/, '') || source.publicId;
+}
+export function slugFromApp(app) {
+    return appSlug({ privateId: app.private_id, publicId: app.public_id });
+}
+export function slugFromInstalledApp(rec) {
+    return appSlug({
+        privateId: rec.app_private_id,
+        publicId: rec.app_public_id,
+    });
+}

package/dist/lib/inspect/content.d.ts

@@ -0,0 +1,39 @@
+import { GroupInfo } from './table.js';
+export interface ParsedContentId {
+    middle: string;
+    name: string;
+    prefix: 'app' | 'custom';
+}
+/**
+ * Parse a content view identifier of the form `app.<appPart>.<name>` or
+ * `custom.<source>.<name>`. Returns null for anything that doesn't match.
+ */
+export declare function parseContentId(id: string): ParsedContentId | null;
+/**
+ * Produce the column-1 paste-back key for a content view. Rewrites
+ * `app.<hex>.<name>` to `app.<slug>.<name>` when the slug is known; passes
+ * `custom.*` and unresolvable app ids through unchanged (both remain valid
+ * paste-back forms against the detail endpoint).
+ */
+export declare function resolveContentKey(id: string, appSlugById: Record<string, string>): string;
+/**
+ * Group a content view record for the vertical split. Records with no
+ * `app_id` belong to the platform's `custom.*` source and land in a
+ * single `<custom>` section at the top of the output.
+ */
+export declare function groupContentRecord(record: {
+    app_id?: string;
+}, appSlugById: Record<string, string>): GroupInfo;
+/**
+ * Translate a user-supplied content identifier into the unresolved API
+ * form. Accepts:
+ *   - `custom.<source>.<name>`  → unchanged
+ *   - `app.<hex>.<name>`        → unchanged (already unresolved form)
+ *   - `app.<slug>.<name>`       → slug resolved to hex
+ *   - bare `<name>`             → combined with scope.appId to `app.<hex>.<name>`
+ *
+ * `resolveAppId` is injected so this function is testable without a live API.
+ */
+export declare function reverseResolveContentId(identifier: string, scope: {
+    appId?: string;
+}, resolveAppId: (slug: string) => Promise<string>): Promise<string>;

package/dist/lib/inspect/content.js

@@ -0,0 +1,76 @@
+/**
+ * Parse a content view identifier of the form `app.<appPart>.<name>` or
+ * `custom.<source>.<name>`. Returns null for anything that doesn't match.
+ */
+export function parseContentId(id) {
+    const match = id.match(/^(app|custom)\.([^.]+)\.(.+)$/);
+    if (!match)
+        return null;
+    return {
+        prefix: match[1],
+        middle: match[2],
+        name: match[3],
+    };
+}
+/**
+ * Produce the column-1 paste-back key for a content view. Rewrites
+ * `app.<hex>.<name>` to `app.<slug>.<name>` when the slug is known; passes
+ * `custom.*` and unresolvable app ids through unchanged (both remain valid
+ * paste-back forms against the detail endpoint).
+ */
+export function resolveContentKey(id, appSlugById) {
+    const parsed = parseContentId(id);
+    if (!parsed)
+        return id;
+    if (parsed.prefix === 'custom')
+        return id;
+    const slug = appSlugById[parsed.middle] ?? parsed.middle;
+    return `app.${slug}.${parsed.name}`;
+}
+/**
+ * Group a content view record for the vertical split. Records with no
+ * `app_id` belong to the platform's `custom.*` source and land in a
+ * single `<custom>` section at the top of the output.
+ */
+export function groupContentRecord(record, appSlugById) {
+    if (!record.app_id) {
+        return { slug: '<custom>', label: 'custom', order: 0 };
+    }
+    const resolved = appSlugById[record.app_id];
+    if (!resolved) {
+        return { slug: '<not resolved>', order: 2 };
+    }
+    return { slug: resolved };
+}
+/**
+ * Translate a user-supplied content identifier into the unresolved API
+ * form. Accepts:
+ *   - `custom.<source>.<name>`  → unchanged
+ *   - `app.<hex>.<name>`        → unchanged (already unresolved form)
+ *   - `app.<slug>.<name>`       → slug resolved to hex
+ *   - bare `<name>`             → combined with scope.appId to `app.<hex>.<name>`
+ *
+ * `resolveAppId` is injected so this function is testable without a live API.
+ */
+export async function reverseResolveContentId(identifier, scope, resolveAppId) {
+    if (/^custom\.[^.]+\..+$/.test(identifier)) {
+        return identifier;
+    }
+    if (/^app\.[\da-f]{24}\..+$/i.test(identifier)) {
+        return identifier;
+    }
+    const appMatch = identifier.match(/^app\.([^.]+)\.(.+)$/);
+    if (appMatch) {
+        const appId = await resolveAppId(appMatch[1]);
+        return `app.${appId}.${appMatch[2]}`;
+    }
+    if (/^[\w-]+$/i.test(identifier)) {
+        if (!scope.appId) {
+            throw new Error(`Bare content name '${identifier}' requires --app=<slug> or --app=. to scope. ` +
+                `Alternatively, pass a full identifier (app.<app>.<name> or custom.<source>.<name>).`);
+        }
+        return `app.${scope.appId}.${identifier}`;
+    }
+    throw new Error(`Invalid content identifier '${identifier}'. ` +
+        `Expected bare name, app.<app>.<name>, or custom.<source>.<name>.`);
+}

package/dist/lib/inspect/notifications.d.ts

@@ -0,0 +1,115 @@
+import { GroupInfo } from './table.js';
+export interface NotificationRecord {
+    api?: string;
+    app_id?: string;
+    enabled?: boolean;
+    id?: string;
+    model?: string;
+    name?: string;
+    v2?: boolean;
+}
+export type ParsedNotificationKey = {
+    id: string;
+    kind: 'hex';
+} | {
+    id: string;
+    kind: 'system_id';
+} | {
+    kind: 'app_full';
+    model: string;
+    name: string;
+    slug: string;
+} | {
+    kind: 'app_short';
+    name: string;
+    slug: string;
+} | {
+    kind: 'bare';
+    name: string;
+} | {
+    input: string;
+    kind: 'invalid';
+};
+/**
+ * Translate a stored model path into its display form.
+ *
+ *   apps/<own-hex>/<x>      → <x>          (own-app prefix is implicit in the slug)
+ *   apps/<other-hex>/<x>    → apps/<other-slug>/<x>
+ *   apps/<unknown-hex>/<x>  → unchanged    (preserve a paste-back form)
+ *   <built-in-model>        → unchanged
+ *
+ * Stripping `apps/<own>/` keeps the common case readable; the rare collision
+ * with a same-named built-in (e.g. an app model literally named
+ * `subscriptions`) is recovered by `expandModelCandidates` at lookup time.
+ */
+export declare function normalizeModelForDisplay(model: string, ownAppId: string | undefined, appSlugById: Record<string, string>): string;
+/**
+ * Produce the column-1 paste-back key for a notification.
+ *
+ *   System (no app_id):   record.id verbatim — already in `com.<model>.<name>` form.
+ *   App with model+name:  `app.<slug>.<model-display>.<name>`
+ *   Anything else:        record.id (degenerate, no meaningful slug)
+ *
+ * Notification identity is `(api, model, name, app_id?)`; collapsing on
+ * `(app_id, name)` alone caused two `notify_me.back-in-stock` rows
+ * (different `model`) to render identically.
+ */
+export declare function formatNotificationKey(record: NotificationRecord, appSlugById: Record<string, string>): string;
+/**
+ * Group a notification record. System rows (no app_id) are not store data —
+ * they belong to the platform and render under a `system` divider at the top.
+ */
+export declare function groupNotificationRecord(record: NotificationRecord, appSlugById: Record<string, string>): GroupInfo;
+/**
+ * Classify a notification identifier. The base `classifyIdentifier` collapses
+ * every dot-segment after `app.<part>.` into `name`, which loses the model.
+ * Notifications need a model-aware split, so they bypass the base classifier.
+ *
+ * Recognised shapes:
+ *   - 24-char hex                    → hex (delegate to base GET-by-id)
+ *   - com.<rest>                     → system_id (canonical platform id)
+ *   - app.<slug>.<model>.<name>      → app_full (triplet lookup)
+ *   - app.<slug>.<name>              → app_short (3-part legacy; ambiguous)
+ *   - bare <name>                    → bare (requires --app= scope; ambiguous)
+ *   - anything else                  → invalid
+ *
+ * Multi-segment names (e.g. `unpaid.v2`) only appear in system notifications,
+ * which arrive via the `com.*` form and never go through `app.*` parsing.
+ */
+export declare function parseNotificationKey(input: string): ParsedNotificationKey;
+/**
+ * Render the disambiguation error body when a `(app_id, name)` query returns
+ * multiple notifications. Caller fetches with `limit = displayLimit + 1` so
+ * we can detect overflow without paging through the whole result set; if
+ * `results.length > displayLimit`, the surplus rows are dropped and a hint
+ * line is appended directing the user to the full key form.
+ */
+export declare function formatDisambiguationError(results: NotificationRecord[], appSlugById: Record<string, string>, identifier: string, displayLimit?: number): string;
+/**
+ * Build the `template` value used on send records at `/notifications` from a
+ * manifest record's fields. Three shapes:
+ *
+ *   System (no app_id):                 <model>.<name>
+ *   App on a standard model:            app_<app_id>.<model>.<name>
+ *   App on a custom (apps/<hex>/x) model: app_<app_id>.apps_<hex>_<x>.<name>
+ *
+ * The custom-model branch transforms slashes to underscores in the model
+ * segment.
+ *
+ * V2 system notifications have `name` literally ending in `.v2` (mirroring the
+ * `id` and the `v2: true` flag), but the send-record `template` strips that
+ * suffix. App notifications carry `v2: true` without the suffix in `name`, so
+ * they pass through unchanged.
+ *
+ * Returns undefined when `model` or `name` is missing.
+ */
+export declare function buildNotificationTemplate(record: NotificationRecord): string | undefined;
+/**
+ * Expand a display-form model into the candidate stored values to try at
+ * lookup time. A bare display token can mean either:
+ *   - the literal built-in model (e.g. `subscriptions`)
+ *   - an own-app model whose `apps/<own>/` prefix was stripped for display
+ * so we try both. `apps/<slug>/x` is resolved to `apps/<hex>/x`; an already-hex
+ * `apps/<hex>/x` passes through unchanged.
+ */
+export declare function expandModelCandidates(modelDisplay: string, appId: string, resolveAppId: (slug: string) => Promise<string>): Promise<string[]>;

package/dist/lib/inspect/notifications.js

@@ -0,0 +1,173 @@
+import { HEX24 } from '../apps/object-id.js';
+const APPS_MODEL = /^apps\/([^/]+)\/(.+)$/;
+/**
+ * Translate a stored model path into its display form.
+ *
+ *   apps/<own-hex>/<x>      → <x>          (own-app prefix is implicit in the slug)
+ *   apps/<other-hex>/<x>    → apps/<other-slug>/<x>
+ *   apps/<unknown-hex>/<x>  → unchanged    (preserve a paste-back form)
+ *   <built-in-model>        → unchanged
+ *
+ * Stripping `apps/<own>/` keeps the common case readable; the rare collision
+ * with a same-named built-in (e.g. an app model literally named
+ * `subscriptions`) is recovered by `expandModelCandidates` at lookup time.
+ */
+export function normalizeModelForDisplay(model, ownAppId, appSlugById) {
+    const match = model.match(APPS_MODEL);
+    if (!match)
+        return model;
+    const [, hex, rest] = match;
+    if (ownAppId && hex === ownAppId)
+        return rest;
+    const slug = appSlugById[hex];
+    return slug ? `apps/${slug}/${rest}` : model;
+}
+/**
+ * Produce the column-1 paste-back key for a notification.
+ *
+ *   System (no app_id):   record.id verbatim — already in `com.<model>.<name>` form.
+ *   App with model+name:  `app.<slug>.<model-display>.<name>`
+ *   Anything else:        record.id (degenerate, no meaningful slug)
+ *
+ * Notification identity is `(api, model, name, app_id?)`; collapsing on
+ * `(app_id, name)` alone caused two `notify_me.back-in-stock` rows
+ * (different `model`) to render identically.
+ */
+export function formatNotificationKey(record, appSlugById) {
+    if (!record.app_id) {
+        return record.id ?? '-';
+    }
+    if (!record.name || !record.model) {
+        return record.id ?? '-';
+    }
+    const slug = appSlugById[record.app_id] ?? record.app_id;
+    const modelDisplay = normalizeModelForDisplay(record.model, record.app_id, appSlugById);
+    return `app.${slug}.${modelDisplay}.${record.name}`;
+}
+/**
+ * Group a notification record. System rows (no app_id) are not store data —
+ * they belong to the platform and render under a `system` divider at the top.
+ */
+export function groupNotificationRecord(record, appSlugById) {
+    if (!record.app_id) {
+        return { slug: '<system>', label: 'system', order: 0 };
+    }
+    const resolved = appSlugById[record.app_id];
+    if (!resolved) {
+        return { slug: '<not resolved>', order: 2 };
+    }
+    return { slug: resolved };
+}
+/**
+ * Classify a notification identifier. The base `classifyIdentifier` collapses
+ * every dot-segment after `app.<part>.` into `name`, which loses the model.
+ * Notifications need a model-aware split, so they bypass the base classifier.
+ *
+ * Recognised shapes:
+ *   - 24-char hex                    → hex (delegate to base GET-by-id)
+ *   - com.<rest>                     → system_id (canonical platform id)
+ *   - app.<slug>.<model>.<name>      → app_full (triplet lookup)
+ *   - app.<slug>.<name>              → app_short (3-part legacy; ambiguous)
+ *   - bare <name>                    → bare (requires --app= scope; ambiguous)
+ *   - anything else                  → invalid
+ *
+ * Multi-segment names (e.g. `unpaid.v2`) only appear in system notifications,
+ * which arrive via the `com.*` form and never go through `app.*` parsing.
+ */
+export function parseNotificationKey(input) {
+    if (HEX24.test(input)) {
+        return { kind: 'hex', id: input };
+    }
+    if (input.startsWith('com.')) {
+        return { kind: 'system_id', id: input };
+    }
+    if (input.startsWith('app.')) {
+        const parts = input.split('.');
+        // Reject any post-prefix empty segment (`app..foo`, `app.foo.`, etc.).
+        // Without this, `app..foo` would classify as `app_short` with an empty
+        // slug and dispatch a useless `/client/apps` lookup.
+        const hasEmptySegment = parts.some((p, i) => i > 0 && p.length === 0);
+        if (hasEmptySegment) {
+            return { kind: 'invalid', input };
+        }
+        if (parts.length === 3) {
+            return { kind: 'app_short', slug: parts[1], name: parts[2] };
+        }
+        if (parts.length >= 4) {
+            const slug = parts[1];
+            const name = parts.at(-1);
+            const model = parts.slice(2, -1).join('.');
+            return { kind: 'app_full', slug, model, name };
+        }
+        return { kind: 'invalid', input };
+    }
+    if (/^[\w-]+$/.test(input)) {
+        return { kind: 'bare', name: input };
+    }
+    return { kind: 'invalid', input };
+}
+/**
+ * Render the disambiguation error body when a `(app_id, name)` query returns
+ * multiple notifications. Caller fetches with `limit = displayLimit + 1` so
+ * we can detect overflow without paging through the whole result set; if
+ * `results.length > displayLimit`, the surplus rows are dropped and a hint
+ * line is appended directing the user to the full key form.
+ */
+export function formatDisambiguationError(results, appSlugById, identifier, displayLimit = 10) {
+    const truncated = results.length > displayLimit;
+    const visible = truncated ? results.slice(0, displayLimit) : results;
+    const lines = visible.map((r) => `  ${formatNotificationKey(r, appSlugById)}`);
+    if (truncated) {
+        lines.push('  … (+more candidates; pass the full key)');
+    }
+    return `Multiple notifications match '${identifier}'. Use the full key:\n${lines.join('\n')}`;
+}
+/**
+ * Build the `template` value used on send records at `/notifications` from a
+ * manifest record's fields. Three shapes:
+ *
+ *   System (no app_id):                 <model>.<name>
+ *   App on a standard model:            app_<app_id>.<model>.<name>
+ *   App on a custom (apps/<hex>/x) model: app_<app_id>.apps_<hex>_<x>.<name>
+ *
+ * The custom-model branch transforms slashes to underscores in the model
+ * segment.
+ *
+ * V2 system notifications have `name` literally ending in `.v2` (mirroring the
+ * `id` and the `v2: true` flag), but the send-record `template` strips that
+ * suffix. App notifications carry `v2: true` without the suffix in `name`, so
+ * they pass through unchanged.
+ *
+ * Returns undefined when `model` or `name` is missing.
+ */
+export function buildNotificationTemplate(record) {
+    if (!record.model || !record.name) {
+        return undefined;
+    }
+    const name = record.v2 === true && record.name.endsWith('.v2')
+        ? record.name.slice(0, -'.v2'.length)
+        : record.name;
+    const match = record.model.match(APPS_MODEL);
+    const modelSegment = match ? `apps_${match[1]}_${match[2]}` : record.model;
+    const prefix = record.app_id ? `app_${record.app_id}.` : '';
+    return `${prefix}${modelSegment}.${name}`;
+}
+/**
+ * Expand a display-form model into the candidate stored values to try at
+ * lookup time. A bare display token can mean either:
+ *   - the literal built-in model (e.g. `subscriptions`)
+ *   - an own-app model whose `apps/<own>/` prefix was stripped for display
+ * so we try both. `apps/<slug>/x` is resolved to `apps/<hex>/x`; an already-hex
+ * `apps/<hex>/x` passes through unchanged.
+ */
+export async function expandModelCandidates(modelDisplay, appId, resolveAppId) {
+    const match = modelDisplay.match(APPS_MODEL);
+    if (match) {
+        const [, sluglike, rest] = match;
+        if (HEX24.test(sluglike))
+            return [modelDisplay];
+        const hex = await resolveAppId(sluglike);
+        return [`apps/${hex}/${rest}`];
+    }
+    return [modelDisplay, `apps/${appId}/${modelDisplay}`];
+}

package/dist/lib/inspect/settings.d.ts

@@ -0,0 +1,61 @@
+import { GroupInfo } from './table.js';
+export interface SettingRecord {
+    api?: string;
+    app_id?: string | null;
+    deprecated?: boolean | null;
+    fields?: Record<string, unknown>;
+    id?: string;
+    label?: string;
+    name?: string;
+}
+/**
+ * Settings identifier grammar (calibrated against `/data/:settings`).
+ *
+ *   `app.<slug-or-hex>` → kind 'app'  — slug must be translated to hex before
+ *                                       a path GET; hex passes through.
+ *   anything else valid → kind 'path' — direct path GET. The endpoint resolves
+ *                                       bare system names (`taxes`), bare app
+ *                                       hexes, and full dotted ids
+ *                                       (`com.taxes`) on the path. No `name`
+ *                                       query needed.
+ *   anything else      → kind 'invalid'
+ *
+ * The 3-segment `app.<slug>.<name>` form is rejected: settings collapse to one
+ * record per app at push time, so there is no sub-section identity the API can
+ * resolve back. Users wanting a single section run `--json | jq`.
+ */
+export type ParsedSettingsKey = {
+    kind: 'app';
+    ref: string;
+} | {
+    kind: 'path';
+    segment: string;
+} | {
+    input: string;
+    kind: 'invalid';
+};
+export declare function parseSettingsKey(input: string): ParsedSettingsKey;
+/**
+ * Produce the column-1 paste-back key for a settings record.
+ *
+ *   System (no app_id):  `record.name` (e.g. `taxes`).
+ *   App with slug:       `app.<slug>`.
+ *   App without slug:    `app.<hex>` (still pasteable — `app.<hex>` resolves).
+ *
+ * App records carry `name === app_id` (the hex), which is meaningless to a
+ * human; we never surface it. Ultimate fallback is `record.id` for degenerate
+ * records that have neither `app_id` nor `name`.
+ */
+export declare function formatSettingsKey(record: SettingRecord, appSlugById: Record<string, string>): string;
+/**
+ * Group a settings record. System rows (`app_id` null/undefined) belong to the
+ * platform and render under a `system` divider at the top, mirroring the
+ * notifications shape.
+ */
+export declare function groupSettingsRecord(record: SettingRecord, appSlugById: Record<string, string>): GroupInfo;
+/**
+ * `general` and `admin` are flagged `deprecated: true` in the base schema and
+ * still come back from the default list (no server-side filter equivalent —
+ * `deprecated[$ne]=true` doesn't take). Filter them out client-side.
+ */
+export declare function isDeprecatedRecord(record: SettingRecord): boolean;