@substrio/cli 0.0.0-stage → 0.1.0

package/src/commands/dev.mjs

@@ -0,0 +1,246 @@
+/**
+ * Substrio CLI: `substrio dev`, the app on a local server with hot reload.
+ *
+ *   substrio dev [--attach URL] [--server PATH] [--port N] [--data DIR]
+ *            [--debounce MS] [--no-build] [--no-logs] [--prune]
+ *
+ * Starts a substrio_server of its own on an OS-picked port, with its data in
+ * .substrio/dev of the project (or in --data DIR; either is made, owner-only, with
+ * its master.key and tenant.key, when it is missing, and kept on exit, so the
+ * data and the keys are the same on the next start; `substrio init` keeps .substrio/
+ * out of git). It reports its port on a pipe (substrio_server --ready-fd, a
+ * supervisor can use the same flag), so nothing polls /health. Or attaches to
+ * the server at --attach URL, with the key of the profile or SUBSTRIO_MASTER_KEY.
+ * Makes the app's tenant (or finds it again), applies substrio.toml and
+ * its files as one version, and then watches the app's directory with the OS
+ * file watcher: a saved function is redeployed alone, a changed substrio.toml,
+ * rules, cron, trigger or site as one new version, a changed build input runs
+ * its build step. A change the server refuses is reported, typed, with the
+ * server's diagnostics; the server keeps the last good version. The data
+ * survives every reload. The tenant's function logs stream to the terminal.
+ * Ctrl+C (or SIGTERM, SIGHUP) stops the watcher and the server; the data stays.
+ *
+ * A server declaration (index, expiry, aggregate) a collection's file no longer names is reported
+ * at each apply (drift) and left in place; --prune drops it instead. Never a field's undeclared
+ * adaptive key.
+ *
+ * It saves (and refreshes at each start, the port is new) the profile `<tenant>-dev`: this server's URL and the
+ * tenant's key, never made the default. `substrio --dev COMMAND` in the project's directory selects it, so
+ * `substrio invoke hello` from a second terminal reaches the dev server.
+ *
+ * Under --json every event is one JSON line ("ready" when the server is up,
+ * "watching" when saved files are seen from then on).
+ */
+
+import { join, resolve } from 'node:path';
+
+import { readApp } from '../apply.mjs';
+import { CliError, ErrorCode, emitLine, fail } from '../cli.mjs';
+import { aggregateCountLabel, indexCountLabel } from '../collections.mjs';
+import { devDataDir, devTenantSlug, loadConfig, saveDevProfile } from '../config.mjs';
+import { IdentityKind, appliedNames } from '../identity.mjs';
+import { FlagKind, parseFlags, wholeNumber } from '../local/args.mjs';
+import { Reloader, ReloadKind } from '../local/reload.mjs';
+import { LocalServer, resolveServerBinary } from '../local/server.mjs';
+import { AppWatcher, WatchPlan } from '../local/watch.mjs';
+import { followLogs, printLogEntry } from './logs.mjs';
+
+const C = {
+    reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+    red: '\x1b[91m', green: '\x1b[92m', yellow: '\x1b[93m', cyan: '\x1b[96m',
+};
+
+export const DEV_FLAGS = Object.freeze({
+    '--attach': FlagKind.VALUE,
+    '--server': FlagKind.VALUE,
+    '--port': FlagKind.VALUE,
+    '--data': FlagKind.VALUE,
+    '--debounce': FlagKind.VALUE,
+    '--no-build': FlagKind.SWITCH,
+    '--no-logs': FlagKind.SWITCH,
+    '--prune': FlagKind.SWITCH,
+});
+
+const place = (d) => `${d.file}${d.line ? `:${d.line}${d.column ? `:${d.column}` : ''}` : ''}`;
+const secs = (event) => `${event.ms} ms`;
+
+/** One reload event as the lines a person reads (pure). */
+export function describeReload(event) {
+    const k = ReloadKind;
+    switch (event.kind) {
+        case k.FUNCTION_DEPLOYED:
+            return [`${C.green}↻${C.reset} function ${C.bold}${event.name}${C.reset} deployed ${C.dim}(${secs(event)})${C.reset}`];
+        case k.FUNCTION_REMOVED:
+            return [`${C.green}↻${C.reset} function ${C.bold}${event.name}${C.reset} removed ${C.dim}(${secs(event)})${C.reset}`];
+        case k.FUNCTION_REFUSED: {
+            const lines = [`${C.red}✗${C.reset} function ${C.bold}${event.name}${C.reset} not deployed: the server keeps the last good version`];
+            for (const d of event.diagnostics ?? []) lines.push(`    ${place(d)} ${d.severity}: ${d.message}`);
+            if (event.error) lines.push(`    ${event.error.message}`);
+            if (event.esbuildHint) lines.push(`    ${C.yellow}⚠${C.reset} this may need bundling: run \`npm install --save-dev esbuild\` and save again`);
+            return lines;
+        }
+        case k.VERSION_APPLIED:
+            return [`${C.green}↻${C.reset} version ${event.version} applied: ${event.units.join(', ')} ${C.dim}(${event.functions} functions, ${secs(event)})${C.reset}`];
+        case k.VERSION_REFUSED:
+            return [`${C.red}✗${C.reset} the server refused the change${event.units ? ` (${event.units.join(', ')})` : ''}: ${event.error.message}`,
+                `    it keeps what it runs; the change goes with the next one`];
+        case k.COLLECTIONS_APPLIED: {
+            const lines = [`${C.green}↻${C.reset} collections applied: ${event.collections.map((c) => `${C.bold}${c.collection}${C.reset}${c.created ? ' (made)' : ''}${c.schema ? ' (schema)' : ''}${indexCountLabel(c.indexes ?? 0)}${aggregateCountLabel(c.aggregates ?? 0)}`).join(', ')} ${C.dim}(${secs(event)})${C.reset}`];
+            for (const w of event.warnings ?? []) lines.push(`    ${C.yellow}⚠ ${w.message}${C.reset}`);
+            return lines;
+        }
+        case k.COLLECTIONS_REFUSED:
+            return [`${C.red}✗${C.reset} the server refused a collection: ${event.error.message}`,
+                `    it keeps what it has; the change goes with the next save`];
+        case k.COLLECTIONS_DRIFT:
+            return event.drift.map((d) => `${C.yellow}⚠${C.reset} ${C.dim}${d.collection}: ${d.kind} ${d.label} is declared on the server but not in the file (substrio dev --prune drops it)${C.reset}`);
+        case k.COLLECTIONS_PRUNED:
+            return event.drift.map((d) => `${C.yellow}⊘${C.reset} ${C.dim}pruned ${d.collection}: ${d.kind} ${d.label}${C.reset}`);
+        case k.IDENTITY_APPLIED: {
+            const names = (kind) => appliedNames(event.applied, kind).map((n) => `${C.bold}${n}${C.reset}`).join(', ');
+            const parts = [['roles', IdentityKind.ROLE], ['auth providers', IdentityKind.PROVIDER]]
+                .filter(([, kind]) => appliedNames(event.applied, kind).length > 0).map(([label, kind]) => `${label} ${names(kind)}`);
+            return [`${C.green}↻${C.reset} ${parts.join('; ')} applied ${C.dim}(${secs(event)})${C.reset}`];
+        }
+        case k.IDENTITY_REFUSED:
+            return [`${C.red}✗${C.reset} the server refused a role or auth provider: ${event.error.message}`,
+                `    it keeps what it has; the change goes with the next apply`];
+        case k.BUILD_RAN:
+            return [`${C.green}↻${C.reset} built ${C.dim}${event.step.dir}: ${event.step.run} (${secs(event)})${C.reset}`];
+        case k.BUILD_FAILED:
+            return [`${C.red}✗${C.reset} build failed in ${event.step.dir}: ${event.error.message}`];
+        case k.CONFIG_REFUSED:
+            return [`${C.red}✗${C.reset} ${event.error.message}`, `    nothing changed on the server`];
+        case k.FAILED:
+            return [`${C.red}✗${C.reset} ${event.error?.message ?? 'failed'}`];
+        default:
+            return [];
+    }
+}
+
+/** The line of a reload event for --json: the kind and its fields, the error as the CLI reports one (pure). */
+export function reloadRecord(event) {
+    const { error, step, ...rest } = event;
+    return {
+        event: event.kind, ...rest,
+        ...(step ? { step: { dir: step.dir, run: step.run } } : {}),
+        ...(error ? { error: error instanceof CliError ? error.toJSON() : { error: String(error.message ?? error) } } : {}),
+    };
+}
+
+export async function cmdDev(args) {
+    let parsed;
+    let app;
+    try {
+        parsed = parseFlags(args, DEV_FLAGS);
+        app = readApp(process.cwd());
+    } catch (err) {
+        fail(err);
+    }
+    const { flags } = parsed;
+    const cwd = process.cwd();
+    let debounceMs;
+    let port;
+    try {
+        debounceMs = wholeNumber(flags, '--debounce', 0, 60_000, 50);
+        port = wholeNumber(flags, '--port', 0, 65_535, 0);
+    } catch (err) {
+        fail(err);
+    }
+
+    const attach = flags.get('--attach');
+    const slug = devTenantSlug(app.config);
+    let server;
+    let tenant;
+    let profile = null;
+    try {
+        if (attach !== undefined) {
+            const config = loadConfig(cwd);
+            if (!config.master_key) {
+                throw new CliError('--attach needs a key: SUBSTRIO_MASTER_KEY or the profile', { code: ErrorCode.CREDENTIAL_REQUIRED });
+            }
+            server = LocalServer.attach({ url: attach, masterKey: config.master_key });
+            tenant = await server.tenant(slug, config.master_key);
+        } else {
+            server = await LocalServer.spawn({
+                binary: resolveServerBinary(flags.get('--server')),
+                port,
+                dataDir: flags.has('--data') ? resolve(flags.get('--data')) : devDataDir(cwd),
+            });
+            tenant = await server.ensureTenant(slug, join(server.dataDir, 'tenant.key'));
+            // The CLI reaches this server from another terminal with `substrio --dev` (or --profile NAME).
+            profile = saveDevProfile(slug, server.url, tenant.key);
+        }
+    } catch (err) {
+        await server?.stop();
+        fail(err);
+    }
+
+    const abort = new AbortController();
+    const ignored = server.dataDir ? [server.dataDir] : [];
+    const plan = new WatchPlan(cwd, app.config, app.manifest, ignored);
+    const reloader = new Reloader({
+        cwd, api: tenant.api, ops: tenant.ops, invoke: tenant.invoke, debounceMs, build: !flags.has('--no-build'), prune: flags.has('--prune'),
+        report: (event) => emitLine(reloadRecord(event), () => {
+            for (const line of describeReload(event)) console.log(line);
+        }),
+        onFunctionInputs: (name, absPaths) => plan.setFunctionInputs(name, absPaths),
+    });
+    const watcher = new AppWatcher(plan, (change) => reloader.note(change));
+
+    let stopping = null;
+    const stop = (code) => {
+        stopping ??= (async () => {
+            abort.abort();
+            watcher.close();
+            await reloader.close();
+            await server.stop();
+            return code;
+        })();
+        return stopping;
+    };
+    const done = new Promise((resolveDone) => {
+        for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+            process.on(signal, () => {
+                // A second signal does not wait for the first one's cleanup.
+                if (stopping !== null) process.exit(130);
+                void stop(0).then(resolveDone);
+            });
+        }
+        // The server ending on its own is the end of the session, typed.
+        void server.exited.then((ended) => {
+            if (ended === null || stopping !== null) return;
+            console.error(`${C.red}✗ the server ended (${ended.signal ?? `exit ${ended.code}`})${C.reset}`);
+            void stop(1).then(resolveDone);
+        });
+    });
+
+    const apiUrl = server.url;
+    emitLine({ event: 'ready', url: apiUrl, tenant: slug, profile, app: `http://${slug}.localhost:${server.port}`, data_dir: server.dataDir }, () => {
+        console.log(`\n${C.bold}${C.cyan}⚡ substrio dev${C.reset} ${C.dim}(${server.target})${C.reset}`);
+        console.log(`  server  ${apiUrl}`);
+        console.log(`  app     http://${slug}.localhost:${server.port}`);
+        if (server.dataDir) {
+            console.log(`  data    ${server.dataDir} ${C.dim}(kept on exit, owner-only, with master.key and tenant.key)${C.reset}`);
+            console.log(`  key     ${join(server.dataDir, 'tenant.key')} ${C.dim}(SUBSTRIO_URL=${apiUrl} SUBSTRIO_TENANT=${slug} SUBSTRIO_MASTER_KEY=$(cat it))${C.reset}`);
+        }
+        if (profile !== null) {
+            console.log(`  profile ${profile} ${C.dim}(saved, not the default: "substrio --dev COMMAND" in this directory uses it)${C.reset}`);
+        }
+        console.log('');
+    });
+
+    // Armed before the first apply: the OS watcher takes a moment to arm, and a save landing in that gap would be
+    // lost. An event during the first apply marks the reloader dirty, and its drain loop applies it right after.
+    watcher.start();
+    await reloader.start();
+    // From here a saved file is seen: what a supervisor (or a test) waits for before it saves one.
+    emitLine({ event: 'watching' }, () => console.log(`  ${C.dim}watching for changes${C.reset}\n`));
+    if (!flags.has('--no-logs')) {
+        followLogs(tenant.api, {}, (entry) => emitLine(entry, printLogEntry), abort.signal).catch((err) => {
+            if (!abort.signal.aborted) console.error(`${C.yellow}⚠ ${err.message}${C.reset}`);
+        });
+    }
+    const code = await done;
+    process.exitCode = code;
+}

