create-minlang-app 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codeshift AI Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/bin.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// Scaffold a MinLang web app. Usage: npm create minlang-app <name>
+// The app is one .ml file plus a thin Next.js shell that consumes the
+// published @minlang/* runtime packages. Compile with ml1 (see the printed
+// next steps), run with pnpm, deploy via the included Vercel workflow.
+
+import { cpSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const name = process.argv[2];
+if (!name || !/^[a-z][a-z0-9-]*$/.test(name)) {
+	console.error("usage: npm create minlang-app <name>   (lowercase, digits, dashes)");
+	process.exit(2);
+}
+
+const templateDir = join(dirname(fileURLToPath(import.meta.url)), "template");
+const dest = join(process.cwd(), name);
+mkdirSync(dest, { recursive: false });
+cpSync(templateDir, dest, { recursive: true });
+
+// Substitute the app name in every text file.
+const substitute = (dir) => {
+	for (const entry of readdirSync(dir)) {
+		const path = join(dir, entry);
+		if (statSync(path).isDirectory()) {
+			substitute(path);
+			continue;
+		}
+		const text = readFileSync(path, "utf8");
+		if (text.includes("__APP_NAME__")) {
+			writeFileSync(path, text.replaceAll("__APP_NAME__", name));
+		}
+	}
+};
+substitute(dest);
+renameSync(join(dest, "__APP_NAME__.ml"), join(dest, `${name}.ml`));
+// npm strips dotfiles from published packages; restore them.
+renameSync(join(dest, "gitignore"), join(dest, ".gitignore"));
+renameSync(join(dest, "github"), join(dest, ".github"));
+
+console.log(`
+Created ${name}/ — a MinLang web app.
+
+Next steps:
+  cd ${name}
+  # 1. install the ml1 compiler (pick one):
+  #    brew install codeshift-ai-solutions/tap/ml1
+  #    bash <(curl -fsSL https://raw.githubusercontent.com/codeshift-ai-solutions/minlang-core/main/install/install.sh)
+  # 2. compile, install, run:
+  make compile
+  pnpm --dir app install
+  pnpm --dir app dev
+
+Your whole app lives in ${name}.ml (it starts as a task tracker — replace it).
+Authoring guide: https://github.com/codeshift-ai-solutions/minlang-core/blob/main/docs/ai/language/WEB_APP_GUIDE.md
+Deploys: push to GitHub with org secrets VERCEL_TOKEN/VERCEL_ORG_ID set.
+`);

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "create-minlang-app",
+  "version": "0.1.0",
+  "description": "Scaffold a MinLang web app: write one .ml file, compile with ml1, deploy.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codeshift-ai-solutions/minlang-core.git"
+  },
+  "type": "module",
+  "bin": {
+    "create-minlang-app": "./bin.mjs"
+  },
+  "files": [
+    "bin.mjs",
+    "template"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "node --check bin.mjs",
+    "test": "node --test test/scaffold.test.mjs"
+  }
+}

package/template/Makefile

@@ -0,0 +1,21 @@
+APP := __APP_NAME__
+
+.PHONY: validate compile build test test-e2e dev
+
+validate:
+	ml1 validate $(APP).ml
+
+compile: validate
+	ml1 compile $(APP).ml --target web --out app
+
+build:
+	pnpm --dir app run build
+
+test:
+	pnpm --dir app run test
+
+test-e2e:
+	pnpm --dir app run test:e2e
+
+dev:
+	pnpm --dir app run dev

package/template/README.md

@@ -0,0 +1,15 @@
+# __APP_NAME__
+
+A MinLang web app. The whole application lives in `__APP_NAME__.ml`;
+`app/generated/` is compiler output (committed, never edited); `app/` holds
+the thin Next.js shell consuming the published `@minlang/*` runtime.
+
+```bash
+make compile           # __APP_NAME__.ml -> app/generated/ (needs ml1 on PATH)
+pnpm --dir app install
+pnpm --dir app dev
+make test              # generated test triads + integration
+```
+
+Authoring guide:
+https://github.com/codeshift-ai-solutions/minlang-core/blob/main/docs/ai/language/WEB_APP_GUIDE.md

