aavegotchi-cli 0.1.0

package/README.md

@@ -0,0 +1,120 @@
+# aavegotchi-cli
+
+Agent-first CLI for automating Aavegotchi app and onchain workflows on Base.
+
+## Install
+
+```bash
+npm install -g aavegotchi-cli
+```
+
+For local development:
+
+```bash
+npm install
+```
+
+## First command an agent should run
+
+```bash
+AGCLI_PRIVATE_KEY=0x... npm run ag -- bootstrap \
+  --mode agent \
+  --profile prod \
+  --chain base \
+  --signer env:AGCLI_PRIVATE_KEY \
+  --policy default \
+  --json
+```
+
+For read-only automation:
+
+```bash
+npm run ag -- bootstrap --mode agent --profile prod --chain base --signer readonly --json
+```
+
+## Command surface (current)
+
+- `bootstrap`
+- `profile list|show|use|export`
+- `signer check`
+- `signer keychain list|import|remove`
+- `policy list|show|upsert`
+- `rpc check`
+- `tx send|status|resume|watch`
+- `batch run --file plan.yaml`
+- `onchain call|send`
+- `<domain> read` (routes to generic onchain call for that domain)
+
+Planned domain namespaces are stubbed for parity tracking:
+
+- `gotchi`, `portal`, `wearables`, `items`, `inventory`, `baazaar`, `auction`, `lending`, `staking`, `gotchi-points`, `realm`, `alchemica`, `forge`, `token`
+
+Many Base-era write flows are already executable as mapped aliases in those namespaces (internally routed through `onchain send`).
+Example: `ag lending create --abi-file ./abis/GotchiLendingFacet.json --address 0x... --args-json '[...]' --json`
+
+## Signer backends
+
+- `readonly` (read-only mode)
+- `env:ENV_VAR` (private key from env var)
+- `keychain:ACCOUNT_ID` (encrypted local key store; requires `AGCLI_KEYCHAIN_PASSPHRASE`)
+- `remote:URL|ADDRESS|AUTH_ENV` (HTTP signer service)
+- `ledger:DERIVATION_PATH|ADDRESS|BRIDGE_ENV` (external bridge command signer)
+
+Remote signer contract:
+
+- `GET /address` -> `{ "address": "0x..." }` (optional if address configured)
+- `POST /sign-transaction` -> `{ "rawTransaction": "0x..." }` or `{ "txHash": "0x..." }`
+
+Ledger bridge contract:
+
+- Set `AGCLI_LEDGER_BRIDGE_CMD` (or custom env var in signer config) to a command that reads tx payload JSON from stdin and outputs JSON containing either `rawTransaction` or `txHash`.
+
+Keychain import example:
+
+```bash
+AGCLI_KEYCHAIN_PASSPHRASE=your-passphrase \
+AGCLI_PRIVATE_KEY=0x... \
+npm run ag -- signer keychain import --account-id bot --private-key-env AGCLI_PRIVATE_KEY --json
+```
+
+## Agent-mode behavior
+
+`--mode agent` implies:
+
+- `--json`
+- `--yes`
+
+All successful/error responses use a stable envelope:
+
+```json
+{
+  "schemaVersion": "1.0.0",
+  "command": "tx send",
+  "status": "ok",
+  "data": {},
+  "meta": { "timestamp": "...", "mode": "agent" }
+}
+```
+
+## Config and journal
+
+- Config default path: `~/.aavegotchi-cli/config.json`
+- Journal default path: `~/.aavegotchi-cli/journal.sqlite`
+- Override both via `AGCLI_HOME=/custom/path`
+
+## Parity artifacts
+
+- Method inventory: [`docs/parity/base-method-inventory.md`](docs/parity/base-method-inventory.md)
+- Command mapping: [`docs/parity/base-command-matrix.md`](docs/parity/base-command-matrix.md)
+
+Raffle/ticket flows are intentionally excluded for Base-era scope.
+
+## Development
+
+```bash
+npm run typecheck
+npm test
+npm run build
+npm run parity:check
+npm run ag -- help
+```

