8000 docs: drop AGENTS.md for CONTRIBUTING.md by oritwoen · Pull Request #290 · agntn/keys · GitHub
[go: up one dir, main page]

Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 0 additions & 126 deletions AGENTS.md

This file was deleted.

54 changes: 54 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# Contributing

## Setup

Run `pnpm install`, then `pnpm --dir docs install`. Yes, both: `test/docs-mcp.test.ts` loads Zod and the toolkit from `docs/node_modules`. `pnpm test` runs lint, the type checks, the build, the extension checks, the suite with coverage and the MCP eval.

The lint scripts build first, because the Pi and OMP extensions take their tool types from `dist/tools.d.mts`. So `build`, `lint`, `fmt`, `test`, `test:mcp` and packing all rewrite `dist/`. Serving `keys mcp` or an extension from your checkout? Run them in a separate worktree, or the live server gets a new bundle under its feet.

## Adding a chain

1. `src/blockchains/<name>.ts` exports a class extending `AbstractBlockchain` (or the family base in `src/utils/`), by name and as the default export. It implements `name`, `curve`, `bip44`, `getKeyPublic`, `getAddress`, `validateAddress`, `signMessage` and `verifyMessage`.
2. More than one address format means overriding `defaultAddressType`. One format still takes `type` and hands it to `refuseAddressType`, so a wallet never claims a type it didn't write.
3. Register it in `src/_blockchains.ts` with `lazy()`.
4. Add `test/blockchains/<name>.test.ts`, with vectors from outside this package.
5. The site lists chains by hand. That means a row in `CHAINS` in `docs/app/utils/chains.ts`, rows in `docs/app/utils/derive.ts` and a fixture in `docs/app/utils/landing.ts`. Then its icon in the `nuxt.config.ts` bundle and in `useSubNavigation.ts`, and `docs/content/2.blockchains/<name>.md` with `::chain-facts`. `test/docs-chains.test.ts` points at whatever you forgot.

## Crypto and code

- A primitive an `@agntn/*` package covers comes from it: every hash from `@agntn/hashes`, point math from `@agntn/curves`, encodings from `@agntn/encodings`. Signing, ed25519 and HD stay on @noble/@scure until a sibling takes them over. A missing primitive is an issue on the sibling, not a new @noble dependency, and an audit is no argument for one.
- Never Node `crypto`, not even for randomness. Keys come from the curve's `utils.randomSecretKey()`.
- secp256k1 chains sign through `evmSignMessage` or their own preamble, ed25519 chains through `ed25519SignMessage` on the raw message. Don't mix them.
- `src/` uses `Uint8Array.fromHex`, `.toHex()` and `concatBytes` from `src/utils/bytes.ts`. Tests and the playground use `hex` from `@agntn/encodings/hex`, because the type-aware lint types them without the `esnext` lib.
- No `as any`, `@ts-ignore` or `@ts-expect-error` in `src/`. Tests may use `@ts-expect-error` for input that's wrong on purpose.
- `src/index.ts` only re-exports. Public loading goes through `blockchains.chain(options)()`; a direct constructor is for subclassing and explicit imports.
- BIP39 stays strict by default through `@scure/bip39`. Localized word lists load only when asked for, and lookups normalize to NFKD first. Every numeric lookup says whether it counts from 0 or 1.

## Agent tools

- One `defineTool` per tool in `src/tools.ts`, with its executor in `src/tool-operations.ts`. `keys mcp`, the docs `/mcp`, Pi and OMP all serve that list, so a fix never lands on one surface only.
- Schemas in `src/tool-schemas.ts` take `Type` from `@agntn/tools`, never a bare `typebox` import, which OMP rewrites to its own facade. Every root is a plain object without `oneOf`, and a `pattern` stays portable across JSON Schema consumers. Unicode property escapes belong in the executor.
- Executors compose public library capabilities and keep their own checks for callers that skip the schema. A blank optional name reads as omitted, while passphrases keep blank and whitespace values.
- Secret input never lands in an error or in structured details.
- A tool maps to a real library capability. The names and parameters are still experimental, so nobody should build on them as a stable contract yet.