package/template/__APP_NAME__.ml

@@ -0,0 +1,240 @@
+entity Workspace {
+	id: string req
+	view: enum(board, projects)
+}
+
+entity Project {
+	id: string req
+	name: string
+}
+
+entity Task {
+	id: string req
+	project: ref(Project)
+	title: string
+	status: enum(todo, doing, done)
+	assignee: string
+	created_at: string
+	actor_id: string
+}
+
+constraint TitleRequired {
+	on: Task
+	validate: NOT(self.title == '')
+	message: 'title is required'
+}
+
+constraint AssigneeRequiredWhenDoing {
+	on: Task
+	validate: NOT(self.status == 'doing' AND self.assignee == '')
+	message: 'assignee is required when a task is doing'
+}
+
+constraint ProjectExists {
+	on: Task
+	validate: count(Project as p, p == self.project) == 1
+	message: 'project does not exist'
+}
+
+constraint ProjectNameRequired {
+	on: Project
+	validate: NOT(self.name == '')
+	message: 'project name is required'
+}
+
+constraint UniqueProjectName {
+	on: Project
+	validate: count(Project as p, p.name == name) == 0
+	message: 'a project with this name already exists'
+}
+
+action CreateProject(id: string, name: string, actor_id: string) {
+	on: Project
+	create(Project, { id: id, name: name })
+}
+
+action CreateTask(id: string, project: ref(Project), title: string, status: enum(todo, doing, done), assignee: string, created_at: string, actor_id: string) {
+	on: Task
+	create(Task, { id: id, project: project, title: title, status: status, assignee: assignee, created_at: created_at, actor_id: actor_id })
+}
+
+action MoveTask(id: string, status: enum(todo, doing, done), actor_id: string) {
+	on: Task
+	set(status, status)
+}
+
+action RenameTask(id: string, title: string, actor_id: string) {
+	on: Task
+	set(title, title)
+}
+
+action OpenProjects(workspace: ref(Workspace), actor_id: string) {
+	on: Workspace
+	set(view, 'projects')
+}
+
+action OpenBoard(workspace: ref(Workspace), actor_id: string) {
+	on: Workspace
+	set(view, 'board')
+}
+
+query TaskBoard(workspace: ref(Workspace)) -> list<Task> {
+	from Task
+}
+
+query ProjectList(workspace: ref(Workspace)) -> list<Project> {
+	from Project
+}
+
+query TaskDetail(task: ref(Task)) -> Task {
+	from Task
+}
+
+screen Board {
+	when workspace.view == 'board'
+	title "Task board"
+	hint "Create tasks, move them between statuses, and rename them."
+	board TaskBoard
+	primary { label "Add task" action CreateTask }
+	button { label "Move task" action MoveTask }
+	button { label "Rename task" action RenameTask }
+	button { label "Projects" action OpenProjects }
+}
+
+screen Projects {
+	when workspace.view == 'projects'
+	title "Projects"
+	body "Every task belongs to a project."
+	board ProjectList
+	primary { label "Add project" action CreateProject }
+	button { label "Back to board" action OpenBoard }
+}
+
+test CreateTaskSucceeds {
+	setup: [
+		create(Workspace, { id: "w1", view: "board" }),
+		create(Project, { id: "p1", name: "General" })
+	]
+	when: CreateTask on Task { id: "t1", project: "p1", title: "Ship the compiler", status: "todo", assignee: "" }
+	then: [
+		entity_count(Task) == 1,
+		entity_has(Task.1, title == "Ship the compiler")
+	]
+}
+
+test TitleRequiredRejectsEmpty {
+	setup: [
+		create(Workspace, { id: "w1", view: "board" }),
+		create(Project, { id: "p1", name: "General" })
+	]
+	when: CreateTask on Task { id: "t1", project: "p1", title: "", status: "todo", assignee: "" }
+	then: [
+		error_raised('title is required'),
+		entity_count(Task) == 0
+	]
+}
+
+test AssigneeRequiredWhenDoingRejects {
+	setup: [
+		create(Workspace, { id: "w1", view: "board" }),
+		create(Project, { id: "p1", name: "General" })
+	]
+	when: CreateTask on Task { id: "t1", project: "p1", title: "Ship the compiler", status: "doing", assignee: "" }
+	then: [
+		error_raised('assignee is required when a task is doing'),
+		entity_count(Task) == 0
+	]
+}
+
+test ProjectExistsRejectsUnknown {
+	setup: [
+		create(Workspace, { id: "w1", view: "board" })
+	]
+	when: CreateTask on Task { id: "t1", project: "ghost", title: "Ship the compiler", status: "todo", assignee: "" }
+	then: [
+		error_raised('project does not exist'),
+		entity_count(Task) == 0
+	]
+}
+
+test MoveTaskSucceeds {
+	setup: [
+		create(Workspace, { id: "w1", view: "board" }),
+		create(Project, { id: "p1", name: "General" }),
+		create(Task, { id: "t1", project: "p1", title: "Ship the compiler", status: "todo", assignee: "casey", created_at: "2026-01-01T00:00:00Z", actor_id: "a1" })
+	]
+	when: MoveTask on Task { id: "t1", status: "doing" }
+	then: [
+		entity_has(Task.1, status == "doing"),
+		entity_count(Task) == 1
+	]
+}
+
+test MoveTaskRejectsDoingWithoutAssignee {
+	setup: [
+		create(Workspace, { id: "w1", view: "board" }),
+		create(Project, { id: "p1", name: "General" }),
+		create(Task, { id: "t1", project: "p1", title: "Ship the compiler", status: "todo", assignee: "", created_at: "2026-01-01T00:00:00Z", actor_id: "a1" })
+	]
+	when: MoveTask on Task { id: "t1", status: "doing" }
+	then: [
+		error_raised('assignee is required when a task is doing'),
+		entity_has(Task.1, status == "todo")
+	]
+}
+
+test RenameTaskSucceeds {
+	setup: [
+		create(Workspace, { id: "w1", view: "board" }),
+		create(Project, { id: "p1", name: "General" }),
+		create(Task, { id: "t1", project: "p1", title: "Old name", status: "todo", assignee: "", created_at: "2026-01-01T00:00:00Z", actor_id: "a1" })
+	]
+	when: RenameTask on Task { id: "t1", title: "New name" }
+	then: [
+		entity_has(Task.1, title == "New name")
+	]
+}
+
+test CreateProjectSucceeds {
+	setup: [
+		create(Workspace, { id: "w1", view: "board" })
+	]
+	when: CreateProject on Project { id: "p1", name: "Platform" }
+	then: [
+		entity_count(Project) == 1,
+		entity_has(Project.1, name == "Platform")
+	]
+}
+
+test ProjectNameRequiredRejectsEmpty {
+	setup: [
+		create(Workspace, { id: "w1", view: "board" })
+	]
+	when: CreateProject on Project { id: "p1", name: "" }
+	then: [
+		error_raised('project name is required'),
+		entity_count(Project) == 0
+	]
+}
+
+test UniqueProjectNameRejectsDuplicate {
+	setup: [
+		create(Workspace, { id: "w1", view: "board" }),
+		create(Project, { id: "p0", name: "General" })
+	]
+	when: CreateProject on Project { id: "p1", name: "General" }
+	then: [
+		error_raised('a project with this name already exists'),
+		entity_count(Project) == 1
+	]
+}
+
+test OpenProjectsSwitchesView {
+	setup: [
+		create(Workspace, { id: "w1", view: "board" })
+	]
+	when: OpenProjects on Workspace { workspace: "w1" }
+	then: [
+		entity_has(Workspace.1, view == "projects")
+	]
+}

