switchman-dev 0.1.0

package/examples/worktrees/agent-validation/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "taskapi",
+  "version": "1.0.0",
+  "description": "Example project for practising Switchman — a simple task management REST API",
+  "main": "src/server.js",
+  "scripts": {
+    "start": "node src/server.js",
+    "dev": "node --watch src/server.js",
+    "test": "jest --runInBand"
+  },
+  "dependencies": {
+    "express": "^4.18.2"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0",
+    "supertest": "^6.3.4"
+  }
+}

package/examples/worktrees/agent-validation/src/db.js

@@ -0,0 +1,179 @@
+// db.js — SQLite-backed store for taskapi.
+// Drop-in alternative to dbstore/store.js.
+// Requires: npm install better-sqlite3
+//
+// Usage: swap require('./dbstore/store') → require('./db') in routes/app.js
+
+const path = require('path');
+const Database = require('better-sqlite3');
+
+const DB_PATH = process.env.DB_PATH || path.join(__dirname, '..', 'taskapi.db');
+
+let _db;
+
+function getDb() {
+  if (!_db) {
+    _db = new Database(DB_PATH);
+    _db.pragma('journal_mode = WAL');
+    _db.pragma('busy_timeout = 5000');
+    _db.pragma('foreign_keys = ON');
+    migrate(_db);
+    seed(_db);
+  }
+  return _db;
+}
+
+function migrate(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS users (
+      id        INTEGER PRIMARY KEY AUTOINCREMENT,
+      name      TEXT    NOT NULL,
+      email     TEXT    NOT NULL UNIQUE,
+      role      TEXT    NOT NULL DEFAULT 'member',
+      createdAt TEXT    NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE IF NOT EXISTS projects (
+      id        INTEGER PRIMARY KEY AUTOINCREMENT,
+      name      TEXT    NOT NULL,
+      ownerId   INTEGER REFERENCES users(id),
+      createdAt TEXT    NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE IF NOT EXISTS tasks (
+      id         INTEGER PRIMARY KEY AUTOINCREMENT,
+      title      TEXT    NOT NULL,
+      status     TEXT    NOT NULL DEFAULT 'todo',
+      priority   TEXT    NOT NULL DEFAULT 'medium',
+      projectId  INTEGER NOT NULL REFERENCES projects(id),
+      assigneeId INTEGER REFERENCES users(id),
+      createdAt  TEXT    NOT NULL DEFAULT (datetime('now'))
+    );
+  `);
+}
+
+function seed(db) {
+  const count = db.prepare('SELECT COUNT(*) AS n FROM users').get().n;
+  if (count > 0) return; // already seeded
+
+  db.prepare(`INSERT INTO users (name, email, role) VALUES (?, ?, ?)`).run('Alice', 'alice@example.com', 'admin');
+  db.prepare(`INSERT INTO users (name, email, role) VALUES (?, ?, ?)`).run('Bob', 'bob@example.com', 'member');
+
+  db.prepare(`INSERT INTO projects (name, ownerId) VALUES (?, ?)`).run('Backend Rewrite', 1);
+  db.prepare(`INSERT INTO projects (name, ownerId) VALUES (?, ?)`).run('Mobile App', 2);
+
+  db.prepare(`INSERT INTO tasks (title, status, priority, projectId, assigneeId) VALUES (?, ?, ?, ?, ?)`).run('Set up CI pipeline', 'todo', 'high', 1, null);
+  db.prepare(`INSERT INTO tasks (title, status, priority, projectId, assigneeId) VALUES (?, ?, ?, ?, ?)`).run('Write API docs', 'in_progress', 'medium', 1, 2);
+  db.prepare(`INSERT INTO tasks (title, status, priority, projectId, assigneeId) VALUES (?, ?, ?, ?, ?)`).run('Fix login bug', 'todo', 'high', 2, null);
+}
+
+// ── Public API (same shape as dbstore/store.js) ──────────────────────────────
+
+const db = {
+  tasks: {
+    findAll() {
+      return getDb().prepare('SELECT * FROM tasks ORDER BY createdAt DESC').all();
+    },
+    findById(id) {
+      return getDb().prepare('SELECT * FROM tasks WHERE id = ?').get(id) || null;
+    },
+    findByProject(projectId) {
+      return getDb().prepare('SELECT * FROM tasks WHERE projectId = ?').all(projectId);
+    },
+    create(data) {
+      const { title, projectId, priority = 'medium', status = 'todo', assigneeId = null } = data;
+      const result = getDb()
+        .prepare('INSERT INTO tasks (title, projectId, priority, status, assigneeId) VALUES (?, ?, ?, ?, ?)')
+        .run(title, projectId, priority, status, assigneeId);
+      return this.findById(result.lastInsertRowid);
+    },
+    update(id, data) {
+      const allowed = ['title', 'status', 'priority', 'assigneeId'];
+      const fields = Object.keys(data).filter(k => allowed.includes(k));
+      if (fields.length === 0) return this.findById(id);
+      const set = fields.map(f => `${f} = ?`).join(', ');
+      const values = fields.map(f => data[f]);
+      getDb().prepare(`UPDATE tasks SET ${set} WHERE id = ?`).run(...values, id);
+      return this.findById(id);
+    },
+    delete(id) {
+      const result = getDb().prepare('DELETE FROM tasks WHERE id = ?').run(id);
+      return result.changes > 0;
+    },
+  },
+
+  projects: {
+    findAll() {
+      return getDb().prepare('SELECT * FROM projects ORDER BY createdAt DESC').all();
+    },
+    findById(id) {
+      return getDb().prepare('SELECT * FROM projects WHERE id = ?').get(id) || null;
+    },
+    create(data) {
+      const { name, ownerId = null } = data;
+      const result = getDb()
+        .prepare('INSERT INTO projects (name, ownerId) VALUES (?, ?)')
+        .run(name, ownerId);
+      return this.findById(result.lastInsertRowid);
+    },
+    update(id, data) {
+      const allowed = ['name', 'ownerId'];
+      const fields = Object.keys(data).filter(k => allowed.includes(k));
+      if (fields.length === 0) return this.findById(id);
+      const set = fields.map(f => `${f} = ?`).join(', ');
+      const values = fields.map(f => data[f]);
+      getDb().prepare(`UPDATE projects SET ${set} WHERE id = ?`).run(...values, id);
+      return this.findById(id);
+    },
+    delete(id) {
+      const result = getDb().prepare('DELETE FROM projects WHERE id = ?').run(id);
+      return result.changes > 0;
+    },
+  },
+
+  users: {
+    findAll() {
+      return getDb().prepare('SELECT * FROM users ORDER BY id').all();
+    },
+    findById(id) {
+      return getDb().prepare('SELECT * FROM users WHERE id = ?').get(id) || null;
+    },
+    findByEmail(email) {
+      return getDb().prepare('SELECT * FROM users WHERE email = ?').get(email) || null;
+    },
+    create(data) {
+      const { name, email, role = 'member' } = data;
+      const result = getDb()
+        .prepare('INSERT INTO users (name, email, role) VALUES (?, ?, ?)')
+        .run(name, email, role);
+      return this.findById(result.lastInsertRowid);
+    },
+    update(id, data) {
+      const allowed = ['name', 'email', 'role'];
+      const fields = Object.keys(data).filter(k => allowed.includes(k));
+      if (fields.length === 0) return this.findById(id);
+      const set = fields.map(f => `${f} = ?`).join(', ');
+      const values = fields.map(f => data[f]);
+      getDb().prepare(`UPDATE users SET ${set} WHERE id = ?`).run(...values, id);
+      return this.findById(id);
+    },
+  },
+
+  // For tests: wipe and re-seed
+  _reset() {
+    const d = getDb();
+    d.exec('DELETE FROM tasks; DELETE FROM projects; DELETE FROM users;');
+    // Reset autoincrement counters
+    d.exec(`
+      DELETE FROM sqlite_sequence WHERE name IN ('tasks','projects','users');
+    `);
+    seed(d);
+  },
+
+  // Close the connection (useful in tests)
+  close() {
+    if (_db) { _db.close(); _db = null; }
+  },
+};
+
+module.exports = db;

package/examples/worktrees/agent-validation/src/middleware/auth.js

@@ -0,0 +1,96 @@
+// middleware/auth.js — API key authentication middleware.
+//
+// Every protected route requires an `x-api-key` header.
+// Keys are looked up against the users table; the resolved user
+// is attached to req.user for downstream handlers.
+//
+// Usage:
+//   const { requireAuth, requireRole } = require('./middleware/auth');
+//   router.post('/admin-only', requireAuth, requireRole('admin'), handler);
+
+const db = require('../dbstore/store');
+
+// Static API key → user mapping (matches session summary keys).
+// In production, store hashed keys in the DB and look them up there.
+const API_KEYS = {
+  'dev-key-alice-123': { email: 'alice@example.com' },
+  'dev-key-bob-456':   { email: 'bob@example.com' },
+  'test-key-789':      { email: 'bob@example.com' }, // test user maps to Bob
+};
+
+/**
+ * requireAuth
+ * Reads the `x-api-key` header, resolves the key to a user record,
+ * and attaches it to req.user. Returns 401 if the key is missing or
+ * unknown, 403 if the user record can no longer be found in the store.
+ */
+function requireAuth(req, res, next) {
+  const key = req.headers['x-api-key'];
+
+  if (!key) {
+    return res.status(401).json({
+      error: 'Missing API key. Provide an x-api-key header.',
+    });
+  }
+
+  const mapping = API_KEYS[key];
+  if (!mapping) {
+    return res.status(401).json({ error: 'Invalid API key.' });
+  }
+
+  const user = db.users.findByEmail(mapping.email);
+  if (!user) {
+    return res.status(403).json({ error: 'API key refers to a deleted user.' });
+  }
+
+  req.user = user;
+  next();
+}
+
+/**
+ * requireRole(role)
+ * Factory that returns a middleware enforcing a minimum role.
+ * Roles (weakest → strongest): member → admin
+ * Must be used AFTER requireAuth.
+ *
+ * @param {'member'|'admin'} role
+ */
+const ROLE_RANK = { member: 1, admin: 2 };
+
+function requireRole(role) {
+  return function roleGuard(req, res, next) {
+    if (!req.user) {
+      // Programmer error: requireRole used without requireAuth
+      return res.status(500).json({ error: 'Auth middleware misconfigured.' });
+    }
+
+    const userRank = ROLE_RANK[req.user.role] ?? 0;
+    const required = ROLE_RANK[role] ?? 99;
+
+    if (userRank < required) {
+      return res.status(403).json({
+        error: `Requires '${role}' role. Your role: '${req.user.role}'.`,
+      });
+    }
+
+    next();
+  };
+}
+
+/**
+ * optionalAuth
+ * Like requireAuth but doesn't block unauthenticated requests.
+ * Attaches req.user if a valid key is provided, otherwise leaves it null.
+ */
+function optionalAuth(req, res, next) {
+  const key = req.headers['x-api-key'];
+  if (!key) { req.user = null; return next(); }
+
+  const mapping = API_KEYS[key];
+  if (!mapping) { req.user = null; return next(); }
+
+  req.user = db.users.findByEmail(mapping.email) || null;
+  next();
+}
+
+module.exports = { requireAuth, requireRole, optionalAuth };

package/examples/worktrees/agent-validation/src/middleware/validate.js

@@ -0,0 +1,133 @@
+// middleware/validate.js — lightweight request validation helpers.
+//
+// Provides schema-based body validation without a heavy dependency.
+// Works alongside auth.js as the other primary shared middleware —
+// making both files natural conflict hotspots for parallel agents.
+//
+// Usage:
+//   const { validate, schemas } = require('./middleware/validate');
+//   router.post('/', validate(schemas.createTask), handler);
+
+/**
+ * validate(schema)
+ * Returns an Express middleware that checks req.body against `schema`.
+ * A schema is a plain object whose values are validator functions:
+ *   { field: (value, body) => errorString | null }
+ *
+ * All errors are collected and returned together as a 400 response.
+ */
+function validate(schema) {
+  return function validationMiddleware(req, res, next) {
+    const errors = [];
+
+    for (const [field, validator] of Object.entries(schema)) {
+      const value = req.body?.[field];
+      const error = validator(value, req.body);
+      if (error) errors.push({ field, message: error });
+    }
+
+    if (errors.length > 0) {
+      return res.status(400).json({ errors });
+    }
+
+    next();
+  };
+}
+
+// ── Reusable validator primitives ────────────────────────────────────────────
+
+const required = (field) => (value) =>
+  value === undefined || value === null || value === ''
+    ? `${field} is required`
+    : null;
+
+const isString = (field) => (value) =>
+  value !== undefined && typeof value !== 'string'
+    ? `${field} must be a string`
+    : null;
+
+const isNumber = (field) => (value) =>
+  value !== undefined && (typeof value !== 'number' || !Number.isFinite(value))
+    ? `${field} must be a number`
+    : null;
+
+const isEmail = (field) => (value) => {
+  if (!value) return null; // let `required` handle missing values
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)
+    ? null
+    : `${field} must be a valid email address`;
+};
+
+const oneOf = (field, options) => (value) =>
+  value !== undefined && !options.includes(value)
+    ? `${field} must be one of: ${options.join(', ')}`
+    : null;
+
+const maxLength = (field, max) => (value) =>
+  value && typeof value === 'string' && value.length > max
+    ? `${field} must be ${max} characters or fewer`
+    : null;
+
+const minLength = (field, min) => (value) =>
+  value && typeof value === 'string' && value.length < min
+    ? `${field} must be at least ${min} characters`
+    : null;
+
+/** Compose multiple validators for one field (returns first error). */
+const compose = (...validators) =>
+  (value, body) => {
+    for (const v of validators) {
+      const err = v(value, body);
+      if (err) return err;
+    }
+    return null;
+  };
+
+// ── Pre-built schemas ────────────────────────────────────────────────────────
+
+const VALID_STATUSES  = ['todo', 'in_progress', 'done', 'cancelled'];
+const VALID_PRIORITIES = ['low', 'medium', 'high'];
+const VALID_ROLES      = ['member', 'admin'];
+
+const schemas = {
+  createTask: {
+    title:     compose(required('title'), isString('title'), maxLength('title', 200)),
+    projectId: compose(required('projectId'), isNumber('projectId')),
+    priority:  oneOf('priority', VALID_PRIORITIES),
+    status:    oneOf('status', VALID_STATUSES),
+  },
+
+  updateTask: {
+    title:    compose(isString('title'), maxLength('title', 200)),
+    status:   oneOf('status', VALID_STATUSES),
+    priority: oneOf('priority', VALID_PRIORITIES),
+  },
+
+  createProject: {
+    name:    compose(required('name'), isString('name'), maxLength('name', 100)),
+    ownerId: isNumber('ownerId'),
+  },
+
+  updateProject: {
+    name: compose(isString('name'), maxLength('name', 100)),
+  },
+
+  createUser: {
+    name:  compose(required('name'), isString('name'), maxLength('name', 100)),
+    email: compose(required('email'), isEmail('email'), maxLength('email', 255)),
+    role:  oneOf('role', VALID_ROLES),
+  },
+
+  updateUser: {
+    name:  compose(isString('name'), maxLength('name', 100)),
+    email: compose(isEmail('email'), maxLength('email', 255)),
+    role:  oneOf('role', VALID_ROLES),
+  },
+};
+
+module.exports = {
+  validate,
+  schemas,
+  // Export primitives so routes can build ad-hoc schemas
+  validators: { required, isString, isNumber, isEmail, oneOf, maxLength, minLength, compose },
+};

package/examples/worktrees/agent-validation/src/routes/tasks.js

@@ -0,0 +1,65 @@
+const express = require('express');
+const db = require('../dbstore/store');
+
+const router = express.Router();
+
+// GET /api/tasks — list all tasks (optionally filter by projectId or status)
+router.get('/', (req, res) => {
+  let tasks = db.tasks.findAll();
+  if (req.query.projectId) {
+    tasks = tasks.filter(t => t.projectId === Number(req.query.projectId));
+  }
+  if (req.query.status) {
+    tasks = tasks.filter(t => t.status === req.query.status);
+  }
+  res.json(tasks);
+});
+
+// GET /api/tasks/:id
+router.get('/:id', (req, res) => {
+  const task = db.tasks.findById(Number(req.params.id));
+  if (!task) return res.status(404).json({ error: 'Task not found' });
+  res.json(task);
+});
+
+// POST /api/tasks
+router.post('/', (req, res) => {
+  const { title, projectId, priority = 'medium', assigneeId } = req.body;
+  if (!title) return res.status(400).json({ error: 'title is required' });
+  if (!projectId) return res.status(400).json({ error: 'projectId is required' });
+
+  const project = db.projects.findById(Number(projectId));
+  if (!project) return res.status(400).json({ error: 'Project not found' });
+
+  const task = db.tasks.create({
+    title,
+    projectId: Number(projectId),
+    priority,
+    status: 'todo',
+    assigneeId: assigneeId ? Number(assigneeId) : null,
+  });
+  res.status(201).json(task);
+});
+
+// PATCH /api/tasks/:id
+router.patch('/:id', (req, res) => {
+  const task = db.tasks.findById(Number(req.params.id));
+  if (!task) return res.status(404).json({ error: 'Task not found' });
+
+  const VALID_STATUSES = ['todo', 'in_progress', 'done', 'cancelled'];
+  if (req.body.status && !VALID_STATUSES.includes(req.body.status)) {
+    return res.status(400).json({ error: `status must be one of: ${VALID_STATUSES.join(', ')}` });
+  }
+
+  const updated = db.tasks.update(Number(req.params.id), req.body);
+  res.json(updated);
+});
+
+// DELETE /api/tasks/:id
+router.delete('/:id', (req, res) => {
+  const deleted = db.tasks.delete(Number(req.params.id));
+  if (!deleted) return res.status(404).json({ error: 'Task not found' });
+  res.status(204).send();
+});
+
+module.exports = router;

package/examples/worktrees/agent-validation/src/routes/users.js

@@ -0,0 +1,38 @@
+const express = require('express');
+const db = require('../dbstore/store');
+
+const router = express.Router();
+
+// GET /api/users
+router.get('/', (req, res) => {
+  res.json(db.users.findAll());
+});
+
+// GET /api/users/:id
+router.get('/:id', (req, res) => {
+  const user = db.users.findById(Number(req.params.id));
+  if (!user) return res.status(404).json({ error: 'User not found' });
+  res.json(user);
+});
+
+// POST /api/users
+router.post('/', (req, res) => {
+  const { name, email, role = 'member' } = req.body;
+  if (!name) return res.status(400).json({ error: 'name is required' });
+  if (!email) return res.status(400).json({ error: 'email is required' });
+
+  const existing = db.users.findByEmail(email);
+  if (existing) return res.status(409).json({ error: 'Email already in use' });
+
+  const user = db.users.create({ name, email, role });
+  res.status(201).json(user);
+});
+
+// PATCH /api/users/:id
+router.patch('/:id', (req, res) => {
+  const user = db.users.findById(Number(req.params.id));
+  if (!user) return res.status(404).json({ error: 'User not found' });
+  res.json(db.users.update(Number(req.params.id), req.body));
+});
+
+module.exports = router;

package/examples/worktrees/agent-validation/src/server.js

@@ -0,0 +1,7 @@
+const app = require('./app');
+
+const PORT = process.env.PORT || 3000;
+
+app.listen(PORT, () => {
+  console.log(`TaskAPI running on port ${PORT}`);
+});

package/examples/worktrees/agent-validation/tests/api.test.js

@@ -0,0 +1,112 @@
+const request = require('supertest');
+const app = require('../src/app');
+const db = require('../src/dbstore/store');
+
+beforeEach(() => db._reset());
+
+describe('Tasks', () => {
+  test('GET /api/tasks returns all tasks', async () => {
+    const res = await request(app).get('/api/tasks');
+    expect(res.status).toBe(200);
+    expect(Array.isArray(res.body)).toBe(true);
+    expect(res.body.length).toBeGreaterThan(0);
+  });
+
+  test('GET /api/tasks?status=todo filters correctly', async () => {
+    const res = await request(app).get('/api/tasks?status=todo');
+    expect(res.status).toBe(200);
+    expect(res.body.every(t => t.status === 'todo')).toBe(true);
+  });
+
+  test('GET /api/tasks/:id returns single task', async () => {
+    const res = await request(app).get('/api/tasks/1');
+    expect(res.status).toBe(200);
+    expect(res.body.id).toBe(1);
+  });
+
+  test('GET /api/tasks/:id returns 404 for unknown id', async () => {
+    const res = await request(app).get('/api/tasks/999');
+    expect(res.status).toBe(404);
+  });
+
+  test('POST /api/tasks creates a task', async () => {
+    const res = await request(app)
+      .post('/api/tasks')
+      .send({ title: 'New task', projectId: 1 });
+    expect(res.status).toBe(201);
+    expect(res.body.title).toBe('New task');
+    expect(res.body.status).toBe('todo');
+  });
+
+  test('POST /api/tasks returns 400 without title', async () => {
+    const res = await request(app).post('/api/tasks').send({ projectId: 1 });
+    expect(res.status).toBe(400);
+  });
+
+  test('PATCH /api/tasks/:id updates status', async () => {
+    const res = await request(app)
+      .patch('/api/tasks/1')
+      .send({ status: 'in_progress' });
+    expect(res.status).toBe(200);
+    expect(res.body.status).toBe('in_progress');
+  });
+
+  test('PATCH /api/tasks/:id rejects invalid status', async () => {
+    const res = await request(app)
+      .patch('/api/tasks/1')
+      .send({ status: 'flying' });
+    expect(res.status).toBe(400);
+  });
+
+  test('DELETE /api/tasks/:id deletes task', async () => {
+    const res = await request(app).delete('/api/tasks/1');
+    expect(res.status).toBe(204);
+    const get = await request(app).get('/api/tasks/1');
+    expect(get.status).toBe(404);
+  });
+});
+
+describe('Projects', () => {
+  test('GET /api/projects returns all projects', async () => {
+    const res = await request(app).get('/api/projects');
+    expect(res.status).toBe(200);
+    expect(Array.isArray(res.body)).toBe(true);
+  });
+
+  test('GET /api/projects/:id/tasks returns tasks for project', async () => {
+    const res = await request(app).get('/api/projects/1/tasks');
+    expect(res.status).toBe(200);
+    expect(res.body.every(t => t.projectId === 1)).toBe(true);
+  });
+
+  test('POST /api/projects creates project', async () => {
+    const res = await request(app)
+      .post('/api/projects')
+      .send({ name: 'New Project', ownerId: 1 });
+    expect(res.status).toBe(201);
+    expect(res.body.name).toBe('New Project');
+  });
+});
+
+describe('Users', () => {
+  test('GET /api/users returns all users', async () => {
+    const res = await request(app).get('/api/users');
+    expect(res.status).toBe(200);
+    expect(res.body.length).toBeGreaterThan(0);
+  });
+
+  test('POST /api/users creates user', async () => {
+    const res = await request(app)
+      .post('/api/users')
+      .send({ name: 'Charlie', email: 'charlie@example.com' });
+    expect(res.status).toBe(201);
+    expect(res.body.name).toBe('Charlie');
+  });
+
+  test('POST /api/users rejects duplicate email', async () => {
+    const res = await request(app)
+      .post('/api/users')
+      .send({ name: 'Dup', email: 'alice@example.com' });
+    expect(res.status).toBe(409);
+  });
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "switchman-dev",
+  "version": "0.1.0",
+  "description": "Route your AI agents so they don't collide",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "switchman": "./src/cli/index.js",
+    "switchman-mcp": "./src/mcp/server.js"
+  },
+   "repository": {
+    "type": "git",
+    "url": "https://github.com/switchman-dev/switchman"
+  },
+  "scripts": {
+    "start": "node src/cli/index.js",
+    "mcp": "node src/mcp/server.js",
+    "test": "node tests/test.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "node-sqlite3-wasm": "^0.8.35",
+    "ora": "^8.0.1",
+    "zod": "^4.3.6"
+  },
+  "license": "Apache-2.0"
+}