agent-manifest 3.2.0

package/dist/parser/zod-extractor.js

@@ -0,0 +1,335 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZodExtractor = void 0;
+const ts_morph_1 = require("ts-morph");
+/**
+ * Extracts parameter schemas from Zod validators in a source file.
+ *
+ * Handles patterns like:
+ *   const Schema = z.object({ field: z.string().min(1).default('x'), ... })
+ *   Schema.safeParse(req.body) / Schema.parse(await request.json())
+ *
+ * Also resolves schemas imported from other files (e.g. src/lib/schemas.ts),
+ * so centralised schema files are picked up even when the route file only
+ * imports and uses the schema rather than defining it inline.
+ */
+class ZodExtractor {
+    extractSchemas(sourceFile) {
+        const schemas = new Map();
+        for (const varDecl of sourceFile.getVariableDeclarations()) {
+            const init = varDecl.getInitializer();
+            if (!init)
+                continue;
+            const shape = this.tryExtractObjectShape(init);
+            if (shape) {
+                schemas.set(varDecl.getName(), shape);
+            }
+        }
+        return schemas;
+    }
+    /**
+     * Walk .parse() / .safeParse() calls in the file. When the schema variable
+     * isn't defined locally, follow the import graph one level to find it in the
+     * source file that exported it.
+     */
+    findUsedSchema(sourceFile, schemas) {
+        // Build a name→sourceFile map for every named import so we can resolve
+        // cross-file schemas on demand.
+        const importedFrom = this.buildImportMap(sourceFile);
+        let found = null;
+        sourceFile.forEachDescendant(node => {
+            if (found)
+                return;
+            if (!ts_morph_1.Node.isCallExpression(node))
+                return;
+            const expr = node.getExpression();
+            if (!ts_morph_1.Node.isPropertyAccessExpression(expr))
+                return;
+            const method = expr.getName();
+            if (method !== 'safeParse' && method !== 'parse')
+                return;
+            const schemaName = expr.getExpression().getText().trim();
+            // 1. Local schema defined in the same file
+            if (schemas.has(schemaName)) {
+                found = schemas.get(schemaName);
+                return;
+            }
+            // 2. Schema imported from another file — resolve and extract
+            const importedFile = importedFrom.get(schemaName);
+            if (importedFile) {
+                const remoteSchemas = this.extractSchemas(importedFile);
+                if (remoteSchemas.has(schemaName)) {
+                    found = remoteSchemas.get(schemaName);
+                }
+            }
+        });
+        return found;
+    }
+    /**
+     * Build a map of { localName → SourceFile } for every named import in the
+     * file whose module specifier resolves within the project.
+     */
+    buildImportMap(sourceFile) {
+        const map = new Map();
+        for (const importDecl of sourceFile.getImportDeclarations()) {
+            const resolvedFile = importDecl.getModuleSpecifierSourceFile();
+            if (!resolvedFile)
+                continue;
+            for (const named of importDecl.getNamedImports()) {
+                // alias: `import { BodySchema as Body }` → local name is "Body"
+                map.set(named.getAliasNode()?.getText() ?? named.getName(), resolvedFile);
+            }
+            // Default import: `import Schemas from './schemas'` — less common for Zod
+            const defaultImport = importDecl.getDefaultImport();
+            if (defaultImport)
+                map.set(defaultImport.getText(), resolvedFile);
+        }
+        return map;
+    }
+    tryExtractObjectShape(node) {
+        const base = this.getZodBase(node);
+        if (!base || base.method !== 'object')
+            return null;
+        const args = base.node.getArguments();
+        if (!args.length)
+            return null;
+        const shapeArg = args[0];
+        if (!ts_morph_1.Node.isObjectLiteralExpression(shapeArg))
+            return null;
+        const shape = {};
+        for (const prop of shapeArg.getProperties()) {
+            if (!ts_morph_1.Node.isPropertyAssignment(prop))
+                continue;
+            const init = prop.getInitializer();
+            if (init) {
+                shape[prop.getName()] = this.extractFieldType(init);
+            }
+        }
+        return shape;
+    }
+    extractFieldType(node) {
+        const isOptional = this.chainContains(node, 'optional') || this.chainContains(node, 'nullish');
+        const base = this.getZodBase(node);
+        if (!base)
+            return { type: 'any', required: !isOptional };
+        const result = this.mapZodMethod(base.method, base.node);
+        result.required = !isOptional;
+        // Walk the full chain to collect constraints
+        const constraints = this.extractConstraints(node, base.method);
+        Object.assign(result, constraints);
+        return result;
+    }
+    /**
+     * Walk every method in the Zod chain to collect constraints:
+     * min, max, length, default, regex, email, url, uuid, datetime.
+     */
+    extractConstraints(node, baseType) {
+        const constraints = {};
+        const isNumeric = baseType === 'number' || baseType === 'bigint';
+        this.walkChain(node, (method, callNode) => {
+            const args = callNode.getArguments();
+            switch (method) {
+                case 'min': {
+                    const val = this.getNumericArg(args[0]);
+                    if (val !== undefined) {
+                        if (isNumeric)
+                            constraints.minimum = val;
+                        else
+                            constraints.minLength = val;
+                    }
+                    break;
+                }
+                case 'max': {
+                    const val = this.getNumericArg(args[0]);
+                    if (val !== undefined) {
+                        if (isNumeric)
+                            constraints.maximum = val;
+                        else
+                            constraints.maxLength = val;
+                    }
+                    break;
+                }
+                case 'gte': {
+                    const val = this.getNumericArg(args[0]);
+                    if (val !== undefined && isNumeric)
+                        constraints.minimum = val;
+                    break;
+                }
+                case 'lte': {
+                    const val = this.getNumericArg(args[0]);
+                    if (val !== undefined && isNumeric)
+                        constraints.maximum = val;
+                    break;
+                }
+                case 'gt': {
+                    const val = this.getNumericArg(args[0]);
+                    if (val !== undefined && isNumeric)
+                        constraints.minimum = val + Number.EPSILON;
+                    break;
+                }
+                case 'lt': {
+                    const val = this.getNumericArg(args[0]);
+                    if (val !== undefined && isNumeric)
+                        constraints.maximum = val - Number.EPSILON;
+                    break;
+                }
+                case 'length': {
+                    const val = this.getNumericArg(args[0]);
+                    if (val !== undefined) {
+                        constraints.minLength = val;
+                        constraints.maxLength = val;
+                    }
+                    break;
+                }
+                case 'default': {
+                    if (args[0]) {
+                        const val = this.getLiteralValue(args[0]);
+                        if (val !== undefined)
+                            constraints.default = val;
+                    }
+                    break;
+                }
+                case 'regex': {
+                    if (args[0] && ts_morph_1.Node.isRegularExpressionLiteral(args[0])) {
+                        const text = args[0].getText();
+                        const lastSlash = text.lastIndexOf('/');
+                        constraints.pattern = text.slice(1, lastSlash);
+                    }
+                    break;
+                }
+                case 'email':
+                    constraints.format = 'email';
+                    break;
+                case 'url':
+                    constraints.format = 'uri';
+                    break;
+                case 'uuid':
+                    constraints.format = 'uuid';
+                    break;
+                case 'datetime':
+                    constraints.format = 'date-time';
+                    break;
+                case 'ip':
+                    constraints.format = 'ip';
+                    break;
+                case 'cuid':
+                case 'cuid2':
+                case 'ulid':
+                    constraints.format = method;
+                    break;
+            }
+        });
+        return constraints;
+    }
+    mapZodMethod(method, node) {
+        switch (method) {
+            case 'string': return { type: 'string', required: true };
+            case 'number': return { type: 'number', required: true };
+            case 'boolean': return { type: 'boolean', required: true };
+            case 'bigint': return { type: 'number', required: true };
+            case 'date': return { type: 'string', format: 'date-time', required: true };
+            case 'array': return { type: 'array', required: true };
+            case 'object': return { type: 'object', required: true };
+            case 'any':
+            case 'unknown': return { type: 'any', required: true };
+            case 'enum': {
+                const args = node.getArguments();
+                if (args.length > 0 && ts_morph_1.Node.isArrayLiteralExpression(args[0])) {
+                    const values = args[0]
+                        .getElements()
+                        .filter(ts_morph_1.Node.isStringLiteral)
+                        .map(el => el.getLiteralValue());
+                    return { type: 'string', enum: values, required: true };
+                }
+                return { type: 'string', required: true };
+            }
+            case 'literal': {
+                const args = node.getArguments();
+                if (args.length > 0) {
+                    const val = args[0];
+                    if (ts_morph_1.Node.isStringLiteral(val))
+                        return { type: 'string', enum: [val.getLiteralValue()], required: true };
+                    if (ts_morph_1.Node.isNumericLiteral(val))
+                        return { type: 'number', required: true };
+                }
+                return { type: 'any', required: true };
+            }
+            case 'union': {
+                const args = node.getArguments();
+                if (args.length > 0 && ts_morph_1.Node.isArrayLiteralExpression(args[0])) {
+                    const types = args[0].getElements().map(el => this.extractFieldType(el).type);
+                    const unique = [...new Set(types)];
+                    return { type: unique.length === 1 ? unique[0] : 'string', required: true };
+                }
+                return { type: 'string', required: true };
+            }
+            default:
+                return { type: 'string', required: true };
+        }
+    }
+    /** Walk a Zod chain back to the root z.*() call. */
+    getZodBase(node) {
+        if (!ts_morph_1.Node.isCallExpression(node))
+            return null;
+        const expr = node.getExpression();
+        if (!ts_morph_1.Node.isPropertyAccessExpression(expr))
+            return null;
+        const method = expr.getName();
+        const obj = expr.getExpression();
+        if (obj.getText() === 'z')
+            return { method, node };
+        return this.getZodBase(obj);
+    }
+    /** Invoke callback for every method call in the chain (from outermost to innermost). */
+    walkChain(node, cb) {
+        if (!ts_morph_1.Node.isCallExpression(node))
+            return;
+        const expr = node.getExpression();
+        if (!ts_morph_1.Node.isPropertyAccessExpression(expr))
+            return;
+        cb(expr.getName(), node);
+        this.walkChain(expr.getExpression(), cb);
+    }
+    chainContains(node, target) {
+        if (!ts_morph_1.Node.isCallExpression(node))
+            return false;
+        const expr = node.getExpression();
+        if (!ts_morph_1.Node.isPropertyAccessExpression(expr))
+            return false;
+        if (expr.getName() === target)
+            return true;
+        return this.chainContains(expr.getExpression(), target);
+    }
+    getNumericArg(node) {
+        if (!node)
+            return undefined;
+        if (ts_morph_1.Node.isNumericLiteral(node))
+            return Number(node.getLiteralValue());
+        // Handle negative literals: -0.01 is PrefixUnaryExpression
+        if (ts_morph_1.Node.isPrefixUnaryExpression(node)) {
+            const operand = node.getOperand();
+            if (ts_morph_1.Node.isNumericLiteral(operand))
+                return -Number(operand.getLiteralValue());
+        }
+        return undefined;
+    }
+    getLiteralValue(node) {
+        // Never embed env var values — store the variable name as a sentinel instead
+        const text = node.getText().trim();
+        const envMatch = text.match(/process\.env\.([A-Z0-9_]+)/);
+        if (envMatch)
+            return { $env: envMatch[1] };
+        if (ts_morph_1.Node.isStringLiteral(node))
+            return node.getLiteralValue();
+        if (ts_morph_1.Node.isNumericLiteral(node))
+            return Number(node.getLiteralValue());
+        if (text === 'true')
+            return true;
+        if (text === 'false')
+            return false;
+        if (text === 'null')
+            return null;
+        return undefined;
+    }
+}
+exports.ZodExtractor = ZodExtractor;

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "agent-manifest",
+  "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"
+  },
+  "files": [
+    "dist",
+    "schema",
+    "README.md",
+    "LICENSE"
+  ],
+  "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"
+  }
+}

