artifact-chain-assistant 0.8.2 → 0.8.3

package/adapters/claude/scripts/family-compile.mjs

@@ -0,0 +1,309 @@
+#!/usr/bin/env node
+// @feature ACA18 @scenario S-65 @decision D-ACA-18
+// Thin full-family compiler facade. API-only validation belongs to
+// check-family-api.mjs. Full conformance integrates the authoritative
+// Registry v2 verifier for independent implementation verification.
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadJson, validateCatalogConsistency, validateFamilyApi } from './lib/family-api-validator.mjs';
+import { parseMinimalYaml } from './lib/inline-yaml-parser.mjs';
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+
+export function subprocessCommandRunner({ command, args, cwd, timeout }) {
+  return {
+    stdout: execFileSync(command, args, { encoding: 'utf8', cwd, timeout }),
+  };
+}
+
+export async function familyCompile({
+  familyApiPath,
+  catalogPath,
+  implementationPath,
+  pluginRoot,
+  artifactGraphCommand,
+  registryCommand,
+  commandRunner = subprocessCommandRunner,
+}) {
+  const base = pluginRoot || root;
+  const checks = [];
+  const result = {
+    ok: false,
+    apiConformance: { status: 'FAIL' },
+    familyConformance: { status: 'FAIL' },
+    deterministicConformance: { status: 'FAIL', checks, attestations: [] },
+    behaviorQualification: {
+      status: 'NOT_RUN',
+      evidence: [],
+      limitations: [
+        'Family behavior TCK has not run',
+        'Behavior qualification cannot prove general LLM semantic quality',
+      ],
+    },
+  };
+
+  let api;
+  const apiCheck = { name: 'family-api-validation', ok: false, status: 'FAIL', errors: [] };
+  try {
+    api = await loadJson(familyApiPath);
+    const validation = await validateFamilyApi(api, { sourcePath: familyApiPath });
+    apiCheck.ok = validation.ok;
+    apiCheck.status = validation.ok ? 'PASS' : 'FAIL';
+    apiCheck.errors = validation.errors.map(error => typeof error === 'string' ? error : `${error.code} ${error.path}: ${error.message}`);
+    apiCheck.warnings = validation.warnings;
+  } catch (error) {
+    apiCheck.errors.push(`Failed to load API file: ${error.message}`);
+  }
+  checks.push(apiCheck);
+
+  const catalogCheck = { name: 'catalog-consistency', ok: false, status: 'FAIL', errors: [] };
+  try {
+    const catalog = await loadJson(catalogPath || join(base, 'family-apis/catalog.json'));
+    if (!api) api = await loadJson(familyApiPath);
+    const validation = validateCatalogConsistency(catalog, [{
+      id: api.api?.id,
+      major: api.api?.major,
+      content: api,
+    }]);
+    catalogCheck.ok = validation.ok;
+    catalogCheck.status = validation.ok ? 'PASS' : 'FAIL';
+    catalogCheck.errors = validation.errors;
+  } catch (error) {
+    catalogCheck.errors.push(`Catalog consistency check failed: ${error.message}`);
+  }
+  checks.push(catalogCheck);
+
+  result.apiConformance.status = apiCheck.ok && catalogCheck.ok ? 'PASS' : 'FAIL';
+
+  const contractCheck = {
+    name: 'artifact-contract-validation',
+    ok: false,
+    status: 'FAIL',
+    errors: [],
+    resolvedContracts: [],
+  };
+  const command = artifactGraphCommand || findArtifactGraphCli(base);
+  const contractRefs = collectContractRefs(api);
+  if (!command) {
+    contractCheck.errors.push('artifact-graph CLI not found; authoritative contract validation is required');
+  } else {
+    let allResolved = true;
+    for (const contractRef of contractRefs) {
+      try {
+        const response = await commandRunner({
+          command,
+          args: ['contract', 'explain', '--contract', contractRef, '--format', 'json'],
+          cwd: base,
+          timeout: 30000,
+        });
+        const parsed = JSON.parse(response.stdout);
+        const revisionDigest = parsed?.data?.identity?.revisionDigest;
+        if (parsed?.ok !== true || !/^sha256:[a-f0-9]{64}$/.test(revisionDigest || '')) {
+          throw new Error('contract explain returned no authoritative revision digest');
+        }
+        contractCheck.resolvedContracts.push({ ref: contractRef, revisionDigest, status: 'RESOLVED' });
+      } catch (error) {
+        allResolved = false;
+        contractCheck.errors.push(`contract explain for ${contractRef} failed: ${error.message}`);
+        contractCheck.resolvedContracts.push({ ref: contractRef, status: 'FAIL' });
+      }
+    }
+    contractCheck.ok = allResolved;
+    contractCheck.status = allResolved ? 'PASS' : 'FAIL';
+  }
+  checks.push(contractCheck);
+
+  const implementationCheck = {
+    name: 'implementation-descriptor-presence',
+    ok: false,
+    status: 'IMPLEMENTATION_REQUIRED',
+    errors: [],
+  };
+  const registryCheck = {
+    name: 'registry-v2-validation',
+    ok: false,
+    status: 'REGISTRY_V2_REQUIRED',
+    errors: [],
+  };
+
+  let implementationDescriptor = null;
+
+  if (!implementationPath) {
+    implementationCheck.errors.push('Full family compile requires --implementation=<implementation.yaml>');
+  } else if (!existsSync(implementationPath)) {
+    implementationCheck.errors.push(`Implementation descriptor not found: ${implementationPath}`);
+  } else {
+    // Step 1: Invoke Registry v2 validate command
+    const registryCmd = registryCommand || findRegistryCli(base);
+    if (!registryCmd) {
+      registryCheck.errors.push('Registry v2 CLI not found; authoritative validation is required');
+      registryCheck.status = 'REGISTRY_V2_REQUIRED';
+    } else {
+      try {
+        const registryResponse = await commandRunner({
+          command: registryCmd,
+          args: ['validate', '--catalog', implementationPath],
+          cwd: base,
+          timeout: 30000,
+        });
+        const registryParsed = JSON.parse(registryResponse.stdout);
+        if (registryParsed?.ok !== true) {
+          const diagnostics = (registryParsed?.diagnostics || [])
+            .filter(d => d.severity === 'error')
+            .map(d => d.message || d.code)
+            .join('; ');
+          throw new Error(`Registry v2 validation failed: ${diagnostics || 'ok=false'}`);
+        }
+        registryCheck.ok = true;
+        registryCheck.status = 'PASS';
+
+        // Step 2: Read and parse implementation descriptor using fail-closed YAML parser
+        const yamlSource = readFileSync(implementationPath, 'utf8');
+        implementationDescriptor = parseMinimalYaml(yamlSource);
+        if (!implementationDescriptor || typeof implementationDescriptor !== 'object') {
+          throw new Error('Failed to parse implementation descriptor as valid YAML mapping');
+        }
+
+        // Step 3: Execute assistant-owned API/implementation conformance checks
+        const conformanceErrors = validateImplementationConformance(api, implementationDescriptor);
+        if (conformanceErrors.length > 0) {
+          implementationCheck.errors.push(...conformanceErrors);
+          implementationCheck.status = 'CONFORMANCE_FAIL';
+        } else {
+          implementationCheck.ok = true;
+          implementationCheck.status = 'PASS';
+        }
+      } catch (error) {
+        registryCheck.errors.push(`Registry v2 validation failed: ${error.message}`);
+        registryCheck.status = 'FAIL';
+        implementationCheck.errors.push(`Implementation verification failed: ${error.message}`);
+      }
+    }
+  }
+  checks.push(implementationCheck);
+  checks.push(registryCheck);
+
+  const allPass = checks.every(check => check.ok === true);
+  result.deterministicConformance.status = allPass ? 'PASS' : 'FAIL';
+  result.familyConformance.status = allPass ? 'PASS' : 'FAIL';
+  result.ok = allPass;
+  return result;
+}
+
+function collectContractRefs(api) {
+  const refs = new Set();
+  for (const service of api?.services || []) {
+    for (const ref of [...(service.accepts || []), ...(service.produces || [])]) {
+      if (typeof ref === 'string' && /^[a-z][a-z0-9-]*\.[a-z][a-z0-9-]*@[0-9]+$/.test(ref)) refs.add(ref);
+    }
+  }
+  return [...refs].sort();
+}
+
+function findArtifactGraphCli(base) {
+  const candidates = [
+    join(base, 'node_modules/.bin/artifact-graph'),
+    join(base, '../../node_modules/.bin/artifact-graph'),
+  ];
+  return candidates.find(candidate => existsSync(candidate)) || null;
+}
+
+function findRegistryCli(base) {
+  // Deterministic search in plugin and parent project node_modules
+  const candidates = [
+    join(base, 'node_modules/.bin/agent-method-registry'),
+    join(base, '../../node_modules/.bin/agent-method-registry'),
+  ];
+  return candidates.find(candidate => existsSync(candidate)) || null;
+}
+
+/**
+ * Validate implementation conformance against Family API.
+ * Only checks what assistant owns: API identity match, required service coverage,
+ * and no unknown services. Structure validation is Registry's responsibility.
+ *
+ * @param {object} api - The loaded Family API
+ * @param {object} descriptor - The parsed implementation descriptor
+ * @returns {string[]} Array of conformance errors (empty if all pass)
+ */
+function validateImplementationConformance(api, descriptor) {
+  const errors = [];
+
+  // Check implements block exists
+  const impl = descriptor.implements;
+  if (!impl || typeof impl !== 'object') {
+    errors.push('Implementation descriptor missing "implements" block');
+    return errors;
+  }
+
+  // Verify API identity match (exact match required)
+  const apiId = api?.api?.id;
+  const apiMajor = api?.api?.major;
+  const apiRevisionDigest = api?.api?.revisionDigest;
+
+  if (!apiId || apiMajor === undefined || !apiRevisionDigest) {
+    errors.push('Family API missing required identity fields (id, major, revisionDigest)');
+    return errors;
+  }
+
+  if (impl.apiId !== apiId) {
+    errors.push(`API id mismatch: expected "${apiId}", got "${impl.apiId}"`);
+  }
+  if (impl.apiMajor !== apiMajor) {
+    errors.push(`API major version mismatch: expected ${apiMajor}, got ${impl.apiMajor}`);
+  }
+  if (impl.apiRevisionDigest !== apiRevisionDigest) {
+    errors.push(`API revision digest mismatch: expected "${apiRevisionDigest}", got "${impl.apiRevisionDigest}"`);
+  }
+
+  // Check services conformance
+  const services = descriptor.services;
+  if (!services || typeof services !== 'object' || Array.isArray(services)) {
+    errors.push('"services" must be a mapping');
+    return errors;
+  }
+
+  const implementedServices = new Set(Object.keys(services));
+
+  // Check all required services are implemented
+  const requiredServices = (api?.services || [])
+    .filter(service => service.required === true)
+    .map(service => service.id);
+
+  for (const required of requiredServices) {
+    if (!implementedServices.has(required)) {
+      errors.push(`Required service not implemented: "${required}"`);
+    }
+  }
+
+  // Check no unknown services (not in API)
+  const apiServiceIds = new Set((api?.services || []).map(service => service.id));
+  for (const implemented of implementedServices) {
+    if (!apiServiceIds.has(implemented)) {
+      errors.push(`Unknown service not in API: "${implemented}"`);
+    }
+  }
+
+  return errors;
+}
+
+if (process.argv[1] && process.argv[1].endsWith('family-compile.mjs')) {
+  const apiArg = process.argv.find(argument => argument.startsWith('--api='));
+  if (!apiArg) {
+    process.stderr.write('Usage: family-compile.mjs --api=<api.json> --implementation=<implementation.yaml> [--catalog=<catalog.json>] [--registry-command=<path>]\n');
+    process.exit(1);
+  }
+  const catalogArg = process.argv.find(argument => argument.startsWith('--catalog='));
+  const implementationArg = process.argv.find(argument => argument.startsWith('--implementation='));
+  const registryCommandArg = process.argv.find(argument => argument.startsWith('--registry-command='));
+  const result = await familyCompile({
+    familyApiPath: apiArg.slice('--api='.length),
+    catalogPath: catalogArg?.slice('--catalog='.length),
+    implementationPath: implementationArg?.slice('--implementation='.length),
+    registryCommand: registryCommandArg?.slice('--registry-command='.length),
+  });
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  if (!result.ok) process.exit(1);
+}

