@duyquangnvx/agent-cli 0.0.0-stage → 0.2.0

package/dist/skills.js

@@ -0,0 +1,58 @@
+import { readFile, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { isMissingFile } from "./errors.js";
+import { isVersion, standingOf } from "./semver.js";
+/** Where the skills CLI (`npx skills add`) puts a skill, under a project and under home. */
+const SKILL_DIRS = [
+    [".claude", "skills"],
+    [".agents", "skills"],
+];
+export function skillUpdateCommand(cliName) {
+    return `npx -y skills update ${cliName}`;
+}
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---/;
+const METADATA_VERSION = /^metadata:[ \t]*\r?\n(?:[ \t]+.*\r?\n)*?[ \t]+version:[ \t]*["']?([^"'\s]+)["']?[ \t]*$/m;
+/** The version a SKILL.md's frontmatter `metadata.version` states. */
+function skillVersionIn(skill) {
+    const frontmatter = FRONTMATTER.exec(skill)?.[1];
+    return frontmatter === undefined ? undefined : METADATA_VERSION.exec(`${frontmatter}\n`)?.[1];
+}
+function homeOf(env) {
+    return env.HOME ?? env.USERPROFILE ?? homedir();
+}
+async function copyAt(path, cliVersion) {
+    let skill;
+    try {
+        skill = await readFile(join(path, "SKILL.md"), "utf8");
+    }
+    catch (error) {
+        if (isMissingFile(error)) {
+            return undefined;
+        }
+        return { path, version: undefined, state: "unreadable" };
+    }
+    const version = skillVersionIn(skill);
+    if (version === undefined || !isVersion(version) || !isVersion(cliVersion)) {
+        return { path, version, state: "unversioned" };
+    }
+    return { path, version, state: standingOf(version, cliVersion) };
+}
+/** Every installed copy of the skill named after the CLI, in the project first, then under home. */
+export async function skillCopies(skillName, cliVersion, cwd, env) {
+    const roots = [cwd, homeOf(env)];
+    const paths = roots.flatMap((root) => SKILL_DIRS.map((dir) => join(root, ...dir, skillName)));
+    const seen = new Set();
+    const copies = [];
+    for (const path of paths) {
+        const copy = await copyAt(path, cliVersion);
+        // The project may be home itself, or one skill dir a link to the other.
+        const real = copy === undefined ? undefined : await realpath(path);
+        if (copy !== undefined && real !== undefined && !seen.has(real)) {
+            seen.add(real);
+            copies.push(copy);
+        }
+    }
+    return copies;
+}
+//# sourceMappingURL=skills.js.map

package/dist/skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"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"}

package/dist/style.d.ts

@@ -0,0 +1,13 @@
+import type { Env } from "./define.js";
+type Paint = (text: string) => string;
+/** Colours text when colour is on; every method returns the text unchanged when it is off. */
+export interface Style {
+    readonly bold: Paint;
+    readonly dim: Paint;
+    readonly red: Paint;
+    readonly green: Paint;
+    readonly yellow: Paint;
+    readonly cyan: Paint;
+}
+export declare function styleFor(env: Env, stdoutIsTTY: boolean): Style;
+export {};

package/dist/style.js

@@ -0,0 +1,38 @@
+// Some Agent harnesses run commands in a PTY, so a TTY alone doesn't mean a person is watching.
+const AGENT_VARIABLES = [
+    "CLAUDECODE",
+    "CODEX_CI",
+    "CODEX_SANDBOX",
+    "GEMINI_CLI",
+    "CURSOR_AGENT",
+    "CI",
+];
+function colourEnabled(env, stdoutIsTTY) {
+    const noColor = env.NO_COLOR !== undefined && env.NO_COLOR !== "";
+    const agent = AGENT_VARIABLES.some((name) => env[name] !== undefined);
+    return stdoutIsTTY && !noColor && !agent;
+}
+function sgr(open, close) {
+    return (text) => `\u001b[${open}m${text}\u001b[${close}m`;
+}
+const COLOURED = {
+    bold: sgr(1, 22),
+    dim: sgr(2, 22),
+    red: sgr(31, 39),
+    green: sgr(32, 39),
+    yellow: sgr(33, 39),
+    cyan: sgr(36, 39),
+};
+const plain = (text) => text;
+const PLAIN = {
+    bold: plain,
+    dim: plain,
+    red: plain,
+    green: plain,
+    yellow: plain,
+    cyan: plain,
+};
+export function styleFor(env, stdoutIsTTY) {
+    return colourEnabled(env, stdoutIsTTY) ? COLOURED : PLAIN;
+}
+//# sourceMappingURL=style.js.map

