feat: agent accessibility (natspec, discovery docs, @splits/pact cli + mcp + skill) - #67
Closed
r0ohafza wants to merge 6 commits into
Closed
feat: agent accessibility (natspec, discovery docs, @splits/pact cli + mcp + skill)#67r0ohafza wants to merge 6 commits into
r0ohafza wants to merge 6 commits into
Conversation
…n block Adds docs/integrate.md as the canonical direct-call guide and a prebuild step that renders /llms.txt, /.well-known/pact.json, and markdown mirrors under /docs/ from the generated contract pin, failing the build if a landing doc carries a different factory address. Per-page OG descriptions.
Adds the packages/pact workspace: one incur command table (26 commands across offering, buy, funds, fail, voucher, admin, config) served as an argv CLI, an MCP stdio server via --mcp, and generated skill files via skills add, with a hand-written knowledge skill included. Writes go through one guardrail path: factory-child check before any approve, eth_call preflight per transaction, unsigned transaction output by default and signed sends only with PACT_PRIVATE_KEY. Vouchers persist to a file ledger sharing the browser codec. The e2e spec drives the npm pack tarball against anvil in both signing modes plus an MCP stdio smoke.
Dedupe the offering arg schema, token parsing, and call encoder; derive server.json env docs from the env schema; add examples to every command; check the USDC balance behind the unsigned-mode buy preflight; refuse to start the MCP server on a chain mismatch; keep the MCP server dependency external to the bundle; guard the deploy block in docs/integrate.md; and exercise an unsigned refund relay in the e2e.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
One client-parameterised chain module, consumed by two adapters: the browser (wagmi) and the @splits/pact CLI (viem). Contract shape, event decoding, the scan policy (whole range first, 10k-block chunks on failure), the factory-child invariant, and the buy plan now exist once. - packages/core (private, zero-build, inlined into the CLI bundle): the moved pure modules and generated ABIs, plus chain/reads.ts (readOffering, quote, decoders, scan*, findFactoryChild, capTable) and chain/writes.ts (Call, encoders, approveCall, planBuy). Amounts stay bigint; records carry blockNumber/transactionHash/logIndex. - Browser: onchain.ts is the send adapter (sendCalls over EIP-5792 or sequential transactions, buys built from core's plan); offerings.ts is the cache adapter (bigint stored as decimal strings, corrupt or pre-core caches rescan). The eight lifecycle wrappers are gone; pages send offeringCall(record.offering, ...) and buys take an OfferingRecord. - CLI: reads.ts deleted, buys go through planBuy, assertFactoryChild returns the record, serializeOffering moves to format.ts. - Tests follow their modules; one shared fake ChainClient with encoded logs. Docs name the new paths; contracts.md mermaid batchRefund -> refundAll; contracts/README.md joins the pinned-address check.
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements the agent-accessibility spec (
.scratch/agent-accessibility/spec.md, signed off 2026-08-24): NatSpec on the contracts, agent-facing docs and discovery files, and the@splits/pactCLI / MCP server / skill package.Changed user flows
<meta name="description">/og:descriptiontext now differs per page (was one shared sentence)./llms.txt,/.well-known/pact.json,/docs/{architecture,contracts,integrate}.md, rendered atprebuildfromsrc/generated/offering-contracts.ts(build fails if a landing doc carries a different factory address or deploy block).packages/pact(npx @splits/pact): 26 commands acrossoffering,buy,funds,fail,voucher,admin,config; same table as MCP stdio tools via--mcpand as generated skill files viaskills add(plus the hand-writtenpactknowledge skill). Writes go through one guardrail path: factory-child check byOfferingCreatedscan before any USDC approve, per-txeth_callpreflight with decoded reverts, unsigned transaction output by default, signed sends only withPACT_PRIVATE_KEY,--dry-runon every write, non-zero exit whenever nothing was sent. Voucher issuance persists to~/.pact/ledger/<chainId>/<offering>.json(same row shape as the browser ledger; union-by-id,revokedAtwins).Test coverage changed
forge test(87) unchanged;forge build+build:contractsregenerate identically.src/lib/discovery.test.ts(manifest + llms.txt shape),src/lib/og.test.tsupdated for per-page descriptions;tests/og-metadata.spec.tsstill covers the rendered tags.packages/pact/src/cli.test.ts(12 scenarios over a fake chain: chain pin, factory-child refusal before approve, preflight abort, unsigned vs key mode,--dry-run,--max-cost, voucher round trip in both modes),ledger.test.ts(merge rule, file storage).tests/pact-cli.spec.tsexecutes the bin from thenpm packtarball against the shared anvil: config → create → quote → buy (key mode and unsigned relay) → voucher issue/complete → buy private → withdraw → cap-table; failure path (mark, key-mode and unsigned refund, sweep); guardrail negatives (foreign address leaves allowance at 0,PACT_CHAIN_IDmismatch, non-owner close fails preflight with nothing sent); MCP stdio smoke (tools/list= 26,offering_get).test:e2enow builds the package first;check:e2e-impactcoverspackages/pact/**; tsconfig/vitest/oxlint/prettier include the workspace.Validation
npm run typechecknpm testnpm run test:contractsnpm run test:e2eskills addinstalled 8 skills into a scratch dir;--mcpansweredinitialize/tools/listunder a hand-rolled stdio client)Full
npm run validateresult: passed (typecheck, oxlint, prettier, 98 unit tests, forge fmt + 87 forge tests, build:contracts, 15 Playwright tests).E2E impact override: none
Deviations from the spec text
0xE07b…/ 49935597) predate the current pin (0x68DA…/ 50274529); every surface derives from the pin per the spec's own hard-fact rule. The spec's "tools/list = 25" is 26 withconfig, which its §4.2 table lists.runWritepath plusassertFactoryChildrather than literal incur middleware (middleware cannot see command args).PACT_FACTORY_DEPLOY_BLOCK(needed whenever the factory is overridden, e.g. anvil). Env vars are documented underpact config --helpsince incur does not render a root env schema.@modelcontextprotocol/server(pinned alpha, same as incur's) is a declared runtime dependency kept external to the bundle; the e2e symlinks the repo'snode_modulesin place of a registry install.StdioClientTransport.Still manual after merge
npm publish -w packages/pact --access public, thesplits.orgDNS TXT formcp-publisher login dns,mcp-publisher publish, then the awesome-agent-skills PR (spec §6–§7). Until publish, thenpx @splits/pactpointers on the site and README resolve to nothing.