package/dist/args.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseArgv = parseArgv;
+exports.getFlagString = getFlagString;
+exports.getFlagBoolean = getFlagBoolean;
+exports.normalizeGlobals = normalizeGlobals;
+exports.normalizeMode = normalizeMode;
+const errors_1 = require("./errors");
+function parseArgv(argv) {
+    const positionals = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (!token.startsWith("-")) {
+            positionals.push(token);
+            continue;
+        }
+        if (token.startsWith("--")) {
+            const body = token.slice(2);
+            const eqIndex = body.indexOf("=");
+            if (eqIndex >= 0) {
+                const key = body.slice(0, eqIndex);
+                const value = body.slice(eqIndex + 1);
+                flags[key] = value;
+                continue;
+            }
+            const key = body;
+            const next = argv[i + 1];
+            if (next && !next.startsWith("-")) {
+                flags[key] = next;
+                i++;
+                continue;
+            }
+            flags[key] = true;
+            continue;
+        }
+        // Short flags can be grouped, e.g. -jy
+        const shorts = token.slice(1).split("");
+        for (const shortFlag of shorts) {
+            flags[shortFlag] = true;
+        }
+    }
+    return { positionals, flags };
+}
+function getFlagString(flags, ...keys) {
+    for (const key of keys) {
+        const value = flags[key];
+        if (typeof value === "string") {
+            return value;
+        }
+    }
+    return undefined;
+}
+function getFlagBoolean(flags, ...keys) {
+    for (const key of keys) {
+        const value = flags[key];
+        if (typeof value === "boolean") {
+            return value;
+        }
+        if (typeof value === "string") {
+            const normalized = value.toLowerCase();
+            if (normalized === "true") {
+                return true;
+            }
+            if (normalized === "false") {
+                return false;
+            }
+        }
+    }
+    return false;
+}
+function normalizeGlobals(args) {
+    const modeValue = getFlagString(args.flags, "mode");
+    const mode = normalizeMode(modeValue);
+    const explicitJson = getFlagBoolean(args.flags, "json", "j");
+    const explicitYes = getFlagBoolean(args.flags, "yes", "y");
+    // Agent mode defaults to machine-first behavior.
+    const json = explicitJson || mode === "agent";
+    const yes = explicitYes || mode === "agent";
+    const profile = getFlagString(args.flags, "profile");
+    return {
+        mode,
+        json,
+        yes,
+        profile,
+    };
+}
+function normalizeMode(value) {
+    if (!value) {
+        return "human";
+    }
+    const normalized = value.toLowerCase();
+    if (normalized === "human" || normalized === "agent") {
+        return normalized;
+    }
+    throw new errors_1.CliError("INVALID_MODE", `Unsupported mode '${value}'. Expected 'human' or 'agent'.`, 2);
+}

