@spectratools/assembly-cli 0.7.0 → 0.8.2

package/README.md

@@ -33,6 +33,29 @@ assembly-cli mcp add
 | `ABSTRACT_RPC_URL` | No | Abstract RPC URL override (default from package client) |
 | `ASSEMBLY_INDEXER_URL` | No | Optional member snapshot endpoint for `members list` (falls back to on-chain `Registered` events with a warning if unavailable) |
 
+## Shared tx integration pattern (`@spectratools/tx-shared`)
+
+`assembly-cli` write flows are powered by `@spectratools/tx-shared` (`executeTx` lifecycle + structured `TxError`s).
+
+If you're building a consumer CLI command (or extending Assembly write behavior), use the shared pattern:
+
+1. Parse signer flags/env via `toSignerOptions(...)`
+2. Resolve signer with `resolveSigner(...)`
+3. Build write request (`address`, `abi`, `functionName`, `args`/`value`)
+4. Execute with `executeTx(...)` and handle `dryRun` + `TxError.code`
+
+Reference wiring:
+
+- Assembly example: [`src/examples/tx-shared-register.ts`](./src/examples/tx-shared-register.ts)
+- tx-shared docs: [`../tx-shared/README.md`](../tx-shared/README.md)
+- tx-shared assembly-style example: [`../tx-shared/src/examples/assembly-write.ts`](../tx-shared/src/examples/assembly-write.ts)
+
+Current `assembly-cli` write commands require `PRIVATE_KEY`, but tx-shared supports broader provider setup for consumer CLIs:
+
+- private key (`PRIVATE_KEY`)
+- keystore (`--keystore` + `--password` or `KEYSTORE_PASSWORD`)
+- Privy (`PRIVY_APP_ID`, `PRIVY_WALLET_ID`, `PRIVY_AUTHORIZATION_KEY`; implementation tracked in [#117](https://github.com/spectra-the-bot/spectra-tools/issues/117))
+
 ## Command Group Intent Summary
 
 - `members` — Membership state, counts, and registry fee settings

package/dist/cli.js

@@ -4410,10 +4410,14 @@ 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";
+function deriveAuctionExecutionState(params) {
+  if (params.settled) return { executionStatus: "settled", bidExecutableNow: false };
+  const isCurrentAuctionSlot = params.day === Number(params.currentAuctionDay) && params.slot === Number(params.currentAuctionSlot);
+  if (params.currentTimestamp < params.windowEnd) {
+    if (isCurrentAuctionSlot) return { executionStatus: "open_now", bidExecutableNow: true };
+    return { executionStatus: "upcoming", bidExecutableNow: false };
+  }
+  return { executionStatus: "closed_unsettled", bidExecutableNow: false };
 }
 var council = Cli.create("council", {
   description: "Inspect council seats, members, auctions, and seat parameters."
@@ -4629,7 +4633,9 @@ council.command("auctions", {
         settled: z2.boolean(),
         windowEnd: timestampOutput,
         windowEndRelative: z2.string(),
-        status: z2.enum(["bidding", "closed", "settled"])
+        bidExecutableNow: z2.boolean(),
+        executionStatus: z2.enum(["open_now", "upcoming", "closed_unsettled", "settled"]),
+        status: z2.enum(["open_now", "upcoming", "closed_unsettled", "settled"])
       })
     )
   }),
@@ -4687,19 +4693,27 @@ council.command("auctions", {
         currentSlot: asNum(slot),
         auctions: recent.map((x, i) => {
           const windowEnd = windowEnds[i];
+          const dayValue = Number(x.day);
+          const execution = deriveAuctionExecutionState({
+            day: dayValue,
+            slot: x.slot,
+            currentAuctionDay: day,
+            currentAuctionSlot: slot,
+            settled: auctions[i].settled,
+            windowEnd,
+            currentTimestamp
+          });
           return {
-            day: Number(x.day),
+            day: dayValue,
             slot: x.slot,
             highestBidder: toChecksum(auctions[i].highestBidder),
             highestBid: eth(auctions[i].highestBid),
             settled: auctions[i].settled,
             windowEnd: timeValue(windowEnd, c.format),
             windowEndRelative: relTime(windowEnd),
-            status: deriveAuctionStatus({
-              settled: auctions[i].settled,
-              windowEnd,
-              currentTimestamp
-            })
+            bidExecutableNow: execution.bidExecutableNow,
+            executionStatus: execution.executionStatus,
+            status: execution.executionStatus
           };
         })
       },
@@ -4730,7 +4744,9 @@ council.command("auction", {
     settled: z2.boolean(),
     windowEnd: timestampOutput,
     windowEndRelative: z2.string(),
-    status: z2.enum(["bidding", "closed", "settled"])
+    bidExecutableNow: z2.boolean(),
+    executionStatus: z2.enum(["open_now", "upcoming", "closed_unsettled", "settled"]),
+    status: z2.enum(["open_now", "upcoming", "closed_unsettled", "settled"])
   }),
   examples: [{ args: { day: 0, slot: 0 }, description: "Inspect day 0, slot 0 auction" }],
   async run(c) {
@@ -4747,7 +4763,7 @@ council.command("auction", {
         retryable: false
       });
     }
-    const [auctionTuple, windowEnd, latestBlock] = await Promise.all([
+    const [auctionTuple, windowEnd, latestBlock, currentAuctionDay, currentAuctionSlot] = await Promise.all([
       client.readContract({
         abi: councilSeatsAbi,
         address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
@@ -4760,11 +4776,30 @@ council.command("auction", {
         functionName: "auctionWindowEnd",
         args: [BigInt(c.args.day), c.args.slot]
       }),
-      client.getBlock({ blockTag: "latest" })
+      client.getBlock({ blockTag: "latest" }),
+      client.readContract({
+        abi: councilSeatsAbi,
+        address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
+        functionName: "currentAuctionDay"
+      }),
+      client.readContract({
+        abi: councilSeatsAbi,
+        address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
+        functionName: "currentAuctionSlot"
+      })
     ]);
     const auction = decodeAuction(auctionTuple);
     const windowEndTimestamp = windowEnd;
     const currentTimestamp = latestBlock.timestamp;
+    const execution = deriveAuctionExecutionState({
+      day: c.args.day,
+      slot: c.args.slot,
+      currentAuctionDay,
+      currentAuctionSlot,
+      settled: auction.settled,
+      windowEnd: windowEndTimestamp,
+      currentTimestamp
+    });
     return c.ok({
       day: c.args.day,
       slot: c.args.slot,
@@ -4773,11 +4808,9 @@ council.command("auction", {
       settled: auction.settled,
       windowEnd: timeValue(windowEndTimestamp, c.format),
       windowEndRelative: relTime(windowEndTimestamp),
-      status: deriveAuctionStatus({
-        settled: auction.settled,
-        windowEnd: windowEndTimestamp,
-        currentTimestamp
-      })
+      bidExecutableNow: execution.bidExecutableNow,
+      executionStatus: execution.executionStatus,
+      status: execution.executionStatus
     });
   }
 });
@@ -4944,7 +4977,7 @@ council.command("bid", {
         retryable: false
       });
     }
-    const [auctionTuple, windowEnd, latestBlock] = await Promise.all([
+    const [auctionTuple, windowEnd, latestBlock, currentAuctionDay, currentAuctionSlot] = await Promise.all([
       client.readContract({
         abi: councilSeatsAbi,
         address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
@@ -4957,24 +4990,45 @@ council.command("bid", {
         functionName: "auctionWindowEnd",
         args: [BigInt(c.args.day), c.args.slot]
       }),
-      client.getBlock({ blockTag: "latest" })
+      client.getBlock({ blockTag: "latest" }),
+      client.readContract({
+        abi: councilSeatsAbi,
+        address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
+        functionName: "currentAuctionDay"
+      }),
+      client.readContract({
+        abi: councilSeatsAbi,
+        address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
+        functionName: "currentAuctionSlot"
+      })
     ]);
     const auction = decodeAuction(auctionTuple);
     const windowEndTimestamp = windowEnd;
     const currentTimestamp = latestBlock.timestamp;
-    const status = deriveAuctionStatus({
+    const execution = deriveAuctionExecutionState({
+      day: c.args.day,
+      slot: c.args.slot,
+      currentAuctionDay,
+      currentAuctionSlot,
       settled: auction.settled,
       windowEnd: windowEndTimestamp,
       currentTimestamp
     });
-    if (status === "settled") {
+    if (execution.executionStatus === "settled") {
       return c.error({
         code: "AUCTION_SETTLED",
         message: `Auction (day=${c.args.day}, slot=${c.args.slot}) is already settled. Winner: ${toChecksum(auction.highestBidder)}.`,
         retryable: false
       });
     }
-    if (status === "closed") {
+    if (execution.executionStatus === "upcoming") {
+      return c.error({
+        code: "AUCTION_NOT_ACTIVE",
+        message: `Auction (day=${c.args.day}, slot=${c.args.slot}) is not the currently active slot. Current bid-executable slot is day=${Number(currentAuctionDay)}, slot=${Number(currentAuctionSlot)}.`,
+        retryable: false
+      });
+    }
+    if (execution.executionStatus === "closed_unsettled") {
       return c.error({
         code: "AUCTION_CLOSED",
         message: `Auction (day=${c.args.day}, slot=${c.args.slot}) bidding window has ended. Use "council settle" instead.`,
@@ -5055,7 +5109,7 @@ council.command("settle", {
         retryable: false
       });
     }
-    const [auctionTuple, windowEnd, latestBlock] = await Promise.all([
+    const [auctionTuple, windowEnd, latestBlock, currentAuctionDay, currentAuctionSlot] = await Promise.all([
       client.readContract({
         abi: councilSeatsAbi,
         address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
@@ -5068,30 +5122,51 @@ council.command("settle", {
         functionName: "auctionWindowEnd",
         args: [BigInt(c.args.day), c.args.slot]
       }),
-      client.getBlock({ blockTag: "latest" })
+      client.getBlock({ blockTag: "latest" }),
+      client.readContract({
+        abi: councilSeatsAbi,
+        address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
+        functionName: "currentAuctionDay"
+      }),
+      client.readContract({
+        abi: councilSeatsAbi,
+        address: ABSTRACT_MAINNET_ADDRESSES.councilSeats,
+        functionName: "currentAuctionSlot"
+      })
     ]);
     const auction = decodeAuction(auctionTuple);
     const windowEndTimestamp = windowEnd;
     const currentTimestamp = latestBlock.timestamp;
-    const status = deriveAuctionStatus({
+    const execution = deriveAuctionExecutionState({
+      day: c.args.day,
+      slot: c.args.slot,
+      currentAuctionDay,
+      currentAuctionSlot,
       settled: auction.settled,
       windowEnd: windowEndTimestamp,
       currentTimestamp
     });
-    if (status === "settled") {
+    if (execution.executionStatus === "settled") {
       return c.error({
         code: "ALREADY_SETTLED",
         message: `Auction (day=${c.args.day}, slot=${c.args.slot}) is already settled.`,
         retryable: false
       });
     }
-    if (status === "bidding") {
+    if (execution.executionStatus === "open_now") {
       return c.error({
         code: "AUCTION_STILL_ACTIVE",
         message: `Auction (day=${c.args.day}, slot=${c.args.slot}) is still accepting bids. Window ends ${relTime(windowEndTimestamp)}.`,
         retryable: false
       });
     }
+    if (execution.executionStatus === "upcoming") {
+      return c.error({
+        code: "AUCTION_STILL_ACTIVE",
+        message: `Auction (day=${c.args.day}, slot=${c.args.slot}) is not yet the active slot. Current slot is day=${Number(currentAuctionDay)}, slot=${Number(currentAuctionSlot)}.`,
+        retryable: false
+      });
+    }
     const txResult = await assemblyWriteTx({
       env: c.env,
       options: c.options,
@@ -5872,12 +5947,21 @@ import { Cli as Cli4, z as z5 } 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 MAX_MEMBER_LOOKUP_SUGGESTIONS = 5;
 var env4 = z5.object({
   ABSTRACT_RPC_URL: z5.string().optional().describe("Abstract RPC URL override"),
   ASSEMBLY_INDEXER_URL: z5.string().optional().describe("Optional members snapshot endpoint (default: theaiassembly.org indexer)")
 });
 var timestampOutput4 = z5.union([z5.number(), z5.string()]);
-var memberSnapshotSchema = z5.array(z5.string());
+var memberSnapshotEntrySchema = z5.union([
+  z5.string(),
+  z5.object({
+    address: z5.string(),
+    ens: z5.string().optional(),
+    name: z5.string().optional()
+  })
+]);
+var memberSnapshotSchema = z5.array(memberSnapshotEntrySchema);
 var AssemblyApiValidationError = class extends Error {
   constructor(details) {
     super("Assembly API response validation failed");
@@ -5892,6 +5976,45 @@ var AssemblyIndexerUnavailableError = class extends Error {
     this.name = "AssemblyIndexerUnavailableError";
   }
 };
+function mergeMemberIdentities(entries) {
+  const byAddress = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const key = entry.address.toLowerCase();
+    const existing = byAddress.get(key);
+    if (!existing) {
+      byAddress.set(key, entry);
+      continue;
+    }
+    const merged = { address: existing.address };
+    const ens = existing.ens ?? entry.ens;
+    const name = existing.name ?? entry.name;
+    if (ens !== void 0) merged.ens = ens;
+    if (name !== void 0) merged.name = name;
+    byAddress.set(key, merged);
+  }
+  return [...byAddress.values()];
+}
+function memberSnapshotEntryToIdentity(entry) {
+  if (typeof entry === "string") return { address: entry };
+  const identity = { address: entry.address };
+  if (entry.ens !== void 0) identity.ens = entry.ens;
+  if (entry.name !== void 0) identity.name = entry.name;
+  return identity;
+}
+function matchableAddressInput(query) {
+  return query.startsWith("0x") && query.length === 42;
+}
+function searchMemberIdentities(query, members2) {
+  const needle = query.trim().toLowerCase();
+  if (needle.length === 0) return [];
+  const exactMatches = members2.filter((member) => {
+    return member.address.toLowerCase() === needle || member.ens?.toLowerCase() === needle || member.name?.toLowerCase() === needle;
+  });
+  if (exactMatches.length > 0) return exactMatches;
+  return members2.filter((member) => {
+    return member.address.toLowerCase().includes(needle) || member.ens?.toLowerCase().includes(needle) || member.name?.toLowerCase().includes(needle);
+  });
+}
 async function memberSnapshot(url) {
   let res;
   try {
@@ -5914,7 +6037,7 @@ async function memberSnapshot(url) {
   const json = await res.json();
   const parsed = memberSnapshotSchema.safeParse(json);
   if (parsed.success) {
-    return parsed.data;
+    return mergeMemberIdentities(parsed.data.map(memberSnapshotEntryToIdentity));
   }
   throw new AssemblyApiValidationError({
     code: "INVALID_ASSEMBLY_API_RESPONSE",
@@ -5958,7 +6081,28 @@ async function membersFromRegisteredEvents(client) {
       }
     }
   }
-  return [...addresses];
+  return [...addresses].map((address) => ({ address }));
+}
+async function loadMemberIdentities(client, snapshotUrl) {
+  try {
+    return { members: await memberSnapshot(snapshotUrl) };
+  } catch (error) {
+    if (error instanceof AssemblyApiValidationError) {
+      throw error;
+    }
+    if (!(error instanceof AssemblyIndexerUnavailableError)) {
+      throw error;
+    }
+    const fallbackMembers = await withTimeout(
+      membersFromRegisteredEvents(client),
+      REGISTERED_EVENT_SCAN_TIMEOUT_MS,
+      `Registered event fallback scan timed out after ${REGISTERED_EVENT_SCAN_TIMEOUT_MS}ms`
+    );
+    return {
+      members: mergeMemberIdentities(fallbackMembers),
+      fallbackReason: error.details
+    };
+  }
 }
 function indexerIssue(details) {
   if (typeof details.status === "number") {
@@ -5979,6 +6123,12 @@ function emitIndexerFallbackWarning(details) {
 `
   );
 }
+function describeMember(member) {
+  const parts = [toChecksum(member.address)];
+  if (member.ens) parts.push(`ens=${member.ens}`);
+  if (member.name) parts.push(`name=${member.name}`);
+  return parts.join(" ");
+}
 var members = Cli4.create("members", {
   description: "Inspect Assembly membership and registry fee state."
 });
@@ -6006,10 +6156,12 @@ members.command("list", {
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
     const snapshotUrl = c.env.ASSEMBLY_INDEXER_URL ?? DEFAULT_MEMBER_SNAPSHOT_URL;
-    let addresses;
+    let memberIdentities;
     let fallbackReason;
     try {
-      addresses = await memberSnapshot(snapshotUrl);
+      const loaded = await loadMemberIdentities(client, snapshotUrl);
+      memberIdentities = loaded.members;
+      fallbackReason = loaded.fallbackReason;
     } catch (error) {
       if (error instanceof AssemblyApiValidationError) {
         return c.error({
@@ -6018,27 +6170,19 @@ members.command("list", {
           retryable: false
         });
       }
-      if (!(error instanceof AssemblyIndexerUnavailableError)) {
+      if (!(error instanceof Error)) {
         throw error;
       }
-      fallbackReason = error.details;
-      try {
-        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",
-          message: `Member indexer unavailable (${indexerIssue(error.details)} at ${error.details.url}) and on-chain Registered event fallback failed: ${fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}`,
-          retryable: true
-        });
-      }
+      return c.error({
+        code: "MEMBER_LIST_SOURCE_UNAVAILABLE",
+        message: `Unable to load member list from indexer (${snapshotUrl}) or on-chain fallback: ${error.message}`,
+        retryable: true
+      });
     }
     if (fallbackReason) {
       emitIndexerFallbackWarning(fallbackReason);
     }
+    const addresses = memberIdentities.map((member) => member.address);
     const calls = addresses.flatMap((address) => [
       {
         abi: registryAbi,
@@ -6074,9 +6218,9 @@ members.command("list", {
   }
 });
 members.command("info", {
-  description: "Get registry record and active status for a member address.",
+  description: "Get member registry record and active status by full address, partial address, ENS, or name.",
   args: z5.object({
-    address: z5.string().describe("Member wallet address")
+    address: z5.string().describe("Member lookup query (full/partial address, ENS, or name metadata)")
   }),
   env: env4,
   output: z5.object({
@@ -6091,26 +6235,74 @@ members.command("info", {
     {
       args: { address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" },
       description: "Inspect one member address"
+    },
+    {
+      args: { address: "a96045" },
+      description: "Lookup a member by partial address"
     }
   ],
   async run(c) {
     const client = createAssemblyPublicClient(c.env.ABSTRACT_RPC_URL);
+    const snapshotUrl = c.env.ASSEMBLY_INDEXER_URL ?? DEFAULT_MEMBER_SNAPSHOT_URL;
+    let lookupAddress = c.args.address;
+    if (!matchableAddressInput(c.args.address)) {
+      let loadedMembers;
+      let fallbackReason;
+      try {
+        const loaded = await loadMemberIdentities(client, snapshotUrl);
+        loadedMembers = loaded.members;
+        fallbackReason = loaded.fallbackReason;
+      } catch (error) {
+        if (error instanceof AssemblyApiValidationError) {
+          return c.error({
+            code: error.details.code,
+            message: `Member snapshot response failed validation. url=${error.details.url}; issues=${JSON.stringify(error.details.issues)}; response=${JSON.stringify(error.details.response)}`,
+            retryable: false
+          });
+        }
+        return c.error({
+          code: "MEMBER_LOOKUP_SOURCE_UNAVAILABLE",
+          message: error instanceof Error ? `Unable to resolve member query from indexer (${snapshotUrl}) or on-chain fallback: ${error.message}` : `Unable to resolve member query from indexer (${snapshotUrl}) or on-chain fallback.`,
+          retryable: true
+        });
+      }
+      if (fallbackReason) {
+        emitIndexerFallbackWarning(fallbackReason);
+      }
+      const matches = searchMemberIdentities(c.args.address, loadedMembers);
+      if (matches.length === 0) {
+        return c.error({
+          code: "MEMBER_NOT_FOUND",
+          message: `No Assembly member matched "${c.args.address}". Try a longer query or run \`assembly members list\` first.`,
+          retryable: false
+        });
+      }
+      if (matches.length > 1) {
+        const suggestions = matches.slice(0, MAX_MEMBER_LOOKUP_SUGGESTIONS).map(describeMember).join("; ");
+        return c.error({
+          code: "AMBIGUOUS_MEMBER_QUERY",
+          message: `Member query "${c.args.address}" matched ${matches.length} members. Be more specific. Matches: ${suggestions}`,
+          retryable: false
+        });
+      }
+      lookupAddress = matches[0].address;
+    }
     const [member, active] = await Promise.all([
       client.readContract({
         abi: registryAbi,
         address: ABSTRACT_MAINNET_ADDRESSES.registry,
         functionName: "members",
-        args: [c.args.address]
+        args: [lookupAddress]
       }),
       client.readContract({
         abi: registryAbi,
         address: ABSTRACT_MAINNET_ADDRESSES.registry,
         functionName: "isActive",
-        args: [c.args.address]
+        args: [lookupAddress]
       })
     ]);
     return c.ok({
-      address: toChecksum(c.args.address),
+      address: toChecksum(lookupAddress),
       active,
       activeUntil: timeValue(member.activeUntil, c.format),
       lastHeartbeatAt: timeValue(member.lastHeartbeatAt, c.format),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spectratools/assembly-cli",
-  "version": "0.7.0",
+  "version": "0.8.2",
   "description": "CLI for Assembly governance on Abstract (members, council, forum, proposals, and treasury).",
   "type": "module",
   "license": "MIT",
@@ -32,8 +32,8 @@
     "incur": "^0.3.0",
     "ox": "^0.14.0",
     "viem": "^2.47.0",
-    "@spectratools/tx-shared": "0.3.0",
-    "@spectratools/cli-shared": "0.1.1"
+    "@spectratools/cli-shared": "0.1.1",
+    "@spectratools/tx-shared": "0.4.2"
   },
   "devDependencies": {
     "typescript": "5.7.3",