toiljs 0.0.121 → 0.0.123

package/build/cli/index.js

@@ -3510,7 +3510,7 @@ var PREPROCESSOR_PKG = {
 };
 var TAILWIND_PKGS = ["tailwindcss", "@tailwindcss/vite"];
 var PKG_VERSION = {
-  sass: "^1.104.1",
+  sass: "^1.105.1",
   less: "^4.9.1",
   stylus: "^0.64.0",
   tailwindcss: "^4.3.3",
@@ -4017,6 +4017,88 @@ import { fileURLToPath as fileURLToPath2 } from "node:url";
 var import_picocolors3 = __toESM(require_picocolors(), 1);
 import { AI_HELPER_IDS, AI_HELPERS, aiHelperFiles, TOIL_DOCS, TOIL_ENV_DTS } from "toiljs/compiler";
 
+// src/cli/testing.ts
+var TEST_DEPENDENCIES = {
+  vitest: "^5.0.3",
+  "@vitest/browser-webdriverio": "^5.0.0",
+  "@vitest/coverage-v8": "^5.0.3",
+  webdriverio: "^10.0.2"
+};
+var TEST_SCRIPTS = {
+  test: "toiljs test",
+  "test:watch": "toiljs test --watch",
+  "test:browser": "toiljs test --browser",
+  "test:all": "toiljs test --all",
+  "test:coverage": "toiljs test --all --coverage"
+};
+function testingFiles() {
+  return {
+    "vitest.config.ts": "import { defineTestConfig } from 'toiljs/vitest';\n\nexport default defineTestConfig();\n",
+    "client/lib/Greeting.ts": [
+      "/** Formats a greeting, treating blank input as an unnamed guest. */",
+      "export class Greeting {",
+      "    public static message(name: string): string {",
+      "        const recipient: string = name.trim() || 'guest';",
+      "        return `Hello, ${recipient}!`;",
+      "    }",
+      "}",
+      ""
+    ].join("\n"),
+    "tests/Greeting.test.ts": [
+      "import { expect, test } from 'vitest';",
+      "import { Greeting } from '../client/lib/Greeting';",
+      "",
+      "test('trims the supplied name', (): void => {",
+      "    expect(Greeting.message('  Ada  ')).toBe('Hello, Ada!');",
+      "});",
+      "",
+      "test('greets an unnamed guest', (): void => {",
+      "    expect(Greeting.message('   ')).toBe('Hello, guest!');",
+      "});",
+      ""
+    ].join("\n"),
+    "client/components/TestCounter.tsx": [
+      "import { useState, type ReactElement } from 'react';",
+      "",
+      "/** A small component used by the starter browser test. */",
+      "export function TestCounter(): ReactElement {",
+      "    const [count, setCount] = useState<number>(0);",
+      "    return (",
+      "        <section>",
+      '            <Toil.Link href="/">Home</Toil.Link>',
+      "            <button onClick={(): void => setCount(count + 1)}>Count: {count}</button>",
+      "        </section>",
+      "    );",
+      "}",
+      ""
+    ].join("\n"),
+    "tests/TestCounter.browser.test.tsx": [
+      "import { afterEach, expect, test } from 'vitest';",
+      "import { page } from 'vitest/browser';",
+      "import { createRoot, type Root } from 'react-dom/client';",
+      "import { TestCounter } from '../client/components/TestCounter';",
+      "",
+      "let root: Root | null = null;",
+      "afterEach((): void => {",
+      "    root?.unmount();",
+      "    root = null;",
+      "    document.body.replaceChildren();",
+      "});",
+      "",
+      "test('increments when clicked in a real browser', async (): Promise<void> => {",
+      "    const host: HTMLDivElement = document.createElement('div');",
+      "    document.body.append(host);",
+      "    root = createRoot(host);",
+      "    root.render(<TestCounter />);",
+      "    await expect.element(page.getByRole('link', { name: 'Home' })).toHaveAttribute('href', '/');",
+      "    await page.getByRole('button', { name: 'Count: 0' }).click();",
+      "    await expect.element(page.getByRole('button', { name: 'Count: 1' })).toBeVisible();",
+      "});",
+      ""
+    ].join("\n")
+  };
+}
+
 // src/cli/validate.ts
 import path3 from "node:path";
 var PACKAGE_MANAGERS = ["npm", "pnpm", "yarn", "bun"];
@@ -4061,12 +4143,13 @@ async function isEmptyDir(dir) {
 function scaffold(name, template, features, aiTools, images) {
   const toilVersion = version();
   const devDependencies = {
+    ...TEST_DEPENDENCIES,
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
-    oxlint: "^1.83.0",
-    "oxlint-tsgolint": "^7.0.2001",
-    prettier: "^3.9.6",
-    toilscript: "^0.1.63",
+    oxlint: "^1.87.0",
+    "oxlint-tsgolint": "^7.0.2003",
+    prettier: "^3.9.9",
+    toilscript: ">=0.1.63",
     typescript: "^7.0.2"
   };
   for (const dep of requiredPackages(features).sort()) {
@@ -4077,6 +4160,7 @@ function scaffold(name, template, features, aiTools, images) {
     private: true,
     type: "module",
     scripts: {
+      ...TEST_SCRIPTS,
       start: "toiljs start",
       dev: "toiljs dev",
       build: "toiljs build",
@@ -4093,23 +4177,22 @@ function scaffold(name, template, features, aiTools, images) {
     devDependencies
   };
   const files = {
+    ...testingFiles(),
     "package.json": JSON.stringify(pkg, null, 4) + "\n",
-    "toil.config.ts": `import { defineConfig } from 'toiljs/compiler';
-
-export default defineConfig({
-    client: {
+    "toil.config.ts": "import { defineConfig } from 'toiljs/compiler';\n\nexport default defineConfig({\n" + // The app starter's session routes use the identity fields injected by built-in auth.
+    (template === "app" ? "    server: { auth: true },\n" : "") + `    client: {
         // Optimize images at build time (resize/compress imported images).
         images: ${String(images)},
     },
 });
 `,
-    "tsconfig.json": '{\n    "extends": "toiljs/tsconfig",\n    "compilerOptions": {\n        "paths": { "shared/*": ["./shared/*"] }\n    },\n    "include": ["client", "shared", "emails", "toil.config.ts", "toil-env.d.ts", "toil-routes.d.ts"]\n}\n',
+    "tsconfig.json": '{\n    "extends": "toiljs/tsconfig",\n    "compilerOptions": {\n        "paths": { "shared/*": ["./shared/*"] }\n    },\n    "include": ["client", "shared", "emails", "tests", "vitest.config.ts", "toil.config.ts", "toil-env.d.ts", "toil-routes.d.ts"]\n}\n',
     "oxlint.config.ts": "import toiljs from 'toiljs/oxlint';\n\nexport default toiljs;\n",
     ".prettierrc": '"toiljs/prettier"\n',
     // Generated files don't need formatting. (toilscript server decorators like @main /
     // @remote-on-functions are handled by the toiljs/prettier-plugin, so server/ is not ignored.)
-    ".prettierignore": "node_modules\nbuild\n.toil\nshared/server.ts\ntoil-env.d.ts\ntoil-routes.d.ts\nserver/_emails.ts\nserver/_ssr/\nserver/toil-server-env.d.ts\n",
-    ".gitignore": "node_modules\nbuild\n.toil\nshared/server.ts\ntoil-env.d.ts\ntoil-routes.d.ts\nserver/_ssr/\nhosts/*/_tmpl/\n# Local dev env vars/secrets (never commit)\n.env\n.env.secrets\n",
+    ".prettierignore": "node_modules\nbuild\n.toil\ncoverage\n.vitest\nshared/server.ts\ntoil-env.d.ts\ntoil-routes.d.ts\nserver/_emails.ts\nserver/_ssr/\nserver/toil-server-env.d.ts\n",
+    ".gitignore": "node_modules\nbuild\n.toil\ncoverage\n.vitest\nshared/server.ts\ntoil-env.d.ts\ntoil-routes.d.ts\nserver/_ssr/\nhosts/*/_tmpl/\n# Local dev env vars/secrets (never commit)\n.env\n.env.secrets\n",
     // Use the native TypeScript 7 language server.
     ".vscode/settings.json": JSON.stringify(
       {
@@ -4193,6 +4276,21 @@ export default defineConfig({
       "",
       "    npm run build",
       "",
+      "## Test",
+      "",
+      "Vitest, real-browser testing, and V8 coverage are installed with the project.",
+      "Start with `tests/Greeting.test.ts` and `tests/TestCounter.browser.test.tsx`.",
+      "",
+      "    npm test                 # unit tests",
+      "    npm run test:watch       # unit tests in watch mode",
+      "    npm run test:browser     # real Chrome tests",
+      "    npm run test:all         # unit and browser tests",
+      "    npm run test:coverage    # both suites with V8 coverage",
+      "",
+      "Coverage reports are in `coverage/` (HTML, JSON, and LCOV).",
+      "Chrome and its driver are managed by WebdriverIO on the first browser run.",
+      "See `.toil/docs/frontend/testing.md` for configuration, mocks, and CI.",
+      "",
       "## Editor setup",
       "",
       "Run `npm install` first and use Node 26 for editor tooling.",
@@ -4547,6 +4645,8 @@ async function runCreate(opts2) {
     await fs3.cp(appClientDir(), path4.join(targetDir, "client"), { recursive: true });
     const serverAllow = /* @__PURE__ */ new Set([
       "main.ts",
+      "main.stream.ts",
+      "SsrHelloRender.ts",
       "README.md",
       "tsconfig.json",
       "toil-server-env.d.ts",
@@ -4554,6 +4654,7 @@ async function runCreate(opts2) {
       "models",
       "routes",
       "services",
+      "streams",
       "scheduled"
     ]);
     const serverSrc = appServerDir();
@@ -4601,6 +4702,8 @@ async function runCreate(opts2) {
   if (!install) steps.push("npm install");
   steps.push(`${accent("npm run dev")}   ${dim("start the dev server")}`);
   steps.push(`${accent("npm run build")} ${dim("build for production")}`);
+  steps.push(`${accent("npm test")} ${dim("run the starter unit tests")}`);
+  steps.push(`${accent("npm run test:browser")} ${dim("run the starter browser test")}`);
   steps.push("Install the Oxc plugin for VS Code or WebStorm (README.md \u2192 Editor setup)");
   steps.push("WebStorm: Settings \u2192 Tools \u2192 Oxlint \u2192 Enable type aware rules");
   note(steps.map((l2) => dim("  ") + l2).join("\n"), "Next steps");
@@ -6969,7 +7072,8 @@ function buildRows(upgraded, currentDeps) {
 function detectPackageManager2(root) {
   if (fs7.existsSync(path8.join(root, "pnpm-lock.yaml"))) return { name: "pnpm", ncuName: "pnpm" };
   if (fs7.existsSync(path8.join(root, "yarn.lock"))) return { name: "yarn", ncuName: "yarn" };
-  if (fs7.existsSync(path8.join(root, "bun.lockb"))) return { name: "bun", ncuName: "bun" };
+  if (fs7.existsSync(path8.join(root, "bun.lock")) || fs7.existsSync(path8.join(root, "bun.lockb")))
+    return { name: "bun", ncuName: "bun" };
   return { name: "npm", ncuName: "npm" };
 }
 function readDependencies(pkgPath) {
@@ -7330,6 +7434,115 @@ async function notifyIfOutdated(rootArg) {
   }
 }
 
+// src/cli/test.ts
+import fs9 from "node:fs/promises";
+import path10 from "node:path";
+import { createRequire as createRequire2 } from "node:module";
+import { spawn as spawn2 } from "node:child_process";
+async function writeMissing(root, file, content) {
+  const target = path10.join(root, file);
+  await fs9.mkdir(path10.dirname(target), { recursive: true });
+  try {
+    await fs9.writeFile(target, content, { flag: "wx" });
+  } catch (error) {
+    if (!(error instanceof Error) || !("code" in error) || error.code !== "EEXIST") throw error;
+  }
+}
+async function ensureTesting(root) {
+  const pkgPath = path10.join(root, "package.json");
+  const raw = JSON.parse(await fs9.readFile(pkgPath, "utf8"));
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+    throw new Error("toiljs test: package.json must contain an object.");
+  const pkg = raw;
+  for (const field of [pkg.scripts, pkg.dependencies, pkg.devDependencies]) {
+    if (field !== void 0 && (field === null || typeof field !== "object" || Array.isArray(field) || Object.values(field).some((value) => typeof value !== "string")))
+      throw new Error("toiljs test: package scripts and dependencies must be string maps.");
+  }
+  const files = await fs9.readdir(root);
+  const custom = files.find((file) => /^vitest\.config\.[cm]?[jt]s$/.test(file)) ?? files.find((file) => /^vite\.config\.[cm]?[jt]s$/.test(file));
+  const source = custom === void 0 ? "" : await fs9.readFile(path10.join(root, custom), "utf8");
+  const native = custom === void 0 || source.includes("from 'toiljs/vitest'") || source.includes('from "toiljs/vitest"');
+  let changed = false;
+  let install = false;
+  const require2 = createRequire2(pkgPath);
+  for (const [name, range] of Object.entries(TEST_DEPENDENCIES)) {
+    if (pkg.dependencies?.[name] === void 0 && pkg.devDependencies?.[name] === void 0) {
+      pkg.devDependencies ??= {};
+      pkg.devDependencies[name] = range;
+      changed = true;
+      install = true;
+    }
+    try {
+      require2.resolve(name);
+    } catch {
+      install = true;
+    }
+  }
+  pkg.scripts ??= {};
+  for (const [name, script] of Object.entries(TEST_SCRIPTS)) {
+    if (pkg.scripts[name] !== void 0) continue;
+    pkg.scripts[name] = script;
+    changed = true;
+  }
+  if (changed) await fs9.writeFile(pkgPath, JSON.stringify(raw, null, 4) + "\n");
+  if (custom === void 0) {
+    for (const [file, content] of Object.entries(testingFiles()))
+      await writeMissing(root, file, content);
+  }
+  return { install, native };
+}
+function parseTestArgs(args) {
+  let root;
+  let browser = false;
+  let all = false;
+  let watch = false;
+  const forwarded = [];
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === "--root") {
+      const value = args[++index];
+      if (!value) throw new Error("toiljs test: --root requires a directory.");
+      root = value;
+    } else if (arg === "--browser") browser = true;
+    else if (arg === "--all") all = true;
+    else if (arg === "--watch" || arg === "-w") watch = true;
+    else if (arg !== "--") forwarded.push(arg);
+  }
+  if (browser && all) throw new Error("toiljs test: use either --browser or --all.");
+  return { root, browser, all, watch, arguments: forwarded };
+}
+async function runTest(options) {
+  const root = path10.resolve(options.root ?? process.cwd());
+  const setup = await ensureTesting(root);
+  if (setup.install) {
+    const pm = detectPackageManager2(root).name;
+    process.stdout.write(
+      `toiljs test: installing Vitest, browser testing, and V8 coverage with ${pm}.
+`
+    );
+    await run(pm, ["install"], root, { stdio: "inherit" });
+  }
+  const require2 = createRequire2(path10.join(root, "package.json"));
+  const cli = path10.join(
+    path10.dirname(require2.resolve("vitest/package.json")),
+    "vitest.mjs"
+  );
+  const args = [cli, ...options.watch ? [] : ["run"]];
+  const projectFlag = options.arguments.some(
+    (arg) => arg === "--project" || arg.startsWith("--project=")
+  );
+  if (setup.native && !options.all && !projectFlag)
+    args.push("--project", options.browser ? "browser" : "unit");
+  if (!setup.native && options.browser) args.push("--browser");
+  args.push(...options.arguments);
+  const code = await new Promise((resolve, reject) => {
+    const child = spawn2(process.execPath, args, { cwd: root, stdio: "inherit" });
+    child.once("error", reject);
+    child.once("exit", (status) => resolve(status ?? 1));
+  });
+  process.exitCode = code;
+}
+
 // src/cli/index.ts
 var __origEmitWarning = process.emitWarning.bind(process);
 process.emitWarning = ((warning, ...rest) => {
@@ -7436,6 +7649,7 @@ function printHelp() {
       cmd("create [name]", "scaffold a new toiljs app"),
       cmd("configure", "toggle styling features (Sass/Less/Stylus, Tailwind)"),
       cmd("generate auth", "generate private auth keys and the matching client public key"),
+      cmd("test", "run Vitest (auto-installs missing test tooling)"),
       cmd("dev", "start the dev server with HMR"),
       cmd("build", "build the optimized production bundle"),
       cmd("start", "self-host the built app (hyper-express / uWS)"),
@@ -7446,7 +7660,10 @@ function printHelp() {
       bold("Options"),
       cmd("--root <dir>", "project root (default: current directory)"),
       cmd("--port <n>", "dev/start: listen port (or PORT env / client.port; default 3000)"),
-      cmd("--host <h>", "dev/start: bind host, e.g. 0.0.0.0 (or HOST env / client.host; default 127.0.0.1)"),
+      cmd(
+        "--host <h>",
+        "dev/start: bind host, e.g. 0.0.0.0 (or HOST env / client.host; default 127.0.0.1)"
+      ),
       cmd("--threads <n>", "start: production HTTP worker count"),
       cmd("-t, --template", "create: app | minimal | agent"),
       cmd("--style <name>", "create/configure: css | sass | less | stylus"),
@@ -7454,6 +7671,10 @@ function printHelp() {
       cmd("--no-ai", "create: skip AI assistant files (CLAUDE.md, etc.)"),
       cmd("-y, --yes", "create: accept defaults (non-interactive)"),
       cmd("--no-install", "create: don't install dependencies"),
+      cmd("--browser", "test: run real Chrome browser tests"),
+      cmd("--all", "test: run unit and browser projects"),
+      cmd("--coverage", "test: collect V8 coverage reports"),
+      cmd("--watch", "test: watch for changes"),
       cmd("--server", "build: build only the server (regenerate shared/server.ts + wasm)"),
       cmd("--json", "doctor: machine-readable output"),
       cmd("--fix", "doctor: auto-fix what it can (typed-RPC wiring)"),
@@ -7475,6 +7696,9 @@ async function main() {
   const flags = parseArgs(rest);
   await notifyIfOutdated(flags.root);
   switch (command) {
+    case "test":
+      await runTest(parseTestArgs(rest));
+      break;
     case "create":
       banner();
       await runCreate({
@@ -7533,7 +7757,9 @@ async function main() {
       const shownHost = wildcard || server.host === "127.0.0.1" ? "localhost" : server.host;
       const exposed = server.host !== "127.0.0.1" && server.host !== "localhost" && server.host !== "::1";
       process.stdout.write(
-        accent("  \u279C ") + bold(`http://${shownHost}:${String(server.port)}`) + dim(`   ws channel: ${server.wsPath}`) + (exposed ? "\n" + dim(`     bound to ${server.host}:${String(server.port)} (exposed beyond loopback)`) : "") + "\n\n"
+        accent("  \u279C ") + bold(`http://${shownHost}:${String(server.port)}`) + dim(`   ws channel: ${server.wsPath}`) + (exposed ? "\n" + dim(
+          `     bound to ${server.host}:${String(server.port)} (exposed beyond loopback)`
+        ) : "") + "\n\n"
       );
       break;
     }