## Tests

- Tests import from `vite-plus/test` and share vectors through `test/fixtures.ts`.
- Real modules, no module mocks. The one exception is `test/docs-mcp.test.ts`, because the toolkit's server entry won't load outside Nitro.
- No wallet SDKs, not even for a manual check. Freeze what ethers, web3.js or a chain SDK produces as a vector in `fixtures.ts`, with the library and its version in the JSDoc.
- Public, disposable keys only. Nothing here should ever hold a real fund, and nothing's audited.
- The built bin runs its usage paths under `test/record-loads.mjs`: `--help`, `-h` and an unknown command must not load the server stack.
- Pi and OMP dev dependencies are pinned to exact versions.

## Docs site

`pnpm docs` serves it on port 3000.

- A page under `docs/app/pages/` calls `useSeo` and `defineOgImage` itself, gets appended in `server/routes/sitemap.xml.ts` and listed in `llms.sections` in `nuxt.config.ts`. Skip one and crawlers or agents never see it.
- A frontmatter `description` stays under 160 characters, with periods instead of commas, since the OG card drops commas. The landing's SEO description has no trailing period, or the OG image silently skips the prerender; `test/docs-og.test.ts` checks that one.
- Icons: `token` for chains by ticker, Lucide for the interface, `simple-icons` for GitHub and npm, `vscode-icons` for file types. A chain icon that only comes in colour doesn't justify a second set.
- `public/favicon.svg` is the source. The PNGs and the `.ico` are cut from it with ImageMagick, and both MCP servers show `favicon.svg` and `icon-512.png`.
- A new npm import that `src/index.ts` reaches goes into `docs/package.json` at the root's version, `libraryDependencies` and `libraryEntries` in `nuxt.config.ts`. Miss one and the deploy or the dev server breaks.
- Pure helpers go in `app/utils/` so the root suite can test them. Anything touching `ref` or `onMounted` goes in `app/composables/`.
- The explorer derives in the browser. `/mcp` is the only server route that takes key material, and that's not an invitation to add another.
87 changes: 5 additions & 82 deletions docs/AGENTS.md
8000 < 8000 td id="diff-d00743dc4e878f258330deadcd4008e361276d760b58b672150c54bb1ac9758aL46" data-line-number="46" class="blob-num blob-num-deletion js-linkable-line-number">
Original file line number Diff line number Diff line change
@@ -1,87 +1,10 @@
# docs/

Docus site for `@agntn/keys`. Markdown lives in `content/`. The browser explorer is a Vue component in the Nuxt app, not a `playground/` script. The one route of its own that answers at request time is `/mcp`, the Docus MCP server with every tool of `keys mcp` beside its own `list-pages` and `get-page`.
Cloudflare Workers Builds deploys this site to keys.agntn.dev. It installs `docs/` alone, so the root `node_modules` and `dist/` never exist there, and it takes Node.js from the root `.node-version`, never from `engines`.

The site uses the agntn instrument design system, the one `agntn/puzzles/docs` introduced. For panel geometry, typography, motion and the component that owns each part, read [DESIGN.md](DESIGN.md).
Resources on the Cloudflare account, bound by id in `wrangler.jsonc`:

## Layout
- D1 `agntn-keys` as `DB` for Nuxt Content
- No KV, R2 or secrets: the library runs from the bundle, in the browser and in the worker

