pi-archimedes 2.6.3 → 2.7.1

package/README.md

@@ -64,7 +64,7 @@ Then run `/reload` in your session (or start a new one) to pick it up — that r
    }
    ```
 
-   If it already exists, just add/set `"app.clipboard.pasteImage": []` in there and run `/reload`.
+   If it already exists, just add/set `"app.clipboard.pasteImage": []` in there and run `/reload`. Or skip the step entirely if the file doesn't exist yet: on the first TUI session the suite offers to create it automatically with the snippet above — accepting creates it and reloads the terminal automatically (the cleared binding applies immediately); declining or cancelling (Esc) never asks again.
 
 `/login` signs you into a supported provider (subscription or API key) and `/model` selects a model from it. Model access comes through the providers you configure in Pi — Pi's [provider docs](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/providers.md) list the supported ones, and Archimedes doesn't ship a model of its own. For the broader first run, Pi's [quickstart](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/quickstart.md) is worth a read.
 
@@ -170,7 +170,7 @@ Only want the diffs, footer, or MCP tools? Each component is available separatel
 
 ## Settings
 
-Every component keeps its own namespace under `~/.pi/agent/settings.json`, which Pi parses as **strict JSON** (no comments — unlike MCP server configs, which accept JSONC). Each component's README documents its namespace, fields, and defaults — including [core](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/core/README.md) (chrome, spinner, thinking), [footer](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/footer/README.md), [diff](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/diff/README.md), [notify](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/notify/README.md), [mcp](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/mcp/README.md), and [sudo](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/sudo/README.md) (also strict JSON). The `/archimedes` panel covers the settings that have a control; not everything does.
+Every component keeps its own namespace under `~/.pi/agent/settings.json`, which Pi parses as **strict JSON** (no comments — unlike MCP server configs, which accept JSONC). Each component's README documents its namespace, fields, and defaults — including [core](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/core/README.md) (chrome, spinner, thinking), [footer](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/footer/README.md), [diff](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/diff/README.md), [notify](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/notify/README.md), [mcp](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/mcp/README.md), [image-paste](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/image-paste/README.md), and [sudo](https://github.com/danielcherubini/pi-archimedes/blob/main/packages/sudo/README.md) (also strict JSON). The `/archimedes` panel covers the settings that have a control; not everything does.
 
 ---
 

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "pi-archimedes",
-  "version": "2.6.3",
+  "version": "2.7.1",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/danielcherubini/pi-archimedes.git"
+  },
   "type": "module",
   "keywords": [
     "pi-package"
@@ -12,17 +16,17 @@
   ],
   "main": "./src/index.ts",
   "dependencies": {
-    "@pi-archimedes/core": "2.6.3",
-    "@pi-archimedes/diff": "2.6.3",
-    "@pi-archimedes/footer": "2.6.3",
-    "@pi-archimedes/image-paste": "2.6.3",
-    "@pi-archimedes/ask": "2.6.3",
-    "@pi-archimedes/subagent": "2.6.3",
-    "@pi-archimedes/notify": "2.6.3",
-    "@pi-archimedes/todo": "2.6.3",
-    "@pi-archimedes/mcp": "2.6.3",
-    "@pi-archimedes/sudo": "2.6.3",
-    "@pi-archimedes/session-name": "2.6.3"
+    "@pi-archimedes/core": "2.7.1",
+    "@pi-archimedes/footer": "2.7.1",
+    "@pi-archimedes/diff": "2.7.1",
+    "@pi-archimedes/image-paste": "2.7.1",
+    "@pi-archimedes/ask": "2.7.1",
+    "@pi-archimedes/subagent": "2.7.1",
+    "@pi-archimedes/notify": "2.7.1",
+    "@pi-archimedes/todo": "2.7.1",
+    "@pi-archimedes/mcp": "2.7.1",
+    "@pi-archimedes/session-name": "2.7.1",
+    "@pi-archimedes/sudo": "2.7.1"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.1.0",

package/src/factory-lifecycle.test.ts

@@ -60,6 +60,7 @@ vi.mock("@pi-archimedes/todo", () => ({ registerTodo: vi.fn() }));
 vi.mock("@pi-archimedes/ask", () => ({ registerAsk: vi.fn() }));
 vi.mock("@pi-archimedes/notify", () => ({ registerNotify: vi.fn() }));
 vi.mock("@pi-archimedes/session-name", () => ({ registerSessionName: vi.fn() }));
+vi.mock("@pi-archimedes/sudo", () => ({ registerSudo: vi.fn() }));
 
 // Dynamic imports done in the session_start handler — mock EXACTLY the
 // properties index.ts uses via destructured `ipMod.*` / `diffMod` / `saMod` /
@@ -72,6 +73,9 @@ vi.mock("@pi-archimedes/image-paste", () => ({
   shutdownImagePaste: vi.fn(),
   initImagePasteSession: vi.fn(),
 }));
+vi.mock("@pi-archimedes/image-paste/keybinding-offer", () => ({
+  offerKeybindingFix: vi.fn(),
+}));
 vi.mock("@pi-archimedes/subagent", () => ({
   registerSubagent: vi.fn(),
   registerAgentsCommand: vi.fn(),
@@ -92,6 +96,9 @@ const { default: metaFactory } = await import("./index.js");
 const { registerImagePaste, shutdownImagePaste, initImagePasteSession } =
   await import("@pi-archimedes/image-paste");
 
+const { offerKeybindingFix } =
+  await import("@pi-archimedes/image-paste/keybinding-offer");
+
 // ── Stub pi: record pi.on() registrations and command/tool registrations ───
 
 interface PiHarness {
@@ -125,6 +132,12 @@ function freshFactory(): {
   harness: PiHarness;
   startSession: (ctx: unknown) => Promise<unknown>;
   shutdownSession: () => unknown;
+  /** Fire EVERY registered session_start handler in registration order. */
+  fireAllStartHandlers: (ctx: unknown) => Promise<void>;
+  /** Fire ONLY the keybinding-offer session_start handler (the one registered
+   *  before the lazy-load handler). Useful for isolating offer behaviour
+   *  without triggering the heavy dynamic-import path. */
+  fireOfferHandler: (ctx: unknown) => void;
 } {
   const harness = makePi();
   metaFactory(harness.pi);
@@ -133,13 +146,26 @@ function freshFactory(): {
   const shutdownRcs = harness.handlers["session_shutdown"] ?? [];
   expect(startRcs.length).toBeGreaterThan(0);
   expect(shutdownRcs.length).toBeGreaterThan(0);
+  // The LAST session_start handler is the lazy-load one (existing tests rely on this).
   const startRc = (startRcs[startRcs.length - 1] ?? expect.fail("no session_start handler")) as (...args: unknown[]) => unknown;
   const shutdownRc = (shutdownRcs[shutdownRcs.length - 1] ?? expect.fail("no session_shutdown handler")) as (...args: unknown[]) => unknown;
+  // The keybinding-offer handler is at index 0 in this fully-mocked harness —
+  // all earlier package registrations are stubbed to no-op vi.fn(); if a
+  // package is un-mocked here, update the index.
+  const offerRc = (startRcs[0] ?? expect.fail("no offer session_start handler")) as (...args: unknown[]) => unknown;
 
   return {
     harness,
     startSession: (ctx: unknown) => startRc(undefined, ctx) as Promise<unknown>,
     shutdownSession: () => shutdownRc(undefined, {}),
+    fireAllStartHandlers: async (ctx: unknown) => {
+      for (const handler of startRcs) {
+        await (handler(undefined, ctx) as Promise<unknown>);
+      }
+    },
+    fireOfferHandler: (ctx: unknown) => {
+      offerRc(undefined, ctx);
+    },
   };
 }
 
@@ -194,3 +220,41 @@ describe("image-paste factory lifecycle (registration is config-gated, teardown
     expect(vi.mocked(shutdownImagePaste)).toHaveBeenCalledTimes(1); // exactly once total
   });
 });
+
+describe("keybinding-offer wiring (session_start → offerKeybindingFix, fire-and-forget)", () => {
+  it("calls offerKeybindingFix exactly once with the session ctx", () => {
+    const ctx = { ui: { theme: "dark" } };
+    // Return a resolved promise so the handler's .catch() has nothing to report.
+    vi.mocked(offerKeybindingFix).mockResolvedValueOnce(undefined);
+    const { fireOfferHandler } = freshFactory();
+
+    // The offer handler is synchronous from the caller's perspective (fire-and-forget).
+    fireOfferHandler(ctx);
+
+    expect(vi.mocked(offerKeybindingFix)).toHaveBeenCalledTimes(1);
+    expect(vi.mocked(offerKeybindingFix)).toHaveBeenCalledWith(ctx);
+  });
+
+  it("session_start resolves even when offerKeybindingFix rejects (fire-and-forget safety)", async () => {
+    // Arrange: make the mock reject once to simulate an unexpected failure.
+    vi.mocked(offerKeybindingFix).mockRejectedValueOnce(new Error("boom"));
+    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    const ctx = { ui: { theme: "dark" } };
+    const { fireOfferHandler } = freshFactory();
+
+    // Act: invoke the offer handler; it must not throw synchronously.
+    expect(() => fireOfferHandler(ctx)).not.toThrow();
+
+    // Drain the microtask queue so the .catch() branch has had time to run.
+    await new Promise((r) => setTimeout(r, 0));
+
+    // The rejection must have been swallowed and logged — not re-thrown.
+    expect(consoleSpy).toHaveBeenCalledWith(
+      "[archimedes] keybinding offer failed:",
+      expect.any(Error),
+    );
+
+    consoleSpy.mockRestore();
+  });
+});

package/src/index.ts

@@ -14,6 +14,10 @@ import { isPluginEnabled, migrateLegacyPluginsMap } from "./plugins.js";
 import { registerNotify } from "@pi-archimedes/notify";
 import { registerSessionName } from "@pi-archimedes/session-name";
 import { registerSudo } from "@pi-archimedes/sudo";
+// Light module from the image-paste package (no heavy deps) — the offer
+// gates are self-contained, so it is statically imported and runs in its
+// own top-level session_start handler, independent of the lazy-load.
+import { offerKeybindingFix } from "@pi-archimedes/image-paste/keybinding-offer";
 import { loadDiffConfig } from "./config.js";
 import { openSettings } from "./settings.js"
 import { registerPluginsCommand } from "./plugin-manager.js"
@@ -75,6 +79,32 @@ export default function (pi: ExtensionAPI): void {
     archPrintTimings();
   });
 
+  // First-run keybinding offer (see the module doc in
+  // packages/image-paste/src/keybinding-offer.ts). Registered at top level
+  // (AGENTS.md), and placed BEFORE the lazy-load handler below: the
+  // module's own gates (config enabled → TUI → flag unset → file absent
+  // → confirm) are self-contained, so ordering with that handler is not a
+  // correctness issue.
+  //
+  // Deliberately NOT gated with isPluginEnabled("image-paste"): that call
+  // resolves to isConfigEnabled("archimedes.imagePaste") (ADR 0012), which
+  // is exactly the same key the module's own gate 1 already checks — adding
+  // a wrapper here would be a redundant duplicate of the identical check.
+  // This handler runs unconditionally on every session_start; the module's
+  // five gates make it a no-op when not applicable.
+  pi.on("session_start", (_event, ctx: ExtensionContext) => {
+    // Fire-and-forget: the offer is async (it may block on a user
+    // confirm) and must never block or take down session startup — any
+    // throw is logged, never propagated.
+    try {
+      void offerKeybindingFix(ctx).catch((e) => {
+        console.error("[archimedes] keybinding offer failed:", e);
+      });
+    } catch (e) {
+      console.error("[archimedes] keybinding offer failed:", e);
+    }
+  });
+
   pi.on("session_start", async (_event, ctx: ExtensionContext) => {
     archTime(`session_start (factory was ${Date.now() - _moduleEvalAt}ms ago)`);