ainize 0.1.0

package/dist/context.js

@@ -0,0 +1,102 @@
+/**
+ * CLI context: where the node config lives (AINIZE_HOME), which node URL to talk to,
+ * the stored operator bearer token (cli.json) and output flags.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { DEFAULT_HOME, configPath, loadConfig } from '@ainize/core';
+/**
+ * Name the binary was invoked as. There is one: `ainize` (AI + -ize, "ainize your knowledge", like the 2019
+ * `ainize` CLI that ainized GitHub repos). The historical `ngram` alias was withdrawn when the packages moved
+ * to the `@ainize` scope — item 110 counted fourteen hints that told you to run a name the product no longer
+ * uses, starting with the first line `ainize init` prints.
+ */
+export const PROG_NAMES = ['ainize'];
+export function progName(argv1 = process.argv[1]) {
+    const base = basename(argv1 ?? '').replace(/\.(c|m)?js$/, '');
+    return PROG_NAMES.includes(base) ? base : 'ainize';
+}
+export const PROG = progName();
+export class CliError extends Error {
+    exitCode;
+    /** The node's JSON error body, when there was one — e.g. the per-line report a refused dataset upload carries. */
+    details;
+    constructor(message, exitCode = 1, details) {
+        super(message);
+        this.exitCode = exitCode;
+        this.details = details;
+    }
+}
+export function statePath(home) { return join(home, 'cli.json'); }
+export function readState(home) {
+    const p = statePath(home);
+    if (!existsSync(p))
+        return {};
+    try {
+        return JSON.parse(readFileSync(p, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+export function writeState(home, state) {
+    mkdirSync(home, { recursive: true });
+    writeFileSync(statePath(home), JSON.stringify(state, null, 2) + '\n', { mode: 0o600 });
+}
+export function resolveHome(explicit) {
+    return explicit ?? process.env.AINIZE_HOME ?? DEFAULT_HOME;
+}
+/** A TCP port — what config.json's `port` and AINIZE_PORT must hold before a URL can be built from them. */
+const isPort = (v) => Number.isInteger(v) && v >= 1 && v <= 65535;
+/** Build a context from global flags. Node URL precedence: --node > AINIZE_NODE_URL > cli.json > AINIZE_PORT > config port > default. */
+export function buildContext(opts = {}) {
+    const home = resolveHome(opts.home);
+    const cfg = loadConfig(home);
+    const state = readState(home);
+    const envPort = process.env.AINIZE_PORT;
+    if (envPort !== undefined && !isPort(Number(envPort)))
+        throw new CliError(`AINIZE_PORT must be a port number (1–65535) — got ${JSON.stringify(envPort)}`, 2);
+    const port = envPort !== undefined ? Number(envPort) : cfg?.port ?? 3402;
+    const url = opts.node ?? process.env.AINIZE_NODE_URL ?? state.nodeUrl ?? `http://localhost:${port}`;
+    const nodeSource = opts.node ? 'flag'
+        : process.env.AINIZE_NODE_URL ? 'env'
+            : state.nodeUrl ? 'state'
+                : envPort !== undefined ? 'env'
+                    : cfg ? 'config'
+                        : 'default';
+    const nodeUrl = url.replace(/\/+$/, '');
+    // A config.json whose `port` is not a number used to make every command — `config set port …`, the fix, included —
+    // die with "--node must be a full URL", blaming a flag nobody passed (item 123). The URL is only checked when
+    // someone typed it; a broken config is named by the commands that actually need a node (requireNodeTarget).
+    let nodeUrlProblem = null;
+    if (nodeSource === 'config' && !isPort(cfg.port)) {
+        nodeUrlProblem = `port in ${configPath(home)} is ${JSON.stringify(cfg.port)}, not a port number — fix it with \`${PROG} config set port <1-65535>\``;
+    }
+    else if (nodeSource === 'flag' || nodeSource === 'env' || nodeSource === 'state') {
+        // `--node localhost:3402` is the standard typo, and a scheme-less URL used to be reported as a dead node while
+        // the node was serving happily on that very port (item 116).
+        let parsed = null;
+        try {
+            parsed = new URL(nodeUrl);
+        }
+        catch { /* not a URL at all */ }
+        // note `new URL('localhost:3402')` parses — with protocol "localhost:" — so the scheme has to be checked too
+        if (!parsed || (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')) {
+            const where = nodeSource === 'flag' ? '--node' : process.env.AINIZE_NODE_URL ? 'AINIZE_NODE_URL' : `the node URL in ${statePath(home)}`;
+            throw new CliError(`${where} must be a full URL — did you mean http://${nodeUrl.replace(/^\w+:\/\//, '').replace(/^\/+/, '')}?`, 2);
+        }
+    }
+    return { home, nodeUrl, nodeSource, nodeUrlProblem, token: process.env.AINIZE_TOKEN ?? state.token ?? null, json: !!opts.json, quiet: !!opts.quiet, cfg };
+}
+/**
+ * Refuse to send a request nobody aimed: with no config in this home and no `--node`, every read command used to
+ * report whatever answered port 3402 — a colleague's node, or the demo cluster — as yours (item 101).
+ */
+export function requireNodeTarget(ctx) {
+    if (ctx.nodeUrlProblem)
+        throw new CliError(ctx.nodeUrlProblem, 2);
+    if (ctx.cfg || ctx.nodeSource !== 'default')
+        return;
+    throw new CliError(`no node configured in ${ctx.home} — run \`${PROG} init\` to create one, or pass --node <url> to talk to an existing node`, 2);
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

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

package/dist/ens.d.ts

@@ -0,0 +1,50 @@
+/** Where the answer came from, so a caller can say it rather than imply it. */
+export type ResolveSource = 'names-file' | 'config' | 'on-chain';
+export interface ResolvedName {
+    name: string;
+    /** The node that holds the knowledge — what `--node` would have been. */
+    node: string;
+    /** The knowledge id on that node — what `use <id>` would have been. */
+    patch: string;
+    source: ResolveSource;
+    /** Where exactly, so an operator can go and edit it. */
+    where: string;
+}
+export declare const NODE_KEY = "ainize.node";
+export declare const PATCH_KEY = "ainize.patch";
+/** A name this CLI will try to resolve rather than treat as a subcommand or an id. */
+export declare function looksLikeEnsName(s: string): boolean;
+/**
+ * ENSIP-1 namehash. Reverse label order, each step hashing the parent node with the label hash.
+ * `keccak` comes from ain-util, which this workspace already depends on — node's `sha3-256` is NOT keccak256
+ * (different padding) and using it here would produce plausible, wrong nodes.
+ */
+export declare function namehash(name: string): string;
+export interface ResolveOptions {
+    /** JSON-RPC endpoint. `--rpc`, then ENS_RPC_URL, then `ens.rpc` in the node config. */
+    rpc?: string;
+    /** ENS registry address. Never defaulted — see the note at the top of this file. */
+    registry?: string;
+    /** Explicit names file, overriding the search order. */
+    namesFile?: string;
+    /** `ens` block from the node config, when there is one. */
+    config?: {
+        rpc?: string;
+        registry?: string;
+        names?: Record<string, {
+            node: string;
+            patch: string;
+        }>;
+    } | null;
+    home?: string;
+}
+/** The places a names file may live, in the order they are consulted. */
+export declare function namesFileCandidates(opts?: ResolveOptions): string[];
+/**
+ * Resolve `name` to the node and knowledge id it points at.
+ *
+ * Throws with BOTH paths named when neither works, because "cannot resolve" without saying what was tried is
+ * the error message that sends someone to the wrong place.
+ */
+export declare function resolveName(name: string, opts?: ResolveOptions): Promise<ResolvedName>;
+//# sourceMappingURL=ens.d.ts.map

package/dist/ens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ens.d.ts","sourceRoot":"","sources":["../src/ens.ts"],"names":[],"mappings":"AAmCA,+EAA+E;AAC/E,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEjE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,aAAa,CAAC;IACtB,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,QAAQ,gBAAgB,CAAC;AACtC,eAAO,MAAM,SAAS,iBAAiB,CAAC;AAExC,sFAAsF;AACtF,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAEnD;AAID;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAU7C;AAkCD,MAAM,WAAW,cAAc;IAC7B,uFAAuF;IACvF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,MAAM,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;IAC7G,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAYD,yEAAyE;AACzE,wBAAgB,mBAAmB,CAAC,IAAI,GAAE,cAAmB,GAAG,MAAM,EAAE,CAMvE;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,YAAY,CAAC,CAsChG"}

package/dist/ens.js

@@ -0,0 +1,155 @@
+/**
+ * Resolve an ENS name to the knowledge it points at.
+ *
+ * `ainize patch vaults.defi.engram.eth` replaces three commands and a copied id:
+ *
+ *   ainize patch ls --node http://their-node:3402 --status LISTED -q "<topic>"
+ *   ainize login && ainize use <id>
+ *
+ * The reason a name can do that is that it carries BOTH halves of what those commands supply by hand — which
+ * node to talk to and which knowledge to ask for. `ainize.node` and `ainize.patch` are ENSIP-5 text records,
+ * so a publisher sets them once and every buyer's command line collapses to the name.
+ *
+ * TWO RESOLUTION PATHS, and the honest status of each:
+ *
+ *   local     A names file — `ens.names` in the node config, or ~/.ainize/names.json, or --names <file>.
+ *             Verified: it is a file this CLI reads and this repository tests. It is also what makes the
+ *             command work offline, in a demo, and before any name is registered.
+ *
+ *   on-chain  registry.resolver(namehash) then resolver.text(namehash, key), over JSON-RPC with no new
+ *             dependency. `text(bytes32,string)` is ENSIP-5 and stable; the REGISTRY address is not something
+ *             this file guesses — it must be given with --registry or `ens.registry`, because ENSv2's own
+ *             documentation says its contracts "are not yet final and may change prior to mainnet
+ *             deployment", and a hard-coded address that silently resolves against the wrong registry is the
+ *             kind of confident wrong answer this project has spent its time removing.
+ *             NOT YET EXERCISED against a live ENSv2 deployment. It is written from the ENSIP-5 interface and
+ *             it will say so if it fails.
+ *
+ * Local wins when both are available, deliberately: a name you have pinned locally is a name you have
+ * checked, and a lookup that silently prefers the network can change under you between two runs.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { keccak } from '@ainblockchain/ain-util';
+export const NODE_KEY = 'ainize.node';
+export const PATCH_KEY = 'ainize.patch';
+/** A name this CLI will try to resolve rather than treat as a subcommand or an id. */
+export function looksLikeEnsName(s) {
+    return /^[a-z0-9-]+(\.[a-z0-9-]+)+$/i.test(s) && /\.(eth|test)$/i.test(s);
+}
+const hex = (b) => Buffer.from(b).toString('hex');
+/**
+ * ENSIP-1 namehash. Reverse label order, each step hashing the parent node with the label hash.
+ * `keccak` comes from ain-util, which this workspace already depends on — node's `sha3-256` is NOT keccak256
+ * (different padding) and using it here would produce plausible, wrong nodes.
+ */
+export function namehash(name) {
+    let node = Buffer.alloc(32);
+    if (name) {
+        for (const label of name.toLowerCase().split('.').reverse()) {
+            if (!label)
+                continue;
+            const labelHash = Buffer.from(keccak(Buffer.from(label, 'utf8')));
+            node = Buffer.from(keccak(Buffer.concat([node, labelHash])));
+        }
+    }
+    return `0x${node.toString('hex')}`;
+}
+const selector = (sig) => `0x${hex(keccak(Buffer.from(sig, 'utf8'))).slice(0, 8)}`;
+const padWord = (h) => h.replace(/^0x/, '').padStart(64, '0');
+/** ABI-encode `text(bytes32 node, string key)` — one static word, then an offset and the string tail. */
+function encodeText(node, key) {
+    const keyBytes = Buffer.from(key, 'utf8');
+    const len = keyBytes.length.toString(16).padStart(64, '0');
+    const body = Buffer.concat([keyBytes, Buffer.alloc((32 - (keyBytes.length % 32)) % 32)]).toString('hex');
+    return selector('text(bytes32,string)') + padWord(node) + (64).toString(16).padStart(64, '0') + len + body;
+}
+/** Decode a single ABI-encoded string return value. Returns '' for an empty or absent record. */
+function decodeString(data) {
+    const raw = data.replace(/^0x/, '');
+    if (raw.length < 128)
+        return '';
+    const len = parseInt(raw.slice(64, 128), 16);
+    if (!Number.isFinite(len) || len === 0)
+        return '';
+    return Buffer.from(raw.slice(128, 128 + len * 2), 'hex').toString('utf8');
+}
+async function ethCall(rpc, to, data) {
+    const r = await fetch(rpc, {
+        method: 'POST', headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'eth_call', params: [{ to, data }, 'latest'] }),
+        signal: AbortSignal.timeout(20_000),
+    });
+    if (!r.ok)
+        throw new Error(`RPC ${r.status}`);
+    const j = await r.json();
+    if (j.error)
+        throw new Error(j.error.message);
+    return j.result ?? '0x';
+}
+function readNamesFile(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const j = JSON.parse(readFileSync(path, 'utf8'));
+        return ('names' in j && j.names ? j.names : j);
+    }
+    catch {
+        return null;
+    }
+}
+/** The places a names file may live, in the order they are consulted. */
+export function namesFileCandidates(opts = {}) {
+    const out = [];
+    if (opts.namesFile)
+        out.push(opts.namesFile);
+    if (opts.home)
+        out.push(join(opts.home, 'names.json'));
+    out.push(join(homedir(), '.ainize', 'names.json'));
+    return out;
+}
+/**
+ * Resolve `name` to the node and knowledge id it points at.
+ *
+ * Throws with BOTH paths named when neither works, because "cannot resolve" without saying what was tried is
+ * the error message that sends someone to the wrong place.
+ */
+export async function resolveName(name, opts = {}) {
+    const tried = [];
+    // 1. Local, in order: an explicit file, this home's names.json, ~/.ainize/names.json, then node config.
+    for (const path of namesFileCandidates(opts)) {
+        const names = readNamesFile(path);
+        tried.push(path);
+        const hit = names?.[name.toLowerCase()];
+        if (hit?.node && hit?.patch)
+            return { name, node: hit.node, patch: hit.patch, source: 'names-file', where: path };
+    }
+    const fromCfg = opts.config?.names?.[name.toLowerCase()];
+    if (fromCfg?.node && fromCfg?.patch)
+        return { name, node: fromCfg.node, patch: fromCfg.patch, source: 'config', where: 'config.json ens.names' };
+    tried.push('config.json ens.names');
+    // 2. On-chain. Both the RPC and the registry must be supplied; neither is guessed.
+    const rpc = opts.rpc ?? process.env.ENS_RPC_URL ?? opts.config?.rpc;
+    const registry = opts.registry ?? process.env.ENS_REGISTRY ?? opts.config?.registry;
+    if (rpc && registry) {
+        const node = namehash(name);
+        const resolverWord = await ethCall(rpc, registry, selector('resolver(bytes32)') + padWord(node));
+        const resolver = `0x${resolverWord.replace(/^0x/, '').slice(-40)}`;
+        if (/^0x0{40}$/.test(resolver))
+            throw new Error(`${name} has no resolver on the registry at ${registry}`);
+        const [nodeUrl, patchId] = await Promise.all([
+            ethCall(rpc, resolver, encodeText(node, NODE_KEY)).then(decodeString),
+            ethCall(rpc, resolver, encodeText(node, PATCH_KEY)).then(decodeString),
+        ]);
+        if (!nodeUrl || !patchId) {
+            throw new Error(`${name} resolves, but its ${!nodeUrl ? NODE_KEY : PATCH_KEY} text record is empty — the publisher has not pointed it at a knowledge yet`);
+        }
+        return { name, node: nodeUrl, patch: patchId, source: 'on-chain', where: `${resolver} via ${rpc}` };
+    }
+    tried.push(rpc ? 'on-chain (no registry address given)' : 'on-chain (no RPC given)');
+    throw new Error(`cannot resolve ${name}. Tried: ${tried.join(', ')}.\n` +
+        `Either add it to a names file — {"${name.toLowerCase()}": {"node": "http://host:3402", "patch": "<id>"}} — ` +
+        `or give both --rpc and --registry (ENSv2's contracts are not final, so the registry address is never assumed).`);
+}
+//# sourceMappingURL=ens.js.map

package/dist/ens.js.map

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

package/dist/help.d.ts

@@ -0,0 +1,57 @@
+/**
+ * What the CLI says when the command line itself is wrong (item 103).
+ *
+ * yargs' own answers are written for whoever wrote the parser: `Not enough non-option arguments: got 0, need at
+ * least 1` for `ainize publish`, `Unknown argument: statsu` for a one-character typo. Everything needed to answer
+ * properly is already in the command's own help — its usage line, its positionals, its options, its examples — so
+ * this module reads that help back and turns the parser's complaint into the sentence the person needed.
+ *
+ * Nothing here is a second copy of the command tree: the facts come from the help text yargs prints for the level
+ * that failed, which is generated from the declarations in bin.ts.
+ */
+/** One command's help, as read back from the block yargs printed for it. */
+export interface HelpFacts {
+    /** the first line of the usage block: `ainize patch publish <file>` */
+    usage: string;
+    /** the command words in front of the first positional: `ainize patch publish` */
+    path: string;
+    /** every subcommand registered at this level, by its own word (`ls`, `get`, `publish`) */
+    commands: string[];
+    /** every option this level accepts, with dashes (`--price`, `-y`) */
+    options: string[];
+    /** each positional and what it is for */
+    positionals: {
+        name: string;
+        describe: string | null;
+    }[];
+    /** the option describes, so a missing `--benchmark` can be named in the command's own words */
+    describes: Record<string, string>;
+    /** the first `.example()`, command and description */
+    example: {
+        cmd: string;
+        desc: string;
+    } | null;
+}
+/**
+ * Read a printed help block back into the facts an error message needs.
+ *
+ * yargs lays every block out the same way: two spaces, the name, two or more spaces, the description, and a type
+ * column at the end. A description too long for the terminal wraps onto lines indented past the name column, so
+ * those are folded back onto the entry they belong to instead of being read as another entry.
+ */
+export declare function readHelp(text: string): HelpFacts;
+/** Levenshtein distance, for "did you mean". */
+export declare function distance(a: string, b: string): number;
+/** The closest candidate within a small edit distance, or null when nothing is close enough to suggest. */
+export declare function nearest(word: string, candidates: string[]): string | null;
+export interface UsageError {
+    message: string;
+    hints: string[];
+    command: string;
+}
+/**
+ * Turn a yargs failure into the answer the person needed: what is missing or misspelled, in the command's own
+ * words, with its usage line and its first worked example underneath.
+ */
+export declare function explainUsageError(msg: string | null, err: Error | undefined, help: string, argv: string[]): UsageError;
+//# sourceMappingURL=help.d.ts.map

package/dist/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,4EAA4E;AAC5E,MAAM,WAAW,SAAS;IACxB,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb,0FAA0F;IAC1F,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,qEAAqE;IACrE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,yCAAyC;IACzC,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,EAAE,CAAC;IACzD,+FAA+F;IAC/F,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,sDAAsD;IACtD,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC/C;AAoBD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CA6DhD;AAED,gDAAgD;AAChD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAYrD;AAED,2GAA2G;AAC3G,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAQzE;AAED,MAAM,WAAW,UAAU;IAAG,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AAIjF;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CA8EtH"}

package/dist/help.js

@@ -0,0 +1,227 @@
+/**
+ * What the CLI says when the command line itself is wrong (item 103).
+ *
+ * yargs' own answers are written for whoever wrote the parser: `Not enough non-option arguments: got 0, need at
+ * least 1` for `ainize publish`, `Unknown argument: statsu` for a one-character typo. Everything needed to answer
+ * properly is already in the command's own help — its usage line, its positionals, its options, its examples — so
+ * this module reads that help back and turns the parser's complaint into the sentence the person needed.
+ *
+ * Nothing here is a second copy of the command tree: the facts come from the help text yargs prints for the level
+ * that failed, which is generated from the declarations in bin.ts.
+ */
+const BLOCK = /^(Commands|Options|Positionals|Examples):$/;
+/** The `[string] [required] [default: 3]` column yargs prints after a description — a type, not a sentence. */
+const TYPES = /(\s*\[(?:string|number|boolean|array|count|required|deprecated|hidden|default:[^\]]*|choices:[^\]]*)\])+$/;
+/** `ainize patch publish <file>` → `ainize patch publish` (stop at the first `<positional>` or `[option]`). */
+function pathOf(usage) {
+    const out = [];
+    for (const tok of usage.split(/\s+/)) {
+        if (tok.startsWith('<') || tok.startsWith('['))
+            break;
+        out.push(tok);
+    }
+    return out.join(' ');
+}
+/** `ainize patch get <id>` in a Commands: block → `get`: the word that names the subcommand at this level. */
+function commandWord(line, depth) {
+    const toks = line.trim().split(/\s+/);
+    const word = toks[depth];
+    return word && /^[a-z0-9][\w:-]*$/i.test(word) ? word : null;
+}
+/**
+ * Read a printed help block back into the facts an error message needs.
+ *
+ * yargs lays every block out the same way: two spaces, the name, two or more spaces, the description, and a type
+ * column at the end. A description too long for the terminal wraps onto lines indented past the name column, so
+ * those are folded back onto the entry they belong to instead of being read as another entry.
+ */
+export function readHelp(text) {
+    const lines = text.split('\n');
+    const usage = lines.find((l) => l.trim())?.trim() ?? '';
+    const path = pathOf(usage);
+    const depth = path.split(' ').filter(Boolean).length;
+    const facts = { usage, path, commands: [], options: [], positionals: [], describes: {}, example: null };
+    // the indented lines under each `Commands:` / `Options:` / `Positionals:` / `Examples:` heading
+    const blocks = new Map();
+    let cur = null;
+    for (const raw of lines) {
+        const line = raw.replace(/\s+$/, '');
+        const head = BLOCK.exec(line.trim());
+        if (head) {
+            cur = [];
+            blocks.set(head[1], cur);
+            continue;
+        }
+        if (!line.trim())
+            continue;
+        if (!line.startsWith(' ')) {
+            cur = null;
+            continue;
+        }
+        cur?.push(line);
+    }
+    /**
+     * Where an entry starts, per block: an option always begins with a dash (`  -h, --help` sits two columns left of
+     * `      --price`, so an indent rule would fold every long option into the short-alias one above it); a command
+     * and an example always begin with the program name; a positional is at the block's own left edge. Everything
+     * indented past that is a description too long for the terminal, and is folded back into the entry it belongs to.
+     */
+    const prog = path.split(' ')[0];
+    const entriesOf = (block) => {
+        const src = blocks.get(block) ?? [];
+        if (!src.length)
+            return [];
+        const left = Math.min(...src.map((l) => l.length - l.trimStart().length));
+        const isEntry = (line) => {
+            const body = line.trim();
+            if (block === 'Options')
+                return /^-{1,2}[A-Za-z0-9]/.test(body);
+            if (block === 'Commands' || block === 'Examples')
+                return body.split(/\s+/)[0] === prog;
+            return line.length - line.trimStart().length <= left;
+        };
+        const out = [];
+        for (const line of src) {
+            const body = line.trim();
+            const more = body.replace(TYPES, '').trim();
+            if (!isEntry(line) && out.length) {
+                const prev = out[out.length - 1];
+                // a wrapped description when there is one, otherwise the rest of a long command
+                if (prev.desc)
+                    prev.desc = `${prev.desc} ${more}`.trim();
+                else
+                    prev.name = `${prev.name} ${more}`.trim();
+                prev.raw = `${prev.raw} ${more}`.trim();
+                continue;
+            }
+            const at = body.search(/\s{2,}/);
+            out.push({ name: (at === -1 ? body : body.slice(0, at)).trim(), desc: (at === -1 ? '' : body.slice(at)).replace(TYPES, '').trim(), raw: more });
+        }
+        return out;
+    };
+    for (const e of entriesOf('Commands')) {
+        const w = commandWord(e.raw, depth);
+        if (w && !facts.commands.includes(w))
+            facts.commands.push(w);
+    }
+    for (const e of entriesOf('Options')) {
+        for (const n of e.name.split(/,\s*/))
+            if (n.startsWith('-')) {
+                facts.options.push(n);
+                if (e.desc)
+                    facts.describes[n] = e.desc;
+            }
+    }
+    for (const e of entriesOf('Positionals'))
+        facts.positionals.push({ name: e.name, describe: e.desc || null });
+    const ex = entriesOf('Examples')[0];
+    if (ex)
+        facts.example = { cmd: ex.name, desc: ex.desc };
+    return facts;
+}
+/** Levenshtein distance, for "did you mean". */
+export function distance(a, b) {
+    const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let diag = prev[0];
+        prev[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const t = prev[j];
+            prev[j] = Math.min(prev[j] + 1, prev[j - 1] + 1, diag + (a[i - 1] === b[j - 1] ? 0 : 1));
+            diag = t;
+        }
+    }
+    return prev[b.length];
+}
+/** The closest candidate within a small edit distance, or null when nothing is close enough to suggest. */
+export function nearest(word, candidates) {
+    let best = null;
+    let bestD = Infinity;
+    for (const cand of candidates) {
+        const d = distance(word.toLowerCase(), cand.toLowerCase());
+        if (d < bestD && d <= Math.max(2, Math.floor(cand.length / 3))) {
+            best = cand;
+            bestD = d;
+        }
+    }
+    return best;
+}
+const list = (xs) => (xs.length < 2 ? xs.join('') : `${xs.slice(0, -1).join(', ')} and ${xs[xs.length - 1]}`);
+/**
+ * Turn a yargs failure into the answer the person needed: what is missing or misspelled, in the command's own
+ * words, with its usage line and its first worked example underneath.
+ */
+export function explainUsageError(msg, err, help, argv) {
+    const f = readHelp(help);
+    const cmd = f.path || argv.filter((a) => !a.startsWith('-'))[0] || '';
+    const seeHelp = f.path ? `try \`${f.path} --help\`` : 'try `--help`';
+    const example = f.example ? [`example:`, `  ${f.example.cmd}${f.example.desc ? `   # ${f.example.desc}` : ''}`] : [];
+    const usageLine = f.usage ? [`usage: ${f.usage}`] : [];
+    // A `.check()` or a coercion threw: it already speaks the user's language.
+    if (err?.message)
+        return { message: err.message, hints: [seeHelp], command: cmd };
+    const m = msg ?? 'invalid command line';
+    // The word the user typed where a subcommand belongs — the one yargs' own "Did you mean" never names.
+    const typed = argv.filter((a) => !a.startsWith('-'));
+    const depth = f.path.split(' ').filter(Boolean).length - 1; // minus the program name
+    const typo = typed[depth] ?? typed[typed.length - 1] ?? null;
+    const recommend = /^Did you mean (.+)\?$/.exec(m);
+    if (recommend) {
+        const suggestion = recommend[1].replace(/\?$/, '');
+        return {
+            message: typo ? `unknown command "${typo}" — did you mean \`${f.path} ${suggestion}\`?` : `did you mean \`${f.path} ${suggestion}\`?`,
+            hints: [`\`${f.path} --help\` lists every command here.`],
+            command: cmd,
+        };
+    }
+    const unknown = /^Unknown arguments?: (.+)$/.exec(m);
+    if (unknown) {
+        const names = unknown[1].split(/,\s*/).map((s) => s.trim()).filter(Boolean);
+        const flags = names.filter((n) => argv.some((a) => a === `--${n}` || a === `-${n}` || a.startsWith(`--${n}=`)));
+        const words = names.filter((n) => !flags.includes(n));
+        const parts = [];
+        const hints = [];
+        for (const w of words) {
+            const near = nearest(w, f.commands);
+            parts.push(`unknown command "${w}"${near ? ` — did you mean \`${f.path} ${near}\`?` : ''}`);
+        }
+        for (const flag of flags) {
+            const near = nearest(`--${flag}`, f.options);
+            parts.push(`unknown option "--${flag}"${near ? ` — did you mean \`${near}\`?` : ''}`);
+        }
+        if (words.length && !words.some((w) => nearest(w, f.commands)))
+            hints.push(`\`${f.path} --help\` lists every command here.`);
+        if (!parts.length)
+            parts.push(m);
+        hints.push(seeHelp);
+        return { message: parts.join('; '), hints, command: cmd };
+    }
+    if (/^Not enough non-option arguments/.test(m)) {
+        const need = f.positionals.filter((p) => p.describe !== null);
+        const what = need.length ? list(need.map((p) => `<${p.name}>`)) : 'an argument';
+        const said = need.map((p) => `${p.name}: ${p.describe}`);
+        return { message: `\`${f.path}\` needs ${what}`, hints: [...said, ...usageLine, ...example, seeHelp], command: cmd };
+    }
+    const missing = /^Missing required arguments?: (.+)$/.exec(m);
+    if (missing) {
+        const names = missing[1].split(/,\s*/).map((s) => s.trim()).filter(Boolean);
+        const said = names.map((n) => (f.describes[`--${n}`] ? `--${n}: ${f.describes[`--${n}`]}` : null)).filter((x) => !!x);
+        return { message: `\`${f.path}\` needs ${list(names.map((n) => `--${n}`))}`, hints: [...said, ...usageLine, ...example, seeHelp], command: cmd };
+    }
+    // demandCommand: "Specify a command…" / "Subcommand is required (ls|add|rm)."
+    if (/command is required|Specify a command|Give a dataset file/i.test(m)) {
+        // `ainize --hepl` reaches demandCommand before strict() ever looks at the flag, and used to be reported as a
+        // missing command. An option that no longer exists is an option, and is named as one.
+        const bad = argv.filter((a) => /^--?[A-Za-z]/.test(a)).map((a) => a.split('=')[0])
+            .filter((a) => !f.options.includes(a) && !f.options.includes(a.replace(/^--no-/, '--')));
+        if (bad.length) {
+            const near = nearest(bad[0], f.options);
+            return { message: `unknown option "${bad[0]}"${near ? ` — did you mean \`${near}\`?` : ''}`, hints: [seeHelp], command: cmd };
+        }
+        // the demandCommand message already names them on most groups; only add the list when it does not
+        const hints = f.commands.length && !/\(.+\|.+\)/.test(m) ? [`commands here: ${f.commands.join(', ')}`, seeHelp] : [seeHelp];
+        return { message: m, hints, command: cmd };
+    }
+    return { message: m, hints: [seeHelp], command: cmd };
+}
+//# sourceMappingURL=help.js.map