@tallyrelease/cli 0.1.1 → 0.2.0-beta.7

package/dist/commands/shadow.js

@@ -0,0 +1,214 @@
+import { computePlan, TallyError } from "@tallyrelease/core";
+import { appendFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { alignColumns } from "../output/columns.js";
+import { count } from "../output/count.js";
+import { branchName } from "../session.js";
+import { compareShadow } from "../shadow/compare.js";
+import { version } from "../version.js";
+const CAP_ERRORS = new Set(["E_CAP", "E_CAP_BASE"]);
+const short = (sha) => sha?.slice(0, 7) ?? "-";
+const MANIFEST = ".release-please-manifest.json";
+const RP_CONFIG = "release-please-config.json";
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Parsed JSON object; `{}` when the file is absent. */
+const readJson = (content, path, strings = false) => {
+    if (content === undefined) {
+        return {};
+    }
+    let value;
+    try {
+        value = JSON.parse(content);
+    }
+    catch (error) {
+        throw new TallyError("E_SHADOW_INPUT", `cannot parse "${path}": ${error instanceof Error ? error.message : String(error)}`, { path });
+    }
+    if (!isObject(value) ||
+        (strings && Object.values(value).some((v) => typeof v !== "string"))) {
+        throw new TallyError("E_SHADOW_INPUT", `"${path}" must be a JSON object${strings ? " of version strings" : ""}`, { path });
+    }
+    return value;
+};
+const readManifest = (content, path) => readJson(content, path, true);
+// Workflow command data escaping.
+const escapeData = (value) => value.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+/** Full messages of the commits since each changed unit's base tag. */
+const commitMessages = async (git, plan, paths) => {
+    const messages = new Map();
+    const tags = new Set(plan.units.filter((u) => paths.has(u.path)).map((u) => u.baseTag));
+    for (const tag of tags) {
+        // eslint-disable-next-line no-await-in-loop -- one log per base tag
+        const from = tag === null ? null : ((await git.resolve(tag)) ?? null);
+        // eslint-disable-next-line no-await-in-loop -- one log per base tag
+        for (const c of await git.log(from, plan.head)) {
+            messages.set(c.sha, c.message);
+        }
+    }
+    return messages;
+};
+const unlabelled = (rows) => rows.filter((r) => r.status !== "match" && r.labels.length === 0);
+const text = (report) => {
+    const header = `shadow  ${short(report.head)} (planned ${short(report.planned)}, branch ${report.branch})`;
+    if (report.skipped) {
+        return `${header}\nskipped (${report.skipped.reason}): ${report.skipped.message}\n`;
+    }
+    const table = alignColumns([
+        ["PATH", "UNIT", "STATUS", "BEFORE", "AFTER", "NEXT", "LABELS"],
+        ...report.rows.map((r) => [
+            r.path,
+            r.unit ?? "-",
+            r.status,
+            r.before ?? "-",
+            r.after ?? "-",
+            r.next ?? "-",
+            r.labels.join(",") || "-",
+        ]),
+    ]);
+    const matched = report.rows.filter((r) => r.status === "match").length;
+    return `${[
+        header,
+        "",
+        ...table,
+        "",
+        `${count(report.rows.length, "row")}: ${String(matched)} match, ${String(unlabelled(report.rows).length)} unlabelled`,
+    ].join("\n")}\n`;
+};
+const markdown = (report) => {
+    const pin = report.pin === null ? "" : `, pin \`${report.pin}\``;
+    const lines = [
+        "### tallyrelease shadow",
+        "",
+        `Head \`${short(report.head)}\`, planned \`${short(report.planned)}\` on \`${report.branch}\`${pin}.`,
+        "",
+    ];
+    if (report.skipped) {
+        lines.push(`Skipped (${report.skipped.reason}): ${report.skipped.message}`);
+    }
+    else {
+        lines.push("| Path | Unit | Status | Before | release-please | tallyrelease | Labels |", "| :-- | :-- | :-- | :-- | :-- | :-- | :-- |", ...report.rows.map((r) => `| \`${r.path}\` | ${r.unit ?? "-"} | ${r.status} | ${r.before ?? "-"} | ${r.after ?? "-"} | ${r.next ?? "-"} | ${r.labels.join(", ") || "-"} |`));
+    }
+    return `${lines.join("\n")}\n`;
+};
+/** Plans `report.planned` and fills the rows; a cap error becomes a skip. */
+const compareAt = async (session, report, { planned, rpConfig }) => {
+    const { git } = session;
+    const { manifest, head } = report;
+    try {
+        const { plan, units, before, bumpTypes } = await session.workspaceAt(planned, async (workspace, files) => ({
+            plan: await computePlan(workspace, git, {
+                tool: report.tool,
+                branch: report.branch,
+                head: planned,
+                base: null,
+                baseSource: "none",
+                all: true,
+                fs: files,
+            }),
+            units: workspace.units.map((u) => ({
+                id: u.id,
+                path: u.root,
+                released: u.version !== "none",
+                dependsOn: workspace.graph.dependencies.get(u.id) ?? [],
+            })),
+            before: readManifest(files.read(manifest), manifest),
+            bumpTypes: new Set(workspace.release.bumps.keys()),
+        }));
+        const after = readManifest(session.readAt(head, manifest), manifest);
+        const changed = new Set(Object.keys(after).filter((p) => before[p] !== after[p]));
+        report.rows = compareShadow({
+            before,
+            after,
+            plan,
+            units,
+            rpConfig: readJson(session.readAt(head, rpConfig), rpConfig),
+            messages: await commitMessages(git, plan, changed),
+            bumpTypes,
+        });
+        report.warnings.push(...plan.warnings);
+    }
+    catch (error) {
+        if (!(error instanceof TallyError) || !CAP_ERRORS.has(error.code)) {
+            throw error;
+        }
+        report.skipped = { reason: "cap", message: error.message };
+    }
+};
+/** Writes `--out`, the step summary, stdout and annotations. */
+const writeReport = (session, flags, report) => {
+    const { env } = session;
+    if (flags.out !== undefined) {
+        writeFileSync(resolve(session.cwd, flags.out), `${JSON.stringify(report, null, 2)}\n`);
+    }
+    const stepSummary = env["GITHUB_STEP_SUMMARY"];
+    if (flags.summary && stepSummary) {
+        appendFileSync(stepSummary, markdown(report));
+    }
+    session.stdout.write(flags.summary && !stepSummary ? markdown(report) : text(report));
+    if (env["GITHUB_ACTIONS"] === "true") {
+        for (const r of unlabelled(report.rows)) {
+            session.stdout.write(`::warning title=tallyrelease shadow::${escapeData(`${r.path}: ${r.status} (release-please ${r.after ?? "-"}, tallyrelease ${r.next ?? "-"})`)}\n`);
+        }
+    }
+};
+/** `W_SHADOW_INPUT_MISSING` for an explicit `--manifest` or `--rp-config` absent at `head`. */
+const missingInputs = (session, flags, head) => [flags.manifest, flags.rpConfig]
+    .filter((path) => path !== undefined)
+    .filter((path) => session.readAt(head, path) === undefined)
+    .map((path) => ({
+    code: "W_SHADOW_INPUT_MISSING",
+    message: `"${path}" does not exist at ${short(head)}`,
+}));
+/** Compares the plan before a release-please merge with its manifest change. */
+export const shadow = async (session, flags) => {
+    const { git } = session;
+    const manifest = flags.manifest ?? MANIFEST;
+    const head = await git.resolve(flags.head ?? "HEAD");
+    if (head === undefined) {
+        if (flags.head === undefined) {
+            // Surfaces E_NOT_A_REPO and E_NOT_REPO_ROOT first.
+            await session.workspace();
+        }
+        throw new TallyError("E_HEAD_UNRESOLVED", `"${flags.head ?? "HEAD"}" does not resolve to a commit`, { ref: flags.head });
+    }
+    const planned = (await git.resolve(`${head}^1`)) ?? null;
+    const sha = session.env["GITHUB_SHA"] ?? null;
+    const report = {
+        schema: 1,
+        tool: `tallyrelease@${version}`,
+        pin: flags.pin ?? null,
+        sha,
+        replay: flags.head !== undefined || (sha !== null && sha !== head),
+        branch: flags.branch ?? (await branchName(session)),
+        head,
+        planned,
+        manifest,
+        skipped: null,
+        rows: [],
+        warnings: missingInputs(session, flags, head),
+    };
+    if (planned !== null &&
+        (await git.diffFiles(planned, head)).includes(manifest)) {
+        await compareAt(session, report, {
+            planned,
+            rpConfig: flags.rpConfig ?? RP_CONFIG,
+        });
+    }
+    else {
+        report.skipped = {
+            reason: "manifest",
+            message: `${manifest} did not change in ${short(head)}`,
+        };
+    }
+    if (report.skipped) {
+        report.warnings.push({
+            code: "W_SHADOW_SKIPPED",
+            message: `shadow skipped (${report.skipped.reason}): ${report.skipped.message}`,
+        });
+    }
+    session.warn(report.warnings);
+    writeReport(session, flags, report);
+    const open = unlabelled(report.rows).length;
+    if (flags.strict && open > 0) {
+        throw new TallyError("E_SHADOW_MISMATCH", `${count(open, "unlabelled row")} (--strict)`);
+    }
+};

package/dist/config/schema.d.ts

@@ -11,6 +11,7 @@ export declare const configSchema: z.ZodObject<{
             patch: "patch";
             rebuild: "rebuild";
         }>>;
+        initialVersion: z.ZodExactOptional<z.ZodString>;
     }, z.core.$strict>>;
     units: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         id: z.ZodExactOptional<z.ZodString>;
