@tiphys/kernel 0.0.0 → 0.1.0

package/dist/src/commands/spawn.js

@@ -0,0 +1,146 @@
+import { EX_USAGE } from "../cli.js";
+import { loadFleet } from "../fleet.js";
+import { warnIfWatcherStale } from "../liveness.js";
+import { spawnTask } from "../spawn.js";
+import { singleLine } from "../task.js";
+/**
+ * tiphys spawn --task <id> --project <path> --brief <file> --shape
+ * ship|scout --exec <cmd> [--deadline <seconds>] [--offline]
+ * (kernel plan v1, M1-P4 step 4). Runs in a fleet home (cwd).
+ *
+ * --exec is REQUIRED in M1: spawn without it exits 64 with usage,
+ * because the multiplexer-window adapter that would make an exec-less
+ * spawn meaningful is M4-era work (PR-013). The payload runs to
+ * completion before this command returns (plan constraint C-3: nothing
+ * is auto-backgrounded).
+ *
+ * --offline is passed through to pool create, and is a deviation from
+ * the plan's enumerated flag list, recorded in the M1-P4 work history:
+ * meta.json's baseOffline field (criterion 13 of M1-P3, this phase's
+ * named obligation) can only ever be true for a worktree created under
+ * pool create --offline, and spawn is the only command that creates the
+ * worktree a task's meta describes.
+ */
+const USAGE = "usage: tiphys spawn --task <id> --project <path> --brief <file> " +
+    "--shape ship|scout --exec <cmd> [--deadline <seconds>] [--offline]";
+function usageError(message) {
+    if (message !== undefined) {
+        process.stderr.write(`tiphys spawn: ${message}\n`);
+    }
+    process.stderr.write(`${USAGE}\n`);
+    return EX_USAGE;
+}
+function parseFlags(args) {
+    const parsed = {
+        task: undefined,
+        project: undefined,
+        brief: undefined,
+        shape: undefined,
+        exec: undefined,
+        deadlineSeconds: undefined,
+        offline: false,
+    };
+    for (let i = 0; i < args.length; i += 1) {
+        const flag = args[i];
+        const value = args[i + 1];
+        if (flag === "--task" && value !== undefined) {
+            parsed.task = value;
+            i += 1;
+        }
+        else if (flag === "--project" && value !== undefined) {
+            parsed.project = value;
+            i += 1;
+        }
+        else if (flag === "--brief" && value !== undefined) {
+            parsed.brief = value;
+            i += 1;
+        }
+        else if (flag === "--shape" && value !== undefined) {
+            if (value !== "ship" && value !== "scout") {
+                return undefined;
+            }
+            parsed.shape = value;
+            i += 1;
+        }
+        else if (flag === "--exec" && value !== undefined) {
+            parsed.exec = value;
+            i += 1;
+        }
+        else if (flag === "--deadline" && value !== undefined) {
+            const seconds = Number(value);
+            // N-403: finite and positive is not enough. The adapter turns the
+            // deadline into an instant, and any value at or above roughly
+            // 8.64e12 seconds is outside the Date range, so it used to raise
+            // INSIDE the adapter, after pool create had made a worktree, a
+            // branch and a pool record. A deadline this kernel cannot
+            // represent is a usage error, and a usage error creates nothing.
+            if (!Number.isFinite(seconds) ||
+                seconds <= 0 ||
+                !Number.isFinite(new Date(Date.now() + seconds * 1000).getTime())) {
+                return undefined;
+            }
+            parsed.deadlineSeconds = seconds;
+            i += 1;
+        }
+        else if (flag === "--offline") {
+            parsed.offline = true;
+        }
+        else {
+            return undefined;
+        }
+    }
+    return parsed;
+}
+export async function cmdSpawn(args) {
+    const flags = parseFlags(args);
+    if (flags === undefined) {
+        return usageError();
+    }
+    if (flags.task === undefined ||
+        flags.project === undefined ||
+        flags.brief === undefined ||
+        flags.shape === undefined) {
+        return usageError("spawn requires --task <id> --project <path> --brief <file> --shape ship|scout");
+    }
+    if (flags.exec === undefined) {
+        // PR-013: an exec-less spawn has no meaning in M1.
+        return usageError("spawn requires --exec <cmd> in M1");
+    }
+    let fleet;
+    try {
+        fleet = loadFleet(process.cwd());
+    }
+    catch (error) {
+        process.stderr.write(`tiphys spawn: ${singleLine(error.message)}\n`);
+        return 1;
+    }
+    // Liveness guard (M1-P5 step 2), completing the seam this phase left.
+    // It WARNS and never blocks: one stderr line when work is in flight
+    // and supervision has gone quiet, and the command then does exactly
+    // what it would have done anyway (blueprint liveness-guard contract,
+    // criteria 10 and 11).
+    warnIfWatcherStale(fleet);
+    const result = await spawnTask(fleet, {
+        taskId: flags.task,
+        project: flags.project,
+        briefFile: flags.brief,
+        shape: flags.shape,
+        exec: flags.exec,
+        deadlineSeconds: flags.deadlineSeconds,
+        offline: flags.offline,
+    });
+    if (!result.ok) {
+        // One reason line, structurally (CR-303): a reason may carry a
+        // raised error message or git output, and an operator or the M1-P6
+        // harness reading "the reason line" must get all of it.
+        process.stderr.write(`tiphys spawn: ${singleLine(result.reason)}\n`);
+        return 1;
+    }
+    // The payload's exit code is reported, not adopted: the task's state
+    // authority is meta.json plus the turn-end record (plan constraint
+    // C-1), and a nonzero payload is a completed task with a failing
+    // payload, not a failed spawn.
+    const { meta, exitCode } = result.value;
+    process.stdout.write(`spawned ${meta.id} worktree ${meta.worktree} exec exited ${String(exitCode)}\n`);
+    return 0;
+}

