canary-lab 0.1.0

package/dist/templates/project/AGENTS.md

@@ -0,0 +1,27 @@
+# Canary Lab Agent Guide
+
+For the full Codex self-fixing workflow, read:
+
+- `.codex/self-fixing-loop.md`
+
+## Quick Start
+
+1. Run `npx canary-lab run`
+2. Leave the runner open in watch mode
+3. In Codex, type:
+
+```text
+self heal
+```
+
+## What `self heal` Means
+
+When the user types `self heal`, follow `.codex/self-fixing-loop.md`.
+
+That workflow covers:
+
+- which logs to inspect
+- how to diagnose the failure
+- the rule to fix implementation only
+- when to use `touch logs/.restart`
+- when to use `touch logs/.rerun`

package/dist/templates/project/CLAUDE.md

@@ -0,0 +1,31 @@
+# Canary Lab Project Notes
+
+For the full Claude self-fixing workflow, read:
+
+- `.claude/skills/self-fixing-loop.md`
+
+## Quick Start
+
+```bash
+npm install
+npm run install:browsers
+npx canary-lab run
+```
+
+Leave the runner open in watch mode, then type:
+
+```text
+self heal
+```
+
+## What `self heal` Means
+
+When the user types `self heal`, follow `.claude/skills/self-fixing-loop.md`.
+
+That workflow covers:
+
+- which logs to inspect
+- how to diagnose the failure
+- the rule to fix implementation only
+- when to use `touch logs/.restart`
+- when to use `touch logs/.rerun`

package/dist/templates/project/features/broken_todo_api/.env.example

@@ -0,0 +1 @@
+GATEWAY_URL=http://localhost:4100

package/dist/templates/project/features/broken_todo_api/e2e/broken-todo-api.spec.js

@@ -0,0 +1,34 @@
+const { test, expect } = require('canary-lab/feature-support/log-marker-fixture')
+const { TodoApi } = require('./helpers/api')
+
+const api = new TodoApi()
+
+test.describe('broken_todo_api', () => {
+  test('POST /todos creates a todo', async () => {
+    const todo = await api.create('Write logs')
+    expect(todo.id).toBeTruthy()
+    expect(todo.title).toBe('Write logs')
+    expect(todo.done).toBe(false)
+  })
+
+  test('GET /todos lists created todos', async () => {
+    const todo = await api.create('Visible in list')
+    const todos = await api.list()
+    expect(todos.find((entry) => entry.id === todo.id)?.title).toBe(
+      'Visible in list',
+    )
+  })
+
+  test('PATCH /todos/:id marks a todo as done', async () => {
+    const todo = await api.create('Should become done')
+    const updated = await api.markDone(todo.id)
+    expect(updated.done).toBe(true)
+  })
+
+  test('DELETE /todos/:id removes a todo', async () => {
+    const todo = await api.create('This should be removed')
+    await api.remove(todo.id)
+    const todos = await api.list()
+    expect(todos.find((entry) => entry.id === todo.id)).toBeUndefined()
+  })
+})

package/dist/templates/project/features/broken_todo_api/e2e/helpers/api.js

@@ -0,0 +1,48 @@
+const { GATEWAY_URL } = require('../../src/config')
+
+class TodoApi {
+  constructor() {
+    this.baseUrl = GATEWAY_URL
+  }
+
+  async create(title) {
+    const res = await fetch(`${this.baseUrl}/todos`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ title }),
+    })
+    if (!res.ok) {
+      throw new Error(`POST /todos failed: ${res.status}`)
+    }
+    return res.json()
+  }
+
+  async list() {
+    const res = await fetch(`${this.baseUrl}/todos`)
+    if (!res.ok) {
+      throw new Error(`GET /todos failed: ${res.status}`)
+    }
+    return res.json()
+  }
+
+  async remove(id) {
+    const res = await fetch(`${this.baseUrl}/todos/${id}`, { method: 'DELETE' })
+    if (!res.ok && res.status !== 204) {
+      throw new Error(`DELETE /todos/${id} failed: ${res.status}`)
+    }
+  }
+
+  async markDone(id) {
+    const res = await fetch(`${this.baseUrl}/todos/${id}`, {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ done: true }),
+    })
+    if (!res.ok) {
+      throw new Error(`PATCH /todos/${id} failed: ${res.status}`)
+    }
+    return res.json()
+  }
+}
+
+module.exports = { TodoApi }

