create-backbone-template 0.1.0

package/template/e2e/.oxlintrc.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["eslint", "typescript", "unicorn", "oxc", "import", "promise", "node"],
+  "jsPlugins": ["./support/dist/oxlint-plugin.js"],
+  "categories": {
+    "correctness": "deny",
+    "suspicious": "deny",
+    "perf": "deny",
+    "pedantic": "off",
+    "style": "off",
+    "restriction": "off",
+    "nursery": "off"
+  },
+  "options": {
+    "denyWarnings": true,
+    "reportUnusedDisableDirectives": "deny",
+    "typeAware": true
+  },
+  "rules": {
+    "typescript/no-unsafe-type-assertion": "off",
+    "unicorn/no-array-sort": "off"
+  },
+  "overrides": [
+    {
+      "files": ["**/*.test.ts"],
+      "rules": {
+        "typescript/no-floating-promises": "off"
+      }
+    },
+    {
+      "files": ["tests/**/*.spec.ts"],
+      "rules": {
+        "backbone-e2e/valid-gherkin-feature": "error"
+      }
+    }
+  ]
+}

package/template/e2e/_gitignore

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

package/template/e2e/features/helloworld.feature

@@ -0,0 +1,10 @@
+Feature: Hello page
+
+  @id:hello.say-hello
+  Scenario: Say hello through the UI
+    Given the Rust server is healthy
+    And the visitor is on the hello page
+    Then they see the default hello message
+    When they ask to greet Playwright
+    Then they see the Playwright greeting
+    And the Playwright input is saved

package/template/e2e/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "backbone-e2e",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "pnpm run test:support && playwright test",
+    "test:prepared": "pnpm run test:support:prepared && playwright test",
+    "test:browser": "playwright test",
+    "test:support": "pnpm run test:adapter && pnpm run test:oxlint-plugin",
+    "test:support:prepared": "pnpm run test:adapter && pnpm run test:oxlint-plugin:prepared",
+    "test:adapter": "node --disable-warning=ExperimentalWarning --experimental-strip-types --test support/gherkin.test.ts",
+    "test:oxlint-plugin": "pnpm run build:oxlint-plugin && node --disable-warning=ExperimentalWarning --experimental-strip-types --test support/oxlint-plugin.test.ts",
+    "test:oxlint-plugin:prepared": "node --disable-warning=ExperimentalWarning --experimental-strip-types --test support/oxlint-plugin.test.ts",
+    "build:oxlint-plugin": "tsc --project tsconfig.oxlint-plugin.json",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check .",
+    "lint": "pnpm run format:check && pnpm run lint:code && pnpm run lint:features",
+    "lint:prepared": "pnpm run format:check && pnpm run lint:code:prepared && pnpm run lint:features",
+    "lint:code": "pnpm run build:oxlint-plugin && oxlint --config .oxlintrc.json playwright.config.ts support/app-gherkin.ts support/fixtures.ts support/gherkin.ts support/gherkin.test.ts support/oxlint-plugin.ts support/oxlint-plugin.test.ts tests",
+    "lint:code:prepared": "oxlint --config .oxlintrc.json playwright.config.ts support/app-gherkin.ts support/fixtures.ts support/gherkin.ts support/gherkin.test.ts support/oxlint-plugin.ts support/oxlint-plugin.test.ts tests",
+    "lint:features": "gherkin-lint -c .gherkin-lintrc \"features/**/*.feature\"",
+    "typecheck": "tsc --noEmit",
+    "test:debug": "playwright test --max-failures=1 --headed --debug",
+    "test:headed": "playwright test --headed",
+    "test:ui": "playwright test --ui",
+    "report": "playwright show-report"
+  },
+  "devDependencies": {
+    "@cucumber/gherkin": "^39.1.0",
+    "@cucumber/messages": "^32.3.1",
+    "@playwright/test": "latest",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^25.9.1",
+    "better-sqlite3": "^12.10.0",
+    "gherkin-lint": "^4.2.4",
+    "oxfmt": "^0.51.0",
+    "oxlint": "^1.66.0",
+    "oxlint-tsgolint": "^0.22.1",
+    "typescript": "^6.0.3"
+  }
+}

package/template/e2e/playwright.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig, devices } from "@playwright/test"
+
+export default defineConfig({
+  testDir: "./tests",
+  fullyParallel: true,
+  reporter: [["list"], ["html", { open: "never" }]],
+  use: {
+    trace: "on-first-retry",
+  },
+  projects: [
+    {
+      name: "chromium",
+      use: { ...devices["Desktop Chrome"] },
+    },
+  ],
+})

