agent-manifest 3.2.0

package/dist/parser/express-parser.js

@@ -0,0 +1,163 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExpressParser = void 0;
+exports.looksLikeRouteFile = looksLikeRouteFile;
+const ts_morph_1 = require("ts-morph");
+const intent_classifier_1 = require("./intent-classifier");
+const path = __importStar(require("path"));
+/**
+ * Parses Express, Hono, and Fastify route definitions.
+ *
+ * Detects patterns like:
+ *   // Express / Express Router
+ *   app.get('/api/users', handler)
+ *   router.post('/api/payments', handler)
+ *
+ *   // Hono
+ *   app.get('/api/users', (c) => { ... })
+ *   const app = new Hono()
+ *
+ *   // Fastify
+ *   fastify.get('/api/users', handler)
+ *   app.register(fastifyPlugin)
+ */
+const HTTP_METHODS = ['get', 'post', 'put', 'delete', 'patch', 'head', 'options', 'all'];
+const HTTP_METHODS_UPPER = {
+    get: 'GET', post: 'POST', put: 'PUT', delete: 'DELETE',
+    patch: 'PATCH', head: 'HEAD', options: 'OPTIONS', all: 'POST',
+};
+class ExpressParser {
+    project;
+    /** Pass the shared Project from TSParser to avoid duplicate AST construction. */
+    constructor(sharedProject) {
+        this.project = sharedProject ?? new ts_morph_1.Project({
+            compilerOptions: { allowJs: true, checkJs: false },
+        });
+    }
+    async parseFile(filePath, projectPath) {
+        const sourceFile = this.project.addSourceFileAtPath(filePath);
+        const relativePath = path.relative(projectPath, filePath).replace(/\\/g, '/');
+        const actions = [];
+        // Walk all call expressions looking for app.METHOD / router.METHOD / fastify.METHOD
+        sourceFile.forEachDescendant(node => {
+            if (!ts_morph_1.Node.isCallExpression(node))
+                return;
+            const expr = node.getExpression();
+            if (!ts_morph_1.Node.isPropertyAccessExpression(expr))
+                return;
+            const methodName = expr.getName().toLowerCase();
+            if (!HTTP_METHODS.includes(methodName))
+                return;
+            const args = node.getArguments();
+            if (args.length < 2)
+                return;
+            // First arg must be a string literal route path
+            const routeArg = args[0];
+            if (!ts_morph_1.Node.isStringLiteral(routeArg))
+                return;
+            const routePath = routeArg.getLiteralValue();
+            if (!routePath.startsWith('/'))
+                return;
+            const httpMethod = HTTP_METHODS_UPPER[methodName];
+            const actionName = this.routeToActionName(routePath, httpMethod);
+            if (actions.some(a => a.name === actionName))
+                return;
+            // Extract JSDoc from the handler if it's an inline function
+            let description = `${httpMethod} ${routePath}`;
+            const handler = args[args.length - 1];
+            if (ts_morph_1.Node.isArrowFunction(handler) || ts_morph_1.Node.isFunctionExpression(handler)) {
+                const jsDocs = handler.getJsDocs?.() ?? [];
+                if (jsDocs.length > 0) {
+                    description = jsDocs[0].getDescription().trim() || description;
+                }
+            }
+            const safety = (0, intent_classifier_1.classifySafety)({ name: actionName, httpMethod, type: 'api' });
+            actions.push({
+                name: actionName,
+                description,
+                intent: (0, intent_classifier_1.inferIntent)(actionName),
+                type: 'api',
+                location: routePath,
+                method: httpMethod,
+                safety,
+                agentSafe: (0, intent_classifier_1.deriveAgentSafe)(safety),
+                requiredAuth: (0, intent_classifier_1.inferActionAuth)({ safety, httpMethod, type: 'api' }),
+                inputs: this.extractRouteParams(routePath),
+                outputs: { type: 'any' },
+            });
+        });
+        return actions;
+    }
+    /** Convert a route path like /api/users/:id to a snake_case action name */
+    routeToActionName(routePath, method) {
+        const slug = routePath
+            .replace(/^\//, '')
+            .replace(/\/:([^/]+)/g, '_$1') // :param → _param
+            .replace(/\//g, '_')
+            .replace(/[^a-zA-Z0-9_]/g, '');
+        return slug ? `${slug}_${method}` : `root_${method}`;
+    }
+    /** Extract path params like :id, :userId as required string inputs */
+    extractRouteParams(routePath) {
+        const params = {};
+        const matches = routePath.matchAll(/:([a-zA-Z][a-zA-Z0-9_]*)/g);
+        for (const match of matches) {
+            params[match[1]] = {
+                type: 'string',
+                description: `Path parameter: ${match[1]}`,
+                required: true,
+            };
+        }
+        return params;
+    }
+}
+exports.ExpressParser = ExpressParser;
+/**
+ * Quick check: does this file look like it registers Express/Hono/Fastify routes?
+ * Used by DiscoveryService to filter files before expensive AST parsing.
+ */
+function looksLikeRouteFile(content) {
+    return (
+    // Express / Hono app method calls
+    /\.(get|post|put|delete|patch)\s*\(\s*['"`]\//.test(content) ||
+        // Fastify route registration
+        /fastify\.(get|post|put|delete|patch)\s*\(/.test(content) ||
+        // Hono new Hono()
+        /new\s+Hono\s*\(/.test(content) ||
+        // Express Router
+        /Router\s*\(\s*\)/.test(content) ||
+        /express\.Router/.test(content));
+}

package/dist/parser/intent-classifier.js

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inferIntent = inferIntent;
+exports.classifySafety = classifySafety;
+exports.deriveAgentSafe = deriveAgentSafe;
+exports.inferActionAuth = inferActionAuth;
+const INTENT_RULES = [
+    // Trailing \b is intentionally omitted — camelCase names like rollDice, sendTokens,
+    // getUsers don't have a word boundary after the verb segment. Leading \b is kept
+    // to avoid matching mid-word (e.g. "undo" matching "do").
+    // Game
+    { pattern: /\b(play|flip|roll|spin|bet|guess|draw|move|attack|defend|claim(?:Prize|Reward|Win))/i, intent: 'game.play' },
+    { pattern: /\b(score|leaderboard|rank|highscore)/i, intent: 'game.score' },
+    { pattern: /\b(join(?:Game|Room|Lobby)|create(?:Game|Room)|start(?:Game|Round))/i, intent: 'game.join' },
+    // Finance / DeFi
+    { pattern: /\b(transfer|send(?:Token|ETH|USDC)?|pay(?:ment)?)/i, intent: 'finance.transfer' },
+    { pattern: /\b(swap|exchange|trade)/i, intent: 'finance.swap' },
+    { pattern: /\b(stake|unstake|deposit|withdraw|bond|unbond)/i, intent: 'finance.stake' },
+    { pattern: /\b(mint(?!NFT)|buy|purchase)/i, intent: 'finance.purchase' },
+    { pattern: /\b(approve|allowance|permit)/i, intent: 'finance.approve' },
+    { pattern: /\b(balance|getBalance|totalSupply)/i, intent: 'finance.balance' },
+    { pattern: /\b(borrow|repay|liquidate|collateral)/i, intent: 'finance.lending' },
+    // NFT
+    { pattern: /\b(mint(?:NFT)?|safeMint|createNFT)/i, intent: 'nft.mint' },
+    { pattern: /\b(listNFT|sellNFT|listFor(?:Sale)?)/i, intent: 'nft.list' },
+    { pattern: /\b(buyNFT|purchaseNFT)/i, intent: 'nft.buy' },
+    { pattern: /\b(burnNFT|burn)/i, intent: 'nft.burn' },
+    // Social (Farcaster-native)
+    { pattern: /\b(cast|compose(?:Cast)?|post(?:Cast)?)/i, intent: 'social.cast' },
+    { pattern: /\b(follow|unfollow|subscribe)/i, intent: 'social.follow' },
+    { pattern: /\b(like|react|upvote|downvote)/i, intent: 'social.react' },
+    { pattern: /\b(comment|reply)/i, intent: 'social.reply' },
+    { pattern: /\b(share|recast|repost)/i, intent: 'social.share' },
+    // Governance
+    { pattern: /\b(vote|castVote|submitVote)/i, intent: 'governance.vote' },
+    { pattern: /\b(propose|createProposal|submitProposal)/i, intent: 'governance.propose' },
+    { pattern: /\b(delegate|undelegate)/i, intent: 'governance.delegate' },
+    // Auth
+    { pattern: /\b(login|logout|signIn|signOut|connect|disconnect)/i, intent: 'auth.session' },
+    { pattern: /\b(register|signup|createAccount)/i, intent: 'auth.register' },
+    { pattern: /\b(verify(?:Signature|Address|Identity)?)/i, intent: 'auth.verify' },
+    // Data / CRUD
+    { pattern: /\b(get|fetch|load|read|list|query|search|find)/i, intent: 'data.read' },
+    { pattern: /\b(create|add|insert|save|store|upload)/i, intent: 'data.create' },
+    { pattern: /\b(update|edit|patch|set|change)/i, intent: 'data.update' },
+    { pattern: /\b(delete|remove|destroy|archive)/i, intent: 'data.delete' },
+    // Media
+    { pattern: /\b(upload(?:Image|File|Media)?|setAvatar|setImage)/i, intent: 'media.upload' },
+];
+/**
+ * Infer a semantic intent from the action name.
+ * Returns the first matching intent, or "util.action" as fallback.
+ */
+function inferIntent(name, overrideIntent) {
+    if (overrideIntent)
+        return overrideIntent;
+    for (const { pattern, intent } of INTENT_RULES) {
+        if (pattern.test(name))
+            return intent;
+    }
+    return 'util.action';
+}
+// ─── Safety classification ────────────────────────────────────────────────
+// No trailing \b — camelCase verbs like sendPayment, deleteAccount need prefix matching only
+const FINANCIAL_VERBS = /\b(transfer|send|pay|swap|exchange|trade|stake|unstake|deposit|withdraw|buy|purchase|mint|approve|borrow|repay|liquidate|bond|unbond)/i;
+const DESTRUCTIVE_VERBS = /\b(delete|remove|destroy|burn|archive|purge|wipe|clear)/i;
+/**
+ * Matches names that handle PII, credentials, or sensitive identity data.
+ * An agent touching these fields should always require human confirmation and
+ * encrypted transport — even if the HTTP verb is a GET.
+ *
+ * Examples: resetPassword, storeCredentials, uploadPassport, submitKyc,
+ *           updateSsn, exportPrivateKey, getMedicalRecord.
+ */
+// No \b — these nouns appear anywhere in camelCase (resetPassword, submitKyc, getSsn)
+const CONFIDENTIAL_NOUNS = /(password|credential|privateKey|secretKey|biometric|ssn|taxId|pii|kyc|medicalRecord|healthRecord|passport|driverLicense|creditCard|cvv|encryptedData|identityVerif)/i;
+/**
+ * Classify the safety level of an action.
+ *
+ * Rules (in priority order):
+ *  1. ABI write (non view/pure) + financial verb → financial
+ *  2. Financial verb anywhere → financial
+ *  3. Confidential noun (PII/credential) → confidential
+ *  4. ABI view/pure → read
+ *  5. GET HTTP method → read
+ *  6. Destructive verb → destructive
+ *  7. Everything else → write
+ */
+function classifySafety(opts) {
+    const { name, httpMethod, isReadOnly, type } = opts;
+    if (type === 'contract') {
+        if (isReadOnly)
+            return 'read';
+        if (FINANCIAL_VERBS.test(name))
+            return 'financial';
+        if (CONFIDENTIAL_NOUNS.test(name))
+            return 'confidential';
+        return 'write';
+    }
+    if (FINANCIAL_VERBS.test(name))
+        return 'financial';
+    if (CONFIDENTIAL_NOUNS.test(name))
+        return 'confidential';
+    if (httpMethod === 'GET')
+        return 'read';
+    if (DESTRUCTIVE_VERBS.test(name))
+        return 'destructive';
+    return 'write';
+}
+/** Derive agentSafe from safety level. Non-read/write levels require human confirmation. */
+function deriveAgentSafe(safety) {
+    return safety === 'read' || safety === 'write';
+}
+/**
+ * Infer per-action auth requirement.
+ *
+ * Rules:
+ *  1. Contract: view/pure → public; write → required (or farcaster-signed if app uses frames)
+ *  2. API GET + safety=read → public (heuristic: read endpoints are often open)
+ *  3. Farcaster frame app + write/financial/confidential → farcaster-signed
+ *  4. Financial → required + payments:write scope
+ *  5. Confidential → required + pii:read or pii:write scope
+ *  6. Destructive → required
+ *  7. Everything else → required (inherits app-level auth)
+ */
+function inferActionAuth(opts) {
+    const { safety, httpMethod, isReadOnly, appAuthType, type } = opts;
+    // Contract view/pure: always public (read-only, on-chain data)
+    if (type === 'contract' && isReadOnly) {
+        return { required: 'public' };
+    }
+    // Farcaster frame apps: sensitive actions need frame signature
+    if (appAuthType === 'farcaster-frame' &&
+        (safety === 'write' || safety === 'financial' || safety === 'destructive' || safety === 'confidential')) {
+        return { required: 'farcaster-signed' };
+    }
+    // Financial → required + payments:write scope
+    if (safety === 'financial') {
+        return { required: 'required', scope: 'payments:write' };
+    }
+    // Confidential → required + pii scope (write for mutations, read for fetches)
+    if (safety === 'confidential') {
+        return {
+            required: 'required',
+            scope: httpMethod === 'GET' ? 'pii:read' : 'pii:write',
+        };
+    }
+    // Destructive → required, no special scope
+    if (safety === 'destructive') {
+        return { required: 'required' };
+    }
+    // Read-only GET on a public (no-auth) app → public
+    if (httpMethod === 'GET' && safety === 'read' && (appAuthType === 'none' || !appAuthType)) {
+        return { required: 'public' };
+    }
+    return { required: 'required' };
+}