mhproto 0.8.0-preview.0

package/src/server.mjs

@@ -0,0 +1,290 @@
+import { createServer } from 'node:http';
+import { readFile, mkdir, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { loadProject, validateProject, packageRoot, projectPath } from './core.mjs';
+import { addVisual, mediaMime, maxMediaBytes } from './visuals.mjs';
+import { atomicWrite, writePath } from './paths.mjs';
+import { compareModels, contractSnapshot, snapshotProject } from '../viewer/diff.js';
+export { compareModels } from '../viewer/diff.js';
+
+const assets = {
+  '/': ['index.html', 'text/html'],
+  '/app.js': ['app.js', 'text/javascript'],
+  '/diff.js': ['diff.js', 'text/javascript'],
+  '/style.css': ['style.css', 'text/css'],
+  '/vendor/mermaid.min.js': ['vendor/mermaid.min.js', 'text/javascript'],
+};
+export async function model(root) {
+  const project = await loadProject(root);
+  return { ...project, issues: await validateProject(project) };
+}
+async function readBaseline(file, required = false) {
+  try {
+    const value = JSON.parse(await readFile(file, 'utf8'));
+    snapshotProject(value);
+    return contractSnapshot(value, {
+      label: value.label ?? 'Saved baseline',
+      createdAt: value.createdAt ?? null,
+    });
+  } catch (error) {
+    if (error.code === 'ENOENT' && !required) return null;
+    throw error;
+  }
+}
+
+export function createHandler(root, { against } = {}) {
+  const baselineFile = path.resolve(root, against ?? '.mhproto/baseline.json');
+  return async (request, response) => {
+    response.setHeader(
+      'content-security-policy',
+      "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'; frame-ancestors 'none'; base-uri 'none'",
+    );
+    response.setHeader('x-content-type-options', 'nosniff');
+    response.setHeader('cache-control', 'no-store');
+    if (!/^(127\.0\.0\.1|localhost)(:\d+)?$/.test(request.headers.host ?? '')) {
+      response.writeHead(403).end();
+      return;
+    }
+    try {
+      const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+      if (request.method === 'POST' && url.pathname === '/api/baseline') {
+        if (against) {
+          response.writeHead(409, { 'content-type': 'application/json' }).end(
+            JSON.stringify({
+              error:
+                'This comparison uses --against. Start a new viewer without it to save an iteration baseline.',
+            }),
+          );
+          return;
+        }
+        if (request.headers.origin !== 'http://' + request.headers.host) {
+          response.writeHead(403).end();
+          return;
+        }
+        if (!(request.headers['content-type'] ?? '').startsWith('application/json')) {
+          response.writeHead(415).end();
+          return;
+        }
+        let bytes = 0;
+        for await (const chunk of request) {
+          bytes += chunk.length;
+          if (bytes > 1024) {
+            response.writeHead(413).end();
+            return;
+          }
+        }
+        const baseline = contractSnapshot(await model(root));
+        await atomicWrite(root, '.mhproto/baseline.json', JSON.stringify(baseline, null, 2) + '\n');
+        response
+          .writeHead(201, { 'content-type': 'application/json' })
+          .end(JSON.stringify(baseline));
+        return;
+      }
+      if (request.method === 'POST' && url.pathname === '/api/visuals') {
+        if (request.headers.origin !== 'http://' + request.headers.host) {
+          response.writeHead(403).end();
+          return;
+        }
+        if (!(request.headers['content-type'] ?? '').startsWith('application/json')) {
+          response.writeHead(415).end();
+          return;
+        }
+        const chunks = [];
+        let bytes = 0;
+        for await (const chunk of request) {
+          bytes += chunk.length;
+          if (bytes > Math.ceil((maxMediaBytes * 4) / 3) + 8192) {
+            response.writeHead(413).end();
+            return;
+          }
+          chunks.push(chunk);
+        }
+        let visual;
+        try {
+          visual = await addVisual(
+            root,
+            await loadProject(root),
+            JSON.parse(Buffer.concat(chunks).toString('utf8')),
+          );
+        } catch (error) {
+          response
+            .writeHead(400, { 'content-type': 'application/json' })
+            .end(JSON.stringify({ error: error.message }));
+          return;
+        }
+        response.writeHead(201, { 'content-type': 'application/json' }).end(JSON.stringify(visual));
+        return;
+      }
+      if (!['GET', 'HEAD'].includes(request.method)) {
+        response.writeHead(405).end();
+        return;
+      }
+      if (url.pathname.startsWith('/api/visuals/')) {
+        const project = await loadProject(root),
+          id = url.pathname.slice('/api/visuals/'.length);
+        const visual = project.visuals.find((v) => v.id === id && v.file);
+        if (!visual) {
+          response.writeHead(404).end();
+          return;
+        }
+        response.setHeader('content-type', mediaMime(visual.file));
+        const bytes = await readFile(await projectPath(root, visual.file));
+        response.end(request.method === 'HEAD' ? undefined : bytes);
+        return;
+      }
+      if (url.pathname === '/api/model') {
+        response.setHeader('content-type', 'application/json');
+        response.end(JSON.stringify(await model(root)));
+        return;
+      }
+      if (url.pathname === '/api/diff') {
+        const previous = await readBaseline(baselineFile, Boolean(against));
+        response.setHeader('content-type', 'application/json');
+        response.end(
+          JSON.stringify({
+            available: Boolean(previous),
+            changes: previous ? compareModels(previous, await model(root)) : [],
+          }),
+        );
+        return;
+      }
+      if (url.pathname === '/api/baseline') {
+        response.setHeader('x-mhproto-baseline-readonly', String(Boolean(against)));
+        response.setHeader('content-type', 'application/json');
+        response.end(JSON.stringify(await readBaseline(baselineFile, Boolean(against))));
+        return;
+      }
+      const asset = assets[url.pathname];
+      if (!asset) {
+        response.writeHead(404).end();
+        return;
+      }
+      response.setHeader('content-type', asset[1]);
+      response.end(await readFile(path.join(packageRoot, 'viewer', asset[0])));
+    } catch (error) {
+      response
+        .writeHead(500, { 'content-type': 'application/json' })
+        .end(JSON.stringify({ error: error.message }));
+    }
+  };
+}
+export async function serve(root, port = 4317, options = {}) {
+  const server = createServer(createHandler(root, options));
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, '127.0.0.1', resolve);
+  });
+  return server;
+}
+
+export async function exportViewer(root, destination, { against } = {}) {
+  const actualRoot = await realpath(root);
+  const actualDestination = await realpath(destination).catch((error) => {
+    if (error.code !== 'ENOENT') throw error;
+    return path.resolve(destination);
+  });
+  if (actualDestination === actualRoot)
+    throw new Error('Export into a separate directory, not the project root');
+  const relative = path.relative(path.resolve(root), path.resolve(destination));
+  if (!relative.startsWith('..' + path.sep) && !path.isAbsolute(relative))
+    await writePath(root, path.join(relative, 'viewer.html'));
+  const loaded = await model(root);
+  if (loaded.issues.some((issue) => issue.level === 'error'))
+    throw new Error('Fix contract validation errors before exporting');
+  // Portable exports retain evidence summaries, not captured process output or
+  // machine paths. Authored contract data still needs review before sharing.
+  const { root: localRoot, ...data } = loaded;
+  const keep = (value, keys) =>
+    Object.fromEntries(
+      keys.filter((key) => value[key] !== undefined).map((key) => [key, value[key]]),
+    );
+  const project = {
+    ...data,
+    capabilities: loaded.capabilities.map((cap) => ({
+      ...cap,
+      evidence: cap.evidence
+        ? {
+            ...keep(cap.evidence, [
+              'version',
+              'capability',
+              'digest',
+              'finishedAt',
+              'changedDuringRun',
+              'stale',
+            ]),
+            results: cap.evidence.results.map((result) => ({
+              ...keep(result, [
+                'id',
+                'status',
+                'startedAt',
+                'durationMs',
+                'exitCode',
+                'timedOut',
+                'missing',
+                'skipped',
+                'todo',
+                'truncated',
+                'rules',
+                'examples',
+              ]),
+              tests: (result.tests ?? []).map((test) =>
+                keep(test, ['type', 'name', 'skip', 'todo']),
+              ),
+            })),
+          }
+        : null,
+    })),
+  };
+  const media = {};
+  for (const visual of project.visuals)
+    if (visual.file) {
+      const mime = mediaMime(visual.file);
+      if (!mime) throw new Error(`Unsupported visual file: ${visual.file}`);
+      media[visual.id] =
+        `data:${mime};base64,${(await readFile(await projectPath(root, visual.file))).toString('base64')}`;
+    }
+  const baseline = await readBaseline(
+    path.resolve(root, against ?? '.mhproto/baseline.json'),
+    Boolean(against),
+  );
+  const [html, css, js, mermaid, diff] = await Promise.all(
+    ['index.html', 'style.css', 'app.js', 'vendor/mermaid.min.js', 'diff.js'].map((name) =>
+      readFile(path.join(packageRoot, 'viewer', name), 'utf8'),
+    ),
+  );
+  const bundled = js.replace(/import\s*\{[^}]+\}\s*from\s*['"]\.\/diff\.js['"];?/, () =>
+    diff.replace(/^export /gm, ''),
+  );
+  const safeJson = (value) => JSON.stringify(value).replaceAll('<', '\\u003c');
+  const standalone = html
+    .replace(/<link\s+rel="stylesheet"\s+href="\/style\.css"\s*\/?>/, () => `<style>${css}</style>`)
+    .replace(
+      /<script\s+src="\/vendor\/mermaid\.min\.js"\s*>\s*<\/script>/,
+      () => `<script>${mermaid.replace(/<\/script/gi, '<\\/script')}</script>`,
+    )
+    .replace(
+      /<script\s+type="module"\s+src="\/app\.js"\s*>\s*<\/script>/,
+      () =>
+        `<script id="mhproto-model" type="application/json">${safeJson(project)}</script><script id="mhproto-media" type="application/json">${safeJson(media)}</script><script id="mhproto-baseline" type="application/json">${safeJson(baseline)}</script><script type="module">${bundled.replace(/<\/script/gi, '<\\/script')}</script>`,
+    );
+  if (
+    !standalone.includes('id="mhproto-model"') ||
+    /<script[^>]+src=/.test(standalone) ||
+    /<link[^>]+href="\/style\.css"/.test(standalone)
+  )
+    throw new Error('Viewer template could not be bundled into a standalone export');
+  const output = new Map([
+    ['index.html', html],
+    ['style.css', css],
+    ['app.js', js],
+    ['vendor/mermaid.min.js', mermaid],
+    ['diff.js', diff],
+    ['model.json', JSON.stringify(project, null, 2)],
+    ['baseline.json', JSON.stringify(baseline)],
+    ['viewer.html', standalone],
+  ]);
+  await mkdir(destination, { recursive: true });
+  // Resolve every output before replacing any existing file.
+  for (const name of output.keys()) await writePath(destination, name);
+  for (const [name, contents] of output) await atomicWrite(destination, name, contents);
+}

