@cueloop/extension-api 0.1.0-alpha.89 → 0.1.0-alpha.90

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/extension-api",
-  "version": "0.1.0-alpha.89",
+  "version": "0.1.0-alpha.90",
   "description": "The typed contract for extending cueloop: renderers, commands, keybindings, exporters",
   "homepage": "https://github.com/mmurakaru/cueloop#readme",
   "bugs": {
@@ -18,13 +18,20 @@
   ],
   "type": "module",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./client": "./src/client-ui.ts",
+    "./installed-packages": "./src/installed-packages.ts"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@cueloop/schema": "0.1.0-alpha.89"
+    "@cueloop/schema": "0.1.0-alpha.90",
+    "valibot": "^1.5.0"
+  },
+  "peerDependencies": {
+    "@opentui/react": "^0.5.11",
+    "react": "^19.3.0"
   },
   "engines": {
     "bun": ">=1.3.0"

package/src/client-ui.ts

@@ -0,0 +1,57 @@
+import type * as React from "react";
+import type { ComponentType } from "react";
+
+export type ExtensionComponent = ComponentType<{ context: ExtensionUIContext }>;
+
+/** The client supplies current workspace and Thread identity to extension UI. */
+export interface ExtensionUIContext {
+  workspace: string | null;
+  threadId: string | null;
+}
+
+/** A host-owned registration that can be removed on extension reload. */
+export interface ExtensionUIDisposable {
+  dispose(): void;
+}
+
+/** A titled, height-bounded section below the scrolling Threads list. */
+export interface ThreadSidebarSection {
+  id: string;
+  zone: "threads.sidebar";
+  title: string;
+  Component: ExtensionComponent;
+  when?: (context: ExtensionUIContext) => boolean;
+}
+
+/** An action rendered with the Thread header's existing button primitive. */
+export interface ThreadHeaderAction {
+  id: string;
+  zone: "thread.header";
+  label: string;
+  glyph?: string;
+  onPress(context: ExtensionUIContext): void | Promise<void>;
+  when?: (context: ExtensionUIContext) => boolean;
+}
+
+/** A selectable full-height view inside the workspace's existing right pane. */
+export interface WorkspacePanelView {
+  id: string;
+  zone: "workspace.panels";
+  title: string;
+  Component: ExtensionComponent;
+  when?: (context: ExtensionUIContext) => boolean;
+}
+
+/** Client-only registration API; server and VCS capabilities use the daemon entry point. */
+export interface ClientExtensionAPI {
+  /** Use this React instance for hooks so components share the host renderer's dispatcher. */
+  react: typeof React;
+  /** Host keyboard hook; package-local OpenTUI hooks do not share the host context. */
+  useKeyboard: typeof import("@opentui/react").useKeyboard;
+  registerSection(section: ThreadSidebarSection): ExtensionUIDisposable;
+  registerAction(action: ThreadHeaderAction): ExtensionUIDisposable;
+  registerView(view: WorkspacePanelView): ExtensionUIDisposable;
+}
+
+/** Client packages export one factory that registers their UI contributions. */
+export type ClientExtensionFactory = (api: ClientExtensionAPI) => void | Promise<void>;

package/src/installed-packages.test.ts

@@ -0,0 +1,79 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, mkdirSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { discoverInstalledExtensionPackages } from "./installed-packages";
+
+const roots: string[] = [];
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+function installFixture(
+  name: string,
+  cueloop: { client?: string; daemon?: string } | undefined,
+): string {
+  const root = mkdtempSync(join(tmpdir(), "cueloop-extensions-test-"));
+  const packageRoot = join(root, "node_modules", name);
+
+  roots.push(root);
+  mkdirSync(packageRoot, { recursive: true });
+  writeFileSync(join(root, "package.json"), JSON.stringify({ dependencies: { [name]: "1.0.0" } }));
+  writeFileSync(join(packageRoot, "package.json"), JSON.stringify({ name, cueloop }));
+  writeFileSync(join(packageRoot, "client.js"), "export default () => {};");
+  writeFileSync(join(packageRoot, "daemon.js"), "export default () => {};");
+
+  return root;
+}
+
+describe("installed extension discovery", () => {
+  test("finds separate client and daemon entry points in a scoped package", () => {
+    const root = installFixture("@example/tools", { client: "./client.js", daemon: "./daemon.js" });
+    const result = discoverInstalledExtensionPackages(root);
+
+    expect(result.errors).toEqual([]);
+    expect(result.packages).toEqual([
+      {
+        name: "@example/tools",
+        root: join(root, "node_modules", "@example/tools"),
+        clientEntry: realpathSync(join(root, "node_modules", "@example/tools/client.js")),
+        daemonEntry: realpathSync(join(root, "node_modules", "@example/tools/daemon.js")),
+      },
+    ]);
+  });
+
+  test("rejects an entry outside its package and continues discovery", () => {
+    const root = installFixture("example", { client: "./../outside.js" });
+    const result = discoverInstalledExtensionPackages(root);
+
+    expect(result.packages).toEqual([]);
+    expect(result.errors[0]).toContain("entry escapes package root");
+  });
+
+  test("rejects a symlink entry that leaves the package", () => {
+    const root = installFixture("example", { client: "./linked.js" });
+    const outside = join(root, "outside.js");
+
+    writeFileSync(outside, "export default () => {};");
+    symlinkSync(outside, join(root, "node_modules/example/linked.js"));
+
+    expect(discoverInstalledExtensionPackages(root).errors[0]).toContain(
+      "entry escapes package root",
+    );
+  });
+
+  test("rejects a directory entry before installation succeeds", () => {
+    const root = installFixture("example", { client: "./folder" });
+
+    mkdirSync(join(root, "node_modules/example/folder"));
+
+    expect(discoverInstalledExtensionPackages(root).errors[0]).toContain("entry is not a file");
+  });
+
+  test("rejects a package without a cueloop manifest", () => {
+    const root = installFixture("example", undefined);
+
+    expect(discoverInstalledExtensionPackages(root).errors[0]).toContain("no cueloop manifest");
+  });
+});

package/src/installed-packages.ts

@@ -0,0 +1,99 @@
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import * as v from "valibot";
+
+const PackageJsonSchema = v.object({
+  dependencies: v.optional(v.record(v.string(), v.string())),
+  cueloop: v.optional(
+    v.object({
+      client: v.optional(v.string()),
+      daemon: v.optional(v.string()),
+    }),
+  ),
+});
+
+/** The user-owned directory where `cueloop install` keeps npm packages. */
+export function extensionInstallRoot(env = process.env): string {
+  return (
+    env.CUELOOP_EXTENSION_HOME ??
+    join(env.XDG_DATA_HOME ?? join(homedir(), ".local", "share"), "cueloop", "extensions")
+  );
+}
+
+/** One installed package's separate client and daemon extension entry points. */
+export interface InstalledExtensionPackage {
+  name: string;
+  root: string;
+  clientEntry?: string;
+  daemonEntry?: string;
+}
+
+/** Discovery reports bad packages without preventing valid installed extensions from loading. */
+export interface ExtensionPackageDiscovery {
+  packages: InstalledExtensionPackage[];
+  errors: string[];
+}
+
+function readPackageJson(path: string): v.InferOutput<typeof PackageJsonSchema> {
+  const parsed = v.safeParse(PackageJsonSchema, JSON.parse(readFileSync(path, "utf8")));
+
+  if (!parsed.success) throw new Error("invalid package.json");
+
+  return parsed.output;
+}
+
+function packageEntry(root: string, entry: string | undefined): string | undefined {
+  if (entry === undefined) return undefined;
+  if (!entry.startsWith("./")) throw new Error("entry must start with ./");
+  const absolute = resolve(root, entry);
+  const lexicalWithin = relative(root, absolute);
+
+  if (isAbsolute(lexicalWithin) || lexicalWithin === ".." || lexicalWithin.startsWith(`..${sep}`))
+    throw new Error("entry escapes package root");
+  if (!existsSync(absolute)) throw new Error(`entry missing: ${entry}`);
+  if (!statSync(absolute).isFile()) throw new Error(`entry is not a file: ${entry}`);
+  const within = relative(realpathSync(root), realpathSync(absolute));
+
+  if (isAbsolute(within) || within === ".." || within.startsWith(`..${sep}`))
+    throw new Error("entry escapes package root");
+
+  return realpathSync(absolute);
+}
+
+/** Discover only declared `cueloop` entries from packages in the managed install root. */
+export function discoverInstalledExtensionPackages(
+  installRoot = extensionInstallRoot(),
+): ExtensionPackageDiscovery {
+  const packages: InstalledExtensionPackage[] = [];
+  const errors: string[] = [];
+  const rootManifest = join(installRoot, "package.json");
+
+  if (!existsSync(rootManifest)) return { packages, errors };
+  let dependencies: Record<string, string>;
+
+  try {
+    dependencies = readPackageJson(rootManifest).dependencies ?? {};
+  } catch (error) {
+    return { packages, errors: [`Extension package discovery: ${String(error)}`] };
+  }
+
+  for (const name of Object.keys(dependencies).toSorted()) {
+    const root = join(installRoot, "node_modules", name);
+
+    try {
+      const manifest = readPackageJson(join(root, "package.json")).cueloop;
+
+      if (!manifest) throw new Error("package has no cueloop manifest");
+      const clientEntry = packageEntry(root, manifest.client);
+      const daemonEntry = packageEntry(root, manifest.daemon);
+
+      if (!clientEntry && !daemonEntry) throw new Error("manifest declares no entry point");
+      packages.push({ name, root, clientEntry, daemonEntry });
+    } catch (error) {
+      errors.push(`Extension package ${name}: ${String(error)}`);
+    }
+  }
+
+  return { packages, errors };
+}

package/src/registry.test.ts

@@ -48,4 +48,46 @@ describe("Registry", () => {
     expect(record.exporters.size).toBe(0);
     expect(registry.extensions.length).toBe(1);
   });
+
+  test("a failed factory discards VCS adapters and exporters registered before it threw", async () => {
+    const registry = new Registry();
+    const record = await registry.load("broken-vcs", (api) => {
+      api.registerExporter("draft", async () => ({ success: true }));
+      api.registerVcsAdapter({
+        apiVersion: 1,
+        id: "example.sapling",
+        detect: async () => "/repo",
+        captureWorkingDiff: async () => ({ patch: "", files: [] }),
+        listChanges: async () => [],
+        listFiles: async () => [],
+      });
+      throw new Error("incomplete extension");
+    });
+
+    expect(record.errors).toEqual(["incomplete extension"]);
+    expect(record.exporters.size).toBe(0);
+    expect(record.vcsAdapters.size).toBe(0);
+  });
+
+  test("VCS IDs cannot replace built-in or previously registered adapters", async () => {
+    const registry = new Registry();
+    const adapter = {
+      apiVersion: 1 as const,
+      id: "example.sapling",
+      detect: async () => "/repo",
+      captureWorkingDiff: async () => ({ patch: "", files: [] }),
+      listChanges: async () => [],
+      listFiles: async () => [],
+    };
+
+    await registry.load("first", (api) => api.registerVcsAdapter(adapter));
+    const duplicate = await registry.load("second", (api) => api.registerVcsAdapter(adapter));
+    const builtin = await registry.load("third", (api) =>
+      api.registerVcsAdapter({ ...adapter, id: "git" }),
+    );
+
+    expect(duplicate.errors).toEqual(["Invalid or duplicate VCS adapter ID: example.sapling"]);
+    expect(builtin.errors).toEqual(["Invalid or duplicate VCS adapter ID: git"]);
+    expect(registry.extensions[0]!.vcsAdapters.has("example.sapling")).toBe(true);
+  });
 });

