@bunizao/cli-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bunizao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# @bunizao/cli-kit
+
+Small shared primitives for the `ontrack`, `moodle`, and `edstem` command-line tools. The package
+owns their stable command contract: verbs, error codes, exit codes, output formats, mutation
+confirmation, and command self-description.
+
+## Install
+
+```sh
+npm install https://codeload.github.com/bunizao/cli-kit/tar.gz/refs/tags/v0.1.0 commander
+```
+
+After the registry release, consumers can switch to the versioned package:
+
+```sh
+npm install @bunizao/cli-kit commander
+```
+
+Node.js 18 or newer is supported. Individual CLIs may require a newer runtime.
+
+## Program setup
+
+```ts
+import {
+  commandsJson,
+  createProgram,
+  insertDefaultVerb,
+  mutating,
+  type NounSpec,
+} from "@bunizao/cli-kit";
+
+const program = createProgram({
+  name: "example",
+  version: "1.0.0",
+  description: "Example CLI",
+});
+
+const units = program.command("units").aliases(["courses", "projects"]);
+units.command("list").action(listUnits);
+units.command("show <unit>").action(showUnit);
+mutating(units.command("set <unit> <state>")).action(setUnitState);
+
+const nouns: readonly NounSpec[] = [
+  {
+    name: "units",
+    aliases: ["courses", "projects"],
+    verbs: ["list", "show", "set"],
+    defaultByArity: { 0: "list", 1: "show" },
+    valueFlags: [],
+  },
+];
+
+const args = insertDefaultVerb(process.argv.slice(2), nouns);
+await program.parseAsync(args, { from: "user" });
+```
+
+`insertDefaultVerb` accepts user arguments, not the Node executable and script prefix. It is a
+pure transform and does not mutate the provided array.
+
+List option flags that consume a separate value in `valueFlags`. This lets the arity counter ignore
+option values when flags are interleaved with positionals. Boolean flags and `--flag=value` do not
+need to be listed.
+
+## Output and errors
+
+`resolveFormat` applies explicit `--json`, `--yaml`, or `--table` flags, then defaults to `table`
+for a TTY and `json` for a pipe. `render` serializes a value and can select top-level fields.
+`writeOutput` writes to stdout or a file and treats a closed stdout pipe as successful.
+
+Catch errors at the executable boundary and render them once:
+
+```ts
+const format = resolveFormat(program.opts(), process.stdout.isTTY === true);
+
+try {
+  await program.parseAsync(args, { from: "user" });
+} catch (error) {
+  const isNormalExit = typeof error === "object" && error && "exitCode" in error && error.exitCode === 0;
+  if (!isNormalExit) {
+    const reported = reportError(error, format);
+    process.stderr.write(reported.text);
+    process.exitCode = reported.exitCode;
+  }
+}
+```
+
+Commander error text is suppressed by `createProgram`, so the shared reporter is the only error
+renderer. Help and version requests render normally, then throw Commander's zero-exit signal;
+preserve that status without reporting it. Usage failures throw for the boundary to report once.
+
+## Mutations
+
+Call `mutating(command)` for `send`, `submit`, `set`, and `mark-read` commands. The marker is
+included by `commandsJson`. Command actions call `confirm` before making an upstream request:
+
+```ts
+const shouldApply = await confirm(
+  { summary: "Set FIT1045 task 1.1 to complete" },
+  { yes: options.yes, dryRun: options.dryRun, interactive: process.stdin.isTTY === true },
+);
+
+if (!shouldApply) return;
+```
+
+The plan and prompt are written to stderr. A non-interactive mutation without `--yes` throws a
+`usage` error. A dry run prints its plan and returns `false`.
+
+## Command description
+
+`commandsJson(program)` returns the program metadata and full command tree. Every node includes
+aliases, positional arguments, options, enum values, nested commands, and `mutating`. Domain
+commands at noun depth must use a verb exported in `VERBS`; unsupported verbs throw. `auth` and
+`skills` are action groups rather than domain nouns and are not assigned a `verb` field.
+
+The exit-code table, error vocabulary, and verb set are public versioned API. Changing one requires
+a major package release.
+
+The conformance suite is isolated under `conformance/`. Until all three CLIs have published their
+normalized releases, missing binaries are reported as skipped tests. Its CI workflow installs the
+published packages before running the suite.