package/dist/style.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"style.js","sourceRoot":"","sources":["../src/style.ts"],"names":[],"mappings":"AAcA,gGAAgG;AAChG,MAAM,eAAe,GAAG;IACtB,YAAY;IACZ,UAAU;IACV,eAAe;IACf,YAAY;IACZ,cAAc;IACd,IAAI;CACI,CAAC;AAEX,SAAS,aAAa,CAAC,GAAQ,EAAE,WAAoB;IACnD,MAAM,OAAO,GAAG,GAAG,CAAC,QAAQ,KAAK,SAAS,IAAI,GAAG,CAAC,QAAQ,KAAK,EAAE,CAAC;IAClE,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,SAAS,CAAC,CAAC;IACtE,OAAO,WAAW,IAAI,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC;AAC3C,CAAC;AAED,SAAS,GAAG,CAAC,IAAY,EAAE,KAAa;IACtC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,IAAI,IAAI,IAAI,UAAU,KAAK,GAAG,CAAC;AAC5D,CAAC;AAED,MAAM,QAAQ,GAAU;IACtB,IAAI,EAAE,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC;IAChB,GAAG,EAAE,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC;IACf,GAAG,EAAE,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC;IAChB,KAAK,EAAE,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC;IAClB,MAAM,EAAE,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC;IACnB,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC;CAClB,CAAC;AAEF,MAAM,KAAK,GAAU,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC;AAEpC,MAAM,KAAK,GAAU;IACnB,IAAI,EAAE,KAAK;IACX,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,KAAK,EAAE,KAAK;IACZ,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,KAAK;CACZ,CAAC;AAEF,MAAM,UAAU,QAAQ,CAAC,GAAQ,EAAE,WAAoB;IACrD,OAAO,aAAa,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC;AAC5D,CAAC"}

package/dist/suggest.d.ts

@@ -0,0 +1,6 @@
+/** The names closest to `word`, sorted, several when they tie, or none when nothing is close. */
+export declare function closestNames(word: string, names: readonly string[]): string[];
+/** The long flags closest to `flag`, sorted, or none for a short flag or when nothing is close. */
+export declare function closestFlags(flag: string, flags: readonly string[]): string[];
+/** The one long flag closest to `flag`, or none when nothing is close or several tie. */
+export declare function closestFlag(flag: string, flags: readonly string[]): string | undefined;

package/dist/suggest.js

@@ -0,0 +1,49 @@
+const MAX_DISTANCE = 3;
+const MIN_SIMILARITY = 0.4;
+// Optimal string alignment distance.
+function distance(a, b) {
+    const width = b.length + 1;
+    const d = Array.from({ length: (a.length + 1) * width }, (_, k) => {
+        const i = Math.floor(k / width);
+        const j = k % width;
+        // The first row and column count the edits from an empty string.
+        return i === 0 || j === 0 ? i + j : 0;
+    });
+    const at = (i, j) => d[i * width + j] ?? 0;
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            const edit = Math.min(at(i - 1, j) + 1, at(i, j - 1) + 1, at(i - 1, j - 1) + cost);
+            const transposed = i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1];
+            d[i * width + j] = transposed ? Math.min(edit, at(i - 2, j - 2) + 1) : edit;
+        }
+    }
+    return at(a.length, b.length);
+}
+function isClose(word, candidate) {
+    const length = Math.max(word.length, candidate.length);
+    const edits = distance(word, candidate);
+    return candidate.length > 1 && edits < MAX_DISTANCE && (length - edits) / length > MIN_SIMILARITY;
+}
+/** The names closest to `word`, sorted, several when they tie, or none when nothing is close. */
+export function closestNames(word, names) {
+    const close = [...new Set(names)].filter((candidate) => isClose(word, candidate));
+    const best = Math.min(...close.map((candidate) => distance(word, candidate)));
+    return close
+        .filter((candidate) => distance(word, candidate) === best)
+        .sort((a, b) => a.localeCompare(b));
+}
+/** The long flags closest to `flag`, sorted, or none for a short flag or when nothing is close. */
+export function closestFlags(flag, flags) {
+    if (!flag.startsWith("--")) {
+        return [];
+    }
+    const names = flags.map((candidate) => candidate.slice(2));
+    return closestNames(flag.slice(2), names).map((name) => `--${name}`);
+}
+/** The one long flag closest to `flag`, or none when nothing is close or several tie. */
+export function closestFlag(flag, flags) {
+    const closest = closestFlags(flag, flags);
+    return closest.length === 1 ? closest[0] : undefined;
+}
+//# sourceMappingURL=suggest.js.map