package/dist/src/commands/status.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `tiphys status <emit | show>` (kernel plan M3, M3-P1 step 6; R-084).
+ *
+ *   tiphys status emit --run <id> --state <state> [--project <name>]
+ *                      [--detail <text>] [--ref <r>]...
+ *   tiphys status show
+ *
+ * Runs in a fleet home (cwd). `emit` composes a record, VALIDATES it against
+ * the shipped `status-line` schema before writing anything, appends one line
+ * to `state/status/stream.jsonl`, then rewrites `state/status/current.json`
+ * atomically. `show` reads `current.json` ONLY and never opens the stream
+ * (constraint C-1: never read current state from the tail of an append-only
+ * log).
+ *
+ * The state vocabulary is closed and is enforced, not requested: `--state
+ * progress` is refused naming the permitted values, because R-084's
+ * sparseness is worth nothing if the emitter accepts whatever it is handed.
+ */
+export declare function cmdStatus(argv: string[]): number;

package/dist/src/commands/status.js

@@ -0,0 +1,120 @@
+/**
+ * `tiphys status <emit | show>` (kernel plan M3, M3-P1 step 6; R-084).
+ *
+ *   tiphys status emit --run <id> --state <state> [--project <name>]
+ *                      [--detail <text>] [--ref <r>]...
+ *   tiphys status show
+ *
+ * Runs in a fleet home (cwd). `emit` composes a record, VALIDATES it against
+ * the shipped `status-line` schema before writing anything, appends one line
+ * to `state/status/stream.jsonl`, then rewrites `state/status/current.json`
+ * atomically. `show` reads `current.json` ONLY and never opens the stream
+ * (constraint C-1: never read current state from the tail of an append-only
+ * log).
+ *
+ * The state vocabulary is closed and is enforced, not requested: `--state
+ * progress` is refused naming the permitted values, because R-084's
+ * sparseness is worth nothing if the emitter accepts whatever it is handed.
+ */
+import { basename } from "node:path";
+import { EX_USAGE } from "../cli.js";
+import { loadFleet } from "../fleet.js";
+import { loadTypeSchema } from "./validate.js";
+import { formatDiagnostics, validateInstance } from "../validate.js";
+import { STATUS_STATES, emitStatus, makeStatusRecord, readCurrent, renderStatus, } from "../status.js";
+const USAGE = "usage: tiphys status <emit --run <id> --state <" +
+    STATUS_STATES.join("|") +
+    "> [--project <name>] [--detail <text>] [--ref <r>] | show>";
+function parseEmit(argv) {
+    const args = { refs: [] };
+    for (let index = 0; index < argv.length; index += 1) {
+        const flag = argv[index];
+        const value = argv[index + 1];
+        if (flag !== "--run" &&
+            flag !== "--state" &&
+            flag !== "--project" &&
+            flag !== "--detail" &&
+            flag !== "--ref" &&
+            flag !== "--at") {
+            return { usageError: `unknown option ${flag}` };
+        }
+        if (value === undefined) {
+            return { usageError: `${flag} requires a value` };
+        }
+        index += 1;
+        if (flag === "--run")
+            args.run = value;
+        else if (flag === "--state")
+            args.state = value;
+        else if (flag === "--project")
+            args.project = value;
+        else if (flag === "--detail")
+            args.detail = value;
+        else if (flag === "--at")
+            args.at = value;
+        else
+            args.refs.push(value);
+    }
+    if (args.run === undefined) {
+        return { usageError: "--run is required" };
+    }
+    if (args.state === undefined) {
+        return { usageError: "--state is required" };
+    }
+    return { args };
+}
+export function cmdStatus(argv) {
+    const [subcommand, ...rest] = argv;
+    if (subcommand === "show") {
+        if (rest.length > 0) {
+            process.stderr.write(`tiphys status show: takes no arguments\n${USAGE}\n`);
+            return EX_USAGE;
+        }
+        const fleet = loadFleet(process.cwd());
+        const current = readCurrent(fleet.root);
+        if (!current.ok) {
+            process.stderr.write(`tiphys status show: ${current.reason}\n`);
+            return 1;
+        }
+        process.stdout.write(`${renderStatus(current.record)}\n`);
+        return 0;
+    }
+    if (subcommand !== "emit") {
+        process.stderr.write(`${USAGE}\n`);
+        return EX_USAGE;
+    }
+    const parsed = parseEmit(rest);
+    if (parsed.args === undefined) {
+        process.stderr.write(`tiphys status emit: ${parsed.usageError ?? "usage error"}\n${USAGE}\n`);
+        return EX_USAGE;
+    }
+    const fleet = loadFleet(process.cwd());
+    const record = makeStatusRecord({
+        run: parsed.args.run,
+        project: parsed.args.project ?? basename(fleet.root),
+        state: parsed.args.state,
+        detail: parsed.args.detail,
+        refs: parsed.args.refs,
+        at: parsed.args.at,
+    });
+    /* The record is validated against the SHIPPED schema before anything is
+       written. Validating a composed record against the same document the
+       validator command uses is what makes the closed state vocabulary one
+       rule rather than two: `--state progress` fails here for exactly the
+       reason it would fail `tiphys validate --type status-line`. */
+    const diagnostics = validateInstance(loadTypeSchema("status-line"), record);
+    if (diagnostics.length > 0) {
+        for (const line of formatDiagnostics(diagnostics)) {
+            process.stderr.write(`${line}\n`);
+        }
+        process.stderr.write(`tiphys status emit: the permitted states are ${STATUS_STATES.join(", ")}\n`);
+        return 1;
+    }
+    const emitted = emitStatus(fleet.root, record);
+    if (!emitted.ok) {
+        process.stderr.write(`tiphys status emit: ${emitted.reason}\n`);
+        return 1;
+    }
+    process.stdout.write(`${renderStatus(emitted.record)}\n`);
+    return 0;
+}

