@skrr-ai/cli 0.1.110 → 0.1.111

package/dist/lib/appsCheck.js

@@ -0,0 +1,173 @@
+"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.compileScript = compileScript;
+exports.checkLocalFiles = checkLocalFiles;
+exports.formatAppCheckReport = formatAppCheckReport;
+/**
+ * `skrr apps check`: the authoring self-check, offline.
+ *
+ * The check is `checkAppPackage` in `@skrr-ai/data-provider`, the one implementation the server runs
+ * too (`app_check`, and the gate before a version is cut), so what a harness is told here is what the
+ * platform will say. This file supplies the two things that package cannot do for itself:
+ *
+ *  - compile a classic script (`vm.Script`, which parses and never runs), and
+ *  - read the frame heuristics. That scanner is `widgetStaticScan.ts`, the one `skrr widgets check`
+ *    runs, passed in as it is: this EXTENDS the widget check to a whole package and does not copy it.
+ *    (The server's copy is transpiled from the same file and held to it by a spec.)
+ *
+ * It reaches no API. A package on disk is read with `appsFs.ts`, which never follows a link.
+ */
+const vm = __importStar(require("node:vm"));
+const data_provider_1 = require("@skrr-ai/data-provider");
+const widgetStaticScan_1 = require("./widgetStaticScan");
+/** Compile `source` as a classic script and say what is wrong with it, or null. */
+function compileScript(source) {
+    try {
+        new vm.Script(source, { filename: 'app.js' });
+        return null;
+    }
+    catch (error) {
+        const message = error?.message;
+        const stack = error?.stack;
+        const head = typeof stack === 'string' ? stack.split('\n')[0] : '';
+        const at = /^app\.js:(\d+)/.exec(head);
+        return {
+            message: typeof message === 'string' ? message : String(error),
+            ...(at ? { line: Number(at[1]) } : {}),
+        };
+    }
+}
+function scanSandbox(sections) {
+    const scan = (0, widgetStaticScan_1.scanWidgetSource)(sections);
+    return {
+        findings: scan.findings.map((found) => ({
+            severity: found.severity,
+            code: found.code,
+            section: found.section,
+            line: found.line,
+            message: found.message,
+            ...(found.fix ? { fix: found.fix } : {}),
+        })),
+        inlineScripts: scan.inlineScripts,
+    };
+}
+/** Check a package that is already in memory. */
+function checkLocalFiles(files, options = {}) {
+    return (0, data_provider_1.checkAppPackage)(files, {
+        ...(options.expectedId === undefined ? {} : { expectedId: options.expectedId }),
+        checkScriptSyntax: compileScript,
+        scanSandbox,
+    });
+}
+/** How a finding's effect on a store listing reads in a terminal. Words, not colours: the line is also read by an agent. */
+const TIER_TAG = {
+    block: 'keeps it out of the store',
+    warn: 'shown to the installer',
+    info: 'shown, low-key',
+    unanalyzable: 'cannot analyze',
+};
+/** The store gate in one sentence per outcome. None of them is a green light. */
+function storeLine(report) {
+    const { outcome, counts, store } = report.security;
+    switch (outcome) {
+        case 'blocked_for_store':
+            return `store: ${store.blockers} finding${store.blockers === 1 ? '' : 's'} would keep this out of the store${store.strict ? ' (under the stricter reading for a first app or a version that asks for more)' : ''}. Drafts, versions and private installs are not affected.`;
+        case 'cannot_analyze':
+            return `store: ${counts.unanalyzable} place${counts.unanalyzable === 1 ? '' : 's'} could not be read. Nothing else keeps it out of the store, and nothing says it is safe.`;
+        case 'findings':
+            return `store: ${counts.warn + counts.info} finding${counts.warn + counts.info === 1 ? '' : 's'} to read; none keeps it out of the store.`;
+        default:
+            return 'store: nothing found. That is not a statement that the app is safe; see below.';
+    }
+}
+function placeOf(issue) {
+    if (!issue.path)
+        return '';
+    return issue.line ? `${issue.path}:${issue.line}` : issue.path;
+}
+/** The report as lines for a terminal: the verdict, then each finding with where it is and what to do. */
+function formatAppCheckReport(report) {
+    const lines = [];
+    const { errors, warnings, blockers } = report.summary;
+    lines.push(report.ok
+        ? `ok: no errors${warnings > 0 ? `, ${warnings} warning${warnings === 1 ? '' : 's'}` : ''}`
+        : `not ok: ${errors} error${errors === 1 ? '' : 's'}${warnings > 0 ? `, ${warnings} warning${warnings === 1 ? '' : 's'}` : ''}` +
+            (blockers < errors
+                ? ` (${blockers} would stop a version being cut; the other ${errors - blockers} ${errors - blockers === 1 ? 'is a guess from reading the source' : 'are guesses from reading the source'})`
+                : ' (all would stop a version being cut)'));
+    lines.push(`files: ${report.files.count}/${report.files.maxFiles}, ${report.files.chars}/${report.files.maxChars} characters`);
+    if (report.entry) {
+        const part = (name, use) => `${name} ${use.used}/${use.max} (${use.percent}%)`;
+        lines.push(`entry: ${part('css', report.entry.css)}, ${part('html', report.entry.html)}, ${part('js', report.entry.js)}, ${part('total', report.entry.total)}`);
+    }
+    if (report.capabilities.declared.length > 0 || report.capabilities.used.length > 0) {
+        lines.push(`capabilities: declared [${report.capabilities.declared.join(', ')}], used by the script [${report.capabilities.used.join(', ')}]`);
+    }
+    // A report from a server older than the store gate has no `security` section: print what it has.
+    const security = report.security;
+    if (security) {
+        lines.push(storeLine(report));
+        if (!security.scan.complete) {
+            lines.push(`scan: stopped before the end (${security.scan.filesSkipped} of ${security.scan.filesScanned + security.scan.filesSkipped} files not read in full).`);
+        }
+        if (security.disabledRules.length > 0) {
+            lines.push(`policy: ${security.disabledRules.length} rule(s) switched off: ${security.disabledRules.join(', ')}`);
+        }
+    }
+    const explained = {};
+    for (const issue of report.issues) {
+        const place = placeOf(issue);
+        const tag = issue.tier ? `  [${TIER_TAG[issue.tier]}]` : '';
+        lines.push(`${issue.severity === 'error' ? 'error' : 'warn '}  ${issue.code}${place ? `  ${place}` : ''}${issue.at ? `  (${issue.at})` : ''}${issue.heuristic ? '  [heuristic]' : ''}${tag}`);
+        lines.push(`       ${issue.message}`);
+        if (issue.evidence)
+            lines.push(`       found: ${issue.evidence}`);
+        const rule = issue.tier && security ? security.rules[issue.code] : undefined;
+        if (rule && explained[issue.code] !== true) {
+            explained[issue.code] = true;
+            lines.push(`       why it matters: ${rule.why}`);
+        }
+        if (issue.fix)
+            lines.push(`       fix: ${issue.fix}`);
+    }
+    if (security) {
+        lines.push('', security.limitations.headline);
+        for (const point of security.limitations.points)
+            lines.push(`  - ${point}`);
+    }
+    lines.push('', report.heuristic);
+    return lines;
+}