```
docs/
├── nuxt.config.ts # extends: ['docus'], cloudflare_module preset, @agntn/keys aliased to ../src
├── app/app.config.ts # title, github, theme
├── app/app.css # tokens, the shared `console-*`, `hero-*` and `roster` grammar, `keys-*` classes, `.key-bytes`
├── app/components/ # Docus overrides: header (logo, areas, section tabs, mobile menu), sidebar, toc, page header links, surround cards, footer; KeysCallout and RosterSort
├── app/components/OgImage/ # Docs and Landing Takumi templates, theme colours as literals
├── app/assets/fonts.css # @font-face for the Figtree and Fira Code TTFs in public/fonts, shared by the site and the OG images
├── app/components/content/ # MDC components (`::landing-home`, `::chain-facts`, `::chain-list`), the landing instruments, KeyspaceExplorer, Console* and Prose* overrides
├── app/composables/ # useLandingKey (live key walk), useSubNavigation (sections, tabs, icons), useCopied, useRosterFlip
├── app/utils/ # chains (display list), parse-key (range, stepping), derive (rows per chain), format, tokens (`tok-*`), roster (UTable classes)
├── content/index.md # landing
├── content/1.guide/ # getting started
├── content/2.blockchains/ # one page per chain
├── public/ # favicon.svg and the files cut from it, site.webmanifest, fonts/
├── shiki-theme.ts # code block theme, every colour a `--shiki-token-*` variable from app.css
├── server/routes/sitemap.xml.ts # Docus sitemap plus the Vue pages
├── server/mcp/index.ts # the Docus MCP handler at /mcp: the page tools, then every key tool through `toToolkitTools`, introduced like `keys mcp` by `src/server-info.ts`
└── app/pages/keyspace.vue # explorer, own route outside the docs layout
```

`playground/` at the repo root stays Node/tsx demos.

## Commands

```bash
pnpm install # from docs/, nothing to build in the repo root first
pnpm dev # http://localhost:3000
pnpm build # Cloudflare Workers output in .output/, every route prerendered
pnpm deploy # build, then wrangler deploy to keys.agntn.dev
pnpm generate # static output only, no worker
```

Deployment: Workers Builds with root directory `docs`. It installs `docs/` and nothing else, which is enough because the library is bundled from `../src` (next paragraph). The build image takes Node.js from `.node-version` at the repo root and never reads `engines`, so without that file the site builds on the image's default Node.js instead of 26. Nitro preset `cloudflare_module`. Nuxt Content needs a D1 binding named `DB`; `wrangler.jsonc` carries the binding and the `NUXT_SITE_URL` var, Nitro merges it into the generated `.output/server/wrangler.json`. The database is `agntn-keys`, created once with `wrangler d1 create agntn-keys`; its id sits in `wrangler.jsonc`. Workers Builds installs with pnpm 11, whose `minimumReleaseAge` refuses a version younger than a day, so `pnpm-workspace.yaml` here and at the root lists `@agntn/*` under `minimumReleaseAgeExclude`. A name in its place covers only that package, and the deploy fails for a day after every other `@agntn` release.

`@agntn/keys` is an alias in `nuxt.config.ts` for `../src/index.ts`. Vite bundles the checkout's sources for the browser and Nitro gets the same alias for the prerender, so `dist/` and the root `node_modules` are never touched. The subgraph under `src/index.ts` imports from npm: `@agntn/curves`, `@agntn/encodings`, `@agntn/hashes`, `@noble/curves`, `@scure/bip32`, `@scure/bip39` and `micro-key-producer`. Each one is a dependency of `docs/package.json`, pinned to the root's version, and listed in `vite.resolve.dedupe` in `nuxt.config.ts`, because Vite resolves a bare import from the importer's directory upwards and `../src` never reaches `docs/node_modules`. The exact subpaths `src/` imports, dynamic imports included, sit in `vite.optimizeDeps.include`; without that list dev discovers them when a lazy chain module loads, optimizes again and reloads the page under the explorer. A new npm import under `src/` that `index.ts` can reach needs all three entries or the deploy or the dev server breaks. The CLI entry stays out of the alias, and `/mcp` imports `src/tools.ts` by path, see [MCP](#mcp).

Three resolution traps, all because the repo root is its own pnpm workspace:

- `pnpm-workspace.yaml` sets `shamefullyHoist: true`. Without it `docs/node_modules` holds only direct dependencies, Node walks up to the root `node_modules`, and the server bundle can end up with a second copy of Vue.
- `nuxt.config.ts` pins `workspaceDir` to `docs/` and disables devtools and telemetry, which would otherwise resolve from the root.
- `vite.server.fs.allow` in `nuxt.config.ts` adds `../src`. Vite serves only directories on that list, and with `workspaceDir` pinned to `docs/` the library sits outside it, so `pnpm dev` couldn't load it otherwise.

