@skrr-ai/cli 0.1.110 → 0.1.111

package/dist/lib/appSettings.d.ts

@@ -0,0 +1,3 @@
+import type { AppSettings, AppSettingsManifest } from '@skrr-ai/data-provider';
+export declare function readAppSettingsFile(file: string, manifest: AppSettingsManifest): AppSettings;
+export declare function formatAppSettings(manifest: AppSettingsManifest, settings: AppSettings, timezone?: string): string[];

package/dist/lib/appSettings.js

@@ -0,0 +1,71 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readAppSettingsFile = readAppSettingsFile;
+exports.formatAppSettings = formatAppSettings;
+const fs = __importStar(require("node:fs"));
+const data_provider_1 = require("@skrr-ai/data-provider");
+function readAppSettingsFile(file, manifest) {
+    // Bound before reading: the UTF-8 file cannot exceed four bytes per permitted UTF-16 character.
+    if (fs.statSync(file).size > data_provider_1.APP_SETTINGS_LIMITS.settingsJsonMaxChars * 4)
+        throw new Error('Settings file is too large');
+    const text = fs.readFileSync(file, 'utf8');
+    if (text.length > data_provider_1.APP_SETTINGS_LIMITS.settingsJsonMaxChars)
+        throw new Error('Settings file is too large');
+    const value = JSON.parse(text);
+    if (!data_provider_1.AppSettingsSchema.safeParse(value).success)
+        throw new Error('Settings must be a bounded record of non-secret primitive values');
+    const parsed = (0, data_provider_1.parseAppSettings)(manifest, value);
+    if (!parsed.ok)
+        throw new Error(parsed.issues.map((issue) => `${issue.path}: ${issue.message}`).join('; '));
+    return parsed.settings;
+}
+function formatAppSettings(manifest, settings, timezone = 'your account timezone') {
+    const jobs = (0, data_provider_1.appSettingsSchedulePreview)(manifest, settings);
+    if (jobs.some((job) => job.problem))
+        throw new Error(jobs
+            .filter((job) => job.problem)
+            .map((job) => `${(0, data_provider_1.plainAppLabel)(job.title)}: ${job.problem}`)
+            .join('; '));
+    return [
+        `Settings: ${JSON.stringify(settings)}`,
+        ...jobs.map((job) => `${(0, data_provider_1.plainAppLabel)(job.title)}: ${job.schedule} (${timezone})`),
+        ...(jobs.length
+            ? [
+                'These jobs run under your existing installer authority and may use model/runtime quota. Saving explicitly approves these settings and schedules.',
+            ]
+            : []),
+    ];
+}

package/dist/lib/appWebhooks.d.ts

@@ -0,0 +1,7 @@
+import type { AppWebhookList, AppWebhookView } from '@skrr-ai/data-provider';
+/** The list a server sent, or null when this CLI does not understand it ("cannot show", never "no hooks"). */
+export declare function readWebhookList(raw: unknown): AppWebhookList | null;
+/** One hook, in lines. The path is the endpoint's address on this platform; it is not a secret and is not a credential. */
+export declare function formatWebhook(view: AppWebhookView): string[];
+/** The lines of a whole list; an empty list says so in words. */
+export declare function formatWebhookList(list: AppWebhookList): string[];