package/template/app/app/layout.tsx

@@ -0,0 +1,5 @@
+// Thin re-export of the generated root layout (generated/ is the app).
+// The seed import binds the data adapter in this server bundle (side effect).
+import "../seed";
+
+export { default, metadata } from "../generated/app/layout";

package/template/app/app/page.tsx

@@ -0,0 +1,5 @@
+// Thin re-export of the generated route (generated/ is the app).
+// Segment config must live in the page file itself for Next to see it.
+export const dynamic = "force-dynamic";
+
+export { default } from "../generated/app/page";

package/template/app/app/screens/board/page.tsx

@@ -0,0 +1,5 @@
+// Thin re-export of the generated route (generated/ is the app).
+// Segment config must live in the page file itself for Next to see it.
+export const dynamic = "force-dynamic";
+
+export { default } from "../../../generated/app/screens/board/page";

package/template/app/app/screens/projects/page.tsx

@@ -0,0 +1,5 @@
+// Thin re-export of the generated route (generated/ is the app).
+// Segment config must live in the page file itself for Next to see it.
+export const dynamic = "force-dynamic";
+
+export { default } from "../../../generated/app/screens/projects/page";

package/template/app/e2e/01-board.spec.ts

@@ -0,0 +1,68 @@
+// Core journeys: create a task, see the rejection path, move and rename it.
+// Deterministic: every run starts a fresh server with the same seed.
+
+import { expect, test } from "@playwright/test";
+
+test.describe.configure({ mode: "serial" });
+
+test("create task journey: form -> table row", async ({ page }) => {
+	await page.goto("/");
+	await expect(page.getByRole("heading", { name: "Task board" })).toBeVisible();
+	await expect(page.getByRole("note")).toContainText("No task yet");
+
+	const form = page.getByRole("form", { name: "Create task" });
+	await form.getByLabel("Title").fill("Ship the web target");
+	await form.getByLabel("Status").selectOption("todo");
+	await form.getByLabel("Assignee").fill("casey");
+	await form.getByRole("button", { name: "Add task" }).click();
+
+	const table = page.getByRole("table", { name: "Task board" });
+	await expect(table).toBeVisible();
+	await expect(table.getByRole("row").filter({ hasText: "Ship the web target" })).toBeVisible();
+});
+
+test("validation rejection shows the exact constraint message", async ({ page }) => {
+	await page.goto("/");
+	const form = page.getByRole("form", { name: "Create task" });
+	await form.getByLabel("Status").selectOption("doing");
+	await form.getByLabel("Title").fill("Doing without assignee");
+	await form.getByRole("button", { name: "Add task" }).click();
+	await expect(form.getByRole("alert")).toHaveText("assignee is required when a task is doing");
+});
+
+test("move task journey: status changes in the table", async ({ page }) => {
+	await page.goto("/");
+	const create = page.getByRole("form", { name: "Create task" });
+	await create.getByLabel("Title").fill("Move me");
+	await create.getByLabel("Assignee").fill("alex");
+	await create.getByRole("button", { name: "Add task" }).click();
+	await expect(page.getByRole("table", { name: "Task board" })).toBeVisible();
+
+	const move = page.getByRole("form", { name: "Move task" });
+	await move.getByLabel("Id").selectOption({ label: "Move me" });
+	await move.getByLabel("Status").selectOption("doing");
+	await move.getByRole("button", { name: "Move task" }).click();
+	const row = page.getByRole("row").filter({ hasText: "Move me" });
+	await expect(row).toContainText("doing");
+});
+
+test("rename task journey + projects navigation", async ({ page }) => {
+	await page.goto("/");
+	const create = page.getByRole("form", { name: "Create task" });
+	await create.getByLabel("Title").fill("Old title");
+	await create.getByRole("button", { name: "Add task" }).click();
+	await expect(page.getByRole("table", { name: "Task board" })).toBeVisible();
+
+	const rename = page.getByRole("form", { name: "Rename task" });
+	await rename.getByLabel("Id").selectOption({ label: "Old title" });
+	await rename.getByLabel("Title").fill("New title");
+	await rename.getByRole("button", { name: "Rename task" }).click();
+	await expect(page.getByRole("row").filter({ hasText: "New title" })).toBeVisible();
+
+	await page.goto("/screens/projects");
+	await expect(page.getByRole("heading", { name: "Projects" })).toBeVisible();
+	const project = page.getByRole("form", { name: "Create project" });
+	await project.getByLabel("Name").fill("Platform");
+	await project.getByRole("button", { name: "Add project" }).click();
+	await expect(page.getByRole("row").filter({ hasText: "Platform" })).toBeVisible();
+});

