@shidesheng0218/dsh-plugin-lint 0.0.0-stage → 0.4.0

package/src/matrix/run.js

@@ -0,0 +1,241 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { ToolError } from '../shared/errors.js';
+import { PROBE_VERSION } from '../shared/version.js';
+import { sha256 } from '../shared/hash.js';
+import { resolveArtifact } from '../probe/artifact-resolver.js';
+import { createProbeEnvironment } from '../probe/environment.js';
+import { probePackage } from '../probe/probe.js';
+import { startStub as startHostStub } from '../probe/dsh-adapter.js';
+import { cacheKeyFor } from './cache.js';
+import { createCell } from './cell.js';
+import { cellFilePath, writeCell } from './cells.js';
+import { readCellAny } from './migrate.js';
+import { buildManifest } from './manifest.js';
+import { validateCell } from './schema.js';
+
+const EXACT_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const productionServices = {
+  resolveArtifact,
+  createProbeEnvironment,
+  probePackage,
+  startStub: async ({ environment }) => environment.startStub ? environment.startStub() : startHostStub(),
+};
+
+function splitSpec(value) {
+  const text = String(value);
+  const split = text.startsWith('@') ? text.lastIndexOf('@') > text.indexOf('/') : text.lastIndexOf('@') > 0;
+  if (!split) return { name: text, version: 'latest' };
+  const index = text.lastIndexOf('@');
+  return { name: text.slice(0, index), version: text.slice(index + 1) || 'latest' };
+}
+
+function inputFor(target, targetMode) {
+  if (targetMode === 'refresh-latest') {
+    if (typeof target === 'string' && existsSync(target)) return target;
+    if (target && typeof target === 'object' && (target.local || target.path)) return target;
+    return typeof target === 'string' ? splitSpec(target).name : target.name;
+  }
+  if ((typeof target === 'string' && existsSync(target)) || (target && typeof target === 'object' && (target.local || target.path))) return target;
+  if (target && typeof target === 'object') {
+    if (!EXACT_VERSION.test(target.version || '') || typeof target.integrity !== 'string') {
+      throw new ToolError('ARTIFACT_SPEC_UNSUPPORTED', 'Pinned matrix targets need an exact version and registry integrity.');
+    }
+    return target;
+  }
+  const spec = splitSpec(target);
+  if (!EXACT_VERSION.test(spec.version)) {
+    throw new ToolError('ARTIFACT_SPEC_UNSUPPORTED', 'Pinned matrix targets cannot re-resolve latest or a dist-tag.');
+  }
+  return target;
+}
+
+function publicError(error) {
+  return {
+    code: error?.code || 'MATRIX_INFRASTRUCTURE_ERROR',
+    message: error?.code ? error.message : 'The matrix cell could not complete because of an internal or host failure.',
+  };
+}
+
+export async function runMatrix({
+  targets,
+  targetMode = 'pinned',
+  dshVersions,
+  compositions = ['headless', 'web'],
+  outDir,
+  cacheRoot,
+  concurrency = 4,
+  force = false,
+  keep = false,
+  useTools = true,
+  backend = 'auto',
+  services = productionServices,
+  runId = 'local-matrix',
+}) {
+  if (!['pinned', 'refresh-latest'].includes(targetMode)) throw new ToolError('MATRIX_INPUT_INVALID', 'targetMode must be pinned or refresh-latest.');
+  if (!Array.isArray(targets) || targets.length === 0) throw new ToolError('MATRIX_INPUT_INVALID', 'At least one target is required.');
+  if (!Array.isArray(dshVersions) || dshVersions.length === 0) throw new ToolError('MATRIX_INPUT_INVALID', 'At least one DSH version is required.');
+  if (!Array.isArray(compositions) || compositions.length === 0 || compositions.some((mode) => !['headless', 'web'].includes(mode))) {
+    throw new ToolError('MATRIX_INPUT_INVALID', 'compositions must contain only headless and/or web.');
+  }
+  if (!outDir || !cacheRoot) throw new ToolError('MATRIX_INPUT_INVALID', 'outDir and cacheRoot are required.');
+  const resolved = [];
+  for (const target of targets) {
+    const artifact = await services.resolveArtifact(inputFor(target, targetMode));
+    resolved.push({
+      artifact,
+      input: {
+        name: artifact.name,
+        requestedVersion: artifact.requestedVersion,
+        resolvedVersion: artifact.resolvedVersion,
+        // A local artifact has integrity: undefined. JSON has no undefined, and
+        // stableStringify rightly rejects it; omitting the key keeps the manifest
+        // hashable instead of aborting every local-directory run.
+        ...(artifact.integrity !== undefined ? { integrity: artifact.integrity } : {}),
+        ...(artifact.sourceDigest !== undefined ? { sourceDigest: artifact.sourceDigest } : {}),
+        local: artifact.local,
+      },
+    });
+  }
+  const tasks = [];
+  for (const { artifact } of resolved) {
+    for (const version of dshVersions) {
+      for (const composition of compositions) tasks.push({ artifact, version, composition });
+    }
+  }
+  const summary = {
+    total: tasks.length,
+    completed: 0,
+    errors: 0,
+    cached: 0,
+    invalidCache: 0,
+    targetMode,
+    inputs: resolved.map((entry) => entry.input),
+    statuses: {},
+    outDir,
+    cacheRoot,
+  };
+  const written = [];
+  let invalidCache = 0;
+
+  function cachedCell(task, cacheKey) {
+    if (force) return undefined;
+    const path = cellFilePath(cacheRoot, {
+      plugin: task.artifact,
+      dsh: { version: task.version, composition: task.composition },
+      cacheKey,
+    });
+    if (!existsSync(path)) return undefined;
+    try {
+      const { kind, cell } = readCellAny(JSON.parse(readFileSync(path, 'utf8')));
+      if (kind !== 'v2' || cell.cacheKey !== cacheKey || cell.run.outcome !== 'completed' || !validateCell(cell).ok) {
+        invalidCache += 1;
+        return undefined;
+      }
+      writeCell(outDir, cell);
+      return { cell, path: cellFilePath(outDir, cell), cached: true };
+    } catch {
+      invalidCache += 1;
+      return undefined;
+    }
+  }
+
+  async function execute(task) {
+    const cacheKey = cacheKeyFor({ artifact: task.artifact, dshVersion: task.version, composition: task.composition, probeVersion: PROBE_VERSION });
+    const cached = cachedCell(task, cacheKey);
+    if (cached) return cached;
+    let environment;
+    let stub;
+    let observation;
+    try {
+      environment = await services.createProbeEnvironment({
+        backend,
+        workDir: cacheRoot,
+        dshDir: task.version !== 'desktop' ? join(cacheRoot, 'dsh', task.version) : undefined,
+      });
+      stub = useTools && task.composition !== 'web' ? await services.startStub({ environment, composition: task.composition }) : undefined;
+      const dsh = { kind: task.version === 'desktop' ? 'desktop' : 'npm', version: task.version, source: task.version === 'desktop' ? 'desktop' : 'npm', composition: task.composition };
+      observation = await services.probePackage({ artifact: task.artifact, dsh, environment, stub, tools: useTools, keep, composition: task.composition, audit: true });
+    } catch (error) {
+      observation = { outcome: 'error', error: publicError(error), entries: [], durationMs: 0 };
+      if (environment) await environment.destroy();
+    } finally {
+      if (stub?.server) stub.server.close();
+    }
+    let cell;
+    try {
+      cell = createCell({
+        artifact: task.artifact,
+        dsh: { version: task.version, source: task.version === 'desktop' ? 'desktop' : 'npm', composition: task.composition },
+        observation,
+        isolation: environment?.isolation || backend,
+        probeVersion: PROBE_VERSION,
+      });
+    } catch (error) {
+      // A cell that cannot be represented is an infrastructure error for that
+      // cell, not a reason to abort the remaining queue.
+      cell = createCell({
+        artifact: task.artifact,
+        dsh: { version: task.version, source: task.version === 'desktop' ? 'desktop' : 'npm', composition: task.composition },
+        observation: {
+          outcome: 'error',
+          error: { code: 'CELL_BUILD_FAILED', message: String(error?.message || error) },
+          entries: [],
+          durationMs: observation?.durationMs || 0,
+        },
+        isolation: environment?.isolation || backend,
+        probeVersion: PROBE_VERSION,
+      });
+    }
+    const path = writeCell(outDir, cell);
+    if (cell.run.outcome === 'completed' && cacheRoot !== outDir) writeCell(cacheRoot, cell);
+    return { cell, path, cached: false };
+  }
+
+  const queue = [...tasks];
+  const workers = Array.from({ length: Math.min(Math.max(1, concurrency), queue.length) }, async () => {
+    while (queue.length > 0) {
+      const result = await execute(queue.shift());
+      written.push(result);
+    }
+  });
+  await Promise.all(workers);
+  written.sort((a, b) => a.cell.plugin.name.localeCompare(b.cell.plugin.name)
+    || a.cell.plugin.resolvedVersion.localeCompare(b.cell.plugin.resolvedVersion, undefined, { numeric: true })
+    || a.cell.dsh.version.localeCompare(b.cell.dsh.version, undefined, { numeric: true })
+    || a.cell.dsh.composition.localeCompare(b.cell.dsh.composition));
+
+  for (const { cell, cached } of written) {
+    if (cached) summary.cached += 1;
+    if (cell.run.outcome === 'completed') {
+      summary.completed += 1;
+      summary.statuses[cell.result.status] = (summary.statuses[cell.result.status] || 0) + 1;
+    } else {
+      summary.errors += 1;
+    }
+  }
+  summary.invalidCache = invalidCache;
+  const manifest = buildManifest({
+    runId,
+    probeVersion: PROBE_VERSION,
+    inputs: {
+      targetMode,
+      targets: summary.inputs,
+      dshVersions,
+      compositions,
+      probeVersion: PROBE_VERSION,
+    },
+    artifacts: written.map(({ path }) => {
+      const bytes = readFileSync(path);
+      return { path: relative(outDir, path).replace(/\\/g, '/'), bytes: bytes.length, sha256: sha256(bytes) };
+    }),
+  });
+  manifest.targetMode = targetMode;
+  manifest.inputs = summary.inputs;
+  manifest.cellCount = written.length;
+  manifest.errorCount = summary.errors;
+  const manifestPath = `${outDir}/run-manifest.json`;
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+  summary.manifestPath = manifestPath;
+  return { cells: written.map((entry) => entry.cell), summary };
+}

