@werewolf-solutions/dev 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
+# @werewolf-solutions/dev
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Connect your machine, or your own AI harness, to [Werewolf Solutions](https://werewolf.solutions)
+as a developer. You build website drafts for the businesses assigned to you. Drafts are
+held for your review; only your **Accept** on the developer page sends one to the owner.
+
+Needs Node 20 or newer. Nothing else to install: `npx` fetches it.
+
+## Connect your machine (runner token)
+
+One command connects your machine. Leave it running.
+
+1. On the developer page, under **Website runner**, press **Create runner token**. It is shown
+   once. It only works for your website runs: it can check in, take your runs and upload drafts
+   held for your review, nothing else.
+2. Run:
+
+   ```sh
+   WEREWOLF_DEV_TOKEN=ws_sk_… npx @werewolf-solutions/dev runner --api https://staging.werewolf.solutions
+   ```
+
+   For production use `--api https://werewolf.solutions`.
+3. The developer page shows the machine as connected straight away, with what it offers: the
+   `claude` CLI, the `codex` CLI (once you've signed in) and Ollama (when `ollama serve` is
+   running), whichever it has.
+4. On a request, pick one with a model and effort, read the prompt and press **Start**. The
+   runner builds it with exactly that and uploads the draft held for your review. Only your
+   **Accept** sends it to the owner.
+
+Ctrl+C stops it. A run in progress goes back to the queue, and the developer page shows the
+machine as gone at once. You can connect more than one machine; each takes only runs for what
+it offers.
+
+| | |
+|---|---|
+| `--api <site>` | The site, with or without `/api/v1`. Or set `WEREWOLF_API_URL`. https only, except localhost. |
+| `--exec "<command>"` | Offer any other CLI agent: it gets the prompt on stdin, the workspace as its working directory and screenshot paths in `WEREWOLF_IMAGES`, and prints `{"files": [...]}` on stdout. It shows as **Your command (name)**. |
+| `--host <name>` | The name this machine shows on the developer page. Default: its hostname. |
+| `AI_BUILDER_CLI_TIMEOUT_MS` | How long one model call may take. Default 600000 (10 minutes). |
+| `OLLAMA_HOST`, `CODEX_HOME` | Where Ollama and Codex live, if not the defaults. |
+
+The rules for a site that works online (the brief, the checklist, the output format, the
+contact widget) come from the server with each run, so every agent builds to the same rules.
+
+### Optional: let your harness build, over MCP
+
+The same token also works as an MCP server inside Claude Code, Codex, Cursor or any MCP
+client. That connection offers the harness itself as well as the CLIs. Pick the harness on a
+request, then ask it to "take the next website job".
+
+```sh
+claude mcp add werewolf-dev --env WEREWOLF_DEV_TOKEN=ws_sk_… \
+  -- npx -y @werewolf-solutions/dev mcp --api https://staging.werewolf.solutions
+```
+
+Other clients take `command: "npx"`, `args: ["-y", "@werewolf-solutions/dev", "mcp", "--api",
+"<site>"]` and `env: { WEREWOLF_DEV_TOKEN: "ws_sk_…" }`. It lives only while the harness is
+open.
+
+| Tool | What it does |
+|---|---|
+| `list_website_requests` | Your open requests, with business, kind and run state. Read-only |
+| `next_website_job` | Takes the next run you started for the harness: brief, checklist, screenshots |
+| `submit_website_draft` | Uploads the files for a job, held for your review; returns the preview link |
+| `report_website_failure` | Gives a job back with the reason; it is queued once more, then marked failed |
+
+## MCP server (business key)
+
+Connects Claude Code (or any MCP client) to one business's site builder. Claude generates
+website files itself and saves/publishes them through the platform: the business data
+stays the single source of truth, and publishing mints a domain-locked publishable key
+automatically.
+
+### Setup
+
+You need a **secret API key** (`ws_sk_...`) for the business: dashboard →
+Generate API Key → type "Secret", tied to the business.
+
+Register with Claude Code:
+
+```sh
+claude mcp add werewolf \
+  --env WEREWOLF_API_URL=http://localhost:3000/api/v1 \
+  --env WEREWOLF_API_KEY=ws_sk_... \
+  -- npx -y @werewolf-solutions/dev mcp
+```
+
+For production use `WEREWOLF_API_URL=https://werewolf.solutions/api/v1`.
+
+For a status-only PSM integration, set `WEREWOLF_MCP_PROFILE=psm-readonly`.
+That profile registers only `get_psm_service_status`; site-builder read/write tools
+are not advertised to the MCP client.
+
+### Tools
+
+| Tool | What it does |
+|---|---|
+| `get_business` | Business profile/services/branding — the content source |
+| `get_psm_service_status` | Read-only PSM cloud billing/storage readiness and aggregate usage |
+| `list_projects` / `get_project` | Browse builder projects + current files |
+| `create_project` | New website project; optional `sourceUrl` imports an existing site's content |
+| `save_revision` | Save files Claude generated as the new draft revision |
+| `generate_revision` | Ask the platform to generate server-side instead |
+| `publish_project` | Go live; pass `domains` for tenant hosts |
+
+### Example session in Claude Code
+
+> "Get my business info, then create a website project importing
+> https://old-site.example.com, generate a modern single-page site from the
+> imported content and business data, save it as a revision, and publish it
+> with domains [mybusiness.werewolf.solutions]."
+
+### Notes
+
+- Generated files must keep the `__WEREWOLF_PUBLISHABLE_KEY__` and
+  `__WEREWOLF_PLATFORM_URL__` placeholders in the widget snippet verbatim —
+  publishing substitutes the real values so keys never enter prompts.
+- The secret key is scoped: it can only drive the builder for its own business.
+
+## Development
+
+This package lives in `mcp/` in the Werewolf Solutions app repository. The server's tests
+run the runner against a real server, and `npm test` here runs the package's own tests.
+Releases: bump `version` in `package.json`, then push a tag `dev-v<version>`.

package/bin/werewolf-dev.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * werewolf-dev: connect your machine or your own AI harness to Werewolf Solutions as a
+ * developer.
+ *
+ *   werewolf-dev runner --api <site>   build website drafts here with claude, codex, ollama or --exec
+ *   werewolf-dev mcp --api <site>      MCP server for Claude Code, Codex, Cursor and other harnesses
+ */
+const path = require('path');
+const { pathToFileURL } = require('url');
+const { version } = require('../package.json');
+
+const USAGE = `werewolf-dev ${version}
+
+  werewolf-dev runner --api <site> [--exec "<command>"]   build website drafts on this machine
+  werewolf-dev mcp [--api <site>]                          MCP server for your own harness
+  werewolf-dev --version
+
+Both sign in with WEREWOLF_DEV_TOKEN, your runner token from the developer page.
+Run "werewolf-dev runner --help" for the runner options.`;
+
+async function main(argv) {
+  const [command, ...rest] = argv;
+  if (command === '--version' || command === '-v') { console.log(version); return 0; }
+  if (command === 'runner') return require('../src/cli').runnerMain(rest);
+  if (command === 'mcp') {
+    const api = require('../src/cli').argValue(rest, '--api');
+    if (api) process.env.WEREWOLF_API_URL = api;
+    await import(pathToFileURL(path.join(__dirname, '..', 'werewolf-mcp.mjs')).href);
+    return null; // the MCP server keeps running on stdio
+  }
+  console.log(USAGE);
+  return command && command !== '--help' && command !== '-h' ? 1 : 0;
+}
+
+main(process.argv.slice(2)).then((code) => { if (code !== null) process.exitCode = code; }, (error) => { console.error(error); process.exitCode = 1; });

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@werewolf-solutions/dev",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Connect your machine or your own AI harness (Claude Code, Codex, Cursor, any MCP client) to Werewolf Solutions as a developer: build website drafts for the businesses assigned to you.",
+  "license": "UNLICENSED",
+  "homepage": "https://werewolf.solutions",
+  "keywords": ["werewolf-solutions", "website", "mcp", "claude", "codex", "agent"],
+  "main": "src/runner.js",
+  "bin": {
+    "werewolf-dev": "bin/werewolf-dev.js",
+    "werewolf-mcp": "werewolf-mcp.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "werewolf-mcp.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  }
+}

