@akanjs/devkit 3.1.1-rc.15 → 3.1.1-rc.16

package/workflow/mutationSource.ts

@@ -0,0 +1,219 @@
+import { lowerlize } from "akanjs/common";
+import { bilingualLabelForField, moduleComponentName, titleize } from "./source";
+
+export interface MutationCall {
+  ref: string;
+  method: string;
+  field: string | null;
+  args: string[];
+}
+
+export interface MutationActingUser {
+  argName: string;
+  param: string;
+  value: string;
+  serviceParam: string;
+}
+
+export interface MutationSourceSpec {
+  module: string;
+  mutation: string;
+  guards: readonly string[];
+  acting: MutationActingUser | null;
+  withCalls: readonly MutationCall[];
+  afterCalls: readonly MutationCall[];
+}
+
+export class MutationSource {
+  static readonly #irregularParticiples = new Map([
+    ["admit", "admitted"],
+    ["bind", "bound"],
+    ["build", "built"],
+    ["choose", "chosen"],
+    ["commit", "committed"],
+    ["control", "controlled"],
+    ["cut", "cut"],
+    ["find", "found"],
+    ["freeze", "frozen"],
+    ["get", "got"],
+    ["give", "given"],
+    ["hide", "hidden"],
+    ["hold", "held"],
+    ["keep", "kept"],
+    ["lead", "led"],
+    ["leave", "left"],
+    ["lose", "lost"],
+    ["make", "made"],
+    ["omit", "omitted"],
+    ["pay", "paid"],
+    ["permit", "permitted"],
+    ["put", "put"],
+    ["read", "read"],
+    ["run", "run"],
+    ["sell", "sold"],
+    ["send", "sent"],
+    ["set", "set"],
+    ["show", "shown"],
+    ["shut", "shut"],
+    ["split", "split"],
+    ["submit", "submitted"],
+    ["take", "taken"],
+    ["transfer", "transferred"],
+    ["win", "won"],
+    ["write", "written"],
+  ]);
+  readonly spec: MutationSourceSpec;
+  readonly modelClassName: string;
+  readonly model: string;
+  readonly idParam: string;
+  readonly chainMethod: string;
+
+  constructor(spec: MutationSourceSpec) {
+    this.spec = spec;
+    this.modelClassName = moduleComponentName(spec.module);
+    this.model = lowerlize(this.modelClassName);
+    this.idParam = `${this.model}Id`;
+    this.chainMethod = MutationSource.chainMethodOf(spec.mutation, this.modelClassName);
+  }
+
+  static chainMethodOf(mutation: string, modelClassName: string) {
+    const dropped = mutation.replace(modelClassName, "");
+    return dropped && dropped !== mutation ? lowerlize(dropped) : mutation;
+  }
+
+  static participleOf(verb: string) {
+    const irregular = MutationSource.#irregularParticiples.get(verb);
+    if (irregular) return irregular;
+    if (verb.endsWith("e")) return `${verb}d`;
+    if (/[^aeiou]y$/.test(verb)) return `${verb.slice(0, -1)}ied`;
+    if (/^[^aeiou]*[aeiou][^aeiouwxy]$/.test(verb)) return `${verb}${verb.at(-1)}ed`;
+    return `${verb}ed`;
+  }
+
+  get isPublic() {
+    return this.spec.guards.includes("Public");
+  }
+
+  get #verb() {
+    return this.chainMethod.replace(/[A-Z].*$/s, "");
+  }
+
+  get #noun() {
+    return titleize(this.model).toLowerCase();
+  }
+
+  get chainMethodBlock() {
+    return [
+      `  // any → ${MutationSource.participleOf(this.#verb)}.`,
+      `  ${this.chainMethod}() {`,
+      "    return this;",
+      "  }",
+    ].join("\n");
+  }
+
+  get serviceMethod() {
+    return this.chainMethod;
+  }
+
+  get serviceMethodBlock() {
+    const { acting } = this.spec;
+    const params = [`${this.idParam}: string`, ...(acting ? [`${acting.serviceParam}: string`] : [])];
+    const load = `const ${this.model} = await this.get${this.modelClassName}(${this.idParam});`;
+    const owned = acting
+      ? [
+          `// TODO: ${this.spec.guards.join(" and ")} admits any signed-in caller; refuse a ${acting.serviceParam} that may not ${this.#verb} this ${this.#noun}.`,
+        ]
+      : [];
+    const chained = `${this.model}.${this.chainMethod}().save()`;
+    const head = `  async ${this.serviceMethod}(${params.join(", ")}) {`;
+    if (!this.spec.withCalls.length && !this.spec.afterCalls.length)
+      return [head, `    ${load}`, ...owned.map((line) => `    ${line}`), `    return await ${chained};`, "  }"].join(
+        "\n",
+      );
+    return [
+      head,
+      "    return await this.transaction(async () => {",
+      `      ${load}`,
+      ...owned.map((line) => `      ${line}`),
+      `      await ${chained};`,
+      ...this.spec.withCalls.map((call) => `      await ${MutationSource.#callOf(call)};`),
+      ...this.spec.afterCalls.map((call) => `      await this.afterCommit(() => ${MutationSource.#callOf(call)});`),
+      `      return ${this.model};`,
+      "    });",
+      "  }",
+    ].join("\n");
+  }
+
+  get signalEntry() {
+    const options = this.isPublic
+      ? `{ guards: [${this.spec.guards.join(", ")}], rateLimit: { calls: 20 } }`
+      : `{ guards: [${this.spec.guards.join(", ")}] }`;
+    const { acting } = this.spec;
+    const execParams = [this.idParam, ...(acting ? [acting.param] : [])];
+    const serviceArgs = [this.idParam, ...(acting ? [acting.value] : [])];
+    return [
+      `${this.spec.mutation}: mutation(cnst.${this.modelClassName}, ${options})`,
+      `    .param("${this.idParam}", ID)`,
+      ...(acting ? [`    .with(${acting.argName})`] : []),
+      `    .exec(async function (${execParams.join(", ")}) {`,
+      `      return await this.${this.model}Service.${this.serviceMethod}(${serviceArgs.join(", ")});`,
+      "    }),",
+    ].join("\n");
+  }
+
+  get storeActionBlock() {
+    return [
+      `  async ${this.spec.mutation}(${this.idParam}: string) {`,
+      `    this.set${this.modelClassName}(await fetch.${this.spec.mutation}(${this.idParam}));`,
+      "  }",
+    ].join("\n");
+  }
+
+  dictionaryEntryOf(modelKo?: string) {
+    const label = bilingualLabelForField(this.spec.mutation);
+    const modelLabel = { ...bilingualLabelForField(this.model), ...(modelKo ? { ko: modelKo } : {}) };
+    const pair = (en: string, ko: string) => `[${JSON.stringify(en)}, ${JSON.stringify(ko)}]`;
+    const idPair = pair(`${modelLabel.en} ID`, `${modelLabel.ko} ID`);
+    return [
+      `${this.spec.mutation}: fn(${pair(label.en, label.ko)})`,
+      `      .desc(${pair(`API to ${label.en.toLowerCase()}`, `${label.ko} API`)})`,
+      "      .arg((t) => ({",
+      `        ${this.idParam}: t(${idPair}).desc(${idPair}),`,
+      "      })),",
+    ].join("\n");
+  }
+
+  get testTitles() {
+    const guards = this.spec.guards.join(" and ");
+    const participle = MutationSource.participleOf(this.#verb);
+    return [
+      `${this.spec.mutation} leaves the ${this.#noun} ${participle} for a caller ${guards} admits`,
+      ...(this.spec.guards.every((guard) => guard === "Public")
+        ? []
+        : [`${this.spec.mutation} refuses a caller ${guards} turns away`]),
+      ...(this.spec.acting
+        ? [`${this.spec.mutation} refuses a signed-in caller who may not ${this.#verb} the ${this.#noun}`]
+        : []),
+    ];
+  }
+
+  testCaseLines(itName: string, indent: string) {
+    return this.testTitles.map((title) => `${indent}${itName}.todo(${JSON.stringify(title)});`);
+  }
+
+  get testFile() {
+    return [
+      'import { describe, it } from "bun:test";',
+      "",
+      `describe(${JSON.stringify(`${this.modelClassName} Signal`)}, () => {`,
+      ...this.testCaseLines("it", "  "),
+      "});",
+      "",
+    ].join("\n");
+  }
+
+  static #callOf(call: MutationCall) {
+    const target = call.field ? `this.${call.field}` : "this";
+    return `${target}.${call.method}(${call.args.join(", ")})`;
+  }
+}

