@yousif_nazhat/penpal-pi 0.2.0-rc.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yousif Nazhat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,12 @@
+# PenPal PI adapter
+
+This PI package adds PenPal's seven read-only, masked workspace tools to PI.
+
+Install the PenPal Python core first, then install this release candidate in PI:
+
+```bash
+python3 -m pip install --pre penpal-enum
+pi install npm:@yousif_nazhat/penpal-pi@0.2.0-rc.2
+```
+
+Set `PENPAL_WORKSPACE` when the workspace is not `penpal-workspace`; set `PENPAL_PYTHON` when Python is not available as `python3`.

package/index.ts

@@ -0,0 +1,151 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { Type } from "typebox";
+
+const execFileAsync = promisify(execFile);
+const cwd = process.env.PENPAL_CWD ?? process.cwd();
+const python = process.env.PENPAL_PYTHON ?? (process.platform === "win32" ? "python" : "python3");
+const workspace = process.env.PENPAL_WORKSPACE;
+const readOnlyTools = [
+  "penpal_context",
+  "penpal_suggest",
+  "penpal_evidence",
+  "penpal_playbooks_validate",
+  "penpal_playbook_show",
+  "penpal_modules_list",
+  "penpal_module_plan",
+];
+
+export default function (pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "penpal_context",
+    label: "PenPal context",
+    description: "Read PenPal's masked deterministic context snapshot for a target.",
+    parameters: Type.Object({ target: Type.String({ description: "PenPal target name" }) }),
+    async execute(_toolCallId, params, signal) {
+      return readOnly(["context", params.target, "--json"], signal);
+    },
+  });
+
+  pi.registerTool({
+    name: "penpal_suggest",
+    label: "PenPal suggestions",
+    description: "Read PenPal's deterministic suggestions for a target.",
+    parameters: Type.Object({ target: Type.String({ description: "PenPal target name" }) }),
+    async execute(_toolCallId, params, signal) {
+      return readOnly(["suggest", params.target, "--json"], signal);
+    },
+  });
+
+  pi.registerTool({
+    name: "penpal_evidence",
+    label: "PenPal evidence",
+    description: "Read PenPal's masked extracted evidence for a target.",
+    parameters: Type.Object({ target: Type.String({ description: "PenPal target name" }) }),
+    async execute(_toolCallId, params, signal) {
+      return readOnly(["evidence", params.target, "--json"], signal);
+    },
+  });
+
+  pi.registerTool({
+    name: "penpal_playbooks_validate",
+    label: "Validate PenPal playbooks",
+    description: "Validate PenPal's bundled playbooks.",
+    parameters: Type.Object({}),
+    async execute(_toolCallId, _params, signal) {
+      return readOnly(["playbooks", "playbooks", "--json"], signal);
+    },
+  });
+
+  pi.registerTool({
+    name: "penpal_playbook_show",
+    label: "Show PenPal playbook",
+    description: "Read one validated PenPal playbook by id.",
+    parameters: Type.Object({ id: Type.String({ description: "Playbook id" }) }),
+    async execute(_toolCallId, params, signal) {
+      return readOnly(["playbooks", "playbooks", "--show", params.id], signal);
+    },
+  });
+
+  pi.registerTool({
+    name: "penpal_modules_list",
+    label: "List PenPal service modules",
+    description: "Read PenPal's source-backed service module registry.",
+    parameters: Type.Object({}),
+    async execute(_toolCallId, _params, signal) {
+      return readOnly(["modules", "list", "--json"], signal);
+    },
+  });
+
+  pi.registerTool({
+    name: "penpal_module_plan",
+    label: "Plan PenPal service module",
+    description: "Read a source-backed module plan without executing commands.",
+    parameters: Type.Object({
+      target: Type.String({ description: "PenPal target name" }),
+      module: Type.String({ description: "Module name, such as snmp, web, smb, or dns" }),
+    }),
+    async execute(_toolCallId, params, signal) {
+      return readOnly(["modules", "plan", params.target, params.module, "--json"], signal);
+    },
+  });
+
+  pi.registerCommand("penpal-status", {
+    description: "Verify PenPal's read-only PI tools and deterministic core.",
+    handler: async (_args, ctx) => {
+      const registered = new Set(pi.getAllTools().map((tool) => tool.name));
+      const missing = readOnlyTools.filter((tool) => !registered.has(tool));
+      if (missing.length > 0) {
+        ctx.ui.notify(`PenPal extension incomplete; missing tools: ${missing.join(", ")}`, "error");
+        return;
+      }
+      try {
+        const report = JSON.parse(await penpal(["playbooks", "playbooks", "--json"]));
+        if (report.invalid_playbooks !== 0) {
+          ctx.ui.notify(`PenPal core reported ${report.invalid_playbooks} invalid playbooks`, "error");
+          return;
+        }
+        ctx.ui.notify(
+          `PenPal ready: ${readOnlyTools.length} read-only tools registered; ${report.valid_playbooks} playbooks valid.`,
+          "info",
+        );
+      } catch (error) {
+        ctx.ui.notify(errorMessage(error), "error");
+      }
+    },
+  });
+}
+
+async function readOnly(args: string[], signal?: AbortSignal) {
+  try {
+    return textResult(await penpal(args, signal));
+  } catch (error) {
+    return textResult(`error: ${errorMessage(error)}`);
+  }
+}
+
+async function penpal(args: string[], signal?: AbortSignal): Promise<string> {
+  const fullArgs = ["-m", "penpal"];
+  if (workspace) fullArgs.push("--workspace", workspace);
+  fullArgs.push(...args);
+  const { stdout } = await execFileAsync(python, fullArgs, {
+    cwd,
+    signal,
+    timeout: 30_000,
+    maxBuffer: 2_000_000,
+  });
+  return stdout.trim();
+}
+
+function errorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    const stderr = (error as Error & { stderr?: string }).stderr?.trim();
+    return stderr || error.message;
+  }
+  return String(error);
+}
+
+function textResult(text: string) {
+  return { content: [{ type: "text" as const, text }], details: {} };
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@yousif_nazhat/penpal-pi",
+  "version": "0.2.0-rc.2",
+  "description": "PI cockpit for the PenPal Python core.",
+  "license": "MIT",
+  "keywords": ["pi-package", "penpal"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": ["index.ts", "LICENSE", "README.md"],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "pi": {
+    "extensions": ["./index.ts"]
+  }
+}