artifact-chain-assistant 0.8.2 → 0.8.4

package/adapters/claude/family-apis/schema/family-api.schema.json

@@ -0,0 +1,235 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://artifact-chain.dev/schemas/family-api.schema.json",
+  "title": "Skill Family API",
+  "description": "Schema for standard Skill Family API definitions owned by artifact-chain-assistant",
+  "type": "object",
+  "required": ["schemaVersion", "api", "services"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "type": "integer",
+      "const": 1
+    },
+    "api": {
+      "type": "object",
+      "required": ["id", "major", "revisionDigest", "displayName", "summary"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^artifact\\.[a-z][a-z0-9-]*-family$",
+          "description": "Canonical family API identity in the artifact.* namespace"
+        },
+        "major": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Major version indicating compatibility family"
+        },
+        "revisionDigest": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$",
+          "description": "Immutable SHA-256 digest of canonical API content excluding this field"
+        },
+        "displayName": {
+          "type": "string",
+          "minLength": 1
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        },
+        "artifactTypes": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true,
+          "description": "Artifact types this family operates on"
+        }
+      }
+    },
+    "services": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/definitions/service"
+      }
+    },
+    "capabilities": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/capability"
+      },
+      "description": "Optional public capabilities (no implementation state)"
+    },
+    "dataTransferObjects": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/dataTransferObject" },
+      "description": "Family API 拥有的结构化中间或正式 DTO 声明；schema 仍由 family 提供，接口编译器只校验声明形状和服务引用。"
+    },
+    "qualificationKinds": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^[a-z][A-Za-z0-9]+$" },
+      "uniqueItems": true,
+      "description": "该 Family API 区分的资格种类名称；只声明种类，不把资格证据或成熟度写入接口。"
+    }
+  },
+  "definitions": {
+    "service": {
+      "type": "object",
+      "required": ["id", "required", "kind", "intents"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^artifact\\.[a-z][a-z0-9-]+\\.[a-z][a-z0-9-]+$",
+          "description": "Canonical service identity: artifact.<family>.<intent>"
+        },
+        "required": {
+          "type": "boolean",
+          "description": "Whether this service is required for API conformance"
+        },
+        "kind": {
+          "type": "string",
+          "enum": ["workflow", "operation"],
+          "description": "workflow = stateful multi-step; operation = stateless single-step"
+        },
+        "intents": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "enum": ["default", "help", "author", "review", "repair", "route", "audit", "generate", "batch"]
+          },
+          "uniqueItems": true
+        },
+        "accepts": {
+          "type": "array",
+          "items": {
+            "anyOf": [
+              { "type": "string", "minLength": 1 },
+              { "$ref": "#/definitions/protocolRef" }
+            ]
+          },
+          "description": "Input contract references or natural language descriptions"
+        },
+        "produces": {
+          "type": "array",
+          "items": {
+            "anyOf": [
+              { "type": "string", "minLength": 1 },
+              { "$ref": "#/definitions/protocolRef" }
+            ]
+          },
+          "description": "Output contract references or natural language descriptions"
+        },
+        "sideEffectCeiling": {
+          "type": "string",
+          "enum": ["none", "read-only", "write-authorized-artifacts", "write-review-result", "write-project-artifacts"],
+          "description": "Maximum side effect level this service may produce"
+        },
+        "mixSafe": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether this service can be bound to a different family implementation than other services in the same family"
+        },
+        "discoverable": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "default": {
+              "type": "boolean",
+              "description": "Whether this is the default entry point"
+            },
+            "help": {
+              "type": "boolean",
+              "description": "Whether this is the help entry point"
+            }
+          }
+        },
+        "modes": {
+          "$ref": "#/definitions/serviceModes"
+        }
+      }
+    },
+    "capability": {
+      "type": "object",
+      "required": ["id", "summary"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "serviceModes": {
+      "type": "object",
+      "required": ["supported", "default"],
+      "additionalProperties": false,
+      "properties": {
+        "supported": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+          "uniqueItems": true
+        },
+        "default": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" }
+      }
+    },
+    "dataTransferObject": {
+      "type": "object",
+      "required": ["id", "schemaId", "schema", "version", "digestRule", "services"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+        "schemaId": { "type": "string", "minLength": 1 },
+        "schema": { "type": "string", "pattern": "^[^/\\\\~].*\\.json$" },
+        "version": { "type": "string", "minLength": 1 },
+        "digestRule": { "type": "string", "minLength": 1 },
+        "artifactBinding": { "type": "string", "minLength": 1 },
+        "services": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["service", "position"],
+            "additionalProperties": false,
+            "properties": {
+              "service": { "type": "string", "pattern": "^artifact\\.[a-z][a-z0-9-]+\\.[a-z][a-z0-9-]+$" },
+              "position": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    },
+    "contractRef": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*\\.[a-z][a-z0-9-]*@[0-9]+$",
+      "description": "Artifact Contract major identity reference (e.g., artifact.e2e-test@1)"
+    },
+    "protocolRef": {
+      "type": "object",
+      "required": ["protocol", "version"],
+      "additionalProperties": false,
+      "properties": {
+        "protocol": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Protocol name when no formal Artifact Contract exists"
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Protocol version"
+        },
+        "input": {
+          "type": "string",
+          "description": "Describes what the protocol accepts or produces"
+        }
+      }
+    }
+  }
+}