package/workflow/plan.ts

@@ -1,5 +1,9 @@
 import { capitalize } from "akanjs/common";
+import type { Workspace } from "../commandDecorators";
 import { workflowPlanApproval } from "./artifacts";
+import { resolveWorkflowSys } from "./executor";
+import { InteractionScaffold } from "./interactionScaffold";
+import { MutationScaffold } from "./mutationScaffold";
 import { coerceFieldDefault, moduleSourcePaths } from "./source";
 import type {
   WorkflowDiagnostic,
@@ -420,3 +424,53 @@ export const createWorkflowPlan = (spec: WorkflowSpec, rawInputs: Record<string,
     approval: workflowPlanApproval,
   };
 };
+
+const planString = (inputs: Record<string, WorkflowInputValue>, name: string) =>
+  typeof inputs[name] === "string" ? inputs[name] : null;
+const planStrings = (inputs: Record<string, WorkflowInputValue>, name: string) =>
+  Array.isArray(inputs[name]) ? inputs[name] : null;
+
+export const inspectWorkflowPlan = async (workspace: Workspace, plan: WorkflowPlan): Promise<WorkflowPlan> => {
+  if (plan.workflow !== "add-mutation" && plan.workflow !== "create-interaction") return plan;
+  const app = planString(plan.inputs, "app");
+  if (!app) return plan;
+  const sys = await resolveWorkflowSys(workspace, app).catch(() => null);
+  if (!sys)
+    return {
+      ...plan,
+      diagnostics: [
+        ...plan.diagnostics,
+        {
+          severity: "error",
+          code: "workflow-target-missing",
+          input: "app",
+          message: `No app or library named ${app}.`,
+        },
+      ],
+    };
+  const inspected =
+    plan.workflow === "add-mutation"
+      ? await MutationScaffold.build(
+          sys,
+          {
+            module: planString(plan.inputs, "module"),
+            mutation: planString(plan.inputs, "mutation"),
+            guards: planStrings(plan.inputs, "guard"),
+            withCalls: planStrings(plan.inputs, "with"),
+            afterCalls: planStrings(plan.inputs, "after"),
+          },
+          { strict: false },
+        )
+      : { ...(await InteractionScaffold.build(sys, planString(plan.inputs, "interaction"))), recommendations: [] };
+  const failedInputs = new Set(
+    plan.diagnostics.filter((diagnostic) => diagnostic.severity === "error").map((diagnostic) => diagnostic.input),
+  );
+  return {
+    ...plan,
+    diagnostics: [
+      ...plan.diagnostics,
+      ...inspected.diagnostics.filter((diagnostic) => !diagnostic.input || !failedInputs.has(diagnostic.input)),
+    ],
+    recommendations: [...plan.recommendations, ...inspected.recommendations],
+  };
+};

