devmethod-ai 0.1.0-rc.2 → 0.1.0

package/examples/pocket-tasks/public/app.js

@@ -0,0 +1,84 @@
+'use strict';
+const $ = selector => document.querySelector(selector);
+let tasks = [], filter = 'all', busy = false, editing = null;
+const status = message => { $('#status').textContent = message; };
+function showError(message, canReload = true) { $('#error').textContent = message; $('#error').hidden = !message; $('#retry').hidden = !message || !canReload; }
+async function api(path = '', options = {}) {
+  const response = await fetch(`/api/tasks${path}`, { ...options, headers: { 'Content-Type': 'application/json' } });
+  if (response.status === 204) return;
+  const result = await response.json();
+  if (!response.ok) { const error = new Error(result.error || 'Request failed.'); error.status = response.status; throw error; }
+  return result;
+}
+function setBusy(value) {
+  busy = value;
+  document.querySelectorAll('button,input').forEach(element => { element.disabled = value; });
+  $('#tasks').setAttribute('aria-busy', String(value));
+}
+function button(label, action, className = '') {
+  const element = document.createElement('button'); element.type = 'button'; element.textContent = label; element.className = className; element.addEventListener('click', action); return element;
+}
+function render() {
+  const list = $('#tasks'); list.replaceChildren();
+  const visible = tasks.filter(task => filter === 'all' || task.done === (filter === 'completed'));
+  $('#count').textContent = `${tasks.length} ${tasks.length === 1 ? 'task' : 'tasks'} · ${tasks.filter(task => !task.done).length} active`;
+  $('#empty').hidden = visible.length > 0;
+  $('#empty').textContent = tasks.length === 0 ? 'No tasks yet. Add your first above.' : `No ${filter} tasks.`;
+  for (const task of visible) {
+    const row = document.createElement('li'); row.className = `task${task.done ? ' done' : ''}`;
+    if (editing === task.id) {
+      const form = document.createElement('form'); form.className = 'edit-form';
+      const label = document.createElement('label'); label.htmlFor = 'edit-title'; label.textContent = 'Edit task title';
+      const controls = document.createElement('div'); controls.className = 'edit-row';
+      const input = document.createElement('input'); input.id = 'edit-title'; input.value = task.title; input.maxLength = 120; input.required = true;
+      const save = document.createElement('button'); save.type = 'submit'; save.textContent = 'Save'; save.className = 'primary';
+      const cancel = button('Cancel', () => { editing = null; render(); focusEdit(task.id); });
+      form.addEventListener('submit', event => { event.preventDefault(); mutate(`/${task.id}`, 'PATCH', { title: input.value }, 'Task updated.', () => focusEdit(task.id)); });
+      input.addEventListener('keydown', event => { if (event.key === 'Escape') { editing = null; render(); focusEdit(task.id); } });
+      controls.append(input, save, cancel); form.append(label, controls); row.append(form);
+    } else {
+      const checkbox = document.createElement('input'); checkbox.type = 'checkbox'; checkbox.checked = task.done; checkbox.setAttribute('aria-label', `Mark ${task.title} ${task.done ? 'active' : 'completed'}`);
+      checkbox.addEventListener('change', () => mutate(`/${task.id}`, 'PATCH', { done: checkbox.checked }, task.done ? 'Task reopened.' : 'Task completed.', () => { const next = document.querySelector(`[data-toggle="${task.id}"]`); (next || $('#new-title')).focus(); }));
+      checkbox.dataset.toggle = task.id;
+      const title = document.createElement('span'); title.className = 'task-title'; title.textContent = task.title;
+      const actions = document.createElement('div'); actions.className = 'actions';
+      const edit = button('Edit', () => { editing = task.id; render(); $('#edit-title').focus(); }); edit.dataset.edit = task.id; edit.setAttribute('aria-label', `Edit ${task.title}`);
+      const remove = button('Delete', () => mutate(`/${task.id}`, 'DELETE', undefined, 'Task deleted.', () => $('#new-title').focus()), 'delete'); remove.setAttribute('aria-label', `Delete ${task.title}`);
+      actions.append(edit, remove); row.append(checkbox, title, actions);
+    }
+    list.append(row);
+  }
+  document.querySelectorAll('[data-filter]').forEach(element => element.setAttribute('aria-pressed', String(element.dataset.filter === filter)));
+}
+function focusEdit(id) { (document.querySelector(`[data-edit="${id}"]`) || $('#new-title')).focus(); }
+async function mutate(path, method, body, message, focus) {
+  if (busy) return;
+  setBusy(true); showError(''); status('Saving…');
+  try {
+    const result = await api(path, { method, ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+    if (method === 'POST') { tasks.push(result.task); $('#new-title').value = ''; }
+    else if (method === 'PATCH') tasks = tasks.map(task => task.id === result.task.id ? result.task : task);
+    else tasks = tasks.filter(task => `/${task.id}` !== path);
+    editing = null; render(); status(message);
+  } catch (error) {
+    if (error.status >= 400 && error.status < 500) {
+      showError(error.message, false); status('Change rejected. Correct the input and try again.');
+      document.querySelectorAll('[data-toggle]').forEach(checkbox => { checkbox.checked = tasks.find(task => task.id === checkbox.dataset.toggle).done; });
+      focus = () => ($('#edit-title') || $('#new-title')).focus();
+    } else {
+      showError(`${error.message} Reload to check saved state before retrying a change.`); status('Change could not be confirmed.'); render();
+    }
+  }
+  finally { setBusy(false); focus?.(); }
+}
+async function load() {
+  if (busy) return;
+  setBusy(true); showError(''); status('Loading tasks…'); $('#empty').hidden = true;
+  try { tasks = (await api()).tasks; editing = null; render(); status('Tasks loaded.'); }
+  catch (error) { showError(error.message); status('Tasks could not be loaded.'); }
+  finally { setBusy(false); }
+}
+$('#add-form').addEventListener('submit', event => { event.preventDefault(); mutate('', 'POST', { title: $('#new-title').value }, 'Task added.', () => $('#new-title').focus()); });
+document.querySelectorAll('[data-filter]').forEach(element => element.addEventListener('click', () => { filter = element.dataset.filter; editing = null; render(); status(`Showing ${filter} tasks.`); }));
+$('#retry').addEventListener('click', load);
+load();

package/examples/pocket-tasks/public/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Pocket Tasks</title><link rel="stylesheet" href="/styles.css"><script src="/app.js" defer></script></head>
+<body><main>
+<header><span class="eyebrow">A LITTLE SPACE TO GET THINGS DONE</span><h1>Pocket Tasks<span aria-hidden="true">.</span></h1><p>Clear your head. Start with one small thing.</p></header>
+<section class="workspace" aria-label="Your tasks">
+<form id="add-form"><label for="new-title">What needs doing?</label><div class="add-row"><input id="new-title" name="title" maxlength="120" required placeholder="e.g. Plan tomorrow’s walk" autocomplete="off"><button type="submit" class="primary">Add task</button></div></form>
+<div class="toolbar"><div class="filters" role="group" aria-label="Filter tasks"><button type="button" data-filter="all" aria-pressed="true">All</button><button type="button" data-filter="active" aria-pressed="false">Active</button><button type="button" data-filter="completed" aria-pressed="false">Completed</button></div><span id="count">0 tasks</span></div>
+<p id="status" role="status" aria-live="polite">Loading tasks…</p><div id="error" role="alert" hidden></div><button id="retry" type="button" hidden>Reload tasks</button>
+<ul id="tasks" aria-label="Task list"></ul><p id="empty" hidden>No tasks yet. Add your first above.</p>
+</section><footer>Stored on this computer. One task at a time.</footer>
+</main></body></html>

package/examples/pocket-tasks/public/styles.css

@@ -0,0 +1 @@
+:root{font-family:system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;color:#213e39;background:#f4f6f1;font-synthesis:none;line-height:1.5}*{box-sizing:border-box}body{margin:0}main{max-width:820px;margin:64px auto;padding:0 28px}header{margin-bottom:32px}.eyebrow{font-size:11px;font-weight:750;letter-spacing:2px;color:#5a7067}h1{font-size:clamp(36px,7vw,54px);letter-spacing:-2px;margin:12px 0 8px;line-height:1.1}h1 span{color:#bf651b}header p{color:#5b6e64;margin:0}.workspace{background:white;border:1px solid #dbe4d8;border-radius:20px;padding:28px;box-shadow:0 16px 40px #23463208}label{display:block;font-weight:650;font-size:14px;margin-bottom:10px}.add-row{display:flex;gap:10px}input[type=text],input:not([type]){min-width:0;flex:1;width:100%;border:1px solid #b8c9bf;background:#fbfcfa;border-radius:9px;padding:12px;font:inherit;color:inherit}button{border:1px solid #cdd8cf;border-radius:8px;background:#fff;padding:10px 14px;color:#29483e;font:inherit;font-size:14px;font-weight:650;cursor:pointer;min-height:44px}button:hover{background:#edf3ec}.primary{background:#285743;color:#fff;border-color:#285743}.primary:hover{background:#1c4232}button:disabled,input:disabled{opacity:.65;cursor:wait}:focus-visible{outline:3px solid #b2671d;outline-offset:3px}.toolbar{display:flex;justify-content:space-between;align-items:center;gap:12px;border-bottom:1px solid #e7ece5;margin-top:26px;padding-bottom:18px}.filters{display:flex;gap:5px;flex-wrap:wrap}.filters button{border-color:transparent;font-size:13px;padding:8px 12px}.filters button[aria-pressed=true]{background:#e7f0e7;color:#17452f;border-color:#b5cbb7}#count{font-size:12px;color:#617567;white-space:nowrap}#status{font-size:13px;color:#4d695a;margin:16px 0 0;min-height:20px}#error{color:#8d281d;background:#fff0ec;padding:12px;margin-top:12px;border-radius:8px}#tasks{list-style:none;margin:8px 0 0;padding:0}.task{display:flex;align-items:center;gap:12px;padding:17px 0;border-bottom:1px solid #e8ece6}.task:last-child{border-bottom:0}.task input[type=checkbox]{width:22px;height:22px;flex-shrink:0;accent-color:#285743;cursor:pointer}.task-title{flex:1;min-width:0;overflow-wrap:anywhere}.task.done .task-title{text-decoration:line-through;color:#718076}.actions{display:flex;gap:6px}.actions button{font-size:12px;padding:8px 10px}.delete{color:#8b4030}.edit-form{width:100%}.edit-row{display:flex;gap:8px;flex-wrap:wrap}.edit-row input{flex-basis:200px}#empty{text-align:center;color:#667c6e;padding:32px 4px}footer{font-size:12px;color:#647569;text-align:center;margin-top:24px}[hidden]{display:none!important}@media(max-width:540px){main{margin:28px auto;padding:0 16px}.workspace{padding:18px;border-radius:14px}.add-row{flex-direction:column}.toolbar{align-items:flex-start;flex-direction:column;gap:6px}.task{flex-wrap:wrap;gap:10px}.task-title{flex-basis:calc(100% - 40px)}.actions{margin-left:32px}.edit-row input{flex-basis:100%}.eyebrow{font-size:9px;letter-spacing:1px}}

package/examples/pocket-tasks/server.mjs

@@ -0,0 +1,79 @@
+import { createServer } from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { resolve } from 'node:path';
+import { createStore } from './src/store.mjs';
+import { TaskError, validateBody } from './src/domain.mjs';
+
+const assets = new Map([
+  ['/', ['index.html', 'text/html; charset=utf-8']],
+  ['/styles.css', ['styles.css', 'text/css; charset=utf-8']],
+  ['/app.js', ['app.js', 'text/javascript; charset=utf-8']],
+]);
+function body(request) {
+  return new Promise((resolveBody, reject) => {
+    const chunks = []; let size = 0, exceeded = false;
+    request.on('data', chunk => {
+      size += chunk.length;
+      if (size > 16384) {
+        if (!exceeded) { exceeded = true; chunks.length = 0; reject(new TaskError('Request body exceeds 16 KiB.', 413)); }
+      } else if (!exceeded) chunks.push(chunk);
+    });
+    request.on('end', () => {
+      if (exceeded) return;
+      try { resolveBody(JSON.parse(Buffer.concat(chunks).toString('utf8'))); }
+      catch { reject(new TaskError('Malformed JSON.')); }
+    });
+    request.on('error', reject);
+  });
+}
+function validateLocalRequest(request) {
+  const expectedHost = `127.0.0.1:${request.socket.localPort}`;
+  const hostCount = request.rawHeaders.filter((_, index) => index % 2 === 0 && request.rawHeaders[index].toLowerCase() === 'host').length;
+  if (hostCount !== 1 || request.headers.host !== expectedHost) throw new TaskError('Use the local 127.0.0.1 address and server port.', 403);
+  if (!['POST', 'PATCH', 'DELETE'].includes(request.method)) return;
+  const originCount = request.rawHeaders.filter((_, index) => index % 2 === 0 && request.rawHeaders[index].toLowerCase() === 'origin').length;
+  if (originCount > 1 || (request.headers.origin !== undefined && request.headers.origin !== `http://${expectedHost}`) || request.headers['sec-fetch-site'] === 'cross-site') {
+    throw new TaskError('Cross-site changes are not permitted.', 403);
+  }
+}
+function requireJSON(request) {
+  if (request.headers['content-type']?.split(';', 1)[0].trim().toLowerCase() !== 'application/json') throw new TaskError('Content-Type must be application/json.', 415);
+}
+function json(response, status, value) {
+  response.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' });
+  response.end(value === undefined ? undefined : JSON.stringify(value));
+}
+export function createTaskServer({ dataFile }) {
+  const store = createStore(resolve(dataFile));
+  return createServer(async (request, response) => {
+    response.setHeader('X-Content-Type-Options', 'nosniff');
+    response.setHeader('Content-Security-Policy', "default-src 'self'; script-src 'self'; style-src 'self'; object-src 'none'; base-uri 'none'; frame-ancestors 'none'");
+    try {
+      validateLocalRequest(request);
+      const pathname = new URL(request.url, 'http://127.0.0.1').pathname;
+      if (pathname === '/api/tasks' && request.method === 'GET') return json(response, 200, { tasks: await store.list() });
+      if (pathname === '/api/tasks' && request.method === 'POST') { requireJSON(request); return json(response, 201, { task: await store.create(validateBody(await body(request))) }); }
+      const match = /^\/api\/tasks\/([^/]+)$/.exec(pathname);
+      if (match && request.method === 'PATCH') { requireJSON(request); return json(response, 200, { task: await store.update(decodeURIComponent(match[1]), validateBody(await body(request), true)) }); }
+      if (match && request.method === 'DELETE') { await store.remove(decodeURIComponent(match[1])); return json(response, 204); }
+      if (request.method === 'GET' && assets.has(pathname)) {
+        const [file, type] = assets.get(pathname);
+        const content = await readFile(new URL(`./public/${file}`, import.meta.url));
+        response.writeHead(200, { 'Content-Type': type }); return response.end(content);
+      }
+      json(response, 404, { error: 'Not found.' });
+    } catch (error) {
+      const status = error instanceof TaskError ? error.status : error instanceof URIError ? 400 : 500;
+      json(response, status, { error: status === 500 ? 'Storage or server unavailable. Check local data and server permissions; existing data has not been reset.' : error.message });
+    }
+  });
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  const port = Number(process.env.PORT ?? 4318);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error('PORT must be an integer from 0 to 65535.');
+  const server = createTaskServer({ dataFile: process.env.DATA_FILE ?? fileURLToPath(new URL('./data/tasks.json', import.meta.url)) });
+  server.on('error', error => { console.error(`Pocket Tasks could not start: ${error.message}`); process.exitCode = 1; });
+  server.listen(port, '127.0.0.1', () => console.log(`Pocket Tasks: http://127.0.0.1:${server.address().port}`));
+  for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => server.close());
+}

package/examples/pocket-tasks/src/domain.mjs

@@ -0,0 +1,31 @@
+export class TaskError extends Error {
+  constructor(message, status = 400) { super(message); this.status = status; }
+}
+export function title(value) {
+  if (typeof value !== 'string' || !value.trim() || value.trim().length > 120) {
+    throw new TaskError('Title must contain 1–120 characters.');
+  }
+  return value.trim();
+}
+export function validateBody(body, patch = false) {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) throw new TaskError('Expected a JSON object.');
+  const result = {};
+  if (Object.hasOwn(body, 'title')) result.title = title(body.title);
+  if (patch && Object.hasOwn(body, 'done')) {
+    if (typeof body.done !== 'boolean') throw new TaskError('Done must be a boolean.');
+    result.done = body.done;
+  }
+  if (!patch && !Object.hasOwn(result, 'title')) throw new TaskError('A title is required.');
+  if (patch && !Object.keys(result).length) throw new TaskError('Provide title or done.');
+  return result;
+}
+export function validateStoredTasks(tasks) {
+  if (!Array.isArray(tasks)) throw new Error('Invalid stored task list');
+  const ids = new Set();
+  for (const task of tasks) {
+    if (!task || typeof task.id !== 'string' || !task.id || ids.has(task.id) ||
+      typeof task.done !== 'boolean' || typeof task.title !== 'string' || !task.title || task.title.length > 120 || task.title.trim() !== task.title) throw new Error('Invalid stored task');
+    ids.add(task.id);
+  }
+  return tasks;
+}

package/examples/pocket-tasks/src/store.mjs

@@ -0,0 +1,49 @@
+import { readFile, mkdir, open, rename, unlink } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { TaskError, validateStoredTasks } from './domain.mjs';
+
+export function createStore(dataFile) {
+  let tail = Promise.resolve();
+  const enqueue = fn => {
+    const result = tail.then(fn);
+    tail = result.catch(() => {});
+    return result;
+  };
+  async function read() {
+    let raw;
+    try { raw = await readFile(dataFile, 'utf8'); }
+    catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+    return validateStoredTasks(JSON.parse(raw));
+  }
+  async function save(tasks) {
+    await mkdir(dirname(dataFile), { recursive: true });
+    const temporary = `${dataFile}.${randomUUID()}.tmp`;
+    try {
+      const handle = await open(temporary, 'wx', 0o600);
+      try { await handle.writeFile(`${JSON.stringify(tasks, null, 2)}\n`); await handle.sync(); }
+      finally { await handle.close(); }
+      await rename(temporary, dataFile);
+    } finally { await unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error; }); }
+  }
+  return {
+    list: () => enqueue(read),
+    create: input => enqueue(async () => {
+      const tasks = await read();
+      const task = { id: randomUUID(), title: input.title, done: false };
+      tasks.push(task); await save(tasks); return task;
+    }),
+    update: (id, input) => enqueue(async () => {
+      const tasks = await read();
+      const task = tasks.find(task => task.id === id);
+      if (!task) throw new TaskError('Task not found.', 404);
+      Object.assign(task, input); await save(tasks); return task;
+    }),
+    remove: id => enqueue(async () => {
+      const tasks = await read();
+      const index = tasks.findIndex(task => task.id === id);
+      if (index === -1) throw new TaskError('Task not found.', 404);
+      tasks.splice(index, 1); await save(tasks);
+    }),
+  };
+}