package/dist/suggest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggest.js","sourceRoot":"","sources":["../src/suggest.ts"],"names":[],"mappings":"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"}

package/dist/tokenize.d.ts

@@ -0,0 +1,20 @@
+/** What a flag takes after it: nothing, the next word unless it is a flag, or the next word. */
+export type Takes = "nothing" | "optional value" | "value";
+export interface KnownFlag {
+    /** The flag as the caller types it, such as `--limit` or `--no-install`. */
+    readonly flag: string;
+    readonly takes: Takes;
+}
+export interface Operand {
+    readonly value: string;
+    readonly afterUnknownOption: boolean;
+}
+export interface Words {
+    readonly operands: readonly Operand[];
+    /** Each unknown option word as typed, `=value` included. */
+    readonly unknownOptions: readonly string[];
+    /** The last value of each known flag passed; `true` for a switch or a flag given no value. */
+    readonly values: ReadonlyMap<string, string | true>;
+}
+/** Splits a Command's words into operands, unknown options and the values of known flags. */
+export declare function tokenize(words: readonly string[], known: readonly KnownFlag[]): Words;

package/dist/tokenize.js

@@ -0,0 +1,79 @@
+import { parseArgs } from "node:util";
+const NEGATIVE_NUMBER = /^-(\d+|\d*\.\d+)(e[+-]?\d+)?$/;
+function isOptionLike(word) {
+    return word !== undefined && word.length > 1 && word[0] === "-" && !NEGATIVE_NUMBER.test(word);
+}
+// A flag taking an optional value is declared a switch, so that parseArgs never swallows the next
+// flag as its value; the value is then picked here from the word after it.
+function parseArgsOptions(known) {
+    return Object.fromEntries(known.map(({ flag, takes }) => [
+        flag.slice(2),
+        { type: takes === "value" ? "string" : "boolean" },
+    ]));
+}
+function flagItem(token, { flag, takes }, words) {
+    if (takes !== "optional value" || token.inlineValue === true) {
+        return { kind: "flag", flag, value: token.value ?? true };
+    }
+    const took = token.index + 1;
+    const next = words[took];
+    return next === undefined || isOptionLike(next)
+        ? { kind: "flag", flag, value: true }
+        : { kind: "flag", flag, value: next, took };
+}
+function itemOf(token, words, byFlag) {
+    const word = words[token.index] ?? "";
+    if (token.kind === "option-terminator") {
+        return { kind: "end" };
+    }
+    if (token.kind === "positional" || NEGATIVE_NUMBER.test(word)) {
+        return { kind: "operand", value: word };
+    }
+    const flag = byFlag.get(token.rawName);
+    return flag === undefined || (flag.takes === "nothing" && token.inlineValue === true)
+        ? { kind: "unknown option", word }
+        : flagItem(token, flag, words);
+}
+/** Splits a Command's words into operands, unknown options and the values of known flags. */
+export function tokenize(words, known) {
+    const byFlag = new Map(known.map((flag) => [flag.flag, flag]));
+    const { tokens } = parseArgs({
+        args: [...words],
+        options: parseArgsOptions(known),
+        strict: false,
+        allowPositionals: true,
+        tokens: true,
+    });
+    const operands = [];
+    const unknownOptions = [];
+    const values = new Map();
+    // A short group such as `-abc` yields one token per letter, all at the same index.
+    const done = new Set();
+    let literal = false;
+    let afterUnknownOption = false;
+    for (const token of tokens) {
+        if (done.has(token.index)) {
+            continue;
+        }
+        done.add(token.index);
+        const item = itemOf(token, words, byFlag);
+        if (item.kind === "end") {
+            literal = true;
+        }
+        else if (item.kind === "operand") {
+            operands.push({ value: item.value, afterUnknownOption: !literal && afterUnknownOption });
+            afterUnknownOption = false;
+        }
+        else if (item.kind === "unknown option") {
+            unknownOptions.push(item.word);
+            afterUnknownOption = true;
+        }
+        else {
+            values.set(item.flag, item.value);
+            if (item.took !== undefined)
+                done.add(item.took);
+        }
+    }
+    return { operands, unknownOptions, values };
+}
+//# sourceMappingURL=tokenize.js.map

