@spectratools/assembly-cli 0.2.0 → 0.3.1

package/README.md

@@ -1,6 +1,11 @@
 # @spectratools/assembly-cli
 
-Assembly governance CLI for Abstract.
+Assembly is the governance layer for protocols on the Abstract chain: it manages membership, council seats, proposals, forum participation, and treasury controls through onchain contracts. Abstract is an Ethereum L2 focused on consumer-facing apps and agent-friendly infrastructure. This CLI gives operators and agents one interface to query Assembly state, run checks, and power automation.
+
+Learn more:
+
+- Abstract site: https://abs.xyz
+- Abstract docs: https://docs.abs.xyz
 
 ## Install
 
@@ -47,27 +52,30 @@ assembly-cli <group> <command> [args] [options]
 
 ```bash
 # 1) Agent startup snapshot: report system health in one call
-assembly-cli status --format json
+assembly-cli status --json
 
 # 2) Verify whether an address can currently participate as council
 assembly-cli council is-member 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --format json
 
 # 3) Pull active member roster with relative activity timings
-assembly-cli members list --format json
+# Note: best results require ASSEMBLY_INDEXER_URL; if the indexer returns 404/unavailable,
+# the CLI falls back to onchain Registered events and output may be slower or partial.
+assembly-cli members list --json
 
 # 4) Pre-vote automation: list proposals and fetch one in detail
 assembly-cli governance proposals --format json
-assembly-cli governance proposal 1 --format json
+assembly-cli governance proposal 1 --json
 
 # 5) Treasury monitoring loop: balance + spend lock status
 assembly-cli treasury balance --format json
-assembly-cli treasury major-spend-status --format json
+assembly-cli treasury major-spend-status --json
 ```
 
 ## Output Mode
 