package/src/registry.ts

@@ -4,11 +4,23 @@
  * extension. One broken extension never takes the host down.
  */
 
-import type { Exporter, ExtensionAPI, ExtensionFactory } from "./types";
+import type { Exporter, ExtensionAPI, ExtensionFactory, VcsAdapter } from "./types";
+import * as v from "valibot";
+
+const VcsAdapterSchema = v.object({
+  apiVersion: v.literal(1),
+  id: v.pipe(v.string(), v.regex(/^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)+$/)),
+  detect: v.function(),
+  captureWorkingDiff: v.function(),
+  captureChange: v.optional(v.function()),
+  listChanges: v.function(),
+  listFiles: v.function(),
+});
 
 export interface ExtensionRecord {
   name: string;
   exporters: Map<string, Exporter>;
+  vcsAdapters: Map<string, VcsAdapter>;
   errors: string[];
 }
 
@@ -17,16 +29,36 @@ export class Registry {
 
   /** Run one extension factory, capturing its registrations. */
   async load(name: string, factory: ExtensionFactory): Promise<ExtensionRecord> {
-    const record: ExtensionRecord = { name, exporters: new Map(), errors: [] };
+    const record: ExtensionRecord = {
+      name,
+      exporters: new Map(),
+      vcsAdapters: new Map(),
+      errors: [],
+    };
     const api: ExtensionAPI = {
       registerExporter(exporterName, exporter) {
         record.exporters.set(exporterName, exporter);
       },
+      registerVcsAdapter: (adapter) => {
+        if (adapter.id === "git" || adapter.id === "jj")
+          throw new Error(`Invalid or duplicate VCS adapter ID: ${adapter.id}`);
+        const parsed = v.safeParse(VcsAdapterSchema, adapter);
+
+        if (!parsed.success) throw new Error(`Invalid VCS adapter contract: ${adapter.id}`);
+        if (
+          record.vcsAdapters.has(adapter.id) ||
+          this.extensions.some((extension) => extension.vcsAdapters.has(adapter.id))
+        )
+          throw new Error(`Invalid or duplicate VCS adapter ID: ${adapter.id}`);
+        record.vcsAdapters.set(adapter.id, adapter);
+      },
     };
 
     try {
       await factory(api);
     } catch (err) {
+      record.exporters.clear();
+      record.vcsAdapters.clear();
       record.errors.push(err instanceof Error ? err.message : String(err));
     }
     this.extensions.push(record);

package/src/types.ts

@@ -8,15 +8,49 @@
  * later, host-driven. No import-time side effects.
  */
 
-import type { Thread } from "@cueloop/schema";
+import type { DiffFileContents, DiffFileStatus, Thread } from "@cueloop/schema";
 
 /** Exporters ship resolved sessions somewhere (notes vaults, forges). */
 export type Exporter = (
   session: Thread,
 ) => Promise<{ success: boolean; path?: string; error?: string }>;
 
+/** A source identity links a live diff to an exact captured revision. */
+export interface VcsSourceIdentity {
+  /** Stable logical change identity, when the VCS provides one. */
+  changeId?: string;
+  /** Exact revision that supplied this patch. */
+  revisionId: string;
+}
+
+/** One complete working-copy capture; file contents must match the returned patch. */
+export interface VcsDiffSnapshot {
+  patch: string;
+  files: DiffFileContents[];
+  source?: VcsSourceIdentity;
+}
+
+/** The daemon-owned diff source contract; adapters never mutate Threads. */
+export interface VcsAdapter {
+  /** Contract version understood by this host. */
+  apiVersion: 1;
+  /** Unique namespaced ID, such as `example.sapling`. */
+  id: string;
+  /** Return the checkout root containing cwd, or null when this adapter does not apply. */
+  detect(cwd: string): Promise<string | null>;
+  /** Capture the working copy against its current parent in Git patch format. */
+  captureWorkingDiff(repoRoot: string): Promise<VcsDiffSnapshot>;
+  /** Optional: recapture one logical change after its exact revision was rewritten. */
+  captureChange?(repoRoot: string, changeId: string): Promise<VcsDiffSnapshot>;
+  /** List changed paths, including files that cannot be curated as text. */
+  listChanges(repoRoot: string): Promise<{ path: string; status: DiffFileStatus }[]>;
+  /** List the project files at the current revision. */
+  listFiles(repoRoot: string): Promise<string[]>;
+}
+
 export interface ExtensionAPI {
   registerExporter(name: string, exporter: Exporter): void;
+  registerVcsAdapter(adapter: VcsAdapter): void;
 }
 
 export type ExtensionFactory = (cueloop: ExtensionAPI) => void | Promise<void>;