package/adapters/claude/schemas/project-facts.schema.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://artifact-chain.dev/schemas/project-facts.schema.json",
+  "title": "Project Facts Evidence Envelope",
+  "description": "Structured envelope capturing project identity, configuration, graph state, and evidence for registry/planner consumption",
+  "type": "object",
+  "required": ["schemaVersion", "projectRoot", "configDigest", "artifactGraphSummary", "targetArtifact", "contractRevisionDigest", "proofStatus", "versionLockStatus", "sourcesFreshness", "bindingFreshness", "evidenceDigest"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "type": "integer",
+      "const": 1
+    },
+    "projectRoot": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Project root identity (path or canonical identifier)"
+    },
+    "configDigest": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$",
+      "description": "SHA-256 digest of artifact-graph.config.yaml content"
+    },
+    "policyDigest": {
+      "type": ["string", "null"],
+      "pattern": "^sha256:[a-f0-9]{64}$",
+      "description": "SHA-256 digest of project policy overlay, or null if none"
+    },
+    "artifactGraphSummary": {
+      "type": "object",
+      "required": ["artifactCount", "edgeCount", "contextTargets"],
+      "additionalProperties": false,
+      "properties": {
+        "artifactCount": { "type": "integer", "minimum": 0 },
+        "edgeCount": { "type": "integer", "minimum": 0 },
+        "contextTargets": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "targetArtifact": {
+      "type": "object",
+      "required": ["type", "id"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "type": "string", "minLength": 1 },
+        "id": { "type": "string", "minLength": 1 }
+      }
+    },
+    "contractRevisionDigest": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$",
+      "description": "SHA-256 digest of the contract revision content"
+    },
+    "proofStatus": {
+      "type": "string",
+      "enum": ["present", "missing", "stale"]
+    },
+    "versionLockStatus": {
+      "type": "string",
+      "enum": ["fresh", "stale", "missing"]
+    },
+    "sourcesFreshness": {
+      "type": "string",
+      "enum": ["fresh", "stale", "missing"],
+      "description": "Freshness of the adopted catalog source set"
+    },
+    "bindingFreshness": {
+      "type": "string",
+      "enum": ["fresh", "stale", "missing"],
+      "description": "Freshness of the project provider binding"
+    },
+    "evidenceDigest": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$",
+      "description": "SHA-256 digest of the envelope content excluding this field, using stable key serialization"
+    }
+  }
+}

package/adapters/claude/scripts/check-family-api.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// @feature ACA18 @scenario S-65 @decision D-ACA-18
+// Deterministic Family API catalog validator.
+// Validates all API files in family-apis/ and checks catalog consistency.
+// JSON envelope output; non-zero exit on failure.
+import { readdir, readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  validateFamilyApi,
+  validateCatalogConsistency,
+  loadJson,
+} from './lib/family-api-validator.mjs';
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const familyApisDir = join(root, 'family-apis');
+
+const errors = [];
+const warnings = [];
+const checked = [];
+
+try {
+  // 1. Load catalog
+  const catalogPath = join(familyApisDir, 'catalog.json');
+  let catalog;
+  try {
+    catalog = await loadJson(catalogPath);
+  } catch (err) {
+    errors.push(`Failed to load catalog.json: ${err.message}`);
+    emitResult();
+    process.exit(1);
+  }
+
+  // 2. Discover API files
+  const apiFiles = [];
+  const familiesDir = join(familyApisDir);
+  for (const entry of await readdir(familiesDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name === 'schema') continue;
+    const apiPath = join(familiesDir, entry.name, 'api.json');
+    try {
+      const content = await loadJson(apiPath);
+      apiFiles.push({
+        path: `${entry.name}/api.json`,
+        id: content.api?.id,
+        major: content.api?.major,
+        content,
+      });
+    } catch (err) {
+      // Non-API directories are fine
+    }
+  }
+
+  // 3. Validate each API file (async now)
+  for (const apiFile of apiFiles) {
+    const result = await validateFamilyApi(apiFile.content, { sourcePath: apiFile.path });
+    errors.push(...result.errors.map(e => typeof e === 'string' ? e : e.message || JSON.stringify(e)));
+    warnings.push(...result.warnings);
+    checked.push(apiFile.path);
+  }
+
+  // 4. Validate catalog consistency
+  const consistency = validateCatalogConsistency(
+    catalog,
+    apiFiles.map(f => ({ id: f.id, major: f.major, content: f.content })),
+  );
+  errors.push(...consistency.errors);
+
+  emitResult();
+  if (errors.length > 0) process.exit(1);
+} catch (err) {
+  errors.push(`Unexpected error: ${err.message}`);
+  emitResult();
+  process.exit(1);
+}
+
+function emitResult() {
+  const envelope = {
+    ok: errors.length === 0,
+    checked,
+    errors,
+    warnings,
+  };
+  process.stdout.write(JSON.stringify(envelope, null, 2) + '\n');
+}