package/examples/pocket-tasks/tests/app.test.mjs

@@ -0,0 +1,132 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, writeFile, rm, readdir } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { once } from 'node:events';
+import { request as httpRequest } from 'node:http';
+import { createTaskServer } from '../server.mjs';
+import { validateBody } from '../src/domain.mjs';
+
+async function fixture(t) {
+  const dir = await mkdtemp(join(tmpdir(), 'pocket-tasks-'));
+  const file = join(dir, 'tasks.json');
+  const servers = [];
+  async function start() {
+    const server = createTaskServer({ dataFile: file }); servers.push(server);
+    server.listen(0, '127.0.0.1'); await once(server, 'listening');
+    const base = `http://127.0.0.1:${server.address().port}`;
+    return { server, call: (path = '/api/tasks', method = 'GET', payload) => fetch(`${base}${path}`, { method, headers: { 'Content-Type': 'application/json' }, ...(payload === undefined ? {} : { body: typeof payload === 'string' ? payload : JSON.stringify(payload) }) }) };
+  }
+  t.after(async () => { for (const server of servers) if (server.listening) await new Promise(resolve => server.close(resolve)); await rm(dir, { recursive: true, force: true }); });
+  return { dir, file, start, ...await start() };
+}
+
+test('domain normalizes titles and rejects invalid shapes/fields', () => {
+  assert.deepEqual(validateBody({ title: '  hello  ' }), { title: 'hello' });
+  assert.deepEqual(validateBody({ done: false }, true), { done: false });
+  for (const body of [null, [], {}, { title: '' }, { title: ' ' }, { title: 1 }, { title: 'x'.repeat(121) }]) assert.throws(() => validateBody(body));
+  for (const body of [null, [], {}, { extra: true }, { done: 'true' }, { title: ' ' }, { done: null }]) assert.throws(() => validateBody(body, true));
+  assert.equal(validateBody({ title: 'x'.repeat(120) }).title.length, 120);
+});
+
+test('HTTP CRUD and restart preserve titles, completion and deletion', async t => {
+  const f = await fixture(t);
+  assert.deepEqual(await (await f.call()).json(), { tasks: [] });
+  const created = await f.call('/api/tasks', 'POST', { title: '  <img src=x onerror=alert(1)>  ' });
+  assert.equal(created.status, 201); const { task } = await created.json();
+  assert.equal(task.title, '<img src=x onerror=alert(1)>'); assert.equal(task.done, false); assert.equal(typeof task.id, 'string');
+  const updated = await f.call(`/api/tasks/${task.id}`, 'PATCH', { title: ' Revised ', done: true });
+  assert.equal(updated.status, 200); assert.deepEqual((await updated.json()).task, { id: task.id, title: 'Revised', done: true });
+  await new Promise(resolve => f.server.close(resolve));
+  const restarted = await f.start();
+  assert.deepEqual((await (await restarted.call()).json()).tasks, [{ id: task.id, title: 'Revised', done: true }]);
+  assert.equal((await restarted.call(`/api/tasks/${task.id}`, 'PATCH', { done: false })).status, 200);
+  assert.equal((await restarted.call(`/api/tasks/${task.id}`, 'DELETE')).status, 204);
+  assert.deepEqual(JSON.parse(await readFile(f.file, 'utf8')), []);
+  assert.equal((await restarted.call(`/api/tasks/${task.id}`, 'DELETE')).status, 404);
+});
+
+test('bad HTTP input and oversized body never change persisted state', async t => {
+  const f = await fixture(t);
+  const { task } = await (await f.call('/api/tasks', 'POST', { title: 'Keep me' })).json();
+  const before = await readFile(f.file, 'utf8');
+  for (const payload of ['{', 'null', '[]', { title: false }, { title: '' }, { title: 'x'.repeat(121) }]) {
+    const response = await f.call('/api/tasks', 'POST', payload); assert.equal(response.status, 400); assert.equal(typeof (await response.json()).error, 'string');
+  }
+  for (const payload of [{}, { done: 1 }, { title: null }, { extra: 'value' }]) assert.equal((await f.call(`/api/tasks/${task.id}`, 'PATCH', payload)).status, 400);
+  const large = await f.call('/api/tasks', 'POST', { title: 'x'.repeat(17000) }); assert.equal(large.status, 413); assert.equal(typeof (await large.json()).error, 'string');
+  assert.equal((await f.call('/api/tasks/missing', 'PATCH', { done: true })).status, 404);
+  assert.equal(await readFile(f.file, 'utf8'), before);
+});
+
+test('concurrent mutations serialize without losing tasks or leaking temp files', async t => {
+  const f = await fixture(t);
+  const responses = await Promise.all(Array.from({ length: 20 }, (_, n) => f.call('/api/tasks', 'POST', { title: `Task ${n}` })));
+  assert.ok(responses.every(response => response.status === 201));
+  const tasks = (await (await f.call()).json()).tasks;
+  assert.equal(tasks.length, 20); assert.equal(new Set(tasks.map(task => task.id)).size, 20);
+  assert.deepEqual(await readdir(f.dir), ['tasks.json']);
+});
+
+test('malformed persisted data fails closed and recovers only after explicit repair', async t => {
+  const f = await fixture(t);
+  for (const malformed of ['{broken', '{}', '[{"id":"x","title":"","done":false}]', '[{"id":"x","title":"hello","done":"yes"}]', '[{"id":"x","title":"hello","done":false},{"id":"x","title":"again","done":true}]']) {
+    await writeFile(f.file, malformed);
+    assert.equal((await f.call()).status, 500);
+    assert.equal((await f.call('/api/tasks', 'POST', { title: 'New' })).status, 500);
+    assert.equal(await readFile(f.file, 'utf8'), malformed);
+  }
+  await writeFile(f.file, '[]');
+  assert.equal((await f.call('/api/tasks', 'POST', { title: 'Recovered' })).status, 201);
+});
+
+test('static allowlist serves UI and rejects private assets and unknown methods', async t => {
+  const f = await fixture(t);
+  const page = await f.call('/'); assert.equal(page.status, 200); assert.match(page.headers.get('content-type'), /text\/html/);
+  assert.match(page.headers.get('content-security-policy'), /script-src 'self'/);
+  assert.match(await page.text(), /aria-live="polite"/);
+  for (const path of ['/server.mjs', '/BRIEF.md', '/data/tasks.json', '/%2e%2e%2fserver.mjs', '/missing']) assert.equal((await f.call(path)).status, 404);
+  assert.equal((await f.call('/api/tasks', 'PUT', {})).status, 404);
+  const js = await (await f.call('/app.js')).text(); assert.ok(!js.includes('innerHTML'));
+});
+
+
+test('local HTTP boundary rejects cross-site writes, rebinding hosts and simple MIME without mutation', async t => {
+  const f = await fixture(t);
+  const { task } = await (await f.call('/api/tasks', 'POST', { title: 'Keep local' })).json();
+  const before = await readFile(f.file, 'utf8');
+  const port = f.server.address().port;
+  const send = (method, path, headers, payload = '{}') => new Promise((resolve, reject) => {
+    const request = httpRequest({ hostname: '127.0.0.1', port, method, path, headers: { ...headers, 'Content-Length': Buffer.byteLength(payload) } }, response => {
+      let text = ''; response.setEncoding('utf8'); response.on('data', chunk => { text += chunk; });
+      response.on('end', () => resolve({ status: response.statusCode, text }));
+    });
+    request.on('error', reject); request.end(payload);
+  });
+  const local = { Host: `127.0.0.1:${port}`, 'Content-Type': 'application/json' };
+  for (const headers of [
+    { ...local, Origin: 'https://attacker.example' },
+    { ...local, Origin: 'null' },
+    { ...local, Origin: `http://127.0.0.1:${port + 1}` },
+    { ...local, Origin: `http://127.0.0.1:${port}`, 'Sec-Fetch-Site': 'cross-site' },
+    { ...local, Host: `attacker.example:${port}` },
+    { ...local, Host: `127.0.0.1:${port + 1}` },
+    { ...local, Host: `localhost:${port}` },
+    { ...local, Host: `127.0.0.1:${port}.attacker.example` },
+  ]) {
+    for (const [method, path] of [['POST', '/api/tasks'], ['PATCH', `/api/tasks/${task.id}`], ['DELETE', `/api/tasks/${task.id}`]]) {
+      const response = await send(method, path, headers, JSON.stringify({ title: 'Injected' }));
+      assert.equal(response.status, 403); assert.equal(typeof JSON.parse(response.text).error, 'string');
+    }
+  }
+  for (const mime of ['text/plain', 'application/x-www-form-urlencoded', 'multipart/form-data', '']) {
+    for (const [method, path] of [['POST', '/api/tasks'], ['PATCH', `/api/tasks/${task.id}`]]) {
+      assert.equal((await send(method, path, { ...local, 'Content-Type': mime }, '{"title":"Injected"}')).status, 415);
+    }
+  }
+  assert.equal((await send('GET', '/api/tasks', { ...local, Host: `attacker.example:${port}` })).status, 403);
+  assert.equal(await readFile(f.file, 'utf8'), before);
+  assert.equal((await send('PATCH', `/api/tasks/${task.id}`, { ...local, Origin: `http://127.0.0.1:${port}`, 'Content-Type': 'application/json; charset=utf-8' }, '{"done":true}')).status, 200);
+  assert.equal((await send('PATCH', `/api/tasks/${task.id}`, local, '{"done":false}')).status, 200);
+});