package/src/commands/env.mjs

@@ -0,0 +1,115 @@
+/**
+ * Substrio CLI: env command
+ * 
+ * Usage:
+ *   substrio env pull              Pull remote secrets → .env file
+ *   substrio env push              Push .env file → remote secrets
+ *   substrio env host set|list|remove   TEST-HOSTS: the app's environment hosts (env.host.*)
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+
+import { errorText } from '../api.mjs';
+import { CliError, ErrorCode, emit, exitCodeFor, fail } from '../cli.mjs';
+import { callOperation, failResult, loadOperations } from './op.mjs';
+import { cmdRegistry } from './groups-runtime.mjs';
+
+const C = {
+    reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+    red: '\x1b[91m', green: '\x1b[92m', cyan: '\x1b[96m', yellow: '\x1b[93m',
+};
+
+export async function cmdEnv(api, args) {
+    const sub = args[0];
+
+    if (sub === 'pull') return envPull(api);
+    if (sub === 'push') return envPush(api);
+    // TEST-HOSTS: any env.* operation by its words (substrio env host set host=... environment=dev).
+    if (sub && !sub.startsWith('-')) return cmdRegistry(api, 'env', args);
+
+    fail(`Unknown subcommand: ${sub || '(none)'}`, 'Usage: substrio env pull|push | env host set|list|remove');
+}
+
+// secret.list answers { secrets: [{key, value: "***"}], count }; --json
+// prints it whole once .env is written.
+async function envPull(api) {
+    const result = await callOperation(api, await loadOperations(api), 'secret.list', undefined);
+    if (!result.ok) failResult(result);
+    const secrets = result.data?.secrets ?? [];
+
+    if (secrets.length === 0) {
+        console.log(`${C.dim}No secrets configured. .env file not created.${C.reset}`);
+        return emit(result.data, () => {});
+    }
+
+    const lines = [
+        '# Substrio Secrets (pulled via "substrio env pull")',
+        `# Note: Values are masked, set real values manually or use "substrio secret set"`,
+        '',
+        ...secrets.map((s) => `${s.key}=${s.value}`),
+    ];
+
+    writeFileSync('.env', lines.join('\n') + '\n', 'utf-8');
+    emit(result.data, () => {
+        console.log(`${C.green}✓${C.reset} Pulled ${secrets.length} secret(s) to ${C.bold}.env${C.reset}`);
+        console.log(`${C.yellow}⚠${C.reset} Values are masked. Edit .env with real values, then "substrio env push".`);
+    });
+}
+
+async function envPush(api) {
+    if (!existsSync('.env')) fail('No .env file found in current directory.', null, ErrorCode.FILE_NOT_FOUND);
+
+    const content = readFileSync('.env', 'utf-8');
+    const entries = [];
+
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) continue;
+
+        const eqIdx = trimmed.indexOf('=');
+        if (eqIdx === -1) continue;
+
+        const key = trimmed.slice(0, eqIdx).trim();
+        let value = trimmed.slice(eqIdx + 1).trim();
+
+        // Strip quotes
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+
+        // Skip masked values
+        if (value === '***' || value.endsWith('***')) {
+            continue;
+        }
+
+        entries.push({ key, value });
+    }
+
+    if (entries.length === 0) {
+        console.log(`${C.dim}No non-masked entries to push.${C.reset}`);
+        return emit({ pushed: [], failed: [] }, () => {});
+    }
+
+    // Each by secret.write; --json prints the keys pushed and, per key that
+    // failed, the server's typed error. A failure exits with its code.
+    const ops = await loadOperations(api);
+    const pushed = [];
+    const failed = [];
+    let firstFailure = null;
+    for (const { key, value } of entries) {
+        const result = await callOperation(api, ops, 'secret.write', { key, value });
+        if (result.ok) {
+            pushed.push(key);
+            console.log(`  ${C.green}✓${C.reset} ${key}`);
+        } else {
+            const error = CliError.fromResponse(`${key}: ${errorText(result.data, result.status)}`, result.data, result.status);
+            firstFailure ??= error;
+            failed.push({ key, error: error.toJSON() });
+            console.log(`  ${C.red}✗${C.reset} ${key}: ${error.message}`);
+        }
+    }
+
+    emit({ pushed, failed }, () => console.log(`\n${C.green}✓${C.reset} Pushed ${pushed.length} secret(s)${failed.length ? `, ${C.red}${failed.length} failed${C.reset}` : ''}`));
+    if (firstFailure) process.exitCode = exitCodeFor(firstFailure);
+}

package/src/commands/files.mjs

@@ -0,0 +1,172 @@
+/**
+ * Substrio CLI: files command
+ * 
+ * Usage:
+ *   substrio files ls [path]            List files at path
+ *   substrio files upload <local> [remote]  Upload a file
+ *   substrio files rm <path>            Delete a file
+ *   substrio files sync <local-dir> <prefix> [--concurrency N]
+ *                                       Upload every file under the folder that the app's store
+ *                                       does not hold at the same path with the same size; a file
+ *                                       the server refuses (413) is reported and the sync goes on,
+ *                                       exit 8 (partial)
+ */
+
+import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
+import { basename, join, relative, sep } from 'node:path';
+import { setTimeout as wait } from 'node:timers/promises';
+
+import { ErrorCode, ExitCode, emit, emitLine, errorText, fail } from '../cli.mjs';
+import { cmdRegistry } from './groups-runtime.mjs';
+import { FlagKind, parseFlags, wholeNumber } from '../local/args.mjs';
+import { callOperation, failResult, invokeOperation, loadOperations, runOperation } from './op.mjs';
+
+const C = {
+    reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+    red: '\x1b[91m', green: '\x1b[92m', cyan: '\x1b[96m',
+};
+
+export async function cmdFiles(api, args) {
+    const sub = args[0];
+
+    switch (sub) {
+        case 'ls': case 'list': return runOperation(api, 'file.list', args.slice(1), { render: printFiles });
+        case 'upload': return filesUpload(api, args[1], args[2]);
+        case 'rm': case 'delete': return filesRm(api, args[1]);
+        case 'sync': return filesSync(api, args.slice(1));
+        default:
+            // Any other file.* operation by its words (substrio files download PATH).
+            if (sub && !sub.startsWith('-')) return cmdRegistry(api, 'files', args);
+            fail(`Unknown subcommand: ${sub || '(none)'}`, 'Usage: substrio files ls|upload|rm|sync, or a file.* operation');
+    }
+}
+
+// file.list answers { files: [{path, size, content_type, ...}], count }
+// (--json prints it whole).
+function printFiles(data) {
+    const files = Array.isArray(data.files) ? data.files : [];
+    if (files.length === 0) {
+        console.log(`${C.dim}No files found.${C.reset}`);
+        return;
+    }
+
+    console.log(`\n${C.bold}Files (${files.length})${C.reset}\n`);
+
+    const nameOf = (f) => String(f.path ?? '');
+    const nameW = Math.max(20, ...files.map((f) => nameOf(f).length));
+    console.log(`  ${'NAME'.padEnd(nameW)}  ${'SIZE'.padEnd(10)}  TYPE`);
+    console.log(`  ${'─'.repeat(nameW)}  ${'─'.repeat(10)}  ${'─'.repeat(15)}`);
+
+    for (const f of files) {
+        const size = f.size ? formatSize(f.size) : '-';
+        const type = f.content_type || '-';
+        console.log(`  ${nameOf(f).padEnd(nameW)}  ${size.padEnd(10)}  ${type}`);
+    }
+    console.log('');
+}
+
+// file.upload takes the file's bytes as its body, named by X-Filename (its
+// declared raw alternative to the JSON input);
+// file.delete takes the file's path. --json prints the server's answer.
+async function filesUpload(api, localPath, remoteName) {
+    if (!localPath) fail('Local file path required.', 'Usage: substrio files upload <local-path> [remote-name]');
+    if (!existsSync(localPath)) fail(`File not found: ${localPath}`, null, ErrorCode.FILE_NOT_FOUND);
+
+    const fileName = remoteName || basename(localPath);
+    const size = statSync(localPath).size;
+    const data = await invokeOperation(api, 'file.upload', {}, {
+        body: readFileSync(localPath),
+        headers: { 'Content-Type': 'application/octet-stream', 'X-Filename': fileName },
+    });
+    emit(data, () => console.log(`${C.green}✓${C.reset} Uploaded ${C.bold}${fileName}${C.reset} (${formatSize(size)})`));
+}
+
+const SYNC_USAGE = 'substrio files sync <local-dir> <prefix> [--concurrency N]';
+// One listing page: the store answers up to this many paths a call.
+const LIST_PAGE = 1000;
+// A 429 or 503 with no Retry-After waits this long before the same upload is sent again.
+const RETRY_MS = 1000;
+
+/**
+ * Makes the app's store hold every file under `dir`, at `prefix` + its path below `dir` (with
+ * `/`): one paged file.list of the prefix (a path and its size each), then only the files missing
+ * there or of another size are uploaded, `--concurrency` at once (default 8), each as its own
+ * bytes typed by the server from its name. A 429 or 503 is sent again after the server's wait,
+ * each wait a visible retry line; any other refusal stops the run. Nothing is deleted. Under
+ * --json: one line per retry, then one final `done` line {uploaded, skipped, bytes, elapsed_ms}.
+ * Per file: 1 stat, 1 map lookup; an upload adds 1 read and 1 call.
+ */
+async function filesSync(api, args) {
+    const { flags, positional } = parseFlags(args, { '--concurrency': FlagKind.VALUE });
+    const [dir, rawPrefix] = positional;
+    if (!dir || rawPrefix === undefined || positional.length > 2) fail('A folder and a prefix are required.', SYNC_USAGE);
+    if (!existsSync(dir) || !statSync(dir).isDirectory()) fail(`Folder not found: ${dir}`, SYNC_USAGE, ErrorCode.FILE_NOT_FOUND);
+    const concurrency = wholeNumber(flags, '--concurrency', 1, 64, 8);
+    const prefix = rawPrefix === '' || rawPrefix.endsWith('/') ? rawPrefix : rawPrefix + '/';
+    const started = Date.now();
+    const ops = await loadOperations(api);
+
+    const stored = new Map();
+    for (let cursor; ;) {
+        const page = await invokeOperation(api, 'file.list', { prefix, limit: LIST_PAGE, ...(cursor ? { cursor } : {}) }, { ops });
+        for (const file of page.files ?? []) stored.set(file.path, file.size);
+        cursor = page.next_cursor;
+        if (!cursor) break;
+    }
+
+    const due = [];
+    let skipped = 0;
+    for (const entry of readdirSync(dir, { recursive: true, withFileTypes: true })) {
+        if (!entry.isFile()) continue;
+        const local = join(entry.parentPath ?? entry.path, entry.name);
+        const below = relative(dir, local);
+        const path = prefix + (sep === '/' ? below : below.split(sep).join('/'));
+        const size = statSync(local).size;
+        if (stored.get(path) === size) skipped += 1;
+        else due.push({ local, path });
+    }
+
+    // A file the server refuses for itself (too large, a type it will not store) is reported and the
+    // sync goes on; the run then exits PARTIAL. A refusal of the caller (401, 403) ends it at once.
+    let next = 0;
+    let bytes = 0;
+    const refused = [];
+    const upload = async ({ local, path }) => {
+        const body = readFileSync(local);
+        for (;;) {
+            const result = await callOperation(api, ops, 'file.upload', {}, null, {
+                body, headers: { 'Content-Type': 'application/octet-stream', 'X-Filename': path },
+            });
+            if (result.ok) { bytes += body.length; return; }
+            if (result.status === 401 || result.status === 403) failResult(result);
+            if (result.status !== 429 && result.status !== 503) {
+                const error = { error: errorText(result.data, result.status), code: result.data?.code ?? null, status: result.status };
+                refused.push({ path, size: body.length, ...error });
+                emitLine({ event: 'refused', path, size: body.length, ...error }, () => console.log(`  ${C.red}✗${C.reset} ${path}: ${error.error}`));
+                return;
+            }
+            const waitMs = result.retryAfterMs ?? RETRY_MS;
+            emitLine({ event: 'retry', path, status: result.status, wait_ms: waitMs }, () => console.log(`  ${C.dim}retry ${path}: HTTP ${result.status}, waiting ${waitMs}ms${C.reset}`));
+            await wait(waitMs);
+        }
+    };
+    const worker = async () => { while (next < due.length) await upload(due[next++]); };
+    await Promise.all(Array.from({ length: Math.min(concurrency, due.length) }, worker));
+
+    const report = { uploaded: due.length - refused.length, skipped, refused: refused.length, bytes, elapsed_ms: Date.now() - started };
+    emitLine({ event: 'done', ...report }, () => console.log(`${C.green}✓${C.reset} Synced ${C.bold}${dir}${C.reset} to ${C.bold}${prefix || '/'}${C.reset}: ` +
+        `${report.uploaded} uploaded (${formatSize(bytes)}), ${skipped} already there, ${refused.length} refused, ${(report.elapsed_ms / 1000).toFixed(1)} s`));
+    if (refused.length > 0) process.exitCode = ExitCode.PARTIAL;
+}
+
+async function filesRm(api, path) {
+    if (!path) fail('File path required.', 'Usage: substrio files rm <path>');
+    const data = await invokeOperation(api, 'file.delete', { path });
+    emit(data, () => console.log(`${C.green}✓${C.reset} Deleted ${C.bold}${path}${C.reset}`));
+}
+
+function formatSize(bytes) {
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}