package/dist/tokenize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenize.js","sourceRoot":"","sources":["../src/tokenize.ts"],"names":[],"mappings":"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"}

package/dist/update.d.ts

@@ -0,0 +1,3 @@
+import { type Command, type CommandTreeCli, type GlobalInstall } from "./define.js";
+/** The built-in `update`, for a CLI installed globally with npm. */
+export declare function updateCommand(cli: CommandTreeCli, install: GlobalInstall, bin: string | undefined): Command;

package/dist/update.js

@@ -0,0 +1,91 @@
+import * as z from "zod";
+import { defineCommand } from "./define.js";
+import { FailureWithData } from "./errors.js";
+import { globalInstallOf } from "./global-install.js";
+import { INTERRUPTED } from "./interrupts.js";
+import { installGlobally, latestVersion, npmContext } from "./npm.js";
+import { standingOf } from "./semver.js";
+import { skillUpdateCommand } from "./skills.js";
+import { upgradeNotes } from "./upgrade-notes.js";
+const updateSchema = z.object({
+    from: z.string(),
+    latest: z.string(),
+    installed: z.object({ version: z.string(), prefix: z.string() }).nullable(),
+    upgrades: z.array(z.object({ version: z.string(), notes: z.string() })),
+    next: z.array(z.string()),
+});
+function nothingToInstall({ from, latest }) {
+    return standingOf(from, latest) === "current"
+        ? `already on ${from}, the latest release: nothing to install`
+        : `${from} is newer than the latest release ${latest}: nothing to install`;
+}
+function renderUpdate(cli, install, update) {
+    const { installed } = update;
+    if (installed === null) {
+        return nothingToInstall(update);
+    }
+    return [
+        `installed ${install.package}@${installed.version} with the npm under ${installed.prefix}, replacing ${update.from}`,
+        ...update.upgrades.map(({ version, notes }) => `\nchanges in ${version}:\n${notes}`),
+        "",
+        ...update.next.map((command) => `next: ${command}, so the ${cli.name} skill describes ${installed.version}`),
+    ].join("\n");
+}
+// The install ran to its end, so the run reports it rather than asking for a rerun.
+function interruptedAfterInstall(plan, update) {
+    return new FailureWithData({
+        code: INTERRUPTED,
+        message: `interrupted, but ${plan.package}@${plan.latest} had already been installed with the npm under ${plan.prefix}, replacing ${plan.from}`,
+        hint: "nothing to run again: run the commands under next",
+        retryable: false,
+    }, update);
+}
+/** The built-in `update`, for a CLI installed globally with npm. */
+export function updateCommand(cli, install, bin) {
+    return defineCommand({
+        name: "update",
+        description: "install the latest version of this CLI from its registry",
+        examples: [
+            { command: `${cli.name} update`, note: "install the latest version and show what changed" },
+            { command: `${cli.name} update --dry-run`, note: "show the version it would install" },
+        ],
+        effect: "write",
+        output: updateSchema,
+        plan: async (_input, ctx) => {
+            const npm = npmContext(cli, install, ctx);
+            const copy = await globalInstallOf(bin, npm);
+            return {
+                package: install.package,
+                from: cli.version,
+                latest: await latestVersion(npm),
+                prefix: copy.prefix,
+                packageDir: copy.packageDir,
+            };
+        },
+        apply: async (plan, ctx) => {
+            const { from, latest, prefix } = plan;
+            if (standingOf(from, latest) !== "behind") {
+                return { from, latest, installed: null, upgrades: [], next: [] };
+            }
+            ctx.signal.throwIfAborted();
+            ctx.progress(`installing ${plan.package}@${latest} with the npm under ${prefix}…`);
+            await ctx.runToEnd(() => installGlobally(latest, npmContext(cli, install, ctx)));
+            const update = {
+                from,
+                latest,
+                installed: { version: latest, prefix },
+                upgrades: await upgradeNotes(plan.packageDir, from, latest),
+                next: [skillUpdateCommand(cli.name)],
+            };
+            if (ctx.signal.aborted) {
+                throw interruptedAfterInstall(plan, update);
+            }
+            return update;
+        },
+        render: (update) => renderUpdate(cli, install, update),
+        renderPlan: (plan) => standingOf(plan.from, plan.latest) === "behind"
+            ? `would install ${plan.package}@${plan.latest} with the npm under ${plan.prefix}, replacing ${plan.from}`
+            : nothingToInstall(plan),
+    });
+}
+//# sourceMappingURL=update.js.map