package/template/e2e/support/app-gherkin.ts

@@ -0,0 +1,4 @@
+import { test, type AppFixtures } from "./fixtures"
+import { createFeature } from "./gherkin"
+
+export const feature = createFeature<AppFixtures>(test)

package/template/e2e/support/fixtures.ts

@@ -0,0 +1,236 @@
+import { spawn, type ChildProcess } from "node:child_process"
+import { mkdirSync, rmSync } from "node:fs"
+import net from "node:net"
+import os from "node:os"
+import path from "node:path"
+
+import { test as base } from "@playwright/test"
+import Database from "better-sqlite3"
+
+type AppWorker = {
+  clientUrl: string
+  db: E2eDatabase
+  serverUrl: string
+  stop(): Promise<void>
+}
+
+type WorkerFixtures = {
+  app: AppWorker
+}
+
+export type AppFixtures = {
+  db: E2eDatabase
+  serverUrl: string
+}
+
+export const test = base.extend<AppFixtures, WorkerFixtures>({
+  app: [
+    // oxlint-disable-next-line no-empty-pattern -- Playwright worker fixtures require object destructuring here.
+    async ({}, use, workerInfo) => {
+      const app = await startAppWorker(workerInfo.workerIndex)
+
+      try {
+        await use(app)
+      } finally {
+        await app.stop()
+      }
+    },
+    { scope: "worker" },
+  ],
+  baseURL: async ({ app }, use) => {
+    await use(app.clientUrl)
+  },
+  db: async ({ app }, use) => {
+    await use(app.db)
+  },
+  serverUrl: async ({ app }, use) => {
+    await use(app.serverUrl)
+  },
+})
+
+export class E2eDatabase {
+  readonly #database: Database.Database
+
+  constructor(databasePath: string) {
+    this.#database = new Database(databasePath)
+  }
+
+  close(): void {
+    this.#database.close()
+  }
+
+  reset(): void {
+    this.#database.prepare("DELETE FROM hello_world_inputs").run()
+    this.#database.prepare("DELETE FROM projects").run()
+  }
+
+  listHelloWorldInputs(): string[] {
+    return this.#database
+      .prepare("SELECT input FROM hello_world_inputs ORDER BY created_at, id")
+      .all()
+      .map(readHelloWorldInput)
+  }
+}
+
+async function startAppWorker(workerIndex: number): Promise<AppWorker> {
+  const [serverPort, clientPort] = await Promise.all([freePort(), freePort()])
+  const rootDir = path.resolve("..")
+  const workerDir = path.join(os.tmpdir(), `backbone-e2e-${process.pid}-${workerIndex}`)
+  const databasePath = path.join(workerDir, "backbone.sqlite")
+  const databaseUrl = `sqlite://${databasePath}?mode=rwc`
+
+  rmSync(workerDir, { force: true, recursive: true })
+  mkdirSync(workerDir, { recursive: true })
+
+  const serverUrl = `http://127.0.0.1:${serverPort}`
+  const clientUrl = `http://127.0.0.1:${clientPort}`
+  const env = {
+    ...process.env,
+    APP_ENV: "test",
+    DATABASE_URL: databaseUrl,
+    SERVER_HOST: "127.0.0.1",
+    SERVER_PORT: String(serverPort),
+    VITE_DEV_SERVER_PORT: String(clientPort),
+    VITE_SERVER_URL: serverUrl,
+  }
+  const server = spawnProcess("cargo", ["run", "-p", "server"], rootDir, env)
+
+  await waitForUrl(`${serverUrl}/health`, [server], "server")
+
+  const client = spawnProcess(
+    "pnpm",
+    [
+      "--filter",
+      "backbone-client",
+      "exec",
+      "vite",
+      "--host",
+      "127.0.0.1",
+      "--port",
+      String(clientPort),
+      "--strictPort",
+    ],
+    rootDir,
+    env,
+  )
+
+  await waitForUrl(clientUrl, [server, client], "client")
+
+  const db = new E2eDatabase(databasePath)
+
+  return {
+    clientUrl,
+    db,
+    serverUrl,
+    async stop() {
+      db.close()
+      await stopProcess(client)
+      await stopProcess(server)
+      rmSync(workerDir, { force: true, recursive: true })
+    },
+  }
+}
+
+function spawnProcess(
+  command: string,
+  args: string[],
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+): ChildProcess {
+  const child = spawn(command, args, {
+    cwd,
+    env,
+    stdio: ["ignore", "pipe", "pipe"],
+  })
+
+  child.stdout?.on("data", (chunk: Buffer) => {
+    process.stdout.write(chunk)
+  })
+  child.stderr?.on("data", (chunk: Buffer) => {
+    process.stderr.write(chunk)
+  })
+
+  return child
+}
+
+async function stopProcess(child: ChildProcess): Promise<void> {
+  if (child.exitCode !== null || child.signalCode !== null) {
+    return
+  }
+
+  child.kill("SIGTERM")
+
+  await new Promise<void>((resolve) => {
+    child.once("exit", () => {
+      resolve()
+    })
+    setTimeout(() => {
+      if (child.exitCode === null && child.signalCode === null) {
+        child.kill("SIGKILL")
+      }
+      resolve()
+    }, 3000)
+  })
+}
+
+async function waitForUrl(url: string, processes: ChildProcess[], name: string): Promise<void> {
+  for (let attempt = 0; attempt < 150; attempt += 1) {
+    for (const child of processes) {
+      if (child.exitCode !== null) {
+        throw new Error(`${name} dependency exited with code ${child.exitCode}`)
+      }
+    }
+
+    try {
+      // oxlint-disable-next-line no-await-in-loop -- Readiness polling is intentionally sequential.
+      const response = await fetch(url)
+
+      if (response.ok) {
+        return
+      }
+    } catch {
+      // Keep polling until the process is ready or exits.
+    }
+
+    // oxlint-disable-next-line no-await-in-loop -- Polling attempts need a delay between checks.
+    await delay(200)
+  }
+
+  throw new Error(`Timed out waiting for ${name} at ${url}`)
+}
+
+async function freePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer()
+
+    server.once("error", reject)
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address()
+
+      if (typeof address === "object" && address !== null) {
+        const port = address.port
+        server.close(() => {
+          resolve(port)
+        })
+      } else {
+        server.close(() => {
+          reject(new Error("Could not allocate a TCP port"))
+        })
+      }
+    })
+  })
+}
+
+function readHelloWorldInput(row: unknown): string {
+  if (typeof row === "object" && row !== null && "input" in row && typeof row.input === "string") {
+    return row.input
+  }
+
+  throw new Error("Unexpected hello_world_inputs row shape")
+}
+
+async function delay(ms: number): Promise<void> {
+  await new Promise((resolve) => {
+    setTimeout(resolve, ms)
+  })
+}

