Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

4.1 KB
Raw Blame
/**
 * A module's manifest: its static description, as a JSON file that is read and checked
 * WITHOUT executing the module — the same split VS Code makes between package.json's
 * `contributes` and the plugin's code.
 *
 *   {
 *     "name": "agents",
 *     "requires": { "projects": { "iface": "ProjectsNeeded", "from": "projects" } },
 *     "provides": { "agents": "Agents" },
 *     "contributes": { "http.routes": [{ "id": "agents.routes", "prefix": "/api/…", "auth": "user" }] },
 *     "context": { "version": 1, "schema": "{ collapsed?: string[] }" },
 *     "children": ["vault", { "keyed": "workflows" }]
 *   }
 *
 * - `provides`: alias → an interface class this module declares, keyed
 *   `<name>#<Export>` in the bundle's iface table.
 * - `requires`: alias → the SHAPE needed (an interface class the consumer declares —
 *   the Go habit of declaring the interface where it is consumed — or `<pkg>#<Export>`,
 *   copied into this bundle's table at build) and `from`, the module WIRED to provide
 *   it. Satisfaction is structural; `from` only says whose implementation.
 * - `contributes`: `<module>.<slot>` → entries, each with a unique `id`. Pure data.
 * - `context`: the parked state's version and schema; migrations are code and live on
 *   the module implementation.
 */
import { type } from "arktype";
import type { Json, JsonObject } from "./json.js";

export interface Requirement {
  readonly iface: string;
  readonly from?: string;
}

export interface ContextDecl {
  readonly version: number;
  /** An arktype definition; absent = opaque (anything parks). */
  readonly schema?: Json;
}

export type ChildRef = string | { readonly keyed: string };

export interface Manifest {
  readonly name: string;
  readonly requires: Readonly<Record<string, Requirement>>;
  readonly provides: Readonly<Record<string, string>>;
  readonly contributes: Readonly<
    Record<string, ReadonlyArray<{ readonly id: string } & JsonObject>>
  >;
  readonly context?: ContextDecl;
  readonly children: ReadonlyArray<ChildRef>;
  /**
   * Aliases in `provides` that are FORWARDED from a child: the module exports what one of
   * its children provides under that interface, so the subtree's other provisions stay
   * private to it. Resolved at boot to the child declaring the interface (else the one
   * child whose provision satisfies it).
   */
  readonly exports?: ReadonlyArray<string>;
  /** What the class was declared as: a component exports itself, a module exports others. Informational. */
  readonly kind?: "module" | "component";
}

const ManifestType = type({
  name: "string > 0",
  "requires?": { "[string]": { iface: "string > 0", "from?": "string > 0" } },
  "provides?": { "[string]": "string > 0" },
  "contributes?": { "[string]": type({ id: "string > 0", "[string]": "unknown" }).array() },
  "context?": { version: "number.integer >= 1", "schema?": "unknown" },
  "children?": type("string").or({ keyed: "string" }).array(),
  "exports?": "string[]",
  "kind?": "'module' | 'component'",
});

/**
 * Strict parse of a manifest document; throws with the arktype summary on failure. An empty
 * `requires`, `provides`, `contributes` or `children` may be left out of the document — a
 * plugin that only contributes writes its name and its contributions — and reads as empty.
 */
export function parseManifest(doc: unknown, where = "manifest"): Manifest {
  const out = ManifestType(doc);
  if (out instanceof type.errors) throw new Error(`${where}: ${out.summary}`);
  return {
    ...out,
    requires: out.requires ?? {},
    provides: out.provides ?? {},
    contributes: out.contributes ?? {},
    children: out.children ?? [],
  } as unknown as Manifest;
}

/** The iface-table key a manifest reference resolves to. */
export function ifaceKey(moduleName: string, ref: string): string {
  return ref.includes("#") ? ref : `${moduleName}#${ref}`;
}

/** `<module>.<slot>` → its two halves. */
export function splitSlotKey(key: string): { module: string; slot: string } | null {
  const at = key.lastIndexOf(".");
  if (at <= 0 || at === key.length - 1) return null;
  return { module: key.slice(0, at), slot: key.slice(at + 1) };
}