-All commands support structured JSON output for agents:
+All commands support structured JSON output for agents with either `--json` or `--format json`:
 
 ```bash
+assembly-cli forum threads --json
 assembly-cli forum threads --format json
-```
+```

package/dist/cli.js

@@ -4281,6 +4281,10 @@ var ABSTRACT_MAINNET_ADDRESSES = {
   governance: "0xe82a25937e07a3855d8B8352b85fF4B4Aa3fb0C0",
   treasury: "0xC2e6DDbdc1A8e4DcCc60A78B6Faa197967a8FEb9"
 };
+var ABSTRACT_MAINNET_DEPLOYMENT_BLOCKS = {
+  // https://abscan.org/tx/0xe1dd27a739944c9847a7f366ea2363e7bf0fc2067377020fd749a8301e09b1ec
+  registry: 43782651n
+};
 
 // src/contracts/client.ts
 import { http, createPublicClient, defineChain } from "viem";
@@ -4317,6 +4321,11 @@ function decodeAuction(value) {
   const [highestBidder, highestBid, settled] = value;
   return { highestBidder, highestBid, settled };
 }
+function deriveAuctionStatus(params) {
+  if (params.settled) return "settled";
+  if (params.currentTimestamp < params.windowEnd) return "bidding";
+  return "closed";
+}
 var council = Cli.create("council", {
   description: "Inspect council seats, members, auctions, and seat parameters."
 });
@@ -4516,7 +4525,10 @@ council.command("auctions", {
         slot: z.number(),
         highestBidder: z.string(),
         highestBid: z.string(),
-        settled: z.boolean()
+        settled: z.boolean(),
+        windowEnd: z.number(),
+        windowEndRelative: z.string(),
+        status: z.enum(["bidding", "closed", "settled"])
       })
     )
   }),
@@ -4545,27 +4557,50 @@ council.command("auctions", {
       if (d < 0) continue;
       for (let s = 0; s < Number(slotsPerDay); s++) recent.push({ day: BigInt(d), slot: s });
     }
-    const auctionTuples = recent.length ? await client.multicall({
-      allowFailure: false,
-      contracts: recent.map((x) => ({
-        abi: councilSeatsAbi,
-        address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
-        functionName: "auctions",
-        args: [x.day, x.slot]
-      }))
-    }) : [];
+    const [auctionTuples, windowEnds, latestBlock] = await Promise.all([
+      recent.length ? client.multicall({
+        allowFailure: false,
+        contracts: recent.map((x) => ({
+          abi: councilSeatsAbi,
+          address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
+          functionName: "auctions",
+          args: [x.day, x.slot]
+        }))
+      }) : Promise.resolve([]),
+      recent.length ? client.multicall({
+        allowFailure: false,
+        contracts: recent.map((x) => ({
+          abi: councilSeatsAbi,
+          address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
+          functionName: "auctionWindowEnd",
+          args: [x.day, x.slot]
+        }))
+      }) : Promise.resolve([]),
+      client.getBlock({ blockTag: "latest" })
+    ]);
     const auctions = auctionTuples.map(decodeAuction);
+    const currentTimestamp = latestBlock.timestamp;
     return c.ok(
       {
         currentDay: asNum(day),
         currentSlot: asNum(slot),
-        auctions: recent.map((x, i) => ({
-          day: Number(x.day),
-          slot: x.slot,
-          highestBidder: toChecksum(auctions[i].highestBidder),
-          highestBid: eth(auctions[i].highestBid),
-          settled: auctions[i].settled
-        }))
+        auctions: recent.map((x, i) => {
+          const windowEnd = windowEnds[i];
+          return {
+            day: Number(x.day),
+            slot: x.slot,
+            highestBidder: toChecksum(auctions[i].highestBidder),
+            highestBid: eth(auctions[i].highestBid),
+            settled: auctions[i].settled,
+            windowEnd: asNum(windowEnd),
+            windowEndRelative: relTime(windowEnd),
+            status: deriveAuctionStatus({
+              settled: auctions[i].settled,
+              windowEnd,
+              currentTimestamp
+            })
+          };
+        })
       },
       {
         cta: {
@@ -4591,24 +4626,45 @@ council.command("auction", {
     slot: z.number(),
     highestBidder: z.string(),
     highestBid: z.string(),
-    settled: z.boolean()
+    settled: z.boolean(),
+    windowEnd: z.number(),
+    windowEndRelative: z.string(),
+    status: z.enum(["bidding", "closed", "settled"])
   }),
   examples: [{ args: { day: 0, slot: 0 }, description: "Inspect day 0, slot 0 auction" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
-    const auctionTuple = await client.readContract({
-      abi: councilSeatsAbi,
-      address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
-      functionName: "auctions",
-      args: [BigInt(c.args.day), c.args.slot]
-    });
+    const [auctionTuple, windowEnd, latestBlock] = await Promise.all([
+      client.readContract({
+        abi: councilSeatsAbi,
+        address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
+        functionName: "auctions",
+        args: [BigInt(c.args.day), c.args.slot]
+      }),
+      client.readContract({
+        abi: councilSeatsAbi,
+        address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
+        functionName: "auctionWindowEnd",
+        args: [BigInt(c.args.day), c.args.slot]
+      }),
+      client.getBlock({ blockTag: "latest" })
+    ]);
     const auction = decodeAuction(auctionTuple);
+    const windowEndTimestamp = windowEnd;
+    const currentTimestamp = latestBlock.timestamp;
     return c.ok({
       day: c.args.day,
       slot: c.args.slot,
       highestBidder: toChecksum(auction.highestBidder),
       highestBid: eth(auction.highestBid),
-      settled: auction.settled
+      settled: auction.settled,
+      windowEnd: asNum(windowEndTimestamp),
+      windowEndRelative: relTime(windowEndTimestamp),
+      status: deriveAuctionStatus({
+        settled: auction.settled,
+        windowEnd: windowEndTimestamp,
+        currentTimestamp
+      })
     });
   }
 });
@@ -4767,17 +4823,20 @@ var forum = Cli2.create("forum", {
 forum.command("threads", {
   description: "List forum threads with author and creation metadata.",
   env: env2,
-  output: z2.array(
-    z2.object({
-      id: z2.number(),
-      kind: z2.number(),
-      author: z2.string(),
-      createdAt: z2.number(),
-      createdAtRelative: z2.string(),
-      category: z2.string().nullable().optional(),
-      title: z2.string().nullable().optional()
-    })
-  ),
+  output: z2.object({
+    threads: z2.array(
+      z2.object({
+        id: z2.number(),
+        kind: z2.number(),
+        author: z2.string(),
+        createdAt: z2.number(),
+        createdAtRelative: z2.string(),
+        category: z2.string().nullable().optional(),
+        title: z2.string().nullable().optional()
+      })
+    ),
+    count: z2.number()
+  }),
   examples: [{ description: "List all forum threads" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
@@ -4797,16 +4856,20 @@ forum.command("threads", {
       }))
     }) : [];
     const items = threadTuples.map(decodeThread);
+    const threads = items.map((x) => ({
+      id: x.id,
+      kind: x.kind,
+      author: x.author,
+      createdAt: x.createdAt,
+      createdAtRelative: relTime(x.createdAt),
+      category: x.category ?? null,
+      title: x.title ?? null
+    }));
     return c.ok(
-      items.map((x) => ({
-        id: x.id,
-        kind: x.kind,
-        author: x.author,
-        createdAt: x.createdAt,
-        createdAtRelative: relTime(x.createdAt),
-        category: x.category ?? null,
-        title: x.title ?? null
-      })),
+      {
+        threads,
+        count: threads.length
+      },
       {
         cta: {
           description: "Inspect or comment:",
@@ -5131,16 +5194,19 @@ var governance = Cli3.create("governance", {
 governance.command("proposals", {
   description: "List governance proposals with status and vote end time.",
   env: env3,
-  output: z3.array(
-    z3.object({
-      id: z3.number(),
-      kind: z3.number(),
-      status: z3.number(),
-      title: z3.string().nullable().optional(),
-      voteEndAt: z3.number(),
-      voteEndRelative: z3.string()
-    })
-  ),
+  output: z3.object({
+    proposals: z3.array(
+      z3.object({
+        id: z3.number(),
+        kind: z3.number(),
+        status: z3.number(),
+        title: z3.string().nullable().optional(),
+        voteEndAt: z3.number(),
+        voteEndRelative: z3.string()
+      })
+    ),
+    count: z3.number()
+  }),
   examples: [{ description: "List all proposals" }],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
@@ -5160,15 +5226,19 @@ governance.command("proposals", {
       }))
     }) : [];
     const proposals = proposalTuples.map(decodeProposal);
+    const items = proposals.map((p, i) => ({
+      id: i + 1,
+      kind: asNum(p.kind),
+      status: asNum(p.status),
+      title: p.title ?? null,
+      voteEndAt: asNum(p.voteEndAt),
+      voteEndRelative: relTime(p.voteEndAt)
+    }));
     return c.ok(
-      proposals.map((p, i) => ({
-        id: i + 1,
-        kind: asNum(p.kind),
-        status: asNum(p.status),
-        title: p.title ?? null,
-        voteEndAt: asNum(p.voteEndAt),
-        voteEndRelative: relTime(p.voteEndAt)
-      })),
+      {
+        proposals: items,
+        count: items.length
+      },
       {
         cta: {
           description: "Inspect or vote:",
@@ -5301,6 +5371,7 @@ governance.command("params", {
 import { Cli as Cli4, z as z4 } from "incur";
 var DEFAULT_MEMBER_SNAPSHOT_URL = "https://www.theaiassembly.org/api/indexer/members";
 var REGISTERED_EVENT_SCAN_STEP = 100000n;
+var REGISTERED_EVENT_SCAN_TIMEOUT_MS = 2e4;
 var env4 = z4.object({
   ABSTRACT_RPC_URL: z4.string().optional().describe("Abstract RPC URL override"),
   ASSEMBLY_INDEXER_URL: z4.string().optional().describe("Optional members snapshot endpoint (default: theaiassembly.org indexer)")
@@ -5351,10 +5422,25 @@ async function memberSnapshot(url) {
     response: json
   });
 }
+async function withTimeout(promise, timeoutMs, timeoutMessage) {
+  let timer;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        timer = setTimeout(() => {
+          reject(new Error(timeoutMessage));
+        }, timeoutMs);
+      })
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
 async function membersFromRegisteredEvents(client) {
   const latestBlock = await client.getBlockNumber();
   const addresses = /* @__PURE__ */ new Set();
-  for (let fromBlock = 0n; fromBlock <= latestBlock; fromBlock += REGISTERED_EVENT_SCAN_STEP) {
+  for (let fromBlock = ABSTRACT_MAINNET_DEPLOYMENT_BLOCKS.registry; fromBlock <= latestBlock; fromBlock += REGISTERED_EVENT_SCAN_STEP) {
     const toBlock = fromBlock + REGISTERED_EVENT_SCAN_STEP - 1n > latestBlock ? latestBlock : fromBlock + REGISTERED_EVENT_SCAN_STEP - 1n;
     const events = await client.getContractEvents({
       abi: registryAbi,
@@ -5433,7 +5519,11 @@ members.command("list", {
       }
       fallbackReason = error.details;
       try {
-        addresses = await membersFromRegisteredEvents(client);
+        addresses = await withTimeout(
+          membersFromRegisteredEvents(client),
+          REGISTERED_EVENT_SCAN_TIMEOUT_MS,
+          `Registered event fallback scan timed out after ${REGISTERED_EVENT_SCAN_TIMEOUT_MS}ms`
+        );
       } catch (fallbackError) {
         return c.error({
           code: "MEMBER_LIST_SOURCE_UNAVAILABLE",
@@ -5708,6 +5798,133 @@ treasury.command("executed", {
   }
 });
 
+// src/error-handling.ts
+import { AsyncLocalStorage } from "async_hooks";
+import { Errors } from "incur";
+var VIEM_VERSION_PATTERN = /\n*Version:\s*viem@[^\n]+/i;
+var VIEM_VERSION_PATTERN_GLOBAL = /\n*Version:\s*viem@[^\n]+/gi;
+var debugFlagStore = new AsyncLocalStorage();
+var VIEM_ERROR_NAMES = /* @__PURE__ */ new Set([
+  "CallExecutionError",
+  "ContractFunctionExecutionError",
+  "ContractFunctionRevertedError",
+  "HttpRequestError",
+  "InvalidAddressError",
+  "TransactionExecutionError"
+]);
+function parseDebugFlag(argv) {
+  const cleaned = [];
+  let debug = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === "--debug") {
+      debug = true;
+      continue;
+    }
+    if (token === "--debug=true" || token === "--debug=1") {
+      debug = true;
+      continue;
+    }
+    if (token === "--debug=false" || token === "--debug=0") {
+      debug = false;
+      continue;
+    }
+    cleaned.push(token);
+  }
+  return { argv: cleaned, debug };
+}
+function isViemLikeError(error) {
+  if (!(error instanceof Error)) return false;
+  const shortMessage = error.shortMessage;
+  return VIEM_ERROR_NAMES.has(error.name) || VIEM_VERSION_PATTERN.test(error.message) || typeof shortMessage === "string" && error.message.includes("Docs: https://viem.sh");
+}
+function sanitizeViemMessage(message) {
+  return message.replace(VIEM_VERSION_PATTERN_GLOBAL, "").trim();
+}
+function toFriendlyViemError(error) {
+  const shortMessage = typeof error.shortMessage === "string" && error.shortMessage.trim().length > 0 ? error.shortMessage.trim() : void 0;
+  if (error.name === "InvalidAddressError" || shortMessage?.startsWith('Address "')) {
+    return {
+      code: "INVALID_ADDRESS",
+      message: `${shortMessage ?? "Invalid address."} Use a valid 0x-prefixed 20-byte address. Run with --debug for full error details.`
+    };
+  }
+  if (shortMessage?.toLowerCase().includes("http request failed") || error.message.toLowerCase().includes("http request failed")) {
+    return {
+      code: "RPC_CONNECTION_FAILED",
+      message: "RPC connection failed. Check ABSTRACT_RPC_URL and try again. Run with --debug for full error details."
+    };
+  }
+  if (shortMessage || VIEM_VERSION_PATTERN.test(error.message)) {
+    return {
+      code: "UPSTREAM_ERROR",
+      message: `${sanitizeViemMessage(shortMessage ?? error.message)} Run with --debug for full error details.`
+    };
+  }
+  return void 0;
+}
+function isMissingRequiredArgValidation(error) {
+  return error.fieldErrors.some((fieldError) => {
+    const msg = fieldError.message.toLowerCase();
+    return msg.includes("received undefined") || fieldError.received === "";
+  });
+}
+function missingArgPaths(error) {
+  const paths = /* @__PURE__ */ new Set();
+  for (const fieldError of error.fieldErrors) {
+    const msg = fieldError.message.toLowerCase();
+    if (msg.includes("received undefined") || fieldError.received === "") {
+      paths.add(fieldError.path);
+    }
+  }
+  return [...paths];
+}
+function toFriendlyValidationError(ctx, error) {
+  const missing = missingArgPaths(error);
+  if (missing.length === 0) return void 0;
+  const helpCommand = `${ctx.name} ${ctx.command} --help`;
+  const argsList = missing.join(", ");
+  return {
+    code: "VALIDATION_ERROR",
+    cta: {
+      description: "See command usage:",
+      commands: [{ command: helpCommand }]
+    },
+    message: missing.length === 1 ? `Missing required argument: ${argsList}. Run \`${helpCommand}\` for usage.` : `Missing required arguments: ${argsList}. Run \`${helpCommand}\` for usage.`
+  };
+}
+function handleError(ctx, error) {
+  if (debugFlagStore.getStore()) throw error;
+  if (error instanceof Errors.ValidationError && isMissingRequiredArgValidation(error)) {
+    const friendly = toFriendlyValidationError(ctx, error);
+    if (friendly) {
+      return ctx.error(friendly);
+    }
+  }
+  if (isViemLikeError(error)) {
+    const friendly = toFriendlyViemError(error);
+    if (friendly) {
+      return ctx.error(friendly);
+    }
+  }
+  throw error;
+}
+function applyFriendlyErrorHandling(cli2) {
+  const originalServe = cli2.serve.bind(cli2);
+  cli2.serve = (async (argv, options) => {
+    const rawArgv = argv ?? process.argv.slice(2);
+    const parsed = parseDebugFlag(rawArgv);
+    return debugFlagStore.run(parsed.debug, () => originalServe(parsed.argv, options));
+  });
+  cli2.use(async (context, next) => {
+    try {
+      await next();
+    } catch (error) {
+      return handleError(context, error);
+    }
+  });
+}
+
 // src/cli.ts
 var cli = Cli6.create("assembly", {
   description: "Assembly governance CLI for Abstract chain."
@@ -5843,6 +6060,7 @@ cli.command("health", {
     });
   }
 });
+applyFriendlyErrorHandling(cli);
 var isMain = process.argv[1] === fileURLToPath(import.meta.url);
 if (isMain) {
   cli.serve();

package/package.json

@@ -1,10 +1,27 @@
 {
   "name": "@spectratools/assembly-cli",
-  "version": "0.2.0",
-  "description": "Assembly CLI for spectra-the-bot",
+  "version": "0.3.1",
+  "description": "CLI for Assembly governance on Abstract (members, council, forum, proposals, and treasury).",
   "type": "module",
   "license": "MIT",
   "author": "spectra-the-bot",
+  "keywords": [
+    "assembly",
+    "abstract",
+    "governance",
+    "dao",
+    "ethereum",
+    "web3",
+    "cli",
+    "incur",
+    "spectratools"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/spectra-the-bot/spectra-tools.git",
+    "directory": "packages/assembly"
+  },
+  "homepage": "https://github.com/spectra-the-bot/spectra-tools/tree/main/packages/assembly#readme",
   "engines": {
     "node": ">=20"
   },