package/schema/agent.schema.json

@@ -0,0 +1,168 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://farcaster.xyz/schemas/agent.json",
+  "title": "Farcaster Agent Manifest",
+  "description": "Describes all agent-callable actions in a Farcaster Mini App",
+  "type": "object",
+  "required": ["name", "description", "version", "auth", "capabilities", "actions"],
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Mini app name"
+    },
+    "description": {
+      "type": "string",
+      "description": "Human-readable description of the mini app"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semantic version of the mini app"
+    },
+    "author": {
+      "type": "string",
+      "description": "Author or organization name"
+    },
+    "url": {
+      "type": "string",
+      "format": "uri",
+      "description": "Mini app homepage or Farcaster frame URL"
+    },
+    "auth": {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": false,
+      "description": "How agents should authenticate with this app",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["none", "bearer", "api-key", "oauth2", "basic", "farcaster-frame", "cookie"],
+          "description": "Authentication scheme"
+        },
+        "header":     { "type": "string", "description": "Header name, e.g. Authorization or X-API-Key" },
+        "scheme":     { "type": "string", "description": "Header value prefix, e.g. Bearer or Token" },
+        "queryParam": { "type": "string", "description": "Query param name for api-key auth" },
+        "docsUrl":    { "type": "string", "format": "uri", "description": "Where to obtain credentials" }
+      }
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "iconUrl":               { "type": "string", "format": "uri" },
+        "homeUrl":               { "type": "string", "format": "uri" },
+        "imageUrl":              { "type": "string", "format": "uri" },
+        "splashImageUrl":        { "type": "string", "format": "uri" },
+        "splashBackgroundColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }
+      }
+    },
+    "capabilities": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Farcaster SDK capabilities used by this app"
+    },
+    "actions": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/AgentAction" }
+    }
+  },
+  "definitions": {
+    "ParameterProperty": {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": false,
+      "properties": {
+        "type":        { "type": "string" },
+        "description": { "type": "string" },
+        "required":    { "type": "boolean" },
+        "enum":        { "type": "array", "items": { "type": "string" } },
+        "default":     {},
+        "minimum":     { "type": "number" },
+        "maximum":     { "type": "number" },
+        "minLength":   { "type": "integer", "minimum": 0 },
+        "maxLength":   { "type": "integer", "minimum": 0 },
+        "pattern":     { "type": "string" },
+        "format":      { "type": "string" }
+      }
+    },
+    "AgentAction": {
+      "type": "object",
+      "required": ["name", "description", "intent", "type", "location", "safety", "agentSafe", "inputs", "outputs"],
+      "additionalProperties": false,
+      "properties": {
+        "name":        { "type": "string", "description": "Unique action identifier" },
+        "description": { "type": "string" },
+        "intent": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9]*\\.[a-z][a-z0-9]*$",
+          "description": "Standardized semantic intent in domain.verb format"
+        },
+        "type": {
+          "type": "string",
+          "enum": ["api", "contract", "function"]
+        },
+        "location": { "type": "string" },
+        "method": {
+          "type": "string",
+          "enum": ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"]
+        },
+        "abiFunction": { "type": "string" },
+        "isReadOnly":  { "type": "boolean" },
+        "chainId":     { "type": "integer" },
+        "contractAddress": {
+          "oneOf": [
+            { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Literal deployed address" },
+            {
+              "type": "object",
+              "required": ["$env"],
+              "additionalProperties": false,
+              "properties": {
+                "$env": { "type": "string", "description": "Environment variable name that holds the address" }
+              },
+              "description": "Address resolved from an environment variable at runtime"
+            }
+          ]
+        },
+        "safety": {
+          "type": "string",
+          "enum": ["read", "write", "financial", "destructive", "confidential"],
+          "description": "Safety classification for agent policy enforcement. confidential = handles PII, credentials, or sensitive identity data requiring encrypted transport and human confirmation"
+        },
+        "agentSafe": {
+          "type": "boolean",
+          "description": "True when the action can be executed autonomously without human confirmation"
+        },
+        "requiredAuth": {
+          "type": "object",
+          "required": ["required"],
+          "additionalProperties": false,
+          "properties": {
+            "required": {
+              "type": "string",
+              "enum": ["public", "required", "farcaster-signed"],
+              "description": "Whether this action needs credentials"
+            },
+            "scope": {
+              "type": "string",
+              "description": "Optional OAuth/custom scope e.g. payments:write"
+            }
+          }
+        },
+        "inputs": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/definitions/ParameterProperty" }
+        },
+        "outputs": {
+          "type": "object",
+          "required": ["type"],
+          "additionalProperties": false,
+          "properties": {
+            "type":        { "type": "string" },
+            "description": { "type": "string" }
+          }
+        }
+      }
+    }
+  }
+}