quixos-protocol/test/scaffold-recipes.test.ts

import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { execFile as callback } from "node:child_process";
import { promisify } from "node:util";
import { scaffoldRecipe } from "../src/capability-language/scaffold-recipes.js";
import { planStructure, applyStructure } from "../src/capability-language/structural-plan.js";
import { contentDigest } from "../src/capability-model/evolution.js";
import { sealMigrations } from "../src/capability-language/migration-seal.js";
import { reactPlatformTypes } from "../src/bindings/react-platform.js";
const execFile = promisify(callback);

test("React preset applies its browser build script and shared-platform imports", async (context) => {
  const root = await fs.mkdtemp(path.join(os.tmpdir(), "qx-react-recipe-"));
  context.after(() => fs.rm(root, { recursive: true, force: true }));
  await execFile("git", ["-C", root, "init"]);
  const source = { repository: "https://example.test/react.git", commit: "a".repeat(40) };
  const request = await scaffoldRecipe(root, "package", {
    source,
    name: "React",
    id: "package:react",
    revision: "package:react@1",
    template: "typescript-react",
    tools: { quixos: source, protocol: source, helpers: source, sdk: source },
  });
  await applyStructure(await planStructure(root, request));
  assert.match(await fs.readFile(path.join(root, "src/impl/sourceGet.ts"), "utf8"), /component.js\?browser-source/);
  assert.match(await fs.readFile(path.join(root, "flake.nix"), "utf8"), /browserSources = true/);
  assert.equal(await fs.readFile(path.join(root, "src/gen/web-studio-react-runtime.d.ts"), "utf8"), reactPlatformTypes);
  assert.match(await fs.readFile(path.join(root, "src/browser-assets.d.ts"), "utf8"), /declare module "\*\.css"/);
  assert.deepEqual(
    JSON.parse(await fs.readFile(path.join(root, "quixos.check.json"), "utf8")).options.react.propsExports,
    [],
  );
  await assert.rejects(fs.access(path.join(root, "quixos.scaffold.json")));
  assert.equal(
    JSON.parse(await fs.readFile(path.join(root, "tsconfig.json"), "utf8")).compilerOptions.jsx,
    "react-jsx",
  );
});

test("imperative scaffolds preserve authored wiring; migration sealing is explicit and separate", async (context) => {
  const root = await fs.mkdtemp(path.join(os.tmpdir(), "qx-recipes-"));
  context.after(() => fs.rm(root, { recursive: true, force: true }));
  await execFile("git", ["-C", root, "init"]);
  await fs.writeFile(path.join(root, ".gitignore"), ".quixos/\n");
  const source = { repository: "https://example.test/chess.git", commit: "a".repeat(40) };
  const base = { source, directory: "packages/Chess" };
  const apply = async (command: Parameters<typeof scaffoldRecipe>[1], input: Parameters<typeof scaffoldRecipe>[2]) =>
    applyStructure(await planStructure(root, await scaffoldRecipe(root, command, input)));
  await apply("package", {
    ...base,
    name: "Chess",
    id: "package:chess",
    revision: "package:chess@1",
    tools: { quixos: source, protocol: source, helpers: source, sdk: source },
  });
  await apply("function", { ...base, name: "play", id: "export:play" });
  const filename = path.join(root, base.directory, "src/impl/play.ts");
  const edited =
    'import type {Implementation} from "../gen/qx.js";\nexport const handler: Implementation["play"] = async () => null;\n';
  await fs.writeFile(filename, edited);
  const old = { version: 1 },
    next = { version: 2 },
    from = contentDigest(old),
    to = contentDigest(next);
  await apply("migration", {
    ...base,
    name: "upgrade",
    id: "export:upgrade",
    migration: {
      id: "upgrade-v2",
      scopeId: "board",
      from,
      to,
      predecessors: [],
      ports: [],
      contracts: { [from]: old, [to]: next },
    },
  });
  const migrationFile = path.join(root, base.directory, "src/migrations/upgrade.ts");
  await fs.appendFile(migrationFile, "\n// authored migration change\n");
  await sealMigrations(path.join(root, base.directory));
  assert.equal(await fs.readFile(filename, "utf8"), edited);
  const catalog = JSON.parse(await fs.readFile(path.join(root, base.directory, "quixos.migrations.json"), "utf8"));
  assert.equal(catalog.migrations[0].implementation.digest, contentDigest(await fs.readFile(migrationFile, "utf8")));
  assert.match(await fs.readFile(path.join(root, base.directory, "src/migrate.ts"), "utf8"), /export:upgrade/);
  await assert.rejects(() => apply("function", { ...base, name: "play", id: "export:play" }), /unique/);
  const declarations = path.join(root, base.directory, "package.qx");
  await fs.writeFile(
    declarations,
    (await fs.readFile(declarations, "utf8")).replace(
      /}\s*$/,
      '  function authored id "export:authored" : unit -> unit;\n}\n',
    ),
  );
  const server = path.join(root, base.directory, "src/server.ts");
  await fs.appendFile(server, "\n// authored comment must survive\n");
  await apply("function", { ...base, name: "another", id: "export:another" });
  assert.match(await fs.readFile(server, "utf8"), /authored comment must survive/);
  await assert.rejects(() => apply("refresh", base), /removed/);
  await assert.rejects(fs.access(path.join(root, base.directory, "src/impl/authored.ts")));
  assert.equal(await fs.readFile(filename, "utf8"), edited);
  await planStructure(root, {
    kind: "package",
    source,
    resourceRoot: base.directory,
    validation: "syntax",
    files: [
      {
        file: `${base.directory}/package.qx`,
        edits: [
          {
            operation: "replace",
            target: { kind: "packageResourceDecl", id: "package:chess" },
            source: 'package Other id "package:other" revision "package:other@1" {}',
          },
        ],
      },
    ],
  });
});