package/template/app/e2e/02-a11y.spec.ts

@@ -0,0 +1,44 @@
+// WCAG 2.1 AA gate: axe-core scans per screen (no serious/critical
+// violations) and a keyboard-only create journey.
+
+import AxeBuilder from "@axe-core/playwright";
+import { expect, test } from "@playwright/test";
+
+const scan = async (page: import("@playwright/test").Page): Promise<void> => {
+	const results = await new AxeBuilder({ page })
+		.withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"])
+		.analyze();
+	const serious = results.violations.filter(
+		(v) => v.impact === "serious" || v.impact === "critical",
+	);
+	expect(serious, JSON.stringify(serious, null, 2)).toEqual([]);
+};
+
+test("board screen is axe-clean (WCAG 2.1 AA)", async ({ page }) => {
+	await page.goto("/");
+	await expect(page.getByRole("heading", { name: "Task board" })).toBeVisible();
+	await scan(page);
+});
+
+test("projects screen is axe-clean (WCAG 2.1 AA)", async ({ page }) => {
+	await page.goto("/screens/projects");
+	await expect(page.getByRole("heading", { name: "Projects" })).toBeVisible();
+	await scan(page);
+});
+
+test("keyboard-only journey: create a task without the mouse", async ({ page }) => {
+	await page.goto("/");
+	const form = page.getByRole("form", { name: "Create task" });
+	await form.getByLabel("Project").focus();
+	await page.keyboard.press("Tab"); // -> Title
+	await page.keyboard.type("Keyboard task");
+	await page.keyboard.press("Tab"); // -> Status (select)
+	await page.keyboard.press("Tab"); // -> Assignee
+	await page.keyboard.type("sam");
+	await page.keyboard.press("Tab"); // -> submit
+	await expect(form.getByRole("button", { name: "Add task" })).toBeFocused();
+	await page.keyboard.press("Enter");
+	await expect(
+		page.getByRole("row").filter({ hasText: "Keyboard task" }),
+	).toBeVisible();
+});

