@agtnames/cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AGT Domains LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+# @agtnames/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The `agt` command: register a `.agt` name, publish its signed manifest, set its records and verify the result, all from a terminal.
+
+```bash
+npx @agtnames/cli --help
+```
+
+It signs in MetaMask by default. `agt` opens a page on `127.0.0.1` and you approve each signature and transaction in your wallet, so the private key never leaves it. Any browser wallet that injects `window.ethereum` works the same way. For automation, it can also sign with a key from an environment variable or from an encrypted keyfile.
+
+## From nothing to a verified agent
+
+```bash
+agt available weather                     # price and availability
+agt register weather --years 1            # quote → approve USDC → register, approved in your wallet
+agt manifest init weather                 # writes weather.manifest.json to fill in
+agt manifest publish weather weather.manifest.json
+agt verify weather                        # signer == manifest owner == on-chain owner, endpoints live
+```
+
+`register` pays in USDC on Polygon and needs a little POL for gas. The quote the site signs is good for about 15 minutes, so the approval and the registration go out one after the other.
+
+`manifest publish` does four things:
+
+1. checks that every endpoint in the file answers;
+2. signs the manifest in your wallet (EIP-191 over the canonical JSON);
+3. hosts it at `https://agts.dev/<name>.json`, or on IPFS with `--host ipfs`;
+4. sets the on-chain records in one transaction: the manifest pointer, one endpoint per protocol, `addr`, and the agent wallet if the manifest lists a payment address.
+
+Pass `--no-records` to host the document without writing the records.
+
+## Commands
+
+```
+agt available <name>
+agt register <name> [--years N] [--to 0x…] [--dry-run] [--yes]
+agt manifest init <name> [--out file.json]
+agt manifest publish <name> <file.json> [--host agts.dev|ipfs] [--no-records] [--skip-live-check] [--dry-run]
+agt records set <name> [--mcp URL] [--a2a URL] [--http URL] [--ws URL] [--wallet 0x…] [--addr 0x…] [--manifest URI] [--dry-run]
+agt verify <name> [--no-endpoints] [--json]
+agt keyfile create <file>
+agt keyfile address <file>
+```
+
+With `--dry-run`, a write command signs what needs signing, prints the exact document and transactions, and sends nothing. With `--json`, the result goes to stdout as JSON and progress goes to stderr. Exit codes: 0 done, 1 failed or `verify` found a problem, 2 usage error.
+
+## Signing
+
+| How | Flag | Key source |
+|---|---|---|
+| MetaMask or another browser wallet (default) | none, or `--no-open` to print the page URL | stays in the wallet |
+| Environment variable | `--signer key`, or `--key-env NAME` | `AGT_OWNER_KEY`, or the variable you name |
+| Encrypted keyfile | `--keyfile owner.json` | passphrase from `AGT_KEYFILE_PASSPHRASE` or a hidden prompt |
+
+A key is never taken from a command-line argument, where it would end up in shell history. `agt keyfile create` reads the key and passphrase at hidden prompts. It uses the same format as `@agtnames/mcp`'s session key: scrypt, then AES-256-GCM, with the address stored in the clear.
+
+The wallet page listens only on `127.0.0.1` under a random path. It refuses requests carrying another Host or Origin, and runs under a strict content security policy. The CLI checks everything that comes back: a signature must recover to the connected account, and the page re-checks the chain and account before each transaction.
+
+## Registering for someone else
+
+`agt register <name> --to 0x…` pays from your wallet and mints the name to another address. Only that address can then publish the manifest or set records. A manifest signed by anyone else shows as unverified.
+
+## Networks
+
+`--network polygon` (the default) or `--network amoy`. `--rpc URL` overrides the RPC endpoint (default: the resolver's public fallback list). `--site URL` overrides where quotes and manifest hosting come from (default `https://agtnames.com`). Amoy has no public site, so pass `--site`, for example a local `next dev`. The same settings can come from `AGT_NETWORK`, `AGT_RPC_URL` and `AGT_SITE`.
+
+## License
+
+MIT

package/dist/abi.d.ts

@@ -0,0 +1,239 @@
+export declare const controllerAbi: readonly [{
+    readonly name: "register";
+    readonly type: "function";
+    readonly stateMutability: "payable";
+    readonly inputs: readonly [{
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly type: "string";
+            readonly name: "label";
+        }, {
+            readonly type: "address";
+            readonly name: "to";
+        }, {
+            readonly type: "address";
+            readonly name: "payToken";
+        }, {
+            readonly type: "uint256";
+            readonly name: "price";
+        }, {
+            readonly type: "uint64";
+            readonly name: "duration";
+        }, {
+            readonly type: "uint64";
+            readonly name: "validUntil";
+        }, {
+            readonly type: "bytes32";
+            readonly name: "nonce";
+        }];
+        readonly name: "q";
+    }, {
+        readonly type: "bytes";
+        readonly name: "sig";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "available";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "string";
+        readonly name: "label";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly name: "valid";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "string";
+        readonly name: "label";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly name: "paused";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly name: "usedNonce";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}];
+export declare const registryAbi: readonly [{
+    readonly name: "tokenIdOf";
+    readonly type: "function";
+    readonly stateMutability: "pure";
+    readonly inputs: readonly [{
+        readonly type: "string";
+        readonly name: "label";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "ownerOf";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "tokenId";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "address";
+    }];
+}, {
+    readonly name: "resolverOf";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "tokenId";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "address";
+    }];
+}];
+export declare const resolverAbi: readonly [{
+    readonly name: "setAgentManifest";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly type: "bytes32";
+        readonly name: "node";
+    }, {
+        readonly type: "string";
+        readonly name: "uri";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly name: "setAgentEndpoint";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly type: "bytes32";
+        readonly name: "node";
+    }, {
+        readonly type: "string";
+        readonly name: "protocol";
+    }, {
+        readonly type: "string";
+        readonly name: "url";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly name: "setAddr";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly type: "bytes32";
+        readonly name: "node";
+    }, {
+        readonly type: "address";
+        readonly name: "a";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly name: "setAgentWallet";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly type: "bytes32";
+        readonly name: "node";
+    }, {
+        readonly type: "address";
+        readonly name: "wallet";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly name: "agentManifest";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "bytes32";
+        readonly name: "node";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "string";
+    }];
+}, {
+    readonly name: "agentEndpoint";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "bytes32";
+        readonly name: "node";
+    }, {
+        readonly type: "string";
+        readonly name: "protocol";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "string";
+    }];
+}, {
+    readonly name: "multicall";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly type: "bytes[]";
+        readonly name: "data";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bytes[]";
+    }];
+}];
+export declare const erc20Abi: readonly [{
+    readonly name: "allowance";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "owner";
+    }, {
+        readonly type: "address";
+        readonly name: "spender";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "approve";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "spender";
+    }, {
+        readonly type: "uint256";
+        readonly name: "amount";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly name: "balanceOf";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "account";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}];

