@agtnames/cli 0.0.0-stage → 0.1.0

package/dist/signer.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Who signs. Every write command takes a Signer, so the commands never see a key:
+ *
+ *   browser   (default) a local page asks MetaMask, or any injected wallet, to approve each signature (browser.ts)
+ *   key       a 0x-prefixed private key in an environment variable (AGT_OWNER_KEY, or the one --key-env names)
+ *   keyfile   a passphrase-encrypted key file (keyfile.ts), for automation that should not hold a raw key in env
+ *
+ * A key is never read from a command-line argument, where it would land in shell history.
+ */
+import { type Address, type Hex } from "viem";
+import type { Network } from "./config.js";
+export interface TxRequest {
+    to: Address;
+    data: Hex;
+    value?: bigint;
+    /** One line shown in the wallet page and the terminal: what this transaction does. */
+    description: string;
+}
+export interface Signer {
+    kind: "browser" | "key" | "keyfile";
+    address: Address;
+    /** EIP-191 personal_sign over the UTF-8 message. */
+    signMessage(message: string, description: string): Promise<Hex>;
+    sendTransaction(tx: TxRequest): Promise<Hex>;
+    close(): Promise<void>;
+}
+/**
+ * Check a private key's shape before use and say what is wrong in plain words. The traps from the first terminal run:
+ * a missing 0x, a passphrase pasted where the key belongs, and an address pasted where the key belongs.
+ */
+export declare function parsePrivateKey(raw: string | undefined, source: string): Hex;
+export declare function keySigner(pk: Hex, network: Network, kind?: "key" | "keyfile"): Signer;

package/dist/signer.js