package/template/app/e2e/03-perf.spec.ts

@@ -0,0 +1,21 @@
+// Performance budget smoke: initial route JS <= 120KB compressed
+// (ADR-0016, revised 2026-06-11) measured by gzipping every script
+// response on first load.
+
+import { gzipSync } from "node:zlib";
+import { expect, test } from "@playwright/test";
+
+test("initial route JS stays within the 120KB compressed budget", async ({ page }) => {
+	const sizes: Array<number> = [];
+	page.on("response", (response) => {
+		const url = response.url();
+		if (url.includes("/_next/static/") && url.endsWith(".js")) {
+			void response.body().then((body) => {
+				sizes.push(gzipSync(body).length);
+			});
+		}
+	});
+	await page.goto("/", { waitUntil: "networkidle" });
+	const totalKb = sizes.reduce((sum, n) => sum + n, 0) / 1024;
+	expect(totalKb).toBeLessThanOrEqual(120);
+});

package/template/app/next.config.mjs

@@ -0,0 +1,10 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+	transpilePackages: [
+		"@minlang/runtime-web",
+		"@minlang/design-system",
+		"@minlang/tailwind-preset",
+	],
+};
+
+export default nextConfig;

package/template/app/package.json

@@ -0,0 +1,35 @@
+{
+	"name": "__APP_NAME__-web",
+	"private": true,
+	"scripts": {
+		"dev": "next dev",
+		"build": "next build",
+		"start": "next start --port 3111",
+		"typecheck": "tsc -p tsconfig.json",
+		"test": "vitest run",
+		"test:e2e": "next build && playwright test"
+	},
+	"dependencies": {
+		"@minlang/design-system": "^0.1.0",
+		"@minlang/runtime-web": "^0.1.0",
+		"@minlang/tailwind-preset": "^0.1.0",
+		"next": "15.5.19",
+		"react": "19.2.7",
+		"react-dom": "19.2.7",
+		"zod": "3.23.8"
+	},
+	"devDependencies": {
+		"@axe-core/playwright": "4.11.3",
+		"@playwright/test": "1.60.0",
+		"@types/node": "22.19.21",
+		"@types/react": "19.2.17",
+		"@vitejs/plugin-react": "4.7.0",
+		"autoprefixer": "10.4.21",
+		"jsdom": "25.0.1",
+		"postcss": "8.5.6",
+		"tailwindcss": "3.4.19",
+		"typescript": "5.6.3",
+		"vitest": "3.2.6"
+	},
+	"packageManager": "pnpm@10.33.0"
+}