@@ -29,6 +30,7 @@ export declare const configSchema: z.ZodObject<{
             rebuild: "rebuild";
         }>>;
         tags: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+        initialVersion: z.ZodExactOptional<z.ZodString>;
     }, z.core.$strict>>>;
     deps: z.ZodExactOptional<z.ZodArray<z.ZodObject<{
         from: z.ZodString;
@@ -38,6 +40,46 @@ export declare const configSchema: z.ZodObject<{
     }, z.core.$strict>>>;
     ignore: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
     globalInputs: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+    branches: z.ZodExactOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        line: z.ZodEnum<{
+            default: "default";
+            maintenance: "maintenance";
+        }>;
+        channel: z.ZodExactOptional<z.ZodString>;
+        unit: z.ZodExactOptional<z.ZodString>;
+        group: z.ZodExactOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    bumps: z.ZodExactOptional<z.ZodObject<{
+        types: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+            patch: "patch";
+            major: "major";
+            minor: "minor";
+        }>>>;
+        preMajor: z.ZodExactOptional<z.ZodObject<{
+            breaking: z.ZodExactOptional<z.ZodEnum<{
+                patch: "patch";
+                major: "major";
+                minor: "minor";
+            }>>;
+            feat: z.ZodExactOptional<z.ZodEnum<{
+                patch: "patch";
+                major: "major";
+                minor: "minor";
+            }>>;
+        }, z.core.$strict>>;
+        absorbed: z.ZodExactOptional<z.ZodEnum<{
+            patch: "patch";
+            minor: "minor";
+        }>>;
+    }, z.core.$strict>>;
+    groups: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+        units: z.ZodArray<z.ZodString>;
+        tags: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>, z.ZodObject<{
+        units: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+        tags: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>]>>>;
 }, z.core.$strict>;
 /** JSON schema (draft-07) of `tallyrelease.yaml` as published for editors. */
 export declare const configJsonSchema: () => {
@@ -54,6 +96,7 @@ export declare const configJsonSchema: () => {
                 patch: "patch";
                 rebuild: "rebuild";
             }>>;
+            initialVersion: z.ZodExactOptional<z.ZodString>;
         }, z.core.$strict>>;
         units: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
             id: z.ZodExactOptional<z.ZodString>;