## MCP

`server/mcp/index.ts` imports `src/tools.ts` and `src/server-info.ts` by path and hands `keysTools` to `toToolkitTools` from `@agntn/tools/toolkit`. That's the list `keys mcp` serves, in its order, so a tool added to `src/tools.ts` shows up here without an edit. `tools` is a function that puts them after `getMcpTools({ event })`. An array would replace the toolkit's own pool and quietly take `list-pages` and `get-page` with it. `@nuxtjs/mcp-toolkit` wants Zod and validates with it before the handler runs. A Zod error quotes the client's keys as they came, bidi overrides and line separators included, and reads differently from `keys mcp` (#240). So the adapter hands it a `z.looseObject({})` whose `toJSONSchema` returns the tool's own schema: `tools/list` shows what `keys mcp` lists, Zod waves any object through, and `@agntn/tools` turns a bad one down the way stdio does, through `sanitizeLine`. Every answer, refusals included, is the text `keys mcp` gives. A call with no `arguments` at all reads as `{}`, the way stdio does. Progress would need `mcp: { sessions: { enabled: true } }`, and no key tool reports any, so the handler stays stateless.

On the `cloudflare_module` preset the toolkit hands its server to `createMcpHandler` from `agents`, which tells an SDK v1 server apart with `instanceof`. pnpm installs one copy of `@modelcontextprotocol/sdk` per `zod` peer it resolves, so the toolkit and `agents` can each get their own and every request fails with "createMcpHandler received an unsupported server". `nitro.alias` points every import of the SDK at the copy in `docs/node_modules`. Keep it until both resolve the same one. `@agntn/ciphers` and `@agntn/tools` are dependencies here for `src/tools.ts` and the adapter, pinned to the root's versions and deduped like the others; `@modelcontextprotocol/sdk` stays for the toolkit and `agents`. They run on the worker only, so they stay out of `optimizeDeps`. Types are another story. Checked from `server/`, `src/tools.ts` finds the root's copy of `@agntn/tools`, and the adapter won't take that `ToolDefinition` (agntn/tools#93). So `nitro.typescript.tsConfig` points both specifiers at the `.d.mts` files here, since an alias path loses its extension in the generated tsconfig and misses them. The library writes bigint literals, so `nitro.esbuild` targets es2022.

`/mcp` is the one place where key material reaches the server, because an agent sends it there on purpose. The worker must not log or keep it: no `evlog` module, no `observability` block in `wrangler.jsonc`, no `console` call with tool arguments. The page at `content/1.guide/1.index.md#remote-mcp` says so to users.

## Tests

`test/docs-parse-key.test.ts` and `test/docs-landing.test.ts` in the repo root cover `app/utils/`, and `test/docs-mcp.test.ts` loads the `/mcp` handler and holds every key tool it serves to `toolListings` and `callTool()` from `src/mcp.ts` through an SDK v1 server. All three run with the root suite. The first two need no docs install; `docs-mcp.test.ts` loads the handler with Zod and the toolkit from `docs/node_modules`, so every workflow that lints or tests installs `docs/` too. It swaps in the root's `@agntn/tools/toolkit` for the copy here, since the worker bundles one. The root `vite.config.ts` transforms them with the root tsconfig, because `docs/tsconfig.json` only references files Nuxt generates. `derive.ts` takes the library module as an argument and imports its types from `../src` by path, so a root test passes `src/index.ts` and never needs the `@agntn/keys` alias; `test/public-exports.test.ts` keeps that name for the built package. Keep pure helpers in `app/utils/` so they stay testable from the root; anything that touches `ref` or `onMounted` belongs in `app/composables/`.