package/workflow/render.ts

@@ -33,7 +33,13 @@ export const renderWorkflowList = (specs: readonly WorkflowSpec[]) =>
   [
     "# Akan Workflows",
     "",
-    ...specs.flatMap((spec) => [`- \`${spec.name}\`: ${spec.description}`, `  - When: ${spec.whenToUse}`]),
+    ...specs.flatMap((spec) => [
+      `- \`${spec.name}\`: ${spec.description}`,
+      `  - When: ${spec.whenToUse}`,
+      ...(spec.replacesRules?.length
+        ? [`  - Fixes: ${spec.replacesRules.map((rule) => `\`${rule}\``).join(", ")}`]
+        : []),
+    ]),
     "",
   ].join("\n");
 
@@ -46,6 +52,14 @@ export const renderWorkflowExplain = (spec: WorkflowSpec) =>
     "## When To Use",
     spec.whenToUse,
     "",
+    ...(spec.replacesRules?.length
+      ? [
+          "## Replaces Rules",
+          "This path is the fix when lint or the gate reports:",
+          ...spec.replacesRules.map((rule) => `- \`${rule}\``),
+          "",
+        ]
+      : []),
     "## Inputs",
     ...Object.entries(spec.inputs).map(
       ([name, input]) =>

package/workflow/source.test.ts

@@ -1,9 +1,15 @@
 import { describe, expect, test } from "bun:test";
 import {
+  appendTopLevelTestCases,
+  classMethodParameters,
+  ensureImportDeclaration,
+  ensureNamedImport,
   hasClassMethod,
+  hasDictionaryEndpointEntry,
   hasSignalFactoryEntry,
   hasSourceParseErrors,
   insertClassMethod,
+  insertDictionaryEndpointEntry,
   insertSignalFactoryEntry,
   inspectDictionaryStructure,
 } from "./source";
@@ -173,3 +179,127 @@ export class BannerEndpoint extends endpoint(srv.banner, ({ mutation }) => ({
     expect(next).toBe(content);
   });
 });
