Implement wish<>() built-in (#1898)

bfollington · web-flow · commit 0c65d67948c2 · 2025-10-14T15:50:22.000-07:00
* Implement `wish&lt;&gt;()` built-in

Also removed the need to inject `allCharms` into `default-app.tsx` as an example usage

* Format and lint

* Add doc comment

* Fix wish tests

* Move all charms ID constant to runner package

Resolves circular import

* Use `derive` to attach correct schema to wish result

* Action Berni's feedback

* Fix failing test

* Format

-_-

* Update commontools.d.ts
diff --git a/packages/api/index.ts b/packages/api/index.ts
@@ -524,6 +524,13 @@ export type CompileAndRunFunction = <T = any, S = any>(
 ) => OpaqueRef<BuiltInCompileAndRunState<S>>;
 
 export type NavigateToFunction = (cell: OpaqueRef<any>) => OpaqueRef<string>;
+export type WishFunction = {
+  <T = unknown>(target: Opaque<string>): OpaqueRef<T | undefined>;
+  <T = unknown>(
+    target: Opaque<string>,
+    defaultValue: Opaque<T>,
+  ): OpaqueRef<T>;
+};
 
 export type CreateNodeFactoryFunction = <T = any, R = any>(
   moduleSpec: Module,
@@ -575,6 +582,7 @@ export declare const fetchData: FetchDataFunction;
 export declare const streamData: StreamDataFunction;
 export declare const compileAndRun: CompileAndRunFunction;
 export declare const navigateTo: NavigateToFunction;
+export declare const wish: WishFunction;
 export declare const createNodeFactory: CreateNodeFactoryFunction;
 export declare const createCell: CreateCellFunction;
 export declare const cell: CellFunction;
diff --git a/packages/charm/src/index.ts b/packages/charm/src/index.ts
@@ -65,4 +65,3 @@ export {
   type WorkflowType,
 } from "./workflow.ts";
 export * from "./spellbook.ts";
-export * from "./well-known.ts";
diff --git a/packages/charm/src/well-known.ts b/packages/charm/src/well-known.ts
diff --git a/packages/patterns/default-app.tsx b/packages/patterns/default-app.tsx
@@ -1,7 +1,6 @@
 /// <cts-enable />
 import {
   Cell,
-  Default,
   derive,
   handler,
   NAME,
@@ -10,6 +9,7 @@ import {
   recipe,
   str,
   UI,
+  wish,
 } from "commontools";
 
 // Import recipes we want to be launchable from the default app.
@@ -28,9 +28,7 @@ export type Charm = {
   [key: string]: any;
 };
 
-type CharmsListInput = {
-  allCharms: Default<MentionableCharm[], []>;
-};
+type CharmsListInput = void;
 
 // Recipe returns only UI, no data outputs (only symbol properties)
 interface CharmsListOutput {
@@ -113,10 +111,18 @@ const spawnNote = handler<
   }));
 });
 
