@swell/cli 2.6.0 → 2.7.1

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/extensions.d.ts

@@ -0,0 +1,267 @@
+import { GroupInfo } from './table.js';
+/**
+ * Manifest entry shape, matching `extensions[]` in the deployed app record
+ * and in local `./swell.json`. Mirrors the schema at
+ * schema-api-server/api/admin/models/apps.json:429-491.
+ */
+export interface ManifestEntry {
+    id: string;
+    type: 'payment' | 'tax' | 'shipping';
+    name?: string;
+    description?: string;
+    setting?: string;
+    subscriptions?: boolean;
+    method?: string;
+    gateway?: string;
+    method_logo_src?: string;
+    method_icon_src?: string;
+    gateway_logo_src?: string;
+    gateway_icon_src?: string;
+    carrier?: string;
+    carrier_logo_src?: string;
+    carrier_icon_src?: string;
+    [key: string]: unknown;
+}
+/** CLI-resolved type. Diverges from raw manifest `type` for payment (card vs alt). */
+export type ExtensionType = 'card' | 'alt' | 'shipping' | 'tax';
+export type ExtensionStatus = 'not deployed' | 'not activated' | 'app id mismatch' | 'id mismatch' | 'not selected' | 'gateway missing' | 'not enabled' | 'no handler' | 'handler mismatch' | 'activated';
+export type ActionOwner = 'dev' | 'merchant' | null;
+export interface FunctionRecord {
+    id?: string;
+    name?: string;
+    enabled?: boolean;
+    app_id?: string;
+    extension?: string;
+    model?: {
+        events?: string[];
+    };
+}
+export interface ComponentRecord {
+    id?: string;
+    name?: string;
+    file_path?: string;
+    values?: {
+        [key: string]: unknown;
+        extension?: string;
+    };
+    [key: string]: unknown;
+}
+export interface PaymentMethodRecord {
+    id?: string;
+    name?: string;
+    gateway?: string;
+    extension_app_id?: string;
+    extension_config_id?: string;
+    enabled?: boolean;
+    activated?: boolean;
+    [key: string]: unknown;
+}
+export interface PaymentGatewayRecord {
+    id?: string;
+    name?: string;
+    extension_app_id?: string;
+    extension_config_id?: string;
+    [key: string]: unknown;
+}
+export interface ShippingCarrierRecord {
+    id?: string;
+    name?: string;
+    enabled?: boolean;
+    extension_app_id?: string;
+    extension_config_id?: string;
+    [key: string]: unknown;
+}
+export interface TaxSettingsRecord {
+    extension_app_id?: string;
+    extension_config_id?: string;
+    [key: string]: unknown;
+}
+export interface PaymentSettings {
+    methods?: PaymentMethodRecord[];
+    gateways?: PaymentGatewayRecord[];
+    [key: string]: unknown;
+}
+export interface ShippingSettings {
+    carriers?: ShippingCarrierRecord[];
+    [key: string]: unknown;
+}
+export interface NativeBinding {
+    path: string;
+    record: unknown;
+    field_checks: Record<string, boolean>;
+}
+export interface BoundFunction {
+    id?: string;
+    name?: string;
+    extension?: string;
+    enabled?: boolean;
+    model?: {
+        events?: string[];
+    };
+}
+export interface BoundComponent {
+    id?: string;
+    name?: string;
+    extension?: string;
+    file_path?: string;
+}
+export interface LocalDiff {
+    changed_fields: string[];
+    local: ManifestEntry;
+    deployed: ManifestEntry;
+}
+export interface ExtensionDetail {
+    status: ExtensionStatus;
+    action_owner: ActionOwner;
+    action: string | null;
+    type: ExtensionType | null;
+    manifest: ManifestEntry | null;
+    native_bindings: NativeBinding[];
+    bound: {
+        components: BoundComponent[];
+        functions: BoundFunction[];
+    };
+    required_events: string[];
+    missing_required_events: string[];
+    local_diff: LocalDiff | null;
+}
+/** Parsed identifier for `swell inspect extensions <id>`. */
+export type ParsedExtensionKey = {
+    appPart: string;
+    extId: string;
+    kind: 'slug';
+} | {
+    kind: 'name';
+    name: string;
+} | {
+    input: string;
+    kind: 'invalid';
+};
+/**
+ * Parse a `swell inspect extensions` identifier.
+ *
+ * Accepts:
+ *   - `app.<slug>.<extId>`  → kind 'slug'
+ *   - bare `<extId>`        → kind 'name' (requires --app= scope at the call site)
+ *
+ * 24-char hex is intentionally NOT a valid form — the synthesized resource has
+ * no canonical 24-char id. Callers should reject hex shapes upstream so the
+ * error message can be clear about the cause.
+ */
+export declare function parseExtensionKey(input: string): ParsedExtensionKey;
+/** Build the column-1 paste-back key for a row. */
+export declare function formatExtensionKey(slug: string, extId: string): string;
+/**
+ * Resolve a manifest entry to the CLI's type taxonomy. Payment splits on
+ * `method`: when `method === 'card'` the extension provides a card gateway;
+ * otherwise it's an alt method. The platform formula at
+ * schema-api-server/api/admin/models/apps.json:457-458 defaults `method` to
+ * `id` when unset, so a payment extension whose `id` happens to be `card`
+ * resolves to `card` even with no explicit `method`.
+ */
+export declare function resolveExtensionType(entry: Pick<ManifestEntry, 'type' | 'method' | 'id'>): ExtensionType;
+/** Apply the platform's `if(method, method, id)` formula. */
+export declare function paymentMethodIdFor(entry: Pick<ManifestEntry, 'method' | 'id'>): string;
+/** Shipping records use `app_<appId>_<extId>` as both the row id and the carrier id. */
+export declare function shippingBindId(appId: string, extId: string): string;
+/** Card-gateway records use the same id form as shipping rows. */
+export declare function gatewayBindId(appId: string, extId: string): string;
+/**
+ * Required events per extension type, in the `<model>/<event>` form that
+ * function records actually store.
+ *
+ * Verified against:
+ *   schema-api-server/server/vault.js:1818,1894          (payment.create_intent)
+ *   schema-api-server/api/com/features/payments/index.js:701-757
+ *                                                        (payment.charge, payment.refund, dispatcher gate)
+ *   schema-api-server/server/vault.js:2304-2322          (card-gateway intent path)
+ *   schema-api-server/api/com/features/orders/shipping.js:411-417,424-431,452-458
+ *                                                        (shipping dispatch + enabled gate)
+ *   schema-api-server/api/com/features/orders/taxes.js:123-176
+ *                                                        (tax dispatch)
+ *   schema-api-server/api/com/features/orders/extensions.test.js:85,95,179,271,290,303,671,704
+ *                                                        (event-name format fixtures)
+ */
+export declare function requiredEventsFor(type: ExtensionType): string[];
+/**
+ * Strip `before:` / `after:` hook-type prefix from an event identifier.
+ *
+ * Both prefixes are platform-supported on function records; bare events
+ * default to `after`. For required-event coverage we treat any prefix as
+ * equivalent so that a function declaring `before:payment.charge` covers a
+ * required `payments/payment.charge`. Cite:
+ * schema-api-server/api/com/features/orders/extensions.test.js:95.
+ */
+export declare function stripHookPrefix(event: string): string;
+/**
+ * Compute the set of bare event identifiers covered by a function record's
+ * `model.events` list. The function event format is `<model>/<event>` with
+ * an optional `before:`/`after:` prefix on the bare event part. Returns the
+ * full `<model>/<event>` string with hook prefixes stripped from the event.
+ */
+export declare function eventsCoveredByFunctions(functions: Pick<FunctionRecord, 'model'>[]): Set<string>;
+/** Required events not covered by any of the bound functions. */
+export declare function missingRequiredEvents(type: ExtensionType, functions: Pick<FunctionRecord, 'model'>[]): string[];
+/** Lift a component record into the synthesized `BoundComponent` shape. */
+export declare function liftBoundComponent(record: ComponentRecord): BoundComponent;
+/** Lift a function record into the synthesized `BoundFunction` shape. */
+export declare function liftBoundFunction(record: FunctionRecord): BoundFunction;
+/**
+ * Compare a local manifest entry against the deployed entry. Uses deep
+ * equality for change detection and reports differing top-level keys. When
+ * the entries are equal, returns `null`.
+ */
+export declare function diffManifestEntries(local: ManifestEntry, deployed: ManifestEntry): LocalDiff | null;
+export interface BuildDetailInput {
+    appId: string;
+    appSlug: string;
+    extId: string;
+    manifest: ManifestEntry | null;
+    /** True when the local manifest has the entry but the deployed app record doesn't. */
+    notDeployed?: boolean;
+    payments?: PaymentSettings | null;
+    shipments?: ShippingSettings | null;
+    taxes?: TaxSettingsRecord | null;
+    /** Functions in the same app whose top-level `extension` matches this extId. */
+    functions: FunctionRecord[];
+    /** Components in the same app whose `values.extension` matches this extId. */
+    components: ComponentRecord[];
+    localDiff?: LocalDiff | null;
+}
+export interface BuildOrphanInput {
+    appId: string;
+    appSlug: string;
+    /** The unresolved extension value taken from the function/component. */
+    unresolvedId: string;
+    functions: FunctionRecord[];
+    components: ComponentRecord[];
+}
+/** Build the synthesized envelope for a regular (non-orphan) extension row. */
+export declare function buildExtensionDetail(input: BuildDetailInput): ExtensionDetail;
+/** Build the synthesized envelope for an orphan row. */
+export declare function buildOrphanDetail(input: BuildOrphanInput): ExtensionDetail;
+/**
+ * List-mode meta string for one row. Returns `undefined` when the row has
+ * nothing surface-worthy beyond the type tag (which is always present).
+ */
+export declare function listMetaFor(detail: ExtensionDetail): string;
+/**
+ * List-mode meta string for an orphan row. The type tag is replaced with
+ * the status word since there's no manifest to derive type from.
+ */
+export declare function orphanListMeta(fnCount: number, compCount: number): string;
+/**
+ * `Next steps:` lines per status. Runnable shell commands come first,
+ * merchant-UI lines come second prefixed with `(merchant)` so an agent can
+ * filter. Empty array when there are no actionable next steps.
+ */
+export declare function nextStepLines(detail: ExtensionDetail): string[];
+/**
+ * Section ordering for the list view. Apps render alphabetically; orphan
+ * rows land in a single trailing `<orphans>` group.
+ */
+export declare function listGroupForApp(slug: string): GroupInfo;
+export declare function listGroupForOrphans(): GroupInfo;
+/** True when a function/component "belongs to" an extension by direct match. */
+export declare function functionMatchesExtension(fn: FunctionRecord, extId: string): boolean;
+export declare function componentMatchesExtension(comp: ComponentRecord, extId: string): boolean;