package/adapters/claude/scripts/family-help-render.mjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+// @feature ACA18 @scenario S-65 @decision D-ACA-18
+// Deterministic renderer for help skill.
+// Reads Family API catalog, implementation samples, and optional projection;
+// outputs Markdown help text. Fail-closed: projection parse failure → NOT_AVAILABLE.
+import { readdir, readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseMinimalYaml } from './lib/inline-yaml-parser.mjs';
+import { validateCatalogConsistency, validateFamilyApi } from './lib/family-api-validator.mjs';
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+
+export async function renderHelp({ projectionPath, pluginRoot } = {}) {
+  const base = pluginRoot || root;
+  const sections = [];
+
+  // 1. Load and render Family API Catalog
+  const catalogPath = join(base, 'family-apis', 'catalog.json');
+  let catalog;
+  try {
+    catalog = JSON.parse(await readFile(catalogPath, 'utf8'));
+  } catch {
+    sections.push('## Standard Family API\n\n> Family API catalog not found or invalid.\n');
+    return sections.join('\n---\n\n');
+  }
+
+  const apiSummary = await renderApiCatalog(catalog, base);
+  sections.push(apiSummary);
+
+  // 2. Load and render bundled legacy implementations
+  const familiesDir = join(base, 'families-src');
+  const legacySection = await renderLegacyMethods(familiesDir);
+  sections.push(legacySection);
+
+  // 3. Render installation status from optional projection
+  const statusSection = await renderInstallationStatus(projectionPath);
+  sections.push(statusSection);
+
+  // 4. Adoption steps
+  sections.push(renderAdoptionSteps());
+
+  return sections.join('\n---\n\n');
+}
+
+async function renderApiCatalog(catalog, base) {
+  const lines = ['## Standard Family API', ''];
+
+  if (!catalog.families || catalog.families.length === 0) {
+    lines.push('> No standard families registered.\n');
+    return lines.join('\n');
+  }
+
+  const loadedFamilies = [];
+  const diagnostics = [];
+  for (const family of catalog.families) {
+    const api = await loadApi(join(base, 'family-apis', family.apiPath));
+    if (!api) {
+      diagnostics.push(`${family.id}@${family.major}: API file missing or invalid JSON`);
+      continue;
+    }
+    const validation = await validateFamilyApi(api, { sourcePath: family.apiPath });
+    if (!validation.ok) {
+      diagnostics.push(...validation.errors.map(error => `${family.id}@${family.major}: ${error.code} ${error.path} ${error.message}`));
+      continue;
+    }
+    loadedFamilies.push({ family, api });
+  }
+
+  const consistency = validateCatalogConsistency(catalog, loadedFamilies.map(({ api }) => ({
+    id: api.api.id,
+    major: api.api.major,
+    content: api,
+  })));
+  diagnostics.push(...consistency.errors);
+  if (diagnostics.length > 0) {
+    lines.push('> Standard Family API catalog is unavailable because deterministic validation failed.');
+    lines.push('>');
+    for (const diagnostic of diagnostics) lines.push(`> - ${diagnostic}`);
+    return lines.join('\n');
+  }
+
+  // Summary table
+  lines.push('| Family | Major | Services | Summary |');
+  lines.push('|--------|-------|----------|---------|');
+
+  for (const { family, api } of loadedFamilies) {
+    const serviceNames = (api.services || []).map(s => s.id.split('.').pop()).join(', ');
+    lines.push(`| ${family.id} | ${family.major} | ${serviceNames} | ${family.summary || api.api?.summary || ''} |`);
+  }
+
+  // Detailed per-family sections
+  for (const { family, api } of loadedFamilies) {
+    lines.push('');
+    lines.push(`### ${family.id}@${family.major}`);
+    lines.push('');
+    lines.push(api.api?.summary || '');
+    lines.push('');
+    lines.push('**Services:**');
+
+    for (const svc of api.services || []) {
+      const required = svc.required ? 'required' : 'optional';
+      const discoverable = svc.discoverable?.default ? ' [DEFAULT]' : (svc.discoverable?.help ? ' [HELP]' : '');
+      lines.push(`- \`${svc.id.split('.').pop()}\` (${required}, ${svc.kind})${discoverable} — ${renderServiceSummary(svc)}`);
+    }
+
+    // Contract refs
+    const contractRefs = new Set();
+    for (const svc of api.services || []) {
+      for (const ref of [...(svc.accepts || []), ...(svc.produces || [])]) {
+        if (typeof ref === 'string' && ref.includes('@')) {
+          contractRefs.add(ref);
+        }
+      }
+    }
+    if (contractRefs.size > 0) {
+      lines.push(`**Artifact Contracts:** ${[...contractRefs].join(', ')}`);
+    }
+
+    // Capabilities
+    if (api.capabilities && api.capabilities.length > 0) {
+      lines.push('');
+      lines.push('**Capabilities:**');
+      for (const cap of api.capabilities) {
+        lines.push(`- ${cap.id}: ${cap.summary}`);
+      }
+    }
+  }
+
+  return lines.join('\n');
+}
+
+function renderServiceSummary(svc) {
+  const parts = [];
+  if (svc.intents) parts.push(`intents: ${svc.intents.join(', ')}`);
+  if (svc.sideEffectCeiling) parts.push(`ceiling: ${svc.sideEffectCeiling}`);
+  return parts.length > 0 ? parts.join('; ') : svc.id;
+}
+
+async function renderLegacyMethods(familiesDir) {
+  const lines = ['## Bundled Legacy Methods', ''];
+  lines.push('These bundled families predate the standard Family API system.');
+  lines.push('They are recorded as migration samples and do NOT claim Family API conformance.');
+  lines.push('');
+
+  let found = false;
+  try {
+    for (const entry of await readdir(familiesDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const implPath = join(familiesDir, entry.name, 'implementation.yaml');
+      try {
+        const content = await readFile(implPath, 'utf8');
+        const impl = parseMinimalYaml(content);
+        if (!impl) continue;
+        found = true;
+        const status = impl.targetApiStatus === 'pending' ? 'pending (no published Family API)' : impl.targetApiStatus || 'unknown';
+        const ownership = impl.lifecycle?.ownership || 'unknown';
+        const maturity = impl.lifecycle?.maturity || 'unknown';
+        lines.push(`### ${entry.name} (${maturity})`);
+        lines.push(`- Status: targetApiStatus: ${status}`);
+        lines.push(`- Ownership: ${ownership}`);
+        const serviceIds = impl.services ? Object.keys(impl.services) : [];
+        const serviceNames = serviceIds.map(s => s.split('.').pop());
+        lines.push(`- Services: ${serviceNames.join(', ')}`);
+        lines.push('- Note: Does NOT claim Family API conformance');
+        lines.push('');
+      } catch {
+        // No implementation.yaml — skip
+      }
+    }
+  } catch {
+    // families-src directory not found
+  }
+
+  if (!found) {
+    lines.push('> No bundled legacy family implementations found.\n');
+  }
+
+  return lines.join('\n');
+}
+
+async function renderInstallationStatus(projectionPath) {
+  const lines = ['## Installation Status', ''];
+  lines.push('Registry projection: **NOT_AVAILABLE** (REGISTRY_V2_REQUIRED)');
+  lines.push('');
+  lines.push('Dynamic provider state is intentionally unavailable until the Registry v2 projection verifier is integrated.');
+  if (projectionPath) lines.push('The supplied projection was ignored; assistant-side marker checks are not an authority.');
+  return lines.join('\n');
+}
+
+function renderAdoptionSteps() {
+  return `## Getting Started
+
+1. **Learn**: Review the Standard Family API above to understand available capabilities.
+2. **Bootstrap**: Run \`artifact-chain-bootstrap\` (with user authorization) to set up your project.
+3. **Orient**: Run \`where-am-i\` to get project-specific recommendations based on your current state.
+4. **Adopt**: Follow where-am-i recommendations to adopt specific families and services.`;
+}
+
+async function loadApi(path) {
+  try {
+    return JSON.parse(await readFile(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// CLI entry
+if (process.argv[1] && process.argv[1].endsWith('family-help-render.mjs')) {
+  const projectionArg = process.argv.find(a => a.startsWith('--projection='));
+  const projectionPath = projectionArg ? projectionArg.slice('--projection='.length) : undefined;
+  const md = await renderHelp({ projectionPath });
+  process.stdout.write(md + '\n');
+}