@intentic/extension-api 1.325.0 → 1.327.0

package/dist/testing.js

@@ -0,0 +1,152 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { extensionRouteReach } from "@intentic/extension-manifest/permissions";
+import { extensionEventsUrl, extensionSettingsUrl } from "@intentic/sandbox-contract/extension-protocol";
+import { EXTENSION_TOKEN_HEADER } from "@intentic/sandbox-contract/headers";
+import { activateServerModule, createServerApi, deactivateWithin, healthWithin } from "./runtime.js";
+const DAEMON = "http://daemon.fake";
+const TOKEN = "fake-extension-token";
+const json = (body, status = 200) => Response.json(body, { status });
+const changedKeys = (before, after) => [...new Set([...Object.keys(before), ...Object.keys(after)])].filter((key) => before[key] !== after[key]).toSorted();
+export const fakeExtensionApi = async (options) => {
+    const made = [];
+    const dirOf = async (given, label) => {
+        if (given !== undefined) {
+            return given;
+        }
+        const dir = await mkdtemp(join(tmpdir(), `fake-extension-${label}-`));
+        made.push(dir);
+        return dir;
+    };
+    const workspaceRoot = await dirOf(options.workspaceRoot, "workspace");
+    const id = `${options.manifest.publisher}.${options.manifest.name}`;
+    const reach = { permissions: options.manifest.permissions?.daemon ?? [], listener: options.manifest.contributes?.listener?.provider };
+    const calls = [];
+    const logs = [];
+    let settings = { ...options.settings };
+    const streams = new Set();
+    const pending = [];
+    const encoder = new TextEncoder();
+    const write = (stream, event) => {
+        try {
+            stream.enqueue(encoder.encode(`${JSON.stringify(event)}\n`));
+        }
+        catch {
+            streams.delete(stream);
+        }
+    };
+    const send = (event) => {
+        if (streams.size === 0) {
+            pending.push(event);
+            return;
+        }
+        for (const stream of streams) {
+            write(stream, event);
+        }
+    };
+    const eventStream = (signal) => {
+        let held;
+        const body = new ReadableStream({
+            start: (controller) => {
+                held = controller;
+                streams.add(controller);
+                write(controller, { kind: "heartbeat" });
+                for (const event of pending.splice(0)) {
+                    write(controller, event);
+                }
+            },
+            cancel: () => {
+                if (held !== undefined) {
+                    streams.delete(held);
+                }
+            },
+        });
+        signal?.addEventListener("abort", () => {
+            if (held !== undefined) {
+                streams.delete(held);
+            }
+        });
+        return new Response(body, { headers: { "content-type": "application/x-ndjson" } });
+    };
+    const daemon = async (input, init) => {
+        const request = new Request(input, init);
+        const url = new URL(request.url);
+        const line = `${request.method} ${url.pathname}`;
+        if (request.headers.get(EXTENSION_TOKEN_HEADER) !== TOKEN) {
+            calls.push({ line, admitted: false });
+            return json({ error: "unauthorized" }, 401);
+        }
+        const admitted = extensionRouteReach(reach, request.method, url.pathname);
+        calls.push({ line, admitted });
+        if (!admitted) {
+            return json({ error: "extension token not valid for this route" }, 403);
+        }
+        if (request.method === "GET" && url.pathname === extensionSettingsUrl()) {
+            return json({ settings });
+        }
+        if (request.method === "GET" && url.pathname === extensionEventsUrl()) {
+            return eventStream(init?.signal ?? null);
+        }
+        return (await options.daemon?.(request)) ?? json({ error: "not found" }, 404);
+    };
+    const slots = createServerApi({
+        id,
+        daemonUrl: DAEMON,
+        token: TOKEN,
+        permissions: reach.permissions,
+        workspaceRoot,
+        extensionDir: await dirOf(options.extensionDir, "checkout"),
+        stateDir: await dirOf(options.stateDir, "state"),
+        cacheDir: await dirOf(options.cacheDir, "cache"),
+        log: (message) => logs.push(message),
+        fetch: daemon,
+    });
+    let activation = {};
+    return {
+        api: slots.api,
+        calls,
+        logs,
+        activate: async (module) => {
+            activation = await activateServerModule(module, slots.api, { extensionId: id });
+        },
+        route: async (path, init) => {
+            const handler = slots.handler();
+            if (handler === undefined) {
+                return json({ error: `the "${id}" backend serves no routes` }, 404);
+            }
+            return (await handler(new Request(new URL(path, "http://extension.internal"), init))) ?? json({ error: "not found" }, 404);
+        },
+        tools: async (card) => (await slots.tools()?.(card)) ?? [],
+        callTool: async (name, args = {}, card, context = {}) => {
+            const tool = ((await slots.tools()?.(card)) ?? []).find((each) => each.name === name);
+            if (tool === undefined) {
+                throw new Error(`"${id}" serves no tool named ${name}${card === undefined ? "" : ` for card ${card.id}`}`);
+            }
+            return tool.call(args, { signal: context.signal ?? new AbortController().signal, conversationId: context.conversationId });
+        },
+        setSettings: (values) => {
+            const keys = changedKeys(settings, values);
+            settings = { ...values };
+            if (keys.length > 0) {
+                send({ kind: "settings", keys });
+            }
+        },
+        emit: send,
+        health: () => healthWithin(activation),
+        deactivate: () => deactivateWithin(activation, (message) => logs.push(message)),
+        dispose: async () => {
+            slots.close();
+            for (const stream of streams) {
+                try {
+                    stream.close();
+                }
+                catch {
+                }
+            }
+            streams.clear();
+            await Promise.all(made.map((dir) => rm(dir, { recursive: true, force: true })));
+        },
+    };
+};
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const extensionApiVersion = "2.23.0";
+export declare const extensionApiVersion = "2.26.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAkJA,eAAO,MAAM,mBAAmB,WAAW,CAAC"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAwKA,eAAO,MAAM,mBAAmB,WAAW,CAAC"}