package/dist/src/commands/teardown.d.ts

@@ -0,0 +1 @@
+export declare function cmdTeardown(args: string[]): Promise<number>;

package/dist/src/commands/teardown.js

@@ -0,0 +1,79 @@
+import { EX_USAGE } from "../cli.js";
+import { loadFleet } from "../fleet.js";
+import { warnIfWatcherStale } from "../liveness.js";
+import { singleLine } from "../task.js";
+import { teardownTask } from "../teardown.js";
+/**
+ * tiphys teardown --task <id> [--salvage] (kernel plan v1, M1-P4
+ * step 5). Runs in a fleet home (cwd).
+ *
+ * Every refusal is exit nonzero plus a SINGLE reason line naming the
+ * blocking condition. A failure of the destroy itself is passed through
+ * with the pool's own wording, which distinguishes a refusal (a true
+ * no-op) from a partial failure (the worktree is already gone and the
+ * survivors are enumerated); this command adds no framing of its own to
+ * either, because the two must never be described alike.
+ */
+const USAGE = "usage: tiphys teardown --task <id> [--salvage]";
+function usageError(message) {
+    if (message !== undefined) {
+        process.stderr.write(`tiphys teardown: ${message}\n`);
+    }
+    process.stderr.write(`${USAGE}\n`);
+    return EX_USAGE;
+}
+function parseFlags(args) {
+    const parsed = { task: undefined, salvage: false };
+    for (let i = 0; i < args.length; i += 1) {
+        const flag = args[i];
+        const value = args[i + 1];
+        if (flag === "--task" && value !== undefined) {
+            parsed.task = value;
+            i += 1;
+        }
+        else if (flag === "--salvage") {
+            parsed.salvage = true;
+        }
+        else {
+            return undefined;
+        }
+    }
+    return parsed;
+}
+export async function cmdTeardown(args) {
+    const flags = parseFlags(args);
+    if (flags === undefined) {
+        return usageError();
+    }
+    if (flags.task === undefined) {
+        return usageError("teardown requires --task <id>");
+    }
+    let fleet;
+    try {
+        fleet = loadFleet(process.cwd());
+    }
+    catch (error) {
+        process.stderr.write(`tiphys teardown: ${singleLine(error.message)}\n`);
+        return 1;
+    }
+    // Liveness guard (M1-P5 step 2): one stderr warning line when work is
+    // in flight and supervision has gone quiet, and then the teardown
+    // proceeds exactly as it would have. It never blocks and never changes
+    // an exit code (criteria 10 and 11).
+    warnIfWatcherStale(fleet);
+    const result = await teardownTask(fleet, {
+        taskId: flags.task,
+        salvage: flags.salvage,
+    });
+    if (!result.ok) {
+        // Plan step 5: "every refusal is exit nonzero plus a single reason
+        // line". Enforced here structurally (CR-303) rather than trusted of
+        // every reason string, because reasons interpolate git output and a
+        // raised error message, neither of which is guaranteed to be short.
+        process.stderr.write(`tiphys teardown: ${singleLine(result.reason)}\n`);
+        return 1;
+    }
+    const suffix = result.value.salvaged ? " (leavings salvaged and pushed)" : "";
+    process.stdout.write(`torn down ${result.value.taskId}${suffix}\n`);
+    return 0;
+}