package/template/e2e/support/gherkin-fixtures/duplicate-id.feature

@@ -0,0 +1,9 @@
+Feature: Duplicate id fixture
+
+  @id:fixture.duplicate-id
+  Scenario: First scenario
+    Given the first scenario uses the id
+
+  @id:fixture.duplicate-id
+  Scenario: Second scenario
+    Given the second scenario reuses the id

package/template/e2e/support/gherkin-fixtures/duplicate-id.spec.ts

@@ -0,0 +1,7 @@
+import { feature } from "../gherkin"
+
+feature("./duplicate-id.feature", {
+  "fixture.duplicate-id": async ({ scenario }) => {
+    await scenario.step("Given the first scenario uses the id", async () => {})
+  },
+})

package/template/e2e/support/gherkin-fixtures/extra-implementation.spec.ts

@@ -0,0 +1,7 @@
+import { feature } from "../gherkin"
+import { validImplementations } from "./valid-implementations"
+
+feature("./valid-scenarios.feature", {
+  ...validImplementations,
+  "fixture.unused-implementation": async () => {},
+})

package/template/e2e/support/gherkin-fixtures/extra-step.spec.ts

@@ -0,0 +1,10 @@
+import { feature } from "../gherkin"
+import { validImplementations } from "./valid-implementations"
+
+feature("./valid-scenarios.feature", {
+  ...validImplementations,
+  "fixture.extra-step": async ({ scenario }) => {
+    await scenario.step("Given the only documented step", async () => {})
+    await scenario.step("Then an extra implementation step runs", async () => {})
+  },
+})

package/template/e2e/support/gherkin-fixtures/happy-path.spec.ts

@@ -0,0 +1,4 @@
+import { feature } from "../gherkin"
+import { validImplementations } from "./valid-implementations"
+
+feature("./valid-scenarios.feature", validImplementations)

package/template/e2e/support/gherkin-fixtures/missing-id.feature

