@malmhq/intermesh-cli 0.1.0

package/dist/generation/scripts/validate-source-brief.mjs

@@ -0,0 +1,220 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { basename, dirname, resolve } from 'node:path';
+
+function fail(message) {
+  throw new TypeError(message);
+}
+
+function record(value, name) {
+  if (typeof value !== 'object' || value === null || Array.isArray(value))
+    fail(`${name} is invalid`);
+  return value;
+}
+
+function exactKeys(value, expected, name) {
+  const actual = Object.keys(value).sort();
+  if (actual.join(',') !== [...expected].sort().join(',')) fail(`${name} has unexpected fields`);
+}
+
+function text(value, name) {
+  if (typeof value !== 'string' || value.trim() === '') fail(`${name} is invalid`);
+  return value;
+}
+
+function operation(value, name, strict = true) {
+  const item = record(value, name);
+  if (strict) exactKeys(item, ['method', 'path'], name);
+  return { method: text(item.method, `${name}.method`), path: text(item.path, `${name}.path`) };
+}
+
+function selectedOperation(value, name) {
+  const item = record(value, name);
+  exactKeys(item, ['method', 'path', 'effect'], name);
+  return {
+    ...operation(item, name, false),
+    effect: text(item.effect, `${name}.effect`),
+  };
+}
+
+function hash(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (typeof value === 'object' && value !== null) {
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`)
+      .join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+export async function validateSourceBrief(
+  requestPath,
+  briefPath,
+  inventoryPath,
+  expectedRequestHash,
+) {
+  const requestBytes = await readFile(requestPath);
+  if (hash(requestBytes) !== expectedRequestHash) fail('Run request hash does not match');
+  const request = record(JSON.parse(requestBytes.toString('utf8')), 'Run request');
+  const workspace = dirname(dirname(resolve(requestPath)));
+  const inventory = record(
+    JSON.parse(await readFile(inventoryPath, 'utf8')),
+    'Operation inventory',
+  );
+  const brief = record(JSON.parse(await readFile(briefPath, 'utf8')), 'Source brief');
+  const inventoryHash = hash(canonical(inventory));
+  if (request.operation_inventory_hash !== inventoryHash)
+    fail('Operation inventory hash does not match the run request');
+  if (
+    resolve(workspace, text(request.operation_inventory, 'operation_inventory')) !==
+    resolve(inventoryPath)
+  )
+    fail('Run request points to a different operation inventory');
+  const openApiBytes = await readFile(resolve(workspace, text(request.openapi, 'openapi')));
+  const openApiHash = hash(openApiBytes);
+  if (request.openapi_hash !== openApiHash || inventory.source_hash !== openApiHash)
+    fail('OpenAPI hash does not match the operation inventory');
+  const profileBytes = await readFile(
+    resolve(workspace, text(request.customer_profile, 'customer_profile')),
+  );
+  if (request.customer_profile_hash !== hash(profileBytes))
+    fail('Customer profile hash does not match the run request');
+  const profile = record(JSON.parse(profileBytes.toString('utf8')), 'Customer profile');
+  if (!Array.isArray(profile.operations) || profile.operations.length === 0)
+    fail('Customer profile has no operations');
+  const approved = new Map();
+  for (const [index, item] of profile.operations.entries()) {
+    const value = selectedOperation(item, `customer_profile.operations[${index}]`);
+    const key = `${value.method} ${value.path}`;
+    if (approved.has(key)) fail(`Customer profile operation is duplicated: ${key}`);
+    approved.set(key, value.effect);
+  }
+
+  if (!['1.0.0', '2.0.0'].includes(brief.schema_version))
+    fail('Source brief schema version is invalid');
+  exactKeys(
+    brief,
+    [
+      'schema_version',
+      'operation_inventory_hash',
+      'capabilities',
+      'excluded_operations',
+      'questions',
+    ],
+    'Source brief',
+  );
+  if (brief.operation_inventory_hash !== inventoryHash)
+    fail('Source brief does not reference the trusted operation inventory');
+
+  if (!Array.isArray(request.selected_operations) || request.selected_operations.length === 0)
+    fail('Run request has no selected operations');
+  const selected = new Set();
+  for (const [index, item] of request.selected_operations.entries()) {
+    const value = selectedOperation(item, `selected_operations[${index}]`);
+    const key = `${value.method} ${value.path}`;
+    if (selected.has(key)) fail(`Selected operation is duplicated: ${key}`);
+    if (approved.get(key) !== value.effect)
+      fail(`Selected operation is not approved by the customer profile: ${key}`);
+    selected.add(key);
+  }
+  if (selected.size !== approved.size)
+    fail('Selected operations do not match the customer profile');
+  const available = new Set(
+    Array.isArray(inventory.operations)
+      ? inventory.operations.map((item, index) => {
+          const value = operation(item, `inventory.operations[${index}]`, false);
+          return `${value.method} ${value.path}`;
+        })
+      : fail('Operation inventory has no operations'),
+  );
+  if (!Array.isArray(request.context) || request.context.length === 0)
+    fail('Run request has no context');
+  const documents = new Map();
+  for (const [index, item] of request.context.entries()) {
+    const context = record(item, `context[${index}]`);
+    exactKeys(context, ['path', 'hash'], `context[${index}]`);
+    const path = resolve(workspace, text(context.path, `context[${index}].path`));
+    const content = await readFile(path, 'utf8');
+    if (hash(content) !== context.hash) fail(`Context hash does not match: ${path}`);
+    documents.set(basename(path), content);
+  }
+
+  const covered = new Set();
+  const commands = new Set();
+  if (!Array.isArray(brief.capabilities)) fail('Source brief capabilities are invalid');
+  for (const [index, value] of brief.capabilities.entries()) {
+    const capability = record(value, `capabilities[${index}]`);
+    const capabilityKeys = [
+      'operation',
+      'effect',
+      'business_purpose',
+      'proposed_command',
+      'context_evidence',
+      ...(brief.schema_version === '2.0.0' && capability.response_pattern !== undefined
+        ? ['response_pattern']
+        : []),
+    ];
+    exactKeys(capability, capabilityKeys, `capabilities[${index}]`);
+    const ref = operation(capability.operation, `capabilities[${index}].operation`);
+    const key = `${ref.method} ${ref.path}`;
+    if (!available.has(key) || !selected.has(key))
+      fail(`Source brief references an unselected operation: ${key}`);
+    if (capability.effect !== approved.get(key))
+      fail(`Source brief effect does not match the customer profile: ${key}`);
+    if (covered.has(key)) fail(`Source brief operation is duplicated: ${key}`);
+    text(capability.business_purpose, `capabilities[${index}].business_purpose`);
+    const command = text(capability.proposed_command, `capabilities[${index}].proposed_command`);
+    if (commands.has(command)) fail(`Source brief command is duplicated: ${command}`);
+    commands.add(command);
+    if (capability.response_pattern !== undefined && capability.response_pattern !== 'file')
+      fail(`capabilities[${index}].response_pattern must be file`);
+    if (!Array.isArray(capability.context_evidence) || capability.context_evidence.length === 0)
+      fail(`capabilities[${index}].context_evidence is invalid`);
+    for (const [evidenceIndex, evidenceValue] of capability.context_evidence.entries()) {
+      const evidence = record(evidenceValue, `context_evidence[${evidenceIndex}]`);
+      exactKeys(evidence, ['document', 'location', 'excerpt'], 'context_evidence');
+      const document = text(evidence.document, 'context_evidence.document');
+      text(evidence.location, 'context_evidence.location');
+      const excerpt = text(evidence.excerpt, 'context_evidence.excerpt');
+      if (excerpt.length > 500) fail('Context evidence excerpt is too long');
+      const content = documents.get(document);
+      if (content === undefined)
+        fail(`Source brief references an unknown context document: ${document}`);
+      if (!content.includes(excerpt)) fail(`Context evidence was not found in ${document}`);
+    }
+    covered.add(key);
+  }
+  if (!Array.isArray(brief.excluded_operations)) fail('Source brief exclusions are invalid');
+  for (const [index, value] of brief.excluded_operations.entries()) {
+    const exclusion = record(value, `excluded_operations[${index}]`);
+    exactKeys(exclusion, ['operation', 'reason'], `excluded_operations[${index}]`);
+    const ref = operation(exclusion.operation, `excluded_operations[${index}].operation`);
+    const key = `${ref.method} ${ref.path}`;
+    if (!selected.has(key)) fail(`Source brief excludes an unselected operation: ${key}`);
+    if (covered.has(key)) fail(`Source brief operation is duplicated: ${key}`);
+    text(exclusion.reason, `excluded_operations[${index}].reason`);
+    covered.add(key);
+  }
+  if (brief.excluded_operations.length > 0)
+    fail('Source brief could not support every selected operation');
+  if (covered.size !== selected.size)
+    fail('Source brief does not account for every selected operation');
+  if (!Array.isArray(brief.questions) || brief.questions.some((value) => typeof value !== 'string'))
+    fail('Source brief questions are invalid');
+  if (brief.questions.length > 0) fail('Source brief has unresolved questions');
+}
+
+if (
+  globalThis.__INTERMESH_BUNDLED__ !== true &&
+  process.argv[1] === new URL(import.meta.url).pathname
+) {
+  const [requestPath, briefPath, inventoryPath, expectedRequestHash] = process.argv.slice(2);
+  if (!requestPath || !briefPath || !inventoryPath || !expectedRequestHash)
+    fail('Expected request, brief, inventory and request hash');
+  await validateSourceBrief(requestPath, briefPath, inventoryPath, expectedRequestHash);
+}

package/dist/generation/scripts/verify-package.mjs

@@ -0,0 +1,365 @@
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { promisify } from 'node:util';
+
+const execute = promisify(execFile);
+function fail(message) {
+  throw new TypeError(message);
+}
+
+function record(value, name) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail(`${name} is invalid`);
+  return value;
+}
+
+function text(value, name) {
+  if (typeof value !== 'string' || value.trim() === '') fail(`${name} is invalid`);
+  return value;
+}
+
+function operation(value, name) {
+  const item = record(value, name);
+  return {
+    method: text(item.method, `${name}.method`),
+    path: text(item.path, `${name}.path`),
+    effect: text(item.effect, `${name}.effect`),
+  };
+}
+
+function validateManifest(value, selected) {
+  const manifest = record(value, 'Capability manifest');
+  if (!Array.isArray(manifest.commands) || !Array.isArray(manifest.excluded))
+    fail('Capability manifest is invalid');
+  if (manifest.excluded.length !== 0) fail('Capability manifest has excluded approved operations');
+  const approved = new Map(
+    selected.map((item, index) => {
+      const entry = operation(item, `selected_operations[${index}]`);
+      return [`${entry.method} ${entry.path}`, entry.effect];
+    }),
+  );
+  const commands = new Set();
+  const covered = new Set();
+  for (const [index, value] of manifest.commands.entries()) {
+    const item = record(value, `commands[${index}]`);
+    const command = text(item.command, `commands[${index}].command`);
+    const entry = operation(item, `commands[${index}]`);
+    const key = `${entry.method} ${entry.path}`;
+    if (commands.has(command)) fail(`Capability command is duplicated: ${command}`);
+    if (covered.has(key)) fail(`Capability operation is duplicated: ${key}`);
+    if (approved.get(key) !== entry.effect) fail(`Capability is not approved: ${key}`);
+    commands.add(command);
+    covered.add(key);
+  }
+  if (covered.size !== approved.size)
+    fail('Capability manifest does not cover every approved operation');
+  return [...commands];
+}
+
+function escapePattern(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+}
+
+function validateSkillFrontmatter(skill) {
+  const normalized = skill.replaceAll('\r\n', '\n');
+  const match = /^---\n([\s\S]*?)\n---(?:\n|$)/u.exec(normalized);
+  if (!match) fail('Skill must start with YAML frontmatter');
+  const fields = new Map();
+  for (const line of match[1].split('\n')) {
+    const field = /^([a-z][a-z0-9_-]*):\s*(.+)$/iu.exec(line);
+    if (field) fields.set(field[1].toLowerCase(), field[2].trim());
+  }
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(fields.get('name') ?? ''))
+    fail('Skill frontmatter name is invalid');
+  if (!fields.get('description')) fail('Skill frontmatter description is invalid');
+  return { name: fields.get('name'), description: fields.get('description') };
+}
+
+function skillLocalLinks(skill) {
+  return [...skill.matchAll(/\[[^\]]+\]\(([^)]+)\)/gu)]
+    .map((match) => match[1].trim().replace(/^<|>$/gu, '').split(/\s+/u)[0])
+    .filter((target) => !/^(?:https?:|mailto:|#)/iu.test(target));
+}
+
+function validateReadmeCommands(readme, binary, commands) {
+  const escapedBinary = escapePattern(binary);
+  const invocations = [
+    ...readme.matchAll(/`([^`\n]+)`/gu),
+    ...readme.matchAll(new RegExp(`^\\s*(?:\\$\\s*)?(${escapedBinary}(?:\\s+.*)?)$`, 'gmu')),
+  ]
+    .map((match) => match[1].trim())
+    .filter((value) => value === binary || value.startsWith(`${binary} `));
+  const allowed = ['', '--help', 'setup', 'login', 'status', 'update', 'logout', ...commands];
+  for (const invocation of invocations) {
+    const argumentsText = invocation.slice(binary.length).trim();
+    if (
+      !allowed.some(
+        (command) => argumentsText === command || argumentsText.startsWith(`${command} `),
+      )
+    )
+      fail(`README documents an unknown command: ${invocation}`);
+  }
+}
+
+export function validateDocumentationBoundary({
+  readme,
+  skills,
+  contributing,
+  binary,
+  packageName,
+  commands,
+}) {
+  for (const [value, name] of [
+    [readme, 'README'],
+    [contributing, 'CONTRIBUTING'],
+    [binary, 'Binary'],
+    [packageName, 'Package name'],
+  ])
+    text(value, name);
+  if (!Array.isArray(skills) || skills.length === 0) fail('Generated Skill suite is invalid');
+  for (const [index, skill] of skills.entries()) {
+    const item = record(skill, `Skill ${index}`);
+    text(item.path, `Skill ${index} path`);
+    text(item.content, `Skill ${index} content`);
+  }
+  if (!Array.isArray(commands) || commands.some((command) => typeof command !== 'string'))
+    fail('Generated commands are invalid');
+  if (
+    /\bpnpm\s+(?:install|check|test|build|pack|mock:run)\b|\.generation(?:\/|\b)|\.opencode(?:\/|\b)|\bmock[- ]server\b|\bnode\s+dist\/index\.js\b|\/tmp\//iu.test(
+      readme,
+    )
+  )
+    fail('README contains maintainer or generation instructions');
+  for (const required of [
+    `npm install --global ${packageName}`,
+    `${binary} login`,
+    `${binary} setup`,
+    `${binary} status`,
+    `${binary} update`,
+    `${binary} logout`,
+  ])
+    if (!readme.includes(required)) fail(`README is missing customer guidance: ${required}`);
+  if (commands.length > 0 && !commands.some((command) => readme.includes(`${binary} ${command}`)))
+    fail('README must document a generated command');
+  validateReadmeCommands(readme, binary, commands);
+  if (
+    /replace this|unfinished|\bTBD\b|\bTODO\b|__[A-Z0-9_]+__/iu.test(
+      `${readme}\n${skills.map((skill) => skill.content).join('\n')}`,
+    )
+  )
+    fail('Customer documentation contains unfinished placeholders');
+  for (const skill of skills) validateSkillFrontmatter(skill.content);
+  for (const command of ['check', 'test', 'build', 'pack', 'mock:run'])
+    if (!contributing.includes(`pnpm ${command}`))
+      fail(`CONTRIBUTING is missing maintainer command: pnpm ${command}`);
+  return skills.flatMap((skill) =>
+    skillLocalLinks(skill.content).map((target) => ({ source: skill.path, target })),
+  );
+}
+
+async function readSkillSuite(packagePath, binary) {
+  const skillsRoot = join(packagePath, 'skills');
+  const entries = await readdir(skillsRoot, { withFileTypes: true }).catch(() =>
+    fail('Generated package has no Skill suite'),
+  );
+  const skills = [];
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    if (!entry.isDirectory()) fail('Skill suite contains a file outside a Skill folder');
+    const path = `skills/${entry.name}/SKILL.md`;
+    const content = await readFile(join(packagePath, path), 'utf8').catch(() =>
+      fail(`Skill is missing its entrypoint: ${entry.name}`),
+    );
+    const frontmatter = validateSkillFrontmatter(content);
+    if (frontmatter.name !== entry.name) fail(`Skill folder and name do not match: ${entry.name}`);
+    skills.push({
+      name: entry.name,
+      path,
+      content,
+      description: frontmatter.description,
+      role:
+        entry.name === `${binary}-cli-management`
+          ? 'management'
+          : entry.name === `${binary}-workflow`
+            ? 'workflow'
+            : 'focused',
+    });
+  }
+  const management = skills.filter((skill) => skill.role === 'management');
+  const workflow = skills.filter((skill) => skill.role === 'workflow');
+  if (management.length !== 1) fail(`Skill suite must contain ${binary}-cli-management`);
+  if (workflow.length !== 1) fail(`Skill suite must contain ${binary}-workflow`);
+  if (new Set(skills.map((skill) => skill.description)).size !== skills.length)
+    fail('Skill descriptions must be distinct');
+  for (const focused of skills.filter((skill) => skill.role === 'focused')) {
+    const expected = `../${focused.name}/SKILL.md`;
+    if (!skillLocalLinks(workflow[0].content).some((link) => link.split('#')[0] === expected))
+      fail(`Workflow Skill does not route focused Skill: ${focused.name}`);
+  }
+  return skills;
+}
+
+async function run(command, args, options) {
+  await execute(command, args, { ...options, timeout: 120_000, maxBuffer: 10 * 1024 * 1024 });
+}
+
+export async function verifyPackage(packageDirectory, requestPath, reportPath) {
+  const offlineArgs = [];
+  const packagePath = resolve(packageDirectory);
+  const request = record(JSON.parse(await readFile(requestPath, 'utf8')), 'Run request');
+  if (!Array.isArray(request.selected_operations) || request.selected_operations.length === 0)
+    fail('Run request has no selected operations');
+  const commands = validateManifest(
+    JSON.parse(await readFile(join(packagePath, 'capabilities.json'), 'utf8')),
+    request.selected_operations,
+  );
+  const packageDocument = record(
+    JSON.parse(await readFile(join(packagePath, 'package.json'), 'utf8')),
+    'Package',
+  );
+  if (packageDocument.private !== true) fail('Generated package must remain private');
+  const binaries = record(packageDocument.bin, 'Package binaries');
+  const binaryNames = Object.keys(binaries);
+  if (binaryNames.length !== 1 || typeof binaries[binaryNames[0]] !== 'string')
+    fail('Generated package must expose one binary');
+  const binary = binaryNames[0];
+  const skills = await readSkillSuite(packagePath, binary);
+  const skillLinks = validateDocumentationBoundary({
+    readme: await readFile(join(packagePath, 'README.md'), 'utf8'),
+    skills,
+    contributing: await readFile(join(packagePath, 'CONTRIBUTING.md'), 'utf8'),
+    binary,
+    packageName: text(packageDocument.name, 'Package name'),
+    commands,
+  });
+  const linkedFiles = [];
+  for (const link of skillLinks) {
+    let decoded;
+    try {
+      decoded = decodeURIComponent(link.target.split('#')[0]);
+    } catch {
+      fail(`Skill has an invalid local link: ${link.target}`);
+    }
+    const linkedPath = resolve(packagePath, dirname(link.source), decoded);
+    if (linkedPath === packagePath || !linkedPath.startsWith(`${packagePath}${sep}`))
+      fail(`Skill local link leaves the package: ${link.target}`);
+    await readFile(linkedPath).catch(() => fail(`Skill local link is missing: ${link.target}`));
+    linkedFiles.push(relative(packagePath, linkedPath).replaceAll(sep, '/'));
+  }
+  const excludedVariables = new Set(['OPENROUTER_API_KEY', 'DEEPSEEK_API_KEY']);
+  if (typeof request.customer_profile === 'string') {
+    const workspace = dirname(dirname(resolve(requestPath)));
+    const profile = record(
+      JSON.parse(await readFile(resolve(workspace, request.customer_profile), 'utf8')),
+      'Customer profile',
+    );
+    const api = record(profile.api, 'Customer profile API');
+    const auth = record(api.auth, 'Customer profile authentication');
+    excludedVariables.add(text(auth.environment_variable, 'Authentication variable'));
+  }
+  const environment = Object.fromEntries(
+    Object.entries(process.env).filter(([name]) => !excludedVariables.has(name)),
+  );
+  const installArgs = ['install', ...offlineArgs, '--frozen-lockfile', '--ignore-scripts'];
+  await run('pnpm', installArgs, {
+    cwd: packagePath,
+    env: environment,
+  });
+  const checks = [`pnpm ${installArgs.join(' ')}`];
+  for (const name of ['check', 'test', 'build']) {
+    await run('pnpm', [name], { cwd: packagePath, env: environment });
+    checks.push(`pnpm ${name}`);
+  }
+  const tarball = resolve(dirname(reportPath), 'candidate.tgz');
+  const packed = await execute('pnpm', ['pack', '--out', tarball, '--json'], {
+    cwd: packagePath,
+    env: environment,
+    timeout: 120_000,
+    maxBuffer: 10 * 1024 * 1024,
+  });
+  const pack = record(JSON.parse(packed.stdout), 'Pack result');
+  if (!Array.isArray(pack.files)) fail('Pack result has no files');
+  const paths = pack.files.map((value, index) =>
+    text(record(value, `Pack file ${index}`).path, `Pack file ${index}.path`),
+  );
+  for (const required of ['README.md', 'capabilities.json', 'dist/index.js'])
+    if (!paths.includes(required)) fail(`Packed candidate is missing ${required}`);
+  for (const skill of skills)
+    if (!paths.includes(skill.path)) fail(`Packed candidate is missing ${skill.path}`);
+  for (const linkedFile of linkedFiles)
+    if (!paths.includes(linkedFile)) fail(`Packed candidate is missing Skill link ${linkedFile}`);
+  if (
+    paths.some((path) =>
+      /^(?:\.generation|\.opencode|inputs|node_modules|\.env|src|test|mock|CONTRIBUTING\.md)/u.test(
+        path,
+      ),
+    )
+  )
+    fail('Packed candidate contains development or generation files');
+  const installation = await mkdtemp(join(dirname(reportPath), 'candidate-install-'));
+  try {
+    await writeFile(join(installation, 'package.json'), '{"private":true}');
+    await run('pnpm', ['add', ...offlineArgs, '--ignore-scripts', tarball], {
+      cwd: installation,
+      env: environment,
+    });
+    const executable = join(installation, 'node_modules/.bin', binary);
+    for (const args of [
+      ['--help'],
+      ['setup', '--help'],
+      ['login', '--help'],
+      ['status', '--help'],
+      ['update', '--help'],
+      ['logout', '--help'],
+      ...commands.map((command) => [...command.split(/\s+/u), '--help']),
+    ])
+      await run(executable, args, { cwd: installation, env: environment });
+  } finally {
+    await rm(installation, { recursive: true, force: true });
+  }
+  const tarballHash = createHash('sha256')
+    .update(await readFile(tarball))
+    .digest('hex');
+  const report = {
+    passed: true,
+    commands,
+    skills: await Promise.all(
+      skills.map(async (skill) => ({
+        name: skill.name,
+        path: skill.path,
+        sha256: createHash('sha256')
+          .update(await readFile(join(packagePath, skill.path)))
+          .digest('hex'),
+        role: skill.role,
+      })),
+    ),
+    checks: [...checks, 'pnpm pack', 'clean install', 'installed help'],
+    tarball: 'candidate.tgz',
+    tarball_sha256: tarballHash,
+  };
+  await writeFile(reportPath, JSON.stringify(report, null, 2), { flag: 'wx' });
+  return report;
+}
+
+if (
+  globalThis.__INTERMESH_BUNDLED__ !== true &&
+  process.argv[1] === new URL(import.meta.url).pathname
+) {
+  const [packageDirectory, requestPath, reportPath] = process.argv.slice(2);
+  try {
+    if (!packageDirectory || !requestPath || !reportPath)
+      fail('Expected package, run request and report paths');
+    await verifyPackage(packageDirectory, requestPath, reportPath);
+  } catch (error) {
+    const finding = error instanceof Error ? error.message : 'Candidate verification failed';
+    if (reportPath) {
+      await writeFile(
+        reportPath,
+        `${JSON.stringify({ passed: false, step: 'candidate_verification', finding }, null, 2)}\n`,
+        { flag: 'wx' },
+      ).catch(() => {});
+    }
+    console.error(finding);
+    process.exitCode = 1;
+  }
+}

package/dist/generation/templates/npm-cli/CONTRIBUTING.md

@@ -0,0 +1,20 @@
+# Development
+
+Generation and automated tests remain offline and use synthetic fixtures.
+
+```bash
+pnpm install --frozen-lockfile
+pnpm check
+pnpm test
+pnpm build
+pnpm mock:run -- node dist/index.js <command>
+pnpm pack
+```
+
+`mock:run` starts the synthetic API, runs one command and stops the API. The loopback-only
+`--base-url` option never sends a stored token. Human-controlled live verification happens only
+after the exact tarball has passed offline checks and clean installation.
+
+Define stable error codes, messages, recovery hints, safe details, retryability and exit codes in
+`src/shared/errors.ts`. Command and transport code must throw `new CliError(cliErrors.<name>)`
+instead of defining error copy or exit behavior inline.