Plugins

module.exports = {
  // ... extension points
};

~/.forage/plugins/
  my-plugin/
    forage-plugin.json   ← optional manifest
    index.js             ← required entry point
    lib/
      helper.js          ← any supporting files

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "What this plugin does",
  "main": "index.js",
  "disabled": false
}

'use strict';

module.exports = {
  tools:    [...],   // agent tools
  routes:   (router, { requireWs }) => { ... },   // API routes
  mcpTools: [...],   // MCP tools
  hooks:    { ... }, // lifecycle hooks
};

module.exports = {
  tools: [
    {
      name: 'fetch_readme',
      description: 'Fetch the README for an npm package by name',
      args: {
        packageName: 'The npm package name, e.g. "express"',
      },
      async execute(args, context) {
        // context.workspacePath — absolute path to the active workspace
        // context.toolRegistry  — the full ToolRegistry instance
        const res = await fetch(
          `https://registry.npmjs.org/${args.packageName}`
        );
        const data = await res.json();
        return { readme: data.readme || 'No README available.' };
      },
    },
  ],
};

module.exports = {
  routes(router, { requireWs }) {
    // GET /api/plugins/my-plugin/status
    router.get('/status', (req, res) => {
      res.json({ ok: true, plugin: 'my-plugin' });
    });

    // POST /api/plugins/my-plugin/summarise
    // requireWs resolves the workspace from the X-Workspace header
    router.post('/summarise', requireWs, async (req, res) => {
      const { filePath } = req.body;
      // req.workspacePath is set by requireWs
      // ... do work ...
      res.json({ summary: '...' });
    });
  },
};

module.exports = {
  mcpTools: [
    {
      name: 'search_jira',
      description: 'Search Jira issues related to a codebase symbol or keyword',
      inputSchema: {
        type: 'object',
        properties: {
          query: {
            type: 'string',
            description: 'Search term or symbol name',
          },
          workspace: {
            type: 'string',
            description: 'Workspace name or path. Omit to use the default.',
          },
        },
        required: ['query'],
      },
      async execute(args, workspacePath) {
        // args — the validated input object
        // workspacePath — resolved workspace path
        const issues = await myJiraClient.search(args.query);
        return { issues };
      },
    },
  ],
};

module.exports = {
  hooks: {
    async afterCrawl({ workspacePath, result }) {
      console.log(
        `[my-plugin] crawl done for ${workspacePath}: ` +
        `${result.indexed} files indexed`
      );
    },
  },
};

module.exports = {
  hooks: {
    async beforeChat({ messages, workspacePath, question }) {
      // Inject an extra system instruction
      messages.push({
        role: 'system',
        content: 'Always cite the file path when referencing code.',
      });
      // Return the full payload — omitting a return value leaves it unchanged
      return { messages, workspacePath, question };
    },
  },
};

module.exports = {
  hooks: {
    async afterChat({ question, answer, workspacePath }) {
      await myAuditLog.write({ question, answer, workspacePath, ts: Date.now() });
    },
  },
};

module.exports = {
  hooks: {
    async onFileChange({ filePath, event, workspacePath }) {
      // event is the raw watcher event string, e.g. 'change', 'add', 'unlink'
      if (filePath.endsWith('.env')) {
        console.warn(`[my-plugin] .env file changed — check for leaked secrets`);
      }
    },
  },
};

'use strict';

const fs   = require('fs');
const path = require('path');

function logPath(workspacePath) {
  return path.join(workspacePath, '.forage', 'changelog.ndjson');
}

module.exports = {
  // Agent tool: let the LLM read the local changelog
  tools: [
    {
      name: 'read_changelog',
      description: 'Read the Forage change log entries for this workspace',
      args: { limit: 'Max number of entries to return (default 20)' },
      execute(args, { workspacePath }) {
        const file = logPath(workspacePath);
        if (!fs.existsSync(file)) return { entries: [] };
        const lines = fs.readFileSync(file, 'utf8')
          .trim().split('\n').filter(Boolean).slice(-(args.limit || 20));
        return { entries: lines.map(l => JSON.parse(l)) };
      },
    },
  ],

  // REST route: expose the changelog over HTTP
  routes(router, { requireWs }) {
    router.get('/entries', requireWs, (req, res) => {
      const file = logPath(req.workspacePath);
      if (!fs.existsSync(file)) return res.json({ entries: [] });
      const lines = fs.readFileSync(file, 'utf8')
        .trim().split('\n').filter(Boolean);
      res.json({ entries: lines.map(l => JSON.parse(l)) });
    });
  },

  // Hook: record every chat question and answer
  hooks: {
    async afterChat({ question, answer, workspacePath }) {
      const entry = JSON.stringify({ ts: Date.now(), question, answer }) + '\n';
      fs.appendFileSync(logPath(workspacePath), entry, 'utf8');
    },
  },
};

GET http://localhost:9988/api/plugins

{
  "plugins": [
    {
      "name": "changelog-tracker",
      "manifest": { "name": "changelog-tracker", "version": "1.0.0" },
      "dir": "/Users/you/.forage/plugins/changelog-tracker",
      "scope": "global"
    },
    {
      "name": "jira-search",
      "manifest": { "name": "jira-search", "version": "0.3.0" },
      "dir": "/Users/you/projects/my-app/.forage/plugins/jira-search",
      "scope": "/Users/you/projects/my-app"
    }
  ]
}