The landing renders before the library loads, so `app/utils/landing.ts` records private key 1 on every row, the Bitcoin pipeline and the first HD sample as fixtures. `test/docs-landing.test.ts` derives the same values from `src/` and fails when they drift, so a fixture edit without a library change is a lie the test catches.

## SEO

- `seo.schema` in `app/app.config.ts` emits the landing JSON-LD: `WebSite`, the agntn `Organization` as publisher, and a free `SoftwareApplication` with `sameAs` on GitHub and npm. Docs pages get `Article` plus `BreadcrumbList` from Docus on their own.
- `app/pages/keyspace.vue` sits outside `content/`, so it calls `useSeo` and `defineOgImage("Docs", props, { alt })` itself, `server/routes/sitemap.xml.ts` appends it to the Docus sitemap and `llms.sections` in `nuxt.config.ts` lists it for `llms.txt`. A new page under `app/pages/` needs all three or crawlers and agents never see it.
- Docus links `/favicon.ico` without shipping one. `public/favicon.svg` is the source, the PNGs and the `.ico` are cut from it with ImageMagick (`magick -background none favicon.svg -resize 512x512 icon-512.png`, `-define icon:auto-resize=48,32,16 favicon.ico`), `app.head` in `nuxt.config.ts` links them with the manifest, theme colours, `og:locale` and `author`. Both MCP servers show `favicon.svg` and `icon-512.png` as their icons, so `test/mcp.test.ts` fails when either goes missing.
- Audit on `.output/public/*.html` with grep for `<meta`, `<link rel="canonical"` and `"@type"`, not by impression.

## OG images

- `app/components/OgImage/Docs.takumi.vue` and `Landing.takumi.vue` override the Docus templates of the same name and are rendered by Takumi at build time. Takumi has no CSS variables, so the theme colours from `app.css` are repeated there as literals.
- nuxt-og-image doesn't see the faces `@nuxt/fonts` generates, but it parses `@font-face` rules from the files in `css`. That's why `app/assets/fonts.css` declares the four TTFs in `public/fonts` (Figtree and Fira Code, 400 and 500) and `fonts.families` uses the `local` provider. Site and OG images share the files. Without them Takumi falls back to Inter, which is what `agntn/puzzles` ships today.
- Docus encodes title and description in the OG file name and a comma is a separator there, so the template gets descriptions without commas. Frontmatter descriptions use periods and `and` instead, and stay under 160 characters.
- The landing OG file is named from the SEO description and Nitro refuses a prerender path containing `..`, so a description ending in a period is silently skipped and the landing ships with a dead `og:image`. Keep the description in `content/index.md` without a trailing period and check `grep c_Landing` in the build log has no `(skipped)`.

## Constraints

- The explorer derives in the browser only. `/mcp` is the one server route that accepts private keys or mnemonics; do not add another.
- Do not log, persist, or send key material.
- secp256k1 keyspace is `1 .. n-1`. ed25519 rows reuse the same 32 bytes as a secret; label that.
- Keep Node demos in `playground/`.
- Icons: `token` (Web3 Icons, monochrome) for chains by ticker (`i-token-btc`), Lucide for the interface, `simple-icons` for GitHub and npm, `vscode-icons` for file types in code block headers. A chain icon that only exists in colour is not a reason to mix sets.
- Chains are listed by hand: rows and `loadExplorerChains` in `app/utils/derive.ts`, fixtures in `app/utils/landing.ts`, the display list in `app/utils/chains.ts` (name, curve, icon, blurb and the fixture row, read by the landing instruments, `ChainList` and `ChainFacts`), the secp256k1 list in `LandingToolCall.vue`, sidebar icons in `useSubNavigation.ts`, the icon bundle in `nuxt.config.ts`. A new chain in `src/_blockchains.ts` needs all of them plus a page under `content/2.blockchains/` with its `::chain-facts`.
`/mcp` is the one place where key material reaches the server, because an agent sends it there on purpose. The worker must not log or keep it: tool arguments stay out of every log line, observability included. `content/1.guide/1.index.md#remote-mcp` promises users exactly that.
Loading
Loading
0