package/src/verify.mjs

@@ -0,0 +1,149 @@
+import { spawn } from 'node:child_process';
+import { StringDecoder } from 'node:string_decoder';
+import path from 'node:path';
+import { loadProject, packageRoot } from './core.mjs';
+import { atomicWrite } from './paths.mjs';
+
+export async function runCheck(check, root) {
+  const command = check.command.map((arg) =>
+    arg === '{mhprotoNodeReporter}' ? path.join(packageRoot, 'src/node-reporter.mjs') : arg,
+  );
+  const startedAt = new Date().toISOString();
+  const started = Date.now();
+  return new Promise((resolve) => {
+    const env = { ...process.env, ...check.env };
+    // Each command is an independent run even when MHProto itself is called from node --test.
+    delete env.NODE_TEST_CONTEXT;
+    const child = spawn(command[0], command.slice(1), {
+      cwd: root,
+      shell: false,
+      env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      detached: process.platform !== 'win32',
+    });
+    let stdout = '',
+      stderr = '',
+      truncated = false,
+      settled = false,
+      timedOut = false;
+    const tests = [];
+    const decoder = new StringDecoder('utf8');
+    let pending = '',
+      eventBytes = 0,
+      malformed = false;
+    const limit = 1024 * 1024;
+    const stop = () => {
+      try {
+        if (process.platform === 'win32') child.kill('SIGKILL');
+        else process.kill(-child.pid, 'SIGKILL');
+      } catch {}
+    };
+    const timer = setTimeout(() => {
+      timedOut = true;
+      stop();
+    }, check.timeoutMs ?? 60000);
+    child.stdout.on('data', (data) => {
+      const text = decoder.write(data);
+      if (stdout.length + text.length > limit) truncated = true;
+      stdout += text.slice(0, Math.max(0, limit - stdout.length));
+      if (check.runner === 'node-test') {
+        eventBytes += data.length;
+        if (eventBytes > limit) {
+          malformed = true;
+          stop();
+          return;
+        }
+        const lines = (pending + text).split('\n');
+        pending = lines.pop();
+        for (const line of lines) {
+          try {
+            const item = JSON.parse(line);
+            if (!['test:pass', 'test:fail'].includes(item.type) || typeof item.name !== 'string')
+              malformed = true;
+            else tests.push(item);
+          } catch {
+            if (line.trim()) malformed = true;
+          }
+        }
+      }
+    });
+    child.stderr.on('data', (data) => {
+      const text = data.toString();
+      if (stderr.length + text.length > limit) truncated = true;
+      stderr += text.slice(0, Math.max(0, limit - stderr.length));
+    });
+    function finish(exitCode, error) {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      const missing = (check.testNames ?? []).filter(
+        (name) =>
+          !tests.some((t) => t.name === name && ['test:pass', 'test:fail'].includes(t.type)),
+      );
+      const skipped = (check.testNames ?? []).filter((name) =>
+        tests.some((t) => t.name === name && t.skip),
+      );
+      const todo = (check.testNames ?? []).filter((name) =>
+        tests.some((t) => t.name === name && t.todo),
+      );
+      const failed = tests.filter((t) => t.type === 'test:fail');
+      if (pending.trim()) malformed = true;
+      const passed =
+        exitCode === 0 &&
+        !error &&
+        !timedOut &&
+        !malformed &&
+        !missing.length &&
+        !skipped.length &&
+        !todo.length &&
+        !failed.length;
+      resolve({
+        id: check.id,
+        status: passed ? 'passing' : 'failing',
+        startedAt,
+        durationMs: Date.now() - started,
+        command,
+        exitCode,
+        timedOut,
+        error:
+          error?.message ?? (malformed ? 'Invalid or oversized node-test reporter output' : null),
+        missing,
+        skipped,
+        todo,
+        tests,
+        stdout,
+        stderr,
+        truncated,
+        rules: check.rules ?? [],
+        examples: check.examples ?? [],
+      });
+    }
+    child.on('error', (error) => finish(null, error));
+    child.on('close', (code) => finish(code));
+  });
+}
+
+export async function verifyCapability(project, cap, onResult = () => {}) {
+  const results = [];
+  // Commands are deliberately sequential. Test fixtures can share resources.
+  for (const check of cap.checks) {
+    const result = await runCheck(check, project.root);
+    results.push(result);
+    onResult(result);
+  }
+  const current = (await loadProject(project.root)).capabilities.find((c) => c.id === cap.id);
+  const report = {
+    version: 1,
+    capability: cap.id,
+    digest: cap.digest,
+    finishedAt: new Date().toISOString(),
+    changedDuringRun: current?.digest !== cap.digest,
+    results,
+  };
+  await atomicWrite(
+    project.root,
+    `.mhproto/evidence/${cap.id}.json`,
+    JSON.stringify(report, null, 2) + '\n',
+  );
+  return report;
+}