package/dist/version.js

@@ -1,2 +1,2 @@
-export const extensionApiVersion = "2.23.0";
+export const extensionApiVersion = "2.26.0";
 //# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAkJA,MAAM,CAAC,MAAM,mBAAmB,GAAG,QAAQ,CAAC"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAwKA,MAAM,CAAC,MAAM,mBAAmB,GAAG,QAAQ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentic/extension-api",
-  "version": "1.325.0",
+  "version": "1.327.0",
   "description": "The versioned public API intentic extensions compile against, manifest schema, detection facts and the host API",
   "license": "MIT",
   "type": "module",
@@ -39,24 +39,60 @@
         "@intentic/src": "./src/protocol.ts",
         "default": "./dist/protocol.js"
       }
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "import": {
+        "@intentic/src": "./src/runtime.ts",
+        "default": "./dist/runtime.js"
+      },
+      "require": {
+        "@intentic/src": "./src/runtime.ts",
+        "default": "./dist/runtime.js"
+      }
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": {
+        "@intentic/src": "./src/testing.ts",
+        "default": "./dist/testing.js"
+      },
+      "require": {
+        "@intentic/src": "./src/testing.ts",
+        "default": "./dist/testing.js"
+      }
     }
   },
   "dependencies": {
-    "@intentic/sandbox-contract": "1.325.0",
+    "@intentic/base": "1.327.0",
+    "@intentic/extension-manifest": "1.327.0",
+    "@intentic/sandbox-contract": "1.327.0",
+    "@orpc/client": "1.15.4",
     "@orpc/contract": "1.15.4",
+    "@orpc/openapi-client": "1.15.4",
     "tslib": "2.8.1"
   },
   "peerDependencies": {
     "vue": "3"
   },
+  "peerDependenciesMeta": {
+    "vue": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@intentic/testing": "0.0.0",
     "@intentic/tsconfig": "0.0.0",
-    "@types/node": "24.13.6",
+    "@types/bun": "1.4.2",
+    "@types/node": "24.19.1",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
-    "vue": "3.5.43"
+    "vue": "3.5.43",
+    "zod": "4.6.5"
   },
   "scripts": {
     "build": "tsgo",
-    "watch": "tsgo --build --watch"
+    "watch": "tsgo --build --watch",
+    "typecheck": "tsgo --noEmit -p tsconfig.test.json",
+    "test": "suites"
   }
 }

package/src/api.ts

@@ -2,14 +2,13 @@ import type { sandboxContract } from "@intentic/sandbox-contract";
 import type { ContractRouterClient } from "@orpc/contract";
 import type { Component } from "vue";
 import type { DiffPayload } from "./diff.js";