package/dist/lib/appsFs.d.ts

@@ -0,0 +1,58 @@
+import type { AppDraftFile, AppPathProblem } from '@skrr-ai/data-provider';
+/** Why a read or a write of a package was refused. */
+export type AppsFsErrorCode = 'symlink' | 'not_regular' | 'too_large' | 'too_many' | 'not_text' | 'bad_path' | 'outside_root' | 'exists' | 'not_directory' | 'unreadable';
+export declare class AppsFsError extends Error {
+    readonly code: AppsFsErrorCode;
+    /** The path (relative to the package, or as typed) the refusal is about. */
+    readonly at: string;
+    constructor(code: AppsFsErrorCode, at: string, message: string);
+}
+/** UTF-8 is at most four bytes a character: the largest file a text of the limit's length can be. */
+export declare const APPS_FS_FILE_MAX_BYTES: number;
+export interface LocalPackage {
+    /** The root, resolved once. */
+    root: string;
+    files: AppDraftFile[];
+    /** What was left out on purpose: a name that starts with ".", `node_modules`. Never a link, never a file. */
+    skipped: string[];
+}
+/** A seam for the spec only: runs between the look (`lstat`) and the open, where a race would land. */
+export interface ReadHooks {
+    betweenLookAndOpen?: () => void;
+}
+/**
+ * Read ONE file the way the rules above say, from a name the caller already trusts to be a candidate.
+ * Returns its text. `label` is what the file is called in a message.
+ */
+export declare function readRegularTextFile(absolute: string, label: string, hooks?: ReadHooks): string;
+/**
+ * Read a package directory: every regular file under `root`, as text, with its package path.
+ *
+ * Throws `AppsFsError` for what must not be followed or cannot be stored (a link, a pipe, a file that is
+ * too large or not text, a name the contract refuses, too many files). The caller still judges the whole
+ * set (`appDraftProblems`), which is where case collisions and totals are.
+ */
+export declare function readPackageDir(rootInput: string): LocalPackage;
+export interface WriteResult {
+    root: string;
+    written: string[];
+}
+/** The problems of a set of paths a server sent, judged as strangers' input. */
+export declare function remoteTreeProblems(files: readonly AppDraftFile[]): AppPathProblem[];
+/**
+ * Write files into `rootInput`. All of them are judged first and nothing is written unless all are
+ * acceptable; an existing file is replaced only with `force`, and a link is never written through or
+ * replaced.
+ */
+export declare function writePackageDir(rootInput: string, files: readonly AppDraftFile[], { force }?: {
+    force?: boolean;
+}): WriteResult;
+/**
+ * Text from stdin, bounded: a pipe that never ends is read until the limit and then refused, not until
+ * the memory is gone. Strict UTF-8, kept byte for byte.
+ */
+export declare function readStdinText(stream?: NodeJS.ReadableStream): Promise<string>;
+export declare const APPS_FS_FLAGS: {
+    readonly O_NOFOLLOW: number;
+    readonly O_DIRECTORY: number;
+};