package/dist/templates/project/features/broken_todo_api/envsets/envsets.config.json

@@ -0,0 +1,14 @@
+{
+  "appRoots": {},
+  "slots": {
+    "broken_todo_api.env": {
+      "description": "Environment file for the intentionally broken TODO API sample",
+      "target": "$CANARY_LAB_PROJECT_ROOT/features/broken_todo_api/.env"
+    }
+  },
+  "feature": {
+    "slots": ["broken_todo_api.env"],
+    "testCommand": "npx playwright test",
+    "testCwd": "$CANARY_LAB_PROJECT_ROOT/features/broken_todo_api"
+  }
+}

package/dist/templates/project/features/broken_todo_api/envsets/local/broken_todo_api.env

@@ -0,0 +1 @@
+GATEWAY_URL=http://localhost:4100

package/dist/templates/project/features/broken_todo_api/feature.config.cjs

@@ -0,0 +1,24 @@
+const config = {
+  name: 'broken_todo_api',
+  description: 'Intentionally broken sample feature with mixed passing and failing tests for self-fixing practice.',
+  envs: ['local'],
+  repos: [
+    {
+      name: 'broken_todo_api',
+      localPath: __dirname,
+      startCommands: [
+        {
+          name: 'broken-todo-api-server',
+          command: 'node scripts/server.js',
+          healthCheck: {
+            url: 'http://localhost:4100/',
+            timeoutMs: 3000,
+          },
+        },
+      ],
+    },
+  ],
+  featureDir: __dirname,
+}
+
+module.exports = { config }

package/dist/templates/project/features/broken_todo_api/playwright.config.js

@@ -0,0 +1,6 @@
+const { defineConfig } = require('@playwright/test')
+const { baseConfig } = require('canary-lab/feature-support/playwright-base')
+
+module.exports = defineConfig({
+  ...baseConfig,
+})

package/dist/templates/project/features/broken_todo_api/scripts/server.js

@@ -0,0 +1,76 @@
+const http = require('http')
+
+const todos = []
+let nextId = 1
+
+const server = http.createServer((req, res) => {
+  const url = new URL(req.url ?? '/', `http://${req.headers.host}`)
+  const method = req.method ?? 'GET'
+
+  console.log(`[broken_todo_api] ${method} ${url.pathname}`)
+  res.setHeader('Content-Type', 'application/json')
+
+  if (method === 'GET' && url.pathname === '/') {
+    res.end(JSON.stringify({ status: 'ok' }))
+    return
+  }
+
+  if (method === 'GET' && url.pathname === '/todos') {
+    res.end(JSON.stringify(todos))
+    return
+  }
+
+  if (method === 'POST' && url.pathname === '/todos') {
+    let body = ''
+    req.on('data', (chunk) => {
+      body += chunk
+    })
+    req.on('end', () => {
+      const parsed = JSON.parse(body || '{}')
+      const todo = { id: String(nextId++), title: parsed.title, done: false }
+      todos.push(todo)
+      res.writeHead(201)
+      res.end(JSON.stringify(todo))
+    })
+    return
+  }
+
+  if (method === 'PATCH' && url.pathname.startsWith('/todos/')) {
+    const id = url.pathname.split('/')[2]
+    const todo = todos.find((entry) => entry.id === id)
+    if (!todo) {
+      res.writeHead(404)
+      res.end(JSON.stringify({ error: 'not found' }))
+      return
+    }
+
+    let body = ''
+    req.on('data', (chunk) => {
+      body += chunk
+    })
+    req.on('end', () => {
+      const parsed = JSON.parse(body || '{}')
+      console.log(
+        `[broken_todo_api] simulated bug: ignoring done=${parsed.done} for ${id}`,
+      )
+      res.end(JSON.stringify(todo))
+    })
+    return
+  }
+
+  if (method === 'DELETE' && url.pathname.startsWith('/todos/')) {
+    const id = url.pathname.split('/')[2]
+    console.log(`[broken_todo_api] simulated bug: refusing to delete ${id}`)
+    res.writeHead(204)
+    res.end()
+    return
+  }
+
+  res.writeHead(404)
+  res.end(JSON.stringify({ error: 'not found' }))
+})
+
+const port = Number.parseInt(process.env.PORT ?? '4100', 10)
+server.listen(port, () => {
+  console.log(`Broken TODO API listening on http://localhost:${port}`)
+})