package/adapters/claude/scripts/export-family-api.mjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+// @feature ACA18 @scenario S-65 @decision D-ACA-18
+// Authority Family API exporter. Outputs the exact bytes of a registered and
+// validated Family API to a specified path. Supports --check mode for drift detection.
+//
+// CLI does not expose --catalog; only internal test injection can override it.
+// All output is path-safe: no absolute paths in stdout or stderr.
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadJson, validateFamilyApi, computeRevisionDigest } from './lib/family-api-validator.mjs';
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+
+/**
+ * Export a Family API from the authoritative catalog.
+ * @param {object} opts
+ * @param {string} opts.apiId - API id (e.g., "artifact.e2e-test-family")
+ * @param {number} opts.apiMajor - API major version
+ * @param {string} opts.outputPath - Absolute path to write the API JSON
+ * @param {boolean} [opts.check=false] - If true, only check for drift (exit nonzero on drift)
+ * @param {string} [opts.catalogPath] - Override catalog path (internal use only)
+ * @param {boolean} [opts.json=false] - If true, output structured JSON to stdout
+ * @returns {Promise<{ok: boolean, code: string, identity?: object, status?: string, digest?: string, message?: string}>}
+ */
+export async function exportFamilyApi({ apiId, apiMajor, outputPath, check = false, catalogPath, json = false }) {
+  // 1. Load and validate catalog
+  const catalogFilePath = catalogPath || join(root, 'family-apis', 'catalog.json');
+  if (!existsSync(catalogFilePath)) {
+    return { ok: false, code: 'CATALOG_NOT_FOUND', status: 'FAILED', message: 'Catalog file not found' };
+  }
+
+  let catalog;
+  try {
+    catalog = await loadJson(catalogFilePath);
+  } catch {
+    return { ok: false, code: 'CATALOG_INVALID', status: 'FAILED', message: 'Catalog is not valid JSON' };
+  }
+
+  if (!catalog?.families || !Array.isArray(catalog.families)) {
+    return { ok: false, code: 'CATALOG_INVALID', status: 'FAILED', message: 'Catalog missing families array' };
+  }
+
+  // 2. Find matching family
+  const family = catalog.families.find(f => f.id === apiId && f.major === apiMajor);
+  if (!family) {
+    return { ok: false, code: 'API_NOT_REGISTERED', status: 'FAILED', message: 'API not registered in catalog' };
+  }
+
+  // 3. Load and validate the API
+  const apiPath = join(root, 'family-apis', family.apiPath);
+  if (!existsSync(apiPath)) {
+    return { ok: false, code: 'API_FILE_MISSING', status: 'FAILED', message: 'API file missing from catalog path' };
+  }
+
+  let apiContent;
+  try {
+    apiContent = readFileSync(apiPath, 'utf8');
+  } catch {
+    return { ok: false, code: 'API_READ_FAILED', status: 'FAILED', message: 'Cannot read API file' };
+  }
+
+  let apiObject;
+  try {
+    apiObject = JSON.parse(apiContent);
+  } catch {
+    return { ok: false, code: 'API_PARSE_FAILED', status: 'FAILED', message: 'API file is not valid JSON' };
+  }
+
+  // Validate API schema and semantics
+  const validation = await validateFamilyApi(apiObject, { sourcePath: undefined });
+  if (!validation.ok) {
+    return {
+      ok: false, code: 'API_VALIDATION_FAILED', status: 'FAILED',
+      message: `API validation failed: ${validation.errors.length} error(s)`,
+    };
+  }
+
+  // 4. Verify revision digest matches catalog
+  const computedDigest = computeRevisionDigest(apiObject);
+  if (computedDigest !== family.revisionDigest) {
+    return {
+      ok: false, code: 'REVISION_DIGEST_MISMATCH', status: 'FAILED',
+      message: 'Revision digest mismatch between catalog and computed value',
+    };
+  }
+
+  // 5. Check mode: compare with existing output
+  if (check) {
+    if (!existsSync(outputPath)) {
+      return { ok: false, code: 'DRIFT_MISSING_OUTPUT', status: 'DRIFT', message: 'Output file does not exist' };
+    }
+    let existing;
+    try {
+      existing = readFileSync(outputPath, 'utf8');
+    } catch {
+      return { ok: false, code: 'DRIFT_READ_FAILED', status: 'DRIFT', message: 'Cannot read output file' };
+    }
+    if (existing !== apiContent) {
+      return { ok: false, code: 'DRIFT_CONTENT_MISMATCH', status: 'DRIFT', message: 'Output differs from authority' };
+    }
+    return {
+      ok: true, code: 'CHECK_PASSED', status: 'NO_DRIFT',
+      identity: { apiId, apiMajor, revisionDigest: family.revisionDigest },
+      digest: computedDigest,
+    };
+  }
+
+  // 6. Write mode: create parent dir, output exact bytes
+  try {
+    const parentDir = dirname(outputPath);
+    mkdirSync(parentDir, { recursive: true });
+    writeFileSync(outputPath, apiContent, 'utf8');
+    return {
+      ok: true, code: 'EXPORTED', status: 'EXPORTED',
+      identity: { apiId, apiMajor, revisionDigest: family.revisionDigest },
+      digest: computedDigest,
+    };
+  } catch {
+    return { ok: false, code: 'WRITE_FAILED', status: 'FAILED', message: 'Cannot write output file' };
+  }
+}
+
+// CLI entry point
+if (process.argv[1] && process.argv[1].endsWith('export-family-api.mjs')) {
+  const args = process.argv.slice(2);
+  const getArg = (name) => {
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] === `--${name}` && i + 1 < args.length) return args[i + 1];
+      if (args[i].startsWith(`--${name}=`)) return args[i].slice(`--${name}=`.length);
+    }
+    return null;
+  };
+
+  const apiId = getArg('api-id');
+  const apiMajorStr = getArg('api-major');
+  const output = getArg('output');
+  const check = args.includes('--check');
+  const jsonMode = args.includes('--json');
+  // --catalog is internal-only, not in public usage help
+
+  if (!apiId || !apiMajorStr || !output) {
+    if (jsonMode) {
+      process.stdout.write(JSON.stringify({ ok: false, code: 'USAGE', status: 'FAILED', message: 'Missing required arguments' }) + '\n');
+    } else {
+      process.stderr.write('Usage: export-family-api.mjs --api-id=<id> --api-major=<n> --output=<path> [--check] [--json]\n');
+    }
+    process.exit(1);
+  }
+
+  const apiMajor = parseInt(apiMajorStr, 10);
+  if (isNaN(apiMajor)) {
+    if (jsonMode) {
+      process.stdout.write(JSON.stringify({ ok: false, code: 'INVALID_ARGUMENT', status: 'FAILED', message: '--api-major must be a number' }) + '\n');
+    } else {
+      process.stderr.write('--api-major must be a number\n');
+    }
+    process.exit(1);
+  }
+
+  // --catalog is only available via env var for testing (not a public CLI flag)
+  const catalogPath = getArg('catalog');
+  const result = await exportFamilyApi({ apiId, apiMajor, outputPath: output, check, catalogPath, json: jsonMode });
+
+  if (jsonMode) {
+    // JSON output: stable fields only, no absolute paths
+    process.stdout.write(JSON.stringify({
+      ok: result.ok,
+      code: result.code,
+      status: result.status,
+      ...(result.identity ? { identity: result.identity } : {}),
+      ...(result.digest ? { digest: result.digest } : {}),
+      ...(result.message ? { message: result.message } : {}),
+    }, null, 2) + '\n');
+  } else {
+    if (!result.ok) {
+      process.stderr.write(`ERROR: ${result.code}\n`);
+    } else {
+      process.stdout.write(`${result.code}: ${result.status}\n`);
+    }
+  }
+
+  process.exit(result.ok ? 0 : 1);
+}