package/src/agents.js

@@ -0,0 +1,228 @@
+/**
+ * The coding agents the runner can drive: the `claude` CLI, the `codex` CLI, a local Ollama
+ * server, and any other CLI through --exec. Each run is one locked-down turn: the prompt goes
+ * in, text comes out. No dependencies beyond Node.
+ */
+const fs = require('fs/promises');
+const os = require('os');
+const path = require('path');
+const { execFile, spawn } = require('child_process');
+const { promisify } = require('util');
+
+const execFileAsync = promisify(execFile);
+const TIMEOUT_MS = () => parseInt(process.env.AI_BUILDER_CLI_TIMEOUT_MS || '600000', 10);
+const MAX_OUTPUT = 32 * 1024 * 1024;
+const codexHome = (env) => env.CODEX_HOME || path.join(os.homedir(), '.codex');
+const ollamaHost = (env) => (env.OLLAMA_HOST ? (/^https?:\/\//.test(env.OLLAMA_HOST) ? env.OLLAMA_HOST : `http://${env.OLLAMA_HOST}`) : 'http://127.0.0.1:11434').replace(/\/$/, '');
+
+const CLAUDE_EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max'];
+const CLAUDE_MODELS = [
+  { id: 'opus', label: 'Opus (newest)' },
+  { id: 'sonnet', label: 'Sonnet (newest)' },
+  { id: 'fable', label: 'Fable (newest)' },
+  { id: 'haiku', label: 'Haiku (newest)' },
+  { id: 'claude-opus-5-5', label: 'claude-opus-5-5' },
+  { id: 'claude-sonnet-5-5', label: 'claude-sonnet-5-5' },
+  { id: 'claude-fable-5-1', label: 'claude-fable-5-1' },
+  { id: 'claude-haiku-5-5', label: 'claude-haiku-5-5' },
+].map((model) => ({ ...model, efforts: CLAUDE_EFFORTS }));
+const OLLAMA_EFFORTS = ['low', 'medium', 'high'];
+
+const installed = async (command) => {
+  try { await execFileAsync(command, ['--version'], { timeout: 10000 }); return true; } catch { return false; }
+};
+
+// Runs a command with `input` on stdin; resolves with stdout. Kills it after the timeout.
+function pipe(command, args, { cwd, input, env, shell = false, timeoutMs = TIMEOUT_MS() }) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, env, shell, stdio: ['pipe', 'pipe', 'pipe'] });
+    let stdout = '';
+    let errors = '';
+    let timedOut = false;
+    const timer = setTimeout(() => { timedOut = true; child.kill('SIGTERM'); }, timeoutMs);
+    child.stdout.on('data', (chunk) => { stdout += chunk; if (stdout.length > MAX_OUTPUT) child.kill('SIGTERM'); });
+    child.stderr.on('data', (chunk) => { errors = `${errors}${chunk}`.slice(-2000); });
+    child.on('error', (error) => { clearTimeout(timer); reject(error); });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      if (timedOut) return reject(new Error(`${shell ? command : path.basename(command)} timed out after ${Math.round(timeoutMs / 1000)}s`));
+      if (code === 0) return resolve(stdout);
+      return reject(new Error(`${shell ? command.split(/\s+/)[0] : path.basename(command)} exited with ${code}: ${errors.trim().split('\n').slice(-3).join(' ')}`));
+    });
+    child.stdin.on('error', () => {});
+    child.stdin.end(input || '');
+  });
+}
+
+// ── Claude CLI ─────────────────────────────────────────────────────────────────────────
+// No tools, no MCP, no local instructions. Prompts with screenshots go over stdin as a
+// stream-json user message, which is the CLI's only way to accept images.
+function claudeArgs({ prompt, model, effort, streamed }) {
+  const args = streamed
+    ? ['--restricted', '--safe-mode', '--strict-mcp-config', '--tools', '', '-p', '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose', '--max-turns', '1']
+    : ['--restricted', '--safe-mode', '--strict-mcp-config', '--tools', '', '-p', prompt, '--output-format', 'json', '--max-turns', '1'];
+  if (model) args.push('--model', model);
+  if (effort) args.push('--effort', effort);
+  return args;
+}
+
+function parseClaude(stdout, streamed) {
+  if (!streamed) return JSON.parse(stdout);
+  const lines = String(stdout).split('\n').filter((line) => line.trim());
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    let event;
+    try { event = JSON.parse(lines[index]); } catch { continue; }
+    if (event.type === 'result') return event;
+  }
+  throw new Error('claude CLI returned no result');
+}
+
+async function runClaude({ prompt, images, cwd, model, effort }) {
+  const streamed = images.length > 0;
+  const input = streamed ? `${JSON.stringify({
+    type: 'user',
+    message: {
+      role: 'user',
+      content: [
+        { type: 'text', text: prompt },
+        ...images.map((image) => ({ type: 'image', source: { type: 'base64', media_type: image.mediaType, data: image.data } })),
+      ],
+    },
+  })}\n` : '';
+  const envelope = parseClaude(await pipe('claude', claudeArgs({ prompt, model, effort, streamed }), { cwd, input }), streamed);
+  if (envelope.is_error) throw new Error(`claude CLI error: ${String(envelope.result).slice(0, 300)}`);
+  return String(envelope.result || '');
+}
+
+// ── Codex CLI ──────────────────────────────────────────────────────────────────────────
+// Codex keeps the models it can use, with their effort levels, in its own cache.
+async function codexModels(env) {
+  const home = codexHome(env);
+  let models = [];
+  try {
+    const cache = JSON.parse(await fs.readFile(path.join(home, 'models_cache.json'), 'utf8'));
+    models = (cache.models || [])
+      .filter((model) => model && typeof model.slug === 'string')
+      .map((model) => ({
+        id: model.slug,
+        label: model.display_name || model.slug,
+        efforts: (model.supported_reasoning_levels || []).map((level) => level.effort).filter((effort) => typeof effort === 'string'),
+        defaultEffort: model.default_reasoning_level,
+      }));
+  } catch { /* no cache yet: the developer can still use Codex's own default */ }
+  let config = '';
+  try { config = await fs.readFile(path.join(home, 'config.toml'), 'utf8'); } catch { /* no config */ }
+  const setting = (key) => (config.match(new RegExp(`^${key}\\s*=\\s*"([^"]+)"`, 'm')) || [])[1];
+  return { models, defaultModel: setting('model'), defaultEffort: setting('model_reasoning_effort') };
+}
+
+// Keep in step with codexArgs in the server's services/siteBuilder/agentRunners.js, which
+// shows this command on the developer page (a server test compares the two).
+function codexArgs({ model, effort, cwd, output, imageFiles = [] }) {
+  return [
+    'exec', '--skip-git-repo-check', '--ephemeral', '--sandbox', 'read-only', '--ignore-rules', '--color', 'never',
+    '-C', cwd, '-m', model,
+    ...(effort ? ['-c', `model_reasoning_effort="${effort}"`] : []),
+    ...imageFiles.flatMap((file) => ['-i', file]),
+    '-o', output, '-',
+  ];
+}
+
+// Screenshots as files in a scratch folder, for CLIs that take image paths.
+async function writeImages(scratch, images) {
+  const files = [];
+  for (const [index, image] of images.entries()) {
+    const file = path.join(scratch, `screenshot-${index + 1}.${(image.mediaType || 'image/png').split('/')[1] || 'png'}`);
+    await fs.writeFile(file, Buffer.from(image.data, 'base64'));
+    files.push(file);
+  }
+  return files;
+}
+
+async function runCodex({ prompt, images, cwd, model, effort }) {
+  const scratch = await fs.mkdtemp(path.join(os.tmpdir(), 'website-runner-codex-'));
+  try {
+    const output = path.join(scratch, 'reply.txt');
+    await pipe('codex', codexArgs({ model, effort, cwd, output, imageFiles: await writeImages(scratch, images) }), { cwd, input: prompt });
+    return await fs.readFile(output, 'utf8');
+  } finally {
+    await fs.rm(scratch, { recursive: true, force: true });
+  }
+}
+
+// ── Ollama ─────────────────────────────────────────────────────────────────────────────
+async function ollamaModels(env) {
+  try {
+    const response = await fetch(`${ollamaHost(env)}/api/tags`, { signal: AbortSignal.timeout(1500) });
+    const data = await response.json();
+    const models = (data.models || []).map((model) => ({ id: model.name, label: model.name, efforts: OLLAMA_EFFORTS }));
+    return models.length ? { available: true, models } : { available: false, reason: 'Ollama has no models. Pull one with: ollama pull <model>', models };
+  } catch {
+    return { available: false, reason: 'Ollama is not running. Start it with: ollama serve', models: [] };
+  }
+}
+
+async function runOllama({ prompt, images, model, effort, env = process.env }) {
+  const response = await fetch(`${ollamaHost(env)}/api/chat`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      model,
+      stream: false,
+      messages: [{ role: 'user', content: prompt, ...(images.length ? { images: images.map((image) => image.data) } : {}) }],
+      ...(effort ? { think: effort } : {}),
+      options: { num_ctx: parseInt(env.OLLAMA_NUM_CTX || '32768', 10) },
+    }),
+    signal: AbortSignal.timeout(TIMEOUT_MS()),
+  });
+  if (!response.ok) throw new Error(`ollama answered ${response.status}`);
+  const data = await response.json();
+  return String(data?.message?.content || '');
+}
+
+// ── --exec: any other CLI agent ────────────────────────────────────────────────────────
+// The prompt goes in on stdin; the reply (the files JSON) comes back on stdout. Screenshots
+// are written next to the workspace, their paths in WEREWOLF_IMAGES (one per line).
+// The command's program name, e.g. "aider" for `aider --yes` or "node" for `"/usr/bin/node" agent.js`.
+const execName = (command) => {
+  const line = String(command || '').trim();
+  const program = /^["']/.test(line) ? line.slice(1, line.indexOf(line[0], 1) > 0 ? line.indexOf(line[0], 1) : undefined) : line.split(/\s+/)[0];
+  return program.split(/[\\/]/).pop() || 'exec';
+};
+
+async function runExec({ command, prompt, images, cwd }) {
+  if (!command) throw new Error('This run is for --exec, but the runner was started without --exec');
+  const scratch = await fs.mkdtemp(path.join(os.tmpdir(), 'website-runner-exec-'));
+  try {
+    const imageFiles = await writeImages(scratch, images);
+    return await pipe(command, [], { cwd, input: prompt, shell: true, env: { ...process.env, WEREWOLF_IMAGES: imageFiles.join('\n') } });
+  } finally {
+    await fs.rm(scratch, { recursive: true, force: true });
+  }
+}
+
+/**
+ * What this machine can run, with a reason when a runner can't be used right now.
+ * With `exec`, the --exec command is offered too, as one model named after the command.
+ */
+async function listRunners({ env = process.env, exec } = {}) {
+  const [claude, codex, codexInfo, ollama] = await Promise.all([installed('claude'), installed('codex'), codexModels(env), ollamaModels(env)]);
+  const runners = [
+    { id: 'claude-cli', label: 'Claude CLI', available: claude, ...(claude ? {} : { reason: 'The claude CLI is not installed or not on PATH.' }), models: CLAUDE_MODELS, defaultModel: 'opus', defaultEffort: 'high' },
+    { id: 'codex-cli', label: 'Codex CLI', available: codex && codexInfo.models.length > 0, ...(!codex ? { reason: 'The codex CLI is not installed or not on PATH.' } : codexInfo.models.length ? {} : { reason: 'Codex has no model list yet. Run codex once to sign in.' }), models: codexInfo.models, defaultModel: codexInfo.defaultModel, defaultEffort: codexInfo.defaultEffort },
+    { id: 'ollama', label: 'Ollama (local)', ...ollama, defaultModel: ollama.models[0]?.id, defaultEffort: '' },
+  ];
+  if (exec) runners.push({ id: 'exec', label: `Your command (${execName(exec)})`, available: true, models: [{ id: execName(exec), label: exec.slice(0, 120), efforts: [] }], defaultModel: execName(exec), defaultEffort: '' });
+  return runners;
+}
+
+/** One turn with the chosen runner; returns the model's reply text. */
+async function runAgent({ provider, model, effort, prompt, images = [], cwd, exec }) {
+  if (provider === 'claude-cli') return runClaude({ prompt, images, cwd, model, effort });
+  if (provider === 'codex-cli') return runCodex({ prompt, images, cwd, model, effort });
+  if (provider === 'ollama') return runOllama({ prompt, images, model, effort });
+  if (provider === 'exec') return runExec({ command: exec, prompt, images, cwd });
+  throw new Error(`This runner can't run ${provider}`);
+}
+
+module.exports = { listRunners, runAgent, codexArgs, codexModels, claudeArgs, execName, pipe };

package/src/api.js

@@ -0,0 +1,43 @@
+/**
+ * Talking to a Werewolf Solutions server with a runner token. Plain fetch, no dependencies.
+ * Failed calls throw an Error with `response: { status, data }`, so callers can tell a refusal
+ * (the server answered) from a server that isn't reachable (no `response`).
+ */
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+
+// "https://staging.werewolf.solutions" or ".../api/v1" both work. Tokens only travel over
+// HTTPS, except to this machine.
+function apiBase(value) {
+  let url;
+  try { url = new URL(String(value || '')); } catch { throw new Error('Pass the site address, for example --api https://staging.werewolf.solutions'); }
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && LOCAL_HOSTS.has(url.hostname))) throw new Error('The API address must use https (http only for localhost)');
+  const trimmed = `${url.origin}${url.pathname}`.replace(/\/+$/, '');
+  return trimmed.endsWith('/api/v1') ? trimmed : `${trimmed}/api/v1`;
+}
+
+const problemOf = (error) => error.response?.data?.message || error.message || String(error);
+
+function createClient({ api, token, fetch: fetchImpl = globalThis.fetch, timeoutMs = 120000 }) {
+  if (!token || !/^ws_sk_/.test(token)) throw new Error('Set WEREWOLF_DEV_TOKEN to your website runner token (create it on the developer page)');
+  const baseURL = apiBase(api);
+  const request = async (method, path, body, { timeout = timeoutMs } = {}) => {
+    const response = await fetchImpl(`${baseURL}${path}`, {
+      method,
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: AbortSignal.timeout(timeout),
+    });
+    const data = await response.json().catch(() => ({}));
+    if (!response.ok) {
+      throw Object.assign(new Error(data.message || `${method} ${path} failed (${response.status})`), { response: { status: response.status, data } });
+    }
+    return { status: response.status, data };
+  };
+  return {
+    baseURL,
+    get: (path, options) => request('GET', path, undefined, options),
+    post: (path, body = {}, options) => request('POST', path, body, options),
+  };
+}
+
+module.exports = { apiBase, createClient, problemOf };