package/dist/templates/project/features/broken_todo_api/src/config.js

@@ -0,0 +1,9 @@
+const { loadFeatureEnv } = require('canary-lab/feature-support/load-env')
+
+loadFeatureEnv(__dirname + '/..')
+
+const GATEWAY_URL = process.env.GATEWAY_URL ?? 'http://localhost:4100'
+
+module.exports = {
+  GATEWAY_URL,
+}

package/dist/templates/project/features/example_todo_api/.env.example

@@ -0,0 +1 @@
+GATEWAY_URL=http://localhost:4000

package/dist/templates/project/features/example_todo_api/e2e/helpers/api.js

@@ -0,0 +1,36 @@
+const { GATEWAY_URL } = require('../../src/config')
+
+class TodoApi {
+  constructor() {
+    this.baseUrl = GATEWAY_URL
+  }
+
+  async create(title) {
+    const res = await fetch(`${this.baseUrl}/todos`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ title }),
+    })
+    if (!res.ok) {
+      throw new Error(`POST /todos failed: ${res.status}`)
+    }
+    return res.json()
+  }
+
+  async list() {
+    const res = await fetch(`${this.baseUrl}/todos`)
+    if (!res.ok) {
+      throw new Error(`GET /todos failed: ${res.status}`)
+    }
+    return res.json()
+  }
+
+  async remove(id) {
+    const res = await fetch(`${this.baseUrl}/todos/${id}`, { method: 'DELETE' })
+    if (!res.ok && res.status !== 204) {
+      throw new Error(`DELETE /todos/${id} failed: ${res.status}`)
+    }
+  }
+}
+
+module.exports = { TodoApi }

package/dist/templates/project/features/example_todo_api/e2e/todo-api.spec.js

@@ -0,0 +1,25 @@
+const { test, expect } = require('canary-lab/feature-support/log-marker-fixture')
+const { TodoApi } = require('./helpers/api')
+
+const api = new TodoApi()
+
+test.describe('example_todo_api', () => {
+  test('POST /todos creates a todo', async () => {
+    const todo = await api.create('Buy milk')
+    expect(todo.id).toBeTruthy()
+    expect(todo.title).toBe('Buy milk')
+    expect(todo.done).toBe(false)
+  })
+
+  test('GET /todos lists todos', async () => {
+    const todos = await api.list()
+    expect(todos.length).toBeGreaterThan(0)
+  })
+
+  test('DELETE /todos/:id removes a todo', async () => {
+    const todo = await api.create('Temporary item')
+    await api.remove(todo.id)
+    const todos = await api.list()
+    expect(todos.find((entry) => entry.id === todo.id)).toBeUndefined()
+  })
+})

package/dist/templates/project/features/example_todo_api/envsets/envsets.config.json

@@ -0,0 +1,14 @@
+{
+  "appRoots": {},
+  "slots": {
+    "example_todo_api.env": {
+      "description": "Environment file for the example TODO API sample",
+      "target": "$CANARY_LAB_PROJECT_ROOT/features/example_todo_api/.env"
+    }
+  },
+  "feature": {
+    "slots": ["example_todo_api.env"],
+    "testCommand": "npx playwright test",
+    "testCwd": "$CANARY_LAB_PROJECT_ROOT/features/example_todo_api"
+  }
+}

package/dist/templates/project/features/example_todo_api/envsets/local/example_todo_api.env

@@ -0,0 +1 @@
+GATEWAY_URL=http://localhost:4000

package/dist/templates/project/features/example_todo_api/feature.config.cjs

@@ -0,0 +1,24 @@
+const config = {
+  name: 'example_todo_api',
+  description: 'Working sample feature for Canary Lab.',
+  envs: ['local'],
+  repos: [
+    {
+      name: 'example_todo_api',
+      localPath: __dirname,
+      startCommands: [
+        {
+          name: 'example-todo-api-server',
+          command: 'node scripts/server.js',
+          healthCheck: {
+            url: 'http://localhost:4000/',
+            timeoutMs: 3000,
+          },
+        },
+      ],
+    },
+  ],
+  featureDir: __dirname,
+}
+
+module.exports = { config }

package/dist/templates/project/features/example_todo_api/playwright.config.js

@@ -0,0 +1,6 @@
+const { defineConfig } = require('@playwright/test')
+const { baseConfig } = require('canary-lab/feature-support/playwright-base')
+
+module.exports = defineConfig({
+  ...baseConfig,
+})