+function getAllCharms() {
+  const allCharms = wish<MentionableCharm[]>("#/allCharms", []);
+  // ensure schema is added to return type
+  return derive<MentionableCharm[], MentionableCharm[]>(allCharms, (c) => c);
+}
+
 export default recipe<CharmsListInput, CharmsListOutput>(
   "DefaultCharmList",
-  ({ allCharms }) => {
+  (_) => {
+    const allCharms = getAllCharms();
     const index = BacklinksIndex({ allCharms });
+
     return {
       [NAME]: str`DefaultCharmList (${allCharms.length})`,
       [UI]: (
diff --git a/packages/runner/src/builder/built-in.ts b/packages/runner/src/builder/built-in.ts
@@ -88,6 +88,26 @@ export const navigateTo = createNodeFactory({
   implementation: "navigateTo",
 }) as (cell: OpaqueRef<unknown>) => OpaqueRef<string>;
 
+let wishFactory: NodeFactory<[unknown, unknown], any> | undefined;
+
+export function wish<T = unknown>(
+  target: Opaque<string>,
+): OpaqueRef<T | undefined>;
+export function wish<T = unknown>(
+  target: Opaque<string>,
+  defaultValue: Opaque<T> | T,
+): OpaqueRef<T>;
+export function wish<T = unknown>(
+  target: Opaque<string>,
+  defaultValue?: Opaque<T> | T,
+): OpaqueRef<T | undefined> {
+  wishFactory ||= createNodeFactory({
+    type: "ref",
+    implementation: "wish",
+  });
+  return wishFactory([target, defaultValue]) as OpaqueRef<T | undefined>;
+}
+
 // Example:
 // str`Hello, ${name}!`
 //
diff --git a/packages/runner/src/builder/factory.ts b/packages/runner/src/builder/factory.ts
@@ -31,6 +31,7 @@ import {
   navigateTo,
   str,
   streamData,
+  wish,
 } from "./built-in.ts";
 import { getRecipeEnvironment } from "./env.ts";
 import type { RuntimeProgram } from "../harness/types.ts";
@@ -117,6 +118,7 @@ export const createBuilder = (
       streamData,
       compileAndRun,
       navigateTo,
+      wish,
 
       // Cell creation
       createCell,
diff --git a/packages/runner/src/builder/types.ts b/packages/runner/src/builder/types.ts
@@ -32,6 +32,7 @@ import type {
   StreamDataFunction,
   StreamFunction,
   StrFunction,
+  WishFunction,
 } from "@commontools/api";
 import {
   h,
@@ -287,6 +288,7 @@ export interface BuilderFunctionsAndConstants {
   streamData: StreamDataFunction;
   compileAndRun: CompileAndRunFunction;
   navigateTo: NavigateToFunction;
+  wish: WishFunction;
 
   // Cell creation
   createCell: CreateCellFunction;
diff --git a/packages/runner/src/builtins/index.ts b/packages/runner/src/builtins/index.ts
@@ -7,6 +7,7 @@ import { ifElse } from "./if-else.ts";
 import type { IRuntime } from "../runtime.ts";
 import { compileAndRun } from "./compile-and-run.ts";
 import { navigateTo } from "./navigate-to.ts";
+import { wish } from "./wish.ts";
 import type { Cell } from "../cell.ts";
 import type { BuiltInGenerateObjectParams } from "@commontools/api";
 import { llmDialog } from "./llm-dialog.ts";
@@ -34,4 +35,5 @@ export function registerBuiltins(runtime: IRuntime) {
     }>(generateObject),
   );
   moduleRegistry.addModuleByRef("navigateTo", raw(navigateTo));
+  moduleRegistry.addModuleByRef("wish", raw(wish));
 }
diff --git a/packages/runner/src/builtins/well-known.ts b/packages/runner/src/builtins/well-known.ts
@@ -0,0 +1,9 @@
+/**
+ * Well-known entity IDs used by built-in functions.
+ */
+
+/**
+ * Well-known entity ID for the all charms list.
+ */
+export const ALL_CHARMS_ID =
+  "baedreiahv63wxwgaem4hzjkizl4qncfgvca7pj5cvdon7cukumfon3ioye";
diff --git a/packages/runner/src/builtins/wish.ts b/packages/runner/src/builtins/wish.ts
@@ -0,0 +1,83 @@
+import { type Cell } from "../cell.ts";
+import { type Action } from "../scheduler.ts";
+import type { IRuntime } from "../runtime.ts";
+import type {
+  IExtendedStorageTransaction,
+  MemorySpace,
+} from "../storage/interface.ts";
+import type { EntityId } from "../create-ref.ts";
+import { ALL_CHARMS_ID } from "./well-known.ts";
+import type { JSONSchema } from "../builder/types.ts";
+
+type WishResolution = {
+  entityId: EntityId;
+  path?: readonly string[];
+};
+
+const WISH_TARGETS: Record<string, WishResolution> = {
+  "#/allCharms": { entityId: { "/": ALL_CHARMS_ID } },
+};
+
+function resolveWishTarget(
+  wish: string,
+  runtime: IRuntime,
+  space: MemorySpace,
+  tx: IExtendedStorageTransaction,
+): Cell<unknown> | undefined {
+  const target = WISH_TARGETS[wish];
+  if (!target) return undefined;
+
+  const path = target.path ? [...target.path] : [];
+  return runtime.getCellFromEntityId(
+    space,
+    target.entityId,
+    path,
+    undefined,
+    tx,
+  );
+}
+
+const TARGET_SCHEMA = {
+  type: "string",
+  default: "",
+} as const satisfies JSONSchema;
+
+export function wish(
+  inputsCell: Cell<[unknown, unknown]>,
+  sendResult: (tx: IExtendedStorageTransaction, result: unknown) => void,
+  _addCancel: (cancel: () => void) => void,
+  _cause: Cell<any>[],
+  parentCell: Cell<any>,
+  runtime: IRuntime,
+): Action {
+  return (tx: IExtendedStorageTransaction) => {
+    const inputsWithTx = inputsCell.withTx(tx);
+    const values = inputsWithTx.get() ?? [];
+    const target = inputsWithTx.key(0).asSchema(TARGET_SCHEMA).get();
+    const defaultValue = values.length >= 2 ? values[1] : undefined;
+    const hasDefault = defaultValue !== undefined && defaultValue !== null;
+    const defaultCell = hasDefault ? inputsWithTx.key(1) : undefined;
+
+    const wishTarget = typeof target === "string" ? target.trim() : "";
+
+    if (wishTarget === "") {
+      sendResult(tx, hasDefault ? defaultCell : undefined);
+      return;
+    }
+
+    const resolvedCell = resolveWishTarget(
+      wishTarget,
+      runtime,
+      parentCell.space,
+      tx,
+    );
+
+    if (!resolvedCell) {
+      console.error(`Wish target "${wishTarget}" is not recognized.`);
+      sendResult(tx, hasDefault ? defaultCell : undefined);
+      return;
+    }
+
+    sendResult(tx, resolvedCell.withTx(tx));
+  };
+}
diff --git a/packages/runner/test/wish.test.ts b/packages/runner/test/wish.test.ts
@@ -0,0 +1,134 @@
+import { afterEach, beforeEach, describe, it } from "@std/testing/bdd";
+import { expect } from "@std/expect";
+import { Identity } from "@commontools/identity";
+import { StorageManager } from "@commontools/runner/storage/cache.deno";
+import { LINK_V1_TAG } from "../src/sigil-types.ts";
+import { createBuilder } from "../src/builder/factory.ts";
+import { Runtime } from "../src/runtime.ts";
+import { ALL_CHARMS_ID } from "../src/builtins/well-known.ts";
+
+const signer = await Identity.fromPassphrase("wish built-in tests");
+const space = signer.did();
+
+describe("wish built-in", () => {
+  let storageManager: ReturnType<typeof StorageManager.emulate>;
+  let runtime: Runtime;
+  let tx: ReturnType<Runtime["edit"]>;
+  let wish: ReturnType<typeof createBuilder>["commontools"]["wish"];
+  let recipe: ReturnType<typeof createBuilder>["commontools"]["recipe"];
+
+  beforeEach(() => {
+    storageManager = StorageManager.emulate({ as: signer });
+    runtime = new Runtime({
+      apiUrl: new URL("https://example.com"),
+      storageManager,
+    });
+
+    tx = runtime.edit();
+
+    const { commontools } = createBuilder(runtime);
+    ({ wish, recipe } = commontools);
+  });
+
+  afterEach(async () => {
+    await tx.commit();
+    await runtime.dispose();
+    await storageManager.close();
+  });
+
+  it("resolves the well known all charms cell", async () => {
+    const allCharmsCell = runtime.getCellFromEntityId(
+      space,
+      { "/": ALL_CHARMS_ID },
+      [],
+      undefined,
+      tx,
+    );
+    const charmsData = [{ name: "Alpha" }];
+    allCharmsCell.withTx(tx).set(charmsData);
+
+    const wishRecipe = recipe("wish resolves all charms", () => {
+      const allCharms = wish<Array<Record<string, unknown>>>("#/allCharms");
+      return { allCharms };
+    });
+
+    const resultCell = runtime.getCell<{ allCharms?: unknown[] }>(
+      space,
+      "wish built-in result",
+      undefined,
+      tx,
+    );
+    const result = runtime.run(tx, wishRecipe, {}, resultCell);
+    await tx.commit();
+    tx = runtime.edit();
+
+    await runtime.idle();
+
+    const readTx = runtime.readTx();
+    const actualCell = result.withTx(readTx).key("allCharms");
+    const rawValue = actualCell.withTx(readTx).getRaw() as
+      | { ["/"]: Record<string, unknown> }
+      | undefined;
+    const linkData = rawValue?.["/"]?.[LINK_V1_TAG] as
+      | { id?: string; overwrite?: string }
+      | undefined;
+
+    expect(result.key("allCharms").get()).toEqual(charmsData);
+    expect(linkData?.id).toEqual(`of:${ALL_CHARMS_ID}`);
+  });
+
+  it("returns undefined for unknown wishes", async () => {
+    const errors: unknown[] = [];
+    const originalError = console.error;
+    console.error = (...args: unknown[]) => {
+      errors.push(args);
+    };
+
+    try {
+      const wishRecipe = recipe("wish unknown target", () => {
+        const missing = wish("commontools://unknown");
+        return { missing };
+      });
+
+      const resultCell = runtime.getCell<{ missing?: unknown }>(
+        space,
+        "wish built-in missing target",
+        undefined,
+        tx,
+      );
+      const result = runtime.run(tx, wishRecipe, {}, resultCell);
+      await tx.commit();
+      tx = runtime.edit();
+
+      await runtime.idle();
+
+      expect(result.key("missing").get()).toBeUndefined();
+      expect(errors.length).toBeGreaterThan(0);
+    } finally {
+      console.error = originalError;
+    }
+  });
+
+  it("uses provided default when target is missing", async () => {
+    const fallback = [{ name: "Fallback" }];
+
+    const wishRecipe = recipe("wish default", () => {
+      const missing = wish("#/missing", fallback);
+      return { missing };
+    });
+
+    const resultCell = runtime.getCell<{ missing?: unknown }>(
+      space,
+      "wish built-in default",
+      undefined,
+      tx,
+    );
+    const result = runtime.run(tx, wishRecipe, {}, resultCell);
+    await tx.commit();
+    tx = runtime.edit();
+
+    await runtime.idle();
+
+    expect(result.key("missing").get()).toEqual(fallback);
+  });
+});
diff --git a/packages/shell/src/lib/default-pattern.ts b/packages/shell/src/lib/default-pattern.ts
diff --git a/packages/static/assets/types/commontools.d.ts b/packages/static/assets/types/commontools.d.ts
diff --git a/tutorials/index.md b/tutorials/index.md