package/src/visuals.mjs

@@ -0,0 +1,189 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID, createHash } from 'node:crypto';
+import { parse, stringify } from 'yaml';
+import { atomicWrite, writePath } from './paths.mjs';
+
+export const visualsFile = 'mhproto/visuals.yaml';
+const queues = new Map();
+export const mediaTypes = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/webp': 'webp',
+  'image/gif': 'gif',
+  'application/pdf': 'pdf',
+};
+export const maxMediaBytes = 8 * 1024 * 1024;
+export function mediaMime(file) {
+  return Object.entries(mediaTypes).find(
+    ([, ext]) =>
+      path.extname(file).slice(1).toLowerCase() === ext ||
+      (ext === 'jpg' && path.extname(file).toLowerCase() === '.jpeg'),
+  )?.[0];
+}
+export function safeDesignUrl(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === 'https:' && !url.username && !url.password;
+  } catch {
+    return false;
+  }
+}
+function resolve(cap, schema) {
+  let current = schema,
+    seen = new Set();
+  while (current?.$ref) {
+    if (seen.has(current.$ref)) return {};
+    seen.add(current.$ref);
+    let value = cap.openapi;
+    for (const part of current.$ref.slice(2).split('/'))
+      value = value?.[part.replaceAll('~1', '/').replaceAll('~0', '~')];
+    current = value;
+  }
+  return current ?? {};
+}
+function propertyAt(cap, schema, parts) {
+  const s = resolve(cap, schema);
+  if (!parts.length) return s;
+  if (s.anyOf || s.oneOf || s.allOf)
+    return (s.anyOf ?? s.oneOf ?? s.allOf)
+      .map((item) => propertyAt(cap, item, parts))
+      .find((schema) => schema != null);
+  const [part, ...rest] = parts;
+  const child = part === '*' ? s.items : s.properties?.[part];
+  return child !== undefined ? propertyAt(cap, child, rest) : null;
+}
+export function targetError(project, target) {
+  if (!target || typeof target !== 'object') return 'Visual requires a target';
+  const cap = project.capabilities.find((c) => c.id === target.capability);
+  if (!cap) return 'Visual references an unknown feature';
+  const op = cap.operations.find((o) => o.operationId === target.id);
+  if (target.kind === 'feature') return null;
+  if (['operation', 'request', 'response', 'field'].includes(target.kind)) {
+    if (!op) return 'Visual references an unknown operation';
+    if (target.kind === 'response' && target.status && !op.responses?.[target.status])
+      return 'Visual references an unknown response';
+    if (target.kind === 'field') {
+      if (
+        !['request', 'response'].includes(target.scope) ||
+        typeof target.path !== 'string' ||
+        !target.path.startsWith('/')
+      )
+        return 'Field visual requires request/response scope and a JSON pointer';
+      let schema;
+      if (target.scope === 'response')
+        schema =
+          op.responses?.[target.status ?? Object.keys(op.responses).find((s) => /^2/.test(s))]
+            ?.content?.['application/json']?.schema;
+      else
+        schema = {
+          type: 'object',
+          properties: {
+            body: op.requestBody?.content?.['application/json']?.schema,
+            ...Object.fromEntries(
+              ['path', 'query', 'header', 'cookie'].map((location) => [
+                location,
+                {
+                  type: 'object',
+                  properties: Object.fromEntries(
+                    (op.parameters ?? [])
+                      .filter((p) => p.in === location)
+                      .map((p) => [p.name, p.schema]),
+                  ),
+                },
+              ]),
+            ),
+          },
+        };
+      if (
+        propertyAt(
+          cap,
+          schema,
+          target.path
+            .slice(1)
+            .split('/')
+            .map((p) => p.replaceAll('~1', '/').replaceAll('~0', '~')),
+        ) == null
+      )
+        return 'Visual references an unknown field';
+    }
+    return null;
+  }
+  const items = {
+    schema: Object.keys(cap.openapi.components?.schemas ?? {}),
+    example: cap.examples.map((e) => e.id),
+    rule: cap.rules.map((r) => r.id),
+    check: cap.checks.map((c) => c.id),
+  };
+  if (!items[target.kind]) return 'Unsupported visual target';
+  return items[target.kind].includes(target.id)
+    ? null
+    : 'Visual references an unknown ' + target.kind;
+}
+export function validMedia(bytes, mime) {
+  if (mime === 'image/png')
+    return bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]));
+  if (mime === 'image/jpeg') return bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255;
+  if (mime === 'image/webp')
+    return bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WEBP';
+  if (mime === 'image/gif') return /^GIF8[79]a$/.test(bytes.toString('ascii', 0, 6));
+  return mime === 'application/pdf' && bytes.toString('ascii', 0, 5) === '%PDF-';
+}
+export async function addVisual(root, project, input) {
+  const operation = async () => {
+    if (!input || typeof input !== 'object') throw new Error('Visual input must be an object');
+    if (Boolean(input.url) === Boolean(input.data))
+      throw new Error('Choose exactly one file or design link');
+    const error = targetError(project, input.target);
+    if (error) throw new Error(error);
+    if (typeof input.title !== 'string' || !input.title.trim() || input.title.length > 200)
+      throw new Error('Visual requires a title (up to 200 characters)');
+    const visual = {
+      id: randomUUID(),
+      title: input.title.trim(),
+      kind: input.url ? 'design' : 'screenshot',
+      target: input.target,
+    };
+    if (input.caption) {
+      if (typeof input.caption !== 'string' || input.caption.length > 1000)
+        throw new Error('Caption is too long');
+      visual.caption = input.caption;
+    }
+    let bytes;
+    if (input.url) {
+      if (!safeDesignUrl(input.url)) throw new Error('Design links must use HTTPS');
+      visual.url = input.url;
+    } else {
+      const match = /^data:([^;]+);base64,([A-Za-z0-9+/]*={0,2})$/.exec(input.data ?? '');
+      if (!match || !mediaTypes[match[1]]) throw new Error('Use a PNG, JPEG, WebP, GIF or PDF');
+      bytes = Buffer.from(match[2], 'base64');
+      if (!bytes.length || bytes.length > maxMediaBytes)
+        throw new Error('Visual files must be between 1 byte and 8 MB');
+      if (!validMedia(bytes, match[1]))
+        throw new Error('Visual content does not match its media type');
+      visual.mime = match[1];
+      if (visual.mime === 'application/pdf') visual.kind = 'design';
+      visual.file = `mhproto/assets/${visual.id}.${mediaTypes[visual.mime]}`;
+      visual.sha256 = createHash('sha256').update(bytes).digest('hex');
+    }
+    const metadata = await writePath(root, visualsFile);
+    let entries = [];
+    try {
+      entries = parse(await readFile(metadata, 'utf8'))?.visuals;
+      if (!Array.isArray(entries)) throw new Error('visuals.yaml requires a visuals array');
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+    if (bytes) await writeFile(await writePath(root, visual.file), bytes, { flag: 'wx' });
+    await atomicWrite(root, visualsFile, stringify({ visuals: [...entries, visual] }));
+    return visual;
+  };
+  const previous = queues.get(root) ?? Promise.resolve();
+  const task = previous.catch(() => {}).then(operation);
+  queues.set(root, task);
+  try {
+    return await task;
+  } finally {
+    if (queues.get(root) === task) queues.delete(root);
+  }
+}