package/dist/abi.js

@@ -0,0 +1,32 @@
+/**
+ * The contract surface the CLI writes through. Mirrors the site's src/lib/agt-abi.ts (source of truth:
+ * contracts/contracts/launch/*.sol); only what the four write commands need.
+ */
+import { parseAbi } from "viem";
+export const controllerAbi = parseAbi([
+    "struct Quote { string label; address to; address payToken; uint256 price; uint64 duration; uint64 validUntil; bytes32 nonce; }",
+    "function register(Quote q, bytes sig) payable returns (uint256)",
+    "function available(string label) view returns (bool)",
+    "function valid(string label) view returns (bool)",
+    "function paused() view returns (bool)",
+    "function usedNonce(bytes32) view returns (bool)",
+]);
+export const registryAbi = parseAbi([
+    "function tokenIdOf(string label) pure returns (uint256)",
+    "function ownerOf(uint256 tokenId) view returns (address)",
+    "function resolverOf(uint256 tokenId) view returns (address)",
+]);
+export const resolverAbi = parseAbi([
+    "function setAgentManifest(bytes32 node, string uri)",
+    "function setAgentEndpoint(bytes32 node, string protocol, string url)",
+    "function setAddr(bytes32 node, address a)",
+    "function setAgentWallet(bytes32 node, address wallet)",
+    "function agentManifest(bytes32 node) view returns (string)",
+    "function agentEndpoint(bytes32 node, string protocol) view returns (string)",
+    "function multicall(bytes[] data) returns (bytes[])",
+]);
+export const erc20Abi = parseAbi([
+    "function allowance(address owner, address spender) view returns (uint256)",
+    "function approve(address spender, uint256 amount) returns (bool)",
+    "function balanceOf(address account) view returns (uint256)",
+]);

package/dist/args.d.ts

