create-waygraph 0.0.1

package/README.md

@@ -0,0 +1,34 @@
+# create-waygraph
+
+Scaffolds a new [waygraph](https://github.com/deviate-dv8/waygraph) project - one fixed
+shape, no prompts, no template picker.
+
+```bash
+npx create-waygraph my-project
+cd my-project
+npm install
+npx playwright install chromium
+npm test
+```
+
+Generates:
+
+```
+my-project/
+  package.json          waygraph + @playwright/test
+  tsconfig.json
+  playwright.config.ts
+  .gitignore
+  src/
+    blocks/load-page.block.ts   one real Block (act/resolve/verify)
+    flows/example.flow.ts       Engine.defineFlow([start, LoadPageBlock, end])
+  tests/
+    example.spec.ts             runs the flow, asserts the terminal Checkpoint
+```
+
+`npm test` goes green immediately, offline - the example Block navigates to a self-contained
+`data:` URL, not a live site, so scaffolding a project never depends on network access.
+
+Ships as its own package rather than a `waygraph init` subcommand, so consuming `waygraph`
+at runtime never pulls in scaffolding code - `npx create-waygraph` resolves and runs without
+adding anything to your own `node_modules`.

package/bin/create-waygraph.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import fs from "node:fs";
+
+const projectName = process.argv[2];
+
+if (!projectName) {
+  console.error("Usage: npx create-waygraph <project-name>");
+  process.exit(1);
+}
+
+const templatesDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "templates");
+const targetDir = path.resolve(process.cwd(), projectName);
+
+if (fs.existsSync(targetDir)) {
+  const stat = fs.statSync(targetDir);
+  if (!stat.isDirectory() || fs.readdirSync(targetDir).length > 0) {
+    console.error(`create-waygraph: "${targetDir}" already exists - refusing to overwrite it.`);
+    process.exit(1);
+  }
+}
+
+fs.mkdirSync(targetDir, { recursive: true });
+fs.cpSync(templatesDir, targetDir, { recursive: true });
+
+fs.renameSync(path.join(targetDir, "gitignore"), path.join(targetDir, ".gitignore"));
+
+const packageJsonPath = path.join(targetDir, "package.json");
+const packageJson = fs.readFileSync(packageJsonPath, "utf8").replace("__PROJECT_NAME__", projectName);
+fs.writeFileSync(packageJsonPath, packageJson);
+
+console.log(`Scaffolded ${projectName}/`);
+console.log("");
+console.log(`  cd ${projectName}`);
+console.log("  npm install");
+console.log("  npx playwright install chromium");
+console.log("  npm test");

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "create-waygraph",
+  "version": "0.0.1",
+  "description": "Scaffold a new waygraph project - package.json, tsconfig, playwright.config, and one working example flow.",
+  "type": "module",
+  "bin": {
+    "create-waygraph": "bin/create-waygraph.js"
+  },
+  "files": [
+    "bin",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deviate-dv8/create-waygraph.git"
+  }
+}

package/templates/gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+test-results/
+playwright-report/

package/templates/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "playwright test",
+    "flows": "waygraph list .",
+    "nav": "waygraph nav ."
+  },
+  "dependencies": {
+    "waygraph": "^0.1.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.55.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}

package/templates/playwright.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from "@playwright/test";
+
+export default defineConfig({
+  testDir: "./tests",
+  fullyParallel: true,
+  reporter: "list",
+  use: {
+    launchOptions: {
+      // If CHROME_PATH/CHROMIUM_PATH is set (e.g. a Flatpak/system Chromium),
+      // use it instead of downloading Playwright's own bundled binary.
+      // Falls through to Playwright's default when unset - safe either way.
+      executablePath: process.env.CHROME_PATH || process.env.CHROMIUM_PATH,
+    },
+  },
+});

package/templates/src/blocks/load-page.block.ts

@@ -0,0 +1,18 @@
+import { defineBlock, checkpoint, Trait } from "waygraph";
+import type { Checkpoint } from "waygraph";
+
+export type Start = Checkpoint<"__start__">;
+export type Loaded = Checkpoint<"Loaded">;
+
+const PAGE_URL = "data:text/html,<h1>Hello Waygraph</h1>";
+
+export const LoadPageBlock = defineBlock<Start, Loaded>({
+  name: "load-page",
+  instruction: {
+    async act(page) {
+      await page.goto(PAGE_URL);
+    },
+    resolve: () => checkpoint("Loaded"),
+    verify: [Trait.text("h1", "Hello Waygraph")],
+  },
+});

package/templates/src/flows/example.flow.ts

@@ -0,0 +1,6 @@
+import { Engine, start, end } from "waygraph";
+import { LoadPageBlock } from "../blocks/load-page.block.js";
+
+const engine = new Engine();
+
+export const exampleFlow = engine.defineFlow([start, LoadPageBlock, end]);

package/templates/tests/example.spec.ts

@@ -0,0 +1,8 @@
+import { test, expect } from "@playwright/test";
+import { MemPage, checkpoint } from "waygraph";
+import { exampleFlow } from "../src/flows/example.flow.js";
+
+test("example flow reaches Loaded", async ({ context }) => {
+  const result = await exampleFlow.run(context, new MemPage());
+  expect(result).toEqual(checkpoint("Loaded"));
+});

package/templates/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "strict": true,
+    "noImplicitAny": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts"]
+}