package/dist/lib/appWebhooks.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readWebhookList = readWebhookList;
+exports.formatWebhook = formatWebhook;
+exports.formatWebhookList = formatWebhookList;
+/**
+ * `skrr apps webhooks list`: what the inbound hooks of an installed app look like to a terminal.
+ *
+ * It builds no URL. The call is `dataService.listAppInstallationWebhooks` (`@skrr-ai/data-provider`), which is
+ * what keeps this CLI and the web screen on one route (and what `domain-api-parity.spec.ts` checks). What lives
+ * here is what a terminal needs around it: reading the list through the contract, and saying each hook in a line.
+ *
+ * WHAT IT NEVER SHOWS. The list carries the existence of an endpoint, its state, its revision and its times, and
+ * nothing that works as a credential: the token and the signing secret are shown ONCE, by whatever made them, and
+ * cannot be read again by anyone. (No screen in the product makes one today: the routes admit only an interactive
+ * first-party session, so this says "no endpoint has been made yet" and does not send a person to a screen.) There is deliberately no `create`, `rotate` or `revoke` here
+ * (the routes admit only an interactive first-party session; a credential printed to a terminal lands in the
+ * transcript of whatever is running there), so this file has nothing to print that could be one.
+ */
+const data_provider_1 = require("@skrr-ai/data-provider");
+/** The list a server sent, or null when this CLI does not understand it ("cannot show", never "no hooks"). */
+function readWebhookList(raw) {
+    return (0, data_provider_1.parseAppWebhookList)(raw);
+}
+function endpointWords(view) {
+    const endpoint = view.endpoint;
+    if (!endpoint) {
+        return view.declared
+            ? 'declared; no endpoint yet (no screen in the product makes one today)'
+            : 'nothing';
+    }
+    if (endpoint.state === 'revoked') {
+        return `revoked ${endpoint.revokedAt ?? ''}`.trim();
+    }
+    const parts = [`active (rev ${endpoint.rev}, ${endpoint.lastSeq} accepted)`];
+    if (endpoint.previousValidUntil) {
+        parts.push(`the previous credentials still work until ${endpoint.previousValidUntil}`);
+    }
+    if (!view.declared) {
+        parts.push('the running version no longer declares it, so it receives nothing');
+    }
+    return parts.join('; ');
+}
+/** One hook, in lines. The path is the endpoint's address on this platform; it is not a secret and is not a credential. */
+function formatWebhook(view) {
+    const head = `${view.name}  ->  ${view.collection ?? '(not declared by the running version)'}${view.title ? `  "${view.title}"` : ''}`;
+    const lines = [head, `    ${endpointWords(view)}`];
+    if (view.endpoint) {
+        lines.push(`    POST ${view.endpoint.path}`);
+    }
+    return lines;
+}
+/** The lines of a whole list; an empty list says so in words. */
+function formatWebhookList(list) {
+    if (list.webhooks.length === 0) {
+        return ['This installation declares no webhooks.'];
+    }
+    return list.webhooks.flatMap((view) => formatWebhook(view));
+}

package/dist/lib/apps-command.d.ts

@@ -0,0 +1,44 @@
+import { BaseCommand } from '../base-command';
+/**
+ * The base of every `skrr apps` command that talks to the API.
+ *
+ * What it adds to `BaseCommand` is one thing: the loop's refusals (a stale revision, a path that is not
+ * allowed, a draft with errors) are not API failures to be translated generically, they are answers, and
+ * a harness that reads this CLI's exit and `--json` has to be able to tell `APP_REV_MISMATCH` (read again,
+ * retry) from `APP_CHECK_FAILED` (fix the draft) from a network error (try later). The ones this does not
+ * know (forbidden, not found, the server being down) are the base command's to say.
+ */
+export declare abstract class AppsCommand extends BaseCommand {
+    /** The id of the app the person named (an id or a slug). */
+    protected appId(ref: string): Promise<string>;
+    /**
+     * Say what went wrong with an INSTALLATION call (`/api/apps/installations`): the refusals that route makes
+     * are answers with a next step (a bundle that moved while the person decided, data that would be deleted),
+     * so they come under their own machine code and exit, and a refusal that is not one of them is the base
+     * command's. Never returns.
+     */
+    protected failInstallation(error: unknown, { subject }?: {
+        subject?: string;
+    }): never;
+    /**
+     * Say what went wrong with a call to the PERSON channel (`apps data put | query`): a document that was not given or
+     * is not JSON (before anything was sent), a refusal from the contract's closed set, or a conflict, which is an
+     * answer ("someone wrote first": the revision to retry from) and exits non-zero because nothing was written. What
+     * the channel does not say (the server being down, a sign-in that expired) is the base command's. Never returns.
+     */
+    protected failPersonData(error: unknown, target: {
+        installation: string;
+        collection: string;
+        id?: string;
+    }): never;
+    /**
+     * Say what went wrong with a REPORT: the refusals only a report makes (a reason the Store does not take, a
+     * second report on the same version) get their own machine code and words; the ones an installation call
+     * also makes (not found, forbidden) are {@link failInstallation}'s. Never returns.
+     */
+    protected failReport(error: unknown): never;
+    /** Say what went wrong with a call, in the loop's own terms where it has them. Never returns. */
+    protected failApps(error: unknown, { subject }?: {
+        subject?: string;
+    }): never;
+}