@@ -0,0 +1,4 @@
+Feature: Missing id fixture
+
+  Scenario: Missing id fails
+    Given the scenario has no id tag

package/template/e2e/support/gherkin-fixtures/missing-id.spec.ts

@@ -0,0 +1,7 @@
+import { feature } from "../gherkin"
+
+feature("./missing-id.feature", {
+  "fixture.missing-id": async ({ scenario }) => {
+    await scenario.step("Given the scenario has no id tag", async () => {})
+  },
+})

package/template/e2e/support/gherkin-fixtures/missing-implementation.spec.ts

@@ -0,0 +1,7 @@
+import { feature } from "../gherkin"
+import { validImplementations } from "./valid-implementations"
+
+const { "fixture.missing-implementation": _missingImplementation, ...implementations } =
+  validImplementations
+
+feature("./valid-scenarios.feature", implementations)

package/template/e2e/support/gherkin-fixtures/missing-step.spec.ts

@@ -0,0 +1,7 @@
+import { feature } from "../gherkin"
+import { validImplementations } from "./valid-implementations"
+
+feature("./valid-scenarios.feature", {
+  ...validImplementations,
+  "fixture.missing-step": async () => {},
+})

package/template/e2e/support/gherkin-fixtures/playwright.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "@playwright/test"
+
+export default defineConfig({
+  reporter: "line",
+  testDir: ".",
+  workers: 1,
+})

package/template/e2e/support/gherkin-fixtures/scenario-outline.feature

@@ -0,0 +1,9 @@
+Feature: Scenario outline fixture
+
+  @id:fixture.scenario-outline
+  Scenario Outline: Scenario outlines fail
+    Given the value is <value>
+
+    Examples:
+      | value |
+      | one   |

package/template/e2e/support/gherkin-fixtures/scenario-outline.spec.ts

@@ -0,0 +1,7 @@
+import { feature } from "../gherkin"
+
+feature("./scenario-outline.feature", {
+  "fixture.scenario-outline": async ({ scenario }) => {
+    await scenario.step("Given the value is one", async () => {})
+  },
+})

package/template/e2e/support/gherkin-fixtures/step-mismatch.spec.ts

@@ -0,0 +1,9 @@
+import { feature } from "../gherkin"
+import { validImplementations } from "./valid-implementations"
+
+feature("./valid-scenarios.feature", {
+  ...validImplementations,
+  "fixture.step-mismatch": async ({ scenario }) => {
+    await scenario.step("Given a different step name", async () => {})
+  },
+})

package/template/e2e/support/gherkin-fixtures/valid-implementations.ts

@@ -0,0 +1,23 @@
+import type { ScenarioImplementation } from "../gherkin"
+
+export const validImplementations: Record<string, ScenarioImplementation> = {
+  "fixture.happy-path": async ({ scenario }) => {
+    await scenario.step("Given the first step matches", async () => {})
+    await scenario.step("Then the second step matches", async () => {})
+  },
+  "fixture.step-mismatch": async ({ scenario }) => {
+    await scenario.step("Given the documented step name", async () => {})
+  },
+  "fixture.missing-step": async ({ scenario }) => {
+    await scenario.step("Given the documented step is not implemented", async () => {})
+  },
+  "fixture.extra-step": async ({ scenario }) => {
+    await scenario.step("Given the only documented step", async () => {})
+  },
+  "fixture.missing-implementation": async ({ scenario }) => {
+    await scenario.step("Given the scenario is not implemented", async () => {})
+  },
+  "fixture.extra-implementation": async ({ scenario }) => {
+    await scenario.step("Given the feature has one implementation", async () => {})
+  },
+}

package/template/e2e/support/gherkin-fixtures/valid-scenarios.feature

@@ -0,0 +1,26 @@
+Feature: Valid adapter fixture scenarios
+
+  @id:fixture.happy-path
+  Scenario: Matching steps pass
+    Given the first step matches
+    Then the second step matches
+
+  @id:fixture.step-mismatch
+  Scenario: Renamed implementation step fails
+    Given the documented step name
+
+  @id:fixture.missing-step
+  Scenario: Missing implementation step fails
+    Given the documented step is not implemented
+
+  @id:fixture.extra-step
+  Scenario: Extra implementation step fails
+    Given the only documented step
+
+  @id:fixture.missing-implementation
+  Scenario: Missing implementation fails
+    Given the scenario is not implemented
+
+  @id:fixture.extra-implementation
+  Scenario: Extra implementation fails
+    Given the feature has one implementation