@cueloop/extension-api 0.1.0-alpha.2 → 0.1.0-alpha.21

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@cueloop/extension-api",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.21",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@cueloop/schema": "0.1.0-alpha.2"
+    "@cueloop/schema": "0.1.0-alpha.21"
   },
   "publishConfig": {
     "access": "public"
@@ -23,5 +23,10 @@
     "type": "git",
     "url": "git+https://github.com/mmurakaru/cueloop.git",
     "directory": "packages/extension-api"
-  }
-}
+  },
+  "homepage": "https://github.com/mmurakaru/cueloop#readme",
+  "bugs": {
+    "url": "https://github.com/mmurakaru/cueloop/issues"
+  },
+  "description": "The typed contract for extending cueloop: renderers, commands, keybindings, exporters"
+}

package/src/index.ts

@@ -1,3 +1,2 @@
 export * from "./types";
 export * from "./registry";
-export * from "./loader";

package/src/registry.test.ts

@@ -1,98 +1,30 @@
 import { describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
 import { Registry } from "./registry";
-import { loadExtensions, readTrust } from "./loader";
 import type { ReviewSession } from "@cueloop/schema";
 
 const SESSION = { id: "ses_x", annotations: [] } as unknown as ReviewSession;
 
 describe("Registry", () => {
-  test("captures registrations per extension; first wins", async () => {
-    const reg = new Registry();
-    await reg.load("builtin", (api) => {
-      api.registerRenderer("plan", () => [[{ text: "builtin" }]]);
+  test("captures each extension's exporters, attributed by name", async () => {
+    const registry = new Registry();
+    await registry.load("obsidian", (api) => {
+      api.registerExporter("obsidian", async () => ({ success: true, path: "/vault/note.md" }));
     });
-    await reg.load("third-party", (api) => {
-      api.registerRenderer("plan", () => [[{ text: "override-attempt" }]]);
-      api.registerRenderer("svg", () => [[{ text: "svg" }]]);
+    await registry.load("bear", (api) => {
+      api.registerExporter("bear", async () => ({ success: true }));
     });
-    expect(reg.rendererFor("plan")!({ content: "", meta: {} }, 80)[0]![0]!.text).toBe("builtin");
-    expect(reg.rendererFor("svg")).toBeDefined();
+    expect(registry.extensions.map((extension) => extension.name)).toEqual(["obsidian", "bear"]);
+    const obsidian = registry.extensions[0]!.exporters.get("obsidian")!;
+    expect(await obsidian(SESSION)).toEqual({ success: true, path: "/vault/note.md" });
   });
 
   test("a throwing factory is contained, not fatal", async () => {
-    const reg = new Registry();
-    const record = await reg.load("broken", () => {
+    const registry = new Registry();
+    const record = await registry.load("broken", () => {
       throw new Error("boom");
     });
     expect(record.errors).toEqual(["boom"]);
-    expect(reg.extensions.length).toBe(1);
-  });
-
-  test("reserved keybindings are rejected with attribution", async () => {
-    const reg = new Registry();
-    const record = await reg.load("greedy", (api) => {
-      api.registerKeybinding({ action: "steal", defaultKeys: ["j"], handler: () => {} });
-      api.registerKeybinding({ action: "fine", defaultKeys: ["F5"], handler: () => {} });
-    });
-    expect(record.keybindings.length).toBe(1);
-    expect(record.errors[0]).toContain('"j" is reserved');
-  });
-
-  test("observers never cancel and never crash the host", async () => {
-    const reg = new Registry();
-    const seen: string[] = [];
-    await reg.load("observer", (api) => {
-      api.on("session.resolved", () => {
-        throw new Error("observer bug");
-      });
-      api.on("session.resolved", (s) => seen.push(s.id));
-    });
-    reg.emit("session.resolved", SESSION);
-    expect(seen).toEqual(["ses_x"]);
-  });
-});
-
-describe("loadExtensions", () => {
-  test("loads user extensions; repo extensions gated by trust", async () => {
-    const dir = mkdtempSync(join(tmpdir(), "cueloop-ext-"));
-    const userDir = join(dir, "user-ext");
-    const repoRoot = join(dir, "repo");
-    const home = join(dir, "home");
-    mkdirSync(userDir, { recursive: true });
-    mkdirSync(join(repoRoot, ".cueloop", "extensions"), { recursive: true });
-    writeFileSync(
-      join(userDir, "hello.ts"),
-      `export default (api) => { api.registerCommand("hello", { description: "hi", handler() {} }); };`,
-    );
-    writeFileSync(
-      join(repoRoot, ".cueloop", "extensions", "repo-ext.ts"),
-      `export default (api) => { api.registerCommand("repo", { description: "r", handler() {} }); };`,
-    );
-    try {
-      // untrusted repo: user loads, repo skipped
-      const reg1 = new Registry();
-      const r1 = await loadExtensions({ registry: reg1, userDir, repoRoot, home });
-      expect(r1.loaded.length).toBe(1);
-      expect(r1.skipped.length).toBe(1);
-      expect(reg1.commandFor("hello")).toBeDefined();
-      expect(reg1.commandFor("repo")).toBeUndefined();
-
-      // trust granted through the resolver: repo loads and persists
-      const reg2 = new Registry();
-      const r2 = await loadExtensions({ registry: reg2, userDir, repoRoot, home, confirmTrust: async () => true });
-      expect(r2.loaded.length).toBe(2);
-      expect(reg2.commandFor("repo")).toBeDefined();
-      expect(readTrust(home).trusted).toContain(repoRoot);
-
-      // persisted: no resolver needed next time
-      const reg3 = new Registry();
-      const r3 = await loadExtensions({ registry: reg3, userDir, repoRoot, home });
-      expect(r3.loaded.length).toBe(2);
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
+    expect(record.exporters.size).toBe(0);
+    expect(registry.extensions.length).toBe(1);
   });
 });

package/src/registry.ts

@@ -1,28 +1,14 @@
 /**
- * The contribution registry (#10): registrations are plain data, attributed
- * per extension. Reserved app keybindings are rejected at registration so a
- * broken extension cannot shadow core grammar.
+ * The contribution registry: an extension factory runs against a captured
+ * API, and its exporter registrations land as plain data attributed to that
+ * extension. One broken extension never takes the host down.
  */
 
-import type {
-  ArtifactRenderer,
-  CommandRegistration,
-  Exporter,
-  ExtensionAPI,
-  ExtensionFactory,
-  KeybindingRegistration,
-} from "./types";
-import type { ReviewSession } from "@cueloop/schema";
-
-const RESERVED_KEYS = new Set(["j", "k", "g", "G", "v", "c", "s", "x", "e", "n", "p", "q", "return", "escape", "backspace"]);
+import type { Exporter, ExtensionAPI, ExtensionFactory } from "./types";
 
 export interface ExtensionRecord {
   name: string;
-  renderers: Map<string, ArtifactRenderer>;
-  commands: Map<string, CommandRegistration>;
-  keybindings: KeybindingRegistration[];
   exporters: Map<string, Exporter>;
-  listeners: Map<string, ((session: ReviewSession) => void)[]>;
   errors: string[];
 }
 
@@ -31,75 +17,18 @@ export class Registry {
 
   /** Run one extension factory, capturing its registrations. */
   async load(name: string, factory: ExtensionFactory): Promise<ExtensionRecord> {
-    const record: ExtensionRecord = {
-      name,
-      renderers: new Map(),
-      commands: new Map(),
-      keybindings: [],
-      exporters: new Map(),
-      listeners: new Map(),
-      errors: [],
-    };
+    const record: ExtensionRecord = { name, exporters: new Map(), errors: [] };
     const api: ExtensionAPI = {
-      registerRenderer(type, renderer) {
-        record.renderers.set(type, renderer);
-      },
-      registerCommand(cmdName, registration) {
-        record.commands.set(cmdName, registration);
-      },
-      registerKeybinding(registration) {
-        const clash = registration.defaultKeys.find((k) => RESERVED_KEYS.has(k));
-        if (clash) {
-          record.errors.push(`keybinding "${registration.action}" rejected: "${clash}" is reserved`);
-          return;
-        }
-        record.keybindings.push(registration);
-      },
-      registerExporter(expName, exporter) {
-        record.exporters.set(expName, exporter);
-      },
-      on(event, handler) {
-        const list = record.listeners.get(event) ?? [];
-        list.push(handler);
-        record.listeners.set(event, list);
+      registerExporter(exporterName, exporter) {
+        record.exporters.set(exporterName, exporter);
       },
     };
     try {
       await factory(api);
     } catch (err) {
-      // one broken extension never takes the app down
       record.errors.push(err instanceof Error ? err.message : String(err));
     }
     this.extensions.push(record);
     return record;
   }
-
-  /** First-registered wins for renderers/commands; built-ins load first. */
-  rendererFor(artifactType: string): ArtifactRenderer | undefined {
-    for (const ext of this.extensions) {
-      const r = ext.renderers.get(artifactType);
-      if (r) return r;
-    }
-    return undefined;
-  }
-
-  commandFor(name: string): { extension: string; registration: CommandRegistration } | undefined {
-    for (const ext of this.extensions) {
-      const c = ext.commands.get(name);
-      if (c) return { extension: ext.name, registration: c };
-    }
-    return undefined;
-  }
-
-  emit(event: string, session: ReviewSession): void {
-    for (const ext of this.extensions) {
-      for (const handler of ext.listeners.get(event) ?? []) {
-        try {
-          handler(session);
-        } catch {
-          // observers never cancel and never crash the host
-        }
-      }
-    }
-  }
 }

package/src/types.ts

@@ -1,58 +1,20 @@
 /**
- * The single typed extension contract (#10). This module is import-free
- * beyond the schema: whatever a declaration file can reach gets published,
- * so the contract stays self-contained.
+ * The typed extension contract. Import-free beyond the schema, so the
+ * contract stays self-contained.
  *
- * An extension is a factory:
- *   export default (cueloop: ExtensionAPI) => { cueloop.registerCommand(...) }
- * Registration is data written into a per-extension record; action methods
- * are late-bound by the host. No import-time side effects.
+ * An extension is a factory that registers an exporter:
+ *   export default (cueloop: ExtensionAPI) => { cueloop.registerExporter(...) }
+ * Registration is data written into a per-extension record; the exporter runs
+ * later, host-driven. No import-time side effects.
  */
 
-import type { Annotation, ReviewSession, VerdictKind } from "@cueloop/schema";
-
-/** A renderable line: styled runs the host paints into the terminal grid. */
-export interface UiRun {
-  text: string;
-  fg?: string;
-  bg?: string;
-}
-
-export type UiLine = UiRun[];
-
-/** Renderers project an artifact type into lines at a given width. */
-export type ArtifactRenderer = (artifact: { content: string; meta: Record<string, unknown> }, width: number) => UiLine[];
-
-export interface CommandContext {
-  session: ReviewSession | null;
-  annotate(annotation: Omit<Annotation, "createdAt">): Promise<void>;
-  resolve(verdict: VerdictKind, summary: string): Promise<void>;
-  notify(message: string): void;
-}
-
-export interface CommandRegistration {
-  description: string;
-  handler(ctx: CommandContext, args: string): void | Promise<void>;
-}
-
-export interface KeybindingRegistration {
-  /** Action name; binds through the same [keys] config as built-ins. */
-  action: string;
-  defaultKeys: string[];
-  handler(ctx: CommandContext): void | Promise<void>;
-}
+import type { ReviewSession } from "@cueloop/schema";
 
 /** Exporters ship resolved sessions somewhere (notes vaults, forges). */
 export type Exporter = (session: ReviewSession) => Promise<{ success: boolean; path?: string; error?: string }>;
 
 export interface ExtensionAPI {
-  /** Renderers for artifact types; built-ins register through this too. */
-  registerRenderer(artifactType: string, renderer: ArtifactRenderer): void;
-  registerCommand(name: string, registration: CommandRegistration): void;
-  registerKeybinding(registration: KeybindingRegistration): void;
   registerExporter(name: string, exporter: Exporter): void;
-  /** Observe session lifecycle; fold semantics: observers never cancel. */
-  on(event: "session.created" | "session.resolved" | "session.updated", handler: (session: ReviewSession) => void): void;
 }
 
 export type ExtensionFactory = (cueloop: ExtensionAPI) => void | Promise<void>;

package/src/loader.ts

@@ -1,98 +0,0 @@
-/**
- * Extension discovery and loading (#10): zero-build TypeScript executed
- * directly. Global user extensions always load; repo-local `.cueloop/
- * extensions/` loads only when the repo is trusted (persisted decisions
- * under the cueloop home).
- */
-
-import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { Registry } from "./registry";
-import type { ExtensionFactory } from "./types";
-
-export function userExtensionsDir(): string {
-  return join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "cueloop", "extensions");
-}
-
-export interface LoadOptions {
-  registry: Registry;
-  userDir?: string;
-  repoRoot?: string;
-  /** Persisted trust decisions live under the cueloop home. */
-  home?: string;
-  /** Trust resolver for untrusted repos; default denies (never prompt-free). */
-  confirmTrust?: (repoRoot: string) => Promise<boolean>;
-}
-
-interface TrustStore {
-  trusted: string[];
-}
-
-function trustPath(home: string): string {
-  return join(home, "trusted-repos.json");
-}
-
-export function readTrust(home: string): TrustStore {
-  try {
-    return JSON.parse(readFileSync(trustPath(home), "utf8")) as TrustStore;
-  } catch {
-    return { trusted: [] };
-  }
-}
-
-export function grantTrust(home: string, repoRoot: string): void {
-  const store = readTrust(home);
-  if (!store.trusted.includes(repoRoot)) store.trusted.push(repoRoot);
-  mkdirSync(home, { recursive: true });
-  writeFileSync(trustPath(home), JSON.stringify(store, null, 2));
-}
-
-function extensionFiles(dir: string): string[] {
-  if (!existsSync(dir)) return [];
-  return readdirSync(dir)
-    .filter((f) => f.endsWith(".ts") || f.endsWith(".js"))
-    .map((f) => join(dir, f))
-    .sort();
-}
-
-export async function loadExtensions(opts: LoadOptions): Promise<{ loaded: string[]; skipped: string[] }> {
-  const loaded: string[] = [];
-  const skipped: string[] = [];
-  const files: { path: string; source: string }[] = [];
-
-  for (const path of extensionFiles(opts.userDir ?? userExtensionsDir())) {
-    files.push({ path, source: "user" });
-  }
-  if (opts.repoRoot) {
-    const repoDir = join(opts.repoRoot, ".cueloop", "extensions");
-    const repoFiles = extensionFiles(repoDir);
-    if (repoFiles.length) {
-      const home = opts.home ?? join(homedir(), ".cueloop");
-      const trusted =
-        readTrust(home).trusted.includes(opts.repoRoot) ||
-        (opts.confirmTrust ? await opts.confirmTrust(opts.repoRoot) : false);
-      if (trusted) {
-        grantTrust(home, opts.repoRoot);
-        for (const path of repoFiles) files.push({ path, source: "repo" });
-      } else {
-        skipped.push(...repoFiles);
-      }
-    }
-  }
-
-  for (const file of files) {
-    try {
-      const mod = (await import(file.path)) as { default?: ExtensionFactory };
-      if (typeof mod.default !== "function") {
-        skipped.push(file.path);
-        continue;
-      }
-      await opts.registry.load(file.path, mod.default);
-      loaded.push(file.path);
-    } catch {
-      skipped.push(file.path);
-    }
-  }
-  return { loaded, skipped };
-}