package/dist/lib/apps-command.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppsCommand = void 0;
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../base-command");
+const apps_1 = require("./apps");
+const appInstallations_1 = require("./appInstallations");
+const appsFs_1 = require("./appsFs");
+const appData_1 = require("./appData");
+/**
+ * The base of every `skrr apps` command that talks to the API.
+ *
+ * What it adds to `BaseCommand` is one thing: the loop's refusals (a stale revision, a path that is not
+ * allowed, a draft with errors) are not API failures to be translated generically, they are answers, and
+ * a harness that reads this CLI's exit and `--json` has to be able to tell `APP_REV_MISMATCH` (read again,
+ * retry) from `APP_CHECK_FAILED` (fix the draft) from a network error (try later). The ones this does not
+ * know (forbidden, not found, the server being down) are the base command's to say.
+ */
+class AppsCommand extends base_command_1.BaseCommand {
+    /** The id of the app the person named (an id or a slug). */
+    async appId(ref) {
+        try {
+            return await (0, apps_1.resolveAppRef)(ref);
+        }
+        catch (error) {
+            if (error instanceof apps_1.AppRefError) {
+                return this.failWithCliError({
+                    message: error.message,
+                    code: error.code === 'ambiguous' ? 'APP_AMBIGUOUS' : 'APP_NOT_FOUND',
+                    exit: error.code === 'ambiguous' ? 1 : 4,
+                    retryable: false,
+                });
+            }
+            return this.handleApiError(error);
+        }
+    }
+    /**
+     * Say what went wrong with an INSTALLATION call (`/api/apps/installations`): the refusals that route makes
+     * are answers with a next step (a bundle that moved while the person decided, data that would be deleted),
+     * so they come under their own machine code and exit, and a refusal that is not one of them is the base
+     * command's. Never returns.
+     */
+    failInstallation(error, { subject } = {}) {
+        const refusal = (0, apps_1.readAppsRefusal)(error);
+        if (refusal && (0, data_provider_1.isAppInstallationConflict)(refusal.error)) {
+            const words = (0, appInstallations_1.describeInstallationConflict)(refusal, this.config.bin);
+            if (words !== null) {
+                return this.failWithCliError({
+                    message: words,
+                    code: appInstallations_1.ALL_INSTALLATION_REFUSAL_CODES[refusal.error],
+                    ...(refusal.status === undefined ? {} : { status: refusal.status }),
+                    exit: (0, appInstallations_1.installationRefusalExit)(refusal.error),
+                    retryable: false,
+                    details: {
+                        ...(refusal.reason === undefined ? {} : { reason: refusal.reason }),
+                        ...(refusal.docCount === undefined ? {} : { docCount: refusal.docCount }),
+                        ...(refusal.installationId === undefined
+                            ? {}
+                            : { installationId: refusal.installationId }),
+                        ...(refusal.current ? { current: refusal.current } : {}),
+                    },
+                });
+            }
+        }
+        return this.failApps(error, subject ? { subject } : {});
+    }
+    /**
+     * Say what went wrong with a call to the PERSON channel (`apps data put | query`): a document that was not given or
+     * is not JSON (before anything was sent), a refusal from the contract's closed set, or a conflict, which is an
+     * answer ("someone wrote first": the revision to retry from) and exits non-zero because nothing was written. What
+     * the channel does not say (the server being down, a sign-in that expired) is the base command's. Never returns.
+     */
+    failPersonData(error, target) {
+        if (error instanceof appData_1.AppDataInputError) {
+            return this.failWithCliError({
+                message: error.message,
+                code: error.code,
+                exit: 2,
+                retryable: false,
+            });
+        }
+        if (error instanceof appsFs_1.AppsFsError) {
+            return this.failApps(error);
+        }
+        const failure = (0, appData_1.readPersonDataFailure)(error);
+        if (failure === null) {
+            return this.failApps(error);
+        }
+        if (failure.kind === 'conflict') {
+            return this.failWithCliError({
+                message: (0, appData_1.describePersonDataConflict)(failure, { ...target, id: target.id ?? '<id>' }, this.config.bin),
+                code: appData_1.PERSON_DATA_CONFLICT_CODES[failure.conflict],
+                ...(failure.status === undefined ? {} : { status: failure.status }),
+                exit: (0, appData_1.personDataFailureExit)(failure),
+                retryable: false,
+                details: {
+                    conflict: failure.conflict,
+                    ...(failure.currentRev === undefined ? {} : { currentRev: failure.currentRev }),
+                },
+            });
+        }
+        return this.failWithCliError({
+            message: (0, appData_1.describePersonDataRefusal)(failure, this.config.bin),
+            code: appData_1.PERSON_DATA_REFUSAL_CODES[failure.code],
+            ...(failure.status === undefined ? {} : { status: failure.status }),
+            exit: (0, appData_1.personDataFailureExit)(failure),
+            retryable: (0, appData_1.personDataFailureRetryable)(failure),
+            ...(failure.retryAfterMs === undefined
+                ? {}
+                : { details: { retryAfterMs: failure.retryAfterMs } }),
+        });
+    }
+    /**
+     * Say what went wrong with a REPORT: the refusals only a report makes (a reason the Store does not take, a
+     * second report on the same version) get their own machine code and words; the ones an installation call
+     * also makes (not found, forbidden) are {@link failInstallation}'s. Never returns.
+     */
+    failReport(error) {
+        const refusal = (0, apps_1.readAppsRefusal)(error);
+        const machineCode = refusal?.error ? appInstallations_1.REPORT_REFUSAL_CODES[refusal.error] : undefined;
+        if (refusal && machineCode) {
+            const words = (0, appInstallations_1.describeReportRefusal)(refusal, this.config.bin);
+            if (words !== null) {
+                return this.failWithCliError({
+                    message: words,
+                    code: machineCode,
+                    ...(refusal.status === undefined ? {} : { status: refusal.status }),
+                    exit: 1,
+                    retryable: false,
+                });
+            }
+        }
+        return this.failInstallation(error);
+    }
+    /** Say what went wrong with a call, in the loop's own terms where it has them. Never returns. */
+    failApps(error, { subject } = {}) {
+        if (error instanceof appsFs_1.AppsFsError) {
+            return this.failWithCliError({
+                message: error.message,
+                code: `APP_FS_${error.code.toUpperCase()}`,
+                exit: 1,
+                retryable: false,
+                details: { at: error.at },
+            });
+        }
+        const refusal = (0, apps_1.readAppsRefusal)(error);
+        if (refusal && refusal.error && apps_1.APPS_REFUSAL_CODES[refusal.error]) {
+            return this.failWithCliError({
+                message: (0, apps_1.describeAppsRefusal)(refusal, this.config.bin),
+                code: apps_1.APPS_REFUSAL_CODES[refusal.error],
+                ...(refusal.status === undefined ? {} : { status: refusal.status }),
+                exit: 1,
+                retryable: false,
+                details: {
+                    ...(refusal.currentRev === undefined ? {} : { currentRev: refusal.currentRev }),
+                    ...(refusal.problems ? { problems: refusal.problems } : {}),
+                    ...(refusal.check ? { check: refusal.check } : {}),
+                },
+            });
+        }
+        return this.handleApiError(error, subject ? { subject } : {});
+    }
+}
+exports.AppsCommand = AppsCommand;