package/dist/chains.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveChain = resolveChain;
+exports.resolveRpcUrl = resolveRpcUrl;
+exports.toViemChain = toViemChain;
+const viem_1 = require("viem");
+const chains_1 = require("viem/chains");
+const errors_1 = require("./errors");
+const CHAIN_PRESETS = {
+    base: {
+        key: "base",
+        chainId: 8453,
+        defaultRpcUrl: "https://mainnet.base.org",
+        viemChain: chains_1.base,
+    },
+    "base-sepolia": {
+        key: "base-sepolia",
+        chainId: 84532,
+        defaultRpcUrl: "https://sepolia.base.org",
+        viemChain: chains_1.baseSepolia,
+    },
+};
+function resolveChain(value) {
+    if (!value) {
+        return CHAIN_PRESETS.base;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (CHAIN_PRESETS[normalized]) {
+        return CHAIN_PRESETS[normalized];
+    }
+    if (/^\d+$/.test(normalized)) {
+        return {
+            key: `chain-${normalized}`,
+            chainId: Number(normalized),
+            defaultRpcUrl: undefined,
+        };
+    }
+    throw new errors_1.CliError("INVALID_CHAIN", `Unsupported chain '${value}'. Use 'base', 'base-sepolia', or a numeric chain id.`, 2);
+}
+function resolveRpcUrl(chain, rpcFlag) {
+    if (rpcFlag) {
+        return rpcFlag;
+    }
+    if (chain.key === "base" && process.env.BASE_RPC_URL) {
+        return process.env.BASE_RPC_URL;
+    }
+    if (process.env.AGCLI_RPC_URL) {
+        return process.env.AGCLI_RPC_URL;
+    }
+    if (chain.defaultRpcUrl) {
+        return chain.defaultRpcUrl;
+    }
+    throw new errors_1.CliError("MISSING_RPC_URL", "RPC URL is required for custom chain IDs.", 2);
+}
+function toViemChain(chain, rpcUrl) {
+    const preset = CHAIN_PRESETS[chain.key];
+    if (preset) {
+        return preset.viemChain;
+    }
+    return (0, viem_1.defineChain)({
+        id: chain.chainId,
+        name: chain.key,
+        nativeCurrency: {
+            name: "Ether",
+            symbol: "ETH",
+            decimals: 18,
+        },
+        rpcUrls: {
+            default: {
+                http: [rpcUrl],
+            },
+        },
+    });
+}

package/dist/command-runner.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeCommandPath = normalizeCommandPath;
+exports.executeCommand = executeCommand;
+const errors_1 = require("./errors");
+const batch_1 = require("./commands/batch");
+const bootstrap_1 = require("./commands/bootstrap");
+const mapped_1 = require("./commands/mapped");
+const onchain_1 = require("./commands/onchain");
+const policy_1 = require("./commands/policy");
+const profile_1 = require("./commands/profile");
+const rpc_1 = require("./commands/rpc");
+const signer_1 = require("./commands/signer");
+const stubs_1 = require("./commands/stubs");
+const tx_1 = require("./commands/tx");
+function normalizeCommandPath(positionals) {
+    if (positionals.length === 0 || positionals[0] === "help") {
+        return ["help"];
+    }
+    return positionals;
+}
+async function executeCommand(ctx) {
+    const [root, sub] = ctx.commandPath;
+    if (root === "help") {
+        return {
+            commandName: "help",
+            data: { help: true },
+        };
+    }
+    if (root === "bootstrap") {
+        return {
+            commandName: "bootstrap",
+            data: await (0, bootstrap_1.runBootstrapCommand)(ctx),
+        };
+    }
+    if (root === "profile") {
+        if (!sub || sub === "show") {
+            return {
+                commandName: "profile show",
+                data: await (0, profile_1.runProfileShowCommand)(ctx),
+            };
+        }
+        if (sub === "list") {
+            return {
+                commandName: "profile list",
+                data: await (0, profile_1.runProfileListCommand)(),
+            };
+        }
+        if (sub === "use") {
+            return {
+                commandName: "profile use",
+                data: await (0, profile_1.runProfileUseCommand)(ctx),
+            };
+        }
+        if (sub === "export") {
+            return {
+                commandName: "profile export",
+                data: await (0, profile_1.runProfileExportCommand)(ctx),
+            };
+        }
+    }
+    if (root === "policy") {
+        if (!sub || sub === "list") {
+            return {
+                commandName: "policy list",
+                data: await (0, policy_1.runPolicyListCommand)(),
+            };
+        }
+        if (sub === "show") {
+            return {
+                commandName: "policy show",
+                data: await (0, policy_1.runPolicyShowCommand)(ctx),
+            };
+        }
+        if (sub === "upsert" || sub === "set") {
+            return {
+                commandName: "policy upsert",
+                data: await (0, policy_1.runPolicyUpsertCommand)(ctx),
+            };
+        }
+    }
+    if (root === "rpc") {
+        if (!sub || sub === "check") {
+            return {
+                commandName: "rpc check",
+                data: await (0, rpc_1.runRpcCheckCommand)(ctx),
+            };
+        }
+    }
+    if (root === "signer") {
+        if (!sub || sub === "check") {
+            return {
+                commandName: "signer check",
+                data: await (0, signer_1.runSignerCheckCommand)(ctx),
+            };
+        }
+        if (sub === "keychain") {
+            const action = ctx.commandPath[2];
+            if (!action || action === "list") {
+                return {
+                    commandName: "signer keychain list",
+                    data: await (0, signer_1.runSignerKeychainListCommand)(),
+                };
+            }
+            if (action === "import") {
+                return {
+                    commandName: "signer keychain import",
+                    data: await (0, signer_1.runSignerKeychainImportCommand)(ctx),
+                };
+            }
+            if (action === "remove") {
+                return {
+                    commandName: "signer keychain remove",
+                    data: await (0, signer_1.runSignerKeychainRemoveCommand)(ctx),
+                };
+            }
+        }
+    }
+    if (root === "tx") {
+        if (!sub || sub === "status") {
+            return {
+                commandName: "tx status",
+                data: await (0, tx_1.runTxStatusCommand)(ctx),
+            };
+        }
+        if (sub === "send") {
+            return {
+                commandName: "tx send",
+                data: await (0, tx_1.runTxSendCommand)(ctx),
+            };
+        }
+        if (sub === "resume") {
+            return {
+                commandName: "tx resume",
+                data: await (0, tx_1.runTxResumeCommand)(ctx),
+            };
+        }
+        if (sub === "watch") {
+            return {
+                commandName: "tx watch",
+                data: await (0, tx_1.runTxWatchCommand)(ctx),
+            };
+        }
+    }
+    if (root === "onchain") {
+        if (!sub || sub === "call") {
+            return {
+                commandName: "onchain call",
+                data: await (0, onchain_1.runOnchainCallCommand)(ctx),
+            };
+        }
+        if (sub === "send") {
+            return {
+                commandName: "onchain send",
+                data: await (0, onchain_1.runOnchainSendCommand)(ctx),
+            };
+        }
+    }
+    if (root === "batch" && (!sub || sub === "run")) {
+        return {
+            commandName: "batch run",
+            data: await (0, batch_1.runBatchRunCommand)(ctx, executeCommand),
+        };
+    }
+    if ((0, mapped_1.findMappedFunction)(ctx.commandPath)) {
+        return {
+            commandName: ctx.commandPath.join(" "),
+            data: await (0, mapped_1.runMappedDomainCommand)(ctx),
+        };
+    }
+    if ((0, stubs_1.isDomainStubRoot)(root) && sub === "read") {
+        return {
+            commandName: ctx.commandPath.join(" "),
+            data: await (0, onchain_1.runOnchainCallCommand)(ctx),
+        };
+    }
+    if ((0, stubs_1.isDomainStubRoot)(root)) {
+        return {
+            commandName: ctx.commandPath.join(" "),
+            data: await (0, stubs_1.runDomainStubCommand)(ctx),
+        };
+    }
+    throw new errors_1.CliError("UNKNOWN_COMMAND", `Unknown command '${ctx.commandPath.join(" ")}'.`, 2);
+}

package/dist/commands/batch.js

@@ -0,0 +1,189 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runBatchRunCommand = runBatchRunCommand;
+const fs = __importStar(require("fs"));
+const yaml_1 = __importDefault(require("yaml"));
+const args_1 = require("../args");
+const errors_1 = require("../errors");
+const schemas_1 = require("../schemas");
+function parseBatchFile(filePath) {
+    if (!fs.existsSync(filePath)) {
+        throw new errors_1.CliError("BATCH_FILE_NOT_FOUND", `Batch file not found: ${filePath}`, 2);
+    }
+    const source = fs.readFileSync(filePath, "utf8");
+    const raw = yaml_1.default.parse(source);
+    const parsed = schemas_1.batchPlanSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new errors_1.CliError("INVALID_BATCH_PLAN", "Batch plan validation failed.", 2, {
+            issues: parsed.error.issues,
+        });
+    }
+    return parsed.data;
+}
+function createStepArgs(stepCommand, args) {
+    const positionals = stepCommand.split(" ").map((entry) => entry.trim()).filter(Boolean);
+    const flags = {};
+    for (const [key, value] of Object.entries(args || {})) {
+        flags[key] = typeof value === "number" ? String(value) : value;
+    }
+    return {
+        positionals,
+        flags,
+    };
+}
+function mergeGlobals(parent, plan) {
+    return {
+        ...parent,
+        mode: plan.mode || parent.mode,
+        profile: plan.profile || parent.profile,
+        json: true,
+        yes: true,
+    };
+}
+function dependenciesDone(stepDependsOn, completed) {
+    if (!stepDependsOn || stepDependsOn.length === 0) {
+        return true;
+    }
+    return stepDependsOn.every((dep) => completed.has(dep));
+}
+async function runBatchRunCommand(ctx, executor) {
+    const filePath = (0, args_1.getFlagString)(ctx.args.flags, "file") || (0, args_1.getFlagString)(ctx.args.flags, "f");
+    if (!filePath) {
+        throw new errors_1.CliError("MISSING_ARGUMENT", "batch run requires --file <plan.yaml>", 2);
+    }
+    const plan = parseBatchFile(filePath);
+    const globals = mergeGlobals(ctx.globals, plan);
+    const completed = new Set();
+    const failed = new Set();
+    const results = [];
+    const pending = [...plan.steps];
+    while (pending.length > 0) {
+        let progressed = false;
+        for (let index = 0; index < pending.length; index++) {
+            const step = pending[index];
+            if (!dependenciesDone(step.dependsOn, completed)) {
+                continue;
+            }
+            progressed = true;
+            pending.splice(index, 1);
+            index--;
+            const startedAt = new Date().toISOString();
+            if (step.dependsOn && step.dependsOn.some((dep) => failed.has(dep))) {
+                results.push({
+                    id: step.id,
+                    command: step.command,
+                    status: "skipped",
+                    startedAt,
+                    finishedAt: new Date().toISOString(),
+                    error: {
+                        code: "DEPENDENCY_FAILED",
+                        message: "One or more dependency steps failed.",
+                    },
+                });
+                continue;
+            }
+            const stepArgs = createStepArgs(step.command, step.args);
+            try {
+                const childCtx = {
+                    commandPath: stepArgs.positionals,
+                    args: {
+                        positionals: stepArgs.positionals,
+                        flags: {
+                            ...stepArgs.flags,
+                            ...(globals.profile ? { profile: globals.profile } : {}),
+                        },
+                    },
+                    globals,
+                };
+                const executed = await executor(childCtx);
+                completed.add(step.id);
+                results.push({
+                    id: step.id,
+                    command: step.command,
+                    status: "ok",
+                    startedAt,
+                    finishedAt: new Date().toISOString(),
+                    data: {
+                        commandName: executed.commandName,
+                        data: executed.data,
+                    },
+                });
+            }
+            catch (error) {
+                failed.add(step.id);
+                const normalized = error instanceof errors_1.CliError ? error : new errors_1.CliError("STEP_FAILED", String(error));
+                results.push({
+                    id: step.id,
+                    command: step.command,
+                    status: "error",
+                    startedAt,
+                    finishedAt: new Date().toISOString(),
+                    error: {
+                        code: normalized.code,
+                        message: normalized.message,
+                    },
+                });
+                const shouldContinue = step.continueOnError ?? plan.continueOnError ?? false;
+                if (!shouldContinue) {
+                    return {
+                        filePath,
+                        aborted: true,
+                        results,
+                    };
+                }
+            }
+        }
+        if (!progressed) {
+            throw new errors_1.CliError("BATCH_DEPENDENCY_CYCLE", "Batch plan has unmet/cyclic dependencies.", 2, {
+                pending: pending.map((step) => ({
+                    id: step.id,
+                    dependsOn: step.dependsOn || [],
+                })),
+                completed: [...completed],
+                failed: [...failed],
+            });
+        }
+    }
+    return {
+        filePath,
+        completed: [...completed],
+        failed: [...failed],
+        results,
+    };
+}