+import type { Disposable } from "./disposable.js";
 import type { CapabilityFacts, RepoFacts } from "./facts.js";
 
 // The host API an extension programs against; there is no ambient global. Arrives as
 // activate(api, context); everything registered returns a Disposable pushed onto context.subscriptions.
 
-export interface Disposable {
-    dispose(): void;
-}
+export type { Disposable } from "./disposable.js";
 
 // One sidebar element a view contributes, routed at /ext/<viewId>/<key> and rendered by the view's
 // component with `repo` (+ props) bound.

package/src/background.ts

@@ -1,10 +1,8 @@
 import {
     at,
-    type Conversion,
     drop,
     dropAll,
     fold,
-    type Granularity,
     mapValue,
     nested,
     pinDefault,
@@ -16,6 +14,7 @@ import {
 } from "@intentic/sandbox-contract/documents";
 import type { Ref } from "vue";
 import type { Disposable, IntenticApi } from "./api.js";
+import type { ServerDocumentOptions, StoredJson } from "./server.js";
 import { sandboxRef, sandboxScopeGuard } from "./scope.js";
 
 // Sandbox-scoped background polling for a badge that needs an answer before its tile opens: state lives at module
@@ -249,15 +248,8 @@ export interface SandboxDocument<T> {
     update(change: (current: T) => T): Promise<boolean>;
 }
 
-export interface SandboxDocumentOptions<T> {
-    // Today's shape, or undefined for a file this version cannot read.
-    readonly parse: (raw: unknown) => T | undefined;
-    readonly fallback: () => T;
-    // Append-only: a conversion is never edited or removed once shipped, only followed by another.
-    readonly history?: readonly Conversion[];
-    // Where the conversions apply: the document, each entry of a top-level array, or each value of an object keyed by id.
-    readonly granularity?: Granularity;
-}
+// The same options a backend's `api.document` takes (server.ts): one file's shape, however the extension reaches it.
+export type SandboxDocumentOptions<T> = ServerDocumentOptions<T>;
 
 // Every handle on one path queues behind the others, not just behind itself: two handles opened on the same file (two
 // panels, a panel and a command) would otherwise each read, change and write, and the second write would drop the first.
@@ -270,7 +262,8 @@ export const sandboxDocument = <T>(host: () => IntenticApi, path: string, option
     const readAs = async () => {
         // Through the contract's own read, which throws for a refused or unreachable read where `readJson` answers absent.
         const answer = await host().sandbox.rpc.workspace.file({ path });
-        return answer.present ? readDocument<T>(answer.content, shape, { kind: `whole`, parse: (raw) => options.parse(raw) }) : undefined;
+        // SAFETY: readDocument hands its parse what JSON.parse produced and the conversions rewrote, which is JSON.
+        return answer.present ? readDocument<T>(answer.content, shape, { kind: `whole`, parse: (raw) => options.parse(raw as StoredJson) }) : undefined;
     };
     const read = async (): Promise<T> => {
         try {

package/src/diff.ts

@@ -1,12 +1,12 @@
-import type { PartialFileDiff } from "@intentic/sandbox-contract";
+import type { ChangeStatus, PartialFileDiff } from "@intentic/sandbox-contract";
 
 // The argument to `api.workspace.openDiff`: the extension says what changed, the host owns the tab, viewer and
 // dirty-buffer bookkeeping. Lives in the public api package because the app's own review surfaces build the identical
 // payload.
 
-// Git's vocabulary for what happened to a file; the host renders each as its own letter and colour. "conflicted" is
-// git's unmerged state (`U`), not a kind of modification.
-export type ChangeStatus = "added" | "modified" | "deleted" | "renamed" | "type-changed" | "conflicted";
+// Git's vocabulary for what happened to a file (the contract's ChangeStatusSchema); the host renders each as its own
+// letter and colour. "conflicted" is git's unmerged state (`U`), not a kind of modification.
+export type { ChangeStatus };
 
 // A binary diff ships its two sides as daemon URLs to fetch bytes from, not as content. An absent side means that side
 // does not exist; the viewer gives the pane entirely to the side that does.

package/src/disposable.ts

@@ -0,0 +1,5 @@
+// What every registration hands back, in both halves of the api. A leaf of its own so the backend half (server.ts) reaches
+// it without the browser half's types, which name Vue's.
+export interface Disposable {
+    dispose(): void;
+}

package/src/runtime.integration.test.ts

@@ -0,0 +1,159 @@
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { rename } from "@intentic/sandbox-contract/documents";
+import { waitFor } from "@intentic/testing/bun";
+import { z } from "zod";
+import { connectExtensionProcess } from "./runtime.js";
+import type { ExtensionServerApi, ServerActivation, StoredJson } from "./server.js";
+import { type FakeExtension, fakeExtensionApi } from "./testing.js";
+
+// The backend api as a server bundle and a process both get it (runtime.ts), driven through the SDK's own fake daemon
+// (testing.ts), which judges every call by the reach rule the daemon's grant applies.
+
+const opened: FakeExtension[] = [];
+const fake = async (options: Parameters<typeof fakeExtensionApi>[0]): Promise<FakeExtension> => {
+    const made = await fakeExtensionApi(options);
+    opened.push(made);
+    return made;
+};
+afterEach(async () => {
+    await Promise.all(opened.splice(0).map((each) => each.dispose()));
+});
+
+const manifest = { publisher: "acme", name: "probe", permissions: { daemon: ["GET /ports"] } };
+
+test("a call the manifest declares reaches the daemon, and one it does not is refused there", async () => {
+    const extension = await fake({ manifest, daemon: () => Response.json({ ports: [] }) });
+    expect((await extension.api.daemon.request("/ports")).status).toBe(200);
+    expect((await extension.api.daemon.request("/agents")).status).toBe(403);
+    expect(extension.calls).toEqual([
+        { line: "GET /ports", admitted: true },
+        { line: "GET /agents", admitted: false },
+    ]);
+});
+
+test("a typed call outside permissions.daemon is refused before anything is sent", async () => {
+    const extension = await fake({ manifest });
+    await expect(extension.api.daemon.rpc.extensions.settings({ id: "acme.probe" })).rejects.toThrow(/declare it in permissions\.daemon/);
+    expect(extension.calls).toEqual([]);
+});
+
+test("its own settings and event stream need no declaration, and a change names the keys that moved", async () => {
+    const extension = await fake({ manifest: { publisher: "acme", name: "quiet" }, settings: { engine: "browser", autoStart: false } });
+    expect(await extension.api.settings.get()).toEqual({ engine: "browser", autoStart: false });
+    const heard: (readonly string[])[] = [];
+    const subscription = extension.api.settings.onDidChange((keys) => heard.push(keys));
+    extension.setSettings({ engine: "server", autoStart: false });
+    await waitFor(() => expect(heard).toHaveLength(1));
+    expect(heard).toEqual([["engine"]]);
+    expect(await extension.api.settings.get()).toEqual({ engine: "server", autoStart: false });
+    subscription.dispose();
+    expect(extension.calls.every((call) => call.admitted)).toBe(true);
+});
+
+test("workspace changes arrive as the daemon frames them, and a listener that throws does not stop the rest", async () => {
+    const extension = await fake({ manifest });
+    const files: (readonly string[])[] = [];
+    const refs: (readonly string[])[] = [];
+    extension.api.workspace.onDidChangeFiles(() => {
+        throw new Error("boom");
+    });
+    extension.api.workspace.onDidChangeFiles((paths) => files.push(paths));
+    extension.api.workspace.onDidChangeRefs((repos) => refs.push(repos));
+    extension.emit({ kind: "files", paths: ["src/a.ts"] });
+    extension.emit({ kind: "refs", repos: ["app"] });
+    await waitFor(() => {
+        expect(files).toHaveLength(1);
+        expect(refs).toHaveLength(1);
+    });
+    expect(files).toEqual([["src/a.ts"]]);
+    expect(refs).toEqual([["app"]]);
+    expect(extension.logs.some((line) => line.includes("a files listener threw: boom"))).toBe(true);
+});
+
+const MarksSchema = z.object({ lastUid: z.number() });
+type Marks = z.infer<typeof MarksSchema>;
+const parseMarks = (raw: StoredJson): Marks | undefined => MarksSchema.safeParse(raw).data;
+
+test("a document reads an older shape through its conversions and keeps what a newer version wrote", async () => {
+    const extension = await fake({ manifest });
+    const file = join(extension.api.stateDir, "marks.json");
+    await writeFile(file, JSON.stringify({ uid: 7, addedLater: "kept" }));
+    const marks = extension.api.document("marks.json", { parse: parseMarks, fallback: () => ({ lastUid: 0 }), history: [rename("uid", "lastUid")] });
+    expect(await marks.read()).toEqual({ lastUid: 7 });
+    expect(await marks.update((current) => ({ lastUid: current.lastUid + 1 }))).toEqual({ lastUid: 8 });
+    expect(JSON.parse(await readFile(file, "utf8"))).toEqual({ lastUid: 8, addedLater: "kept" });
+});
+
+test("a document this version cannot read is left as it is rather than written over", async () => {
+    const extension = await fake({ manifest });
+    const file = join(extension.api.stateDir, "marks.json");
+    await writeFile(file, "not json");
+    const marks = extension.api.document("marks.json", { parse: parseMarks, fallback: () => ({ lastUid: 0 }) });
+    expect(await marks.read()).toEqual({ lastUid: 0 });
+    await expect(marks.update(() => ({ lastUid: 1 }))).rejects.toThrow(/cannot read/);
+    expect(await readFile(file, "utf8")).toBe("not json");
+    expect(() => extension.api.document("../escape.json", { parse: parseMarks, fallback: () => ({ lastUid: 0 }) })).toThrow(/inside the extension's state directory/);
+});
+
+test("a server module is activated, served and wound down the way the backend host does it", async () => {
+    const extension = await fake({ manifest });
+    let deactivated = false;
+    await extension.activate({
+        activateServer: (api: ExtensionServerApi): ServerActivation => {
+            api.routes.mount(async (request) => (new URL(request.url).pathname === "/hello" ? Response.json({ hello: api.stateDir !== "" }) : undefined));
+            api.tools.serve(() => [{ name: "echo", description: "echoes", inputSchema: { type: "object" }, effect: "read", call: (args) => args["text"] }]);
+            return {
+                deactivate: () => {
+                    deactivated = true;
+                },
+                health: () => ({ state: "degraded", detail: "the mailbox is not answering" }),
+            };
+        },
+    });
+    expect(await (await extension.route("/hello")).json()).toEqual({ hello: true });
+    expect((await extension.route("/missing")).status).toBe(404);
+    expect((await extension.tools()).map((tool) => tool.name)).toEqual(["echo"]);
+    expect(await extension.callTool("echo", { text: "hi" })).toBe("hi");
+    expect(await extension.health()).toEqual({ state: "degraded", detail: "the mailbox is not answering" });
+    await extension.deactivate();
+    expect(deactivated).toBe(true);
+});
+
+test("a health check that answers outside the vocabulary reads as degraded, saying so", async () => {
+    const extension = await fake({ manifest });
+    // SAFETY: an answer outside the vocabulary is the case under test, which the type would otherwise refuse to state.
+    await extension.activate({ activateServer: () => ({ health: () => ({ state: "fine" }) as never }) });
+    expect(await extension.health()).toEqual({ state: "degraded", detail: "its health check answered something other than ok, starting, degraded or failed" });
+});
+
+test("a process started without the daemon's environment says which variable is missing", async () => {
+    expect(() => connectExtensionProcess({})).toThrow(/missing INTENTIC_EXTENSION_ID/);
+    const root = await mkdtemp(join(tmpdir(), "process-env-"));
+    try {
+        const connected = connectExtensionProcess({
+            INTENTIC_EXTENSION_ID: "acme.probe",
+            INTENTIC_DAEMON: "http://127.0.0.1:1",
+            INTENTIC_EXTENSION_TOKEN: "t",
+            INTENTIC_WORKSPACE: root,
+            INTENTIC_EXTENSION_STATE: join(root, "state"),
+            INTENTIC_EXTENSION_CACHE: join(root, "cache"),
+            INTENTIC_EXTENSION_PERMISSIONS: JSON.stringify(["GET /ports"]),
+        });
+        expect(connected.api.stateDir).toBe(join(root, "state"));
+        expect(connected.api.workspaceRoot).toBe(root);
+        connected.close();
+        const env = {
+            INTENTIC_EXTENSION_ID: "acme.probe",
+            INTENTIC_DAEMON: "http://127.0.0.1:1",
+            INTENTIC_EXTENSION_TOKEN: "t",
+            INTENTIC_WORKSPACE: root,
+            INTENTIC_EXTENSION_STATE: root,
+            INTENTIC_EXTENSION_CACHE: root,
+        };
+        expect(() => connectExtensionProcess({ ...env, INTENTIC_EXTENSION_PERMISSIONS: "{}" })).toThrow(/not a JSON array/);
+    } finally {
+        await rm(root, { recursive: true, force: true });
+    }
+});