@agentplugins/adapter-pimono 0.1.0

package/README.md

@@ -0,0 +1,43 @@
+# @agentplugins/adapter-pimono
+
+> AgentPlugins platform adapter for [Pi Mono](https://pi.mono/).
+
+Generates TypeScript-native extensions for the Pi agent runtime from a universal `PluginManifest`. Pi Mono extensions are regular TS modules, so handlers are emitted as real functions rather than wrapped scripts.
+
+## Installation
+
+```bash
+npm install @agentplugins/adapter-pimono
+```
+
+Typically installed transitively via [`@agentplugins/cli`](https://www.npmjs.com/package/@agentplugins/cli).
+
+## Usage
+
+```typescript
+import { createPiMonoAdapter } from '@agentplugins/adapter-pimono';
+
+const adapter = createPiMonoAdapter();
+const output = await adapter.compile(manifest);
+```
+
+Or via the CLI:
+
+```bash
+npx agentplugins build --target pimono
+```
+
+## Output shape
+
+A successful build writes to `dist/pimono/`:
+
+```
+dist/pimono/
+└── <plugin-name>.ts
+```
+
+Install with: `cp -r dist/pimono ~/.pi/agent/extensions/`
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,576 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  HOOK_TO_EVENT: () => HOOK_TO_EVENT,
+  PiMonoAdapter: () => PiMonoAdapter,
+  SUPPORTED_HANDLERS: () => SUPPORTED_HANDLERS,
+  SUPPORTED_HOOKS: () => SUPPORTED_HOOKS,
+  createPiMonoAdapter: () => createPiMonoAdapter,
+  piMonoAdapter: () => piMonoAdapter
+});
+module.exports = __toCommonJS(index_exports);
+var import_core = require("@agentplugins/core");
+var PLATFORM_NAME = "pimono";
+var DISPLAY_NAME = "Pi Mono";
+var MANIFEST_PATH = "package.json";
+var MANIFEST_FORMAT = "json";
+var SUPPORTED_HOOKS = [
+  "sessionStart",
+  "sessionEnd",
+  "preToolUse",
+  "postToolUse",
+  "userPromptSubmit",
+  "notification",
+  "subagentStart",
+  "subagentStop",
+  "preCompact",
+  "stop"
+];
+var SUPPORTED_HANDLERS = [
+  "inline",
+  // pi.on(event, async (ctx) => { … })
+  "reference"
+  // Handled by generating a proxy that calls the named function
+];
+var HOOK_TO_EVENT = {
+  sessionStart: "session.SessionStart",
+  sessionEnd: "session.SessionEnd",
+  preToolUse: "tool.ToolCall",
+  postToolUse: "tool.ToolResult",
+  userPromptSubmit: "message.MessageReceive",
+  notification: "message.Notification",
+  subagentStart: "agent.AgentStart",
+  subagentStop: "agent.AgentStop",
+  preCompact: "session.CompactStart",
+  stop: "agent.AgentStop"
+};
+function tsStringLiteral(raw) {
+  const escaped = raw.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\n/g, "\\n").replace(/\r/g, "\\r");
+  return `'${escaped}'`;
+}
+function safeIdent(name) {
+  const cleaned = name.replace(/[^a-zA-Z0-9_]/g, "_");
+  return /^\d/.test(cleaned) ? `_${cleaned}` : cleaned;
+}
+function validatePlugin(plugin) {
+  const issues = [];
+  if (!plugin.name || typeof plugin.name !== "string") {
+    issues.push({
+      severity: import_core.Severity.ERROR,
+      message: `Plugin "name" is required and must be a non-empty string.`
+    });
+  }
+  if (plugin.hooks) {
+    for (const hookKey of Object.keys(plugin.hooks)) {
+      const hookName = hookKey;
+      if (!SUPPORTED_HOOKS.includes(hookName)) {
+        const piMonoEvent = HOOK_TO_EVENT[hookName];
+        issues.push({
+          severity: import_core.Severity.ERROR,
+          message: `Unsupported hook "${hookName}". ` + (piMonoEvent ? `This adapter maps it to "${piMonoEvent}", but the hook is not listed as supported.` : `No Pi Mono event mapping exists for this hook.`)
+        });
+      }
+      const hook = plugin.hooks[hookName];
+      if (!hook) continue;
+      const hookHandler = hook.handler;
+      if (hookHandler.type === "inline") {
+        continue;
+      }
+      if (hookHandler.type === "reference") {
+        const refHandler = hookHandler;
+        if (!refHandler.target || typeof refHandler.target !== "string") {
+          issues.push({
+            severity: import_core.Severity.ERROR,
+            message: `Handler reference for "${hookName}" must specify a non-empty "target" string.`
+          });
+        }
+        continue;
+      }
+      issues.push({
+        severity: import_core.Severity.WARNING,
+        message: `Unknown handler type "${hookHandler.type}" for hook "${hookName}". Will be treated as inline.`
+      });
+    }
+  }
+  if (plugin.tools) {
+    for (const tool of plugin.tools) {
+      if (!tool.name || typeof tool.name !== "string") {
+        issues.push({
+          severity: import_core.Severity.ERROR,
+          message: `Tool name is required.`
+        });
+      }
+      if (!tool.parameters || typeof tool.parameters !== "object") {
+        issues.push({
+          severity: import_core.Severity.ERROR,
+          message: `Tool "${tool.name ?? "?"}" must have a parameters object (TypeBox-compatible).`
+        });
+      }
+    }
+  }
+  if (plugin.commands) {
+    for (const cmd of plugin.commands) {
+      if (!cmd.name || typeof cmd.name !== "string") {
+        issues.push({
+          severity: import_core.Severity.ERROR,
+          message: `Command name is required.`
+        });
+      }
+    }
+  }
+  if (plugin.shortcuts) {
+    for (const sc of plugin.shortcuts) {
+      if (!sc.key || typeof sc.key !== "string") {
+        issues.push({
+          severity: import_core.Severity.ERROR,
+          message: `Shortcut key is required.`
+        });
+      }
+    }
+  }
+  if (plugin.flags) {
+    for (const flag of plugin.flags) {
+      if (!flag.name || typeof flag.name !== "string") {
+        issues.push({
+          severity: import_core.Severity.ERROR,
+          message: `Flag name is required.`
+        });
+      }
+    }
+  }
+  return issues;
+}
+function generateInlineHandlerBody(handler, event) {
+  const lines = [];
+  lines.push(`// Handler for ${event}`);
+  if (handler.code) {
+    lines.push(handler.code.trim());
+  } else if (handler.source) {
+    lines.push(`// NOTE: Handler source "${handler.source}" must be copied into this function.`);
+    lines.push(`throw new Error("Handler source not inlined: ${handler.source.replace(/"/g, "\\'")}");`);
+  } else {
+    lines.push(`ctx.logger?.info?.("[${event}] Hook invoked \u2014 no handler code provided.");`);
+    lines.push(`// TODO: Implement handler logic`);
+  }
+  return lines.join("\n    ");
+}
+function generateReferenceHandler(handler) {
+  const { target, source } = handler;
+  const lines = [];
+  if (source) {
+    lines.push(`const mod = await import(${tsStringLiteral(source)});`);
+    lines.push(`const fn = mod[${tsStringLiteral(target)}] ?? mod.default;`);
+  } else {
+    lines.push(`const fn = ${safeIdent(target)};`);
+  }
+  lines.push(`if (typeof fn !== "function") {`);
+  lines.push(`  throw new Error(\`Handler "${target}" is not a function.\`);`);
+  lines.push(`}`);
+  lines.push(`return fn(ctx);`);
+  return lines.join("\n    ");
+}
+function generateEventRegistration(event, handler) {
+  const lines = [];
+  lines.push(`// ${event}`);
+  lines.push(`pi.on(${tsStringLiteral(event)}, async (ctx) => {`);
+  if (handler.type === "reference") {
+    lines.push(`  ${generateReferenceHandler(handler).replace(/\n/g, "\n  ")}`);
+  } else {
+    lines.push(
+      `  ${generateInlineHandlerBody(handler, event).replace(/\n/g, "\n  ")}`
+    );
+  }
+  lines.push(`});`);
+  return lines;
+}
+function generateToolRegistrations(tools) {
+  const lines = [];
+  for (const tool of tools) {
+    const toolName = safeIdent(tool.name);
+    lines.push(``);
+    lines.push(`// Tool: ${tool.name}`);
+    lines.push(`pi.registerTool({`);
+    lines.push(`  name: ${tsStringLiteral(tool.name)},`);
+    lines.push(`  description: ${tsStringLiteral(tool.description ?? `${tool.name} tool`)},`);
+    if (tool.parameters) {
+      const schemaJson = JSON.stringify(tool.parameters, null, 2).split("\n").map((l, i) => i === 0 ? l : `    ${l}`).join("\n");
+      lines.push(`  schema: ${schemaJson},`);
+    }
+    lines.push(`  handler: async (args) => {`);
+    if (tool.handler?.source) {
+      lines.push(`    const mod = await import(${tsStringLiteral(tool.handler.source ?? "")});`);
+      lines.push(`    return mod[${tsStringLiteral(tool.handler.target ?? "default")}](args);`);
+    } else if (tool.handler?.target) {
+      lines.push(`    return ${safeIdent(tool.handler.target)}(args);`);
+    } else {
+      lines.push(`    // TODO: Implement tool handler for "${tool.name}"`);
+      lines.push(`    throw new Error("Tool handler not implemented: ${tool.name}");`);
+    }
+    lines.push(`  },`);
+    lines.push(`});`);
+  }
+  return lines;
+}
+function generateCommandRegistrations(commands) {
+  const lines = [];
+  for (const cmd of commands) {
+    lines.push(``);
+    lines.push(`// Command: /${cmd.name}`);
+    lines.push(`pi.registerCommand(${tsStringLiteral(cmd.name)}, {`);
+    if (cmd.description) {
+      lines.push(`  description: ${tsStringLiteral(cmd.description)},`);
+    }
+    if (cmd.args && cmd.args.length > 0) {
+      const argsSchema = cmd.args.map((a) => ({
+        name: a.name,
+        type: a.type ?? "string",
+        description: a.description,
+        required: a.required ?? false
+      }));
+      const argsJson = JSON.stringify(argsSchema, null, 2).split("\n").map((l, i) => i === 0 ? l : `    ${l}`).join("\n");
+      lines.push(`  args: ${argsJson},`);
+    }
+    lines.push(`  run: async (ctx, args) => {`);
+    if (cmd.handler?.source) {
+      lines.push(`    const mod = await import(${tsStringLiteral(cmd.handler.source)});`);
+      lines.push(`    return mod[${tsStringLiteral(cmd.handler.target ?? "default")}](ctx, args);`);
+    } else if (cmd.handler?.target) {
+      lines.push(`    return ${safeIdent(cmd.handler.target)}(ctx, args);`);
+    } else {
+      lines.push(`    // TODO: Implement command handler for "/${cmd.name}"`);
+      lines.push(`    ctx.ui?.toast?.(\`/${cmd.name} executed\`);`);
+    }
+    lines.push(`  },`);
+    lines.push(`});`);
+  }
+  return lines;
+}
+function generateShortcutRegistrations(shortcuts) {
+  const lines = [];
+  for (const sc of shortcuts) {
+    lines.push(``);
+    lines.push(`// Shortcut: ${sc.key}`);
+    lines.push(`pi.registerShortcut(${tsStringLiteral(sc.key)}, {`);
+    if (sc.description) {
+      lines.push(`  description: ${tsStringLiteral(sc.description)},`);
+    }
+    if (sc.when) {
+      lines.push(`  when: ${tsStringLiteral(sc.when)},`);
+    }
+    lines.push(`  action: async (ctx) => {`);
+    if (sc.action) {
+      if (typeof sc.action === "string") {
+        lines.push(`    return ${safeIdent(sc.action)}(ctx);`);
+      } else if (sc.action.source) {
+        lines.push(`    const mod = await import(${tsStringLiteral(sc.action.source)});`);
+        lines.push(`    return mod[${tsStringLiteral(sc.action.target ?? "default")}](ctx);`);
+      } else if (sc.action.target) {
+        lines.push(`    return ${safeIdent(sc.action.target)}(ctx);`);
+      }
+    } else {
+      lines.push(`    // TODO: Implement shortcut action for "${sc.key}"`);
+      lines.push(`    ctx.logger?.info?.("Shortcut triggered: ${sc.key}");`);
+    }
+    lines.push(`  },`);
+    lines.push(`});`);
+  }
+  return lines;
+}
+function generateFlagRegistrations(flags) {
+  const lines = [];
+  for (const flag of flags) {
+    lines.push(``);
+    lines.push(`// Flag: --${flag.name}`);
+    lines.push(`pi.registerFlag(${tsStringLiteral(flag.name)}, {`);
+    if (flag.description) {
+      lines.push(`  description: ${tsStringLiteral(flag.description)},`);
+    }
+    if (flag.alias) {
+      lines.push(`  alias: ${tsStringLiteral(flag.alias)},`);
+    }
+    if (flag.type) {
+      lines.push(`  type: ${tsStringLiteral(flag.type)},`);
+    }
+    if (flag.defaultValue !== void 0) {
+      lines.push(`  default: ${JSON.stringify(flag.defaultValue)},`);
+    }
+    lines.push(`  handler: async (ctx, value) => {`);
+    if (flag.handler?.source) {
+      lines.push(`    const mod = await import(${tsStringLiteral(flag.handler.source)});`);
+      lines.push(`    return mod[${tsStringLiteral(flag.handler.target ?? "default")}](ctx, value);`);
+    } else if (flag.handler?.target) {
+      lines.push(`    return ${safeIdent(flag.handler.target)}(ctx, value);`);
+    } else {
+      lines.push(`    // TODO: Implement flag handler for "--${flag.name}"`);
+      lines.push(`    ctx.logger?.info?.(\`Flag --${flag.name}=\${value} processed\`);`);
+    }
+    lines.push(`  },`);
+    lines.push(`});`);
+  }
+  return lines;
+}
+function compilePlugin(plugin) {
+  const files = [];
+  let isMultiFile = false;
+  if (plugin.hooks) {
+    for (const handler of Object.values(plugin.hooks)) {
+      if (handler.type === "reference" && handler.source) {
+        isMultiFile = true;
+        break;
+      }
+      if (handler.type === "inline" && handler.source) {
+        isMultiFile = true;
+        break;
+      }
+    }
+  }
+  if (plugin.tools) {
+    for (const tool of plugin.tools) {
+      if (tool.handler?.source) {
+        isMultiFile = true;
+        break;
+      }
+    }
+  }
+  if (plugin.commands) {
+    for (const cmd of plugin.commands) {
+      if (cmd.handler?.source) {
+        isMultiFile = true;
+        break;
+      }
+    }
+  }
+  if (plugin.shortcuts) {
+    for (const sc of plugin.shortcuts) {
+      if (typeof sc.action !== "string" && sc.action?.source) {
+        isMultiFile = true;
+        break;
+      }
+    }
+  }
+  if (plugin.flags) {
+    for (const flag of plugin.flags) {
+      if (flag.handler?.source) {
+        isMultiFile = true;
+        break;
+      }
+    }
+  }
+  const tsLines = [];
+  tsLines.push(`/**`);
+  tsLines.push(` * Generated Pi Mono Extension \u2014 ${plugin.name}`);
+  tsLines.push(` *`);
+  tsLines.push(` * Platform:    ${DISPLAY_NAME}`);
+  tsLines.push(` * Plugin:      ${plugin.name}${plugin.version ? ` v${plugin.version}` : ""}`);
+  tsLines.push(` * Generated:   ${(/* @__PURE__ */ new Date()).toISOString()}`);
+  tsLines.push(` *`);
+  tsLines.push(` * This file is auto-generated by @agentplugins/adapter-pimono.`);
+  tsLines.push(` * Do not edit manually \u2014 changes will be overwritten on next compile.`);
+  tsLines.push(` */`);
+  tsLines.push(``);
+  tsLines.push(`import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";`);
+  const dynamicImports = /* @__PURE__ */ new Set();
+  if (plugin.hooks) {
+    for (const handler of Object.values(plugin.hooks)) {
+      if ("source" in handler && handler.source) {
+        dynamicImports.add(handler.source);
+      }
+    }
+  }
+  if (plugin.tools) {
+    for (const tool of plugin.tools) {
+      if (tool.handler?.source) dynamicImports.add(tool.handler.source);
+    }
+  }
+  if (plugin.commands) {
+    for (const cmd of plugin.commands) {
+      if (cmd.handler?.source) dynamicImports.add(cmd.handler.source);
+    }
+  }
+  if (dynamicImports.size > 0) {
+    tsLines.push(``);
+    tsLines.push(`// External handler modules (loaded dynamically via jiti)`);
+  }
+  tsLines.push(``);
+  tsLines.push(`/**`);
+  tsLines.push(` * Pi Mono extension factory.`);
+  tsLines.push(` *`);
+  tsLines.push(` * @param pi - The ExtensionAPI instance provided by the Pi Mono runtime.`);
+  tsLines.push(` */`);
+  tsLines.push(`export default function(pi: ExtensionAPI) {`);
+  tsLines.push(`  // Extension entry point \u2014 register all hooks, tools, commands, etc.`);
+  tsLines.push(`  pi.logger?.info?.("[${plugin.name}] Extension loaded on ${DISPLAY_NAME}");`);
+  tsLines.push(``);
+  if (plugin.hooks && Object.keys(plugin.hooks).length > 0) {
+    tsLines.push(`  /* \u2500\u2500 Lifecycle Hooks \u2500\u2500 */`);
+    for (const [hookName, handler] of Object.entries(plugin.hooks)) {
+      const event = HOOK_TO_EVENT[hookName];
+      if (!event) {
+        tsLines.push(`  // WARNING: No Pi Mono event for hook "${hookName}" \u2014 skipping`);
+        tsLines.push(``);
+        continue;
+      }
+      const regLines = generateEventRegistration(event, handler);
+      for (const line of regLines) {
+        tsLines.push(`  ${line}`);
+      }
+      tsLines.push(``);
+    }
+  }
+  if (plugin.tools && plugin.tools.length > 0) {
+    tsLines.push(`  /* \u2500\u2500 Tools \u2500\u2500 */`);
+    for (const line of generateToolRegistrations(plugin.tools)) {
+      tsLines.push(`  ${line}`);
+    }
+    tsLines.push(``);
+  }
+  if (plugin.commands && plugin.commands.length > 0) {
+    tsLines.push(`  /* \u2500\u2500 Commands \u2500\u2500 */`);
+    for (const line of generateCommandRegistrations(plugin.commands)) {
+      tsLines.push(`  ${line}`);
+    }
+    tsLines.push(``);
+  }
+  if (plugin.shortcuts && plugin.shortcuts.length > 0) {
+    tsLines.push(`  /* \u2500\u2500 Keyboard Shortcuts \u2500\u2500 */`);
+    for (const line of generateShortcutRegistrations(plugin.shortcuts)) {
+      tsLines.push(`  ${line}`);
+    }
+    tsLines.push(``);
+  }
+  if (plugin.flags && plugin.flags.length > 0) {
+    tsLines.push(`  /* \u2500\u2500 CLI Flags \u2500\u2500 */`);
+    for (const line of generateFlagRegistrations(plugin.flags)) {
+      tsLines.push(`  ${line}`);
+    }
+    tsLines.push(``);
+  }
+  if (plugin.config?.persist) {
+    tsLines.push(`  /* \u2500\u2500 Persistent State \u2500\u2500 */`);
+    tsLines.push(`  pi.appendEntry("${plugin.name}", {`);
+    tsLines.push(`    loadedAt: new Date().toISOString(),`);
+    tsLines.push(`    version: ${tsStringLiteral(plugin.version ?? "0.0.0")},`);
+    tsLines.push(`  });`);
+    tsLines.push(``);
+  }
+  tsLines.push(`}`);
+  tsLines.push(``);
+  files.push({ path: "index.ts", content: tsLines.join("\n") });
+  if (isMultiFile) {
+    const pkg = {
+      name: plugin.name,
+      version: plugin.version ?? "0.0.0",
+      description: plugin.description ?? `Pi Mono extension for ${plugin.name}`,
+      main: "index.ts",
+      pi: {
+        name: plugin.name,
+        version: plugin.version ?? "0.0.0",
+        displayName: plugin.displayName ?? plugin.name,
+        description: plugin.description,
+        entry: "index.ts",
+        author: plugin.author,
+        license: plugin.license,
+        hooks: Object.keys(plugin.hooks ?? {}).map((h) => ({
+          universal: h,
+          piEvent: HOOK_TO_EVENT[h] ?? null
+        })),
+        tools: (plugin.tools ?? []).map((t) => t.name),
+        commands: (plugin.commands ?? []).map((c) => c.name),
+        shortcuts: (plugin.shortcuts ?? []).map((s) => s.key),
+        flags: (plugin.flags ?? []).map((f) => f.name),
+        trusted: plugin.config?.trusted ?? true,
+        autoLoad: plugin.config?.autoLoad ?? false
+      }
+    };
+    files.push({ path: "package.json", content: JSON.stringify(pkg, null, 2) + "\n" });
+  }
+  const warnings = [];
+  if (plugin.hooks) {
+    for (const hookName of Object.keys(plugin.hooks)) {
+      if (!SUPPORTED_HOOKS.includes(hookName)) {
+        warnings.push(
+          `Hook "${hookName}" is not supported by the Pi Mono adapter and was skipped.`
+        );
+      }
+    }
+  }
+  return {
+    files,
+    manifest: plugin,
+    warnings,
+    issues: []
+  };
+}
+var PiMonoAdapter = class {
+  /** @inheritdoc */
+  name = PLATFORM_NAME;
+  /** @inheritdoc */
+  displayName = DISPLAY_NAME;
+  /** @inheritdoc */
+  supportedHooks = SUPPORTED_HOOKS;
+  /** @inheritdoc */
+  supportedHandlers = SUPPORTED_HANDLERS;
+  /** @inheritdoc */
+  manifestPath = MANIFEST_PATH;
+  /** @inheritdoc */
+  manifestFormat = MANIFEST_FORMAT;
+  /**
+   * Validate a plugin manifest for Pi Mono compatibility.
+   *
+   * @param plugin - The plugin manifest.
+   * @returns Array of validation issues (empty if valid).
+   */
+  validate(plugin) {
+    return validatePlugin(plugin);
+  }
+  /**
+   * Compile a plugin manifest into Pi Mono extension files.
+   *
+   * @param plugin - The plugin manifest.
+   * @returns AdapterOutput containing generated files and metadata.
+   */
+  compile(plugin) {
+    const issues = this.validate(plugin);
+    const errors = issues.filter((i) => i.severity === "error");
+    if (errors.length > 0) {
+      const errorMessages = errors.map((e) => `  - ${e.message}`).join("\n");
+      throw new Error(
+        `Pi Mono adapter validation failed with ${errors.length} error(s):
+${errorMessages}`
+      );
+    }
+    return compilePlugin(plugin);
+  }
+};
+var piMonoAdapter = new PiMonoAdapter();
+function createPiMonoAdapter() {
+  return new PiMonoAdapter();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HOOK_TO_EVENT,
+  PiMonoAdapter,
+  SUPPORTED_HANDLERS,
+  SUPPORTED_HOOKS,
+  createPiMonoAdapter,
+  piMonoAdapter
+});