package/dist/lib/appsFs.js

@@ -0,0 +1,384 @@
+"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.APPS_FS_FLAGS = exports.APPS_FS_FILE_MAX_BYTES = exports.AppsFsError = void 0;
+exports.readRegularTextFile = readRegularTextFile;
+exports.readPackageDir = readPackageDir;
+exports.remoteTreeProblems = remoteTreeProblems;
+exports.writePackageDir = writePackageDir;
+exports.readStdinText = readStdinText;
+/**
+ * `skrr apps`: reading an app's package off a disk, and writing one onto it, without being led out of it.
+ *
+ * WHY THIS IS ITS OWN FILE. A package directory is the one place in the authoring loop where a NAME is
+ * not a string but a thing on a disk, and a name on a disk can be something else: a symbolic link to
+ * `~/.skrr/credentials`, a link to a directory outside the package, a device or a pipe that never ends.
+ * The platform's design (unified design 7.2, after the worst incident Anthropic described around its
+ * own sandbox) is one rule: RESOLVE BEFORE YOU CHECK. A path string that passes `isSafeAppPath` says
+ * nothing about what the disk will do when it is opened. Reading `./app/index.html` that is a link to
+ * the user's credentials would upload them into an app draft an agent can read; writing a pulled file
+ * into a directory that is a link to `~/.ssh` would plant a key. Both are done with a perfectly
+ * well-formed path.
+ *
+ * The rules, each of which has a test that plants the thing and a naive implementation that follows it:
+ *
+ *  - Nothing is FOLLOWED. A link anywhere in the tree is refused, naming it and where it points, rather
+ *    than skipped (a silent skip drops a file its author thinks is included) or followed (the exploit).
+ *    The root the person typed is resolved once, and everything is checked against THAT.
+ *  - A file is opened with `O_NOFOLLOW` and then looked at through the descriptor, not the name
+ *    (`fstat`): the thing opened must be a regular file, the one `lstat` saw, and no larger than the
+ *    limit, so a name swapped for a link between the look and the open is an error, not a read.
+ *  - Only regular files and directories exist. A pipe, a socket or a device is refused (reading one can
+ *    hang forever or return forever).
+ *  - Sizes are checked from the metadata BEFORE a byte is read, then again on what was read.
+ *  - Bytes are decoded as strict UTF-8 and kept exactly (`ignoreBOM`), because a version's hash is over
+ *    the bytes. A file that is not text is refused here: the working tree holds text (images are a
+ *    later step, and a lossy decode would store something other than what the person has).
+ *  - What the SERVER sends back (a pull) is as untrusted as a cloned repository: every path is judged
+ *    by the contract's grammar again, the whole set is judged for collisions, and nothing is written
+ *    until all of it is acceptable. Directories are made one component at a time, each looked at with
+ *    `lstat`; a file is created with `O_EXCL | O_NOFOLLOW`; an existing file is replaced only with
+ *    `force`, by unlinking it (never by writing through it), and a link is never replaced at all.
+ *
+ * WHAT IT CANNOT DO. It cannot stop a process that is already running as the same person from swapping a
+ * directory for a link during the few microseconds between two calls: that process can do anything the
+ * person can. The threat is CONTENT (a cloned repository, a downloaded app, a server's answer), not a
+ * concurrent attacker on one's own machine. On Windows `O_NOFOLLOW` does not exist, and the `lstat` checks
+ * are what is left.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const data_provider_1 = require("@skrr-ai/data-provider");
+class AppsFsError extends Error {
+    code;
+    /** The path (relative to the package, or as typed) the refusal is about. */
+    at;
+    constructor(code, at, message) {
+        super(message);
+        this.name = 'AppsFsError';
+        this.code = code;
+        this.at = at;
+    }
+}
+exports.AppsFsError = AppsFsError;
+/** UTF-8 is at most four bytes a character: the largest file a text of the limit's length can be. */
+exports.APPS_FS_FILE_MAX_BYTES = data_provider_1.APP_DRAFT_LIMITS.fileMaxChars * 4;
+const O_NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;
+const O_DIRECTORY = fs.constants.O_DIRECTORY ?? 0;
+/** Directories that are never part of a package and are walked past, not into. */
+const SKIPPED_DIRECTORIES = new Set(['node_modules']);
+function describeLink(absolute) {
+    try {
+        return ` (it points at ${fs.readlinkSync(absolute)})`;
+    }
+    catch {
+        return '';
+    }
+}
+function lstatOrNull(target) {
+    try {
+        return fs.lstatSync(target);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        throw new AppsFsError('unreadable', target, `Could not look at ${target}: ${errorText(error)}`);
+    }
+}
+function errorText(error) {
+    return error?.message
+        ? String(error.message)
+        : String(error);
+}
+/**
+ * Read ONE file the way the rules above say, from a name the caller already trusts to be a candidate.
+ * Returns its text. `label` is what the file is called in a message.
+ */
+function readRegularTextFile(absolute, label, hooks = {}) {
+    const before = lstatOrNull(absolute);
+    if (!before) {
+        throw new AppsFsError('unreadable', label, `${label} does not exist.`);
+    }
+    if (before.isSymbolicLink()) {
+        throw new AppsFsError('symlink', label, `${label} is a symbolic link${describeLink(absolute)}: a package holds its own files, never a link to one elsewhere. Copy the file in.`);
+    }
+    if (!before.isFile()) {
+        throw new AppsFsError('not_regular', label, `${label} is not a regular file.`);
+    }
+    if (before.size > exports.APPS_FS_FILE_MAX_BYTES) {
+        throw new AppsFsError('too_large', label, `${label} is ${before.size} bytes; a text file of at most ${data_provider_1.APP_DRAFT_LIMITS.fileMaxChars} characters is at most ${exports.APPS_FS_FILE_MAX_BYTES}.`);
+    }
+    hooks.betweenLookAndOpen?.();
+    let fd;
+    try {
+        // O_NOFOLLOW: if the name became a link after the look above, this fails (ELOOP) instead of following it.
+        fd = fs.openSync(absolute, fs.constants.O_RDONLY | O_NOFOLLOW);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ELOOP' || code === 'EMLINK') {
+            throw new AppsFsError('symlink', label, `${label} changed into a symbolic link while it was being read.`);
+        }
+        throw new AppsFsError('unreadable', label, `Could not open ${label}: ${errorText(error)}`);
+    }
+    try {
+        const opened = fs.fstatSync(fd);
+        if (!opened.isFile()) {
+            throw new AppsFsError('not_regular', label, `${label} is not a regular file.`);
+        }
+        // Where there are inode numbers, the thing opened is the thing that was looked at.
+        if (before.ino !== 0 &&
+            opened.ino !== 0 &&
+            (opened.ino !== before.ino || opened.dev !== before.dev)) {
+            throw new AppsFsError('symlink', label, `${label} was replaced while it was being read.`);
+        }
+        if (opened.size > exports.APPS_FS_FILE_MAX_BYTES) {
+            throw new AppsFsError('too_large', label, `${label} is larger than a package file may be.`);
+        }
+        const buffer = Buffer.alloc(opened.size);
+        let read = 0;
+        while (read < buffer.length) {
+            const n = fs.readSync(fd, buffer, read, buffer.length - read, read);
+            if (n === 0)
+                break;
+            read += n;
+        }
+        try {
+            // `ignoreBOM: true` keeps a leading BOM as a character, so the text encodes back to the same bytes.
+            return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(buffer.subarray(0, read));
+        }
+        catch {
+            throw new AppsFsError('not_text', label, `${label} is not UTF-8 text: a draft holds text files, and this one would be stored as something other than what is on disk.`);
+        }
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * Read a package directory: every regular file under `root`, as text, with its package path.
+ *
+ * Throws `AppsFsError` for what must not be followed or cannot be stored (a link, a pipe, a file that is
+ * too large or not text, a name the contract refuses, too many files). The caller still judges the whole
+ * set (`appDraftProblems`), which is where case collisions and totals are.
+ */
+function readPackageDir(rootInput) {
+    const typed = path.resolve(rootInput);
+    const rootStat = lstatOrNull(typed);
+    if (!rootStat) {
+        throw new AppsFsError('unreadable', rootInput, `${rootInput} does not exist.`);
+    }
+    // The ONE place a link is resolved: the directory the person named. Everything is checked against what
+    // it resolves to, so `~/work -> /Volumes/x/work` is fine and a link INSIDE it is not.
+    let root;
+    try {
+        root = fs.realpathSync(typed);
+    }
+    catch (error) {
+        throw new AppsFsError('unreadable', rootInput, `Could not resolve ${rootInput}: ${errorText(error)}`);
+    }
+    if (!fs.statSync(root).isDirectory()) {
+        throw new AppsFsError('not_directory', rootInput, `${rootInput} is not a directory.`);
+    }
+    const files = [];
+    const skipped = [];
+    const walk = (relative, depth) => {
+        const absolute = relative === '' ? root : path.join(root, ...relative.split('/'));
+        if (depth > data_provider_1.APP_PATH_LIMITS.pathMaxSegments) {
+            throw new AppsFsError('bad_path', relative, `${relative} is more than ${data_provider_1.APP_PATH_LIMITS.pathMaxSegments} directories deep.`);
+        }
+        let names;
+        try {
+            names = fs.readdirSync(absolute).sort();
+        }
+        catch (error) {
+            throw new AppsFsError('unreadable', relative || '.', `Could not list ${relative || '.'}: ${errorText(error)}`);
+        }
+        for (const name of names) {
+            const childRelative = relative === '' ? name : `${relative}/${name}`;
+            if (name.startsWith('.') || SKIPPED_DIRECTORIES.has(name)) {
+                skipped.push(childRelative);
+                continue;
+            }
+            const childAbsolute = path.join(absolute, name);
+            const stat = lstatOrNull(childAbsolute);
+            if (!stat) {
+                continue; // gone since it was listed
+            }
+            if (stat.isSymbolicLink()) {
+                throw new AppsFsError('symlink', childRelative, `${childRelative} is a symbolic link${describeLink(childAbsolute)}: a package holds its own files, never a link to one elsewhere. Copy the file in, or remove the link.`);
+            }
+            if (stat.isDirectory()) {
+                walk(childRelative, depth + 1);
+                continue;
+            }
+            if (!stat.isFile()) {
+                throw new AppsFsError('not_regular', childRelative, `${childRelative} is not a regular file (a pipe, a socket or a device).`);
+            }
+            const bad = (0, data_provider_1.appPathProblem)(childRelative);
+            if (bad) {
+                throw new AppsFsError('bad_path', childRelative, bad.message);
+            }
+            if (files.length >= data_provider_1.APP_DRAFT_LIMITS.filesMax) {
+                throw new AppsFsError('too_many', childRelative, `A package holds at most ${data_provider_1.APP_DRAFT_LIMITS.filesMax} files; this directory has more. Leave out what is not part of the app.`);
+            }
+            const content = readRegularTextFile(childAbsolute, childRelative);
+            // After the read: the real location of what was read is inside the root.
+            const real = fs.realpathSync(childAbsolute);
+            if (real !== path.join(root, ...childRelative.split('/'))) {
+                throw new AppsFsError('outside_root', childRelative, `${childRelative} is not where it appears to be (${real}).`);
+            }
+            files.push({ path: childRelative, content });
+        }
+    };
+    walk('', 1);
+    return { root, files, skipped };
+}
+/** The problems of a set of paths a server sent, judged as strangers' input. */
+function remoteTreeProblems(files) {
+    return (0, data_provider_1.appDraftProblems)(files);
+}
+/**
+ * Write files into `rootInput`. All of them are judged first and nothing is written unless all are
+ * acceptable; an existing file is replaced only with `force`, and a link is never written through or
+ * replaced.
+ */
+function writePackageDir(rootInput, files, { force = false } = {}) {
+    const problems = remoteTreeProblems(files);
+    if (problems.length > 0) {
+        throw new AppsFsError('bad_path', problems[0].path, `Refusing to write: ${problems[0].message}`);
+    }
+    for (const file of files) {
+        if (typeof file.content !== 'string') {
+            throw new AppsFsError('not_text', file.path, `${file.path} is not a text file; this command writes text files only.`);
+        }
+    }
+    const typed = path.resolve(rootInput);
+    const existing = lstatOrNull(typed);
+    if (existing && !existing.isDirectory() && !existing.isSymbolicLink()) {
+        throw new AppsFsError('not_directory', rootInput, `${rootInput} exists and is not a directory.`);
+    }
+    if (!existing) {
+        fs.mkdirSync(typed, { recursive: true, mode: 0o755 });
+    }
+    const root = fs.realpathSync(typed);
+    if (!fs.statSync(root).isDirectory()) {
+        throw new AppsFsError('not_directory', rootInput, `${rootInput} is not a directory.`);
+    }
+    const written = [];
+    for (const file of files) {
+        const segments = file.path.split('/');
+        // The directories, one component at a time, each looked at before it is trusted.
+        let current = root;
+        for (let i = 0; i < segments.length - 1; i += 1) {
+            current = path.join(current, segments[i]);
+            const stat = lstatOrNull(current);
+            if (!stat) {
+                fs.mkdirSync(current, { mode: 0o755 });
+            }
+            else if (stat.isSymbolicLink()) {
+                throw new AppsFsError('symlink', segments.slice(0, i + 1).join('/'), `${segments.slice(0, i + 1).join('/')} is a symbolic link${describeLink(current)}: nothing is written through a link.`);
+            }
+            else if (!stat.isDirectory()) {
+                throw new AppsFsError('not_directory', segments.slice(0, i + 1).join('/'), `${segments.slice(0, i + 1).join('/')} exists and is not a directory.`);
+            }
+            // the directory is now a real directory, and it is inside the root
+            if (fs.realpathSync(current) !== current) {
+                throw new AppsFsError('outside_root', segments.slice(0, i + 1).join('/'), `${segments.slice(0, i + 1).join('/')} does not resolve to itself.`);
+            }
+        }
+        const target = path.join(current, segments[segments.length - 1]);
+        const there = lstatOrNull(target);
+        if (there) {
+            if (there.isSymbolicLink()) {
+                throw new AppsFsError('symlink', file.path, `${file.path} is a symbolic link${describeLink(target)}: it is never replaced or written through.`);
+            }
+            if (!there.isFile()) {
+                throw new AppsFsError('not_regular', file.path, `${file.path} exists and is not a regular file.`);
+            }
+            if (!force) {
+                throw new AppsFsError('exists', file.path, `${file.path} already exists. Use --force to replace it.`);
+            }
+            fs.unlinkSync(target);
+        }
+        let fd;
+        try {
+            fd = fs.openSync(target, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | O_NOFOLLOW, 0o644);
+        }
+        catch (error) {
+            throw new AppsFsError('unreadable', file.path, `Could not create ${file.path}: ${errorText(error)}`);
+        }
+        try {
+            const bytes = Buffer.from(file.content, 'utf8');
+            let offset = 0;
+            while (offset < bytes.length) {
+                offset += fs.writeSync(fd, bytes, offset);
+            }
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        if (fs.realpathSync(target) !== target) {
+            throw new AppsFsError('outside_root', file.path, `${file.path} does not resolve to itself.`);
+        }
+        written.push(file.path);
+    }
+    return { root, written };
+}
+/**
+ * Text from stdin, bounded: a pipe that never ends is read until the limit and then refused, not until
+ * the memory is gone. Strict UTF-8, kept byte for byte.
+ */
+async function readStdinText(stream = process.stdin) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of stream) {
+        const buffer = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk;
+        total += buffer.length;
+        if (total > exports.APPS_FS_FILE_MAX_BYTES) {
+            throw new AppsFsError('too_large', 'stdin', `stdin holds more than a package file may (${exports.APPS_FS_FILE_MAX_BYTES} bytes).`);
+        }
+        chunks.push(buffer);
+    }
+    try {
+        return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(Buffer.concat(chunks));
+    }
+    catch {
+        throw new AppsFsError('not_text', 'stdin', 'stdin is not UTF-8 text.');
+    }
+}
+// kept for the spec: the flags a disk-touching call is made with
+exports.APPS_FS_FLAGS = { O_NOFOLLOW, O_DIRECTORY };

