@akanjs/devkit 3.2.0-rc.2 → 3.2.0-rc.5

package/moduleFieldNames.ts

@@ -0,0 +1,25 @@
+import ts from "typescript";
+
+const isFieldCall = (node: ts.Expression): boolean =>
+  ts.isCallExpression(node) &&
+  (ts.isIdentifier(node.expression)
+    ? node.expression.text === "field"
+    : ts.isPropertyAccessExpression(node.expression) && isFieldCall(node.expression.expression));
+
+const propertyNames = (content: string, declares: (initializer: ts.Expression) => boolean) => {
+  const names: string[] = [];
+  const visit = (node: ts.Node) => {
+    if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name) && declares(node.initializer))
+      names.push(node.name.text);
+    ts.forEachChild(node, visit);
+  };
+  visit(ts.createSourceFile("module.ts", content, ts.ScriptTarget.Latest));
+  return names;
+};
+
+export const constantFieldNames = (content: string) => propertyNames(content, isFieldCall);
+
+export const unlabeledFieldNames = (constantContent: string, dictionaryContent: string) => {
+  const labels = new Set(propertyNames(dictionaryContent, () => true));
+  return constantFieldNames(constantContent).filter((name) => !labels.has(name));
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.2.0-rc.2",
+  "version": "3.2.0-rc.5",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -41,7 +41,7 @@
     "./*": "./*.ts"
   },
   "dependencies": {
-    "@akanjs/language": "3.2.0-rc.2",
+    "@akanjs/language": "3.2.0-rc.5",
     "@earendil-works/pi-agent-core": "1.3.0",
     "@earendil-works/pi-ai": "1.3.0",
     "@earendil-works/pi-codemode": "1.3.0",
@@ -50,7 +50,7 @@
     "@earendil-works/pi-tui": "1.3.0",
     "@inquirer/prompts": "^8.7.3",
     "@tailwindcss/node": "^4.3.3",
-    "akanjs": "3.2.0-rc.2",
+    "akanjs": "3.2.0-rc.5",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",

package/preview/PreviewView.ts

@@ -77,18 +77,12 @@ export class PreviewView {
     }: PreviewProbeOptions = {},
   ): Promise<PreviewProbeResult> {
     const logs: string[] = [];
-    const view = PreviewView.#open({ width, height, engine, onConsole: (line) => logs.push(line) });
+    const view = await PreviewView.#start(
+      () => PreviewView.#open({ width, height, engine, onConsole: (line) => logs.push(line) }),
+      engine,
+      { startTimeoutMs, timeoutMs },
+    );
     try {
-      //? A browser that missed its start bound may still come up, so a later page retries it within only its own bound.
-      const startMs = PreviewView.#stalled.has(engine) ? Math.min(startTimeoutMs, timeoutMs) : startTimeoutMs;
-      const stalled = new Error(`Timed out starting the ${engine} browser after ${startMs / 1_000} s.`);
-      await PreviewView.#within(view.navigate("about:blank"), Date.now() + startMs, stalled).then(
-        () => PreviewView.#stalled.delete(engine),
-        (error: unknown) => {
-          if (error === stalled) PreviewView.#stalled.add(engine);
-          throw error;
-        },
-      );
       const deadline = Date.now() + timeoutMs;
       const within = <T>(work: Promise<T>, what: string) =>
         PreviewView.#within(
@@ -120,6 +114,33 @@ export class PreviewView {
     }
   }
 