package/dist/confirm.d.ts

@@ -0,0 +1,8 @@
+export interface MutationPlan {
+    readonly summary: string;
+}
+export declare function confirm(plan: MutationPlan, options: {
+    yes: boolean;
+    dryRun: boolean;
+    interactive: boolean;
+}): Promise<boolean>;

package/dist/confirm.js

@@ -0,0 +1,22 @@
+import { createInterface } from "node:readline/promises";
+import { CliError } from "./errors.js";
+export async function confirm(plan, options) {
+    if (options.dryRun) {
+        process.stderr.write(`${plan.summary}\n`);
+        return false;
+    }
+    if (options.yes)
+        return true;
+    if (!options.interactive) {
+        throw new CliError("usage", "Mutation requires --yes when stdin is not interactive.");
+    }
+    process.stderr.write(`${plan.summary}\n`);
+    const prompt = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = await prompt.question("Continue? y/N ");
+        return answer.trim().toLowerCase() === "y";
+    }
+    finally {
+        prompt.close();
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,10 @@
+export declare const ERROR_CODES: readonly ["usage", "auth", "config", "not_found", "upstream", "network", "cancelled", "unexpected"];
+export type ErrorCode = (typeof ERROR_CODES)[number];
+export declare const EXIT_CODES: Readonly<Record<ErrorCode, number>>;
+export declare class CliError extends Error {
+    readonly code: ErrorCode;
+    readonly hint: string | undefined;
+    constructor(code: ErrorCode, message: string, hint?: string);
+}
+export declare function exitCodeFor(code: ErrorCode): number;
+export declare function normalizeError(error: unknown): CliError;

package/dist/errors.js

@@ -0,0 +1,51 @@
+export const ERROR_CODES = [
+    "usage",
+    "auth",
+    "config",
+    "not_found",
+    "upstream",
+    "network",
+    "cancelled",
+    "unexpected",
+];
+export const EXIT_CODES = Object.freeze({
+    usage: 2,
+    auth: 3,
+    config: 1,
+    not_found: 4,
+    upstream: 5,
+    network: 1,
+    cancelled: 130,
+    unexpected: 1,
+});
+export class CliError extends Error {
+    code;
+    hint;
+    constructor(code, message, hint) {
+        super(message);
+        this.name = "CliError";
+        this.code = code;
+        this.hint = hint;
+    }
+}
+export function exitCodeFor(code) {
+    return EXIT_CODES[code];
+}
+export function normalizeError(error) {
+    if (error instanceof CliError)
+        return error;
+    if (error instanceof Error) {
+        const candidate = error;
+        if (typeof candidate.code === "string" && candidate.code.startsWith("commander.")) {
+            return new CliError("usage", error.message.replace(/^error:\s*/i, ""));
+        }
+        if (error.name === "AbortError")
+            return new CliError("cancelled", "Operation cancelled.");
+        if (typeof candidate.code === "string" && NETWORK_CODES.has(candidate.code)) {
+            return new CliError("network", error.message);
+        }
+        return new CliError("unexpected", error.message);
+    }
+    return new CliError("unexpected", String(error));
+}
+const NETWORK_CODES = new Set(["ECONNREFUSED", "ECONNRESET", "ENETUNREACH", "ETIMEDOUT", "EAI_AGAIN"]);

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./confirm.js";
+export * from "./errors.js";
+export * from "./nouns.js";
+export * from "./output.js";
+export * from "./program.js";
+export * from "./report.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from "./confirm.js";
+export * from "./errors.js";
+export * from "./nouns.js";
+export * from "./output.js";
+export * from "./program.js";
+export * from "./report.js";

package/dist/nouns.d.ts

@@ -0,0 +1,9 @@
+export interface NounSpec {
+    readonly name: string;
+    readonly aliases?: readonly string[];
+    readonly verbs: readonly string[];
+    readonly defaultByArity: Readonly<Record<number, string>>;
+    /** Option flags whose following token is a value, not a positional argument. */
+    readonly valueFlags?: readonly string[];
+}
+export declare function insertDefaultVerb(argv: readonly string[], nouns: readonly NounSpec[]): string[];

package/dist/nouns.js

@@ -0,0 +1,57 @@
+const GLOBAL_VALUE_FLAGS = new Set(["--fields", "-o", "--output"]);
+export function insertDefaultVerb(argv, nouns) {
+    const result = [...argv];
+    const nounIndex = findNounIndex(result, nouns);
+    if (nounIndex === -1)
+        return result;
+    const spec = nouns.find((noun) => noun.name === result[nounIndex] || noun.aliases?.includes(result[nounIndex] ?? ""));
+    if (!spec)
+        return result;
+    result[nounIndex] = spec.name;
+    const next = result[nounIndex + 1];
+    if (next && spec.verbs.includes(next))
+        return result;
+    if (result.includes("--help") || result.includes("-h"))
+        return result;
+    const arity = countPositionals(result.slice(nounIndex + 1), spec.valueFlags ?? []);
+    const verb = spec.defaultByArity[arity];
+    if (!verb)
+        return result;
+    result.splice(nounIndex + 1, 0, verb);
+    return result;
+}
+function findNounIndex(argv, nouns) {
+    const names = new Set(nouns.flatMap((noun) => [noun.name, ...(noun.aliases ?? [])]));
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (!token)
+            continue;
+        if (GLOBAL_VALUE_FLAGS.has(token)) {
+            index += 1;
+            continue;
+        }
+        if (token.startsWith("-"))
+            continue;
+        return names.has(token) ? index : -1;
+    }
+    return -1;
+}
+function countPositionals(argv, valueFlags) {
+    const flagsWithValues = new Set([...GLOBAL_VALUE_FLAGS, ...valueFlags]);
+    let count = 0;
+    let terminated = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === "--") {
+            terminated = true;
+            continue;
+        }
+        if (!terminated && token && flagsWithValues.has(token)) {
+            index += 1;
+            continue;
+        }
+        if (terminated || (token && !token.startsWith("-")))
+            count += 1;
+    }
+    return count;
+}