+
+describe("import editing", () => {
+  const signal = `import { endpoint, internal, slice } from "akanjs/signal";
+
+import * as srv from "../srv";
+`;
+
+  test("adds a name in Biome's order and keeps a type modifier", () => {
+    const content = 'import { type Dayjs, dayjs } from "akanjs/base";\n';
+
+    expect(ensureNamedImport(content, "akanjs/base", "ID")).toBe(
+      'import { type Dayjs, dayjs, ID } from "akanjs/base";\n',
+    );
+    expect(ensureNamedImport(signal, "akanjs/signal", "None")).toContain(
+      'import { endpoint, internal, None, slice } from "akanjs/signal";',
+    );
+  });
+
+  test("never adds a value name to a type-only import", () => {
+    const next = ensureNamedImport('import type { Guard } from "akanjs/signal";\n', "akanjs/signal", "Public");
+
+    expect(next).toContain('import type { Guard } from "akanjs/signal";');
+    expect(next).toContain('import { Public } from "akanjs/signal";');
+  });
+
+  test("puts a new declaration in its chunk, in source order", () => {
+    const withPackages = ensureNamedImport(
+      ensureNamedImport(signal, "akanjs/base", "ID"),
+      "@libs/shared/srvkit",
+      "Admin",
+    );
+    const withRelative = ensureImportDeclaration(withPackages, "../cnst", "* as cnst");
+
+    expect(withRelative).toBe(`import { Admin } from "@libs/shared/srvkit";
+import { ID } from "akanjs/base";
+import { endpoint, internal, slice } from "akanjs/signal";
+
+import * as cnst from "../cnst";
+import * as srv from "../srv";
+`);
+    expect(
+      ensureImportDeclaration('import { serve } from "akanjs/service";\n\nexport {};\n', "../srv", "type * as srv"),
+    ).toBe('import { serve } from "akanjs/service";\n\nimport type * as srv from "../srv";\n\nexport {};\n');
+  });
+});
+
+describe("dictionary endpoint entries", () => {
+  const dictionary = `export const dictionary = modelDictionary(["en", "ko"])
+  .slice<TaskSlice>((fn) => ({}))
+  .endpoint<TaskEndpoint>((fn) => ({}))
+  .error({})
+  .translate({});
+`;
+
+  test("inserts an entry into the endpoint stage and finds it again", () => {
+    const next = insertDictionaryEndpointEntry(
+      dictionary,
+      "Task",
+      "archiveTask",
+      'archiveTask: fn(["Archive", "보관"]),',
+    );
+
+    expect(next).toContain('.endpoint<TaskEndpoint>((fn) => ({\n    archiveTask: fn(["Archive", "보관"]),\n  }))');
+    expect(hasDictionaryEndpointEntry(next ?? "", "Task", "archiveTask")).toBe(true);
+    expect(hasDictionaryEndpointEntry(dictionary, "Task", "archiveTask")).toBe(false);
+  });
+
+  test("answers null when the dictionary has no endpoint stage for the model", () => {
+    expect(insertDictionaryEndpointEntry(dictionary, "Note", "pinNote", "pinNote: fn([]),")).toBeNull();
+  });
+});
+
+describe("classMethodParameters", () => {
+  test("reads names and which parameters a caller may leave out", () => {
+    const content = `export class NoteService {
+  async pushNote(taskId: string, note?: string, retries = 3) {}
+}`;
+
+    expect(classMethodParameters(content, "NoteService", "pushNote")).toEqual([
+      { name: "taskId", optional: false },
+      { name: "note", optional: true },
+      { name: "retries", optional: true },
+    ]);
+    expect(classMethodParameters(content, "NoteService", "missing")).toBeNull();
+  });
+});
+
+describe("appendTopLevelTestCases", () => {
+  const render = (itName: string, indent: string) => [`${indent}${itName}.todo("archives");`];
+
+  test("appends inside the outermost describe with the runner name the file imports", () => {
+    const content = `import { describe, expect, test } from "bun:test";
+
+describe("Task Signal", () => {
+  test("creates", () => {
+    expect(1).toBe(1);
+  });
+});
+`;
+
+    expect(
+      appendTopLevelTestCases(content, "Task Signal", render),
+    ).toBe(`import { describe, expect, test } from "bun:test";
+
+describe("Task Signal", () => {
+  test("creates", () => {
+    expect(1).toBe(1);
+  });
+  test.todo("archives");
+});
+`);
+  });
+
+  test("adds a describe when the file has none", () => {
+    const next = appendTopLevelTestCases('import { expect } from "bun:test";\n', "Task Signal", render);
+
+    expect(next).toBe(`import { describe, expect, it } from "bun:test";
+
+describe("Task Signal", () => {
+  it.todo("archives");
+});
+`);
+  });
+});