package/dist/lib/apps.d.ts

@@ -0,0 +1,45 @@
+import type { AppCheckReport, AppListedEntry, AppPathProblem, AppSummary } from '@skrr-ai/data-provider';
+export declare class AppRefError extends Error {
+    readonly code: 'not_found' | 'ambiguous';
+    constructor(code: 'not_found' | 'ambiguous', message: string);
+}
+/**
+ * The id of the app a person named: an id (`app_...`) is taken as it is, a slug is looked up among the
+ * apps they can edit. Two apps with one slug (their own and one shared with them) is ambiguous and says
+ * both ids.
+ */
+export declare function resolveAppRef(ref: string): Promise<string>;
+/** What a refusal the server made on purpose carries (`{ error, message, ...details }`). */
+export interface AppsRefusal {
+    status?: number;
+    error?: string;
+    message?: string;
+    currentRev?: number;
+    previewRev?: number;
+    path?: string;
+    problems?: AppPathProblem[];
+    check?: AppCheckReport;
+    /** An installation call's refusal (`appInstallations.ts`): the reason a `forbidden` carries, and what a conflict names. */
+    reason?: string;
+    docCount?: number;
+    installationId?: string;
+    current?: {
+        versionId?: string;
+        bundleHash?: string;
+    };
+    /** What an install was MISSING (`issues`) and why what it carried would not do (`unsuitable`), on a `binding_required`. */
+    issues?: unknown;
+    unsuitable?: unknown;
+    /** What an app declares that the principal it would be installed on cannot serve, on a `principal_scope_unserved`. */
+    unserved?: unknown;
+}
+/** Read the refusal out of an API error, or null when the error is not one of ours (a network failure, an HTML error page). */
+export declare function readAppsRefusal(error: unknown): AppsRefusal | null;
+/** Refusals this CLI reads itself, with the machine code it exits under. Everything else is the base command's. */
+export declare const APPS_REFUSAL_CODES: Record<string, string>;
+/** The words for a refusal: what it was, the revision to retry from, each problem, what to do. */
+export declare function describeAppsRefusal(refusal: AppsRefusal, bin: string): string;
+/** A table row of the apps a person can edit. */
+export declare function formatAppRow(app: AppSummary): string;
+/** `dir/` and `file  (size)` lines, as `ls` would. */
+export declare function formatEntryLine(entry: AppListedEntry): string;