package/template/app/playwright.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from "@playwright/test";
+
+export default defineConfig({
+	testDir: "./e2e",
+	fullyParallel: false,
+	workers: 1,
+	retries: 0,
+	reporter: [["list"]],
+	use: {
+		baseURL: "http://localhost:3111",
+	},
+	webServer: {
+		command: "pnpm run start",
+		url: "http://localhost:3111",
+		reuseExistingServer: false,
+		timeout: 60_000,
+	},
+});

package/template/app/postcss.config.mjs

@@ -0,0 +1,6 @@
+export default {
+	plugins: {
+		tailwindcss: {},
+		autoprefixer: {},
+	},
+};

package/template/app/seed.ts

@@ -0,0 +1,17 @@
+// App wiring: bind the data adapter (in-memory default) with the
+// deterministic demo seed. Imported for its side effect by app/layout.tsx so
+// it runs once in the route-server bundle before any render or action.
+// WEB_DATA_ADAPTER=memory is the supported adapter for plan completion; a
+// real adapter (USE_REAL_SERVICES=true) would bind here instead.
+
+import { createInMemoryAdapter } from "@minlang/runtime-web";
+import { bindServerAdapter } from "@minlang/runtime-web/server";
+import { emptyAppState } from "./generated/state";
+
+bindServerAdapter(
+	createInMemoryAdapter({
+		...emptyAppState,
+		workspaces: [{ id: "w1", view: "board" }],
+		projects: [{ id: "p1", name: "General" }],
+	}),
+);

package/template/app/tailwind.config.ts

@@ -0,0 +1,17 @@
+// Theme wiring: the preset (token-mapped utilities) + content globs covering
+// the generated app and the design system. Restyle by changing tokens.
+
+import { minlangPreset } from "@minlang/tailwind-preset";
+import type { Config } from "tailwindcss";
+
+const config: Config = {
+	presets: [minlangPreset],
+	content: [
+		"./app/**/*.{ts,tsx}",
+		"./generated/**/*.{ts,tsx}",
+		"./node_modules/@minlang/design-system/dist/**/*.js",
+		"./node_modules/@minlang/runtime-web/dist/**/*.js",
+	],
+};
+
+export default config;

package/template/app/tests/task-flow.test.ts

