{"_id":"@0xdeve/agentjson","name":"@0xdeve/agentjson","dist-tags":{"latest":"3.2.0"},"versions":{"3.2.0":{"name":"@0xdeve/agentjson","version":"3.2.0","description":"Universal agent manifest compiler — generates agent.json for any web app so AI agents can discover and interact with it","main":"dist/index.js","bin":{"agentjson":"dist/cli.js","agent-json":"dist/cli.js","farcaster-agent-compiler":"dist/cli.js"},"scripts":{"build":"tsc && node -e \"const fs=require('fs');const f='dist/cli.js';const c=fs.readFileSync(f,'utf8');if(!c.startsWith('#!/'))fs.writeFileSync(f,'#!/usr/bin/env node\\n'+c);\"","start":"node dist/cli.js","test":"jest"},"repository":{"type":"git","url":"git+https://github.com/0xedev/farcaster-agent-compiler.git"},"keywords":["agent","ai","manifest","agent.json","compiler","farcaster","next.js","express","hono","fastify","openapi","llm"],"author":"","license":"ISC","type":"commonjs","devDependencies":{"@types/jest":"^30.0.0","@types/node":"^25.5.0","jest":"^30.3.0","ts-jest":"^29.4.6","ts-node":"^10.9.2","typescript":"^5.9.3","zod":"^4.3.6","zod-to-json-schema":"^3.25.1"},"directories":{"doc":"docs"},"dependencies":{"commander":"^14.0.3","tinyglobby":"^0.2.15","ts-morph":"^27.0.2"},"gitHead":"1eecb1d75c11899f877fd323903971504da65fc0","_id":"@0xdeve/agentjson@3.2.0","bugs":{"url":"https://github.com/0xedev/farcaster-agent-compiler/issues"},"homepage":"https://github.com/0xedev/farcaster-agent-compiler#readme","_nodeVersion":"24.11.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-QJwO/JDKo1x67DcDaCeq0GRnDMt4a82+xOIol9BWvFSEiOiMXHZ3Fv3QUWbB+eiiuNhHESiVmJmkQzMZv207mg==","shasum":"7734a2c9221c1de32bc8c19dff5584643aaabcdb","tarball":"https://registry.npmjs.org/@0xdeve/agentjson/-/agentjson-3.2.0.tgz","fileCount":16,"unpackedSize":108279,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDkc/Ag0YHz2votrkAhjJzvk2xsjulJxlvQhrdkPbmerAiEAmkGTl5N92+3zgn3plt5gegeTNMfy0KTbDHtc7t/+TRw="}]},"_npmUser":{"name":"0xdeve","email":"oxdeve@gmail.com"},"maintainers":[{"name":"0xdeve","email":"oxdeve@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agentjson_3.2.0_1774044516951_0.5979189219640462"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-20T22:08:36.873Z","3.2.0":"2026-03-20T22:08:37.097Z","modified":"2026-03-20T22:08:37.313Z"},"maintainers":[{"name":"0xdeve","email":"oxdeve@gmail.com"}],"description":"Universal agent manifest compiler — generates agent.json for any web app so AI agents can discover and interact with it","homepage":"https://github.com/0xedev/farcaster-agent-compiler#readme","keywords":["agent","ai","manifest","agent.json","compiler","farcaster","next.js","express","hono","fastify","openapi","llm"],"repository":{"type":"git","url":"git+https://github.com/0xedev/farcaster-agent-compiler.git"},"bugs":{"url":"https://github.com/0xedev/farcaster-agent-compiler/issues"},"license":"ISC","readme":"# agentjson\n\nA universal CLI compiler that scans any web app codebase and generates a `public/agent.json` manifest — so AI agents can discover and interact with your app without custom integration work.\n\nWorks with Next.js (App Router + Pages Router), Express, Hono, Fastify, and any TypeScript/JavaScript project with smart contracts.\n\n## Installation\n\n```bash\n# Run once, no install\nnpx @0xdeve/agentjson\n\n# Or install globally\nnpm install -g @0xdeve/agentjson\n```\n\n## Usage\n\n```bash\n# Scan current directory, output to public/agent.json\nagentjson\n\n# Specify project path and output\nagentjson -p ./my-app -o ./public/agent.json\n\n# With auth metadata\nagentjson --auth-type bearer --auth-header Authorization --auth-docs https://myapp.xyz/docs/auth\n\n# Add author / URL to manifest\nagentjson --author \"0xDev\" --url https://myapp.xyz\n\n# Validate an existing agent.json\nagentjson validate ./public/agent.json\n```\n\n## What gets generated\n\n```json\n{\n  \"name\": \"FlipIt\",\n  \"description\": \"On-chain coin flip game\",\n  \"version\": \"1.0.0\",\n  \"author\": \"0xDev\",\n  \"url\": \"https://flipit.xyz\",\n  \"auth\": { \"type\": \"farcaster-frame\" },\n  \"capabilities\": [\"wallet\", \"payments\"],\n  \"actions\": [\n    {\n      \"name\": \"flip\",\n      \"description\": \"Flip a coin and bet ETH\",\n      \"intent\": \"game.play\",\n      \"type\": \"contract\",\n      \"location\": \"./src/abis/FlipABI.json\",\n      \"abiFunction\": \"flip\",\n      \"chainId\": 8453,\n      \"contractAddress\": { \"$env\": \"NEXT_PUBLIC_FLIP_ADDRESS\" },\n      \"safety\": \"financial\",\n      \"agentSafe\": false,\n      \"requiredAuth\": { \"required\": \"farcaster-signed\" },\n      \"inputs\": {\n        \"choice\": { \"type\": \"string\", \"enum\": [\"heads\", \"tails\"], \"required\": true },\n        \"amount\":  { \"type\": \"number\", \"required\": true }\n      },\n      \"outputs\": { \"type\": \"void\" }\n    }\n  ],\n  \"metadata\": {}\n}\n```\n\n## Automatic detection\n\n### API routes\n- **Next.js App Router** — `app/api/**/route.ts` (GET, POST, PUT, DELETE, PATCH)\n- **Next.js Pages Router** — `pages/api/**/*.ts`\n- **Express / Hono / Fastify** — `app.get('/path', handler)` and `router.post(...)` patterns\n- **Server Actions** — `'use server'` files\n\n### Smart contracts\n- ABI JSON files (`*ABI.json`, `abi/*.json`, `abis/*.json`)\n- Wagmi hooks — `useWriteContract`, `useContractWrite`, `writeContract`\n- Contract addresses extracted as `{ \"$env\": \"VAR_NAME\" }` — secrets never embedded\n\n### Zod schemas\n- Inline `z.object(...)` schemas in the same file as `.parse()` / `.safeParse()`\n- **Cross-file** — schemas imported from centralised files (e.g. `src/lib/schemas.ts`) are resolved via the import graph\n\n### Auth\n- Detected from source code and `package.json` dependencies:\n  `bearer` · `api-key` · `oauth2` · `basic` · `farcaster-frame` · `cookie`\n- Override with `--auth-type` if detection misses\n\n### Capabilities\n`wallet` · `payments` · `ai` · `database` · `realtime` · `storage` · `farcaster`\n\n---\n\n## Safety levels\n\nEvery action is classified automatically:\n\n| Level | Meaning | `agentSafe` |\n|---|---|---|\n| `read` | Read-only, no side effects | `true` |\n| `write` | Mutates state, no money movement | `true` |\n| `financial` | Moves tokens or value | `false` |\n| `destructive` | Deletes or burns irreversibly | `false` |\n| `confidential` | Handles PII, passwords, credentials, KYC | `false` |\n\n`agentSafe: false` means the agent must ask for human confirmation before executing.\n\n---\n\n## Intent taxonomy\n\nActions get a `domain.verb` intent so agents understand what they do:\n\n| Domain | Examples |\n|---|---|\n| `game.*` | `game.play`, `game.join`, `game.score` |\n| `finance.*` | `finance.transfer`, `finance.swap`, `finance.stake`, `finance.approve` |\n| `nft.*` | `nft.mint`, `nft.burn`, `nft.list` |\n| `social.*` | `social.cast`, `social.follow`, `social.react`, `social.share` |\n| `governance.*` | `governance.vote`, `governance.propose`, `governance.delegate` |\n| `auth.*` | `auth.session`, `auth.register`, `auth.verify` |\n| `data.*` | `data.read`, `data.create`, `data.update`, `data.delete` |\n| `media.*` | `media.upload` |\n\nOverride with a JSDoc tag: `@agent-action intent=custom.thing`\n\n---\n\n## Explicit annotation (optional)\n\nThe compiler discovers actions automatically, but you can annotate for precision:\n\n```typescript\n/**\n * @agent-action intent=game.play\n * @description Flip a coin and bet ETH on the outcome.\n * @param choice The side to bet on — \"heads\" or \"tails\".\n * @param amount The amount of ETH to wager in wei.\n */\nexport async function flip(choice: string, amount: bigint) {\n  // ...\n}\n```\n\n---\n\n## Auth scopes\n\nPer-action auth is inferred automatically:\n\n| Condition | `requiredAuth` |\n|---|---|\n| Contract `view`/`pure` function | `public` |\n| GET endpoint on public app | `public` |\n| Farcaster frame app + write action | `farcaster-signed` |\n| Financial action | `required` + scope `payments:write` |\n| Confidential action (POST) | `required` + scope `pii:write` |\n| Confidential action (GET) | `required` + scope `pii:read` |\n| Everything else | `required` |\n\n---\n\n## CLI options\n\n```\nagentjson [options]\n\nOptions:\n  -p, --path <path>         Project root (default: \".\")\n  -o, --output <output>     Output path (default: \"./public/agent.json\")\n  --author <author>         Author name or organization\n  --url <url>               App homepage URL\n  --auth-type <type>        Override detected auth type\n                            none | bearer | api-key | oauth2 | basic | farcaster-frame | cookie\n  --auth-header <header>    Auth header name (default: Authorization)\n  --auth-docs <url>         URL where agents can obtain credentials\n  -V, --version             Show version\n  -h, --help                Show help\n\nCommands:\n  validate <file>           Validate an existing agent.json against the schema\n```\n\n---\n\n## JSON Schema\n\nA full JSON Schema is bundled at `node_modules/@0xdeve/agentjson/schema/agent.schema.json` for editor autocomplete and CI validation.\n\n---\n\n## Performance\n\nOn large repos the compiler skips unchanged files using SHA-1 content hashing. Cache is stored in `.agentjson-cache.json` at the project root (add to `.gitignore`).\n\n---\n\n## License\n\nISC\n","readmeFilename":"README.md","_rev":"1-b8383044814a0659e021d3b52bf0dcfe"}