package/src/cli.js

@@ -0,0 +1,81 @@
+/**
+ * `werewolf-dev runner`: build website drafts for the businesses assigned to you, on this
+ * machine, for the server at --api.
+ */
+const { createRemoteRunner } = require('./runner');
+const { listRunners } = require('./agents');
+const { buildDraft } = require('./draft');
+
+const RUNNER_USAGE = `usage: WEREWOLF_DEV_TOKEN=ws_sk_… werewolf-dev runner --api <site> [--exec "<command>"] [--host <name>]
+
+  --api    the site, e.g. https://staging.werewolf.solutions (or set WEREWOLF_API_URL)
+  --exec   any other CLI agent: gets the prompt on stdin, prints the files JSON on stdout;
+           screenshot paths are in WEREWOLF_IMAGES, one per line
+  --host   the name this machine shows on the developer page (default: its hostname)
+
+Get the token on the developer page, under Website runner.`;
+
+const log = (...parts) => console.log(`[website-runner ${new Date().toISOString().slice(11, 19)}]`, ...parts);
+
+function argValue(argv, name) {
+  const index = argv.indexOf(name);
+  if (index > -1) return argv[index + 1];
+  const inline = argv.find((item) => item.startsWith(`${name}=`));
+  return inline ? inline.slice(name.length + 1) : undefined;
+}
+
+// Ctrl+C, closing the terminal or kill: run `cleanup` (at most 5s), then exit. A second
+// Ctrl+C skips the cleanup. Child CLIs (claude, codex) share the terminal and get it too.
+function onStop(cleanup) {
+  let stopping = false;
+  const stop = async () => {
+    if (stopping) process.exit(130);
+    stopping = true;
+    log('stopping');
+    const timeout = new Promise((resolve) => { setTimeout(resolve, 5000).unref(); });
+    await Promise.race([Promise.resolve().then(cleanup).catch((error) => log(`cleanup failed: ${error.message}`)), timeout]);
+    log('stopped');
+    process.exit(0);
+  };
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(signal, stop);
+  return () => stopping;
+}
+
+async function runnerMain(argv, env = process.env) {
+  if (argv.includes('--help') || argv.includes('-h')) { console.log(RUNNER_USAGE); return 0; }
+  // Full-site generation with the checklist takes longer than a quick revision.
+  env.AI_BUILDER_CLI_TIMEOUT_MS = env.AI_BUILDER_CLI_TIMEOUT_MS || '600000';
+  const exec = argValue(argv, '--exec');
+  let runner;
+  try {
+    runner = createRemoteRunner({
+      api: argValue(argv, '--api') || env.WEREWOLF_API_URL,
+      token: env.WEREWOLF_DEV_TOKEN,
+      exec,
+      ...(argValue(argv, '--host') ? { host: argValue(argv, '--host') } : {}),
+      listRunners: () => listRunners({ env, exec }),
+      buildDraft,
+      log,
+    });
+  } catch (error) {
+    console.error(`\n  refused: ${error.message}\n\n${RUNNER_USAGE}\n`);
+    return 1;
+  }
+  const stopping = onStop(async () => {
+    if (runner.busy()) {
+      log('handing the current run back to the server');
+      await runner.release().catch((error) => log(`could not hand it back: ${error.message}`));
+    }
+    await runner.disconnect().catch(() => {});
+  });
+  try {
+    await runner.loop();
+  } catch (error) {
+    if (stopping()) await new Promise(() => {});
+    console.error(`\n  stopped: ${error.message}\n`);
+    return 1;
+  }
+  return 0;
+}
+
+module.exports = { runnerMain, argValue, RUNNER_USAGE };