@@ -0,0 +1,111 @@
+// BDD: end-to-end domain flows through dispatch + the in-memory adapter —
+// create → move → rename journeys, rejection leaves state unchanged, and a
+// deterministic replay over a fixed input trace.
+
+import { createInMemoryAdapter, dispatch } from "@minlang/runtime-web";
+import type { DataAdapter, DispatchDeps } from "@minlang/runtime-web";
+import { describe, expect, test } from "vitest";
+import { applyCreateTask, applyMoveTask, applyRenameTask } from "../generated/actions";
+import type { CreateTaskInput } from "../generated/actions";
+import { runTaskBoard } from "../generated/queries";
+import { emptyAppState } from "../generated/state";
+import type { AppState } from "../generated/state";
+
+const seed: AppState = {
+	...emptyAppState,
+	workspaces: [{ id: "w1", view: "board" }],
+	projects: [{ id: "p1", name: "General" }],
+};
+
+const fixedDeps = (adapter: DataAdapter<AppState>): DispatchDeps<AppState> => ({
+	adapter,
+	clock: { currentTime: () => "2026-01-01T00:00:00Z" },
+	rng: { draw: () => 7 },
+	identity: { currentActorId: () => "test-actor" },
+	logger: { info: () => undefined, warn: () => undefined, error: () => undefined },
+	correlationId: "c-test",
+	emptyState: emptyAppState,
+	newId: () => "id-fixed",
+});
+
+const taskInput = (overrides: Partial<CreateTaskInput>): CreateTaskInput => ({
+	id: "t1",
+	project: "p1",
+	title: "Ship the web target",
+	status: "todo",
+	assignee: "",
+	created_at: "2026-01-01T00:00:00Z",
+	actor_id: "test-actor",
+	...overrides,
+});
+
+describe("task-tracker domain flows", () => {
+	test("create → move → rename journey persists each step", async () => {
+		const adapter = createInMemoryAdapter<AppState>(seed);
+		const deps = fixedDeps(adapter);
+		expect((await dispatch(applyCreateTask, taskInput({}), deps)).ok).toBe(true);
+		expect(
+			(await dispatch(applyMoveTask, { id: "t1", status: "doing", actor_id: "a" }, deps)).ok,
+		).toBe(false); // assignee required when doing
+		expect(
+			(
+				await dispatch(
+					applyRenameTask,
+					{ id: "t1", title: "Ship it", actor_id: "a" },
+					deps,
+				)
+			).ok,
+		).toBe(true);
+		const state = (await adapter.load()) ?? emptyAppState;
+		expect(runTaskBoard(state, { workspace: "w1" }).map((t) => t.title)).toEqual(["Ship it"]);
+	});
+
+	test("rejection returns the exact constraint message and persists nothing", async () => {
+		const adapter = createInMemoryAdapter<AppState>(seed);
+		const outcome = await dispatch(
+			applyCreateTask,
+			taskInput({ title: "" }),
+			fixedDeps(adapter),
+		);
+		expect(outcome.ok).toBe(false);
+		if (!outcome.ok) {
+			expect(outcome.error.message).toBe("title is required");
+		}
+		expect(((await adapter.load()) ?? emptyAppState).tasks).toHaveLength(0);
+	});
+
+	test("unknown project is rejected by the count join", async () => {
+		const adapter = createInMemoryAdapter<AppState>(seed);
+		const outcome = await dispatch(
+			applyCreateTask,
+			taskInput({ project: "ghost" }),
+			fixedDeps(adapter),
+		);
+		expect(outcome.ok).toBe(false);
+		if (!outcome.ok) {
+			expect(outcome.error.message).toBe("project does not exist");
+		}
+	});
+
+	test("replay: a fixed trace yields a deep-equal final state across runs", async () => {
+		const run = async (): Promise<AppState> => {
+			const adapter = createInMemoryAdapter<AppState>(seed);
+			const deps = fixedDeps(adapter);
+			await dispatch(applyCreateTask, taskInput({ id: "t1", title: "One" }), deps);
+			await dispatch(applyCreateTask, taskInput({ id: "t2", title: "Two" }), deps);
+			await dispatch(
+				applyMoveTask,
+				{ id: "t2", status: "done", actor_id: "test-actor" },
+				deps,
+			);
+			await dispatch(applyRenameTask, { id: "t1", title: "Won", actor_id: "test-actor" }, deps);
+			return (await adapter.load()) ?? emptyAppState;
+		};
+		const [first, second] = [await run(), await run()];
+		expect(first).toEqual(second);
+		expect(runTaskBoard(first, { workspace: "w1" }).map((t) => [t.title, t.status])).toEqual([
+			["Won", "todo"],
+			["Two", "done"],
+		]);
+	});
+});