package/dist/templates/project/features/example_todo_api/scripts/server.js

@@ -0,0 +1,60 @@
+const http = require('http')
+
+const todos = []
+let nextId = 1
+
+const server = http.createServer((req, res) => {
+  const url = new URL(req.url ?? '/', `http://${req.headers.host}`)
+  const method = req.method ?? 'GET'
+
+  console.log(`[example_todo_api] ${method} ${url.pathname}`)
+  res.setHeader('Content-Type', 'application/json')
+
+  if (method === 'GET' && url.pathname === '/') {
+    res.end(JSON.stringify({ status: 'ok' }))
+    return
+  }
+
+  if (method === 'GET' && url.pathname === '/todos') {
+    res.end(JSON.stringify(todos))
+    return
+  }
+
+  if (method === 'POST' && url.pathname === '/todos') {
+    let body = ''
+    req.on('data', (chunk) => {
+      body += chunk
+    })
+    req.on('end', () => {
+      const parsed = JSON.parse(body || '{}')
+      const todo = { id: String(nextId++), title: parsed.title, done: false }
+      todos.push(todo)
+      res.writeHead(201)
+      res.end(JSON.stringify(todo))
+    })
+    return
+  }
+
+  if (method === 'DELETE' && url.pathname.startsWith('/todos/')) {
+    const id = url.pathname.split('/')[2]
+    const idx = todos.findIndex((todo) => todo.id === id)
+    if (idx === -1) {
+      res.writeHead(404)
+      res.end(JSON.stringify({ error: 'not found' }))
+      return
+    }
+
+    todos.splice(idx, 1)
+    res.writeHead(204)
+    res.end()
+    return
+  }
+
+  res.writeHead(404)
+  res.end(JSON.stringify({ error: 'not found' }))
+})
+
+const port = Number.parseInt(process.env.PORT ?? '4000', 10)
+server.listen(port, () => {
+  console.log(`Example TODO API listening on http://localhost:${port}`)
+})

package/dist/templates/project/features/example_todo_api/src/config.js

@@ -0,0 +1,9 @@
+const { loadFeatureEnv } = require('canary-lab/feature-support/load-env')
+
+loadFeatureEnv(__dirname + '/..')
+
+const GATEWAY_URL = process.env.GATEWAY_URL ?? 'http://localhost:4000'
+
+module.exports = {
+  GATEWAY_URL,
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "canary-lab",
+  "version": "0.1.0",
+  "description": "E2E test scaffolder and runner with agent-assisted self-fixing workflows",
+  "keywords": [
+    "playwright",
+    "e2e",
+    "testing",
+    "test-runner",
+    "local-development",
+    "observability",
+    "developer-tools",
+    "ai-agents",
+    "claude",
+    "codex"
+  ],
+  "author": {
+    "name": "Fer Terahadi",
+    "email": "fernanditerahadi@gmail.com",
+    "url": "https://github.com/ferterahadi/canary-lab"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ferterahadi/canary-lab.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ferterahadi/canary-lab/issues"
+  },
+  "homepage": "https://github.com/ferterahadi/canary-lab#readme",
+  "engines": {
+    "node": ">=20.0.0",
+    "npm": ">=9.0.0"
+  },
+  "bin": {
+    "canary-lab": "dist/scripts/cli.js"
+  },
+  "exports": {
+    "./feature-support/playwright-base": "./dist/feature-support/playwright-base.js",
+    "./feature-support/load-env": "./dist/feature-support/load-env.js",
+    "./feature-support/log-marker-fixture": "./dist/feature-support/log-marker-fixture.js",
+    "./feature-support/types": "./dist/feature-support/types.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node tools/prepare-assets.mjs",
+    "canary-lab:run": "node dist/scripts/cli.js run",
+    "canary-lab:env": "node dist/scripts/cli.js env",
+    "canary-lab:new-feature": "node dist/scripts/cli.js new-feature",
+    "prepack": "npm run build",
+    "pack:check": "node tools/pack-check.mjs",
+    "smoke:pack": "node tools/smoke-pack.mjs",
+    "publish:package": "node tools/publish-package.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "tsx": "^4.20.3",
+    "typescript": "^5.9.2"
+  },
+  "dependencies": {
+    "@playwright/test": "^1.54.2",
+    "dotenv": "^16.6.1"
+  }
+}