@substrio/cli 0.0.0-stage → 0.1.0

package/src/commands/git.mjs

@@ -0,0 +1,195 @@
+/**
+ * Substrio CLI: the app's history as a git repository, and back.
+ *
+ *   substrio git export DIR    the whole history as commits in DIR
+ *   substrio git import DIR    DIR's commits as the app's history
+ *
+ * Both are one stream between two processes, with nothing held in memory on
+ * this side: `substrio_server --git-export <app>` writes a git fast-import
+ * stream (api/version_git.h) that `git fast-import` reads in DIR, and `git
+ * fast-export --all` writes the stream `substrio_server --git-import <app>`
+ * reads. The server's own stream is the one owner of the translation; this
+ * file names the two processes and joins their pipe.
+ *
+ * It is the one command of this CLI that is not an HTTP call: the history
+ * crosses with no port, no key and no request, which is also its limit - the
+ * app's database file has to be on this machine, named by --data (the
+ * directory `substrio dev` keeps, .substrio/dev, by default). A remote app is
+ * exported by running the same command where its server runs.
+ */
+
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import { CliError, ErrorCode, emit, fail } from '../cli.mjs';
+import { devDataDir } from '../config.mjs';
+import { FlagKind, parseFlags } from '../local/args.mjs';
+import { resolveServerBinary } from '../local/server.mjs';
+
+const C = { reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m', green: '\x1b[92m' };
+
+const GIT_FLAGS = {
+    '--data': FlagKind.VALUE,    // the server's data directory (default: .substrio/dev)
+    '--server': FlagKind.VALUE,  // the substrio_server binary (default: PATH, then the checkout's build)
+    '--owner': FlagKind.VALUE,   // the account the objects are billed to
+    '--author': FlagKind.VALUE,  // the person a commit by nobody this app knows is attributed to, on import
+};
+
+/** The file an app keeps its refs and its history in, under the server's data directory. */
+export const appDatabase = (dataDir, slug) => join(dataDir, slug, 'substrio.db');
+
+// A whole number flag, or `fallback`; a value that is not one is a usage error.
+function number(flags, name, fallback) {
+    const text = flags.get(name);
+    if (text === undefined) return fallback;
+    if (!/^\d+$/.test(text)) throw new CliError(`${name} is an id: whole digits`, { code: ErrorCode.INVALID_ARGUMENT });
+    return Number(text);
+}
+
+/**
+ * Where the app's history lives: the data directory, the slug and the
+ * database file, all three checked before a process is started. Throws a
+ * typed CliError naming what is missing.
+ */
+export function historyLocation(config, flags, cwd = process.cwd()) {
+    const slug = config.tenant;
+    if (!slug) {
+        throw new CliError('No app: substrio git needs a tenant', {
+            code: ErrorCode.INVALID_ARGUMENT,
+            hint: 'Give --tenant SLUG, or run it in a project whose substrio.toml names one',
+        });
+    }
+    const dataDir = resolve(flags.get('--data') ?? devDataDir(cwd));
+    const database = appDatabase(dataDir, slug);
+    if (!existsSync(database)) {
+        throw new CliError(`${slug} keeps no database at ${database}`, {
+            code: ErrorCode.FILE_NOT_FOUND,
+            hint: flags.has('--data')
+                ? 'Give --data DIR of the server that serves this app; it has to be a directory on this machine'
+                : `Give --data DIR (the default is this project's ${devDataDir(cwd)}, which "substrio dev" makes)`,
+        });
+    }
+    return { slug, dataDir, database };
+}
+
+// A child process as a promise: its exit code, with its stderr relayed to
+// ours as it comes (the server writes its one-line summary there).
+function ended(child, what) {
+    return new Promise((done, broken) => {
+        child.on('error', (err) => broken(new CliError(`${what} could not be run: ${err.message}`, { code: ErrorCode.UNKNOWN })));
+        child.on('close', (code, signal) => done(signal ? `${what} was stopped by ${signal}` : code === 0 ? null : `${what} exited ${code}`));
+    });
+}
+
+// `git` with these arguments in `dir`, its output relayed; the failure text,
+// or null.
+function git(args, dir, stdio = 'inherit') {
+    return ended(spawn('git', args, { cwd: dir, stdio }), `git ${args[0]}`);
+}
+
+/** The arguments a stream command runs substrio_server with (pure, so a test reads them). */
+export function serverArgs({ dataDir, database, slug, owner = 0, author = null }, direction) {
+    const args = ['--data', dataDir, `--git-${direction}`, slug, '--git-db', database, '--git-owner', String(owner)];
+    if (author !== null) args.push('--git-author', String(author));
+    return args;
+}
+
+export async function cmdGit(config, args = []) {
+    const word = args[0];
+    if (word === 'export') return gitExport(config, args.slice(1));
+    if (word === 'import') return gitImport(config, args.slice(1));
+    return fail('substrio git export DIR | substrio git import DIR',
+        'export writes the app\'s history into a git repository; import reads one back');
+}
+
+// The repository a stream is written into: an existing one is used as it is,
+// an empty (or missing) directory is made one. A directory holding something
+// else is refused, because a fast-import would write refs into nothing.
+function repositoryFor(dir) {
+    if (existsSync(join(dir, '.git'))) return { made: false };
+    if (existsSync(dir) && readdirSync(dir).length > 0) {
+        throw new CliError(`${dir} is not a git repository and is not empty`, {
+            code: ErrorCode.INVALID_ARGUMENT,
+            hint: 'Name an empty directory, or one that is already a repository',
+        });
+    }
+    mkdirSync(dir, { recursive: true });
+    return { made: true };
+}
+
+async function gitExport(config, args) {
+    let where;
+    let dir;
+    let repository;
+    let run;
+    try {
+        const { flags, positional } = parseFlags(args, GIT_FLAGS);
+        if (!positional[0]) {
+            throw new CliError('substrio git export DIR names the directory the history is written into',
+                { code: ErrorCode.INVALID_ARGUMENT });
+        }
+        dir = resolve(positional[0]);
+        where = historyLocation(config, flags);
+        repository = repositoryFor(dir);
+        run = { binary: resolveServerBinary(flags.get('--server')), owner: number(flags, '--owner', 0) };
+    } catch (err) {
+        return fail(err);
+    }
+    if (repository.made) {
+        const failed = await git(['init', '--quiet', '.'], dir);
+        if (failed) return fail(failed, 'git has to be on PATH for substrio git export');
+    }
+
+    // One pipe, two processes: the server writes the stream, git reads it. The
+    // bytes never enter this process.
+    const server = spawn(run.binary, serverArgs({ ...where, owner: run.owner }, 'export'),
+        { stdio: ['ignore', 'pipe', 'inherit'] });
+    const importer = spawn('git', ['fast-import', '--quiet'], { cwd: dir, stdio: ['pipe', 'inherit', 'inherit'] });
+    server.stdout.pipe(importer.stdin);
+    const [wrote, read] = await Promise.all([ended(server, 'substrio_server --git-export'), ended(importer, 'git fast-import')]);
+    if (wrote || read) return fail(wrote ?? read, 'nothing of the app changed; the repository may hold a partial import');
+
+    // A repository this command made holds the history and no files yet; one
+    // that was already here keeps its working tree exactly as it was.
+    if (repository.made) await git(['checkout', '--quiet', 'main'], dir, ['ignore', 'inherit', 'ignore']);
+    emit({ exported: where.slug, directory: dir, repository: repository.made ? 'created' : 'existing' }, () => {
+        console.log(`${C.green}✓${C.reset} ${C.bold}${where.slug}${C.reset}'s history is in ${dir}` +
+            `${repository.made ? '' : ` ${C.dim}(its refs; the working tree was left alone)${C.reset}`}`);
+        console.log(`  ${C.dim}git -C ${dir} log --graph --all${C.reset}`);
+    });
+}
+
+async function gitImport(config, args) {
+    let where;
+    let dir;
+    let run;
+    try {
+        const { flags, positional } = parseFlags(args, GIT_FLAGS);
+        if (!positional[0]) {
+            throw new CliError('substrio git import DIR names the git repository the history is read from',
+                { code: ErrorCode.INVALID_ARGUMENT });
+        }
+        dir = resolve(positional[0]);
+        if (!existsSync(join(dir, '.git'))) {
+            throw new CliError(`${dir} is not a git repository`, { code: ErrorCode.FILE_NOT_FOUND });
+        }
+        where = historyLocation(config, flags);
+        run = {
+            binary: resolveServerBinary(flags.get('--server')),
+            owner: number(flags, '--owner', 0), author: number(flags, '--author', 0),
+        };
+    } catch (err) {
+        return fail(err);
+    }
+    const exporter = spawn('git', ['fast-export', '--all'], { cwd: dir, stdio: ['ignore', 'pipe', 'inherit'] });
+    const server = spawn(run.binary, serverArgs({ ...where, owner: run.owner, author: run.author }, 'import'),
+        { stdio: ['pipe', 'inherit', 'inherit'] });
+    exporter.stdout.pipe(server.stdin);
+    const [wrote, read] = await Promise.all([ended(exporter, 'git fast-export'), ended(server, 'substrio_server --git-import')]);
+    if (wrote || read) return fail(read ?? wrote, 'the app took only the commits the stream carried before the refusal');
+    emit({ imported: where.slug, directory: dir }, () => {
+        console.log(`${C.green}✓${C.reset} ${dir} is now ${C.bold}${where.slug}${C.reset}'s history ${C.dim}(the counts above are the server's)${C.reset}`);
+        console.log(`  ${C.dim}substrio branch, substrio log${C.reset}`);
+    });
+}

package/src/commands/groups-runtime.mjs

@@ -0,0 +1,227 @@
+/**
+ * Substrio CLI: group commands, run. The table itself (GROUPS, REGISTRY_GROUPS,
+ * resolveGroup, entryOf, isDestructiveOperation...) is pure data in
+ * ./groups.mjs, loaded unconditionally so --version and --help stay light;
+ * this module is the one owner of running a group command (a server call, a
+ * confirmation, a file write), loaded only once a group command runs.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { confirmDestructive, fail } from '../cli.mjs';
+import { writePrivateFile } from '../config.mjs';
+import { splitPositional } from '../ops.mjs';
+import {
+    GroupFlow, groupOf, isDestructiveOperation, registryGroupsOf, registryOperation, resolveGroup,
+} from './groups.mjs';
+import { loadOperations, runOperation } from './op.mjs';
+
+const C = {
+    reset: '\x1b[0m', bold: '\x1b[1m', green: '\x1b[92m',
+};
+
+/** The operation `substrio command ...args` names in its registry groups, from the server's catalog. */
+export async function findRegistryOperation(api, command, args) {
+    const ops = await loadOperations(api);
+    const found = registryOperation(new Set(ops.map((op) => op.name)), registryGroupsOf(command), args);
+    if (!found) {
+        const groups = registryGroupsOf(command);
+        throw new Error(`Unknown ${command} command: ${args.filter((a) => typeof a === 'string' && !a.startsWith('-') && !a.includes('=')).join(' ') || '(none)'}. ` +
+            `Its operations: ${groups.map((g) => `substrio op list ${g}.`).join(', ') || 'substrio op list'}`);
+    }
+    return { ...found, ops };
+}
+
+/** Runs the registry operation `substrio command ...args` names (group words and flows alike). */
+export async function cmdRegistry(api, command, args) {
+    let found;
+    try {
+        found = await findRegistryOperation(api, command, args);
+    } catch (err) {
+        return fail(err, `substrio ${command} --help`);
+    }
+    // An operation with both a write and a delete route is destructive only
+    // by its DELETE route, not by its own name:
+    // an explicit --method/-X DELETE on the pass-through path is destructive too.
+    const methodAt = Math.max(found.rest.indexOf('--method'), found.rest.indexOf('-X'));
+    const destructiveMethod = methodAt >= 0 && found.rest[methodAt + 1]?.toUpperCase() === 'DELETE';
+    if (isDestructiveOperation(found.operation) || destructiveMethod) {
+        await confirmDestructive(`substrio ${command} ${args.join(' ')} runs ${found.operation}, which cannot be undone`,
+            `substrio ${command} ${args.join(' ')} --yes`);
+    }
+    const { positional, rest } = splitPositional(found.rest);
+    return runOperation(api, found.operation, rest, { positional, ops: found.ops });
+}
+
+// Takes `--out FILE` out of `args`; returns the file, or null.
+export function takeOut(args) {
+    const at = args.indexOf('--out');
+    if (at < 0) return null;
+    if (at + 1 >= args.length) throw new Error('--out needs a file');
+    const [, file] = args.splice(at, 2);
+    return file;
+}
+
+// A new account key goes to `file`, owner-only and never over an existing
+// file; what is printed says where it went, never the key.
+export function saveKey(file) {
+    return (data) => {
+        const { key, ...shown } = data;
+        if (typeof key === 'string') {
+            writePrivateFile(file, `${key}\n`, { exclusive: true });
+            console.error(`${C.green}✓${C.reset} Key written to ${file} (owner-only); it is shown nowhere else.`);
+        }
+        return shown;
+    };
+}
+
+// Takes `flag` and its value out of `args`; undefined when `flag` is absent.
+function takeFlag(args, flag) {
+    const at = args.indexOf(flag);
+    if (at < 0) return undefined;
+    if (at + 1 >= args.length) throw new Error(`${flag} needs a value`);
+    const [, value] = args.splice(at, 2);
+    return value;
+}
+
+const SECRET_SET_USAGE = 'substrio secrets set KEY  (the value from stdin, or -, --from-file PATH, or --from-env NAME)';
+
+/**
+ * secrets set KEY: the value is never a plain argument (argv, history and
+ * process lists would show it) -- stdin (the default, and what "-" or a
+ * non-TTY stdin means), --from-file PATH or --from-env NAME, one of the
+ * three. Never logged, printed or put in an error.
+ */
+async function cmdSecretSet(api, resolved) {
+    const [key, ...restPositional] = resolved.positional;
+    if (!key) fail(`Usage: ${SECRET_SET_USAGE}`);
+    const rest = [...resolved.rest];
+    let fromFile, fromEnv;
+    try {
+        fromFile = takeFlag(rest, '--from-file');
+        fromEnv = takeFlag(rest, '--from-env');
+    } catch (err) {
+        fail(err);
+    }
+    // A word of any shape after KEY (plain text, or one that looks like a
+    // flag or a key=value field, which rest rather than positional carries)
+    // is the value given as an argument: refused before it is ever read.
+    const explicitStdin = restPositional.length === 1 && restPositional[0] === '-';
+    if ((!explicitStdin && restPositional.length > 0) || rest.length > 0) {
+        fail('secrets set does not take the value as an argument: it would show in argv, history and process lists',
+            `substrio secrets set ${key} < file (stdin), --from-file PATH, or --from-env NAME`);
+    }
+    if ([fromFile !== undefined, fromEnv !== undefined, explicitStdin].filter(Boolean).length > 1) {
+        fail('secrets set: give the value one way only: stdin, --from-file PATH or --from-env NAME');
+    }
+    let value;
+    if (fromFile !== undefined) value = readFileSync(fromFile, 'utf8').replace(/\r?\n$/, '');
+    else if (fromEnv !== undefined) {
+        value = process.env[fromEnv];
+        if (value === undefined) fail(`secrets set: ${fromEnv} is not set`);
+    } else if (explicitStdin || !process.stdin.isTTY) value = readFileSync(0, 'utf8').replace(/\r?\n$/, '');
+    else fail(`Usage: ${SECRET_SET_USAGE}`, 'the value is never a plain argument');
+    return runOperation(api, 'secret.write', [`key==${key}`, `value==${value}`], { method: 'PUT' });
+}
+
+// permissions grant/revoke USER_ID NAME ...: the names are a variable number
+// of trailing bare words, so user.permissions.set's own array field (grant
+// or revoke) is built here, not through resolveGroup's trailing splice
+// (which only ever takes a fixed field count).
+async function cmdUserPermissionsEdit(api, resolved, field) {
+    const [id, ...names] = resolved.positional;
+    if (!id || names.length === 0) fail(`Usage: substrio permissions ${field} USER_ID NAME ...`);
+    return runOperation(api, 'user.permissions.set', [...resolved.rest, `id==${id}`, `${field}:=${JSON.stringify(names)}`]);
+}
+
+// memberships grant/revoke/show's --in COLLECTION:ID: the organization
+// (user.memberships.get/set's collection and id fields), taken out of `rest`
+// in place; undefined when --in was not given.
+function takeMembershipIn(rest) {
+    const value = takeFlag(rest, '--in');
+    if (value === undefined) return undefined;
+    const at = value.indexOf(':');
+    if (at < 0) fail(`--in needs collection:id, not ${value}`);
+    return { collection: value.slice(0, at), id: value.slice(at + 1) };
+}
+
+// memberships grant/revoke USER_ID NAME ... --in COLLECTION:ID: the names
+// are a variable number of trailing bare words, so user.memberships.set's
+// own array field (grant or revoke) is built here, as
+// cmdUserPermissionsEdit builds user.permissions.set's. user_id travels
+// unquoted (=, not ==): the schema needs it a JSON integer, not a string.
+async function cmdUserMembershipsEdit(api, resolved, field) {
+    const [userId, ...names] = resolved.positional;
+    const rest = [...resolved.rest];
+    const membership = takeMembershipIn(rest);
+    if (!userId || names.length === 0 || !membership) {
+        fail(`Usage: substrio memberships ${field} USER_ID NAME ... --in COLLECTION:ID`);
+    }
+    return runOperation(api, 'user.memberships.set', [
+        ...rest, `user_id=${userId}`, `collection==${membership.collection}`, `id==${membership.id}`,
+        `${field}:=${JSON.stringify(names)}`,
+    ]);
+}
+
+// memberships show USER_ID [--in COLLECTION:ID]: user.memberships.get is a
+// GET, so these fields travel in the query string (buildRequest's own rule
+// for GET), not the body; --in is optional (every organization held, else
+// just the one named).
+async function cmdUserMembershipsShow(api, resolved) {
+    const [userId] = resolved.positional;
+    const rest = [...resolved.rest];
+    const membership = takeMembershipIn(rest);
+    if (!userId) fail('Usage: substrio memberships show USER_ID [--in COLLECTION:ID]');
+    const fields = [...rest, `user_id=${userId}`];
+    if (membership) fields.push(`collection==${membership.collection}`, `id==${membership.id}`);
+    return runOperation(api, 'user.memberships.get', fields);
+}
+
+// Each flow's runner, loaded when its words run.
+const FLOWS = {
+    [GroupFlow.IMPORT]: async (api, resolved) => (await import('./import.mjs')).cmdImport(api, resolved),
+    [GroupFlow.COUNT]: async (api, resolved) => (await import('./count.mjs')).cmdCount(api, resolved),
+    [GroupFlow.MCP_CONFIG]: async (api, resolved, context) => (await import('./mcp-config.mjs')).cmdMcpConfig(api, resolved, context),
+    [GroupFlow.TOOL_INSTALL]: async (api, resolved) => (await import('./tools.mjs')).cmdToolInstall(api, resolved),
+    [GroupFlow.SECRET_SET]: async (api, resolved) => cmdSecretSet(api, resolved),
+    [GroupFlow.USER_PERMISSIONS_GRANT]: async (api, resolved) => cmdUserPermissionsEdit(api, resolved, 'grant'),
+    [GroupFlow.USER_PERMISSIONS_REVOKE]: async (api, resolved) => cmdUserPermissionsEdit(api, resolved, 'revoke'),
+    [GroupFlow.USER_MEMBERSHIPS_GRANT]: async (api, resolved) => cmdUserMembershipsEdit(api, resolved, 'grant'),
+    [GroupFlow.USER_MEMBERSHIPS_REVOKE]: async (api, resolved) => cmdUserMembershipsEdit(api, resolved, 'revoke'),
+    [GroupFlow.USER_MEMBERSHIPS_SHOW]: async (api, resolved) => cmdUserMembershipsShow(api, resolved),
+};
+
+// `context` is what the command's entry gave beyond the API client: {config}.
+export async function cmdGroup(api, command, args, context = {}) {
+    const group = groupOf(command);
+    let resolved;
+    let out = null;
+    const rest = [...args];
+    try {
+        out = takeOut(rest);
+        resolved = resolveGroup(group, rest);
+        if (!resolved.operation && out) throw new Error('--out is for accounts keys create');
+        if (resolved.operation === 'account.key.create' && !out) {
+            throw new Error('keys create needs --out FILE: the new key is written there, never printed');
+        }
+        if (out && existsSync(out)) {
+            throw new Error(`${out} exists; --out names a new file for the key`);
+        }
+    } catch (err) {
+        fail(err, `substrio ${group} --help lists its commands; any other operation: substrio op list`);
+    }
+    if (resolved.destructive) {
+        await confirmDestructive(`substrio ${command} ${args.join(' ')} runs ${resolved.operation}, which cannot be undone`,
+            `substrio ${command} ${args.join(' ')} --yes`);
+    }
+    if (resolved.flow !== null) return FLOWS[resolved.flow](api, resolved, context);
+    if (!resolved.operation) return cmdRegistry(api, group, rest);
+    // A "-" value is read from stdin, keeping it out of argv and history.
+    if (resolved.stdinField) {
+        resolved.rest.push(`${resolved.stdinField}==${readFileSync(0, 'utf8').replace(/\r?\n$/, '')}`);
+    }
+    const present = resolved.operation === 'account.key.create' ? saveKey(out) : null;
+    return runOperation(api, resolved.operation, resolved.rest, {
+        positional: resolved.positional, present, render: resolved.render, method: resolved.method,
+        defaults: resolved.defaults, body: resolved.body,
+    });
+}