@substrio/cli 0.0.0-stage → 0.1.1

package/src/commands/history.mjs

@@ -0,0 +1,374 @@
+/**
+ * Substrio CLI: the app's history in the words a developer who knows git
+ * already types. Every verb here is one call to one registry operation, with
+ * its answer printed as a table (or as the server's own JSON under --json):
+ * nothing is worked out twice on this side.
+ *
+ *   substrio branch                       branch.list
+ *   substrio branch create NAME [--from REF]   branch.create
+ *   substrio branch delete NAME [--yes]   branch.delete
+ *   substrio branch protect NAME [--off] [--checks A,B]  branch.protect
+ *   substrio log [PATH] [--branch NAME] [--limit N]      version.log
+ *   substrio tag [NAME [VERSION]] [--branch NAME]        tag.list, tag.create
+ *   substrio merge FROM [--into NAME]     merge.plan
+ *   substrio merge status [--into NAME]   merge.get
+ *   substrio merge resolve PATH (--file F | --text T | -) [--into NAME]  merge.resolve
+ *   substrio merge commit [-m MSG] [--into NAME] [--checks-green]       merge.commit
+ *   substrio merge abort [--into NAME] [--yes]                          merge.abort
+ *   substrio gc [--status] [--dry-run]    version.gc, version.gc.status
+ *
+ * A word none of these owns runs the registry operation it names (substrio
+ * branch WORD ..., the same way substrio versions does), so an operation
+ * added to branch.*, tag.* or merge.* is reachable the day it ships.
+ */
+
+import { readFileSync } from 'node:fs';
+
+import { CliError, ErrorCode, confirmDestructive, emit, fail, globals } from '../cli.mjs';
+import { FlagKind, parseFlags, wholeNumber } from '../local/args.mjs';
+import { cmdRegistry } from './groups-runtime.mjs';
+import { invokeOperation } from './op.mjs';
+
+const C = {
+    reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+    red: '\x1b[91m', green: '\x1b[92m', yellow: '\x1b[93m', cyan: '\x1b[96m',
+};
+
+/** The branch every verb works on when none is named, as the server's own default is. */
+export const MAIN_BRANCH = 'main';
+/** How much of a version id a table shows (a git short hash is seven). */
+const ID_CHARS = 12;
+
+const when = (seconds) => (seconds ? new Date(seconds * 1000).toISOString().replace('T', ' ').slice(0, 16) : '');
+const shortId = (id) => (typeof id === 'string' ? id.slice(0, ID_CHARS) : '');
+const authorOf = (row) => (row.author ? `${row.author_kind ?? 'person'} ${row.author}` : '');
+
+// The one-letter flags git's own verbs take, as the long flag the table holds
+// (parseFlags reads `--name` alone, so a short flag is spelled out before it).
+const SHORT_FLAGS = { '-m': '--message' };
+
+// The words of a verb, with its flags taken out: a flag it does not take is a
+// usage error here, not a word sent to the server (parseFlags is the one flag
+// parser).
+function split(args, table, command) {
+    try {
+        return parseFlags(args.map((arg) => SHORT_FLAGS[arg] ?? arg), table);
+    } catch (err) {
+        return fail(err, `substrio ${command} --help`);
+    }
+}
+
+// A comma list of check names, or undefined when the flag is absent.
+function checkList(flags) {
+    const text = flags.get('--checks');
+    if (text === undefined) return undefined;
+    return text.split(',').map((name) => name.trim()).filter(Boolean);
+}
+
+// The bytes a merge resolution settles a unit with: --text, --file, or stdin
+// for "-". A unit that is not text goes as base64, which is the operation's
+// own second way of carrying it.
+function resolutionBody(flags, positional) {
+    if (flags.has('--text')) return { text: flags.get('--text') };
+    const file = flags.get('--file') ?? (positional.includes('-') ? '-' : undefined);
+    if (file === undefined) {
+        throw new CliError('merge resolve needs the bytes the unit is settled with', {
+            code: ErrorCode.INVALID_ARGUMENT,
+            hint: 'substrio merge resolve PATH --file FILE, --text TEXT, or - to read stdin',
+        });
+    }
+    const bytes = readFileSync(file === '-' ? 0 : file);
+    // Text as text, so the stored unit is the file: a unit with a NUL in it is
+    // not text and crosses as base64.
+    return bytes.includes(0) ? { base64: bytes.toString('base64') } : { text: bytes.toString('utf8') };
+}
+
+// ── branch ──────────────────────────────────────────────────────────────────
+
+const BRANCH_FLAGS = { '--from': FlagKind.VALUE, '--off': FlagKind.SWITCH, '--checks': FlagKind.VALUE };
+
+export async function cmdBranch(api, args = []) {
+    const word = args[0];
+    if (word === undefined || word.startsWith('-')) return branchList(api, args);
+    switch (word) {
+        case 'list': case 'ls': return branchList(api, args.slice(1));
+        case 'create': case 'add': case 'new': return branchCreate(api, args.slice(1));
+        case 'delete': case 'rm': case 'remove': return branchDelete(api, args.slice(1));
+        case 'protect': return branchProtect(api, args.slice(1));
+        default: return cmdRegistry(api, 'branch', args);
+    }
+}
+
+async function branchList(api, args) {
+    split(args, {}, 'branch');
+    const listed = await invokeOperation(api, 'branch.list', undefined);
+    if (globals.json) return emit(listed);
+    const branches = listed.branches || [];
+    if (branches.length === 0) {
+        console.log(`${C.dim}No branches yet. The first push makes ${MAIN_BRANCH}.${C.reset}`);
+        return;
+    }
+    const width = Math.max('BRANCH'.length, ...branches.map((b) => b.name.length)) + 2;
+    console.log(`\n${C.bold}Branches (${branches.length})${C.reset}\n`);
+    console.log(`  ${'BRANCH'.padEnd(width)}${'VERSION'.padEnd(14)}${'MOVED (UTC)'.padEnd(18)}PROTECTED`);
+    for (const b of branches) {
+        const guard = b.protected ? `yes${b.required_checks?.length ? ` (${b.required_checks.join(', ')})` : ''}` : '';
+        console.log(`  ${b.name.padEnd(width)}${shortId(b.version).padEnd(14)}${when(b.updated_at).padEnd(18)}${guard}`);
+    }
+    console.log('');
+}
+
+async function branchCreate(api, args) {
+    const { flags, positional } = split(args, BRANCH_FLAGS, 'branch');
+    const [name] = positional;
+    if (!name) return fail('substrio branch create NAME [--from REF] names the branch to make');
+    const from = flags.get('--from');
+    const made = await invokeOperation(api, 'branch.create', from ? { name, from } : { name });
+    emit(made, () => console.log(`${C.green}✓${C.reset} Branch ${C.bold}${made.name}${C.reset} at ${shortId(made.version) || 'no version yet'}` +
+        `${from ? ` ${C.dim}(from ${from})${C.reset}` : ''}`));
+}
+
+async function branchDelete(api, args) {
+    const { positional } = split(args, BRANCH_FLAGS, 'branch');
+    const [name] = positional;
+    if (!name) return fail('substrio branch delete NAME names the branch whose name is freed');
+    await confirmDestructive(`substrio branch delete ${name} frees the name (its versions and its log are kept)`,
+        `substrio branch delete ${name} --yes`);
+    const gone = await invokeOperation(api, 'branch.delete', { name });
+    emit(gone, () => console.log(`${C.green}✓${C.reset} Branch ${C.bold}${name}${C.reset} is free` +
+        `${gone.version ? ` ${C.dim}(it pointed at ${shortId(gone.version)}; substrio ref restore branch ${name} puts it back)${C.reset}` : ''}`));
+}
+
+async function branchProtect(api, args) {
+    const { flags, positional } = split(args, BRANCH_FLAGS, 'branch');
+    const [name] = positional;
+    if (!name) return fail('substrio branch protect NAME [--off] [--checks A,B] names the branch');
+    const checks = checkList(flags);
+    const input = { name, protected: !flags.has('--off') };
+    if (checks !== undefined) input.required_checks = checks;
+    const set = await invokeOperation(api, 'branch.protect', input);
+    emit(set, () => console.log(set.protected
+        ? `${C.green}✓${C.reset} Branch ${C.bold}${name}${C.reset} is protected: a commit or merge onto it needs ` +
+          `${set.required_checks?.length ? `${set.required_checks.join(', ')} green` : 'a green verdict'}`
+        : `${C.green}✓${C.reset} Branch ${C.bold}${name}${C.reset} is no longer protected`));
+}
+
+// ── log ─────────────────────────────────────────────────────────────────────
+
+const LOG_FLAGS = { '--branch': FlagKind.VALUE, '--limit': FlagKind.VALUE };
+
+export async function cmdLog(api, args = []) {
+    const { flags, positional } = split(args, LOG_FLAGS, 'log');
+    const branch = flags.get('--branch') ?? MAIN_BRANCH;
+    let limit;
+    try {
+        limit = wholeNumber(flags, '--limit', 1, 1_000_000, undefined);
+    } catch (err) {
+        return fail(err);
+    }
+    const [path] = positional;
+    const input = { branch };
+    if (path) input.path = path;
+    if (limit !== undefined) input.limit = limit;
+    const read = await invokeOperation(api, 'version.log', input);
+    if (globals.json) return emit(read);
+    const commits = read.versions || [];
+    if (commits.length === 0) {
+        console.log(`${C.dim}No commits on ${branch}${path ? ` touching ${path}` : ''}.${C.reset}`);
+        return;
+    }
+    console.log(`\n${C.bold}${branch}${C.reset}${path ? ` ${C.dim}· ${path}${C.reset}` : ''} ${C.dim}(${commits.length})${C.reset}\n`);
+    for (const c of commits) {
+        const merge = (c.parents || []).length > 1 ? ` ${C.yellow}(merge)${C.reset}` : '';
+        console.log(`  ${C.cyan}${shortId(c.version)}${C.reset} ${`#${c.number}`.padEnd(7)}${when(c.created_at).padEnd(18)}${c.message || ''}${merge}`);
+        if (c.author) console.log(`  ${C.dim}${' '.repeat(ID_CHARS)} ${authorOf(c)}${C.reset}`);
+    }
+    console.log('');
+}
+
+// ── tag ─────────────────────────────────────────────────────────────────────
+
+const TAG_FLAGS = { '--branch': FlagKind.VALUE };
+
+export async function cmdTag(api, args = []) {
+    const word = args[0];
+    if (word === undefined || word.startsWith('-')) return tagList(api, args);
+    if (word === 'list' || word === 'ls') return tagList(api, args.slice(1));
+    if (word === 'create' || word === 'add') return tagCreate(api, args.slice(1));
+    // A bare name is a tag to make (substrio tag v1.2.0 7), as git's own is.
+    if (word === 'delete' || word === 'rm') return cmdRegistry(api, 'tag', args);
+    return tagCreate(api, args);
+}
+
+async function tagList(api, args) {
+    split(args, {}, 'tag');
+    const listed = await invokeOperation(api, 'tag.list', undefined);
+    if (globals.json) return emit(listed);
+    const tags = listed.tags || [];
+    if (tags.length === 0) {
+        console.log(`${C.dim}No tags yet. Make one with: substrio tag v1.0.0${C.reset}`);
+        return;
+    }
+    const width = Math.max('TAG'.length, ...tags.map((t) => t.name.length)) + 2;
+    console.log(`\n${C.bold}Tags (${tags.length})${C.reset}\n`);
+    console.log(`  ${'TAG'.padEnd(width)}${'VERSION'.padEnd(14)}MADE (UTC)`);
+    for (const t of tags) console.log(`  ${t.name.padEnd(width)}${shortId(t.version).padEnd(14)}${when(t.created_at)}`);
+    console.log('');
+}
+
+async function tagCreate(api, args) {
+    const { flags, positional } = split(args, TAG_FLAGS, 'tag');
+    const [name, version] = positional;
+    if (!name) return fail('substrio tag NAME [VERSION] names the tag to make');
+    const input = { name };
+    if (version !== undefined) input.version = version;
+    else if (flags.has('--branch')) input.branch = flags.get('--branch');
+    const made = await invokeOperation(api, 'tag.create', input);
+    emit(made, () => console.log(`${C.green}✓${C.reset} Tag ${C.bold}${made.name}${C.reset} marks ${shortId(made.version)} ${C.dim}(a tag never moves)${C.reset}`));
+}
+
+// ── merge ───────────────────────────────────────────────────────────────────
+
+const MERGE_FLAGS = {
+    '--into': FlagKind.VALUE, '--message': FlagKind.VALUE,
+    '--file': FlagKind.VALUE, '--text': FlagKind.VALUE, '--checks-green': FlagKind.SWITCH,
+};
+
+export async function cmdMerge(api, args = []) {
+    const word = args[0];
+    switch (word) {
+        case 'status': case 'get': case 'show': return mergeDraft(api, args.slice(1));
+        case 'resolve': return mergeResolve(api, args.slice(1));
+        case 'commit': return mergeCommit(api, args.slice(1));
+        case 'abort': return mergeAbort(api, args.slice(1));
+        case undefined: return fail('substrio merge FROM [--into NAME] names the branch whose work comes in',
+            'substrio merge --help shows resolve, commit and abort');
+        default:
+            if (word.startsWith('-')) return fail('substrio merge FROM [--into NAME] names the branch whose work comes in');
+            return mergePlan(api, args);
+    }
+}
+
+// One line per unit the merge touched, conflicts first: what a developer has
+// to settle before the merge can be committed.
+function printDraft(draft) {
+    const units = draft.units || [];
+    const conflicted = units.filter((u) => u.kind?.startsWith('conflict'));
+    console.log(`\n${C.bold}${draft.from ? `${draft.from} → ` : ''}${draft.branch}${C.reset} ` +
+        `${C.dim}(base ${shortId(draft.base) || 'none'}, ours ${shortId(draft.ours) || 'none'}, theirs ${shortId(draft.theirs) || 'none'})${C.reset}\n`);
+    if (draft.up_to_date) console.log(`  ${C.green}Already up to date.${C.reset}`);
+    else if (draft.fast_forward) console.log(`  ${C.green}Fast forward: substrio merge commit moves ${draft.branch}.${C.reset}`);
+    if (units.length) {
+        const width = Math.max('UNIT'.length, ...units.map((u) => u.path.length)) + 2;
+        console.log(`  ${'UNIT'.padEnd(width)}WHAT THE MERGE DID`);
+        for (const u of units) {
+            const colour = u.kind?.startsWith('conflict') ? C.red : u.kind === 'resolved' ? C.green : C.reset;
+            console.log(`  ${u.path.padEnd(width)}${colour}${u.kind}${u.conflicts ? ` (${u.conflicts} region${u.conflicts === 1 ? '' : 's'})` : ''}${C.reset}`);
+        }
+    }
+    if (conflicted.length) {
+        console.log(`\n  ${C.yellow}${conflicted.length} unit${conflicted.length === 1 ? '' : 's'} to settle${C.reset}: ` +
+            `substrio merge resolve ${conflicted[0].path} --file FILE${draft.branch === MAIN_BRANCH ? '' : ` --into ${draft.branch}`}`);
+        console.log(`  ${C.dim}Each conflicted unit's merged bytes, markers and all: substrio versions unit ${shortId(draft.ours)} path=${conflicted[0].path}${C.reset}`);
+    } else if (!draft.up_to_date) {
+        console.log(`\n  ${C.dim}Nothing is conflicted: substrio merge commit${draft.branch === MAIN_BRANCH ? '' : ` --into ${draft.branch}`} publishes it${C.reset}`);
+    }
+    console.log('');
+}
+
+async function mergePlan(api, args) {
+    const { flags, positional } = split(args, MERGE_FLAGS, 'merge');
+    const [from] = positional;
+    const into = flags.get('--into') ?? MAIN_BRANCH;
+    const draft = await invokeOperation(api, 'merge.plan', { from, into });
+    emit(draft, () => printDraft(draft));
+}
+
+async function mergeDraft(api, args) {
+    const { flags } = split(args, MERGE_FLAGS, 'merge');
+    const branch = flags.get('--into') ?? MAIN_BRANCH;
+    const draft = await invokeOperation(api, 'merge.get', { branch }, {
+        hint: (result) => (result.status === 404 ? `${branch} has no merge in hand: substrio merge FROM --into ${branch} starts one` : null),
+    });
+    emit(draft, () => printDraft(draft));
+}
+
+async function mergeResolve(api, args) {
+    const { flags, positional } = split(args, MERGE_FLAGS, 'merge');
+    const branch = flags.get('--into') ?? MAIN_BRANCH;
+    const [path] = positional.filter((a) => a !== '-');
+    if (!path) return fail('substrio merge resolve PATH (--file FILE | --text TEXT | -) names the unit to settle');
+    let bytes;
+    try {
+        bytes = resolutionBody(flags, positional);
+    } catch (err) {
+        return fail(err);
+    }
+    const draft = await invokeOperation(api, 'merge.resolve', { branch, path, ...bytes });
+    emit(draft, () => {
+        console.log(`${C.green}✓${C.reset} ${path} is settled ${C.dim}(${draft.conflicts} left)${C.reset}`);
+        printDraft(draft);
+    });
+}
+
+async function mergeCommit(api, args) {
+    const { flags } = split(args, MERGE_FLAGS, 'merge');
+    const branch = flags.get('--into') ?? MAIN_BRANCH;
+    const message = flags.get('--message');
+    const input = { branch };
+    if (message !== undefined) input.message = message;
+    if (flags.has('--checks-green')) input.checks_green = true;
+    const done = await invokeOperation(api, 'merge.commit', input);
+    emit(done, () => {
+        if (done.up_to_date) return console.log(`${C.dim}${branch} already holds that work; nothing was committed.${C.reset}`);
+        const how = done.fast_forward ? 'fast forwarded to' : 'committed';
+        console.log(`${C.green}✓${C.reset} ${C.bold}${branch}${C.reset} ${how} ${shortId(done.version)}` +
+            `${done.number ? ` ${C.dim}(version ${done.number})${C.reset}` : ''}`);
+    });
+}
+
+async function mergeAbort(api, args) {
+    const { flags } = split(args, MERGE_FLAGS, 'merge');
+    const branch = flags.get('--into') ?? MAIN_BRANCH;
+    await confirmDestructive(`substrio merge abort --into ${branch} throws away the merge in hand (the branch itself never moved)`,
+        `substrio merge abort${branch === MAIN_BRANCH ? '' : ` --into ${branch}`} --yes`);
+    const gone = await invokeOperation(api, 'merge.abort', { branch });
+    emit(gone, () => console.log(gone.deleted
+        ? `${C.green}✓${C.reset} The merge onto ${C.bold}${branch}${C.reset} is thrown away`
+        : `${C.dim}${branch} had no merge in hand.${C.reset}`));
+}
+
+// ── gc ──────────────────────────────────────────────────────────────────────
+
+const GC_FLAGS = { '--status': FlagKind.SWITCH, '--dry-run': FlagKind.SWITCH };
+
+export async function cmdGc(api, args = []) {
+    const { flags } = split(args, GC_FLAGS, 'gc');
+    const status = flags.has('--status');
+    const dryRun = flags.has('--dry-run');
+    if (status && dryRun) return fail('substrio gc --status reads the last collection; --dry-run works one out. Give one');
+    if (!status && !dryRun) {
+        await confirmDestructive('substrio gc erases every object of the app\'s history no name reaches (--dry-run works it out and erases nothing)',
+            'substrio gc --yes');
+    }
+    const report = status
+        ? await invokeOperation(api, 'version.gc.status', undefined)
+        : await invokeOperation(api, 'version.gc', dryRun ? { dry_run: true } : {});
+    if (globals.json) return emit(report);
+    if (status && !report.started_at) {
+        console.log(`${C.dim}This app was never collected. substrio gc --dry-run says what one would take.${C.reset}`);
+        return;
+    }
+    const megabytes = (report.bytes / 1_048_576).toFixed(2);
+    console.log(`\n${C.bold}${report.dry_run ? 'A collection would take' : 'Collected'}${C.reset} ${C.dim}(${when(report.started_at)} UTC)${C.reset}\n`);
+    console.log(`  ${'roots'.padEnd(12)}${report.roots}`);
+    console.log(`  ${'kept'.padEnd(12)}${report.marked}${report.kept_new ? ` ${C.dim}(+${report.kept_new} written while it ran)${C.reset}` : ''}`);
+    console.log(`  ${'read'.padEnd(12)}${report.read}`);
+    console.log(`  ${'collected'.padEnd(12)}${report.collected} ${C.dim}(${megabytes} MB)${C.reset}`);
+    if (report.missing) console.log(`  ${'missing'.padEnd(12)}${C.yellow}${report.missing}${C.reset}`);
+    if (report.foreign) console.log(`  ${'foreign'.padEnd(12)}${report.foreign} ${C.dim}(objects of another app, left alone)${C.reset}`);
+    if (!report.complete) {
+        console.log(`\n  ${C.yellow}Stopped at its sweep bound${C.reset}: substrio gc carries it on from ${report.resume_after}`);
+    }
+    console.log('');
+}