test("execution scaffolds route typed handlers by declared effect and target without legacy lifecycle files", async (context) => {
  const root = await fs.mkdtemp(path.join(os.tmpdir(), "qx-execution-recipe-"));
  context.after(() => fs.rm(root, { recursive: true, force: true }));
  await execFile("git", ["-C", root, "init"]);
  const source = { repository: "https://example.test/execution.git", commit: "a".repeat(40) };
  const apply = async (
    command: Parameters<typeof scaffoldRecipe>[1],
    spec: Partial<Parameters<typeof scaffoldRecipe>[2]>,
  ) => applyStructure(await planStructure(root, await scaffoldRecipe(root, command, { source, ...spec })));
  await apply("package", {
    name: "Execution",
    id: "package:execution",
    revision: "package:execution@1",
    template: "typescript-execution",
    tools: { quixos: source, protocol: source, helpers: source, sdk: source },
  });
  for (const file of ["quixos.migrations.json", "src/migrate.ts", "descriptor.quixos-package.txtpb"])
    await assert.rejects(fs.access(path.join(root, file)));
  await fs.appendFile(path.join(root, "src/server.ts"), "\n// Preserve authored code\n");
  const add = (name: string, execution: string) =>
    apply("function", {
      name,
      id: "export:" + name,
      declaration: `function ${name} id "export:${name}" : unit -> unit execution ${execution};`,
    });
  await add("both", "transaction targets [browser, server]");
  await add("serverOnly", "snapshot targets [server]");
  await add("asyncWork", "remote");
  const read = (file: string) => fs.readFile(path.join(root, file), "utf8");
  assert.match(await read("src/browser.ts"), /"both":/);
  assert.doesNotMatch(await read("src/browser.ts"), /serverOnly|asyncWork/);
  assert.match(await read("src/server.ts"), /"serverOnly":/);
  assert.match(await read("src/server.ts"), /Preserve authored code/);
  assert.match(await read("src/remote.ts"), /"asyncWork":/);
  assert.match(await read("src/impl/asyncWork.ts"), /RemoteImplementation/);
  assert.match(await read("src/impl/both.ts"), /PortableImplementation/);
  assert.match(await read("flake.nix"), /checkedArtifacts/);
  assert.match(await read("flake.nix"), /entries.browser/);
  await assert.rejects(add("both", "transaction targets [browser, server]"), /unique/);
  await assert.rejects(add("invalid", "snapshot targets [remote]"), /browser\/server/);
  await assert.rejects(apply("function", { name: "missing", id: "export:missing" }), /explicit execution/);
  await assert.rejects(apply("migration", { name: "migration", id: "export:migration" }), /not supported/);
});

test("query scaffold preserves placement and inserts its named GraphQL document atomically", async (context) => {
  const root = await fs.mkdtemp(path.join(os.tmpdir(), "qx-query-recipe-"));
  context.after(() => fs.rm(root, { recursive: true, force: true }));
  await execFile("git", ["-C", root, "init"]);
  const source = { repository: "https://example.test/query.git", commit: "a".repeat(40) };
  await fs.writeFile(
    path.join(root, "package.qx"),
    'import interface Task;\npackage Tasks id "tasks" revision "tasks@1" {}\n',
  );
  const request = (name: string, placement: string) => ({
    source,
    name,
    id: `tasks:${name}`,
    declaration: `query ${name} id "tasks:${name}" root Task document "queries/${name}.graphql" operation "${name}" { ${placement} max rows 100; }`,
    queryDocument: `query ${name} { root { title } }\n`,
  });
  for (const [name, placement] of [
    ["Inputs", "replica;"],
    ["Screen", "local from Inputs;"],
    ["Confirmed", ""],
  ]) {
    const spec = request(name, placement);
    const recipe = await scaffoldRecipe(root, "query", spec);
    const planned = await planStructure(root, recipe);
    await assert.rejects(fs.access(path.join(root, `queries/${name}.graphql`)), "Preview must not write files");
    await applyStructure(planned);
    assert.equal(await fs.readFile(path.join(root, `queries/${name}.graphql`), "utf8"), spec.queryDocument);
    assert.ok((await fs.readFile(path.join(root, "package.qx"), "utf8")).includes(placement));
    await assert.rejects(scaffoldRecipe(root, "query", spec), /unique/);
  }
  const bad = request("Bad", "replica;");
  await assert.rejects(
    scaffoldRecipe(root, "query", {
      ...bad,
      declaration: bad.declaration.replace("queries/Bad.graphql", "../Bad.graphql"),
    }),
    /contained/,
  );
  await assert.rejects(
    scaffoldRecipe(root, "query", { ...bad, queryDocument: "query Other { root { title } }" }),
    /declared named query/,
  );
  await assert.rejects(
    scaffoldRecipe(root, "query", { ...bad, queryDocument: "mutation Bad { title }" }),
    /declared named query/,
  );
  await assert.rejects(
    scaffoldRecipe(root, "query", { ...bad, declaration: bad.declaration + ' function x id "x" : unit -> unit;' }),
    /one QX query/,
  );
  await fs.mkdir(path.join(root, "queries"), { recursive: true });
  await fs.writeFile(path.join(root, "queries/Bad.graphql"), "# authored content\n");
  const before = await fs.readFile(path.join(root, "package.qx"), "utf8");
  await assert.rejects(planStructure(root, await scaffoldRecipe(root, "query", bad)), /existing file/);
  assert.equal(await fs.readFile(path.join(root, "package.qx"), "utf8"), before);
});