package/dist/output.d.ts

@@ -0,0 +1,16 @@
+export type OutputFormat = "table" | "json" | "yaml";
+export interface FormatOptions {
+    readonly json?: boolean;
+    readonly yaml?: boolean;
+    readonly table?: boolean;
+    readonly fields?: string;
+}
+export declare function resolveFormat(options: FormatOptions, isTty: boolean): OutputFormat;
+export declare function render(value: unknown, options: {
+    format: OutputFormat;
+    fields?: readonly string[];
+    columns?: readonly [string, string][];
+}): string;
+export declare function writeOutput(text: string, options: {
+    output?: string;
+}): Promise<void>;

package/dist/output.js

@@ -0,0 +1,63 @@
+import { writeFile } from "node:fs/promises";
+import { stringify as stringifyYaml } from "yaml";
+import { CliError } from "./errors.js";
+export function resolveFormat(options, isTty) {
+    const selected = [options.json && "json", options.yaml && "yaml", options.table && "table"].filter(Boolean);
+    if (selected.length > 1) {
+        throw new CliError("usage", "--json, --yaml, and --table are mutually exclusive.");
+    }
+    return selected[0] ?? (isTty ? "table" : "json");
+}
+export function render(value, options) {
+    const filtered = options.fields?.length ? selectFields(value, options.fields) : value;
+    if (options.format === "json")
+        return `${JSON.stringify(filtered, null, 2)}\n`;
+    if (options.format === "yaml")
+        return stringifyYaml(filtered);
+    return renderTable(filtered, options.columns);
+}
+export async function writeOutput(text, options) {
+    if (options.output) {
+        await writeFile(options.output, text, "utf8");
+        return;
+    }
+    await new Promise((resolve, reject) => {
+        const onError = (error) => finish(error);
+        const finish = (error) => {
+            process.stdout.off("error", onError);
+            if (!error || error.code === "EPIPE")
+                resolve();
+            else
+                reject(error);
+        };
+        process.stdout.once("error", onError);
+        process.stdout.write(text, finish);
+    });
+}
+function selectFields(value, fields) {
+    if (Array.isArray(value))
+        return value.map((item) => selectFields(item, fields));
+    if (!isRecord(value))
+        return value;
+    return Object.fromEntries(fields.filter((field) => field in value).map((field) => [field, value[field]]));
+}
+function renderTable(value, columns) {
+    const rows = Array.isArray(value) ? value : [value];
+    if (rows.length === 0)
+        return "";
+    if (!rows.every(isRecord))
+        return `${rows.map(String).join("\n")}\n`;
+    const selected = columns ?? Object.keys(rows[0] ?? {}).map((key) => [key, key]);
+    const values = rows.map((row) => selected.map(([key]) => formatCell(row[key])));
+    const widths = selected.map(([, label], index) => Math.max(label.length, ...values.map((row) => row[index]?.length ?? 0)));
+    const line = (cells) => cells.map((cell, index) => cell.padEnd(widths[index] ?? 0)).join("  ").trimEnd();
+    return `${line(selected.map(([, label]) => label))}\n${values.map(line).join("\n")}\n`;
+}
+function formatCell(value) {
+    if (value === null || value === undefined)
+        return "";
+    return typeof value === "object" ? JSON.stringify(value) : String(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/program.d.ts

@@ -0,0 +1,40 @@
+import { Command } from "commander";
+export declare const VERBS: readonly ["list", "show", "read", "get", "search", "send", "submit", "set", "mark-read"];
+export interface CommandDescription {
+    readonly name: string;
+    readonly noun?: string;
+    readonly verb?: string;
+    readonly aliases: readonly string[];
+    readonly description: string;
+    readonly positionals: readonly PositionalDescription[];
+    readonly options: readonly OptionDescription[];
+    readonly mutating: boolean;
+    readonly commands: readonly CommandDescription[];
+}
+export interface PositionalDescription {
+    readonly name: string;
+    readonly description: string;
+    readonly required: boolean;
+    readonly variadic: boolean;
+    readonly enumValues?: readonly string[];
+}
+export interface OptionDescription {
+    readonly flags: string;
+    readonly description: string;
+    readonly required: boolean;
+    readonly variadic: boolean;
+    readonly enumValues?: readonly string[];
+}
+export interface ProgramDescription {
+    readonly name: string;
+    readonly version: string;
+    readonly description: string;
+    readonly commands: readonly CommandDescription[];
+}
+export declare function createProgram(meta: {
+    name: string;
+    version: string;
+    description: string;
+}): Command;
+export declare function mutating(command: Command): Command;
+export declare function commandsJson(program: Command): ProgramDescription;

package/dist/program.js

@@ -0,0 +1,81 @@
+import { Command } from "commander";
+export const VERBS = ["list", "show", "read", "get", "search", "send", "submit", "set", "mark-read"];
+const VERB_SET = new Set(VERBS);
+const mutations = new WeakSet();
+const ACTION_GROUPS = new Set(["auth", "skills"]);
+const ACTIONS = {
+    auth: new Set(["install", "uninstall", "login", "status", "logout", "keepalive"]),
+    skills: new Set(["generate", "add"]),
+};
+export function createProgram(meta) {
+    return new Command()
+        .name(meta.name)
+        .version(meta.version, "-V, --version")
+        .description(meta.description)
+        .helpOption("-h, --help")
+        .addHelpCommand(true)
+        .showSuggestionAfterError()
+        .exitOverride()
+        .configureOutput({ outputError: () => undefined })
+        .option("--json", "Emit JSON")
+        .option("--yaml", "Emit YAML")
+        .option("--table", "Emit a human-readable table")
+        .option("--fields <fields>", "Select top-level fields")
+        .option("-o, --output <file>", "Write output to a file")
+        .option("-q, --quiet", "Suppress non-essential diagnostics")
+        .option("--verbose", "Enable debug logging")
+        .option("--no-color", "Disable color output")
+        .option("-y, --yes", "Confirm mutations non-interactively")
+        .option("--dry-run", "Print the mutation plan without applying it");
+}
+export function mutating(command) {
+    mutations.add(command);
+    return command;
+}
+export function commandsJson(program) {
+    return {
+        name: program.name(),
+        version: program.version() ?? "",
+        description: program.description(),
+        commands: program.commands.filter((command) => command.name() !== "help").map((command) => describe(command)),
+    };
+}
+function describe(command, noun) {
+    const currentNoun = noun ?? command.name();
+    const verb = noun && !ACTION_GROUPS.has(noun) ? command.name() : undefined;
+    if (noun && ACTION_GROUPS.has(noun) && !ACTIONS[noun]?.has(command.name())) {
+        throw new Error(`Unsupported action "${command.name()}" on group "${noun}".`);
+    }
+    if (verb && !VERB_SET.has(verb)) {
+        throw new Error(`Unsupported verb "${verb}" on noun "${noun}".`);
+    }
+    return {
+        name: command.name(),
+        noun: currentNoun,
+        ...(verb ? { verb } : {}),
+        aliases: command.aliases(),
+        description: command.description(),
+        positionals: command.registeredArguments.map(describeArgument),
+        options: command.options.map(describeOption),
+        mutating: mutations.has(command),
+        commands: command.commands.filter((child) => child.name() !== "help").map((child) => describe(child, currentNoun)),
+    };
+}
+function describeArgument(argument) {
+    return {
+        name: argument.name(),
+        description: argument.description,
+        required: argument.required,
+        variadic: argument.variadic,
+        ...(argument.argChoices ? { enumValues: argument.argChoices } : {}),
+    };
+}
+function describeOption(option) {
+    return {
+        flags: option.flags,
+        description: option.description,
+        required: option.required,
+        variadic: option.variadic,
+        ...(option.argChoices ? { enumValues: option.argChoices } : {}),
+    };
+}

package/dist/report.d.ts

@@ -0,0 +1,5 @@
+import type { OutputFormat } from "./output.js";
+export declare function reportError(error: unknown, format: OutputFormat): {
+    readonly text: string;
+    readonly exitCode: number;
+};

package/dist/report.js

@@ -0,0 +1,23 @@
+import { stringify as stringifyYaml } from "yaml";
+import { exitCodeFor, normalizeError } from "./errors.js";
+export function reportError(error, format) {
+    const normalized = normalizeError(error);
+    const exitCode = exitCodeFor(normalized.code);
+    if (format === "table") {
+        const hint = normalized.hint ? `\nhint: ${normalized.hint}` : "";
+        return { text: `error: ${normalized.message}${hint}\n`, exitCode };
+    }
+    const envelope = {
+        ok: false,
+        error: {
+            code: normalized.code,
+            message: normalized.message,
+            ...(normalized.hint ? { hint: normalized.hint } : {}),
+        },
+        exit_code: exitCode,
+    };
+    return {
+        text: format === "json" ? `${JSON.stringify(envelope, null, 2)}\n` : stringifyYaml(envelope),
+        exitCode,
+    };
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@bunizao/cli-kit",
+  "version": "0.1.0",
+  "description": "Shared command-line contract for Bunizao CLI tools",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test test/*.test.js",
+    "test:conformance": "npm --prefix conformance test",
+    "prepack": "npm test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "yaml": "^2.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "^5.8.3"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bunizao/cli-kit.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}