@fairgarden/distribution 0.1.0-0.canary.0

package/dist/cli.js

@@ -0,0 +1,1076 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { mkdir, readFile } from 'node:fs/promises';
+import { addModule } from "./add-module.js";
+import { extractModule } from "./extract.js";
+import { writeReadmes } from "./readme.js";
+import { writeDistributionChangelogCheck, writeDistributionWorkflow, writeWorkflows } from "./workflows.js";
+import { writeOverrides } from "./overrides.js";
+import { checkReleasable, planRelease, readRelease, release, releaseDistribution, reportToActions as reportRelease, startPrerelease, } from "./release.js";
+import { reportToActions as reportCanary, stampCanary } from "./canary.js";
+import { describeRemote, isSsh, toHttps } from "./git-url.js";
+import { distributionRepo, isEmpty, moduleRepo, monolithRepo, write, } from "./scaffold.js";
+import { describeViolations, inspectExtends } from "./extends.js";
+import { contribute, forkModule, integrate, unforkModule } from "./forks.js";
+import { inherit } from "./inherit.js";
+import { bumpEntry, checkChangelog, crossedReleases, CHANGELOG, moduleLabel, noteInDistribution, notesFor, pullRequestFromActions, } from "./changelog.js";
+import { buildPolicy, findPolicy, POLICIES, setupTurbo, testPolicy, usePolicy } from "./policy.js";
+import { stampModules } from "./manifest.js";
+import { containsAll, inspect, isDistribution, isPublic, moveTo, repositoryRoot, setUrl, submodules, target, } from "./submodules.js";
+// Piping into `head` closes stdout early; that is ordinary use, not a failure.
+for (const stream of [process.stdout, process.stderr]) {
+    stream.on('error', (error) => {
+        if (error.code === 'EPIPE')
+            process.exit(0);
+        throw error;
+    });
+}
+const USAGE = `Usage: fg-dist <command> [options]
+
+Commands:
+  init <kind> [dir]    Scaffold a repository; kind is "distribution", "monolith" or "module"
+  add-module <url>     Add a module repository as a submodule and link it
+  extract <path>       Turn a directory here into its own repository and submodule
+  use-https [name...]  Rewrite submodule urls from ssh to https
+  readme               Record versions in the readmes; run in a distribution or a module
+  workflows [name...]  Give every module a publishing workflow and a changelog check;
+                       --distribution, this one a publishing workflow too
+  overrides            Point the workspace at this distribution's own checkouts
+  canary               Stamp a canary version into the manifest, for CI
+  release              Move a module on from the release it just published
+  prerelease           Start the next line on a branch, leaving main where it is
+  check                Fail when this ships anything older than what it extends
+  inherit              Add the modules the distribution this extends ships, and this does not
+  sync                 Report which modules have newer versions available
+  bump [name...]       Move modules to their newest non-major version; a fork merges it
+  fork <name> <url>    Check a module out from your fork, keeping where it came from
+  contribute <name>    Push the module's branch and open a pull request upstream
+  unfork <name>        Go back to the upstream a fork came from, once it has the fork's work
+  changelog check      Fail a pull request that adds no changelog line linking itself (CI)
+  changelog notes [v]  Print a version's changelog section, for its release notes
+  policy build         Build the organization's policy: policies/, on every module's own
+  policy test          Test each module's rules, then the organization's on top of them
+  policy use           Put the built policy beside this service, for it to run
+  policy setup         Have turbo build the policy once, before each service that uses it
+
+Options:
+  --cwd <dir>          Repository directory (default: the working directory)
+  --major              Allow major upgrades (bump); the next major (release, prerelease)
+  --minor              Release the next minor, or branch one (release, prerelease)
+  --patch              Release the next patch, staying on this line (release)
+  --id <name>          Prerelease identifier: alpha, beta, rc (release, prerelease)
+  --stable             A distribution's release leaves its prerelease stages (release)
+  --no-fetch           Use the refs already fetched (sync, bump)
+  --dry-run            Report what would change without changing it
+  --check              Verify instead of writing (readme, release, overrides)
+                       --dry-run does the same for workflows, readme and overrides
+  --name <name>        Package name for "init", mount name for add-module
+  --at <dir>           Where add-module puts the submodule (default: apps/<name>)
+  --no-git             Skip "git init" when scaffolding
+  --url <git-url>      Remote the scaffolded repository will live at (init)
+  --extends <name>     Distribution the scaffolded one extends (init distribution)
+  --separate           Scaffold a distribution whose apps deploy separately
+  --ssh                Record a submodule's URL as given, without rewriting it
+  --no-verify          Skip checking whether the https urls can be cloned
+  --no-tag             Do not tag the extracted module with its declared version
+  --force              Overwrite workflows that are already there (workflows)
+  --distribution       Publish the distribution itself, for others to extend (workflows)
+  --no-push            Push nothing and open no pull request (release, fork, contribute, bump)
+  --to <ref>           Upstream tag, branch or commit to go back to (unfork)
+  --base <branch>      Branch the pull request goes into (contribute); what it merges into (changelog check)
+  --pr <number>        The pull request to check, outside GitHub Actions (changelog check)
+  --repo <owner/name>  The repository its link names, outside GitHub Actions (changelog check)
+  --out <file>         Where policy build writes the bundle (default: policies/dist/)
+`;
+const parseArgs = (argv) => {
+    const args = {
+        command: undefined,
+        names: [],
+        cwd: process.cwd(),
+        check: false,
+        major: false,
+        fetch: true,
+        dryRun: false,
+        name: undefined,
+        at: undefined,
+        git: true,
+        url: undefined,
+        extends: undefined,
+        separate: false,
+        ssh: false,
+        verify: true,
+        tag: true,
+        force: false,
+        push: true,
+        bump: undefined,
+        id: undefined,
+        out: undefined,
+        to: undefined,
+        base: undefined,
+        distribution: false,
+        stable: false,
+        pr: undefined,
+        repo: undefined,
+    };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === '--cwd') {
+            args.cwd = path.resolve(argv[++index] ?? '.');
+        }
+        else if (arg === '--check') {
+            args.check = true;
+        }
+        else if (arg === '--major') {
+            args.major = true;
+            args.bump = 'major';
+        }
+        else if (arg === '--minor') {
+            args.bump = 'minor';
+        }
+        else if (arg === '--patch') {
+            args.bump = 'patch';
+        }
+        else if (arg === '--id') {
+            args.id = argv[++index];
+        }
+        else if (arg === '--no-fetch') {
+            args.fetch = false;
+        }
+        else if (arg === '--dry-run') {
+            args.dryRun = true;
+        }
+        else if (arg === '--name') {
+            args.name = argv[++index];
+        }
+        else if (arg === '--at') {
+            args.at = argv[++index];
+        }
+        else if (arg === '--no-git') {
+            args.git = false;
+        }
+        else if (arg === '--url') {
+            args.url = argv[++index];
+        }
+        else if (arg === '--extends') {
+            args.extends = argv[++index];
+        }
+        else if (arg === '--separate') {
+            args.separate = true;
+        }
+        else if (arg === '--ssh') {
+            args.ssh = true;
+        }
+        else if (arg === '--no-verify') {
+            args.verify = false;
+        }
+        else if (arg === '--no-tag') {
+            args.tag = false;
+        }
+        else if (arg === '--force') {
+            args.force = true;
+        }
+        else if (arg === '--no-push') {
+            args.push = false;
+        }
+        else if (arg === '--pr') {
+            args.pr = Number(argv[++index]);
+        }
+        else if (arg === '--repo') {
+            args.repo = argv[++index];
+        }
+        else if (arg === '--stable') {
+            args.stable = true;
+        }
+        else if (arg === '--distribution') {
+            args.distribution = true;
+        }
+        else if (arg === '--to') {
+            args.to = argv[++index];
+        }
+        else if (arg === '--base') {
+            args.base = argv[++index];
+        }
+        else if (arg === '--out') {
+            args.out = path.resolve(argv[++index] ?? '.');
+        }
+        else if (!arg.startsWith('-')) {
+            if (args.command)
+                args.names.push(arg);
+            else
+                args.command = arg;
+        }
+        else {
+            throw new Error(`Unrecognized argument: ${arg}`);
+        }
+    }
+    return args;
+};
+/** One line per module, aligned, saying what is available. */
+/**
+ * Where a fork could go back to upstream, when upstream has taken what it
+ * added: a release past the pinned one, or its branch. Not a fork that has
+ * added nothing yet, which is where every fork starts.
+ */
+const canReturn = (state) => {
+    const merged = state.fork?.merged;
+    if (!merged)
+        return undefined;
+    if (merged === state.current && state.fork?.ahead === 0)
+        return undefined;
+    return merged.replace(/^upstream\//, '');
+};
+const describeState = (state) => {
+    const { current, available, untagged, dirty } = state;
+    const parts = [];
+    const at = current ? (state.exact ? current : `${current}+`) : 'untagged';
+    parts.push(at);
+    if (available.length > 0) {
+        const kinds = ['patch', 'minor', 'major']
+            .filter((kind) => state.upgrades[kind])
+            .map((kind) => `${state.upgrades[kind]} (${kind})`);
+        parts.push(`-> ${kinds.join(', ')}`);
+    }
+    else if (current) {
+        parts.push('up to date');
+    }
+    else {
+        parts.push('no version tags');
+    }
+    if (untagged > 0)
+        parts.push(`${untagged} untagged commit${untagged === 1 ? '' : 's'}`);
+    if (state.fork) {
+        const { upstream, ahead } = state.fork;
+        const from = `fork of ${describeRemote(upstream)}`;
+        const returnTo = canReturn(state);
+        parts.push(returnTo
+            ? `${from}, all in upstream ${returnTo}`
+            : ahead === 0
+                ? `${from}, nothing of its own`
+                : `${from}, ${ahead} commit${ahead === 1 ? '' : 's'} not upstream`);
+    }
+    if (state.pushed === false)
+        parts.push('not pushed');
+    if (dirty)
+        parts.push('uncommitted changes');
+    if (state.fetched === false)
+        parts.push('could not fetch');
+    if (isSsh(state.submodule.url))
+        parts.push('ssh url');
+    return parts.join('  ');
+};
+/** Submodules of the repository holding `cwd`, optionally filtered by name. */
+const modulesFor = (cwd, names) => {
+    const root = repositoryRoot(cwd);
+    if (!root)
+        throw new Error(`${cwd} is not inside a git repository.`);
+    const all = submodules(root);
+    if (all.length === 0) {
+        throw new Error(`${root} has no submodules to sync.`);
+    }
+    if (names.length === 0)
+        return { root, modules: all };
+    const modules = all.filter((module) => names.includes(module.name) || names.includes(module.relativePath));
+    const missing = names.filter((name) => !all.some((m) => m.name === name || m.relativePath === name));
+    if (missing.length > 0) {
+        throw new Error(`No such submodule: ${missing.join(', ')}. ` +
+            `Known: ${all.map((m) => m.name).join(', ')}.`);
+    }
+    return { root, modules };
+};
+const pad = (values) => values.reduce((widest, value) => Math.max(widest, value.length), 0);
+const main = async () => {
+    const args = parseArgs(process.argv.slice(2));
+    if (!args.command || args.command === 'help') {
+        process.stdout.write(USAGE);
+        return args.command ? 0 : 1;
+    }
+    if (args.command === 'init') {
+        const [kind, where] = args.names;
+        if (kind !== 'distribution' && kind !== 'monolith' && kind !== 'module') {
+            process.stderr.write('init needs a kind: "distribution", "monolith" or "module".\n');
+            return 1;
+        }
+        const target = path.resolve(args.cwd, where ?? '.');
+        await mkdir(target, { recursive: true });
+        if (!(await isEmpty(target))) {
+            process.stderr.write(`${target} is not empty; refusing to scaffold over it.\n`);
+            return 1;
+        }
+        const name = args.name ?? path.basename(target);
+        // A module is consumed as a submodule, so record the URL it will be
+        // cloned from in the form a keyless clone can use.
+        const origin = args.url ? (args.ssh ? args.url : toHttps(args.url)) : undefined;
+        const files = kind === 'distribution'
+            ? distributionRepo(name, origin, args.extends, { monolith: !args.separate })
+            : kind === 'monolith'
+                ? monolithRepo(name, origin)
+                : moduleRepo(name, origin);
+        const written = await write(target, files);
+        if (args.git) {
+            try {
+                execFileSync('git', ['init', '--quiet'], { cwd: target, stdio: 'ignore' });
+                if (origin) {
+                    execFileSync('git', ['remote', 'add', 'origin', origin], {
+                        cwd: target,
+                        stdio: 'ignore',
+                    });
+                }
+            }
+            catch {
+                process.stderr.write('Could not run git init; scaffolding is still written.\n');
+            }
+        }
+        for (const file of written)
+            process.stdout.write(`  ${file}\n`);
+        process.stdout.write(`\n${kind} scaffolded in ${target}.\n`);
+        if (origin) {
+            process.stdout.write(`origin is ${origin}\n`);
+            if (args.url && origin !== args.url) {
+                process.stdout.write(`(rewritten from ${args.url}; a submodule is cloned without an SSH key)\n`);
+            }
+        }
+        else {
+            process.stdout.write('No remote set. Pass --url so a monolith can add this as a submodule.\n');
+        }
+        process.stdout.write(kind === 'module'
+            ? 'Next: pnpm install, then commit and push so a distribution can add it.\n'
+            : args.extends && kind === 'distribution'
+                ? `Next: pnpm install, then \`fg-dist inherit\` to ship what ${args.extends} ships.\n`
+                : 'Next: pnpm install, then `fg-dist add-module <url>` to ship a module.\n');
+        return 0;
+    }
+    if (args.command === 'add-module') {
+        const [url] = args.names;
+        if (!url) {
+            process.stderr.write('add-module needs a repository url.\n');
+            return 1;
+        }
+        const result = await addModule(args.cwd, url, {
+            at: args.at,
+            mount: args.name,
+            ssh: args.ssh,
+        });
+        process.stdout.write(`Added ${result.relativePath} from ${result.url}\n`);
+        if (result.packageName && result.version) {
+            process.stdout.write(`Shipping ${result.packageName}@${result.version}, as the checkout declares it\n`);
+        }
+        if (result.rewritten) {
+            process.stdout.write(`(rewritten from ${url}; a submodule is cloned without an SSH key)\n`);
+        }
+        else if (args.ssh && isSsh(result.url)) {
+            process.stdout.write(`(recorded as SSH, so only clones with a key for ${describeRemote(result.url)} can build this)\n`);
+        }
+        if (result.linked && result.monolithPackageJson) {
+            process.stdout.write(`Linked through the workspace in ` +
+                `${path.relative(args.cwd, result.monolithPackageJson)}\n`);
+        }
+        else if (!result.packageName) {
+            process.stdout.write('It has no package.json, so nothing was linked.\n');
+        }
+        if (result.overrides) {
+            process.stdout.write('Workspace overrides updated, so this resolves from the tree rather than npm\n');
+        }
+        else if (result.overridesError) {
+            process.stderr.write(`\nThe module is added, but the workspace overrides were not updated:\n` +
+                `  ${result.overridesError}\n` +
+                'Run `fg-dist overrides` once that is sorted.\n');
+        }
+        if (result.mounted && result.monolithConfig) {
+            process.stdout.write(`Mounted at /${result.mount} in ${path.relative(args.cwd, result.monolithConfig)}\n`);
+        }
+        else if (result.mountError && result.monolithPackageJson) {
+            process.stderr.write(`\nCould not mount it: ${result.mountError}\n` +
+                `Add this to the monolith's Next config yourself:\n` +
+                `    ${result.mount}: '${result.packageName ?? result.relativePath}',\n`);
+        }
+        else if (!result.isApp) {
+            // A package is shared by the apps, not served at a path of its own.
+            process.stdout.write('It has no routes, so it is a package the apps depend on rather than one to mount.\n');
+        }
+        else if (!result.monolithPackageJson) {
+            // A distribution too complex to serve from one deployment has no
+            // monolith; each app under apps/ is deployed on its own.
+            process.stdout.write('No monolith app here, so it is shipped but not mounted. Deploy it on its own.\n');
+        }
+        else if (result.monolithConfig) {
+            process.stdout.write(`Already mounted at /${result.mount}.\n`);
+        }
+        if (result.turbo) {
+            process.stdout.write("turbo.json: the monolith's build waits for its libraries, not its own build\n");
+        }
+        process.stdout.write(result.monolithPackageJson
+            ? '\nRun pnpm install and `fg-monolith merge-package-json`.\n'
+            : '\nRun pnpm install.\n');
+        return 0;
+    }
+    if (args.command === 'readme') {
+        const root = repositoryRoot(args.cwd);
+        if (!root)
+            throw new Error(`${args.cwd} is not inside a git repository.`);
+        const { updates, modules, kind } = await writeReadmes(root, {
+            check: args.check || args.dryRun,
+        });
+        const changed = updates.filter((update) => update.changed);
+        for (const module of modules) {
+            process.stdout.write(`${module.relativePath}  ${module.name}@${module.version}\n`);
+        }
+        if (changed.length === 0) {
+            process.stdout.write(kind === 'module'
+                ? 'This module\'s readme already states its version.\n'
+                : '\nEvery readme already states its version.\n');
+            return 0;
+        }
+        if (args.check) {
+            process.stderr.write(`\n${changed.length} readme(s) are out of date:\n${changed
+                .map((update) => `  ${path.relative(root, update.file)}`)
+                .join('\n')}\nRun \`fg-dist readme\` to update them.\n`);
+            return 1;
+        }
+        process.stdout.write(`\nUpdated:\n${changed
+            .map((update) => `  ${path.relative(root, update.file)}`)
+            .join('\n')}\n`);
+        return 0;
+    }
+    if (args.command === 'workflows') {
+        const root = repositoryRoot(args.cwd);
+        if (!root)
+            throw new Error(`${args.cwd} is not inside a git repository.`);
+        if (args.distribution) {
+            const update = await writeDistributionWorkflow(root, { force: args.force, dryRun: args.dryRun });
+            if (update.skipped) {
+                process.stdout.write('The distribution has a publishing workflow already. Pass --force to overwrite it.\n');
+                return 0;
+            }
+            process.stdout.write(`${update.files.join(', ')}\n`);
+            if (update.unprivated) {
+                process.stdout.write('\nTook "private": true off package.json — a private package cannot publish.\n');
+            }
+            if (update.missingAccess) {
+                process.stdout.write('Nothing says whether it publishes publicly. For others to extend it, add\n' +
+                    '  "publishConfig": { "access": "public" }\n');
+            }
+            process.stdout.write('\nIt publishes the manifest, recording every module it ships, and its policy. ' +
+                'Version it with `fg-dist release`, then run the workflow.\n');
+            return 0;
+        }
+        const updates = await writeWorkflows(root, {
+            force: args.force,
+            dryRun: args.dryRun,
+            names: args.names,
+        });
+        // The distribution checks its own changelog too, for policy changes —
+        // unless only some modules were named.
+        if (isDistribution(root) && args.names.length === 0) {
+            updates.push(await writeDistributionChangelogCheck(root, { force: args.force, dryRun: args.dryRun }));
+        }
+        if (updates.length === 0) {
+            process.stdout.write('No modules here. Run this in a distribution, which is where the modules are.\n');
+            return 0;
+        }
+        const written = updates.filter((update) => !update.skipped);
+        for (const update of updates) {
+            process.stdout.write(update.skipped
+                ? `${update.relativePath}  has one already\n`
+                : `${update.relativePath}  ${update.files.join(', ')}\n`);
+        }
+        if (written.length === 0) {
+            process.stdout.write('\nEvery module already publishes. Pass --force to overwrite the workflows.\n');
+            return 0;
+        }
+        const unprivated = written.filter((update) => update.unprivated);
+        const missingFiles = written.filter((update) => update.missingFiles);
+        if (args.dryRun) {
+            process.stdout.write(`\n${written.length} module(s) would be written. Nothing changed.\n`);
+            return 0;
+        }
+        if (unprivated.length > 0) {
+            process.stdout.write(`\nTook "private": true off ${unprivated.map((u) => u.relativePath).join(', ')} — ` +
+                'a private package cannot publish.\n');
+        }
+        const missingAccess = written.filter((update) => update.missingAccess);
+        if (missingAccess.length > 0) {
+            process.stdout.write(`\nNo "publishConfig.access" in ${missingAccess.map((u) => u.relativePath).join(', ')}.\n` +
+                'Not set here, because npm treats an explicit value as an instruction to\n' +
+                'change an existing package\'s visibility. Say which it is yourself:\n' +
+                '  "publishConfig": { "access": "public" }      — and provenance is generated\n' +
+                '  "publishConfig": { "access": "restricted" }  — and it is not\n');
+        }
+        if (missingFiles.length > 0) {
+            process.stdout.write(`\nNo "files" list in ${missingFiles.map((u) => u.relativePath).join(', ')}.\n` +
+                'npm will ship whatever is in the directory. Say what belongs in the tarball:\n' +
+                '  a module consumed as source ships "app", "lib", "public";\n' +
+                '  one that builds ships "dist".\n');
+        }
+        process.stdout.write(`\nWrote a workflow into ${written.length} module(s).\n` +
+            'Each one is a separate repository, so commit and push them individually.\n' +
+            'npm trusted publishing has to be configured per package before the first run:\n' +
+            '  publish once from a workstation, then point the trusted publisher at\n' +
+            '  .github/workflows/publish.yml in that module\'s repository.\n');
+        return 0;
+    }
+    if (args.command === 'overrides') {
+        const root = repositoryRoot(args.cwd);
+        if (!root)
+            throw new Error(`${args.cwd} is not inside a git repository.`);
+        const { file, names, changed, missing } = await writeOverrides(root, {
+            check: args.check || args.dryRun,
+        });
+        if (missing) {
+            process.stderr.write(`There is no ${path.relative(root, file) || 'pnpm-workspace.yaml'} here. ` +
+                'A distribution needs one before its modules can be overridden.\n');
+            return 1;
+        }
+        if (names.length === 0) {
+            process.stdout.write('No modules here. Run this in a distribution, which is what does the overriding.\n');
+            return 0;
+        }
+        for (const name of names)
+            process.stdout.write(`  ${name}\n`);
+        if (!changed) {
+            process.stdout.write(`\n${path.relative(root, file)} already covers every module.\n`);
+            return 0;
+        }
+        if (args.dryRun) {
+            process.stdout.write(`\n${path.relative(root, file)} would be updated.\n`);
+            return 0;
+        }
+        if (args.check) {
+            process.stderr.write(`\n${path.relative(root, file)} does not match the modules here.\n` +
+                'Run `fg-dist overrides` to update it.\n');
+            return 1;
+        }
+        process.stdout.write(`\nUpdated ${path.relative(root, file)}. Run \`pnpm install\` to take it up.\n`);
+        return 0;
+    }
+    if (args.command === 'canary') {
+        const root = repositoryRoot(args.cwd) ?? args.cwd;
+        const result = await stampCanary(root, { dryRun: args.dryRun });
+        await reportCanary(result);
+        process.stdout.write(result.skip
+            ? `${result.name}@${result.version} is already the canary for ${result.sha}.\n`
+            : `${args.dryRun ? 'Would stamp' : 'Stamped'} ${result.name}@${result.version}\n`);
+        return 0;
+    }
+    if (args.command === 'release') {
+        const root = repositoryRoot(args.cwd);
+        if (!root)
+            throw new Error(`${args.cwd} is not inside a git repository.`);
+        if (args.check) {
+            const releasable = await checkReleasable(root);
+            // A distribution records what it ships in what it publishes.
+            if (isDistribution(root))
+                await stampModules(root, { version: releasable.version });
+            await reportRelease(releasable);
+            process.stdout.write(`${releasable.name}@${releasable.version} is not on npm; ready to release as ` +
+                `${releasable.tag}.\n`);
+            return 0;
+        }
+        if (isDistribution(root)) {
+            if (args.bump) {
+                process.stderr.write("A distribution's version is its month and its release: move it with " +
+                    '--id <alpha|beta|rc> or --stable, or neither to carry on as it is.\n');
+                return 1;
+            }
+            const next = await releaseDistribution(root, {
+                dryRun: args.dryRun,
+                id: args.id,
+                stable: args.stable,
+            });
+            const verb = args.dryRun ? 'Would move' : 'Moved';
+            process.stdout.write(next.version === next.from
+                ? `${next.name} ${next.from} is not published yet; it is what the publish workflow releases next.\n`
+                : `${next.published ? `${next.from} is published. ` : `${next.from} was never published. `}` +
+                    `${verb} ${next.name} to ${next.version}.\n`);
+            if (!args.dryRun && next.version !== next.from) {
+                process.stdout.write(`Commit it, then run the publish workflow, which publishes it and tags v${next.version}.\n`);
+            }
+            return 0;
+        }
+        // Which way main moves on is a judgement about what changed, so it is asked
+        // for rather than guessed at. Showing all three is the cheapest way to ask.
+        if (!args.bump) {
+            const { released, tagged, base } = await readRelease(root, { bump: 'minor' });
+            if (!released.includes('-')) {
+                process.stdout.write(`Released ${released}, ${tagged ? `tagged ${base}` : 'which is not tagged here'}\n\n` +
+                    'Which way does main move on?\n\n');
+                for (const bump of ['patch', 'minor', 'major']) {
+                    const plan = planRelease(released, { bump });
+                    process.stdout.write(`  --${bump.padEnd(6)} ${plan.next.version.padEnd(8)} ` +
+                        (plan.maintenance
+                            ? `${plan.maintenance.branch} keeps ${released.split('.').slice(0, 2).join('.')}.x\n`
+                            : 'stays on this line; nothing branches off\n'));
+                }
+                process.stdout.write(`\nOr \`fg-dist prerelease --major\` to start the next line beside main, ` +
+                    'without\nmoving main off this one.\n');
+                return 1;
+            }
+        }
+        const outcome = await release(root, {
+            bump: args.bump,
+            id: args.id,
+            dryRun: args.dryRun,
+            push: args.push,
+        });
+        const { plan } = outcome;
+        process.stdout.write(`Released ${plan.released}, ` +
+            `${plan.tagged ? `tagged ${plan.base}` : 'which is not tagged here'}\n\n`);
+        const width = pad([plan.maintenance?.branch ?? '', plan.next.branch]);
+        if (plan.maintenance) {
+            process.stdout.write(`  ${plan.maintenance.branch.padEnd(width)}  ${plan.maintenance.version}  ` +
+                `cut from ${plan.base}, where ${plan.released} is maintained\n`);
+        }
+        process.stdout.write(`  ${plan.next.branch.padEnd(width)}  ${plan.next.version}  ` +
+            `opened against ${outcome.base}\n`);
+        if (args.dryRun) {
+            process.stdout.write('\nNothing written. Drop --dry-run to do it.\n');
+            return 0;
+        }
+        // Only worth saying when something was cut from the tag. A prerelease has
+        // no maintenance branch, so there is nothing the missing tag affected.
+        if (!plan.tagged && plan.maintenance) {
+            process.stdout.write(`\nThere is no v${plan.released} tag here, so ${plan.maintenance.branch} was cut ` +
+                `from HEAD.\nIf the release workflow has not run yet, run it first: the tag is ` +
+                `what\nseparates the released commit from whatever ${outcome.base} has done since.\n`);
+        }
+        if (!outcome.pushed) {
+            process.stdout.write('\nLeft local. Push them and open the pull request yourself.\n');
+            return 0;
+        }
+        process.stdout.write(outcome.pullRequest
+            ? `\n${outcome.pullRequest}\n`
+            : '\nPushed. `gh` is not here, so open the pull request yourself.\n');
+        return 0;
+    }
+    if (args.command === 'prerelease') {
+        const root = repositoryRoot(args.cwd);
+        if (!root)
+            throw new Error(`${args.cwd} is not inside a git repository.`);
+        if (args.bump !== 'major' && args.bump !== 'minor') {
+            process.stderr.write('prerelease needs --major or --minor: which line is being started.\n');
+            return 1;
+        }
+        const { plan, created, pushed } = await startPrerelease(root, {
+            bump: args.bump,
+            id: args.id,
+            dryRun: args.dryRun,
+            push: args.push,
+        });
+        process.stdout.write(`  ${plan.branch}  ${plan.version}  cut from ${plan.from}, which main keeps\n`);
+        if (args.dryRun) {
+            process.stdout.write('\nNothing written. Drop --dry-run to do it.\n');
+            return 0;
+        }
+        if (!created)
+            return 1;
+        process.stdout.write(pushed
+            ? `\nPushed. Release from it with a dist tag of its own — \`next\`, say — so\n` +
+                '`latest` goes on meaning the line main is shipping.\n'
+            : '\nLeft local. Push it when you are ready.\n');
+        return 0;
+    }
+    if (args.command === 'policy') {
+        const [action] = args.names;
+        if (action === 'use') {
+            const { policy, status } = usePolicy(args.cwd);
+            process.stdout.write(policy
+                ? status === 0
+                    ? `Using ${path.relative(args.cwd, policy.built) || policy.built}.\n`
+                    : ''
+                : 'No organization policy here: the built-in rules decide.\n');
+            return status;
+        }
+        const policy = findPolicy(args.cwd);
+        if (!policy) {
+            process.stderr.write(`There is no organization policy here: no ${POLICIES}/.manifest above ${args.cwd}.\n`);
+            return 1;
+        }
+        if (action === 'build')
+            return buildPolicy(policy, args.cwd, args.out);
+        if (action === 'test')
+            return testPolicy(policy, args.cwd);
+        if (action === 'setup') {
+            const differ = setupTurbo(policy, { check: args.check });
+            if (differ.length === 0) {
+                process.stdout.write('turbo.json builds the policy once, before each service that uses it.\n');
+                return 0;
+            }
+            process.stdout.write(`${args.check ? 'turbo.json is missing' : 'Wrote'} ${differ.join(', ')}${args.check ? '; run fg-dist policy setup.' : ' into turbo.json.'}\n`);
+            return args.check ? 1 : 0;
+        }
+        process.stderr.write('Usage: fg-dist policy <build|test|use|setup>\n');
+        return 1;
+    }
+    if (args.command === 'check') {
+        const root = repositoryRoot(args.cwd);
+        if (!root)
+            throw new Error(`${args.cwd} is not inside a git repository.`);
+        const report = inspectExtends(root);
+        if (!report.distribution.extends) {
+            process.stdout.write(`${report.distribution.name} extends nothing, so there is no floor to check.\n`);
+            return 0;
+        }
+        if (report.unresolved) {
+            process.stderr.write(`${report.distribution.name} extends ${report.unresolved}, which is not ` +
+                'installed, so nothing could be compared against it.\n');
+            return 1;
+        }
+        if (report.violations.length > 0) {
+            process.stderr.write(`${describeViolations(report)}\n`);
+            return 1;
+        }
+        process.stdout.write(`${report.distribution.name}@${report.distribution.version} ships nothing older ` +
+            `than ${report.parent?.name}@${report.parent?.version}.\n`);
+        return 0;
+    }
+    if (args.command === 'extract') {
+        const [target] = args.names;
+        if (!target) {
+            process.stderr.write('extract needs the directory to turn into a module.\n');
+            return 1;
+        }
+        if (!args.url) {
+            process.stderr.write('extract needs --url, the repository the module will live at.\n');
+            return 1;
+        }
+        const result = await extractModule(args.cwd, target, {
+            url: args.url,
+            ssh: args.ssh,
+            tag: args.tag,
+        });
+        process.stdout.write(`${result.relativePath} is now ${result.initialised ? 'a repository' : 'its own repository'}` +
+            ` and a submodule of this one\n`);
+        if (result.packageName && result.version) {
+            process.stdout.write(`Shipping ${result.packageName}@${result.version}\n`);
+        }
+        if (result.tagged) {
+            process.stdout.write(`Tagged ${result.tagged}, so sync can track it\n` +
+                `  That tag is what the first release would have created, so release it\n` +
+                `  with the next version rather than this one — or \`--no-tag\` next time.\n`);
+        }
+        if (result.overridesError) {
+            process.stderr.write(`\nThe module is extracted, but the workspace overrides were not updated:\n` +
+                `  ${result.overridesError}\n` +
+                'Run `fg-dist overrides` once that is sorted.\n');
+        }
+        process.stdout.write(`origin is ${result.url}\n`);
+        if (result.rewritten) {
+            process.stdout.write(`(rewritten from ${args.url}; a submodule is cloned without an SSH key)\n`);
+        }
+        // Nothing was pushed: the submodule points at a remote that may not exist
+        // yet, which is fine here and fatal on anyone else's clone.
+        process.stdout.write(`\nPush it before anyone else clones this:\n` +
+            `    git -C ${result.relativePath} push -u origin main --tags\n` +
+            'Then commit the new submodule here.\n');
+        return 0;
+    }
+    if (args.command === 'use-https') {
+        const { root, modules } = modulesFor(args.cwd, args.names);
+        const ssh = modules.filter((module) => isSsh(module.url));
+        if (ssh.length === 0) {
+            process.stdout.write('Every submodule url is already https.\n');
+            return 0;
+        }
+        for (const module of ssh) {
+            const https = toHttps(module.url);
+            if (https === module.url) {
+                process.stderr.write(`${module.relativePath}  no https form for ${module.url}\n`);
+                continue;
+            }
+            if (!args.dryRun)
+                setUrl(root, module, https);
+            process.stdout.write(`${module.relativePath}  ${module.url} -> ${https}\n`);
+        }
+        if (args.dryRun) {
+            process.stdout.write('\nDry run; .gitmodules was not changed.\n');
+            return 0;
+        }
+        process.stdout.write('\n.gitmodules updated. Commit it to record the new urls.\n');
+        // https is necessary but not sufficient: a keyless clone also needs the
+        // repository to be readable without credentials.
+        if (!args.verify)
+            return 0;
+        process.stdout.write('\nChecking whether each can be cloned without credentials:\n');
+        const privateOnes = [];
+        for (const module of ssh) {
+            const https = toHttps(module.url);
+            const reachable = isPublic(https);
+            if (!reachable)
+                privateOnes.push(module.relativePath);
+            process.stdout.write(`  ${module.relativePath}  ${reachable ? 'public' : 'not readable'}\n`);
+        }
+        if (privateOnes.length > 0) {
+            process.stdout.write(`\n${privateOnes.length} of these cannot be read anonymously, so a build ` +
+                'host still cannot clone them. Make them public, or expect the build to fail.\n');
+            return 1;
+        }
+        process.stdout.write('\nAll readable anonymously.\n');
+        return 0;
+    }
+    if (args.command === 'sync') {
+        const { root, modules } = modulesFor(args.cwd, args.names);
+        const states = modules.map((module) => inspect(module, { fetch: args.fetch }));
+        const width = pad(states.map((state) => state.submodule.relativePath));
+        for (const state of states) {
+            process.stdout.write(`${state.submodule.relativePath.padEnd(width)}  ${describeState(state)}\n`);
+        }
+        // .gitmodules is committed, so an SSH URL is what a build host will try.
+        const ssh = states.filter((state) => isSsh(state.submodule.url));
+        if (ssh.length > 0) {
+            process.stdout.write(`\n${ssh.length} module(s) are recorded with an ssh url, which a clone ` +
+                'without a key cannot use:\n');
+            for (const state of ssh) {
+                process.stdout.write(`  ${state.submodule.relativePath}  ${state.submodule.url}` +
+                    `  ->  ${toHttps(state.submodule.url)}\n`);
+            }
+            process.stdout.write('Run `fg-dist use-https` to rewrite them. They also have to be ' +
+                'readable without credentials, which means public.\n');
+        }
+        // A pin the remote does not have breaks every other clone, a build host's first.
+        const unpushed = states.filter((state) => state.pushed === false);
+        if (unpushed.length > 0) {
+            process.stdout.write(`\n${unpushed.length} module(s) are pinned at a commit their remote does not have, ` +
+                'so no other clone can check them out:\n');
+            for (const state of unpushed) {
+                process.stdout.write(`  ${state.submodule.relativePath}  ${state.head.slice(0, 7)}\n`);
+            }
+            process.stdout.write('Push them — `fg-dist contribute <name>` does, for a change on its way upstream.\n');
+        }
+        // A fork whose work upstream has taken can go back to upstream.
+        const returnable = states.filter((state) => canReturn(state));
+        if (returnable.length > 0) {
+            process.stdout.write('\nUpstream has everything these forks add:\n');
+            for (const state of returnable) {
+                process.stdout.write(`  ${state.submodule.relativePath}  in ${canReturn(state)}\n`);
+            }
+            process.stdout.write('Keep them, or `fg-dist unfork <name>` to go back to upstream.\n');
+        }
+        // An extension may move ahead of what it extends, never behind it.
+        const extendsReport = inspectExtends(root);
+        if (extendsReport.violations.length > 0) {
+            process.stdout.write(`\n${describeViolations(extendsReport)}\n`);
+        }
+        else if (extendsReport.unresolved) {
+            process.stdout.write(`\nThis extends ${extendsReport.unresolved}, which is not installed, ` +
+                'so nothing could be compared against it.\n');
+        }
+        else if (extendsReport.parent) {
+            process.stdout.write(`\nUp to date with ${extendsReport.parent.name}@${extendsReport.parent.version}, ` +
+                'which it extends.\n');
+        }
+        const upgradable = states.filter((state) => target(state, { major: true }));
+        const untagged = states.filter((state) => state.current === undefined);
+        if (upgradable.length === 0) {
+            process.stdout.write(untagged.length === states.length
+                ? '\nNo module carries a version tag, so there is nothing to compare. ' +
+                    'Tag a release in each module to track it here.\n'
+                : '\nEverything is on its newest version.\n');
+            if (untagged.length > 0 && untagged.length < states.length) {
+                process.stdout.write(`${untagged.length} module(s) carry no version tag and were not compared.\n`);
+            }
+            return 0;
+        }
+        // A major is only held back when it is newer than the non-major target.
+        const held = upgradable.filter((state) => state.upgrades.major !== undefined);
+        process.stdout.write(`\n${upgradable.length} module(s) have newer versions. `);
+        process.stdout.write('Run `fg-dist bump` to take them');
+        process.stdout.write(held.length > 0
+            ? `, or \`fg-dist bump --major\` to include the ${held.length} major upgrade(s).\n`
+            : '.\n');
+        return 0;
+    }
+    if (args.command === 'bump') {
+        const { root, modules } = modulesFor(args.cwd, args.names);
+        const states = modules.map((module) => inspect(module, { fetch: args.fetch }));
+        const moves = states
+            .map((state) => ({ state, to: target(state, { major: args.major }) }))
+            .filter((move) => move.to !== undefined);
+        if (moves.length === 0) {
+            process.stdout.write('Nothing to bump.\n');
+            const held = states.filter((state) => target(state, { major: true }));
+            if (held.length > 0 && !args.major) {
+                process.stdout.write(`${held.length} module(s) have a major upgrade available; pass --major to take it.\n`);
+            }
+            return 0;
+        }
+        // Moving a dirty submodule would fail mid-checkout or discard work.
+        const dirty = moves.filter((move) => move.state.dirty);
+        if (dirty.length > 0) {
+            process.stderr.write(`Refusing to bump, these have uncommitted changes:\n${dirty
+                .map((move) => `  ${move.state.submodule.relativePath}`)
+                .join('\n')}\n`);
+            return 1;
+        }
+        let failed = 0;
+        for (const { state, to } of moves) {
+            const from = state.current ?? state.head.slice(0, 7);
+            const line = `${state.submodule.relativePath}  ${from} -> ${to}`;
+            if (args.dryRun) {
+                const how = !state.fork
+                    ? ''
+                    : containsAll(state.submodule.path, `refs/tags/${to}`, state.head)
+                        ? '  (fork: upstream has all of it; would move to it)'
+                        : '  (fork: would merge it in)';
+                process.stdout.write(`${line}${how}\n`);
+                continue;
+            }
+            if (!state.fork) {
+                moveTo(state.submodule, to);
+                noteInDistribution(root, bumpEntry(moduleLabel(state.submodule.path).name, from, to, state.submodule.url, crossedReleases(state.available, to)));
+                process.stdout.write(`${line}\n`);
+                continue;
+            }
+            // A fork takes upstream's release by merging it, keeping its own work on top.
+            try {
+                const done = integrate(root, state, to, { push: args.push });
+                process.stdout.write(done.how === 'moved'
+                    ? `${line}  (fork: upstream has all of it; \`fg-dist unfork ${state.submodule.name}\` goes back)\n`
+                    : `${line}  (fork: merged${done.pushed ? `, pushed to ${done.pushed}` : ', not pushed'})\n`);
+            }
+            catch (error) {
+                failed += 1;
+                process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+            }
+        }
+        process.stdout.write(args.dryRun
+            ? '\nDry run; nothing moved.\n'
+            : '\nSubmodule pointers moved. Commit them to record the new versions.\n');
+        return failed > 0 ? 1 : 0;
+    }
+    if (args.command === 'inherit') {
+        const root = repositoryRoot(args.cwd);
+        if (!root)
+            throw new Error(`${args.cwd} is not inside a git repository.`);
+        const result = await inherit(root, { dryRun: args.dryRun });
+        const width = pad(result.added.map((module) => module.path));
+        for (const module of result.added) {
+            process.stdout.write(`${module.path.padEnd(width)}  ${module.name} ${module.version} at ${module.commit.slice(0, 7)}, ` +
+                `from ${describeRemote(module.repository)}` +
+                `${module.upstream ? ` (a fork of ${describeRemote(module.upstream)})` : ''}\n`);
+        }
+        for (const module of result.blocked) {
+            process.stderr.write(`${module.path} has something in it already, so ${module.name} was not added there.\n`);
+        }
+        if (result.added.length === 0 && result.blocked.length === 0) {
+            process.stdout.write(`Ships everything ${result.parent}@${result.parentVersion} ships already.\n`);
+            return 0;
+        }
+        process.stdout.write(args.dryRun
+            ? '\nDry run; nothing added.\n'
+            : `\nShips what ${result.parent}@${result.parentVersion} ships. Run pnpm install, then commit.\n`);
+        return result.blocked.length > 0 ? 1 : 0;
+    }
+    if (args.command === 'changelog') {
+        const [action, version] = args.names;
+        const root = repositoryRoot(args.cwd) ?? args.cwd;
+        if (action === 'check') {
+            const actions = pullRequestFromActions();
+            const pullRequest = args.pr ?? actions.pullRequest;
+            const base = args.base ?? actions.base;
+            const repository = args.repo ?? actions.repository;
+            if (!pullRequest || !base || !repository) {
+                process.stderr.write('changelog check runs on a pull request: in GitHub Actions, or given ' +
+                    '--pr <number> --base <ref> --repo <owner/name>.\n');
+                return 1;
+            }
+            const result = checkChangelog(root, {
+                pullRequest,
+                base,
+                repository,
+                distribution: isDistribution(root),
+                labels: actions.labels,
+                server: actions.server,
+            });
+            (result.ok ? process.stdout : process.stderr).write(`${result.message}\n`);
+            return result.ok ? 0 : 1;
+        }
+        if (action === 'notes') {
+            const wanted = version ?? JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8')).version;
+            const text = await readFile(path.join(root, CHANGELOG), 'utf8').catch(() => '');
+            const notes = notesFor(text, wanted);
+            if (!notes) {
+                process.stderr.write(`${CHANGELOG} says nothing for ${wanted}.\n`);
+                return 1;
+            }
+            process.stdout.write(notes);
+            return 0;
+        }
+        process.stderr.write('changelog needs `check` or `notes`.\n');
+        return 1;
+    }
+    if (args.command === 'fork') {
+        const [name, url] = args.names;
+        if (!name || !url) {
+            process.stderr.write('fork needs a module and the url of your fork: fg-dist fork <name> <url>\n');
+            return 1;
+        }
+        const { root, modules } = modulesFor(args.cwd, [name]);
+        const result = forkModule(root, modules[0], url, { ssh: args.ssh, push: args.push });
+        process.stdout.write(`${modules[0].relativePath} is checked out from ${result.url}\n` +
+            `forked from ${result.upstream}, which .gitmodules records as its upstream\n`);
+        if (result.rewritten) {
+            process.stdout.write(`(rewritten from ${url}; a submodule is cloned without an SSH key)\n`);
+        }
+        process.stdout.write(result.branch
+            ? `Pinned commit pushed to ${result.branch}, where everything this distribution pins in the fork lives.\n`
+            : 'Nothing pushed. The pinned commit has to be on the fork before anyone else can check it out.\n');
+        process.stdout.write(`\nNext: make the change on a branch in ${modules[0].relativePath}, then ` +
+            `\`fg-dist contribute ${modules[0].name}\`.\nCommit .gitmodules and ${modules[0].relativePath} here.\n`);
+        return 0;
+    }
+    if (args.command === 'contribute') {
+        const [name] = args.names;
+        if (!name) {
+            process.stderr.write('contribute needs a module: fg-dist contribute <name>\n');
+            return 1;
+        }
+        const { root, modules } = modulesFor(args.cwd, [name]);
+        const result = contribute(root, modules[0], { push: args.push, base: args.base });
+        if (!args.push) {
+            process.stdout.write(`Would push ${result.branch} and open a pull request into ${describeRemote(result.repository)} ${result.base}.\n`);
+            return 0;
+        }
+        process.stdout.write(`Pushed ${result.branch}.\n`);
+        if (result.pinnedOn)
+            process.stdout.write(`Pinned commit kept on ${result.pinnedOn}, which outlives the pull request's branch.\n`);
+        if (result.pullRequest) {
+            process.stdout.write(`Opened ${result.pullRequest}\n`);
+        }
+        else if (result.compare) {
+            process.stdout.write(`Open the pull request at\n  ${result.compare}\n`);
+        }
+        else {
+            process.stdout.write(`Open a pull request from ${result.branch} into ${result.base} on ${describeRemote(result.repository)}.\n`);
+        }
+        if (result.changelog) {
+            process.stdout.write(`\nIts changelog check wants a line in ${result.changelog.file}, under ${result.changelog.version}. ` +
+                'The words are yours:\n' +
+                `  ${result.changelog.line}\n` +
+                'Commit it on the branch and push, then run this again to keep the pin current.\n');
+        }
+        process.stdout.write(`\nCommit ${modules[0].relativePath} here to ship the change meanwhile.\n`);
+        return 0;
+    }
+    if (args.command === 'unfork') {
+        const [name] = args.names;
+        if (!name) {
+            process.stderr.write('unfork needs a module: fg-dist unfork <name>\n');
+            return 1;
+        }
+        const { root, modules } = modulesFor(args.cwd, [name]);
+        const state = inspect(modules[0], { fetch: args.fetch });
+        const result = unforkModule(root, state, { to: args.to, major: args.major, force: args.force });
+        process.stdout.write(`${modules[0].relativePath} is checked out from ${result.url} again, at ${result.to}.\n` +
+            `Commit .gitmodules and ${modules[0].relativePath} here. The fork itself is left as it is.\n`);
+        return 0;
+    }
+    process.stderr.write(`Unknown command: ${args.command}\n\n${USAGE}`);
+    return 1;
+};
+main().then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=cli.js.map