package/dist/lib/auth-failure.d.ts

@@ -11,17 +11,37 @@
  * same record `skrr whoami` prints as "Refresh state"). This module reads that
  * latch and turns it into the sentence the error should have carried.
  */
+import type { SessionRevocationReason } from '@skrr-ai/data-provider';
 export interface RefreshRefusal {
     /** Permanent reason code the refresh latched (`REFRESH_INVALID`, `SESSION_REVOKED`, …). */
     reason?: string;
     /** The server's own message for the refusal, when auth-core recorded one. */
     message?: string;
+    /**
+     * OSK-16941 — for `SESSION_REVOKED`, why the server revoked the session
+     * (`@skrr-ai/data-provider` `SESSION_REVOCATION_REASONS`). Absent on a latch
+     * written by an older auth-core, which then reads as unknown.
+     */
+    revocationReason?: string;
 }
 export interface DescribedAuthFailure {
     message: string;
     /** The code a script should key on: the refresh refusal when known. */
     code: string;
+    /** OSK-16941 — the vocabulary reason a revoked session was revoked for. */
+    revocationReason?: SessionRevocationReason;
 }
+/**
+ * OSK-16941 — the refusal an API 401 body describes, when it is a revoked
+ * session (`{ code: 'SESSION_REVOKED', reason }`). Lets the 401 explain itself
+ * when no refresh refusal was latched, and fills the reason in when the latch
+ * predates it.
+ */
+export declare function refusalFromResponse(body: {
+    code?: unknown;
+    reason?: unknown;
+    message?: unknown;
+} | null | undefined, latched: RefreshRefusal | null | undefined): RefreshRefusal | null;
 /**
  * Explain one refresh refusal in terms of what the reader can do about it.
  * Returns null when there is no latched refusal, so the caller keeps its