+  static async #start(
+    open: () => WebViewLike,
+    engine: PreviewEngine,
+    { startTimeoutMs, timeoutMs }: { startTimeoutMs: number; timeoutMs: number },
+  ) {
+    for (let attempt = 1; ; attempt++) {
+      //? A browser that missed its start bound may still come up, so a later page retries it within only its own bound.
+      //? One that died or was closed instead is spawned afresh by the next view, which gets the full bound.
+      const startMs = PreviewView.#stalled.has(engine) ? Math.min(startTimeoutMs, timeoutMs) : startTimeoutMs;
+      const stalled = new Error(`Timed out starting the ${engine} browser after ${startMs / 1_000} s.`);
+      let view: WebViewLike | undefined;
+      try {
+        view = open();
+        await PreviewView.#within(view.navigate("about:blank"), Date.now() + startMs, stalled);
+        PreviewView.#stalled.delete(engine);
+        return view;
+      } catch (error) {
+        await view?.close();
+        if (error === stalled) PreviewView.#stalled.add(engine);
+        else PreviewView.#stalled.delete(engine);
+        if (error === stalled || attempt > 1) throw error;
+        //? Bun reaps a browser that died only on a later timer turn; until then `new Bun.WebView()` throws "Failed to spawn Chrome".
+        await Bun.sleep(100);
+      }
+    }
+  }
+
   static async #load(
     view: WebViewLike,
     url: string,

package/preview/previewView.test.ts

@@ -14,7 +14,12 @@ const slowChromeRuns = PreviewView.isAvailable("chrome") && process.platform !==
 const withSlowChrome = async (body: string, startSeconds = 3) => {
   const dir = await mkdtemp(path.join(tmpdir(), "akan-slow-chrome-"));
   const chrome = path.join(dir, "chrome");
-  await writeFile(chrome, `#!/bin/sh\nsleep ${startSeconds}\nexec "${PreviewChrome.executable()}" "$@"\n`);
+  const chromeLog = path.join(dir, "chrome.log");
+  //? Bun.WebView sends the browser's stderr to /dev/null, which would hide why it died.
+  await writeFile(
+    chrome,
+    `#!/bin/sh\nexec 2>>"${chromeLog}"\nsleep ${startSeconds}\nexec "${PreviewChrome.executable()}" "$@"\n`,
+  );
   await chmod(chrome, 0o755);
   const script = `const { PreviewView } = await import(${JSON.stringify(path.join(import.meta.dir, "PreviewView.ts"))});\n${body}`;
   //? Chrome is spawned once per process, so only a fresh process takes the slow executable.
@@ -30,7 +35,10 @@ const withSlowChrome = async (body: string, startSeconds = 3) => {
       new Response(child.stderr).text(),
       child.exited,
     ]);