package/src/contract.js

@@ -0,0 +1,38 @@
+/**
+ * Reading a model's reply into website files. A copy of the two helpers in the server's
+ * services/siteBuilder/providers/contract.js, so the runner needs nothing from the server.
+ * The server checks every upload again, so these are a convenience, not the guard.
+ */
+const MAX_FILES = 20;
+const MAX_TOTAL_BYTES = 5 * 1024 * 1024;
+
+const contentTypeFor = (path) => (path.endsWith('.html') ? 'text/html; charset=utf-8'
+  : path.endsWith('.css') ? 'text/css'
+    : path.endsWith('.xml') ? 'application/xml'
+      : 'text/plain; charset=utf-8');
+
+const extractJson = (text) => {
+  const start = text.indexOf('{');
+  const end = text.lastIndexOf('}');
+  if (start === -1 || end <= start) throw new Error('No JSON object in model output');
+  return JSON.parse(text.slice(start, end + 1));
+};
+
+const sanitizeFiles = (rawFiles) => {
+  if (!Array.isArray(rawFiles) || rawFiles.length === 0) throw new Error('Model returned no files');
+  let total = 0;
+  const files = rawFiles.slice(0, MAX_FILES).map((file) => {
+    const path = String(file.path || '').replace(/^\/+/, '');
+    if (!path || path.includes('..') || path.startsWith('/') || !/^[\w./-]+$/.test(path)) {
+      throw new Error(`Unsafe file path from model: ${file.path}`);
+    }
+    const content = String(file.content || '');
+    total += Buffer.byteLength(content, 'utf8');
+    if (total > MAX_TOTAL_BYTES) throw new Error('Generated output too large');
+    return { path, contentType: contentTypeFor(path), content, size: Buffer.byteLength(content, 'utf8') };
+  });
+  if (!files.some((file) => file.path === 'index.html')) throw new Error('Model output is missing index.html');
+  return files;
+};
+
+module.exports = { extractJson, sanitizeFiles, contentTypeFor };