@skrr-ai/cli 0.1.86 → 0.1.88

package/dist/commands/machines/dedicated/ls.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const dedicated_lease_command_1 = require("../../../lib/dedicated-lease-command");
+const format_1 = require("../../../lib/format");
+const computer_files_1 = require("../../../lib/computer-files");
+/**
+ * `skrr machines dedicated ls` — list one directory on the machine.
+ *
+ * Paths are relative to /workspace and, on a guest, confined to `repos/` and
+ * `user-data/` — the tenant roots; the workspace root itself is the runtime's
+ * and a listing of it is refused `path_withheld`. Entries are sorted by the
+ * machine by name bytes; a symlink shows its stored target and is never
+ * followed; an entry the machine withholds (deny set, blockedPaths, a
+ * sensitive pattern, an OS permission) is shown as withheld, not hidden.
+ */
+class DedicatedMachinesLs extends dedicated_lease_command_1.DedicatedLeaseCommand {
+    static summary = 'List a directory on a Dedicated Runtime machine';
+    static description = 'Lists one directory on the machine, one page of up to 500 entries. ' +
+        'Paths are relative to /workspace and must be inside repos/ or user-data/. ' +
+        'A path the machine withholds is answered as a refusal, and an entry it ' +
+        'withholds is shown marked rather than hidden.';
+    static examples = [
+        '<%= config.bin %> machines dedicated ls rtl_abc123 repos/app',
+        '<%= config.bin %> machines dedicated ls rtl_abc123 repos/app --limit 1000 --all',
+        '<%= config.bin %> machines dedicated ls rtl_abc123 repos/app --json',
+    ];
+    static args = {
+        lease: core_1.Args.string({
+            description: dedicated_lease_command_1.DEDICATED_LEASE_ARG_DESCRIPTION,
+            required: true,
+            ignoreStdin: true,
+        }),
+        path: core_1.Args.string({
+            description: 'Directory on the machine, relative to /workspace (inside repos/ or user-data/)',
+            required: true,
+            ignoreStdin: true,
+        }),
+    };
+    static flags = {
+        limit: core_1.Flags.integer({ description: 'Entries per page (at most 2000)' }),
+        cursor: core_1.Flags.string({ description: 'Continue the listing from a nextCursor' }),
+        all: core_1.Flags.boolean({ description: 'Follow the cursor until the directory is listed whole' }),
+        json: core_1.Flags.boolean({ description: 'Output the result as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(DedicatedMachinesLs);
+        const leaseId = await this.resolveLeaseArg(args.lease);
+        const scope = this.scopeFrom(flags);
+        const entries = [];
+        let listedPath = args.path;
+        let nextCursor;
+        try {
+            // Once: every page of this listing is read from the same machine.
+            const generation = await (0, computer_files_1.resolveDedicatedFileGeneration)(leaseId, scope);
+            let cursor = flags.cursor;
+            do {
+                const page = await (0, computer_files_1.listComputerFiles)(leaseId, {
+                    path: args.path,
+                    generation,
+                    ...(cursor ? { cursor } : {}),
+                    ...(flags.limit !== undefined ? { limit: flags.limit } : {}),
+                }, scope);
+                listedPath = page.path;
+                entries.push(...page.entries);
+                cursor = page.nextCursor;
+                nextCursor = page.nextCursor;
+            } while (flags.all && cursor);
+        }
+        catch (err) {
+            const failure = (0, computer_files_1.describeComputerFileFailure)(err, { bin: this.config.bin, leaseId });
+            if (failure)
+                this.failWithCliError({ ...failure, exit: 1 });
+            this.handleApiError(err);
+        }
+        if (flags.json) {
+            this.log(JSON.stringify({ path: listedPath, entries, ...(nextCursor ? { nextCursor } : {}) }, null, 2));
+            return;
+        }
+        this.log(`${listedPath} — ${entries.length} entr${entries.length === 1 ? 'y' : 'ies'}`);
+        (0, format_1.renderTable)(entries.map((entry) => ({
+            type: (0, format_1.formatCell)(entry.withheld ? 'withheld' : entry.type),
+            mode: (0, format_1.formatCell)(entry.withheld ? '-' : (0, computer_files_1.computerFileModeString)(entry.type, entry.mode)),
+            size: (0, format_1.formatCell)(entry.withheld ? '-' : (0, computer_files_1.formatComputerFileSize)(entry.size)),
+            modified: (0, format_1.formatCell)(entry.withheld ? '-' : (0, format_1.localStamp)(entry.mtimeMs)),
+            name: (0, format_1.formatCell)((0, computer_files_1.computerFileEntryName)(entry)),
+        })), [
+            { key: 'type', header: 'TYPE' },
+            { key: 'mode', header: 'MODE' },
+            { key: 'size', header: 'SIZE' },
+            { key: 'modified', header: 'MODIFIED' },
+            { key: 'name', header: 'NAME', verbatim: true },
+        ], (line) => this.log(line));
+        if (nextCursor) {
+            this.log(`More entries: --cursor ${nextCursor} (or --all to list the whole directory).`);
+        }
+    }
+}
+exports.default = DedicatedMachinesLs;

package/dist/commands/machines/dedicated/mkdir.d.ts

@@ -0,0 +1,18 @@
+import { DedicatedLeaseCommand } from '../../../lib/dedicated-lease-command';
+/**
+ * `skrr machines dedicated mkdir` — create a directory on the machine, missing
+ * parents included (`mkdir -p` semantics; the machine makes the chain).
+ */
+export default class DedicatedMachinesMkdir extends DedicatedLeaseCommand {
+    static summary: string;
+    static description: string;
+    static examples: string[];
+    static args: {
+        lease: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+        path: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/machines/dedicated/mkdir.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const dedicated_lease_command_1 = require("../../../lib/dedicated-lease-command");
+const computer_files_1 = require("../../../lib/computer-files");
+/**
+ * `skrr machines dedicated mkdir` — create a directory on the machine, missing
+ * parents included (`mkdir -p` semantics; the machine makes the chain).
+ */
+class DedicatedMachinesMkdir extends dedicated_lease_command_1.DedicatedLeaseCommand {
+    static summary = 'Create a directory on a Dedicated Runtime machine';
+    static description = 'Creates the directory and any missing parents, as the workload user, inside ' +
+        'repos/ or user-data/. The tenant roots themselves and a path that already ' +
+        'exists are refused.';
+    static examples = [
+        '<%= config.bin %> machines dedicated mkdir rtl_abc123 repos/app/dist',
+        '<%= config.bin %> machines dedicated mkdir rtl_abc123 user-data/notes --json',
+    ];
+    static args = {
+        lease: core_1.Args.string({
+            description: dedicated_lease_command_1.DEDICATED_LEASE_ARG_DESCRIPTION,
+            required: true,
+            ignoreStdin: true,
+        }),
+        path: core_1.Args.string({
+            description: 'Directory to create, relative to /workspace (inside repos/ or user-data/)',
+            required: true,
+            ignoreStdin: true,
+        }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output the result as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(DedicatedMachinesMkdir);
+        const leaseId = await this.resolveLeaseArg(args.lease);
+        let result;
+        try {
+            const scope = this.scopeFrom(flags);
+            const generation = await (0, computer_files_1.resolveDedicatedFileGeneration)(leaseId, scope);
+            result = await (0, computer_files_1.mkdirComputerFile)(leaseId, { path: args.path, generation }, scope);
+        }
+        catch (err) {
+            const failure = (0, computer_files_1.describeComputerFileFailure)(err, { bin: this.config.bin, leaseId });
+            if (failure)
+                this.failWithCliError({ ...failure, exit: 1 });
+            this.handleApiError(err);
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        this.log(`Created ${result.path}`);
+    }
+}
+exports.default = DedicatedMachinesMkdir;

package/dist/commands/machines/dedicated/mv.d.ts

@@ -0,0 +1,24 @@
+import { DedicatedLeaseCommand } from '../../../lib/dedicated-lease-command';
+/**
+ * `skrr machines dedicated mv` — rename or move one path on the machine.
+ *
+ * `--tag` is the optimistic-concurrency fence (design §6.3): the tag `stat`
+ * prints for the source. When the source changed since that read the move is
+ * refused `file_changed` and the refusal carries the current tag — it is never
+ * silently applied over the version you did not see.
+ */
+export default class DedicatedMachinesMv extends DedicatedLeaseCommand {
+    static summary: string;
+    static description: string;
+    static examples: string[];
+    static args: {
+        lease: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+        from: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+        to: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        tag: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/machines/dedicated/mv.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const dedicated_lease_command_1 = require("../../../lib/dedicated-lease-command");
+const computer_files_1 = require("../../../lib/computer-files");
+/**
+ * `skrr machines dedicated mv` — rename or move one path on the machine.
+ *
+ * `--tag` is the optimistic-concurrency fence (design §6.3): the tag `stat`
+ * prints for the source. When the source changed since that read the move is
+ * refused `file_changed` and the refusal carries the current tag — it is never
+ * silently applied over the version you did not see.
+ */
+class DedicatedMachinesMv extends dedicated_lease_command_1.DedicatedLeaseCommand {
+    static summary = 'Rename or move a path on a Dedicated Runtime machine';
+    static description = 'Moves or renames one path inside repos/ or user-data/. --tag takes the tag ' +
+        '`stat` prints for the source and refuses the move if the path changed ' +
+        'since; without it the move is unconditional.';
+    static examples = [
+        '<%= config.bin %> machines dedicated mv rtl_abc123 repos/app/old repos/app/new',
+        '<%= config.bin %> machines dedicated mv rtl_abc123 user-data/draft.md user-data/sent/draft.md',
+        '<%= config.bin %> machines dedicated mv rtl_abc123 repos/a repos/b --tag 12345:3182:1761234567890000000',
+    ];
+    static args = {
+        lease: core_1.Args.string({
+            description: dedicated_lease_command_1.DEDICATED_LEASE_ARG_DESCRIPTION,
+            required: true,
+            ignoreStdin: true,
+        }),
+        from: core_1.Args.string({
+            description: 'Existing path on the machine, relative to /workspace',
+            required: true,
+            ignoreStdin: true,
+        }),
+        to: core_1.Args.string({
+            description: 'Where it goes, relative to /workspace',
+            required: true,
+            ignoreStdin: true,
+        }),
+    };
+    static flags = {
+        tag: core_1.Flags.string({
+            description: 'Refuse unless the source still has this tag — the <inode>:<size>:<mtimeNs> `stat` prints',
+        }),
+        json: core_1.Flags.boolean({ description: 'Output the result as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(DedicatedMachinesMv);
+        const leaseId = await this.resolveLeaseArg(args.lease);
+        let tag;
+        if (flags.tag !== undefined) {
+            try {
+                tag = (0, computer_files_1.parseComputerFileTag)(flags.tag);
+            }
+            catch (err) {
+                this.error(err.message, { exit: 2 });
+            }
+        }
+        let result;
+        try {
+            const scope = this.scopeFrom(flags);
+            const generation = await (0, computer_files_1.resolveDedicatedFileGeneration)(leaseId, scope);
+            result = await (0, computer_files_1.moveComputerFile)(leaseId, { from: args.from, to: args.to, generation, ...(tag ? { tag } : {}) }, scope);
+        }
+        catch (err) {
+            const failure = (0, computer_files_1.describeComputerFileFailure)(err, {
+                bin: this.config.bin,
+                leaseId,
+                takesTag: true,
+            });
+            if (failure)
+                this.failWithCliError({ ...failure, exit: 1 });
+            this.handleApiError(err);
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        this.log(`Moved ${args.from} → ${result.path}`);
+    }
+}
+exports.default = DedicatedMachinesMv;

package/dist/commands/machines/dedicated/rm.d.ts

@@ -0,0 +1,26 @@
+import { DedicatedLeaseCommand } from '../../../lib/dedicated-lease-command';
+/**
+ * `skrr machines dedicated rm` — delete one path on the machine.
+ *
+ * As `rm` does: a directory needs --recursive and is refused `not_empty`
+ * without it. `--tag` is the optimistic-concurrency fence — the tag `stat`
+ * prints; a file that changed since that read is refused `file_changed`, so a
+ * scripted delete never removes a version it never saw. For `--recursive` the
+ * tag must be the folder's CONTENTS tag (`stat --contents`): anything changed
+ * inside the folder since is refused. `--recursive` without `--tag` is unfenced.
+ */
+export default class DedicatedMachinesRm extends DedicatedLeaseCommand {
+    static summary: string;
+    static description: string;
+    static examples: string[];
+    static args: {
+        lease: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+        path: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        recursive: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        tag: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/machines/dedicated/rm.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const dedicated_lease_command_1 = require("../../../lib/dedicated-lease-command");
+const computer_files_1 = require("../../../lib/computer-files");
+/**
+ * `skrr machines dedicated rm` — delete one path on the machine.
+ *
+ * As `rm` does: a directory needs --recursive and is refused `not_empty`
+ * without it. `--tag` is the optimistic-concurrency fence — the tag `stat`
+ * prints; a file that changed since that read is refused `file_changed`, so a
+ * scripted delete never removes a version it never saw. For `--recursive` the
+ * tag must be the folder's CONTENTS tag (`stat --contents`): anything changed
+ * inside the folder since is refused. `--recursive` without `--tag` is unfenced.
+ */
+class DedicatedMachinesRm extends dedicated_lease_command_1.DedicatedLeaseCommand {
+    static summary = 'Delete a file or folder on a Dedicated Runtime machine';
+    static description = 'Deletes one path inside repos/ or user-data/, as the workload user. A ' +
+        'folder needs --recursive and is refused without it. --tag takes the tag ' +
+        '`stat` prints and refuses the delete when the path changed since. With ' +
+        "--recursive, --tag must be the folder's contents tag from `stat --contents` " +
+        '(inode:size:mtimeNs:contents), and the delete is refused if anything inside ' +
+        'the folder changed since; --recursive without --tag deletes whatever the ' +
+        'folder holds at that moment (unfenced). There is no trash: a deleted path is gone.';
+    static examples = [
+        '<%= config.bin %> machines dedicated rm rtl_abc123 user-data/notes/draft.md',
+        '<%= config.bin %> machines dedicated rm rtl_abc123 repos/app/dist --recursive',
+        '<%= config.bin %> machines dedicated rm rtl_abc123 repos/app/lock --tag 12345:3182:1761234567890000000',
+        '<%= config.bin %> machines dedicated rm rtl_abc123 repos/app/dist --recursive --tag <tag from `stat --contents`>',
+    ];
+    static args = {
+        lease: core_1.Args.string({
+            description: dedicated_lease_command_1.DEDICATED_LEASE_ARG_DESCRIPTION,
+            required: true,
+            ignoreStdin: true,
+        }),
+        path: core_1.Args.string({
+            description: 'Path to delete, relative to /workspace (inside repos/ or user-data/)',
+            required: true,
+            ignoreStdin: true,
+        }),
+    };
+    static flags = {
+        recursive: core_1.Flags.boolean({
+            char: 'r',
+            description: 'Delete a folder and everything in it',
+        }),
+        tag: core_1.Flags.string({
+            description: 'Refuse unless the path still has this tag — the <inode>:<size>:<mtimeNs> `stat` prints; with --recursive, the <inode>:<size>:<mtimeNs>:<contents> tag `stat --contents` prints',
+        }),
+        json: core_1.Flags.boolean({ description: 'Output the result as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(DedicatedMachinesRm);
+        const leaseId = await this.resolveLeaseArg(args.lease);
+        let tag;
+        if (flags.tag !== undefined) {
+            try {
+                tag = (0, computer_files_1.parseComputerFileTag)(flags.tag);
+            }
+            catch (err) {
+                this.error(err.message, { exit: 2 });
+            }
+            // Said here rather than spent on a round trip the server would refuse
+            // (`contents_tag_required`): a folder's own tag covers only its direct
+            // entries, which is not what a recursive delete erases.
+            if (flags.recursive === true && tag?.contents === undefined) {
+                this.error(`--recursive --tag needs the folder's contents tag, which covers everything inside it. Read it with \`${this.config.bin} machines dedicated stat ${leaseId} ${args.path} --contents\` and pass that tag.`, { exit: 2 });
+            }
+        }
+        let result;
+        try {
+            const scope = this.scopeFrom(flags);
+            const generation = await (0, computer_files_1.resolveDedicatedFileGeneration)(leaseId, scope);
+            result = await (0, computer_files_1.deleteComputerFile)(leaseId, {
+                path: args.path,
+                generation,
+                ...(tag ? { tag } : {}),
+                recursive: flags.recursive === true,
+            }, scope);
+        }
+        catch (err) {
+            const failure = (0, computer_files_1.describeComputerFileFailure)(err, {
+                bin: this.config.bin,
+                leaseId,
+                takesTag: true,
+            });
+            if (failure)
+                this.failWithCliError({ ...failure, exit: 1 });
+            this.handleApiError(err);
+        }
+        if (flags.json) {
+            this.log(JSON.stringify({ ...result, deleted: true }, null, 2));
+            return;
+        }
+        this.log(`Deleted ${result.path}`);
+    }
+}
+exports.default = DedicatedMachinesRm;

package/dist/commands/machines/dedicated/search.d.ts

@@ -0,0 +1,24 @@
+import { DedicatedLeaseCommand } from '../../../lib/dedicated-lease-command';
+/**
+ * `skrr machines dedicated search` — find files by name, or text inside them,
+ * under one folder. Guest-only today; the answer states whether it is whole.
+ */
+export default class DedicatedMachinesSearch extends DedicatedLeaseCommand {
+    static summary: string;
+    static description: string;
+    static examples: string[];
+    static args: {
+        lease: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+        path: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        query: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        content: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        'no-ignore': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        'case-sensitive': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        limit: import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'budget-ms': import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/machines/dedicated/search.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const dedicated_lease_command_1 = require("../../../lib/dedicated-lease-command");
+const computer_files_1 = require("../../../lib/computer-files");
+/**
+ * `skrr machines dedicated search` — find files by name, or text inside them,
+ * under one folder. Guest-only today; the answer states whether it is whole.
+ */
+class DedicatedMachinesSearch extends dedicated_lease_command_1.DedicatedLeaseCommand {
+    static summary = 'Search a folder on a Dedicated Runtime machine';
+    static description = 'Finds files by name, or with --content lines containing the text, under one folder. ' +
+        '.gitignore is honoured unless --no-ignore. The search is bounded: it stops at the result ' +
+        'limit or at a time bound, and says which — a truncated or "still searching" answer is ' +
+        'never printed as complete. Available on dedicated machines, not on a personal machine.';
+    static examples = [
+        '<%= config.bin %> machines dedicated search rtl_abc123 repos/app --query package.json',
+        '<%= config.bin %> machines dedicated search rtl_abc123 repos/app --query TODO --content --limit 50',
+        '<%= config.bin %> machines dedicated search rtl_abc123 repos/app --query dist --no-ignore --json',
+    ];
+    static args = {
+        lease: core_1.Args.string({
+            description: dedicated_lease_command_1.DEDICATED_LEASE_ARG_DESCRIPTION,
+            required: true,
+            ignoreStdin: true,
+        }),
+        path: core_1.Args.string({
+            description: 'Folder to search under, relative to /workspace (inside repos/ or user-data/)',
+            required: true,
+            ignoreStdin: true,
+        }),
+    };
+    static flags = {
+        query: core_1.Flags.string({
+            description: 'Text to look for (one line, at most 200 characters)',
+            required: true,
+        }),
+        content: core_1.Flags.boolean({ description: 'Search inside files instead of file names' }),
+        'no-ignore': core_1.Flags.boolean({ description: 'Also search what .gitignore excludes' }),
+        'case-sensitive': core_1.Flags.boolean({ description: 'Match case exactly' }),
+        limit: core_1.Flags.integer({ description: 'Most results to return (at most 1000)' }),
+        'budget-ms': core_1.Flags.integer({ description: 'Time bound in milliseconds (at most 20000)' }),
+        json: core_1.Flags.boolean({ description: 'Output the result as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(DedicatedMachinesSearch);
+        const leaseId = await this.resolveLeaseArg(args.lease);
+        let result;
+        try {
+            const scope = this.scopeFrom(flags);
+            const generation = await (0, computer_files_1.resolveDedicatedFileGeneration)(leaseId, scope);
+            result = await (0, computer_files_1.searchComputerFiles)(leaseId, {
+                path: args.path,
+                generation,
+                query: flags.query,
+                content: flags.content,
+                ...(flags['no-ignore'] ? { respectIgnore: false } : {}),
+                caseSensitive: flags['case-sensitive'],
+                ...(flags.limit !== undefined ? { limit: flags.limit } : {}),
+                ...(flags['budget-ms'] !== undefined ? { budgetMs: flags['budget-ms'] } : {}),
+            }, scope);
+        }
+        catch (err) {
+            const failure = (0, computer_files_1.describeComputerFileFailure)(err, { bin: this.config.bin, leaseId });
+            if (failure)
+                this.failWithCliError({ ...failure, exit: 1 });
+            this.handleApiError(err);
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        for (const line of (0, computer_files_1.computerFileSearchLines)(result))
+            this.log(line);
+    }
+}
+exports.default = DedicatedMachinesSearch;

package/dist/commands/machines/dedicated/stat.d.ts

@@ -0,0 +1,22 @@
+import type { ComputerFileStatResult } from '@skrr-ai/data-provider';
+import { DedicatedLeaseCommand } from '../../../lib/dedicated-lease-command';
+/** The `stat` read-out, as lines. Pure so a spec can pin it. */
+export declare function computerFileStatLines(result: ComputerFileStatResult): string[];
+/**
+ * `skrr machines dedicated stat` — one path's facts, including the entity tag
+ * a `mv`/`rm`/`file_changed` retry presents.
+ */
+export default class DedicatedMachinesStat extends DedicatedLeaseCommand {
+    static summary: string;
+    static description: string;
+    static examples: string[];
+    static args: {
+        lease: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+        path: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        contents: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/machines/dedicated/stat.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computerFileStatLines = computerFileStatLines;
+const core_1 = require("@oclif/core");
+const dedicated_lease_command_1 = require("../../../lib/dedicated-lease-command");
+const computer_files_1 = require("../../../lib/computer-files");
+/** The `stat` read-out, as lines. Pure so a spec can pin it. */
+function computerFileStatLines(result) {
+    const { entry } = result;
+    const lines = [entry.path];
+    const row = (label, value) => {
+        if (value === undefined || value === null || value === '')
+            return;
+        lines.push(`  ${`${label} `.padEnd(12)}${value}`);
+    };
+    row('type', entry.type);
+    row('size', `${entry.size} bytes`);
+    row('modified', Number.isFinite(entry.mtimeMs) ? new Date(entry.mtimeMs).toISOString() : undefined);
+    row('mode', `${entry.mode.toString(8).padStart(4, '0')} (${(0, computer_files_1.computerFileModeString)(entry.type, entry.mode)})`);
+    row('link target', entry.linkTarget);
+    if (entry.withheld) {
+        row('withheld', `${entry.withheld.reason}${entry.withheld.rule ? ` (${entry.withheld.rule})` : ''}`);
+    }
+    // `--contents` on a folder: how much a fenced `rm -r --tag` would erase.
+    if (result.entries !== undefined) {
+        row('contains', `${result.entries} entr${result.entries === 1 ? 'y' : 'ies'}, at every depth`);
+    }
+    // The tag is what `--tag` on mv and rm takes back, spelled the same way — for
+    // a folder read with --contents, with its contents digest as a fourth part.
+    row('tag', result.tag ? (0, computer_files_1.computerFileTagString)(result.tag) : undefined);
+    return lines;
+}
+/**
+ * `skrr machines dedicated stat` — one path's facts, including the entity tag
+ * a `mv`/`rm`/`file_changed` retry presents.
+ */
+class DedicatedMachinesStat extends dedicated_lease_command_1.DedicatedLeaseCommand {
+    static summary = 'Show one path on a Dedicated Runtime machine, with its tag';
+    static description = 'Type, size, mtime, mode and link target of one path on the machine, plus its entity tag, ' +
+        'the optimistic-concurrency token --tag on `mv` and `rm` (and --if-tag on `cp`) accepts. ' +
+        'With --contents, a folder is also walked: its tag gains a fourth part, a digest of everything ' +
+        'inside it, and the entry count is shown — the tag `rm --recursive --tag` needs, so a fenced ' +
+        'recursive delete can only erase what you were shown. A path the machine withholds is answered ' +
+        'as a refusal.';
+    static examples = [
+        '<%= config.bin %> machines dedicated stat rtl_abc123 repos/app/package.json',
+        '<%= config.bin %> machines dedicated stat rtl_abc123 repos/app --json',
+        '<%= config.bin %> machines dedicated stat rtl_abc123 repos/app/dist --contents',
+    ];
+    static args = {
+        lease: core_1.Args.string({
+            description: dedicated_lease_command_1.DEDICATED_LEASE_ARG_DESCRIPTION,
+            required: true,
+            ignoreStdin: true,
+        }),
+        path: core_1.Args.string({
+            description: 'Path on the machine, relative to /workspace',
+            required: true,
+            ignoreStdin: true,
+        }),
+    };
+    static flags = {
+        contents: core_1.Flags.boolean({
+            description: 'For a folder: walk it and show its contents tag and entry count (for `rm --recursive --tag`)',
+        }),
+        json: core_1.Flags.boolean({ description: 'Output the result as JSON' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(DedicatedMachinesStat);
+        const leaseId = await this.resolveLeaseArg(args.lease);
+        let result;
+        try {
+            const scope = this.scopeFrom(flags);
+            const generation = await (0, computer_files_1.resolveDedicatedFileGeneration)(leaseId, scope);
+            result = await (0, computer_files_1.statComputerFile)(leaseId, { path: args.path, generation, ...(flags.contents ? { contents: true } : {}) }, scope);
+        }
+        catch (err) {
+            const failure = (0, computer_files_1.describeComputerFileFailure)(err, { bin: this.config.bin, leaseId });
+            if (failure)
+                this.failWithCliError({ ...failure, exit: 1 });
+            this.handleApiError(err);
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        for (const line of computerFileStatLines(result))
+            this.log(line);
+    }
+}
+exports.default = DedicatedMachinesStat;

package/dist/commands/machines/hosted/index.js

@@ -14,7 +14,7 @@ class Machines extends core_1.Command {
         '<%= config.bin %> machines hosted connect <machine-id>',
     ];
     async run() {
-        this.log('skrr Hosted Machine commands:');
+        this.log('Skrr Hosted Machine commands:');
         this.log('  skrr machines hosted start      start a hosted machine');
         this.log('  skrr machines hosted list       list Hosted Machine sessions');
         this.log('  skrr machines hosted status     show machine status');

package/dist/commands/machines/hosted/list.js

@@ -6,7 +6,7 @@ const api_fetch_1 = require("../../../lib/api-fetch");
 const format_1 = require("../../../lib/format");
 const hosted_machines_1 = require("../../../lib/hosted-machines");
 class HostedMachinesList extends base_command_1.BaseCommand {
-    static description = 'List skrr Hosted Machine sessions';
+    static description = 'List Skrr Hosted Machine sessions';
     static examples = [
         '<%= config.bin %> machines hosted list',
         '<%= config.bin %> machines hosted list --workspace <workspace-id>',