package/examples/pocket-tasks/tests/ui-errors.test.mjs

@@ -0,0 +1,49 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+import vm from 'node:vm';
+
+async function ui(failure) {
+  const nodes = new Map();
+  const element = () => ({ textContent: '', value: '', hidden: false, disabled: false, dataset: {}, setAttribute() {}, addEventListener() {}, replaceChildren() {}, append() {}, focus() { this.focused = true; } });
+  for (const selector of ['#status', '#error', '#retry', '#tasks', '#empty', '#count', '#add-form', '#new-title']) nodes.set(selector, element());
+  nodes.get('#new-title').value = '   ';
+  let calls = 0;
+  const context = vm.createContext({
+    document: { querySelector: selector => nodes.get(selector) ?? null, querySelectorAll: selector => selector === 'button,input' ? [nodes.get('#new-title'), nodes.get('#retry')] : [], createElement: element },
+    fetch: async () => {
+      calls += 1;
+      if (calls === 1) return { status: 200, ok: true, json: async () => ({ tasks: [] }) };
+      if (failure === 'network') throw new Error('Network unavailable.');
+      return { status: failure, ok: false, json: async () => ({ error: 'Title must contain 1–120 characters.' }) };
+    },
+  });
+  vm.runInContext(await readFile(new URL('../public/app.js', import.meta.url), 'utf8'), context);
+  await new Promise(resolve => setImmediate(resolve));
+  return { nodes, context, calls: () => calls };
+}
+
+test('definitive validation rejection preserves input and permits immediate correction without reload', async () => {
+  const { nodes, context, calls } = await ui(400);
+  await vm.runInContext("mutate('', 'POST', { title: '   ' }, 'Task added.')", context);
+  assert.equal(nodes.get('#new-title').value, '   ');
+  assert.equal(nodes.get('#new-title').disabled, false);
+  assert.equal(nodes.get('#new-title').focused, true);
+  assert.equal(nodes.get('#retry').hidden, true);
+  assert.match(nodes.get('#error').textContent, /Title must contain/);
+  assert.doesNotMatch(nodes.get('#error').textContent, /Reload/);
+  assert.equal(nodes.get('#status').textContent, 'Change rejected. Correct the input and try again.');
+  nodes.get('#new-title').value = 'Corrected input';
+  await vm.runInContext("mutate('', 'POST', { title: 'Corrected input' }, 'Task added.')", context);
+  assert.equal(calls(), 3);
+});
+
+test('network and server failures retain reconciliation instruction', async () => {
+  for (const failure of ['network', 500]) {
+    const { nodes, context } = await ui(failure);
+    await vm.runInContext("mutate('', 'POST', { title: 'Task' }, 'Task added.')", context);
+    assert.equal(nodes.get('#retry').hidden, false);
+    assert.match(nodes.get('#error').textContent, /Reload to check saved state/);
+    assert.equal(nodes.get('#status').textContent, 'Change could not be confirmed.');
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devmethod-ai",
-  "version": "0.1.0-rc.2",
+  "version": "0.1.0",
   "description": "From idea to delivery with your AI coding agents",
   "license": "MIT",
   "type": "module",
@@ -13,8 +13,15 @@
   "files": [
     "dist/",
     ".agents/skills/",
+    "docs/",
+    "examples/",
+    "evaluation/",
+    "scripts/",
     "LICENSE",
-    "COMPATIBILITY.md"
+    "COMPATIBILITY.md",
+    "CONTRIBUTING.md",
+    "VALIDATION.md",
+    "START_HERE.md"
   ],
   "repository": {
     "type": "git",
@@ -22,7 +29,12 @@
   },
   "scripts": {
     "build": "tsc",
-    "test": "npm run build && node --test tests/*.test.mjs"
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "test:fixtures": "node --test tests/evaluation.test.mjs",
+    "check:docs": "node scripts/check-docs.mjs",
+    "test:cli": "node --test tests/install.test.mjs tests/doctor.test.mjs tests/update.test.mjs tests/checkpoint.test.mjs tests/resume-cli.test.mjs tests/mission.test.mjs tests/planner.test.mjs",
+    "test:protocols": "node --test tests/comparison.test.mjs",
+    "test:greenfield": "node --test examples/pocket-tasks/tests/*.test.mjs evaluation/greenfield/*.test.mjs"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/scripts/check-codex-git.mjs

@@ -0,0 +1,20 @@
+// Native sandbox preflight, no model invocation. Run explicitly on macOS.
+import fs from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { startCodexRpc } from './hosts/codex-rpc.mjs';
+export async function checkCodexGit() {
+  if(process.platform!=='darwin')throw new Error('macOS preflight only');
+  const cwd=fs.mkdtempSync('/private/tmp/devmethod-git-sandbox-');
+  execFileSync('git',['init',cwd]);fs.writeFileSync(cwd+'/sentinel.txt','fictional\n');
+  const rpc=startCodexRpc({cwd,timeoutMs:20000});const results=[];
+  try {
+    await rpc.call('initialize',{clientInfo:{name:'devmethod_probe',version:'0.1.0'},capabilities:{experimentalApi:true}});rpc.notify({method:'initialized'});
+    for(const includeGit of [false,true]) {
+      const result=await rpc.call('command/exec',{command:['git','add','sentinel.txt'],cwd,timeoutMs:5000,sandboxPolicy:{type:'workspaceWrite',writableRoots:includeGit?[cwd,cwd+'/.git']:[cwd],networkAccess:false,excludeTmpdirEnvVar:true,excludeSlashTmp:true}});
+      results.push({includeGit,exitCode:result.exitCode});
+    }
+    if(results[0].exitCode===0||results[1].exitCode!==0)throw new Error('Unexpected Git sandbox result');
+    return {gitMetadataWritable:true,results};
+  }finally{rpc.close();fs.rmSync(cwd,{recursive:true,force:true});}
+}
+if(process.argv[1]?.endsWith('/check-codex-git.mjs')) console.log(JSON.stringify(await checkCodexGit()));

package/scripts/check-docs.mjs

@@ -0,0 +1,14 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const skip = new Set(['.git', 'node_modules', '.next', 'dist', 'evaluation-private']);
+function files(root) { return fs.readdirSync(root, { withFileTypes: true }).flatMap(e => skip.has(e.name) || e.isSymbolicLink() ? [] : e.isDirectory() ? files(path.join(root, e.name)) : e.name.endsWith('.md') ? [path.join(root, e.name)] : []); }
+const failures = [];
+for (const file of files('.')) {
+  for (const [, target] of fs.readFileSync(file, 'utf8').matchAll(/\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g)) {
+    if (/^[a-z]+:|^#|^<|\$|\{/.test(target)) continue;
+    const relative = decodeURIComponent(target.split('#')[0]);
+    if (relative && !fs.existsSync(path.resolve(path.dirname(file), relative))) failures.push(`${file}: ${target}`);
+  }
+}
+if (failures.length) { console.error(failures.join('\n')); process.exitCode = 1; }
+else console.log('Local Markdown file links resolve (external URLs and anchors are not checked).');

package/scripts/check-native-sandbox.mjs

@@ -0,0 +1,11 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import assert from 'node:assert/strict';
+import { verifyFixture } from './hosts/checks.mjs';
+const root=fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()),'devmethod-sandbox-probe-'));
+const worker=path.join(root,'worker');fs.mkdirSync(worker);const sentinel=path.join(root,'sentinel');fs.writeFileSync(sentinel,'fictional sentinel');
+try {
+  const code=`const fs=require('node:fs'),net=require('node:net'),assert=require('node:assert/strict');assert.throws(()=>fs.readFileSync(${JSON.stringify(sentinel)}));assert.throws(()=>fs.writeFileSync('forbidden.txt','x'));const socket=net.connect({host:'127.0.0.1',port:9});socket.on('error',e=>{assert.equal(e.code,'EPERM');console.log('read/write/network denied');});`;
+  const result=verifyFixture(worker,['-e',code]); assert.equal(result.status,0,result.stdout+result.stderr);console.log(result.stdout.trim());
+}finally{fs.rmSync(root,{recursive:true,force:true});}

package/scripts/comparison-readiness.mjs

@@ -0,0 +1,26 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Admission requirements for an unattended BMAD/DevMethod comparison.
+ * Evidence is operator supplied; this check does not certify a host.
+ */
+export function comparisonReadiness(evidence) {
+  const required = [
+    'bmadInitializationPassed', 'taskLocalTemporaryDirectory',
+    'methodArtifactsAllowed', 'gitMetadataWritable',
+    'synchronousSubagentsAvailable', 'descendantUsageMeasured',
+    'descendantCancellationVerified', 'equalHostPermissions',
+    'frozenMethodRevisions', 'independentAcceptanceChecks',
+  ];
+  const missing = required.filter(key => evidence[key] !== true);
+  return { ready: missing.length === 0, missing,
+    limitation: 'Requires reviewed native evidence. A true label alone proves no capability.' };
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const file = process.argv[2];
+  if (!file) throw new Error('Usage: node scripts/comparison-readiness.mjs EVIDENCE_JSON');
+  const result = comparisonReadiness(JSON.parse(fs.readFileSync(file, 'utf8')));
+  console.log(JSON.stringify(result, null, 2));
+  if (!result.ready) process.exitCode = 2;
+}

package/scripts/comparison.mjs

@@ -0,0 +1,42 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const arms = ['none', 'devmethod', 'bmad'];
+const nonempty = value => typeof value === 'string' && value.trim().length > 0;
+const finite = value => typeof value === 'number' && Number.isFinite(value) && value >= 0;
+/** Validate a complete matched batch, including blocked/failed runs. Never dispatch models. */
+export function summarize(batch) {
+  if (!batch || batch.format !== 1 || !Array.isArray(batch.runs) || !batch.runs.length) throw new Error('Expected format 1 nonempty batch');
+  const { budget } = batch;
+  if (!budget || !Number.isSafeInteger(budget.runs) || budget.runs < 1 || !Number.isSafeInteger(budget.tokens) || budget.tokens < 1 || !finite(budget.costUSD) || !nonempty(budget.authorization)) throw new Error('Explicit run/token/cost budget and authorization required');
+  if (batch.runs.length > budget.runs) throw new Error('Run budget exceeded');
+  const groups = new Map();
+  const matchedKeys = ['fixtureDigest', 'promptDigest', 'hostVersion', 'model', 'toolsDigest', 'permissionsDigest', 'perRunTokens', 'perRunCostUSD', 'timeoutSeconds'];
+  const digests = ['fixtureDigest', 'promptDigest', 'toolsDigest', 'permissionsDigest'];
+  for (const run of batch.runs) {
+    if (!run || !nonempty(run.caseId) || !Number.isSafeInteger(run.repetition) || run.repetition < 1 || !arms.includes(run.arm) || !['passed', 'failed', 'blocked', 'timeout'].includes(run.status)) throw new Error('Invalid run identity or status');
+    if (!matchedKeys.every(key => ['perRunTokens', 'perRunCostUSD', 'timeoutSeconds'].includes(key) ? finite(run[key]) && (key === 'perRunCostUSD' || run[key] > 0) : nonempty(run[key])) || !digests.every(key => /^[a-f0-9]{64}$/.test(run[key]))) throw new Error('Missing pinned matched conditions');
+    if (!nonempty(run.methodRevision) || !nonempty(run.wrapper) || (run.arm === 'none' && run.methodRevision !== 'none')) throw new Error('Pin method revision and invocation wrapper');
+    if (!nonempty(run.evidence) || !nonempty(run.review)) throw new Error('Evidence reference and review or blocked reason required');
+    for (const metric of ['tokens', 'costUSD', 'elapsedSeconds']) if (run[metric] !== null && !finite(run[metric])) throw new Error('Usage must be measured nonnegative values or null (unavailable)');
+    if ((run.tokens !== null && run.tokens > run.perRunTokens) || (run.costUSD !== null && run.costUSD > run.perRunCostUSD)) throw new Error('Per-run budget exceeded');
+    const key = `${run.caseId}:${run.repetition}`;
+    const group = groups.get(key) ?? [];
+    if (group.some(other => other.arm === run.arm)) throw new Error('Duplicate arm');
+    if (group.length && matchedKeys.some(key => run[key] !== group[0][key])) throw new Error('Unmatched conditions');
+    group.push(run); groups.set(key, group);
+  }
+  for (const group of groups.values()) if (group.length !== 3) throw new Error('Each case/repetition requires all three arms, including blocked records');
+  for (const metric of ['tokens', 'costUSD']) if (batch.runs.reduce((sum, run) => sum + (run[metric] ?? 0), 0) > budget[metric]) throw new Error('Total budget exceeded');
+  const cells = [];
+  for (const caseId of new Set(batch.runs.map(run => run.caseId))) for (const arm of arms) {
+    const runs = batch.runs.filter(run => run.caseId === caseId && run.arm === arm);
+    cells.push({ caseId, arm, denominator: runs.length, ...Object.fromEntries(['passed', 'failed', 'blocked', 'timeout'].map(status => [status, runs.filter(run => run.status === status).length])) });
+  }
+  return { format: 1, cells, usageComplete: batch.runs.every(run => run.tokens !== null && run.costUSD !== null),
+    limitation: 'Validates record consistency only. Evidence authenticity and behavioral claims require independent inspection; no aggregate superiority score.' };
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try { if (process.argv.length !== 3) throw new Error('Usage: node scripts/comparison.mjs BATCH_JSON'); console.log(JSON.stringify(summarize(JSON.parse(fs.readFileSync(process.argv[2]))), null, 2)); }
+  catch (error) { console.error(error.message); process.exitCode = 2; }
+}