@@ -72,6 +115,7 @@ export declare const configJsonSchema: () => {
                 rebuild: "rebuild";
             }>>;
             tags: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+            initialVersion: z.ZodExactOptional<z.ZodString>;
         }, z.core.$strict>>>;
         deps: z.ZodExactOptional<z.ZodArray<z.ZodObject<{
             from: z.ZodString;
@@ -81,6 +125,46 @@ export declare const configJsonSchema: () => {
         }, z.core.$strict>>>;
         ignore: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
         globalInputs: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+        branches: z.ZodExactOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            line: z.ZodEnum<{
+                default: "default";
+                maintenance: "maintenance";
+            }>;
+            channel: z.ZodExactOptional<z.ZodString>;
+            unit: z.ZodExactOptional<z.ZodString>;
+            group: z.ZodExactOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        bumps: z.ZodExactOptional<z.ZodObject<{
+            types: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+                patch: "patch";
+                major: "major";
+                minor: "minor";
+            }>>>;
+            preMajor: z.ZodExactOptional<z.ZodObject<{
+                breaking: z.ZodExactOptional<z.ZodEnum<{
+                    patch: "patch";
+                    major: "major";
+                    minor: "minor";
+                }>>;
+                feat: z.ZodExactOptional<z.ZodEnum<{
+                    patch: "patch";
+                    major: "major";
+                    minor: "minor";
+                }>>;
+            }, z.core.$strict>>;
+            absorbed: z.ZodExactOptional<z.ZodEnum<{
+                patch: "patch";
+                minor: "minor";
+            }>>;
+        }, z.core.$strict>>;
+        groups: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+            units: z.ZodArray<z.ZodString>;
+            tags: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>, z.ZodObject<{
+            units: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+            tags: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>]>>>;
     }, z.core.$strict>>;
     $schema?: "https://json-schema.org/draft/2020-12/schema" | "http://json-schema.org/draft-07/schema#" | "http://json-schema.org/draft-04/schema#";
     $anchor?: string;