package/dist/update.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update.js","sourceRoot":"","sources":["../src/update.ts"],"names":[],"mappings":"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"}

package/dist/upgrade-notes.d.ts

@@ -0,0 +1,9 @@
+export interface UpgradeNotes {
+    readonly version: string;
+    readonly notes: string;
+}
+/**
+ * What changed in each release after `from` up to `to`, oldest first, from the CHANGELOG.md in
+ * `packageDir`; none when the package ships no CHANGELOG.
+ */
+export declare function upgradeNotes(packageDir: string, from: string, to: string): Promise<UpgradeNotes[]>;

package/dist/upgrade-notes.js

@@ -0,0 +1,41 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isMissingFile } from "./errors.js";
+import { compareVersions, isVersion } from "./semver.js";
+const RELEASE_HEADING = /^## v?(\S+)/;
+function releasesIn(changelog) {
+    const releases = [];
+    let current;
+    for (const line of changelog.split(/\r?\n/)) {
+        const heading = RELEASE_HEADING.exec(line);
+        if (heading !== null) {
+            const version = heading[1] ?? "";
+            current = isVersion(version) ? { version, lines: [] } : undefined;
+            if (current !== undefined)
+                releases.push(current);
+        }
+        else {
+            current?.lines.push(line);
+        }
+    }
+    return releases.map(({ version, lines }) => ({ version, notes: lines.join("\n").trim() }));
+}
+/**
+ * What changed in each release after `from` up to `to`, oldest first, from the CHANGELOG.md in
+ * `packageDir`; none when the package ships no CHANGELOG.
+ */
+export async function upgradeNotes(packageDir, from, to) {
+    let changelog;
+    try {
+        changelog = await readFile(join(packageDir, "CHANGELOG.md"), "utf8");
+    }
+    catch (error) {
+        if (isMissingFile(error))
+            return [];
+        throw error;
+    }
+    return releasesIn(changelog)
+        .filter(({ version }) => compareVersions(version, from) > 0 && compareVersions(version, to) <= 0)
+        .sort((a, b) => compareVersions(a.version, b.version));
+}
+//# sourceMappingURL=upgrade-notes.js.map

package/dist/upgrade-notes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade-notes.js","sourceRoot":"","sources":["../src/upgrade-notes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAOzD,MAAM,eAAe,GAAG,aAAa,CAAC;AAEtC,SAAS,UAAU,CAAC,SAAiB;IACnC,MAAM,QAAQ,GAA2C,EAAE,CAAC;IAC5D,IAAI,OAAyD,CAAC;IAC9D,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5C,MAAM,OAAO,GAAG,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3C,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YACjC,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;YAClE,IAAI,OAAO,KAAK,SAAS;gBAAE,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpD,CAAC;aAAM,CAAC;YACN,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;AAC7F,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,UAAkB,EAClB,IAAY,EACZ,EAAU;IAEV,IAAI,SAAiB,CAAC;IACtB,IAAI,CAAC;QACH,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,UAAU,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAAC;IACvE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,aAAa,CAAC,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QACpC,MAAM,KAAK,CAAC;IACd,CAAC;IACD,OAAO,UAAU,CAAC,SAAS,CAAC;SACzB,MAAM,CACL,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,eAAe,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,eAAe,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,CACzF;SACA,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/dist/usage.d.ts