-    return { code, out: out.trim(), err };
+    const chromeErr = await Bun.file(chromeLog)
+      .text()
+      .catch(() => "");
+    return { code, out: out.trim(), log: `${err}\nChrome's stderr:\n${chromeErr}` };
   } finally {
     child.kill();
     await rm(dir, { recursive: true, force: true });
@@ -112,12 +120,12 @@ describe("PreviewView", () => {
     async () => {
       const server = serve("<!doctype html><title>Up</title><body>up</body>");
       try {
-        const { code, out, err } = await withSlowChrome(
+        const { code, out, log } = await withSlowChrome(
           `const probe = await PreviewView.probe("http://localhost:${server.port}/", { engine: "chrome", timeoutMs: 1_500 });
 console.log(probe.text);`,
         );
-        expect(out || err).toBe("up");
-        expect(code).toBe(0);
+        expect(out, log).toBe("up");
+        expect(code, log).toBe(0);
       } finally {
         server.stop(true);
       }
@@ -128,7 +136,7 @@ console.log(probe.text);`,
   test.skipIf(!slowChromeRuns)(
     "gives a later page only its own bound for a browser that missed its start, and recovers once it is up",
     async () => {
-      const { code, out, err } = await withSlowChrome(
+      const { code, out, log } = await withSlowChrome(
         `const open = () =>
   PreviewView.probe("about:blank", { engine: "chrome", startTimeoutMs: 1_500, timeoutMs: 1_000 }).then(
     () => "opened",
@@ -137,7 +145,7 @@ console.log(probe.text);`,
 console.log(await open());
 console.log(await open());
 let late = await open();
-for (let tries = 0; late !== "opened" && tries < 100; tries++) late = await open();
+for (let tries = 0; late.startsWith("Timed out starting") && tries < 100; tries++) late = await open();
 console.log(late);
 Bun.WebView.closeAll();
 await Bun.sleep(500);
@@ -145,7 +153,7 @@ console.log(await open());
 Bun.WebView.closeAll();`,
         6,
       );
-      expect(out || err).toBe(
+      expect(out, log).toBe(
         [
           "Timed out starting the chrome browser after 1.5 s.",
           "Timed out starting the chrome browser after 1 s.",
@@ -153,7 +161,66 @@ Bun.WebView.closeAll();`,
           "Timed out starting the chrome browser after 1.5 s.",
         ].join("\n"),
       );
-      expect(code).toBe(0);
+      expect(code, log).toBe(0);
+    },
+    browserTestMs,
+  );
+
+  test.skipIf(!slowChromeRuns)(
+    "gives a browser killed after it missed its start the full bound for its next start",
+    async () => {
+      const { code, out, log } = await withSlowChrome(
+        `const open = () =>
+  PreviewView.probe("about:blank", { engine: "chrome", startTimeoutMs: 1_500, timeoutMs: 1_000 }).then(
+    () => "opened",
+    (error) => error.message,
+  );
+console.log(await open());
+const killed = open();
+Bun.WebView.closeAll();
+console.log(await killed);
+Bun.WebView.closeAll();`,
+        6,
+      );
+      expect(out, log).toBe(
+        [
+          "Timed out starting the chrome browser after 1.5 s.",
+          "Timed out starting the chrome browser after 1.5 s.",
+        ].join("\n"),
+      );
+      expect(code, log).toBe(0);
+    },
+    browserTestMs,
+  );
+
+  test.skipIf(!slowChromeRuns)(
+    "starts a new browser for the page right after one that the browser died on",
+    async () => {
+      const { code, out, log } = await withSlowChrome(
+        `const { promise: loading, resolve } = Promise.withResolvers();
+const server = Bun.serve({
+  port: 0,
+  fetch: (req) =>
+    new URL(req.url).pathname === "/hang"
+      ? (resolve(), new Promise(() => undefined))
+      : new Response("<!doctype html><body>up</body>", { headers: { "content-type": "text/html" } }),
+});
+const open = (path) =>
+  PreviewView.probe(\`http://localhost:\${server.port}\${path}\`, { engine: "chrome" }).then(
+    (probe) => probe.text,
+    (error) => error.message,
+  );
+const killed = open("/hang");
+await loading;
+Bun.WebView.closeAll();
+console.error(await killed);
+console.log(await open("/"));
+server.stop(true);
+Bun.WebView.closeAll();`,
+        0,
+      );
+      expect(out, log).toBe("up");
+      expect(code, log).toBe(0);
     },
     browserTestMs,
   );

package/workflow/index.ts

@@ -6,6 +6,7 @@ export * from "./keyRename";
 export * from "./moduleIndex";
 export * from "./mutationScaffold";
 export * from "./mutationSource";
+export * from "./plainName";
 export * from "./plan";
 export * from "./render";
 export * from "./rolloutGate";

package/workflow/plainName.ts

@@ -0,0 +1,28 @@
+export const sysNamePattern = /^[a-z0-9][a-zA-Z0-9_-]*$/;
+export const identifierPattern = /^_{0,2}[a-zA-Z][a-zA-Z0-9_-]*$/;
+const packageNamePattern = /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+
+export type PlainNameKind = "app" | "lib" | "module" | "service" | "scalar";
+
+export const isWorkflowSysName = (value: unknown): value is string =>
+  typeof value === "string" && sysNamePattern.test(value);
+export const isWorkflowModuleName = (value: unknown): value is string =>
+  typeof value === "string" && identifierPattern.test(value);
+
+export const plainNameProblem = (kind: PlainNameKind, name: string) => {
+  const isSys = kind === "app" || kind === "lib";
+  if (isSys ? isWorkflowSysName(name) : isWorkflowModuleName(name)) return null;
+  return `${JSON.stringify(name)} is no ${kind} name; use letters, digits, - and _, starting with ${isSys ? "a lowercase letter or digit" : "a letter"}`;
+};
+
+export const assertPlainName = (kind: PlainNameKind, name: string) => {
+  const problem = plainNameProblem(kind, name);
+  if (problem) throw new Error(problem);
+};
+
+export const assertPackageName = (name: string) => {
+  if (packageNamePattern.test(name)) return;
+  throw new Error(
+    `${JSON.stringify(name)} is no package name; use name or @scope/name, each of lowercase letters, digits, -, . and _, starting with a letter or digit`,
+  );
+};

package/workflow/plan.ts

@@ -5,6 +5,7 @@ import { resolveWorkflowSys } from "./executor";
 import { InteractionScaffold } from "./interactionScaffold";
 import { KeyRename } from "./keyRename";
 import { MutationScaffold } from "./mutationScaffold";
+import { identifierPattern, sysNamePattern } from "./plainName";
 import { coerceFieldDefault, getSysRoot, moduleSourcePaths } from "./source";
 import type {
   WorkflowDiagnostic,
@@ -21,8 +22,6 @@ import { workflowStatus } from "./utils";
 
 const surfaceModes = new Set<WorkflowSurfaceMode>(["infer", "include", "skip"]);
 
-const sysNamePattern = /^[a-z0-9][a-zA-Z0-9_-]*$/;
-const identifierPattern = /^_{0,2}[a-zA-Z][a-zA-Z0-9_-]*$/;
 //? These inputs become path segments, identifiers and command arguments, so none may carry a separator or a dot.
 const nameInputPatterns: Record<string, RegExp> = {
   app: sysNamePattern,
@@ -36,11 +35,6 @@ const nameInputPatterns: Record<string, RegExp> = {
   interaction: identifierPattern,
 };
 
-export const isWorkflowSysName = (value: unknown): value is string =>
-  typeof value === "string" && sysNamePattern.test(value);
-export const isWorkflowModuleName = (value: unknown): value is string =>
-  typeof value === "string" && identifierPattern.test(value);
-
 const parseStringList = (value: unknown) => {
   if (Array.isArray(value)) {
     const values = value.filter((item): item is string => typeof item === "string" && item.trim().length > 0);

package/workspaceGraph.test.ts

@@ -3,6 +3,7 @@ import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import type { AkanChangeMap, AkanGraphEdge, AkanGraphNode } from "@akanjs/language";
+import { AkanGraphDiff } from "@akanjs/language";
 import type { Workspace } from "./commandDecorators";
 import { WorkspaceGraph } from "./workspaceGraph";
 
@@ -186,6 +187,89 @@ describe("WorkspaceGraph.scope", () => {
     expect(scoped.nodes.map(({ id }) => id)).toEqual([guard, own]);
     expect(scoped.edges).toEqual([edge(own, guard)]);
   });
+
+  it("follows a role the scope's method calls to the implementation its app binds", () => {
+    const role = "adaptor::LlmAdaptorRole";
+    const binds = (to: string, label: string): AkanGraphEdge => ({ ...edge(role, to), kind: "binds", label });
+    const graph = {
+      version: 1 as const,
+      nodes: [
+        { ...node("method:apps/sceny:plan.draft", "apps/sceny"), module: "plan" },
+        { ...node("method:apps/angelo:chat.reply", "apps/angelo"), module: "chat" },
+        { ...node("method:libs/genai:prompt.run", "libs/genai"), module: "prompt" },
+        node(role, null),
+        node("adaptor::AnthropicLlm", null),
+        node("adaptor:apps/angelo:ChatCompletionsLlm", "apps/angelo"),
+        node("adaptor:libs/genai:GenaiLlm", "libs/genai"),
+      ],
+      edges: [
+        edge("method:apps/sceny:plan.draft", role),
+        edge("method:apps/angelo:chat.reply", role),
+        edge("method:libs/genai:prompt.run", role),
+        binds("adaptor::AnthropicLlm", "apps/sceny"),
+        binds("adaptor:apps/angelo:ChatCompletionsLlm", "apps/angelo"),
+        binds("adaptor:libs/genai:GenaiLlm", "libs/genai"),
+      ],
+    };
+    const bound = (scope: { app?: string; module?: string }) =>
+      WorkspaceGraph.scope(graph, scope)
+        .edges.filter(({ kind }) => kind === "binds")
+        .map(({ to, label }) => `${label} ${to}`);
+    expect(bound({ app: "sceny" })).toEqual(["apps/sceny adaptor::AnthropicLlm"]);
+    expect(WorkspaceGraph.scope(graph, { app: "sceny" }).nodes.map(({ id }) => id)).toContain("adaptor::AnthropicLlm");
+    expect(bound({ app: "angelo" })).toEqual(["apps/angelo adaptor:apps/angelo:ChatCompletionsLlm"]);
+    expect(bound({ app: "genai" })).toEqual([
+      "apps/sceny adaptor::AnthropicLlm",
+      "apps/angelo adaptor:apps/angelo:ChatCompletionsLlm",
+      "libs/genai adaptor:libs/genai:GenaiLlm",
+    ]);
+    expect(bound({ module: "plan" })).toHaveLength(3);
+    expect(
+      WorkspaceGraph.visibleTo(graph, "sceny")
+        .edges.filter(({ kind }) => kind === "binds")
+        .map(({ label }) => label),
+    ).toEqual(["apps/sceny"]);
+  });
+
+  it("scopes a Change Map to the binding the app runs, whether or not that binding changed", () => {
+    const role = "adaptor::LlmAdaptorRole";
+    const versioned = (id: string, owner: string | null, digest: string, module: string | null = null) => ({
+      ...node(id, owner),
+      module,
+      digest,
+      at: { file: `${owner ?? "akanjs"}/x.ts`, line: 1, column: 1 },
+    });
+    const binds = (to: string, label: string): AkanGraphEdge => ({ ...edge(role, to), kind: "binds", label });
+    const graphOf = (ownBinding: boolean, method: string, lib: string) => ({
+      version: 1 as const,
+      nodes: [
+        versioned("method:apps/sceny:plan.draft", "apps/sceny", method, "plan"),
+        node(role, null),
+        node("adaptor::AnthropicLlm", null),
+        versioned("adaptor:libs/genai:GenaiLlm", "libs/genai", lib),
+      ],
+      edges: [
+        edge("method:apps/sceny:plan.draft", role),
+        ...(ownBinding ? [binds("adaptor::AnthropicLlm", "apps/sceny")] : []),
+        binds("adaptor:libs/genai:GenaiLlm", "libs/genai"),
+      ],
+    });
+    const scopedBinds = (base: ReturnType<typeof graphOf>, head: ReturnType<typeof graphOf>) => {
+      const changes = { ...AkanGraphDiff.between(base, head), since: "0123456789ab", unmapped: [] };
+      const answer = WorkspaceGraph.answerChanges(changes, { app: "sceny" });
+      if (!("edges" in answer)) throw new Error("expected an answer");
+      return answer.edges
+        .filter(({ kind }) => kind === "binds")
+        .map(({ label, to, change }) => `${change ?? "unchanged"} ${label} ${to}`);
+    };
+    expect(scopedBinds(graphOf(true, "1", "1"), graphOf(true, "2", "2"))).toEqual([
+      "unchanged apps/sceny adaptor::AnthropicLlm",
+    ]);
+    expect(scopedBinds(graphOf(true, "1", "1"), graphOf(false, "1", "2"))).toEqual([
+      "unchanged libs/genai adaptor:libs/genai:GenaiLlm",
+      "removed apps/sceny adaptor::AnthropicLlm",
+    ]);
+  });
 });
 
 describe("WorkspaceGraph.changesAt", () => {

package/workspaceGraph.ts

@@ -1,6 +1,13 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { type AkanChangeMap, type AkanGraph, AkanGraphDiff, type AkanGraphNode, AkanIndex } from "@akanjs/language";
+import {
+  type AkanChangeMap,
+  type AkanGraph,
+  AkanGraphDiff,
+  type AkanGraphEdge,
+  type AkanGraphNode,
+  AkanIndex,
+} from "@akanjs/language";
 import ts from "typescript";
 import type { Workspace } from "./commandDecorators";
 import { GitRevision } from "./gitRevision";
@@ -109,9 +116,30 @@ export class WorkspaceGraph {
     //? A lib's guard is linked from every app's endpoints; through it, a scope would reach all of them.
     const guards = new Set(graph.nodes.filter((node) => node.kind === "guard").map((node) => node.id));
     const reaches = (id: string) => seeds.has(id) && !guards.has(id);
-    const edges = graph.edges.filter((edge) => reaches(edge.from) || reaches(edge.to));
-    const ids = new Set([...seeds, ...edges.flatMap((edge) => [edge.from, edge.to])]);
-    return { version: 1, nodes: graph.nodes.filter((node) => ids.has(node.id)), edges };
+    const edges = graph.edges.filter((edge) => edge.kind !== "binds" && (reaches(edge.from) || reaches(edge.to)));
+    const kept = new Set([...seeds, ...edges.flatMap((edge) => [edge.from, edge.to])]);
+    const isLib =
+      !!app &&
+      graph.nodes.some((node) => node.owner === `libs/${app}`) &&
+      !graph.nodes.some((node) => node.owner === `apps/${app}`);
+    const applicable = WorkspaceGraph.#bindingsOf(graph, app && !isLib ? `apps/${app}` : null);
+    const isOwn = (edge: AkanGraphEdge) => !module && !!owners?.has(edge.label ?? "");
+    const roles = new Set(
+      applicable.filter((edge) => isOwn(edge) || kept.has(edge.from) || reaches(edge.to)).map((edge) => edge.from),
+    );
+    const bindings = applicable.filter((edge) => roles.has(edge.from));
+    const ids = new Set([...kept, ...bindings.flatMap((edge) => [edge.from, edge.to])]);
+    return { version: 1, nodes: graph.nodes.filter((node) => ids.has(node.id)), edges: [...edges, ...bindings] };
+  }
+
+  //? An app runs a role as its own `applyAdaptor` binds it, else as a lib's does; a lib's code runs under every app's.
+  static #bindingsOf(graph: AkanGraph, appOwner: string | null) {
+    const binds = graph.edges.filter((edge) => edge.kind === "binds");
+    if (!appOwner) return binds;
+    const own = new Set(
+      binds.filter((edge) => edge.label === appOwner && edge.change !== "removed").map((edge) => edge.from),
+    );
+    return binds.filter((edge) => edge.label === appOwner || (!edge.label?.startsWith("apps/") && !own.has(edge.from)));
   }
 
   //? Pages are many and most only wrap one another, so a graph too large to answer whole drops the pages that neither
@@ -141,7 +169,14 @@ export class WorkspaceGraph {
     const isVisible = ({ owner }: AkanGraphNode) => !owner || owner === appOwner || owner.startsWith("libs/");
     const nodes = graph.nodes.filter(isVisible);
     const ids = new Set(nodes.map((node) => node.id));
-    return { version: 1, nodes, edges: graph.edges.filter((edge) => ids.has(edge.from) && ids.has(edge.to)) };
+    const bindings = new Set(WorkspaceGraph.#bindingsOf(graph, appOwner));
+    return {
+      version: 1,
+      nodes,
+      edges: graph.edges.filter(
+        (edge) => ids.has(edge.from) && ids.has(edge.to) && (edge.kind !== "binds" || bindings.has(edge)),
+      ),
+    };
   }
 
   static changesVisibleTo(changes: AkanChangeMap, app: string): AkanChangeMap {

package/constantFieldNames.ts

@@ -1,18 +0,0 @@
-import ts from "typescript";
-
-const isFieldCall = (node: ts.Expression): boolean =>
-  ts.isCallExpression(node) &&
-  (ts.isIdentifier(node.expression)
-    ? node.expression.text === "field"
-    : ts.isPropertyAccessExpression(node.expression) && isFieldCall(node.expression.expression));
-
-export const constantFieldNames = (content: string) => {
-  const names: string[] = [];
-  const visit = (node: ts.Node) => {
-    if (ts.isPropertyAssignment(node) && ts.isIdentifier(node.name) && isFieldCall(node.initializer))
-      names.push(node.name.text);
-    ts.forEachChild(node, visit);
-  };
-  visit(ts.createSourceFile("constant.ts", content, ts.ScriptTarget.Latest));
-  return names;
-};