package/dist/src/commands/tuition.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `tiphys tuition add|list|index` (kernel plan M3, M3-P8 steps 2 and 6;
+ * R-091).
+ *
+ *   add --file <entry> [--into <dir>]   validate an entry and file it
+ *   list [--kernel-relevant] [--dir <d>] one line per entry
+ *   index [--out <f>] [--check] [--dir <d>]  project the mechanism index
+ *
+ * PROMOTION IS NOT A SUBCOMMAND, and that is a decision rather than an
+ * omission. R-091 says kernel-relevant tuition ships upstream as a kernel pull
+ * request; the kernel never opens pull requests, so promotion is a documented
+ * orchestrator procedure (M3-P9's `AGENTS.md`) and building a promoter that M3
+ * would use once is the M1-P3 mistake.
+ *
+ * `add` WRITES WITH AN EXCLUSIVE CREATE, so a second entry claiming an id that
+ * already exists fails loudly and names the file rather than overwriting a
+ * record. A `T-nnn` id is never renumbered and never reused after retirement,
+ * which makes an overwrite a silent loss of exactly the artifact this feed
+ * exists to keep.
+ */
+export declare function cmdTuition(argv: string[]): number;

package/dist/src/commands/tuition.js

@@ -0,0 +1,218 @@
+/**
+ * `tiphys tuition add|list|index` (kernel plan M3, M3-P8 steps 2 and 6;
+ * R-091).
+ *
+ *   add --file <entry> [--into <dir>]   validate an entry and file it
+ *   list [--kernel-relevant] [--dir <d>] one line per entry
+ *   index [--out <f>] [--check] [--dir <d>]  project the mechanism index
+ *
+ * PROMOTION IS NOT A SUBCOMMAND, and that is a decision rather than an
+ * omission. R-091 says kernel-relevant tuition ships upstream as a kernel pull
+ * request; the kernel never opens pull requests, so promotion is a documented
+ * orchestrator procedure (M3-P9's `AGENTS.md`) and building a promoter that M3
+ * would use once is the M1-P3 mistake.
+ *
+ * `add` WRITES WITH AN EXCLUSIVE CREATE, so a second entry claiming an id that
+ * already exists fails loudly and names the file rather than overwriting a
+ * record. A `T-nnn` id is never renumbered and never reused after retirement,
+ * which makes an overwrite a silent loss of exactly the artifact this feed
+ * exists to keep.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { EX_USAGE } from "../cli.js";
+import { refuseOpenForWrite } from "../task.js";
+import { decodeDocument, readOperatorPath } from "../validate.js";
+import { MECHANISM_INDEX_FILE, driftLines, listEntryFiles, loadEntry, projectIndex, renderIndex, } from "../tuition.js";
+const USAGE = "usage: tiphys tuition add --file <entry> [--into <dir>] | " +
+    "tiphys tuition list [--kernel-relevant] [--dir <dir>] | " +
+    "tiphys tuition index [--out <file>] [--check] [--dir <dir>]";
+function parseArgs(argv) {
+    const options = { check: false, kernelRelevant: false };
+    const valued = new Map([
+        ["--file", "file"],
+        ["--into", "into"],
+        ["--dir", "dir"],
+        ["--out", "out"],
+    ]);
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === "--check") {
+            options.check = true;
+            continue;
+        }
+        if (argument === "--kernel-relevant") {
+            options.kernelRelevant = true;
+            continue;
+        }
+        const field = valued.get(argument);
+        if (field === undefined) {
+            return { usageError: `unknown option ${argument}` };
+        }
+        const value = argv[index + 1];
+        if (value === undefined || value.startsWith("--")) {
+            return { usageError: `${argument} requires a value` };
+        }
+        options[field] = value;
+        index += 1;
+    }
+    return { options };
+}
+/** The feed directory a subcommand works in: `--dir`, else `<cwd>/tuition`. */
+function feedDirectory(options) {
+    return options.dir ?? join(process.cwd(), "tuition");
+}
+/** Load every entry in the feed, reporting the first that does not validate. */
+function loadFeed(directory) {
+    const listing = listEntryFiles(directory);
+    if (!listing.ok) {
+        process.stderr.write(`tiphys tuition: ${listing.reason}\n`);
+        return { ok: false };
+    }
+    const entries = [];
+    let failed = false;
+    for (const path of listing.paths) {
+        const loaded = loadEntry(path);
+        if (!loaded.ok) {
+            process.stderr.write(`tiphys tuition: ${loaded.reason}\n`);
+            for (const line of loaded.diagnostics) {
+                process.stdout.write(`${line}\n`);
+            }
+            failed = true;
+            continue;
+        }
+        entries.push(loaded.entry);
+    }
+    return failed ? { ok: false } : { ok: true, entries };
+}
+function cmdAdd(options) {
+    if (options.file === undefined) {
+        process.stderr.write(`tiphys tuition: --file is required\n${USAGE}\n`);
+        return EX_USAGE;
+    }
+    /* VALIDATE FIRST, WRITE SECOND. An invalid entry must leave the feed
+       directory byte-identical, which is criterion 7's own test. */
+    const loaded = loadEntry(options.file);
+    if (!loaded.ok) {
+        process.stderr.write(`tiphys tuition: ${loaded.reason}\n`);
+        for (const line of loaded.diagnostics) {
+            process.stdout.write(`${line}\n`);
+        }
+        return 1;
+    }
+    const directory = options.into ?? join(process.cwd(), "tuition");
+    const target = join(directory, `${loaded.entry.id}.yaml`);
+    const refusal = refuseOpenForWrite(target);
+    if (refusal !== undefined) {
+        process.stderr.write(`tiphys tuition: ${refusal}\n`);
+        return 1;
+    }
+    try {
+        mkdirSync(directory, { recursive: true });
+        /* EXCLUSIVE CREATE: an id already in the feed is a loud refusal, never an
+           overwrite. Ids are never reused, so the collision is the fault. */
+        writeFileSync(target, loaded.body, { flag: "wx" });
+    }
+    catch (error) {
+        const code = error.code;
+        process.stderr.write(code === "EEXIST"
+            ? `tiphys tuition: ${target} already exists, and a tuition id is never reused\n`
+            : `tiphys tuition: ${target} could not be written: ${String(error)}\n`);
+        return 1;
+    }
+    process.stdout.write(`added ${loaded.entry.id} to ${target}\n`);
+    return 0;
+}
+function cmdList(options) {
+    const feed = loadFeed(feedDirectory(options));
+    if (!feed.ok) {
+        return 1;
+    }
+    for (const entry of feed.entries) {
+        if (options.kernelRelevant && !entry["kernel-relevant"]) {
+            continue;
+        }
+        const targets = entry["structural-consequence"]?.length ?? 0;
+        process.stdout.write(`${entry.id} ${entry.date} targets=${String(targets)}\n`);
+    }
+    return 0;
+}
+function cmdIndex(options) {
+    const directory = feedDirectory(options);
+    const feed = loadFeed(directory);
+    if (!feed.ok) {
+        return 1;
+    }
+    const projection = projectIndex(feed.entries);
+    if (!projection.ok) {
+        process.stderr.write(`tiphys tuition: ${projection.reason}\n`);
+        return 1;
+    }
+    const rendered = renderIndex(projection.rows);
+    const out = options.out ?? join(directory, MECHANISM_INDEX_FILE);
+    if (options.check) {
+        const read = readOperatorPath(out);
+        if (!read.ok) {
+            process.stderr.write(`tiphys tuition: ${read.reason}\n`);
+            return 1;
+        }
+        const decoded = decodeDocument(read.body, out);
+        if (!decoded.ok) {
+            process.stderr.write(`tiphys tuition: ${decoded.reason}\n`);
+            return 1;
+        }
+        const problems = driftLines(decoded.value, projection.rows);
+        for (const problem of problems) {
+            process.stdout.write(`DRIFT ${problem}\n`);
+        }
+        if (problems.length > 0) {
+            process.stderr.write(`tiphys tuition: ${basename(out)} is not the projection of the feed in ${directory}\n`);
+            return 1;
+        }
+        /* THE BYTE COMPARISON IS SEPARATE AND SECOND. The structural diff above
+           names WHICH mechanism drifted, which a byte comparison cannot; this
+           catches a hand edit that changed nothing a reader of the decoded
+           document would see (a reordering, a rewrap, an added comment) and says
+           so in those words rather than claiming a rule changed. */
+        if (read.body !== rendered) {
+            process.stdout.write(`DRIFT ${out} decodes to the projection and its bytes differ from it, so it has been hand-edited\n`);
+            process.stderr.write(`tiphys tuition: ${basename(out)} is generated; regenerate it with tiphys tuition index\n`);
+            return 1;
+        }
+        process.stdout.write(`${String(projection.rows.length)} mechanism(s) projected from ${String(feed.entries.length)} entr(ies); the committed index matches\n`);
+        return 0;
+    }
+    const refusal = refuseOpenForWrite(out);
+    if (refusal !== undefined) {
+        process.stderr.write(`tiphys tuition: ${refusal}\n`);
+        return 1;
+    }
+    try {
+        writeFileSync(out, rendered);
+    }
+    catch (error) {
+        process.stderr.write(`tiphys tuition: ${out} could not be written: ${String(error)}\n`);
+        return 1;
+    }
+    process.stdout.write(`wrote ${String(projection.rows.length)} mechanism(s) from ${String(feed.entries.length)} entr(ies) to ${out}\n`);
+    return 0;
+}
+export function cmdTuition(argv) {
+    const [subcommand, ...rest] = argv;
+    const parsed = parseArgs(rest);
+    if (parsed.options === undefined) {
+        process.stderr.write(`tiphys tuition: ${parsed.usageError ?? "usage error"}\n${USAGE}\n`);
+        return EX_USAGE;
+    }
+    if (subcommand === "add") {
+        return cmdAdd(parsed.options);
+    }
+    if (subcommand === "list") {
+        return cmdList(parsed.options);
+    }
+    if (subcommand === "index") {
+        return cmdIndex(parsed.options);
+    }
+    process.stderr.write(`tiphys tuition: ${subcommand === undefined ? "a subcommand is required" : `unknown subcommand ${subcommand}`}\n${USAGE}\n`);
+    return EX_USAGE;
+}