refactor(charm): remove built-in Charm schema; require explicit schemas (#1819)

* add <T> to isStream to override type

* remove [UI] from charm type + first group of fixes based on that.

* refactor(charm): remove built-in Charm schema; require explicit schemas

- Replace Charm type and charmSchema with schema-driven access.
- CharmManager.get now accepts optional schema and returns typed cells.
- Export nameSchema and uiSchema; update callers to read NAME and UI via schema.
- Introduce generic CharmController<T> and CharmsController<T>.
- Background worker: access bgUpdater as Stream via schema; map typed.
- Runner: handle Stream in Cellify<T> for asSchema.
- CLI, UI, and tests: replace Cell<Charm> with Cell<unknown>; pass schemas or cast.
- Persistent flows return typed cells using recipe.resultSchema.
- search.ts and format.ts use nameSchema for NAME access.
- AppView reads title via cc().get(id, nameSchema) and cell.key(NAME).

Motivation:
- Decouple CharmManager from a fixed schema; allow arbitrary charm shapes.
- Make invalid states unrepresentable by requiring explicit schemas at access.
- Enable streams to be typed via schema (asStream) consistently.

* ugly fix for ct-kanban: use any instead of unknown. really this should get a proper schema

* fix UI usage

* call get with runIt true, to keep current behavior

* fix formatting

* remove ct-kanban for now

* addressing various minor PR feedback

* fix formatting

* extract mentionable schema and use in ct-outliner as well

Author: seefeldb

packages/background-charm-service/src/worker.ts

@@ -1,4 +1,4 @@
-import { type Charm, CharmManager } from "@commontools/charm";
+import { CharmManager } from "@commontools/charm";
 import {
   Cell,
   type ConsoleHandler,
@@ -7,6 +7,7 @@ import {
   type ErrorWithContext,
   isStream,
   Runtime,
+  Stream,
 } from "@commontools/runner";
 import { StorageManager } from "@commontools/runner/storage/cache.deno";
 
@@ -29,7 +30,7 @@ let latestError: Error | null = null;
 let currentSession: Session | null = null;
 let manager: CharmManager | null = null;
 let runtime: Runtime | null = null;
-const loadedCharms = new Map<string, Cell<Charm>>();
+const loadedCharms = new Map<string, Cell<{ bgUpdater: Stream<unknown> }>>();
 
 // Error handler that will be passed to Runtime
 const errorHandler: ErrorHandler = (e: ErrorWithContext) => {
@@ -163,7 +164,11 @@ async function runCharm(data: RunData): Promise<void> {
     if (!runningCharm) {
       // If not loaded yet, get it from the manager
       console.log(`Loading charm ${charmId} for the first time`);
-      runningCharm = await manager.get(charmsEntryCell, true);
+      runningCharm = await manager.get(charmsEntryCell, true, {
+        type: "object",
+        properties: { bgUpdater: { asStream: true } },
+        required: ["bgUpdater"],
+      });
 
       if (!runningCharm) {
         throw new Error(`Charm not found: ${charmId}`);
@@ -176,7 +181,7 @@ async function runCharm(data: RunData): Promise<void> {
     }
 
     // Find the updater stream
-    const updater = runningCharm.key("bgUpdater");
+    const updater = runningCharm.key("bgUpdater") as Stream<unknown>;
     if (!updater || !isStream(updater)) {
       throw new Error(`No updater stream found for charm: ${charmId}`);
     }

packages/charm/src/commands.ts

@@ -6,7 +6,7 @@ import { getIframeRecipe } from "./iframe/recipe.ts";
 import { extractUserCode, injectUserCode } from "./iframe/static.ts";
 import { WorkflowForm } from "./index.ts";
 import { compileAndRunRecipe, generateNewRecipeVersion } from "./iterate.ts";
-import { Charm, CharmManager } from "./manager.ts";
+import { CharmManager, nameSchema } from "./manager.ts";
 import { processWorkflow, ProcessWorkflowOptions } from "./workflow.ts";
 
 export const castSpellAsCharm = async (
@@ -71,10 +71,10 @@ export const createDataCharm = (
 
 export async function fixItCharm(
   charmManager: CharmManager,
-  charm: Cell<Charm>,
+  charm: Cell<unknown>,
   error: Error,
   model = DEFAULT_MODEL_NAME,
-): Promise<Cell<Charm>> {
+): Promise<Cell<unknown>> {
   const iframeRecipe = getIframeRecipe(charm, charmManager.runtime);
   if (!iframeRecipe.iframe) {
     throw new Error("Fixit only works for iframe charms");
@@ -112,8 +112,7 @@ export async function renameCharm(
   charmId: string,
   newName: string,
 ): Promise<void> {
-  const charm = await charmManager.get(charmId);
-  if (!charm) return;
+  const charm = await charmManager.get(charmId, false, nameSchema);
   charm.key(NAME).set(newName);
 }
 
@@ -122,7 +121,7 @@ export async function addGithubRecipe(
   filename: string,
   spec: string,
   runOptions: unknown,
-): Promise<Cell<Charm>> {
+): Promise<Cell<unknown>> {
   const response = await fetch(
     `https://raw.githubusercontent.com/commontoolsinc/labs/refs/heads/main/recipes/${filename}?${Date.now()}`,
   );
@@ -151,10 +150,10 @@ export async function addGithubRecipe(
 export async function modifyCharm(
   charmManager: CharmManager,
   promptText: string,
-  currentCharm: Cell<Charm>,
+  currentCharm: Cell<unknown>,
   prefill?: Partial<WorkflowForm>,
   model?: string,
-): Promise<Cell<Charm>> {
+): Promise<Cell<unknown>> {
   // Include the current charm in the context
   const context: ProcessWorkflowOptions = {
     existingCharm: currentCharm,

packages/charm/src/format.ts

@@ -1,5 +1,5 @@
 import { Module, NAME, Recipe } from "@commontools/runner";
-import { CharmManager, charmSchema } from "./index.ts";
+import { CharmManager, nameSchema } from "./manager.ts";
 import { Cell } from "@commontools/runner";
 
 /**
@@ -84,7 +84,7 @@ export function getCharmNameAsCamelCase(
   cell: Cell<unknown>,
   usedKeys: Record<string, unknown>,
 ): string {
-  const charmName = toCamelCase(cell.asSchema(charmSchema).key(NAME).get());
+  const charmName = toCamelCase(cell.asSchema(nameSchema).key(NAME).get());
 
   let name = charmName;
   let num = 0;

packages/charm/src/iframe/recipe.ts

@@ -1,5 +1,5 @@
 import { Cell, type JSONSchema, type Runtime } from "@commontools/runner";
-import { Charm, getRecipeIdFromCharm } from "../manager.ts";
+import { getRecipeIdFromCharm } from "../manager.ts";
 
 export type IFrameRecipe = {
   src: string;
@@ -62,7 +62,7 @@ function parseIframeRecipe(source: string): IFrameRecipe {
 }
 
 export const getIframeRecipe = (
-  charm: Cell<Charm>,
+  charm: Cell<unknown>,
   runtime: Runtime,
 ): {
   recipeId: string;

packages/charm/src/imagine.ts

@@ -1,5 +1,4 @@
 import { Cell } from "@commontools/runner";
-import { Charm } from "./manager.ts";
 
 // Re-export workflow types and functions from workflow module
 export type { WorkflowConfig, WorkflowType } from "./workflow.ts";
@@ -13,13 +12,13 @@ export interface ParsedMention {
   originalText: string;
   startIndex: number;
   endIndex: number;
-  charm: Cell<Charm>;
+  charm: Cell<unknown>;
 }
 
 /**
  * Result of processing a prompt with mentions
  */
 export interface ProcessedPrompt {
   text: string; // Processed text with mentions replaced by readable names
-  mentions: Record<string, Cell<Charm>>; // Map of mention IDs to charm cells
+  mentions: Record<string, Cell<unknown>>; // Map of mention IDs to charm cells
 }

packages/charm/src/index.ts

@@ -1,11 +1,13 @@
 export {
-  type Charm,
   charmId,
   charmListSchema,
   CharmManager,
-  charmSchema,
   getRecipeIdFromCharm,
+  type NameSchema,
+  nameSchema,
   processSchema,
+  type UISchema,
+  uiSchema,
 } from "./manager.ts";
 export { searchCharms } from "./search.ts";
 export {

packages/charm/src/iterate.ts

@@ -11,7 +11,7 @@ import {
   type Runtime,
   type RuntimeProgram,
 } from "@commontools/runner";
-import { Charm, CharmManager, charmSourceCellSchema } from "./manager.ts";
+import { CharmManager, charmSourceCellSchema } from "./manager.ts";
 import { buildFullRecipe, getIframeRecipe } from "./iframe/recipe.ts";
 import { buildPrompt, RESPONSE_PREFILL } from "./iframe/prompt.ts";
 import {
@@ -105,10 +105,10 @@ export const genSrc = async (
  */
 export async function iterate(
   charmManager: CharmManager,
-  charm: Cell<Charm>,
+  charm: Cell<unknown>,
   plan: WorkflowForm["plan"],
   options?: GenerationOptions,
-): Promise<{ cell: Cell<Charm>; llmRequestId?: string }> {
+): Promise<{ cell: Cell<unknown>; llmRequestId?: string }> {
   const optionsWithDefaults = applyDefaults(options);
   const { model, cache, space, generationId } = optionsWithDefaults;
   const { iframe } = getIframeRecipe(charm, charmManager.runtime);
@@ -151,7 +151,7 @@ export function extractTitle(src: string, defaultTitle: string): string {
 
 export const generateNewRecipeVersion = async (
   charmManager: CharmManager,
-  parent: Cell<Charm>,
+  parent: Cell<unknown>,
   newRecipe:
     & Pick<IFrameRecipe, "src" | "spec">
     & Partial<Omit<IFrameRecipe, "src" | "spec">>,
@@ -505,7 +505,7 @@ async function twoPhaseCodeGeneration(
 export async function castNewRecipe(
   charmManager: CharmManager,
   form: WorkflowForm,
-): Promise<{ cell: Cell<Charm>; llmRequestId?: string }> {
+): Promise<{ cell: Cell<unknown>; llmRequestId?: string }> {
   console.log("Processing form:", form);
 
   // Remove $UI, $NAME, and any streams from the cells
@@ -584,7 +584,7 @@ export async function compileAndRunRecipe(
   runOptions: unknown,
   parents?: string[],
   llmRequestId?: string,
-): Promise<Cell<Charm>> {
+): Promise<Cell<unknown>> {
   const recipe = await compileRecipe(
     recipeSrc,
     spec,