package/dist/config/schema.js

@@ -6,6 +6,15 @@ const propagate = z.enum(["auto", "patch", "rebuild"]).meta({
 const tagFormat = z.string().meta({
     description: "Tag template. Defaults to {id}-v{version}, or v{version} for the root unit.",
 });
+const initialVersion = z.string().meta({
+    description: "Version of the first release, parsed by the unit's scheme. Defaults to the scheme's initial version (semver: 1.0.0).",
+});
+const bumpLevel = z.enum(["major", "minor", "patch"]);
+const unitId = z.string().regex(/^(?!\.\.?$)[A-Za-z0-9._-]+$/);
+const groupUnits = z.array(unitId).meta({ description: "Member unit ids." });
+const groupTags = z
+    .array(z.string())
+    .meta({ description: "Selects released units with any of these tags." });
 const unitOverlay = z.strictObject({
     id: z
         .string()
@@ -47,6 +56,7 @@ const unitOverlay = z.strictObject({
         description: "Labels for filtering with affected --tag (letters, digits, dot, underscore, dash), for example docker or npm.",
     })
         .exactOptional(),
+    initialVersion: initialVersion.exactOptional(),
 });
 /** Schema of `tallyrelease.yaml`. */
 export const configSchema = z.strictObject({
@@ -70,6 +80,7 @@ export const configSchema = z.strictObject({
             .exactOptional(),
         tagFormat: tagFormat.exactOptional(),
         propagate: propagate.exactOptional(),
+        initialVersion: initialVersion.exactOptional(),
     })
         .meta({ description: "Defaults applied to every unit." })
         .exactOptional(),
@@ -102,6 +113,82 @@ export const configSchema = z.strictObject({
     globalInputs: globs.meta({
         description: "Globs of files whose change affects all units, unioned with plugin defaults.",
     }),
+    branches: z
+        .array(z.strictObject({
+        name: z.string().meta({
+            description: "Branch name pattern; supports * and the captures {major} and {minor}.",
+        }),
+        line: z.enum(["default", "maintenance"]).meta({
+            description: "Release line of matching branches.",
+        }),
+        channel: z
+            .string()
+            .meta({
+            description: "Prerelease channel (letters, digits, dash); may use {major} and {minor} captured by name.",
+        })
+            .exactOptional(),
+        unit: z
+            .string()
+            .meta({
+            description: "Maintenance rules: ungrouped released unit whose version must be on the line captured by name. Excludes group.",
+        })
+            .exactOptional(),
+        group: z
+            .string()
+            .meta({
+            description: "Maintenance rules: fixed group whose version must be on the line captured by name. Excludes unit.",
+        })
+            .exactOptional(),
+    }))
+        .meta({
+        description: "Branch rules; the first rule matching the branch wins.",
+    })
+        .exactOptional(),
+    bumps: z
+        .strictObject({
+        types: z
+            .record(z.string(), bumpLevel)
+            .meta({
+            description: "Commit type to bump level, merged over feat: minor, fix: patch, perf: patch, revert: patch. Breaking changes bump major.",
+        })
+            .exactOptional(),
+        preMajor: z
+            .strictObject({
+            breaking: bumpLevel.exactOptional(),
+            feat: bumpLevel.exactOptional(),
+        })
+            .meta({
+            description: "Bump levels for breaking changes and feat while the major version is 0. Default minor for both.",
+        })
+            .exactOptional(),
+        absorbed: z
+            .enum(["patch", "minor"])
+            .meta({
+            description: "Level a released unit gets from bump-producing changes absorbed from unreleased dependencies: patch (default) or minor (feat and breaking give minor, fix gives patch).",
+        })
+            .exactOptional(),
+    })
+        .meta({ description: "How commits map to bump levels." })
+        .exactOptional(),
+    groups: z
+        .record(unitId, z.union([
+        z.strictObject({
+            units: groupUnits,
+            tags: groupTags.exactOptional(),
+        }),
+        z.strictObject({
+            units: groupUnits.exactOptional(),
+            tags: groupTags,
+        }),
+    ]))
+        .refine((groups) => Object.keys(groups).length > 0, {
+        message: "groups needs at least one group",
+    })
+        .meta({
+        description: "Fixed groups by name (unit id characters): members release together with one version. Each group needs units, tags or both.",
+        minProperties: 1,
+    })
+        .exactOptional(),
 });
 /** JSON schema (draft-07) of `tallyrelease.yaml` as published for editors. */
 export const configJsonSchema = () => ({

package/dist/fs-ctx.d.ts

@@ -1,3 +1,10 @@
 import type { ReadonlyFs } from "@tallyrelease/core";
 /** `ReadonlyFs` over the directory `root`. */
 export declare const nodeFs: (root: string) => ReadonlyFs;
+/**
+ * `ReadonlyFs` over the tree of commit `sha` in the repository at `root`,
+ * matching `nodeFs`; paths are listed once, files read lazily.
+ */
+export declare const gitTreeFs: (root: string, sha: string) => ReadonlyFs;
+/** Content of `path` at commit `ref` in the repository at `root`, undefined when absent. */
+export declare const gitBlob: (root: string, ref: string, path: string) => string | undefined;

package/dist/fs-ctx.js

@@ -1,5 +1,7 @@
+import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import picomatch from "picomatch/posix.js";
 import { globSync } from "tinyglobby";
 const IGNORED = ["**/.git/**", "**/node_modules/**", "vendor/**"];
 /** `ReadonlyFs` over the directory `root`. */
@@ -23,3 +25,65 @@ export const nodeFs = (root) => ({
         .map((p) => p.replace(/\/$/, ""))
         .sort(),
 });
+/**
+ * `ReadonlyFs` over the tree of commit `sha` in the repository at `root`,
+ * matching `nodeFs`; paths are listed once, files read lazily.
+ */
+export const gitTreeFs = (root, sha) => {
+    const git = (args) => execFileSync("git", ["-c", "core.quotePath=false", ...args], {
+        cwd: root,
+        maxBuffer: 256 * 1024 * 1024,
+        stdio: ["ignore", "pipe", "ignore"],
+    });
+    const ignored = picomatch(IGNORED, { dot: true });
+    const paths = git(["ls-tree", "-r", "-z", "--name-only", sha])
+        .toString("utf8")
+        .split("\0")
+        .filter((p) => p !== "" && !ignored(p))
+        .sort();
+    const files = new Set(paths);
+    const dirs = [
+        ...new Set(paths.flatMap((p) => {
+            const parts = p.split("/");
+            return parts.slice(1).map((_, i) => parts.slice(0, i + 1).join("/"));
+        })),
+    ]
+        .filter((d) => !ignored(d) && !ignored(`${d}/`))
+        .sort();
+    const dirSet = new Set(dirs);
+    const cache = new Map();
+    return {
+        read: (path) => {
+            if (!files.has(path)) {
+                return undefined;
+            }
+            if (!cache.has(path)) {
+                try {
+                    cache.set(path, git(["cat-file", "blob", `${sha}:${path}`]).toString("utf8"));
+                }
+                catch {
+                    cache.set(path, undefined);
+                }
+            }
+            return cache.get(path);
+        },
+        exists: (path) => path === "." || files.has(path) || dirSet.has(path),
+        glob: (patterns, opts) => {
+            const match = picomatch([...patterns], { dot: true });
+            return (opts?.dirs ? dirs : paths).filter((p) => match(p));
+        },
+    };
+};
+/** Content of `path` at commit `ref` in the repository at `root`, undefined when absent. */
+export const gitBlob = (root, ref, path) => {
+    try {
+        return execFileSync("git", ["cat-file", "blob", `${ref}:${path}`], {
+            cwd: root,
+            maxBuffer: 256 * 1024 * 1024,
+            stdio: ["ignore", "pipe", "ignore"],
+        }).toString("utf8");
+    }
+    catch {
+        return undefined;
+    }
+};

package/dist/git/reader.js

@@ -52,8 +52,12 @@ export const gitReader = (cwd, debug) => {
             return result.code === 0;
         },
         isFirstParentAncestor: async (a, b) => {
+            const chain = await firstParentSet(b);
+            if (chain.has(a)) {
+                return true;
+            }
             const sha = await resolve(a);
-            return sha !== undefined && (await firstParentSet(b)).has(sha);
+            return sha !== undefined && chain.has(sha);
         },
         log: async (from, to) => {
             const out = await ok([
@@ -62,6 +66,7 @@ export const gitReader = (cwd, debug) => {
                 "--no-show-signature",
                 "--no-color",
                 "--no-merges",
+                "--topo-order",
                 "--no-renames",
                 "--name-only",
                 "--format=%x1e%H%x00%P%x00%cI%x00%B%x00",

package/dist/main.js

@@ -3,7 +3,10 @@ import { Command, CommanderError, Option } from "commander";
 import { inspect } from "node:util";
 import { affected } from "./commands/affected.js";
 import { check } from "./commands/check.js";
+import { explain } from "./commands/explain.js";
 import { graph } from "./commands/graph.js";
+import { plan } from "./commands/plan.js";
+import { shadow } from "./commands/shadow.js";
 import { painter } from "./output/paint.js";
 import { createSession } from "./session.js";
 import { version } from "./version.js";
@@ -62,6 +65,49 @@ export const main = async (argv, deps) => {
         }
         await affected(session(), flags);
     });
+    program
+        .command("plan")
+        .description("compute the release plan (read-only)")
+        .option("--branch <name>", "plan for this branch (default: current)")
+        .option("--base <ref>", "diff against this ref")
+        .option("--head <ref>", "plan this commit with the current config; pass --branch for its branch rule")
+        .option("--all", "also list released units outside the build set")
+        .option("--json", "print the plan (same as --format json)")
+        .addOption(new Option("--format <format>", "output format").choices([
+        "text",
+        "json",
+    ]))
+        .option("--out <file>", "write the plan to a file")
+        .option("--github-output", "append outputs to $GITHUB_OUTPUT")
+        .action(async (flags, cmd) => {
+        if (flags.json && flags.format !== undefined) {
+            cmd.error("--json and --format cannot be combined", { exitCode: 2 });
+        }
+        await plan(session(), flags);
+    });
+    program
+        .command("explain")
+        .description("explain why a unit is affected and how it is versioned")
+        .argument("<unit>", "unit id")
+        .option("--branch <name>", "plan for this branch (default: current)")
+        .option("--base <ref>", "diff against this ref")
+        .action(async (unit, flags) => {
+        await explain(session(), unit, flags);
+    });
+    program
+        .command("shadow")
+        .description("compare the plan with a release-please manifest change")
+        .option("--manifest <path>", "release-please manifest (default: .release-please-manifest.json)")
+        .option("--rp-config <path>", "release-please config (default: release-please-config.json)")
+        .option("--head <ref>", "compare this merge instead of HEAD (replay)")
+        .option("--branch <name>", "plan for this branch (default: current)")
+        .option("--pin <spec>", "cli version recorded in the report")
+        .option("--out <file>", "write the report to a file")
+        .option("--summary", "write markdown to $GITHUB_STEP_SUMMARY, else print it")
+        .option("--strict", "exit 1 on unlabelled mismatches")
+        .action(async (flags) => {
+        await shadow(session(), flags);
+    });
     try {
         await program.parseAsync(argv, { from: "user" });
         return 0;