package/template/app/tsconfig.json

@@ -0,0 +1,19 @@
+{
+	"extends": "@minlang/runtime-web/tsconfig.base.json",
+	"compilerOptions": {
+		"jsx": "preserve",
+		"allowJs": true,
+		"incremental": true,
+		"plugins": [{ "name": "next" }]
+	},
+	"include": [
+		"next-env.d.ts",
+		"*.ts",
+		"app/**/*",
+		"generated/**/*",
+		"tests/**/*",
+		"e2e/**/*",
+		".next/types/**/*.ts"
+	],
+	"exclude": ["node_modules"]
+}

package/template/app/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+	test: {
+		globals: true,
+		environment: "node",
+		include: ["generated/tests/**/*.test.ts", "tests/**/*.test.ts"],
+	},
+});

package/template/github/workflows/deploy-vercel.yml

@@ -0,0 +1,67 @@
+# Verifies the committed generated output matches the .ml source (via the
+# minlang-compile action), tests, builds, and deploys prebuilt to Vercel.
+# Org-level secrets: VERCEL_TOKEN + VERCEL_ORG_ID (skips when absent).
+# The minlang actions require the minlang-core repo's Actions access setting
+# to allow this repository.
+
+name: Deploy (Vercel)
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: deploy-vercel
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    env:
+      VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+      VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Generated output is current
+        uses: codeshift-ai-solutions/minlang-core/.github/actions/minlang-compile@main
+        with:
+          file: __APP_NAME__.ml
+          target: web
+          out: app
+          check: "true"
+
+      - name: Setup Node + pnpm
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: corepack enable
+
+      - name: Install, typecheck, test
+        working-directory: app
+        run: |
+          pnpm install --frozen-lockfile
+          pnpm run typecheck
+          pnpm run test
+
+      - name: Gate on Vercel secrets
+        id: gate
+        run: |
+          if [ -z "${VERCEL_TOKEN}" ] || [ -z "${VERCEL_ORG_ID}" ]; then
+            echo "notice: VERCEL_TOKEN / VERCEL_ORG_ID not set — skipping deploy"
+            echo "enabled=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "enabled=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Link, build, deploy
+        if: steps.gate.outputs.enabled == 'true'
+        working-directory: app
+        run: |
+          pnpm dlx vercel@latest link --yes \
+            --project "${{ github.event.repository.name }}" --token "${VERCEL_TOKEN}"
+          pnpm dlx vercel@latest pull --yes --environment=production --token "${VERCEL_TOKEN}"
+          pnpm dlx vercel@latest build --prod --token "${VERCEL_TOKEN}"
+          url=$(pnpm dlx vercel@latest deploy --prebuilt --prod --yes --token "${VERCEL_TOKEN}")
+          echo "deployed: $url" | tee -a "$GITHUB_STEP_SUMMARY"

package/template/gitignore

@@ -0,0 +1,9 @@
+node_modules/
+.next/
+.vercel/
+playwright-report/
+test-results/
+coverage/
+*.tsbuildinfo
+.env
+.env.local