package/dist/lib/apps.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APPS_REFUSAL_CODES = exports.AppRefError = void 0;
+exports.resolveAppRef = resolveAppRef;
+exports.readAppsRefusal = readAppsRefusal;
+exports.describeAppsRefusal = describeAppsRefusal;
+exports.formatAppRow = formatAppRow;
+exports.formatEntryLine = formatEntryLine;
+/**
+ * `skrr apps`: what the commands share. The domain lib of the Agent App authoring loop.
+ *
+ * It builds no URL. Every call to the API is a `dataService` function (`@skrr-ai/data-provider`), which
+ * is what keeps this CLI, the web editor and the MCP tools on one set of routes (and what
+ * `domain-api-parity.spec.ts` checks). What lives here is what a terminal needs around them: finding an
+ * app by the name a person types, reading a refusal the server made on purpose, and saying a result.
+ */
+const data_provider_1 = require("@skrr-ai/data-provider");
+const appInstallations_1 = require("./appInstallations");
+/** An app's public id: what the API addresses an app by. A slug cannot look like one (no underscore). */
+const APP_ID = /^app_[A-Za-z0-9_-]{1,60}$/;
+class AppRefError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'AppRefError';
+        this.code = code;
+    }
+}
+exports.AppRefError = AppRefError;
+/**
+ * The id of the app a person named: an id (`app_...`) is taken as it is, a slug is looked up among the
+ * apps they can edit. Two apps with one slug (their own and one shared with them) is ambiguous and says
+ * both ids.
+ */
+async function resolveAppRef(ref) {
+    if (APP_ID.test(ref)) {
+        return ref;
+    }
+    const { apps, truncated } = await data_provider_1.dataService.listMyApps({ limit: data_provider_1.APP_DRAFT_LIMITS.appsListMax });
+    const matches = apps.filter((app) => app.slug === ref);
+    if (matches.length === 1) {
+        return matches[0].id;
+    }
+    if (matches.length === 0) {
+        // A cut list cannot say "no such app", only "not among these": the person may edit more than one page of them.
+        throw new AppRefError('not_found', truncated === true
+            ? `No app called "${ref}" is among the ${apps.length} you changed most recently, and you can edit more than that, so it may exist. Give its id (app_...) instead of its slug.`
+            : `No app you can edit is called "${ref}". List yours with \`apps list\`, or give the id (app_...).`);
+    }
+    throw new AppRefError('ambiguous', `"${ref}" names more than one app (${matches.map((app) => app.id).join(', ')}): give the id.`);
+}
+/** Read the refusal out of an API error, or null when the error is not one of ours (a network failure, an HTML error page). */
+function readAppsRefusal(error) {
+    const e = error;
+    if (!e || typeof e.body !== 'string') {
+        return null;
+    }
+    try {
+        const body = JSON.parse(e.body);
+        if (!body || typeof body !== 'object' || typeof body.error !== 'string') {
+            return null;
+        }
+        return {
+            ...(typeof e.status === 'number' ? { status: e.status } : {}),
+            error: body.error,
+            ...(typeof body.message === 'string' ? { message: body.message } : {}),
+            ...(typeof body.currentRev === 'number' ? { currentRev: body.currentRev } : {}),
+            ...(typeof body.previewRev === 'number' ? { previewRev: body.previewRev } : {}),
+            ...(typeof body.path === 'string' ? { path: body.path } : {}),
+            ...(Array.isArray(body.problems) ? { problems: body.problems } : {}),
+            ...(body.check && typeof body.check === 'object'
+                ? { check: body.check }
+                : {}),
+            ...(typeof body.reason === 'string' ? { reason: body.reason } : {}),
+            ...(typeof body.docCount === 'number' ? { docCount: body.docCount } : {}),
+            ...(typeof body.installationId === 'string' ? { installationId: body.installationId } : {}),
+            ...(body.current && typeof body.current === 'object'
+                ? { current: body.current }
+                : {}),
+            ...(Array.isArray(body.issues) ? { issues: body.issues } : {}),
+            ...(body.unsuitable && typeof body.unsuitable === 'object'
+                ? { unsuitable: body.unsuitable }
+                : {}),
+            ...(Array.isArray(body.unserved) ? { unserved: body.unserved } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Refusals this CLI reads itself, with the machine code it exits under. Everything else is the base command's. */
+exports.APPS_REFUSAL_CODES = {
+    rev_mismatch: 'APP_REV_MISMATCH',
+    invalid: 'APP_INVALID',
+    exists: 'APP_EXISTS',
+    check_failed: 'APP_CHECK_FAILED',
+    limit: 'APP_LIMIT',
+    visibility_unavailable: 'APP_VISIBILITY_UNAVAILABLE',
+    preview_superseded: 'APP_PREVIEW_SUPERSEDED',
+    preview_expired: 'APP_PREVIEW_EXPIRED',
+    // the installation calls (`appInstallations.ts`): installing, approving again, moving, pausing, removing
+    ...appInstallations_1.INSTALLATION_REFUSAL_CODES,
+};
+/** The words for a refusal: what it was, the revision to retry from, each problem, what to do. */
+function describeAppsRefusal(refusal, bin) {
+    const installation = (0, appInstallations_1.describeInstallationConflict)(refusal, bin);
+    if (installation !== null) {
+        return installation;
+    }
+    const lines = [refusal.message || refusal.error || 'refused'];
+    if (refusal.error === 'rev_mismatch' && refusal.currentRev !== undefined) {
+        lines.push(`→ The draft is now at revision ${refusal.currentRev}. Read it again (\`${bin} apps file ls <app>\` shows \`rev\`), merge, and retry with --expected-rev ${refusal.currentRev}.`);
+    }
+    if (refusal.error === 'preview_superseded' || refusal.error === 'preview_expired') {
+        lines.push(`→ Open a new preview: \`${bin} apps preview <app>\`.`);
+    }
+    for (const problem of (refusal.problems ?? []).slice(0, 10)) {
+        lines.push(`  - ${problem.path ? `${problem.path}: ` : ''}${problem.message}`);
+    }
+    if ((refusal.problems ?? []).length > 10) {
+        lines.push(`  - ...and ${(refusal.problems ?? []).length - 10} more`);
+    }
+    if (refusal.check) {
+        const first = refusal.check.issues.filter((issue) => issue.severity === 'error').slice(0, 5);
+        for (const issue of first) {
+            lines.push(`  - ${issue.code}${issue.path ? ` ${issue.path}${issue.line ? `:${issue.line}` : ''}` : ''}: ${issue.message}`);
+        }
+        lines.push(`→ Run \`${bin} apps check-draft <app>\` for the whole report.`);
+    }
+    return lines.join('\n');
+}
+/** A table row of the apps a person can edit. */
+function formatAppRow(app) {
+    return [
+        app.id,
+        app.slug.padEnd(24),
+        `rev ${app.draftRev ?? '-'}`.padEnd(8),
+        app.latestVersionId ? `latest ${app.latestVersionId}` : 'no published version',
+    ].join('  ');
+}
+/** `dir/` and `file  (size)` lines, as `ls` would. */
+function formatEntryLine(entry) {
+    if (entry.kind === 'dir') {
+        return `${entry.name}/`;
+    }
+    const where = entry.storage === 'asset' ? 'asset' : `${entry.size ?? 0} bytes`;
+    return `${entry.name}  (${where})`;
+}

package/dist/lib/appsCheck.d.ts

@@ -0,0 +1,12 @@
+import type { AppCheckReport, AppDraftFile } from '@skrr-ai/data-provider';
+/** Compile `source` as a classic script and say what is wrong with it, or null. */
+export declare function compileScript(source: string): {
+    message: string;
+    line?: number;
+} | null;
+/** Check a package that is already in memory. */
+export declare function checkLocalFiles(files: readonly AppDraftFile[], options?: {
+    expectedId?: string;
+}): AppCheckReport;
+/** The report as lines for a terminal: the verdict, then each finding with where it is and what to do. */
+export declare function formatAppCheckReport(report: AppCheckReport): string[];