@@ -0,0 +1,40 @@
+/**
+ * Who signs. Every write command takes a Signer, so the commands never see a key:
+ *
+ *   browser   (default) a local page asks MetaMask, or any injected wallet, to approve each signature (browser.ts)
+ *   key       a 0x-prefixed private key in an environment variable (AGT_OWNER_KEY, or the one --key-env names)
+ *   keyfile   a passphrase-encrypted key file (keyfile.ts), for automation that should not hold a raw key in env
+ *
+ * A key is never read from a command-line argument, where it would land in shell history.
+ */
+import { createWalletClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+/**
+ * Check a private key's shape before use and say what is wrong in plain words. The traps from the first terminal run:
+ * a missing 0x, a passphrase pasted where the key belongs, and an address pasted where the key belongs.
+ */
+export function parsePrivateKey(raw, source) {
+    const v = (raw ?? "").trim();
+    if (!v)
+        throw new Error(`${source} is empty. Set it to the name owner's private key (0x followed by 64 hex characters).`);
+    if (/^0x[0-9a-fA-F]{64}$/.test(v))
+        return v;
+    if (/^[0-9a-fA-F]{64}$/.test(v))
+        throw new Error(`${source} is missing the 0x prefix. Use 0x${v.slice(0, 4)}… (0x followed by the 64 hex characters).`);
+    if (/^0x[0-9a-fA-F]{40}$/.test(v))
+        throw new Error(`${source} holds an address, not a private key. The key is 64 hex characters; the address is 40.`);
+    if (/^0x[0-9a-fA-F]*$/.test(v))
+        throw new Error(`${source} is ${v.length - 2} hex characters after 0x; a private key is exactly 64.`);
+    throw new Error(`${source} is not a private key. If this is your keyfile passphrase, pass the file with --keyfile and the passphrase in AGT_KEYFILE_PASSPHRASE instead.`);
+}
+export function keySigner(pk, network, kind = "key") {
+    const account = privateKeyToAccount(pk);
+    const wallet = createWalletClient({ account, chain: network.chain, transport: http(network.rpcUrls[0]) });
+    return {
+        kind,
+        address: account.address,
+        signMessage: (message) => account.signMessage({ message }),
+        sendTransaction: (tx) => wallet.sendTransaction({ to: tx.to, data: tx.data, value: tx.value ?? 0n }),
+        close: async () => { },
+    };
+}

package/dist/tui.d.ts

@@ -0,0 +1,62 @@
+export interface Key {
+    name?: string;
+    ctrl?: boolean;
+    meta?: boolean;
+    shift?: boolean;
+    sequence?: string;
+}
+export interface Frame {
+    lines: string[];
+    cursor: {
+        row: number;
+        col: number;
+    };
+}
+export interface Widget<T> {
+    render(): Frame;
+    /** Return { done: value } to finish; anything else redraws. */
+    onKey(str: string | undefined, key: Key): {
+        done: T;
+    } | void | Promise<{
+        done: T;
+    } | void>;
+    /** The one line left on screen after the widget finishes. */
+    summary(value: T): string;
+    /** Shown when the step is skipped. */
+    label?: string;
+    /** Called with a redraw function, for widgets that change on their own (timers, background data). */
+    attach?(redraw: () => void): void;
+    detach?(): void;
+}
+export declare class CancelledError extends Error {
+    constructor();
+}
+/** Step navigation a widget can return instead of a value: `j` goes back a step, `;` skips it. */
+export declare const BACK: unique symbol;
+export declare const SKIP: unique symbol;
+export type Nav = typeof BACK | typeof SKIP;
+export declare const isNav: (v: unknown) => v is Nav;
+/** Erase the last `n` printed lines (a finished step's summary) so a step re-opens in place. */
+export declare function eraseLines(n: number): void;
+export declare const style: {
+    bold: (s: string) => string;
+    dim: (s: string) => string;
+    italic: (s: string) => string;
+    cyan: (s: string) => string;
+    green: (s: string) => string;
+    red: (s: string) => string;
+    yellow: (s: string) => string;
+    inverse: (s: string) => string;
+    /** A grey from the 256-colour ramp, 232 (black) … 255 (white); used for the examples fade. */
+    grey: (level: number) => (s: string) => string;
+};
+export declare const visibleLength: (s: string) => number;
+/** Cut a styled line to `width` visible characters, keeping escape codes intact. */
+export declare function truncate(s: string, width: number): string;
+export declare function isInteractive(): boolean;
+export declare function run<T>(widget: Widget<T | Nav>): Promise<T | Nav>;
+/**
+ * Copy text: OSC 52 (understood by Windows Terminal, iTerm2, kitty, most modern terminals, and over SSH) plus the
+ * platform's clipboard tool. Either one is enough; failures are silent.
+ */
+export declare function copyToClipboard(text: string): void;

package/dist/tui.js

@@ -0,0 +1,153 @@
+/**
+ * The terminal layer for interactive prompts (RATIONALE R-1). A widget renders a block of lines plus a cursor
+ * position; the runner redraws the whole block on every change and parks the cursor exactly there, so faint text can
+ * sit after the cursor (RATIONALE R-5). Lines are cut to the terminal width so nothing wraps and breaks the redraw.
+ */
+import { spawn } from "node:child_process";
+import { emitKeypressEvents } from "node:readline";
+export class CancelledError extends Error {
+    constructor() { super("cancelled"); this.name = "CancelledError"; }
+}
+/** Step navigation a widget can return instead of a value: `j` goes back a step, `;` skips it. */
+export const BACK = Symbol("back");
+export const SKIP = Symbol("skip");
+export const isNav = (v) => v === BACK || v === SKIP;
+/** Erase the last `n` printed lines (a finished step's summary) so a step re-opens in place. */
+export function eraseLines(n) {
+    if (n > 0 && process.stdout.isTTY)
+        process.stdout.write(`\x1b[${n}A\r\x1b[J`);
+}
+// ── styles ────────────────────────────────────────────────────────────────────────────────────────────────────────
+const color = process.env.NO_COLOR === undefined && process.stdout.isTTY;
+const wrap = (open, close) => (s) => (color ? `\x1b[${open}m${s}\x1b[${close}m` : s);
+export const style = {
+    bold: wrap("1", "22"),
+    dim: wrap("2", "22"),
+    italic: wrap("3", "23"),
+    cyan: wrap("36", "39"),
+    green: wrap("32", "39"),
+    red: wrap("31", "39"),
+    yellow: wrap("33", "39"),
+    inverse: wrap("7", "27"),
+    /** A grey from the 256-colour ramp, 232 (black) … 255 (white); used for the examples fade. */
+    grey: (level) => (s) => (color ? `\x1b[38;5;${level}m${s}\x1b[39m` : s),
+};
+const ANSI = /\x1b\[[0-9;]*m|\x1b\]52;[^\x07]*\x07/g;
+export const visibleLength = (s) => s.replace(ANSI, "").length;
+/** Cut a styled line to `width` visible characters, keeping escape codes intact. */
+export function truncate(s, width) {
+    if (visibleLength(s) <= width)
+        return s;
+    let out = "";
+    let seen = 0;
+    let i = 0;
+    while (i < s.length && seen < width - 1) {
+        const m = s[i] === "\x1b" ? /^\x1b\[[0-9;]*m/.exec(s.slice(i)) : null;
+        if (m) {
+            out += m[0];
+            i += m[0].length;
+            continue;
+        }
+        out += s[i];
+        seen++;
+        i++;
+    }
+    return out + "…" + (color ? "\x1b[0m" : "");
+}
+// ── runner ────────────────────────────────────────────────────────────────────────────────────────────────────────
+let keypressReady = false;
+export function isInteractive() {
+    return !!(process.stdin.isTTY && process.stdout.isTTY);
+}
+export function run(widget) {
+    const out = process.stdout;
+    const stdin = process.stdin;
+    if (!keypressReady) {
+        emitKeypressEvents(stdin);
+        keypressReady = true;
+    }
+    let cursorRow = 0; // row the cursor sits on, within the block
+    let finished = false;
+    const draw = () => {
+        if (finished)
+            return;
+        const width = Math.max(20, (out.columns ?? 80) - 1);
+        const f = widget.render();
+        const lines = f.lines.map((l) => truncate(l, width));
+        let s = "\x1b[?25l"; // hide cursor while drawing
+        if (cursorRow > 0)
+            s += `\x1b[${cursorRow}A`;
+        s += "\r\x1b[J" + lines.join("\n");
+        const up = lines.length - 1 - f.cursor.row;
+        if (up > 0)
+            s += `\x1b[${up}A`;
+        s += "\r" + (f.cursor.col > 0 ? `\x1b[${Math.min(f.cursor.col, width)}C` : "") + "\x1b[?25h";
+        out.write(s);
+        cursorRow = f.cursor.row;
+    };
+    return new Promise((resolve, reject) => {
+        const finish = (err, value) => {
+            if (finished)
+                return;
+            widget.detach?.();
+            stdin.removeListener("keypress", onKey);
+            out.removeListener("resize", draw);
+            // Replace the block with the one-line summary.
+            let s = cursorRow > 0 ? `\x1b[${cursorRow}A` : "";
+            const width = Math.max(20, (out.columns ?? 80) - 1);
+            // Back: leave nothing, the previous step re-opens where this one was. Skip: one dim line. Done: the summary.
+            if (value === BACK && !err)
+                s += "\r\x1b[J";
+            else
+                s += "\r\x1b[J" + truncate(err ? style.dim("✗ cancelled") : value === SKIP ? style.dim(`↷ ${widget.label ?? "step"} skipped`) : widget.summary(value), width) + "\n";
+            out.write(s);
+            finished = true;
+            if (stdin.isTTY)
+                stdin.setRawMode(false);
+            stdin.pause();
+            if (err)
+                reject(err);
+            else
+                resolve(value);
+        };
+        const onKey = async (str, key = {}) => {
+            if (key.ctrl && key.name === "c")
+                return finish(new CancelledError());
+            try {
+                const r = await widget.onKey(str, key);
+                if (r && "done" in r)
+                    return finish(null, r.done);
+                draw();
+            }
+            catch (e) {
+                finish(e);
+            }
+        };
+        if (stdin.isTTY)
+            stdin.setRawMode(true);
+        stdin.resume();
+        stdin.on("keypress", onKey);
+        out.on("resize", draw);
+        widget.attach?.(draw);
+        draw();
+    });
+}
+// ── clipboard ─────────────────────────────────────────────────────────────────────────────────────────────────────
+/**
+ * Copy text: OSC 52 (understood by Windows Terminal, iTerm2, kitty, most modern terminals, and over SSH) plus the
+ * platform's clipboard tool. Either one is enough; failures are silent.
+ */
+export function copyToClipboard(text) {
+    if (process.stdout.isTTY)
+        process.stdout.write(`\x1b]52;c;${Buffer.from(text, "utf8").toString("base64")}\x07`);
+    const [cmd, args] = process.platform === "win32" ? ["clip", []]
+        : process.platform === "darwin" ? ["pbcopy", []]
+            : process.env.WAYLAND_DISPLAY ? ["wl-copy", []] : ["xclip", ["-selection", "clipboard"]];
+    try {
+        const p = spawn(cmd, args, { stdio: ["pipe", "ignore", "ignore"] });
+        p.on("error", () => { });
+        p.stdin.on("error", () => { });
+        p.stdin.end(text);
+    }
+    catch { /* OSC 52 already sent */ }
+}

package/dist/verify.d.ts

@@ -0,0 +1,32 @@
+/**
+ * verify: the three-way check (manifest signer == manifest owner == on-chain owner) from @agtnames/resolver, plus a
+ * liveness probe of every on-chain endpoint. An endpoint is live when `<origin>/health` answers 2xx, or, failing
+ * that, when the endpoint URL itself answers below 500 (an MCP endpoint answers GET with 405 or 406, which is alive).
+ */
+import { type AgentResolution } from "@agtnames/resolver";
+import type { Network } from "./config.js";
+export interface EndpointCheck {
+    protocol: string;
+    url: string;
+    live: boolean;
+    via: "health" | "endpoint" | null;
+    status: number | null;
+    error?: string;
+}
+export interface VerifyReport {
+    name: string;
+    ok: boolean;
+    verified: boolean;
+    manifestStatus: AgentResolution["manifestStatus"];
+    owner: string | null;
+    signer: string | null;
+    manifestUri: string;
+    reasons: string[];
+    endpoints: EndpointCheck[];
+    problems: string[];
+}
+export declare function checkEndpoint(protocol: string, url: string, fetchImpl?: typeof fetch, timeoutMs?: number): Promise<EndpointCheck>;
+export declare function verifyName(n: Network, label: string, opts?: {
+    fetchImpl?: typeof fetch;
+    skipEndpoints?: boolean;
+}): Promise<VerifyReport>;

package/dist/verify.js

@@ -0,0 +1,71 @@
+/**
+ * verify: the three-way check (manifest signer == manifest owner == on-chain owner) from @agtnames/resolver, plus a
+ * liveness probe of every on-chain endpoint. An endpoint is live when `<origin>/health` answers 2xx, or, failing
+ * that, when the endpoint URL itself answers below 500 (an MCP endpoint answers GET with 405 or 406, which is alive).
+ */
+import { AgtResolver } from "@agtnames/resolver";
+async function probe(url, fetchImpl, timeoutMs) {
+    try {
+        const r = await fetchImpl(url, { method: "GET", redirect: "follow", signal: AbortSignal.timeout(timeoutMs), headers: { accept: "application/json, text/event-stream, */*" } });
+        await r.body?.cancel().catch(() => { });
+        return r.status;
+    }
+    catch {
+        return null;
+    }
+}
+export async function checkEndpoint(protocol, url, fetchImpl = fetch, timeoutMs = 10_000) {
+    let origin;
+    try {
+        origin = new URL(url).origin;
+    }
+    catch {
+        return { protocol, url, live: false, via: null, status: null, error: "not a URL" };
+    }
+    const h = await probe(`${origin}/health`, fetchImpl, timeoutMs);
+    if (h !== null && h >= 200 && h < 300)
+        return { protocol, url, live: true, via: "health", status: h };
+    const e = await probe(url, fetchImpl, timeoutMs);
+    if (e !== null && e < 500)
+        return { protocol, url, live: true, via: "endpoint", status: e };
+    return { protocol, url, live: false, via: null, status: e ?? h, error: e === null && h === null ? "no response" : `HTTP ${e ?? h}` };
+}
+export async function verifyName(n, label, opts = {}) {
+    const resolver = new AgtResolver({ chain: n.name, rpcUrls: n.rpcUrls, registry: n.registry });
+    const r = await resolver.resolveAgent(`${label}.agt`);
+    const onchain = Object.entries(r.records.endpoints);
+    const endpoints = opts.skipEndpoints ? [] : await Promise.all(onchain.map(([p, u]) => checkEndpoint(p, u, opts.fetchImpl)));
+    const problems = [];
+    if (!r.registered)
+        problems.push("not registered");
+    else if (!r.active)
+        problems.push("registered but not active (expired?)");
+    if (r.registered && r.manifestStatus === "none")
+        problems.push("no manifest published (run `agt manifest publish`)");
+    if (r.manifestStatus === "unavailable")
+        problems.push("the manifest pointer is set but no gateway returned the document (transport; retry later)");
+    if (r.manifestStatus === "unverified")
+        problems.push(`manifest does not verify: ${r.reasons.join("; ")}`);
+    const declared = new Map((r.manifest?.endpoints ?? []).map((e) => [e.protocol, e.url]));
+    for (const [p, u] of declared)
+        if (r.records.endpoints[p] !== undefined && r.records.endpoints[p] !== u)
+            problems.push(`endpoint ${p}: manifest says ${u}, on-chain record says ${r.records.endpoints[p]}`);
+    for (const [p, u] of declared)
+        if (r.records.endpoints[p] === undefined && ["mcp", "a2a", "http", "ws"].includes(p))
+            problems.push(`endpoint ${p} (${u}) is in the manifest but not on-chain (run \`agt records set\`)`);
+    for (const e of endpoints)
+        if (!e.live)
+            problems.push(`endpoint ${e.protocol} ${e.url} is not reachable (${e.error})`);
+    return {
+        name: `${label}.agt`,
+        ok: problems.length === 0 && r.verified,
+        verified: r.verified,
+        manifestStatus: r.manifestStatus,
+        owner: r.owner,
+        signer: r.signer,
+        manifestUri: r.records.manifestUri,
+        reasons: r.reasons,
+        endpoints,
+        problems,
+    };
+}

package/dist/widgets.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Prompt widgets. The placeholder rules (RATIONALE R-5, R-6):
+ *   prefill      a prediction from real data, dim after the cursor; Tab fills it, Enter submits. Typing over it never
+ *                loses it: it stays on the hint line, ↑ puts it back, ^Y copies it.
+ *   instruction  says what to enter; in the field when there is no prefill, otherwise on the label line. Always primary.
+ *   examples     only on an empty field after ~3 s idle, fading in italic below it; never fillable.
+ *
+ * Step navigation: `j` goes back a step and `;` skips it. In lists they are plain keys; in a typing field they act
+ * only while the field is empty, so a value containing j or ; types normally.
+ */
+import { type Frame, type Key, type Nav, type Widget } from "./tui.js";
+export interface TextOptions {
+    label: string;
+    instruction: string;
+    prefill?: string;
+    /** Where the prefill came from, shown beside it ("from your MCP server"). */
+    prefillSource?: string;
+    examples?: string[];
+    initial?: string;
+    optional?: boolean;
+    /** Soft length guide: a counter, red past the limit. */
+    maxLength?: number;
+    /** Error message, or null when fine. */
+    validate?: (v: string) => string | null;
+    /** Live note under the field (e.g. "✓ live"), recomputed on every redraw. */
+    note?: () => string | null;
+    /** j / ; on an empty field go back / skip (default true). Off for fields embedded in another widget. */
+    nav?: boolean;
+}
+export declare const NAV_HINT = "j back \u00B7 ; skip";
+export declare class TextInput implements Widget<string | Nav> {
+    private o;
+    value: string;
+    pos: number;
+    private error;
+    private flash;
+    private lastKey;
+    private timer?;
+    get label(): string;
+    constructor(o: TextOptions);
+    private get prefill();
+    attach(redraw: () => void): void;
+    detach(): void;
+    private say;
+    render(): Frame;
+    onKey(str: string | undefined, key: Key): {
+        done: string | Nav;
+    } | void;
+    summary(v: string | Nav): string;
+}
+export interface Choice<T> {
+    value: T;
+    label: string;
+    description?: string;
+}
+export declare class Select<T> implements Widget<T | Nav> {
+    private o;
+    private i;
+    get label(): string;
+    constructor(o: {
+        label: string;
+        instruction: string;
+        choices: Choice<T>[];
+        initial?: T;
+        prefillSource?: string;
+    });
+    render(): Frame;
+    onKey(str: string | undefined, key: Key): {
+        done: T | Nav;
+    } | void;
+    summary(v: T | Nav): string;
+}
+export declare class Checkbox<T> implements Widget<T[] | Nav> {
+    private o;
+    private i;
+    get label(): string;
+    private on;
+    private error;
+    constructor(o: {
+        label: string;
+        instruction: string;
+        choices: Choice<T>[];
+        initial?: T[];
+        min?: number;
+    });
+    render(): Frame;
+    onKey(str: string | undefined, key: Key): {
+        done: T[] | Nav;
+    } | void;
+    summary(v: T[] | Nav): string;
+}