@@ -0,0 +1,5 @@
+import { UsageError } from "./errors.js";
+import { type Invocation } from "./invocation.js";
+export declare function unknownOptionError(commandLine: string, invocation: Invocation, flag: string, suggestions: readonly string[]): UsageError;
+export declare function unknownCommandError(commandLine: string, name: string, suggestions: readonly string[]): UsageError;
+export declare function invalidInputError(commandLine: string, problem: string): UsageError;

package/dist/usage.js

@@ -0,0 +1,37 @@
+import { UsageError } from "./errors.js";
+import { commandLineRenaming } from "./invocation.js";
+function unknownError({ code, problem, commandLine, corrections, listed }) {
+    return new UsageError({
+        code,
+        message: `${problem} for \`${commandLine}\``,
+        hint: corrections.length === 0
+            ? `run \`${commandLine} --help\` to see the ${listed}`
+            : `did you mean ${corrections.map((correction) => `\`${correction}\``).join(" or ")}?`,
+    });
+}
+export function unknownOptionError(commandLine, invocation, flag, suggestions) {
+    return unknownError({
+        code: "UNKNOWN_OPTION",
+        problem: `unknown option '${flag}'`,
+        commandLine,
+        corrections: suggestions.map((name) => commandLineRenaming(invocation, new Map([[flag, name]]))),
+        listed: "options",
+    });
+}
+export function unknownCommandError(commandLine, name, suggestions) {
+    return unknownError({
+        code: "UNKNOWN_COMMAND",
+        problem: `unknown command '${name}'`,
+        commandLine,
+        corrections: suggestions.map((suggestion) => `${commandLine} ${suggestion}`),
+        listed: "commands",
+    });
+}
+export function invalidInputError(commandLine, problem) {
+    return new UsageError({
+        code: "INVALID_INPUT",
+        message: problem,
+        hint: `run \`${commandLine} --help\` to see the expected input`,
+    });
+}
+//# sourceMappingURL=usage.js.map

package/dist/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,mBAAmB,EAAmB,MAAM,iBAAiB,CAAC;AAUvE,SAAS,YAAY,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,EAAW;IAChF,OAAO,IAAI,UAAU,CAAC;QACpB,IAAI;QACJ,OAAO,EAAE,GAAG,OAAO,UAAU,WAAW,IAAI;QAC5C,IAAI,EACF,WAAW,CAAC,MAAM,KAAK,CAAC;YACtB,CAAC,CAAC,SAAS,WAAW,wBAAwB,MAAM,EAAE;YACtD,CAAC,CAAC,gBAAgB,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,KAAK,UAAU,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG;KAC3F,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,WAAmB,EACnB,UAAsB,EACtB,IAAY,EACZ,WAA8B;IAE9B,OAAO,YAAY,CAAC;QAClB,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,mBAAmB,IAAI,GAAG;QACnC,WAAW;QACX,WAAW,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CACpC,mBAAmB,CAAC,UAAU,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CACzD;QACD,MAAM,EAAE,SAAS;KAClB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,WAAmB,EACnB,IAAY,EACZ,WAA8B;IAE9B,OAAO,YAAY,CAAC;QAClB,IAAI,EAAE,iBAAiB;QACvB,OAAO,EAAE,oBAAoB,IAAI,GAAG;QACpC,WAAW;QACX,WAAW,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,GAAG,WAAW,IAAI,UAAU,EAAE,CAAC;QAC5E,MAAM,EAAE,UAAU;KACnB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,WAAmB,EAAE,OAAe;IACpE,OAAO,IAAI,UAAU,CAAC;QACpB,IAAI,EAAE,eAAe;QACrB,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,SAAS,WAAW,qCAAqC;KAChE,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@duyquangnvx/agent-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Runtime for agent-first command-line tools: owns parsing, output, errors and exit codes.",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "peerDependencies": {
+    "zod": "^4.6.0"
+  },
+  "devDependencies": {
+    "zod": "4.6.7"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  }
 }