package/src/matrix/sanitize.js

@@ -0,0 +1,42 @@
+import { ToolError } from '../shared/errors.js';
+import { validateCell } from './schema.js';
+
+export function sanitizeText(value) {
+  return String(value)
+    .replace(/token=[^\s&"']+/gi, 'token=<redacted>')
+    .replace(/(Bearer\s+)[A-Za-z0-9._~+/=-]+/gi, '$1<redacted>')
+    .replace(/(https?:\/\/)[^/\s:@]+:[^/\s@]+@/gi, '$1<redacted>@')
+    .replace(/((?:api[_-]?key|api[_-]?token|access[_-]?token|secret|password|npm_token|probe_api_key)\s*[:=]\s*["']?)[^\s,"'}]+/gi, '$1<redacted>')
+    .replace(/\/(Users|home)\/[^/\s]+/g, '/$1/<redacted>');
+}
+
+export function sanitizeCellForPublish(cell) {
+  if (cell?.schemaVersion !== 2 || cell.run?.outcome !== 'completed') {
+    throw new ToolError('EXPORT_INPUT_INVALID', 'Only completed v2 cells can be published.');
+  }
+  const validation = validateCell(cell);
+  if (!validation.ok) throw new ToolError('EXPORT_INPUT_INVALID', validation.errors.join('; '));
+  const publicCell = structuredClone(cell);
+  delete publicCell.plugin.path;
+  delete publicCell.installOutput;
+  delete publicCell.stdout;
+  delete publicCell.stderr;
+  delete publicCell.env;
+  if (publicCell.evidence) publicCell.evidence.note = sanitizeText(publicCell.evidence.note || '');
+  if (publicCell.reproduce?.command) publicCell.reproduce.command = sanitizeText(publicCell.reproduce.command);
+  return publicCell;
+}
+
+export function sanitizeForPublish(value) {
+  if (Array.isArray(value)) return value.map(sanitizeForPublish);
+  if (value && typeof value === 'object') {
+    if (value.schemaVersion === 2 && value.plugin && value.run) return sanitizeCellForPublish(value);
+    const output = {};
+    for (const [key, entry] of Object.entries(value)) {
+      if (['stdout', 'stderr', 'installOutput', 'env', 'cause', 'rawOutput'].includes(key)) continue;
+      output[key] = sanitizeForPublish(entry);
+    }
+    return output;
+  }
+  return typeof value === 'string' ? sanitizeText(value) : value;
+}

package/src/matrix/schema.js

@@ -0,0 +1,178 @@
+import { isPlainObject } from '../shared/validate.js';
+import { cacheKeyFor } from './cache.js';
+
+const HEX64 = /^[0-9a-f]{64}$/;
+const TRUST = new Set(['self-reported', 'verified', 'disputed']);
+const OUTCOME = new Set(['completed', 'error']);
+
+function object(value, path, errors) {
+  if (!isPlainObject(value)) errors.push(`${path} must be an object`);
+  return isPlainObject(value);
+}
+
+function string(value, path, errors, { allowEmpty = false } = {}) {
+  if (typeof value !== 'string' || (!allowEmpty && value.length === 0)) errors.push(`${path} must be a non-empty string`);
+}
+
+function date(value, path, errors) {
+  if (typeof value !== 'string' || !Number.isFinite(Date.parse(value))) errors.push(`${path} must be an ISO date`);
+}
+
+function verificationFields(run, probeVersion, errors) {
+  if (run.trust === 'verified') {
+    if (!object(run.verification, 'run.verification', errors)) return;
+    for (const field of ['workflow', 'runId', 'url']) string(run.verification[field], `run.verification.${field}`, errors);
+    if (run.verification.probeVersion !== probeVersion) errors.push('run.verification.probeVersion must match probe.version');
+  }
+  if (run.trust === 'disputed') {
+    if (!object(run.dispute, 'run.dispute', errors)) return;
+    string(run.dispute.reported, 'run.dispute.reported', errors);
+    string(run.dispute.observed, 'run.dispute.observed', errors);
+  }
+}
+
+export function validateCell(value) {
+  const errors = [];
+  if (!object(value, 'cell', errors)) return { ok: false, errors };
+  if (value.schemaVersion !== 2) errors.push('schemaVersion must be 2');
+  if (!HEX64.test(value.cacheKey || '')) errors.push('cacheKey must be a sha256 hex digest');
+
+  if (object(value.plugin, 'plugin', errors)) {
+    for (const field of ['name', 'requestedVersion', 'resolvedVersion']) string(value.plugin[field], `plugin.${field}`, errors);
+    if (typeof value.plugin.local !== 'boolean') errors.push('plugin.local must be boolean');
+    if (value.plugin.local === false && typeof value.plugin.integrity !== 'string') errors.push('registry integrity is required');
+    if (value.plugin.local === true && typeof value.plugin.sourceDigest !== 'string') errors.push('local sourceDigest is required');
+    // A plugin the host rejected was never loaded, so there is no loaded version
+    // to record. Requiring one here made createCell throw and aborted the whole
+    // matrix run on the first rejection.
+    if (value.run?.outcome === 'completed' && value.result?.status !== 'rejected-by-host') {
+      string(value.plugin.loadedVersion, 'plugin.loadedVersion', errors);
+    }
+    if (value.plugin.loadedVersion !== undefined && value.plugin.loadedVersion !== value.plugin.resolvedVersion) {
+      errors.push('plugin.loadedVersion must equal resolvedVersion');
+    }
+  }
+
+  if (object(value.dsh, 'dsh', errors)) {
+    string(value.dsh.version, 'dsh.version', errors);
+    string(value.dsh.source, 'dsh.source', errors);
+    if (!['headless', 'web'].includes(value.dsh.composition)) errors.push('dsh.composition must be headless or web');
+  }
+  if (object(value.probe, 'probe', errors)) {
+    string(value.probe.version, 'probe.version', errors);
+    string(value.probe.isolation, 'probe.isolation', errors);
+    if (object(value.probe.host, 'probe.host', errors)) {
+      string(value.probe.host.os, 'probe.host.os', errors);
+      string(value.probe.host.node, 'probe.host.node', errors);
+    }
+  }
+
+  if (object(value.run, 'run', errors)) {
+    if (!OUTCOME.has(value.run.outcome)) errors.push('run.outcome must be completed or error');
+    if (!TRUST.has(value.run.trust)) errors.push('run.trust is invalid');
+    date(value.run.at, 'run.at', errors);
+    if (!Number.isFinite(value.run.durationMs) || value.run.durationMs < 0) errors.push('run.durationMs must be non-negative');
+    verificationFields(value.run, value.probe?.version, errors);
+    if (value.run.outcome === 'error') {
+      if (value.result !== undefined) errors.push('error cells must not contain a plugin verdict');
+      if (object(value.run.error, 'run.error', errors)) {
+        string(value.run.error.code, 'run.error.code', errors);
+        string(value.run.error.message, 'run.error.message', errors);
+      }
+    }
+  }
+
+  if (value.run?.outcome === 'completed') {
+    if (object(value.result, 'result', errors)) {
+      string(value.result.status, 'result.status', errors);
+      if (!Array.isArray(value.result.entries)) errors.push('result.entries must be an array');
+      if (!Array.isArray(value.result.awaitedServices)) errors.push('result.awaitedServices must be an array');
+      string(value.result.clientHalf, 'result.clientHalf', errors);
+      if (value.result.composition !== value.dsh?.composition) errors.push('result.composition must match dsh.composition');
+    }
+    if (object(value.evidence, 'evidence', errors)) {
+      string(value.evidence.note, 'evidence.note', errors, { allowEmpty: true });
+      if (!HEX64.test(value.evidence.outputSha256 || '')) errors.push('evidence.outputSha256 must be a sha256 hex digest');
+    }
+    if (object(value.reproduce, 'reproduce', errors)) string(value.reproduce.command, 'reproduce.command', errors);
+  }
+
+  if (HEX64.test(value.cacheKey || '') && value.plugin?.resolvedVersion && value.dsh?.composition && value.probe?.version) {
+    try {
+      const expected = cacheKeyFor({
+        artifact: value.plugin,
+        dshVersion: value.dsh.version,
+        composition: value.dsh.composition,
+        probeVersion: value.probe.version,
+      });
+      if (expected !== value.cacheKey) errors.push('cacheKey does not match the artifact inputs');
+    } catch (error) {
+      errors.push(error.message);
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+export function validateIndex(value) {
+  const errors = [];
+  if (!object(value, 'index', errors)) return { ok: false, errors };
+  if (value.schemaVersion !== 2) errors.push('index.schemaVersion must be 2');
+  date(value.generatedAt, 'index.generatedAt', errors);
+  if (!Array.isArray(value.dshVersions) || value.dshVersions.some((entry) => typeof entry !== 'string')) errors.push('index.dshVersions must be strings');
+  if (!Array.isArray(value.plugins)) {
+    errors.push('index.plugins must be an array');
+    return { ok: false, errors };
+  }
+  for (const [pluginIndex, plugin] of value.plugins.entries()) {
+    string(plugin.name, `plugins[${pluginIndex}].name`, errors);
+    if (!Array.isArray(plugin.versions)) {
+      errors.push(`plugins[${pluginIndex}].versions must be an array`);
+      continue;
+    }
+    for (const [versionIndex, version] of plugin.versions.entries()) {
+      string(version.version, `plugins[${pluginIndex}].versions[${versionIndex}].version`, errors);
+      if (!Array.isArray(version.cells)) {
+        errors.push(`plugins[${pluginIndex}].versions[${versionIndex}].cells must be an array`);
+        continue;
+      }
+      for (const [cellIndex, cell] of version.cells.entries()) {
+        const path = `plugins[${pluginIndex}].versions[${versionIndex}].cells[${cellIndex}]`;
+        if (!HEX64.test(cell.cacheKey || '')) errors.push(`${path}.cacheKey is invalid`);
+        string(cell.dsh, `${path}.dsh`, errors);
+        if (!['headless', 'web'].includes(cell.composition)) errors.push(`${path}.composition is invalid`);
+        string(cell.status, `${path}.status`, errors);
+        string(cell.trust, `${path}.trust`, errors);
+        date(cell.at, `${path}.at`, errors);
+        if (!Array.isArray(cell.toolsAdded)) errors.push(`${path}.toolsAdded must be an array`);
+        string(cell.reproduce, `${path}.reproduce`, errors);
+      }
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+export function validateManifest(value) {
+  const errors = [];
+  if (!object(value, 'manifest', errors)) return { ok: false, errors };
+  if (value.schemaVersion !== 2) errors.push('manifest.schemaVersion must be 2');
+  string(value.runId, 'manifest.runId', errors);
+  date(value.generatedAt, 'manifest.generatedAt', errors);
+  string(value.probeVersion, 'manifest.probeVersion', errors);
+  if (!HEX64.test(value.inputsSha256 || '')) errors.push('manifest.inputsSha256 is invalid');
+  if (!Array.isArray(value.artifacts)) {
+    errors.push('manifest.artifacts must be an array');
+    return { ok: false, errors };
+  }
+  const paths = new Set();
+  for (const [index, artifact] of value.artifacts.entries()) {
+    const path = artifact.path;
+    if (typeof path !== 'string' || path.startsWith('/') || path.includes('\\') || path === '..' || path.startsWith('../') || path.includes('/../') || path.includes('\0')) {
+      errors.push(`artifacts[${index}].path is not a safe relative path`);
+    }
+    if (paths.has(path)) errors.push(`artifacts[${index}].path is duplicated`);
+    paths.add(path);
+    if (!Number.isInteger(artifact.bytes) || artifact.bytes < 0) errors.push(`artifacts[${index}].bytes must be non-negative`);
+    if (!HEX64.test(artifact.sha256 || '')) errors.push(`artifacts[${index}].sha256 is invalid`);
+  }
+  return { ok: errors.length === 0, errors };
+}

package/src/matrix/site.js

@@ -0,0 +1,61 @@
+const COLORS = {
+  active: '#1a7f37',
+  'inactive-error': '#cf222e',
+  'rejected-by-host': '#cf222e',
+  'awaiting-service': '#bf8700',
+  'install-failed': '#8250df',
+  'boot-failed': '#cf222e',
+  'template-failed': '#57606a',
+};
+
+export function escapeHtml(value) {
+  return String(value).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+}
+
+function renderCell(cell) {
+  const status = escapeHtml(cell.status);
+  const note = cell.note || cell.title;
+  const title = escapeHtml(note || cell.status);
+  const color = COLORS[cell.status] || '#57606a';
+  const tools = cell.toolsAdded?.length ? `<div class="tools">+${cell.toolsAdded.length} tools</div>` : '';
+  const services = cell.awaitedServices?.length ? `<div class="meta">needs ${escapeHtml(cell.awaitedServices.join(', '))}</div>` : '';
+  const detail = note ? `<div class="note">${escapeHtml(note)}</div>` : '';
+  return `<div class="observation"><span class="pill" style="background:${color}" title="${title}">${status}</span>${tools}${services}<div class="meta">${escapeHtml(cell.composition)} · ${escapeHtml(cell.trust)}</div>${detail}</div>`;
+}
+
+export function renderSite(index) {
+  const dshVersions = index.dshVersions || [];
+  const plugins = index.plugins || [];
+  const cells = plugins.flatMap((plugin) => plugin.versions.flatMap((version) => version.cells));
+  const tally = {};
+  for (const cell of cells) tally[cell.status] = (tally[cell.status] || 0) + 1;
+  const rows = plugins.map((plugin) => plugin.versions.map((version) => {
+    const columns = dshVersions.map((dsh) => {
+      const observations = version.cells.filter((cell) => cell.dsh === dsh)
+        .sort((a, b) => a.composition.localeCompare(b.composition) || a.at.localeCompare(b.at));
+      return `<td>${observations.length ? observations.map(renderCell).join('') : '<span class="none">—</span>'}</td>`;
+    }).join('');
+    return `<tr><th>${escapeHtml(plugin.name)}<div class="ver">${escapeHtml(version.version)}</div></th>${columns}</tr>`;
+  }).join('\n')).join('\n');
+  const source = index.source?.runId || index.sourceRunId || 'unknown';
+  return [
+    '<!doctype html>',
+    '<html lang="en"><head><meta charset="utf-8">',
+    '<title>DSH plugin compatibility matrix</title>',
+    '<style>',
+    'body{font:14px/1.5 ui-sans-serif,system-ui,-apple-system,sans-serif;margin:2rem;color:#1f2328}',
+    'h1{font-size:1.4rem;margin:0 0 .25rem}.sub{color:#57606a;margin-bottom:1.5rem}',
+    'table{border-collapse:collapse}th,td{border:1px solid #d0d7de;padding:.5rem .75rem;text-align:left;vertical-align:top}',
+    'th{background:#f6f8fa;font-weight:600}.ver{color:#57606a;font-weight:400;font-size:.8rem}',
+    '.observation{margin-bottom:.65rem}.pill{display:inline-block;color:#fff;border-radius:999px;padding:.1rem .5rem;font-size:.75rem}',
+    '.tools{color:#1a7f37;font-size:.75rem;margin-top:.25rem}.meta{color:#8c959f;font-size:.7rem;margin-top:.2rem}',
+    '.note{margin-top:1rem;color:#57606a;font-size:.78rem;max-width:60rem}.none{color:#d0d7de;text-align:center}',
+    '</style></head><body>',
+    '<h1>DSH plugin compatibility matrix</h1>',
+    `<div class="sub">${cells.length} cells · ${plugins.length} plugins · ${dshVersions.length} DSH versions · generated ${escapeHtml(index.generatedAt)} · source ${escapeHtml(source)}</div>`,
+    `<table><thead><tr><th>Plugin</th>${dshVersions.map((version) => `<th>${escapeHtml(version)}</th>`).join('')}</tr></thead><tbody>${rows}</tbody></table>`,
+    '<div class="note"><strong>Read "awaiting service" as untested, not as broken.</strong> Each composition is shown separately; no best result is selected across headless and web. Host-half probes do not prove browser client-half behavior or security.</div>',
+    `<div class="note"><strong>Statuses:</strong> ${Object.entries(tally).sort((a, b) => b[1] - a[1]).map(([status, count]) => `${escapeHtml(status)} ${count}`).join(' · ')}</div>`,
+    '</body></html>',
+  ].join('\n');
+}

package/src/matrix/sync.js

@@ -0,0 +1,72 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { ToolError } from '../shared/errors.js';
+import { sha256 } from '../shared/hash.js';
+import { validateManifest } from './schema.js';
+import { verifyPublicArtifact } from './export.js';
+
+const MAX_FILES = 10000;
+const MAX_ARTIFACT_BYTES = 16 * 1024 * 1024;
+
+function safeRelative(path) {
+  return typeof path === 'string' && !path.startsWith('/') && !path.includes('\\') && path !== '..' && !path.startsWith('../') && !path.includes('/../') && !path.includes('\0');
+}
+
+export async function syncMatrix({ source, outDir, fetchImpl = fetch }) {
+  if (!source) throw new ToolError('MATRIX_SOURCE_REQUIRED', 'An explicit matrix source is required.');
+  if (!outDir) throw new ToolError('MATRIX_OUTPUT_REQUIRED', 'An explicit sync output directory is required.');
+  const remote = /^https:\/\//.test(source);
+  const base = remote ? new URL(source.endsWith('/') ? source : source + '/') : realpathSync(source);
+  async function readSource(path) {
+    if (!safeRelative(path)) throw new ToolError('MANIFEST_INVALID', 'The source contains an unsafe artifact path.');
+    if (remote) {
+      const url = new URL(path, base);
+      if (url.protocol !== 'https:') throw new ToolError('MATRIX_SOURCE_UNSUPPORTED', 'Only HTTPS matrix sources are supported.');
+      const response = await fetchImpl(url, { redirect: 'error', signal: AbortSignal.timeout(10000) });
+      if (!response.ok) throw new ToolError('MATRIX_SOURCE_UNAVAILABLE', `The matrix source returned HTTP ${response.status}.`);
+      const bytes = Buffer.from(await response.arrayBuffer());
+      if (bytes.length > MAX_ARTIFACT_BYTES) throw new ToolError('ARTIFACT_TOO_LARGE', 'A matrix artifact exceeds the size limit.');
+      return bytes;
+    }
+    const pathOnDisk = realpathSync(resolve(base, path));
+    if (pathOnDisk !== base && !pathOnDisk.startsWith(base + sep)) throw new ToolError('MANIFEST_INVALID', 'A source file escapes the source directory.');
+    const bytes = readFileSync(pathOnDisk);
+    if (bytes.length > MAX_ARTIFACT_BYTES) throw new ToolError('ARTIFACT_TOO_LARGE', 'A matrix artifact exceeds the size limit.');
+    return bytes;
+  }
+
+  const manifest = JSON.parse((await readSource('manifest.json')).toString('utf8'));
+  const validation = validateManifest(manifest);
+  if (!validation.ok) throw new ToolError('MANIFEST_INVALID', validation.errors.join('; '));
+  if (manifest.artifacts.length > MAX_FILES) throw new ToolError('ARTIFACT_TOO_LARGE', 'The matrix declares too many files.');
+  const parent = dirname(outDir);
+  mkdirSync(parent, { recursive: true });
+  const staging = mkdtempSync(join(parent, '.sync-'));
+  try {
+    for (const artifact of manifest.artifacts) {
+      const bytes = await readSource(artifact.path);
+      if (bytes.length !== artifact.bytes || sha256(bytes) !== artifact.sha256) {
+        throw new ToolError('ARTIFACT_INTEGRITY_MISMATCH', `Artifact integrity mismatch: ${artifact.path}`);
+      }
+      const destination = join(staging, artifact.path);
+      mkdirSync(dirname(destination), { recursive: true });
+      writeFileSync(destination, bytes);
+    }
+    writeFileSync(join(staging, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
+    const verification = await verifyPublicArtifact({ dir: staging });
+    if (!verification.ok) throw new ToolError('ARTIFACT_INTEGRITY_MISMATCH', verification.errors.join('; '));
+    const backup = `${outDir}.backup-${Date.now()}`;
+    if (existsSync(outDir)) renameSync(outDir, backup);
+    try {
+      renameSync(staging, outDir);
+      rmSync(backup, { recursive: true, force: true });
+    } catch (error) {
+      if (existsSync(backup)) renameSync(backup, outDir);
+      throw error;
+    }
+    return { manifest, filesWritten: manifest.artifacts.length + 1 };
+  } catch (error) {
+    rmSync(staging, { recursive: true, force: true });
+    throw error;
+  }
+}