@tallyrelease/cli 0.1.0-beta.3 → 0.1.0-beta.5

package/dist/affected-schema.d.ts

@@ -14,6 +14,7 @@ export declare const affectedDocSchema: z.ZodObject<{
             "pr-merge-base": "pr-merge-base";
             "merge-group": "merge-group";
             "forge-last-success": "forge-last-success";
+            "local-merge-base": "local-merge-base";
             none: "none";
         }>;
         all: z.ZodBoolean;

package/dist/affected-schema.js

@@ -15,6 +15,7 @@ export const affectedDocSchema = z.strictObject({
             "pr-merge-base",
             "merge-group",
             "forge-last-success",
+            "local-merge-base",
             "none",
         ]),
         all: z.boolean(),

package/dist/affected.schema.json

@@ -35,6 +35,7 @@
 						"pr-merge-base",
 						"merge-group",
 						"forge-last-success",
+						"local-merge-base",
 						"none"
 					]
 				},

package/dist/ci/base.d.ts

@@ -1,14 +1,17 @@
-import type { GithubContext } from "./github-env.js";
+import type { Env, GithubContext } from "./github-env.js";
 import type { Forge } from "../forge/forge.js";
 import type { RepoGit } from "../git/reader.js";
 import type { BaseSource, Warning } from "@tallyrelease/core";
 export interface BuildBase {
     base: string | null;
     source: BaseSource;
+    /** The `--base` value, or the branch of a local merge base. */
+    ref?: string;
     warnings: Warning[];
 }
 export interface BuildBaseInput {
     git: RepoGit;
+    env: Env;
     /** Resolved HEAD sha. */
     head: string;
     /** `--base`. */
@@ -17,5 +20,5 @@ export interface BuildBaseInput {
     /** Present only when a token is available. */
     forge?: Forge | undefined;
 }
-/** Resolves the build base from `--base`, the CI event, then the forge. */
+/** Resolves the build base from `--base`, the CI event, the forge, then the local default branch. */
 export declare const resolveBuildBase: (input: BuildBaseInput) => Promise<BuildBase>;

package/dist/ci/base.js

@@ -1,5 +1,20 @@
 import { TallyError } from "@tallyrelease/core";
 const ZERO_SHA = /^0+$/;
+const CI_VARS = [
+    "JENKINS_URL",
+    "TF_BUILD",
+    "CODEBUILD_BUILD_ID",
+    "BUILDKITE",
+    "GITLAB_CI",
+    "TEAMCITY_VERSION",
+    "BITBUCKET_BUILD_NUMBER",
+];
+const DEFAULT_REFS = ["origin/main", "origin/master", "main", "master"];
+const isCi = (env) => {
+    const ci = env["CI"];
+    return ((ci !== undefined && !["", "false", "0"].includes(ci)) ||
+        CI_VARS.some((name) => env[name] !== undefined));
+};
 const str = (value) => typeof value === "string" && value !== "" ? value : undefined;
 const field = (value, key) => typeof value === "object" && value !== null
     ? value[key]
@@ -24,7 +39,7 @@ const noLastSuccess = {
     code: "W_NO_LAST_SUCCESS",
     message: "no successful push run of this workflow on this branch",
 };
-/** Resolves the build base from `--base`, the CI event, then the forge. */
+/** Resolves the build base from `--base`, the CI event, the forge, then the local default branch. */
 export const resolveBuildBase = async (input) => {
     const { git, head, github, forge } = input;
     // A named sha missing from a shallow clone must not silently become "everything".
@@ -84,8 +99,32 @@ export const resolveBuildBase = async (input) => {
             ? result(last, "forge-last-success")
             : result(null, "none", last);
     };
+    /** First of `origin/HEAD` and the common default branch names that resolves. */
+    const defaultRef = async () => {
+        const candidates = [await git.defaultBranch(), ...DEFAULT_REFS];
+        for (const candidate of candidates) {
+            if (candidate === undefined) {
+                continue;
+            }
+            // eslint-disable-next-line no-await-in-loop -- first match wins
+            if ((await git.resolve(candidate)) !== undefined) {
+                return candidate;
+            }
+        }
+        return undefined;
+    };
     if (input.cliBase !== undefined) {
-        return result(await required(input.cliBase, "--base"), "cli");
+        return {
+            ...result(await required(input.cliBase, "--base"), "cli"),
+            ref: input.cliBase,
+        };
+    }
+    if (github === undefined && !isCi(input.env)) {
+        const ref = await defaultRef();
+        const base = ref === undefined ? undefined : await git.mergeBase(head, ref);
+        return ref === undefined || base === undefined
+            ? result(null, "none")
+            : { ...result(base, "local-merge-base"), ref };
     }
     switch (github?.eventName) {
         case "pull_request": {

package/dist/commands/affected.d.ts

@@ -1,6 +1,7 @@
 import type { Session } from "../session.js";
 export interface AffectedFlags {
     base?: string;
+    format?: "text" | "json" | "tsv";
     json?: boolean;
     out?: string;
     githubOutput?: boolean;

package/dist/commands/affected.js

@@ -3,7 +3,40 @@ import { appendFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { resolveBuildBase } from "../ci/base.js";
 import { affectedGithubOutput } from "../ci/outputs.js";
+import { alignColumns } from "../output/columns.js";
+import { count } from "../output/count.js";
+import { painter } from "../output/paint.js";
 import { version } from "../version.js";
+const GROUPS = [
+    "all",
+    "global",
+    "direct",
+    "dependent",
+];
+const baseLabel = (base) => {
+    switch (base.source) {
+        case "cli":
+            return `--base ${base.ref ?? ""}`;
+        case "push-before":
+            return "push before";
+        case "pr-merge-base":
+            return "merge base with the PR target";
+        case "merge-group":
+            return "merge group base";
+        case "forge-last-success":
+            return "last successful run";
+        case "local-merge-base":
+            return `merge base with ${base.ref ?? ""}`;
+        case "none":
+            return "everything is affected";
+    }
+};
+const tsv = (doc) => [
+    "id\tpath\treason\tvia",
+    ...doc.units.map((u) => [u.id, u.path, u.reason, u.via.join(",")].join("\t")),
+]
+    .map((line) => `${line}\n`)
+    .join("");
 /** Computes the build set and writes the requested outputs. */
 export const affected = async (session, flags) => {
     const { git, github } = session;
@@ -15,6 +48,7 @@ export const affected = async (session, flags) => {
     const base = await resolveBuildBase({
         git,
         head,
+        env: session.env,
         cliBase: flags.base,
         github,
         forge: session.forge,
@@ -42,13 +76,46 @@ export const affected = async (session, flags) => {
         }
         appendFileSync(path, affectedGithubOutput(doc));
     }
-    if (flags.json) {
+    const format = flags.format ?? (flags.json ? "json" : "text");
+    if (format === "json") {
         session.stdout.write(json);
         return;
     }
-    session.stdout.write(`base: ${doc.build.base ?? "none"} (${doc.build.baseSource})\n`);
-    for (const u of doc.units) {
-        const via = u.via.length > 0 ? ` via ${u.via.join(", ")}` : "";
-        session.stdout.write(`${u.id}\t${u.path}\t${u.reason}${via}\n`);
+    if (format === "tsv") {
+        session.stdout.write(tsv(doc));
+        return;
+    }
+    const paint = painter(session.stdout);
+    const released = new Set(workspace.units.filter((u) => u.version !== "none").map((u) => u.id));
+    const rows = alignColumns(doc.units.map((u) => [
+        u.id,
+        u.path,
+        u.via.length > 0 ? `via ${u.via.join(", ")}` : "",
+        released.has(u.id) ? "released" : "",
+    ]), { indent: 2, styles: [undefined, "dim", "dim", "cyan"] }, paint);
+    const sha = doc.build.base?.slice(0, 7) ?? "none";
+    const lines = [
+        `${paint("bold", "base")}  ${paint("yellow", sha)} ${paint("dim", `(${baseLabel(base)})`)}`,
+        "",
+    ];
+    for (const group of GROUPS) {
+        const members = rows.filter((_, i) => doc.units[i]?.reason === group);
+        if (members.length > 0) {
+            lines.push(paint("bold", `${group} (${String(members.length)})`));
+            if (group === "global") {
+                lines.push(`  changed: ${doc.build.globalInputs.join(", ")}`);
+            }
+            lines.push(...members);
+        }
+    }
+    if (doc.units.length > 0) {
+        lines.push("");
     }
+    const outside = doc.unattributed.length > 0
+        ? `, ${count(doc.unattributed.length, "file")} outside any unit`
+        : "";
+    lines.push(doc.units.length > 0
+        ? `${String(doc.units.length)} of ${count(workspace.units.length, "unit")} affected${outside}`
+        : `no units affected${outside}`);
+    session.stdout.write(`${lines.join("\n")}\n`);
 };

package/dist/commands/check.js

@@ -1,3 +1,4 @@
+import { count } from "../output/count.js";
 /** Validates config, plugins, units and graph. */
 export const check = async (session) => {
     const workspace = await session.workspace();
@@ -6,5 +7,5 @@ export const check = async (session) => {
         .filter((u) => u.version !== "none")
         .map((u) => u.id);
     const list = released.length > 0 ? `: ${released.join(", ")}` : "";
-    session.stdout.write(`ok: ${String(workspace.units.length)} units (${String(released.length)} released${list}), ${String(workspace.graph.edges.length)} edges\n`);
+    session.stdout.write(`ok: ${count(workspace.units.length, "unit")} (${String(released.length)} released${list}), ${count(workspace.graph.edges.length, "edge")}\n`);
 };

package/dist/commands/graph.js

@@ -1,3 +1,7 @@
+import { alignColumns } from "../output/columns.js";
+import { count } from "../output/count.js";
+import { painter } from "../output/paint.js";
+import { renderTree } from "../output/tree.js";
 import { renderMermaid } from "../render/mermaid.js";
 /** Prints units and edges. */
 export const graph = async (session, flags) => {
@@ -24,10 +28,36 @@ export const graph = async (session, flags) => {
         session.stdout.write(`${JSON.stringify({ repo: workspace.repo, units, edges }, null, 2)}\n`);
         return;
     }
-    for (const u of units) {
-        session.stdout.write(`${u.id}\t${u.path}\t${u.plugin}\t${u.version}\n`);
+    if (units.length === 0) {
+        session.stdout.write("no units\n");
+        return;
     }
-    for (const e of edges) {
-        session.stdout.write(`${e.from} -> ${e.to}${e.pinned ? " (pinned)" : ""}\n`);
+    const paint = painter(session.stdout);
+    const table = [
+        ["UNIT", "PATH", "PLUGIN", "RELEASE"],
+        ...units.map((u) => [
+            u.id,
+            u.path,
+            u.plugin,
+            u.version === "none" ? "-" : u.version,
+        ]),
+    ];
+    // Header is aligned unstyled so column styles do not apply to it.
+    const [header = ""] = alignColumns(table);
+    const [, ...rows] = alignColumns(table, { styles: [undefined, "dim"] }, paint);
+    const lines = [paint("bold", header), ...rows];
+    const tree = renderTree(units.map((u) => u.id), (id) => workspace.graph.dependents.get(id) ?? []);
+    if (edges.length > 0) {
+        lines.push("", paint("bold", "dependents"), ...tree.lines);
     }
+    const released = units.filter((u) => u.version !== "none").length;
+    const legend = [
+        ...(tree.shared ? ["(*) expanded above"] : []),
+        ...(tree.cycle ? ["(cycle) edge back into the current path"] : []),
+    ];
+    lines.push("", [
+        `${count(units.length, "unit")} (${String(released)} released), ${count(edges.length, "edge")}`,
+        ...legend,
+    ].join("; "));
+    session.stdout.write(`${lines.join("\n")}\n`);
 };

package/dist/config/load.js

@@ -24,5 +24,6 @@ export const loadConfig = (fs, path) => {
             issues: result.error.issues,
         });
     }
-    return result.data;
+    const { $schema: _, ...config } = result.data;
+    return config;
 };

package/dist/config/schema.d.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 /** Schema of `tallyrelease.yaml`. */
 export declare const configSchema: z.ZodObject<{
+    $schema: z.ZodExactOptional<z.ZodString>;
     plugins: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
     defaults: z.ZodExactOptional<z.ZodObject<{
         release: z.ZodExactOptional<z.ZodBoolean>;
@@ -37,3 +38,105 @@ export declare const configSchema: z.ZodObject<{
     ignore: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
     globalInputs: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
+/** JSON schema (draft-07) of `tallyrelease.yaml` as published for editors. */
+export declare const configJsonSchema: () => {
+    $id: string;
+    title: string;
+    "~standard": z.core.ZodStandardSchemaWithJSON<z.ZodObject<{
+        $schema: z.ZodExactOptional<z.ZodString>;
+        plugins: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
+        defaults: z.ZodExactOptional<z.ZodObject<{
+            release: z.ZodExactOptional<z.ZodBoolean>;
+            tagFormat: z.ZodExactOptional<z.ZodString>;
+            propagate: z.ZodExactOptional<z.ZodEnum<{
+                auto: "auto";
+                patch: "patch";
+                rebuild: "rebuild";
+            }>>;
+        }, z.core.$strict>>;
+        units: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            id: z.ZodExactOptional<z.ZodString>;
+            include: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+            exclude: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+            release: z.ZodExactOptional<z.ZodBoolean>;
+            version: z.ZodExactOptional<z.ZodEnum<{
+                file: "file";
+                tag: "tag";
+            }>>;
+            scheme: z.ZodExactOptional<z.ZodString>;
+            tagFormat: z.ZodExactOptional<z.ZodString>;
+            propagate: z.ZodExactOptional<z.ZodEnum<{
+                auto: "auto";
+                patch: "patch";
+                rebuild: "rebuild";
+            }>>;
+        }, z.core.$strict>>>;
+        deps: z.ZodExactOptional<z.ZodArray<z.ZodObject<{
+            from: z.ZodString;
+            to: z.ZodString;
+            pinned: z.ZodExactOptional<z.ZodBoolean>;
+            reason: z.ZodExactOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        ignore: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+        globalInputs: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+    }, 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;
+    $ref?: string;
+    $dynamicRef?: string;
+    $dynamicAnchor?: string;
+    $vocabulary?: Record<string, boolean>;
+    $comment?: string;
+    $defs?: Record<string, z.core.JSONSchema.JSONSchema>;
+    type?: z.core.JSONSchema.SchemaType | z.core.JSONSchema.SchemaType[];
+    additionalItems?: z.core.JSONSchema._JSONSchema;
+    unevaluatedItems?: z.core.JSONSchema._JSONSchema;
+    prefixItems?: z.core.JSONSchema._JSONSchema[];
+    items?: z.core.JSONSchema._JSONSchema | z.core.JSONSchema._JSONSchema[];
+    contains?: z.core.JSONSchema._JSONSchema;
+    additionalProperties?: z.core.JSONSchema._JSONSchema;
+    unevaluatedProperties?: z.core.JSONSchema._JSONSchema;
+    properties?: Record<string, z.core.JSONSchema._JSONSchema>;
+    patternProperties?: Record<string, z.core.JSONSchema._JSONSchema>;
+    dependentSchemas?: Record<string, z.core.JSONSchema._JSONSchema>;
+    propertyNames?: z.core.JSONSchema._JSONSchema;
+    if?: z.core.JSONSchema._JSONSchema;
+    then?: z.core.JSONSchema._JSONSchema;
+    else?: z.core.JSONSchema._JSONSchema;
+    allOf?: z.core.JSONSchema.JSONSchema[];
+    anyOf?: z.core.JSONSchema.JSONSchema[];
+    oneOf?: z.core.JSONSchema.JSONSchema[];
+    not?: z.core.JSONSchema._JSONSchema;
+    multipleOf?: number;
+    maximum?: number;
+    exclusiveMaximum?: number | boolean;
+    minimum?: number;
+    exclusiveMinimum?: number | boolean;
+    maxLength?: number;
+    minLength?: number;
+    pattern?: string;
+    maxItems?: number;
+    minItems?: number;
+    uniqueItems?: boolean;
+    maxContains?: number;
+    minContains?: number;
+    maxProperties?: number;
+    minProperties?: number;
+    required?: string[];
+    dependentRequired?: Record<string, string[]>;
+    enum?: Array<string | number | boolean | null>;
+    const?: string | number | boolean | null;
+    id?: string;
+    description?: string;
+    default?: unknown;
+    deprecated?: boolean;
+    readOnly?: boolean;
+    writeOnly?: boolean;
+    nullable?: boolean;
+    examples?: unknown[];
+    format?: string;
+    contentMediaType?: string;
+    contentEncoding?: string;
+    contentSchema?: z.core.JSONSchema.JSONSchema;
+    _prefault?: unknown;
+};

package/dist/config/schema.js

@@ -1,43 +1,105 @@
 import { z } from "zod";
 const globs = z.array(z.string()).exactOptional();
-const propagate = z.enum(["auto", "patch", "rebuild"]);
+const propagate = z.enum(["auto", "patch", "rebuild"]).meta({
+    description: "Policy for this unit when a dependency is released: patch (at least a patch bump), rebuild (rebuild only) or auto (patch if the edge is pinned, else rebuild).",
+});
+const tagFormat = z.string().meta({
+    description: "Tag template. Defaults to {id}-v{version}, or v{version} for the root unit.",
+});
 const unitOverlay = z.strictObject({
-    id: z.string().exactOptional(),
-    include: globs,
-    exclude: globs,
-    release: z.boolean().exactOptional(),
+    id: z
+        .string()
+        .meta({
+        description: "Unit id (letters, digits, dot, underscore, dash). Defaults to the discovered id, or the repo name for the root unit.",
+    })
+        .exactOptional(),
+    include: globs.meta({
+        description: "Globs of files owned by the unit. Replaces the default (the unit root).",
+    }),
+    exclude: globs.meta({
+        description: "Globs excluded from the unit, appended to the default (roots of nested units).",
+    }),
+    release: z
+        .boolean()
+        .meta({
+        description: "Whether the unit is versioned and tagged. Default false (build-only).",
+    })
+        .exactOptional(),
     version: z
         .enum(["file", "tag"], {
         error: (issue) => issue.input === "none"
             ? 'version "none" is not supported, use release: false'
             : undefined,
+    })
+        .meta({
+        description: "Where a released unit's version lives. file: version file written by the plugin. tag: git tags only. Defaults to the plugin's version source.",
     })
         .exactOptional(),
-    scheme: z.string().exactOptional(),
-    tagFormat: z.string().exactOptional(),
+    scheme: z
+        .string()
+        .meta({ description: "Versioning scheme. Defaults to semver." })
+        .exactOptional(),
+    tagFormat: tagFormat.exactOptional(),
     propagate: propagate.exactOptional(),
 });
 /** Schema of `tallyrelease.yaml`. */
 export const configSchema = z.strictObject({
+    $schema: z
+        .string()
+        .meta({ description: "Schema reference for editors, ignored." })
+        .exactOptional(),
     plugins: z
         .record(z.string(), z.record(z.string(), z.unknown()).nullable())
+        .meta({
+        description: "Enabled plugins and their options, run in the listed order. Only listed plugins run.",
+    })
         .default({}),
     defaults: z
         .strictObject({
-        release: z.boolean().exactOptional(),
-        tagFormat: z.string().exactOptional(),
+        release: z
+            .boolean()
+            .meta({
+            description: "Release all units unless a unit sets release: false. Default false.",
+        })
+            .exactOptional(),
+        tagFormat: tagFormat.exactOptional(),
         propagate: propagate.exactOptional(),
+    })
+        .meta({ description: "Defaults applied to every unit." })
+        .exactOptional(),
+    units: z
+        .record(z.string(), unitOverlay)
+        .meta({
+        description: "Unit overlays keyed by root path. A root without a discovered unit becomes a config-only unit.",
     })
         .exactOptional(),
-    units: z.record(z.string(), unitOverlay).exactOptional(),
     deps: z
         .array(z.strictObject({
-        from: z.string(),
-        to: z.string(),
-        pinned: z.boolean().exactOptional(),
-        reason: z.string().exactOptional(),
+        from: z.string().meta({ description: "Id of the dependency." }),
+        to: z.string().meta({ description: "Id of the dependent unit." }),
+        pinned: z
+            .boolean()
+            .meta({
+            description: "Whether the dependent pins an exact version.",
+        })
+            .exactOptional(),
+        reason: z
+            .string()
+            .meta({ description: "Why the edge exists." })
+            .exactOptional(),
     }))
+        .meta({ description: "Extra dependency edges between units." })
         .exactOptional(),
-    ignore: globs,
-    globalInputs: globs,
+    ignore: globs.meta({
+        description: "Globs of files that never affect any unit, for example docs.",
+    }),
+    globalInputs: globs.meta({
+        description: "Globs of files whose change affects all units, unioned with plugin defaults.",
+    }),
+});
+/** JSON schema (draft-07) of `tallyrelease.yaml` as published for editors. */
+export const configJsonSchema = () => ({
+    ...z.toJSONSchema(configSchema, { target: "draft-7", io: "input" }),
+    $id: "https://cdn.jsdelivr.net/npm/@tallyrelease/cli@0/dist/tallyrelease.schema.json",
+    title: "tallyrelease.yaml",
 });

package/dist/git/reader.d.ts

@@ -8,6 +8,8 @@ export interface RepoGit extends GitReader {
     isShallow: () => MaybePromise<boolean>;
     /** Current branch, undefined when detached. */
     branch: () => MaybePromise<string | undefined>;
+    /** Target of `origin/HEAD`, for example `origin/main`; undefined if unset. */
+    defaultBranch: () => MaybePromise<string | undefined>;
 }
 /** `RepoGit` backed by the `git` executable in `cwd`. */
 export declare const gitReader: (cwd: string, debug?: (message: string) => void) => RepoGit;

package/dist/git/reader.js

@@ -110,5 +110,9 @@ export const gitReader = (cwd, debug) => {
             const result = await run(cwd, ["symbolic-ref", "--quiet", "--short", "HEAD"], debug);
             return result.code === 0 ? result.stdout.trim() : undefined;
         },
+        defaultBranch: async () => {
+            const result = await run(cwd, ["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"], debug);
+            return result.code === 0 ? result.stdout.trim() : undefined;
+        },
     };
 };

package/dist/main.js

@@ -4,6 +4,7 @@ import { inspect } from "node:util";
 import { affected } from "./commands/affected.js";
 import { check } from "./commands/check.js";
 import { graph } from "./commands/graph.js";
+import { painter } from "./output/paint.js";
 import { createSession } from "./session.js";
 import { version } from "./version.js";
 /** Runs the cli; returns the exit code (0 ok, 1 error, 2 usage). */
@@ -46,10 +47,18 @@ export const main = async (argv, deps) => {
         .command("affected")
         .description("compute the build set")
         .option("--base <ref>", "diff against this ref")
-        .option("--json", "print the affected document")
+        .option("--json", "print the affected document (same as --format json)")
+        .addOption(new Option("--format <format>", "output format").choices([
+        "text",
+        "json",
+        "tsv",
+    ]))
         .option("--out <file>", "write the affected document to a file")
         .option("--github-output", "append outputs to $GITHUB_OUTPUT")
-        .action(async (flags) => {
+        .action(async (flags, cmd) => {
+        if (flags.json && flags.format !== undefined) {
+            cmd.error("--json and --format cannot be combined", { exitCode: 2 });
+        }
         await affected(session(), flags);
     });
     try {
@@ -60,11 +69,12 @@ export const main = async (argv, deps) => {
         if (error instanceof CommanderError) {
             return error.exitCode === 0 ? 0 : 2;
         }
+        const paint = painter(deps.stderr);
         if (error instanceof TallyError) {
-            deps.stderr.write(`${error.code}: ${error.message}\n`);
+            deps.stderr.write(`${paint("red", `error[${error.code}]`)}: ${error.message}\n`);
         }
         else {
-            deps.stderr.write(`E_INTERNAL: ${error instanceof Error ? error.message : String(error)}\n`);
+            deps.stderr.write(`${paint("red", "error[E_INTERNAL]")}: ${error instanceof Error ? error.message : String(error)}\n`);
             if (program.opts().verbose) {
                 deps.stderr.write(`${inspect(error)}\n`);
             }

package/dist/output/columns.d.ts

@@ -0,0 +1,10 @@
+import type { Format, Paint } from "./paint.js";
+export interface ColumnOptions {
+    indent?: number;
+    styles?: readonly (Format | undefined)[];
+}
+/**
+ * Pads cells to aligned columns; widths come from the plain text, styles apply
+ * per cell. Columns that are empty in every row are dropped.
+ */
+export declare const alignColumns: (rows: readonly (readonly string[])[], opts?: ColumnOptions, paint?: Paint) => string[];

package/dist/output/columns.js

@@ -0,0 +1,32 @@
+/**
+ * Pads cells to aligned columns; widths come from the plain text, styles apply
+ * per cell. Columns that are empty in every row are dropped.
+ */
+export const alignColumns = (rows, opts = {}, paint = (_format, text) => text) => {
+    const widths = [];
+    for (const row of rows) {
+        row.forEach((cell, i) => {
+            widths[i] = Math.max(widths[i] ?? 0, cell.length);
+        });
+    }
+    const indent = " ".repeat(opts.indent ?? 0);
+    return rows.map((row) => {
+        const cells = [...row];
+        while (cells.at(-1) === "") {
+            cells.pop();
+        }
+        return (indent +
+            cells
+                .map((cell, i) => {
+                if (widths[i] === 0) {
+                    return undefined;
+                }
+                const style = opts.styles?.[i];
+                const text = style && cell !== "" ? paint(style, cell) : cell;
+                const pad = i === cells.length - 1 ? 0 : (widths[i] ?? 0) - cell.length;
+                return text + " ".repeat(pad);
+            })
+                .filter((cell) => cell !== undefined)
+                .join("  "));
+    });
+};

package/dist/output/count.d.ts

@@ -0,0 +1,2 @@
+/** `1 unit`, `2 units`. */
+export declare const count: (n: number, noun: string) => string;

package/dist/output/count.js

@@ -0,0 +1,2 @@
+/** `1 unit`, `2 units`. */
+export const count = (n, noun) => `${String(n)} ${noun}${n === 1 ? "" : "s"}`;

package/dist/output/paint.d.ts

@@ -0,0 +1,6 @@
+import { styleText } from "node:util";
+import type { Writer } from "../session.js";
+export type Format = Parameters<typeof styleText>[0];
+export type Paint = (format: Format, text: string) => string;
+/** Styles text for `stream`; Node decides on color for real streams, other writers stay plain. */
+export declare const painter: (stream: Writer) => Paint;

package/dist/output/paint.js

@@ -0,0 +1,10 @@
+import { Stream } from "node:stream";
+import { styleText } from "node:util";
+/** Styles text for `stream`; Node decides on color for real streams, other writers stay plain. */
+export const painter = (stream) => stream instanceof Stream
+    ? (format, text) => 
+    // styleText validates the stream at runtime.
+    styleText(format, text, {
+        stream: stream,
+    })
+    : (_format, text) => text;

package/dist/output/tree.d.ts

@@ -0,0 +1,12 @@
+export interface Tree {
+    lines: string[];
+    /** A `(*)` marker was printed. */
+    shared: boolean;
+    /** A `(cycle)` marker was printed. */
+    cycle: boolean;
+}
+/**
+ * Renders `children` as trees from the units without dependencies, in id order.
+ * Units left unvisited (pure cycles) become extra roots, smallest id first.
+ */
+export declare const renderTree: (ids: readonly string[], children: (id: string) => readonly string[]) => Tree;

package/dist/output/tree.js

@@ -0,0 +1,45 @@
+/**
+ * Renders `children` as trees from the units without dependencies, in id order.
+ * Units left unvisited (pure cycles) become extra roots, smallest id first.
+ */
+export const renderTree = (ids, children) => {
+    const tree = { lines: [], shared: false, cycle: false };
+    const visited = new Set();
+    const path = new Set();
+    const visit = (id, branch, prefix) => {
+        const kids = children(id);
+        if (path.has(id)) {
+            tree.lines.push(`${branch}${id} (cycle)`);
+            tree.cycle = true;
+            return;
+        }
+        if (visited.has(id) && kids.length > 0) {
+            tree.lines.push(`${branch}${id} (*)`);
+            tree.shared = true;
+            return;
+        }
+        tree.lines.push(`${branch}${id}`);
+        visited.add(id);
+        path.add(id);
+        kids.forEach((kid, i) => {
+            const last = i === kids.length - 1;
+            visit(kid, `${prefix}${last ? "└── " : "├── "}`, `${prefix}${last ? "    " : "│   "}`);
+        });
+        path.delete(id);
+    };
+    const inDegree = new Map(ids.map((id) => [id, 0]));
+    for (const id of ids) {
+        for (const kid of children(id)) {
+            inDegree.set(kid, (inDegree.get(kid) ?? 0) + 1);
+        }
+    }
+    for (const id of ids) {
+        if (inDegree.get(id) === 0) {
+            visit(id, "", "");
+        }
+    }
+    for (let root = ids.find((id) => !visited.has(id)); root !== undefined; root = ids.find((id) => !visited.has(id))) {
+        visit(root, "", "");
+    }
+    return tree;
+};

package/dist/session.js

@@ -6,6 +6,7 @@ import { githubForge } from "./forge/github.js";
 import { nodeFs } from "./fs-ctx.js";
 import { git as runGit } from "./git/exec.js";
 import { gitReader } from "./git/reader.js";
+import { painter } from "./output/paint.js";
 import { builtinPlugins } from "./plugins/index.js";
 export const createSession = (deps, opts) => {
     const root = resolve(deps.cwd, opts.cwd ?? ".");
@@ -69,8 +70,9 @@ export const createSession = (deps, opts) => {
             });
         },
         warn: (warnings) => {
+            const paint = painter(deps.stderr);
             for (const w of warnings) {
-                deps.stderr.write(`${w.code}: ${w.plugin ? `${w.plugin}: ` : ""}${w.message}\n`);
+                deps.stderr.write(`${paint("yellow", `warning[${w.code}]`)}: ${w.plugin ? `${w.plugin}: ` : ""}${w.message}\n`);
             }
         },
     };

package/dist/tallyrelease.schema.json

@@ -0,0 +1,163 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"type": "object",
+	"properties": {
+		"$schema": {
+			"type": "string",
+			"description": "Schema reference for editors, ignored."
+		},
+		"plugins": {
+			"default": {},
+			"type": "object",
+			"propertyNames": {
+				"type": "string"
+			},
+			"additionalProperties": {
+				"anyOf": [
+					{
+						"type": "object",
+						"propertyNames": {
+							"type": "string"
+						},
+						"additionalProperties": {}
+					},
+					{
+						"type": "null"
+					}
+				]
+			},
+			"description": "Enabled plugins and their options, run in the listed order. Only listed plugins run."
+		},
+		"defaults": {
+			"type": "object",
+			"properties": {
+				"release": {
+					"type": "boolean",
+					"description": "Release all units unless a unit sets release: false. Default false."
+				},
+				"tagFormat": {
+					"type": "string",
+					"description": "Tag template. Defaults to {id}-v{version}, or v{version} for the root unit."
+				},
+				"propagate": {
+					"type": "string",
+					"enum": [
+						"auto",
+						"patch",
+						"rebuild"
+					],
+					"description": "Policy for this unit when a dependency is released: patch (at least a patch bump), rebuild (rebuild only) or auto (patch if the edge is pinned, else rebuild)."
+				}
+			},
+			"additionalProperties": false,
+			"description": "Defaults applied to every unit."
+		},
+		"units": {
+			"type": "object",
+			"propertyNames": {
+				"type": "string"
+			},
+			"additionalProperties": {
+				"type": "object",
+				"properties": {
+					"id": {
+						"type": "string",
+						"description": "Unit id (letters, digits, dot, underscore, dash). Defaults to the discovered id, or the repo name for the root unit."
+					},
+					"include": {
+						"description": "Globs of files owned by the unit. Replaces the default (the unit root).",
+						"type": "array",
+						"items": {
+							"type": "string"
+						}
+					},
+					"exclude": {
+						"description": "Globs excluded from the unit, appended to the default (roots of nested units).",
+						"type": "array",
+						"items": {
+							"type": "string"
+						}
+					},
+					"release": {
+						"type": "boolean",
+						"description": "Whether the unit is versioned and tagged. Default false (build-only)."
+					},
+					"version": {
+						"type": "string",
+						"enum": [
+							"file",
+							"tag"
+						],
+						"description": "Where a released unit's version lives. file: version file written by the plugin. tag: git tags only. Defaults to the plugin's version source."
+					},
+					"scheme": {
+						"type": "string",
+						"description": "Versioning scheme. Defaults to semver."
+					},
+					"tagFormat": {
+						"type": "string",
+						"description": "Tag template. Defaults to {id}-v{version}, or v{version} for the root unit."
+					},
+					"propagate": {
+						"type": "string",
+						"enum": [
+							"auto",
+							"patch",
+							"rebuild"
+						],
+						"description": "Policy for this unit when a dependency is released: patch (at least a patch bump), rebuild (rebuild only) or auto (patch if the edge is pinned, else rebuild)."
+					}
+				},
+				"additionalProperties": false
+			},
+			"description": "Unit overlays keyed by root path. A root without a discovered unit becomes a config-only unit."
+		},
+		"deps": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"properties": {
+					"from": {
+						"type": "string",
+						"description": "Id of the dependency."
+					},
+					"to": {
+						"type": "string",
+						"description": "Id of the dependent unit."
+					},
+					"pinned": {
+						"type": "boolean",
+						"description": "Whether the dependent pins an exact version."
+					},
+					"reason": {
+						"type": "string",
+						"description": "Why the edge exists."
+					}
+				},
+				"required": [
+					"from",
+					"to"
+				],
+				"additionalProperties": false
+			},
+			"description": "Extra dependency edges between units."
+		},
+		"ignore": {
+			"description": "Globs of files that never affect any unit, for example docs.",
+			"type": "array",
+			"items": {
+				"type": "string"
+			}
+		},
+		"globalInputs": {
+			"description": "Globs of files whose change affects all units, unioned with plugin defaults.",
+			"type": "array",
+			"items": {
+				"type": "string"
+			}
+		}
+	},
+	"additionalProperties": false,
+	"$id": "https://cdn.jsdelivr.net/npm/@tallyrelease/cli@0/dist/tallyrelease.schema.json",
+	"title": "tallyrelease.yaml"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tallyrelease/cli",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.0-beta.5",
   "description": "Command line interface of tallyrelease",
   "repository": {
     "type": "git",
@@ -20,7 +20,8 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
-    "./affected.schema.json": "./dist/affected.schema.json"
+    "./affected.schema.json": "./dist/affected.schema.json",
+    "./tallyrelease.schema.json": "./dist/tallyrelease.schema.json"
   },
   "bin": {
     "tallyrelease": "./dist/bin.js"
@@ -47,7 +48,7 @@
   "prettier": "@abinnovision/prettier-config",
   "dependencies": {
     "@octokit/rest": "^22.0.1",
-    "@tallyrelease/core": "^0.1.0-beta.2",
+    "@tallyrelease/core": "^0.1.0-beta.3",
     "commander": "^15.0.0",
     "tinyglobby": "^0.2.17",
     "yaml": "^2.9.1",
@@ -59,6 +60,7 @@
     "@internal/tsconfig": "0.0.0",
     "@types/node": "^24.0.0",
     "@vitest/coverage-v8": "^5.0.3",
+    "ajv": "^8.20.0",
     "eslint": "^10.12.0",
     "prettier": "^3.9.9",
     "typescript": "^6.0.3",
@@ -76,7 +78,8 @@
         "import": "./dist/index.js",
         "default": "./dist/index.js"
       },
-      "./affected.schema.json": "./dist/affected.schema.json"
+      "./affected.schema.json": "./dist/affected.schema.json",
+      "./tallyrelease.schema.json": "./dist/tallyrelease.schema.json"
     },
     "npm": true
   }