package/workflow/source.ts

@@ -41,6 +41,7 @@ export const moduleSourcePaths = (moduleName: string) => {
     abstract: `lib/${moduleName}/${moduleName}.abstract.md`,
     constant: `lib/${moduleName}/${moduleName}.constant.ts`,
     dictionary: `lib/${moduleName}/${moduleName}.dictionary.ts`,
+    document: `lib/${moduleName}/${moduleName}.document.ts`,
     service: `lib/${moduleName}/${moduleName}.service.ts`,
     signal: `lib/${moduleName}/${moduleName}.signal.ts`,
     store: `lib/${moduleName}/${moduleName}.store.ts`,
@@ -189,20 +190,52 @@ export const normalizeFieldType = (typeName: string) => {
   return normalizedTypes[typeName.toLowerCase()] ?? typeName;
 };
 
+//? Biome's organizeImports order: case-insensitive, an uppercase name before its lowercase twin.
+const importOrder = (a: string, b: string) => {
+  const [lowerA, lowerB] = [a.toLowerCase(), b.toLowerCase()];
+  if (lowerA !== lowerB) return lowerA < lowerB ? -1 : 1;
+  return a < b ? -1 : a > b ? 1 : 0;
+};
+
 export const ensureNamedImport = (content: string, moduleSpecifier: string, name: string) => {
   const source = sourceFileFor("source.ts", content);
-  const namedImport = findNamedImport(source, moduleSpecifier);
-  if (namedImport) {
-    if (namedImport.names.includes(name)) return content;
-    const nextNames = [...namedImport.names, name].sort();
-    return spliceText(
-      content,
-      namedImport.namedBindingsStart,
-      namedImport.namedBindingsEnd,
-      `{ ${nextNames.join(", ")} }`,
+  const namedImport = findNamedImport(source, moduleSpecifier, { valueOnly: true });
+  if (!namedImport) return ensureImportDeclaration(content, moduleSpecifier, `{ ${name} }`);
+  if (namedImport.names.includes(name)) return content;
+  const nextElements = [...namedImport.elements, { name, text: name }].sort((a, b) => importOrder(a.name, b.name));
+  return spliceText(
+    content,
+    namedImport.namedBindingsStart,
+    namedImport.namedBindingsEnd,
+    `{ ${nextElements.map((element) => element.text).join(", ")} }`,
+  );
+};
+
+export const ensureImportDeclaration = (content: string, moduleSpecifier: string, clause: string) => {
+  const line = `import ${clause} from "${moduleSpecifier}";`;
+  if (content.includes(line)) return content;
+  const source = sourceFileFor("source.ts", content);
+  const imports = source.statements
+    .filter((statement): statement is ts.ImportDeclaration => ts.isImportDeclaration(statement))
+    .flatMap((statement) =>
+      ts.isStringLiteral(statement.moduleSpecifier)
+        ? [{ specifier: statement.moduleSpecifier.text, start: statement.getStart(source), end: statement.getEnd() }]
+        : [],
     );
+  const isRelative = (specifier: string) => specifier.startsWith(".");
+  const peers = imports.filter((entry) => isRelative(entry.specifier) === isRelative(moduleSpecifier));
+  const before = peers.find((entry) => importOrder(entry.specifier, moduleSpecifier) > 0);
+  if (before) {
+    const insertAt = lineStartAt(content, before.start);
+    return spliceText(content, insertAt, insertAt, `${line}\n`);
+  }
+  const after = peers.at(-1) ?? (isRelative(moduleSpecifier) ? imports.at(-1) : undefined);
+  if (after) {
+    const insertAt = lineEndAt(content, after.end);
+    return spliceText(content, insertAt, insertAt, peers.length ? `${line}\n` : `\n${line}\n`);
   }
-  return `import { ${name} } from "${moduleSpecifier}";\n${content}`;
+  const insertAt = imports[0] ? lineStartAt(content, imports[0].start) : 0;
+  return spliceText(content, insertAt, insertAt, `${line}\n\n`);
 };
 
 export const ensureBaseImport = (content: string, name: string) => ensureNamedImport(content, "akanjs/base", name);
@@ -382,6 +415,7 @@ interface ArrayInsertionLocator {
 
 interface NamedImportLocator {
   names: string[];
+  elements: { name: string; text: string }[];
   namedBindingsStart: number;
   namedBindingsEnd: number;
 }
@@ -499,16 +533,23 @@ const dictionaryChainOrderValid = (chainMethods: readonly string[]) => {
   return true;
 };
 
-const findDictionaryModelObject = (source: ts.SourceFile, moduleClassName: string): DictionaryModelLocator | null => {
+const findDictionaryModelObject = (source: ts.SourceFile, moduleClassName: string) =>
+  findDictionaryStageObject(source, "model", moduleClassName);
+
+const findDictionaryStageObject = (
+  source: ts.SourceFile,
+  stage: string,
+  typeName: string,
+): DictionaryModelLocator | null => {
   let locator: DictionaryModelLocator | null = null;
   const visit = (node: ts.Node) => {
     if (locator) return;
-    if (!ts.isCallExpression(node) || callExpressionName(node) !== "model") {
+    if (!ts.isCallExpression(node) || callExpressionName(node) !== stage) {
       ts.forEachChild(node, visit);
       return;
     }
     const typeArgument = node.typeArguments?.[0];
-    if (!typeArgument || typeArgument.getText(source) !== moduleClassName) {
+    if (!typeArgument || typeArgument.getText(source) !== typeName) {
       ts.forEachChild(node, visit);
       return;
     }
@@ -556,14 +597,20 @@ const findLightProjectionArray = (source: ts.SourceFile, moduleClassName: string
   return locator;
 };
 
-const findNamedImport = (source: ts.SourceFile, moduleSpecifier: string): NamedImportLocator | null => {
+const findNamedImport = (
+  source: ts.SourceFile,
+  moduleSpecifier: string,
+  { valueOnly = false }: { valueOnly?: boolean } = {},
+): NamedImportLocator | null => {
   for (const statement of source.statements) {
     if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) continue;
     if (statement.moduleSpecifier.text !== moduleSpecifier) continue;
+    if (valueOnly && statement.importClause?.isTypeOnly) continue;
     const namedBindings = statement.importClause?.namedBindings;
     if (!namedBindings || !ts.isNamedImports(namedBindings)) continue;
     return {
       names: namedBindings.elements.map((element) => element.name.text),
+      elements: namedBindings.elements.map((element) => ({ name: element.name.text, text: element.getText(source) })),
       namedBindingsStart: namedBindings.getStart(source),
       namedBindingsEnd: namedBindings.getEnd(),
     };
@@ -816,6 +863,27 @@ export const hasDictionaryModelField = (content: string, moduleClassName: string
   return findDictionaryModelObject(source, moduleClassName)?.fields.some((field) => field.name === fieldName) ?? false;
 };
 
+export const hasDictionaryEndpointEntry = (content: string, moduleClassName: string, entryName: string) => {
+  const source = sourceFileFor("dictionary.ts", content);
+  return (
+    findDictionaryStageObject(source, "endpoint", `${moduleClassName}Endpoint`)?.fields.some(
+      (field) => field.name === entryName,
+    ) ?? false
+  );
+};
+
+export const insertDictionaryEndpointEntry = (
+  content: string,
+  moduleClassName: string,
+  entryName: string,
+  entryText: string,
+) => {
+  const source = sourceFileFor("dictionary.ts", content);
+  const locator = findDictionaryStageObject(source, "endpoint", `${moduleClassName}Endpoint`);
+  if (!locator) return null;
+  return insertOrderedFieldLine(content, locator, entryName, entryText, { fieldIndent: "    ", closingIndent: "  " });
+};
+
 export const ensureConstantTypeImport = (content: string, constantPath: string, typeName: string) => {
   if (new RegExp(`import type \\{[^}]*\\b${typeName}\\b[^}]*\\} from "${constantPath}";`).test(content)) return content;
   const importPattern = new RegExp(`import type \\{ ([^}]+) \\} from "${constantPath}";`);
@@ -883,6 +951,19 @@ export const hasClassMethod = (content: string, className: string, methodName: s
   );
 };
 
+export const classMethodParameters = (content: string, className: string, methodName: string) => {
+  const source = sourceFileFor("service.ts", content);
+  const method = findClassDeclaration(source, className)?.members.find(
+    (member): member is ts.MethodDeclaration => ts.isMethodDeclaration(member) && nodeName(member.name) === methodName,
+  );
+  return (
+    method?.parameters.map((parameter) => ({
+      name: nodeName(parameter.name),
+      optional: !!parameter.questionToken || !!parameter.initializer || !!parameter.dotDotDotToken,
+    })) ?? null
+  );
+};
+
 export const insertClassMethod = (content: string, className: string, methodBlock: string): string | null => {
   const source = sourceFileFor("service.ts", content);
   const node = findClassDeclaration(source, className);
@@ -976,3 +1057,30 @@ export const insertSignalFactoryEntry = (
   if (withEntry === content) return null;
   return paramEdit === "unchanged" ? withEntry : spliceText(withEntry, paramEdit.start, paramEdit.end, paramEdit.text);
 };
+
+export const appendTopLevelTestCases = (
+  content: string,
+  describeTitle: string,
+  render: (itName: string, indent: string) => string[],
+) => {
+  const bunImport = findNamedImport(sourceFileFor("test.ts", content), "bun:test", { valueOnly: true });
+  const itName = !bunImport?.names.includes("it") && bunImport?.names.includes("test") ? "test" : "it";
+  const imported = ensureNamedImport(content, "bun:test", itName);
+  const source = sourceFileFor("test.ts", imported);
+  const body = source.statements.flatMap((statement) => {
+    if (!ts.isExpressionStatement(statement) || !ts.isCallExpression(statement.expression)) return [];
+    if (expressionName(statement.expression.expression) !== "describe") return [];
+    const callback = factoryArrowOf(statement.expression);
+    return callback && ts.isBlock(callback.body) ? [callback.body] : [];
+  })[0];
+  if (!body) {
+    const block = [`describe(${JSON.stringify(describeTitle)}, () => {`, ...render(itName, "  "), "});", ""];
+    return `${ensureNamedImport(imported, "bun:test", "describe").trimEnd()}\n\n${block.join("\n")}`;
+  }
+  const firstStatement = body.statements[0];
+  const indent = firstStatement
+    ? lineIndentAt(imported, firstStatement.getStart(source))
+    : `${lineIndentAt(imported, body.getStart(source))}  `;
+  const insertAt = lineStartAt(imported, body.getEnd() - 1);
+  return spliceText(imported, insertAt, insertAt, `${render(itName, indent).join("\n")}\n`);
+};