@kisev/agentomatic 11.0.0-dev.70.g8d00098df14b → 11.0.0-dev.71.gee4e37a5bb61

package/dist/cli.js

@@ -9,123 +9,114 @@ import { LifecycleError } from "./lifecycle.js";
 import { skillsInstallerSpec } from "./package-metadata.js";
 import { applyReconcile, previewReconcile } from "./reconcile.js";
 import { confirmQuestion, promptText, selectOption, selectOptions } from "./terminal-wizard.js";
+import { Command, Option, common, applyConfig, configFileSync, reporter } from "./generated/cli.js";
+let diagnostics;
+let machineOutput = false;
+let diagnosticJSON = false;
 function parseOptions(values) {
-    const options = {
-        scope: "project",
-        global: false,
-        dryRun: false,
-        json: false,
-        yes: false,
-        selectionFlag: false,
-    };
-    for (let index = 0; index < values.length; index += 1) {
-        const value = values[index];
-        if (!value.startsWith("--")) {
-            if (options.name)
-                throw new InstallerError("invalid_input", `Unexpected argument: ${value}`);
-            options.name = value;
-        }
-        else if (value === "--global") {
-            if (options.global)
-                throw new InstallerError("invalid_input", "--global may be supplied once");
-            options.global = true;
-            options.scope = "global";
-        }
-        else if (value === "--dry-run") {
-            if (options.dryRun)
-                throw new InstallerError("invalid_input", "--dry-run may be supplied once");
-            options.dryRun = true;
-        }
-        else if (value === "--yes") {
-            if (options.yes)
-                throw new InstallerError("invalid_input", "--yes may be supplied once");
-            options.yes = true;
-        }
-        else if (value === "--core") {
-            if (options.core === true || options.core === false)
-                throw new InstallerError("invalid_input", "Use only one core integration option");
-            options.core = true;
-        }
-        else if (value === "--no-core") {
-            if (options.core === true || options.core === false)
-                throw new InstallerError("invalid_input", "Use only one core integration option");
-            options.core = false;
-        }
-        else if (value === "--provider") {
-            options.provider = values[++index];
-            if (!options.provider)
-                throw new InstallerError("invalid_input", "--provider requires a value");
-        }
-        else if (value === "--model") {
-            options.model = values[++index];
-            if (!options.model)
-                throw new InstallerError("invalid_input", "--model requires a value");
-        }
-        else if (value === "--variant") {
-            options.variant = values[++index];
-            if (!options.variant)
-                throw new InstallerError("invalid_input", "--variant requires a value");
-        }
-        else if (value === "--clear-variant") {
-            if (options.variant !== undefined)
-                throw new InstallerError("invalid_input", "Use only one variant option");
-            options.variant = null;
-        }
-        else if (value === "--json") {
-            if (options.json)
-                throw new InstallerError("invalid_input", "--json may be supplied once");
-            options.json = true;
-        }
-        else if (value === "--no-dependency") {
-            if (options.noDependency)
-                throw new InstallerError("invalid_input", "--no-dependency may be supplied once");
-            options.noDependency = true;
-        }
-        else if (["--commands", "--skill-commands", "--agents", "--plugins"].includes(value)) {
-            const raw = values[++index];
-            if (!raw)
-                throw new InstallerError("invalid_input", `${value} requires a comma-separated value`);
-            const target = value === "--agents" ? "agents" : value === "--plugins" ? "plugins" : "commands";
-            const names = raw === "none"
-                ? []
-                : raw
-                    .split(",")
-                    .map((item) => item.trim())
-                    .filter(Boolean);
-            options.selectionFlag = true;
-            if (value === "--skill-commands") {
-                options.commands = [...(options.commands ?? []), ...names];
-            }
-            else {
-                options[target] = names;
-            }
-        }
-        else if (value === "--targets" || value === "--fragments") {
-            const raw = values[++index];
-            if (!raw)
-                throw new InstallerError("invalid_input", `${value} requires a comma-separated value or none`);
-            const names = raw === "none"
-                ? []
-                : raw
-                    .split(",")
-                    .map((item) => item.trim())
-                    .filter(Boolean);
-            options.selectionFlag = true;
-            if (value === "--targets")
-                options.configTargets = names;
-            else
-                options.configFragments = names;
-        }
-        else {
-            throw new InstallerError("invalid_input", `Unknown argument: ${value}`);
-        }
+    const parser = common(new Command()
+        .exitOverride()
+        .helpOption(false)
+        .configureOutput({ writeErr: () => { } }), "AGENTOMATIC").argument("[name]");
+    for (const [flags, description] of [
+        ["--global", "global user scope"],
+        ["--dry-run", "preview changes"],
+        ["--yes", "explicitly confirm the displayed operation"],
+        ["--core", "activate core integration"],
+        ["--no-core", "disable core integration"],
+        ["--provider <value>", "provider"],
+        ["--model <value>", "model"],
+        ["--variant <value>", "reasoning variant"],
+        ["--clear-variant", "clear the variant"],
+        ["--no-dependency", "do not provision dependencies"],
+        ["--commands <value>", "command selection"],
+        ["--skill-commands <value>", "command selection alias"],
+        ["--agents <value>", "agent selection"],
+        ["--plugins <value>", "plugin selection"],
+        ["--targets <value>", "config targets"],
+        ["--fragments <value>", "config fragments"],
+    ]) {
+        const option = new Option(flags, description);
+        if (!["--yes", "--core", "--no-core", "--clear-variant", "--no-dependency"].includes(flags))
+            option.env(`AGENTOMATIC_${option
+                .attributeName()
+                .replace(/[A-Z]/g, (char) => `_${char}`)
+                .toUpperCase()}`);
+        parser.addOption(option);
+    }
+    try {
+        for (const flag of ["--global", "--dry-run", "--yes", "--json", "--no-dependency"])
+            if (values.filter((value) => value === flag).length > 1)
+                throw new Error(`${flag} may be supplied once`);
+        if (values.includes("--core") && values.includes("--no-core"))
+            throw new Error("Use only one core integration option");
+        if (values.includes("--variant") && values.includes("--clear-variant"))
+            throw new Error("Use only one variant option");
+        parser.parse(values, { from: "user" });
+        applyConfig(parser, configFileSync(parser.opts().config));
+        const parsed = parser.opts();
+        machineOutput = parsed.json === true;
+        diagnosticJSON = parsed.logFormat === "json";
+        diagnostics ??= reporter({ ...parsed, progress: parsed.progress ?? "never" });
+        diagnostics.emit({
+            phase: "agentomatic",
+            message: "Validated command options",
+            level: "debug",
+        });
+        const list = (value) => value === undefined
+            ? undefined
+            : Array.isArray(value)
+                ? value.map(String)
+                : String(value) === "none"
+                    ? []
+                    : String(value)
+                        .split(",")
+                        .map((item) => item.trim())
+                        .filter(Boolean);
+        return {
+            scope: parsed.global ? "global" : "project",
+            global: parsed.global === true,
+            dryRun: parsed.dryRun === true,
+            json: parsed.json === true,
+            yes: parsed.yes === true,
+            name: parser.args[0],
+            core: ["cli", "env", "config"].includes(parser.getOptionValueSource("core") ?? "")
+                ? parsed.core
+                : undefined,
+            provider: parsed.provider,
+            model: parsed.model,
+            variant: parsed.clearVariant ? null : parsed.variant,
+            noDependency: parsed.dependency === false,
+            commands: list(parsed.commands ?? parsed.skillCommands),
+            agents: list(parsed.agents),
+            plugins: list(parsed.plugins),
+            configTargets: list(parsed.targets),
+            configFragments: list(parsed.fragments),
+            selectionFlag: [
+                "commands",
+                "skillCommands",
+                "agents",
+                "plugins",
+                "targets",
+                "fragments",
+            ].some((key) => parsed[key] !== undefined),
+        };
+    }
+    catch (error) {
+        throw new InstallerError("invalid_input", error instanceof Error ? error.message : String(error));
     }
-    return options;
 }
 function helpRows(rows) {
     const width = Math.max(...rows.map(([label]) => label.length));
     return rows.map(([label, description]) => `  ${label.padEnd(width)}  ${description}`);
 }
+function commonRows() {
+    const parser = common(new Command("agentomatic"), "AGENTOMATIC");
+    const help = parser.createHelp();
+    return parser.options
+        .filter((option) => option.attributeName() !== "json")
+        .map((option) => [help.optionTerm(option), help.optionDescription(option)]);
+}
 function rootHelp() {
     return [
         `agentomatic ${CATALOG.version}`,
@@ -164,6 +155,7 @@ function rootHelp() {
             ["--json", "Emit stable machine-readable output when supported."],
             ["--help", "Show this help and exit."],
             ["--version", "Show the package version and exit."],
+            ...commonRows(),
         ]),
         "",
         "Install selection:",
@@ -234,7 +226,19 @@ function commandHelp(topic, summary, usage, options, behavior, examples) {
         ...usage.map((line) => `  ${line}`),
         "",
         "Options:",
-        ...helpRows(options),
+        ...helpRows(options.map(([flag, description]) => {
+            const match = /^--([a-z][a-z-]*)/.exec(flag);
+            const environment = match &&
+                !["yes", "core", "no-core", "no-dependency", "clear-variant", "help"].includes(match[1]);
+            return [
+                flag,
+                environment
+                    ? `${description} (env: AGENTOMATIC_${match[1].replaceAll("-", "_").toUpperCase()})`
+                    : description,
+            ];
+        })),
+        "",
+        ...helpRows(commonRows()),
         "",
         "Behavior:",
         ...behavior.map((line) => `  ${line}`),
@@ -1227,17 +1231,28 @@ async function run(arguments_) {
 }
 async function main() {
     try {
-        await run(process.argv.slice(2));
+        let args = process.argv
+            .slice(2)
+            .map((value) => (value === "-h" ? "--help" : value === "-V" ? "--version" : value));
+        if (args[0] === "help")
+            args = [...args.slice(1), "--help"];
+        await run(args);
     }
     catch (error) {
         const known = error instanceof LifecycleError
             ? error
             : new InstallerError("internal_error", error instanceof Error ? error.message : String(error));
-        if (process.argv.includes("--json"))
+        if (process.argv.includes("--json") || machineOutput)
             process.stdout.write(`${JSON.stringify({ status: "error", error: { code: known.code, message: known.message } })}\n`);
+        else if (diagnosticJSON)
+            process.stderr.write(`${JSON.stringify({ level: "error", phase: "agentomatic.error", code: known.code, message: known.message })}\n`);
         else
             process.stderr.write(`Error [${known.code}]: ${terminalSafe(known.message)}\n`);
         process.exitCode = 2;
     }
+    finally {
+        diagnostics?.emit({ phase: "agentomatic.done", message: "Command finished", level: "debug" });
+        diagnostics?.close();
+    }
 }
 void main();

package/dist/generated/cli.d.ts

@@ -0,0 +1,28 @@
+import { Command, Option, CommanderError, InvalidArgumentError } from "commander";
+export { Command, Option, CommanderError, InvalidArgumentError };
+export declare function integer(value: string): number;
+export declare function duration(value: string): number;
+export declare function program(name: string, description: string, version: string): Command;
+export declare function common(command: Command, prefix: string): Command;
+export declare function configFile(path: string | undefined): Promise<Record<string, unknown>>;
+export declare function configFileSync(path: string | undefined): Record<string, unknown>;
+export declare function applyConfig(command: Command, config: Record<string, unknown>): void;
+export type Event = {
+    phase: string;
+    message: string;
+    level?: "debug" | "info" | "warn" | "error";
+    completed?: number;
+    total?: number;
+    elapsedMs?: number;
+    [key: string]: unknown;
+};
+export type Observe = (event: Event) => void;
+export declare function reporter(options?: Record<string, unknown>): {
+    emit: Observe;
+    close: () => void;
+};
+export declare function cancellation(): {
+    signal: AbortSignal;
+    dispose: () => void;
+};
+export declare function fail(name: string, error: unknown, json?: boolean): void;

package/dist/generated/cli.js

@@ -0,0 +1,181 @@
+import { Command, Option, CommanderError, InvalidArgumentError } from "commander";
+import { readFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+export { Command, Option, CommanderError, InvalidArgumentError };
+export function integer(value) {
+    if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)))
+        throw new InvalidArgumentError("expected a non-negative integer");
+    return Number(value);
+}
+export function duration(value) {
+    const match = /^(\d+)(ms|s|m|h)?$/.exec(value);
+    if (!match)
+        throw new InvalidArgumentError("expected a duration such as 500ms, 30s or 5m");
+    const result = Number(match[1]) * ({ ms: 1, s: 1000, m: 60000, h: 3600000 }[match[2] ?? "ms"] ?? 1);
+    if (!Number.isSafeInteger(result) || result < 0)
+        throw new InvalidArgumentError("duration is out of range");
+    return result;
+}
+export function program(name, description, version) {
+    return new Command(name)
+        .description(description)
+        .version(version)
+        .exitOverride()
+        .configureHelp({ showGlobalOptions: true })
+        .showHelpAfterError()
+        .configureOutput({ outputError: () => { } });
+}
+export function common(command, prefix) {
+    return command
+        .addOption(new Option("--config <file>", "JSON configuration file (CLI > env > file > defaults)").env(`${prefix}_CONFIG`))
+        .addOption(new Option("--json", "machine-readable result on stdout").env(`${prefix}_JSON`))
+        .addOption(new Option("--log-level <level>", "diagnostic verbosity on stderr")
+        .choices(["debug", "info", "warn", "error", "silent"])
+        .env(`${prefix}_LOG_LEVEL`))
+        .addOption(new Option("--log-format <format>", "diagnostic format on stderr")
+        .choices(["text", "json"])
+        .env(`${prefix}_LOG_FORMAT`))
+        .addOption(new Option("--progress <mode>", "terminal progress; never written to stdout")
+        .choices(["auto", "always", "never"])
+        .env(`${prefix}_PROGRESS`))
+        .addOption(new Option("--color <mode>", "color policy (NO_COLOR disables color)")
+        .choices(["auto", "always", "never"])
+        .env(`${prefix}_COLOR`));
+}
+export async function configFile(path) {
+    if (!path)
+        return {};
+    const value = JSON.parse(await readFile(path, "utf8"));
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new InvalidArgumentError("configuration must be a JSON object");
+    return value;
+}
+export function configFileSync(path) {
+    if (!path)
+        return {};
+    const value = JSON.parse(readFileSync(path, "utf8"));
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new InvalidArgumentError("configuration must be a JSON object");
+    return value;
+}
+export function applyConfig(command, config) {
+    for (const option of command.options) {
+        const key = option.attributeName();
+        if (!(key in config) || ["cli", "env"].includes(command.getOptionValueSource(key) ?? ""))
+            continue;
+        if (["yes", "config"].includes(key))
+            continue;
+        const value = config[key];
+        if (option.required || option.optional) {
+            const raw = String(value);
+            if (option.argChoices && !option.argChoices.includes(raw))
+                throw new InvalidArgumentError(`invalid configuration value for ${key}`);
+            command.setOptionValueWithSource(key, option.parseArg ? option.parseArg(raw, undefined) : raw, "config");
+        }
+        else {
+            if (typeof value !== "boolean")
+                throw new InvalidArgumentError(`${key} must be boolean`);
+            command.setOptionValueWithSource(key, value, "config");
+        }
+    }
+}
+export function reporter(options = {}) {
+    const started = Date.now();
+    const level = String(options.logLevel ?? "info");
+    const levels = ["debug", "info", "warn", "error", "silent"];
+    const json = options.logFormat === "json";
+    const interactive = !json &&
+        options.progress !== "never" &&
+        (options.progress === "always" || process.stderr.isTTY);
+    let current;
+    let painted = false;
+    let frame = 0;
+    let meter;
+    const bar = () => {
+        if (!meter || meter.total <= 0)
+            return "";
+        const ratio = Math.min(1, Math.max(0, meter.completed / meter.total));
+        const filled = Math.floor(ratio * 16);
+        return ` | ${meter.phase} [${"█".repeat(filled)}${"░".repeat(16 - filled)}] ${Math.floor(ratio * 100)}%`;
+    };
+    const clean = (text) => Array.from(text, (char) => {
+        const code = char.codePointAt(0);
+        return code < 32 || (code >= 127 && code <= 159) ? " " : char;
+    }).join("");
+    const line = (event) => `${event.phase}: ${event.message}${event.total !== undefined ? ` [${event.completed ?? 0}/${event.total}]` : ""} (${Math.floor((Date.now() - started) / 1000)}s)`;
+    const clear = () => {
+        if (painted) {
+            process.stderr.write("\r\x1b[2K");
+            painted = false;
+        }
+    };
+    const timer = interactive && level !== "silent"
+        ? setInterval(() => {
+            if (current) {
+                const color = process.env.NO_COLOR === undefined &&
+                    (options.color === "always" || (options.color !== "never" && process.stderr.isTTY));
+                process.stderr.write(`\r\x1b[2K${color ? "\x1b[36m" : ""}${["⠋", "⠙", "⠹", "⠸"][frame++ % 4]} ${clean(line(current))}${bar()}${color ? "\x1b[0m" : ""}`);
+                painted = true;
+            }
+        }, 120)
+        : undefined;
+    timer?.unref();
+    const emit = (event) => {
+        const severity = event.level ?? "info";
+        if (levels.indexOf(severity) < levels.indexOf(level))
+            return;
+        current = event;
+        if (event.total !== undefined)
+            meter =
+                event.total > 0
+                    ? {
+                        phase: event.phase.split(".")[0],
+                        completed: event.completed ?? 0,
+                        total: event.total,
+                    }
+                    : undefined;
+        else if (meter && meter.completed >= meter.total)
+            meter = undefined;
+        clear();
+        process.stderr.write(json
+            ? `${JSON.stringify({ at: new Date().toISOString(), elapsedMs: Date.now() - started, ...event })}\n`
+            : `${clean(line(event))}\n`);
+    };
+    return {
+        emit,
+        close: () => {
+            if (timer)
+                clearInterval(timer);
+            clear();
+        },
+    };
+}
+export function cancellation() {
+    const controller = new AbortController();
+    const interrupt = () => controller.abort(new Error("interrupted"));
+    process.on("SIGINT", interrupt);
+    process.on("SIGTERM", interrupt);
+    process.on("SIGHUP", interrupt);
+    return {
+        signal: controller.signal,
+        dispose: () => {
+            process.off("SIGINT", interrupt);
+            process.off("SIGTERM", interrupt);
+            process.off("SIGHUP", interrupt);
+        },
+    };
+}
+export function fail(name, error, json = false) {
+    if (error instanceof CommanderError && error.exitCode === 0)
+        return;
+    const message = error instanceof Error ? error.message : String(error);
+    const interrupted = /interrupted|aborted/i.test(message);
+    process.stderr.write(json ? `${JSON.stringify({ status: "error", message })}\n` : `${name}: ${message}\n`);
+    process.exitCode = /timeout|timed out|deadline/i.test(message)
+        ? 124
+        : interrupted
+            ? 130
+            : error instanceof CommanderError
+                ? 2
+                : 1;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kisev/agentomatic",
-  "version": "11.0.0-dev.70.g8d00098df14b",
+  "version": "11.0.0-dev.71.gee4e37a5bb61",
   "description": "OpenCode integration and opt-in installer for portable Agent Skills.",
   "homepage": "https://github.com/kisev/skills#readme",
   "bugs": {
@@ -46,7 +46,8 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.8.1",
-    "@kisev/safe-fs": "1.0.0-dev.70.g8d00098df14b"
+    "@kisev/safe-fs": "1.0.0-dev.71.gee4e37a5bb61",
+    "commander": "15.0.0"
   },
   "devDependencies": {
     "@opencode-ai/plugin": "1.18.29",
@@ -62,7 +63,7 @@
     }
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.13"
   },
   "skillsInstallerVersion": "1.7.0"
 }