@@ -0,0 +1,15 @@
+/** Argument parsing: positionals, `--flag value`, `--flag=value`, and declared booleans. Unknown flags are errors. */
+export declare class UsageError extends Error {
+    constructor(m: string);
+}
+export declare const BOOLEAN_FLAGS: readonly ["dry-run", "json", "yes", "no-open", "no-records", "no-endpoints", "skip-live-check", "template", "no-probe", "help", "version"];
+export declare const VALUE_FLAGS: readonly ["network", "rpc", "site", "signer", "key-env", "keyfile", "years", "to", "host", "out", "mcp", "a2a", "http", "ws", "wallet", "addr", "manifest", "timeout", "shell"];
+export interface Parsed {
+    positionals: string[];
+    flags: Record<string, string>;
+    bools: Set<string>;
+}
+export declare function parseArgs(argv: string[]): Parsed;
+export declare function parseYears(v: string | undefined): number;
+export declare function parseAddressFlag(v: string | undefined, flag: string): `0x${string}` | undefined;
+export declare function parseHttpsFlag(v: string | undefined, flag: string): string | undefined;

package/dist/args.js

@@ -0,0 +1,66 @@
+/** Argument parsing: positionals, `--flag value`, `--flag=value`, and declared booleans. Unknown flags are errors. */
+export class UsageError extends Error {
+    constructor(m) { super(m); this.name = "UsageError"; }
+}
+export const BOOLEAN_FLAGS = ["dry-run", "json", "yes", "no-open", "no-records", "no-endpoints", "skip-live-check", "template", "no-probe", "help", "version"];
+export const VALUE_FLAGS = ["network", "rpc", "site", "signer", "key-env", "keyfile", "years", "to", "host", "out", "mcp", "a2a", "http", "ws", "wallet", "addr", "manifest", "timeout", "shell"];
+export function parseArgs(argv) {
+    const positionals = [];
+    const flags = {};
+    const bools = new Set();
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "-h") {
+            bools.add("help");
+            continue;
+        }
+        if (!a.startsWith("--")) {
+            positionals.push(a);
+            continue;
+        }
+        const eq = a.indexOf("=");
+        const name = a.slice(2, eq > 0 ? eq : undefined);
+        if (BOOLEAN_FLAGS.includes(name)) {
+            if (eq > 0)
+                throw new UsageError(`--${name} takes no value`);
+            bools.add(name);
+            continue;
+        }
+        if (!VALUE_FLAGS.includes(name))
+            throw new UsageError(`unknown option --${name}`);
+        const value = eq > 0 ? a.slice(eq + 1) : argv[++i];
+        if (value === undefined || (eq < 0 && value.startsWith("--")))
+            throw new UsageError(`--${name} needs a value`);
+        flags[name] = value;
+    }
+    return { positionals, flags, bools };
+}
+export function parseYears(v) {
+    if (v === undefined)
+        return 1;
+    const n = Number(v);
+    if (!Number.isInteger(n) || n < 1 || n > 10)
+        throw new UsageError("--years must be a whole number from 1 to 10");
+    return n;
+}
+export function parseAddressFlag(v, flag) {
+    if (v === undefined)
+        return undefined;
+    if (!/^0x[0-9a-fA-F]{40}$/.test(v))
+        throw new UsageError(`--${flag} must be a 0x address (40 hex characters)${/^0x[0-9a-fA-F]{64}$/.test(v) ? "; that looks like a private key, never pass one on the command line" : ""}`);
+    return v;
+}
+export function parseHttpsFlag(v, flag) {
+    if (v === undefined)
+        return undefined;
+    let u;
+    try {
+        u = new URL(v);
+    }
+    catch {
+        throw new UsageError(`--${flag} is not a URL: ${v}`);
+    }
+    if (u.protocol !== "https:" && !(flag === "ws" && u.protocol === "wss:"))
+        throw new UsageError(`--${flag} must be an https:// URL`);
+    return v;
+}

package/dist/browser.d.ts

@@ -0,0 +1,18 @@
+import type { Network } from "./config.js";
+import type { Signer } from "./signer.js";
+export interface BrowserSignerOptions {
+    network: Network;
+    /** Opens the URL; default launches the system browser. Pass a no-op for --no-open or tests. */
+    open?: (url: string) => void;
+    /** Called once with the URL so the terminal can show it. */
+    onUrl?: (url: string) => void;
+    /** Per-request wait for the user, default 10 minutes. */
+    timeoutMs?: number;
+    port?: number;
+}
+export declare class WalletRejectedError extends Error {
+    readonly code?: number | undefined;
+    constructor(message: string, code?: number | undefined);
+}
+export declare function openInBrowser(url: string): void;
+export declare function browserSigner(opts: BrowserSignerOptions): Promise<Signer>;