artifact-chain-assistant 0.8.0

package/scripts/check-templates.mjs

@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+// @scenario S-01 @feature ACA1
+// 模板目录完整性检查：校验 core 和 extended 下每个类型目录至少包含 starter.md 和 review-checklist.md
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const templatesDir = join(root, 'templates');
+const REQUIRED_FILES = ['starter.md', 'review-checklist.md'];
+const CATALOG_FILES = [
+  join(root, 'templates/extended/README.md'),
+  join(root, 'EXTENDED-ARTIFACT-CATALOG.md'),
+  join(root, 'EXTENDED-ARTIFACT-CATALOG.zh-CN.md'),
+];
+
+/** 判断路径是否为目录 */
+async function isDir(path) {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** 获取目录下的子目录名列表 */
+async function subdirs(path) {
+  if (!(await isDir(path))) return [];
+  const entries = await readdir(path, { withFileTypes: true });
+  return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+}
+
+/** 检查单个类型目录，返回缺失文件列表 */
+async function checkTypeDir(dirPath) {
+  const missing = [];
+  for (const file of REQUIRED_FILES) {
+    try {
+      await stat(join(dirPath, file));
+    } catch {
+      missing.push(file);
+    }
+  }
+  return missing;
+}
+
+// ── Professional skill family contract checks ──────────────────────────────
+
+const PROFESSIONAL_ENTRY_FILES = ['SKILL.md', 'author/SKILL.md', 'review/SKILL.md', 'repair/SKILL.md'];
+const PROFESSIONAL_REFERENCE_FILES = ['references/inspect.md', 'references/compose.md', 'references/validate.md'];
+
+/**
+ * Prohibited literal patterns (case-insensitive for first group).
+ * Absolute path patterns are checked separately.
+ */
+const PROHIBITED_LITERALS = [
+  /\bheimdall\b/i,
+  /\btauri\b/i,
+  /\bquick\s+check\b/i,
+  /\bopen\s+core\b/i,
+  /\bsqlite\b/i,
+];
+const ABSOLUTE_PATH_RE = /(?:^|\s)\/(?:Users|home|opt|var|tmp|etc)\b/;
+
+/**
+ * Detect professional families under skills-src: a directory is a professional
+ * family if it contains an `author/` subdirectory.
+ */
+async function discoverProfessionalFamilies(skillsSrcDir) {
+  const families = [];
+  const entries = await readdir(skillsSrcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const familyDir = join(skillsSrcDir, entry.name);
+    try {
+      await stat(join(familyDir, 'author'));
+      families.push({ name: entry.name, dir: familyDir });
+    } catch {
+      // not a professional family
+    }
+  }
+  return families;
+}
+
+/**
+ * Recursively collect all .md files under a directory.
+ */
+async function collectMarkdownFiles(dir) {
+  const files = [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await collectMarkdownFiles(full));
+    } else if (entry.name.endsWith('.md')) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+/**
+ * Parse YAML frontmatter fields from a markdown file.
+ * Returns the raw frontmatter block and parsed { name, description, extra }.
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return { raw: null, fields: {} };
+  const raw = match[1];
+  const fields = {};
+  for (const line of raw.split('\n')) {
+    const m = line.match(/^(\w[\w-]*):\s*(.*)$/);
+    if (m) fields[m[1]] = m[2].trim();
+  }
+  return { raw, fields };
+}
+
+/**
+ * Check professional family contract compliance.
+ * Returns array of error strings.
+ */
+async function checkProfessionalFamilies(skillsSrcDir) {
+  const errors = [];
+  const families = await discoverProfessionalFamilies(skillsSrcDir);
+
+  for (const family of families) {
+    // 1. Entry completeness
+    for (const entry of PROFESSIONAL_ENTRY_FILES) {
+      const entryPath = join(family.dir, entry);
+      try {
+        await stat(entryPath);
+      } catch {
+        errors.push(`family ${family.name}: missing required entry ${entry}`);
+      }
+    }
+
+    // 1b. Internal reference completeness
+    for (const ref of PROFESSIONAL_REFERENCE_FILES) {
+      const refPath = join(family.dir, ref);
+      try {
+        await stat(refPath);
+      } catch {
+        errors.push(`family ${family.name}: missing required internal reference ${ref}`);
+      }
+    }
+
+    // 2. Closed-loop keywords
+    const readSafe = async (rel) => {
+      try { return await readFile(join(family.dir, rel), 'utf8'); } catch { return ''; }
+    };
+
+    const authorContent = await readSafe('author/SKILL.md');
+    const reviewContent = await readSafe('review/SKILL.md');
+    const repairContent = await readSafe('repair/SKILL.md');
+
+    // Default SKILL.md must contain routing keywords: author, review, repair
+    const defaultContent = await readSafe('SKILL.md');
+    if (defaultContent) {
+      for (const kw of ['author', 'review', 'repair']) {
+        if (!defaultContent.includes(kw)) {
+          errors.push(`family ${family.name}/SKILL.md: missing routing keyword "${kw}"`);
+        }
+      }
+    }
+
+    // Author must contain: inspect, compose, validate, review (as steps)
+    if (authorContent) {
+      for (const kw of ['inspect', 'compose', 'validate', 'review']) {
+        if (!authorContent.includes(kw)) {
+          errors.push(`family ${family.name}/author: missing closed-loop keyword "${kw}"`);
+        }
+      }
+    }
+
+    // Review must contain: inspect, review, findings
+    if (reviewContent) {
+      for (const kw of ['inspect', 'review', 'findings']) {
+        if (!reviewContent.includes(kw)) {
+          errors.push(`family ${family.name}/review: missing closed-loop keyword "${kw}"`);
+        }
+      }
+    }
+
+    // Repair must contain: findings, repair, re-review
+    if (repairContent) {
+      for (const kw of ['findings', 'repair', 're-review']) {
+        if (!repairContent.includes(kw)) {
+          errors.push(`family ${family.name}/repair: missing closed-loop keyword "${kw}"`);
+        }
+      }
+    }
+
+    // Internal references: inspect.md must contain "inspect" and "config"
+    //                     compose.md must contain "compose" and "frontmatter"
+    //                     validate.md must contain "validate"
+    const inspectRef = await readSafe('references/inspect.md');
+    if (inspectRef) {
+      for (const kw of ['inspect', 'config']) {
+        if (!inspectRef.includes(kw)) {
+          errors.push(`family ${family.name}/references/inspect.md: missing keyword "${kw}"`);
+        }
+      }
+    }
+    const composeRef = await readSafe('references/compose.md');
+    if (composeRef) {
+      for (const kw of ['compose', 'frontmatter']) {
+        if (!composeRef.includes(kw)) {
+          errors.push(`family ${family.name}/references/compose.md: missing keyword "${kw}"`);
+        }
+      }
+    }
+    const validateRef = await readSafe('references/validate.md');
+    if (validateRef) {
+      for (const kw of ['validate']) {
+        if (!validateRef.includes(kw)) {
+          errors.push(`family ${family.name}/references/validate.md: missing keyword "${kw}"`);
+        }
+      }
+    }
+
+    // 3. Prohibited literals in all family .md files
+    const allFiles = await collectMarkdownFiles(family.dir);
+    for (const filePath of allFiles) {
+      const relPath = relative(root, filePath);
+      const content = await readFile(filePath, 'utf8');
+      for (const pattern of PROHIBITED_LITERALS) {
+        if (pattern.test(content)) {
+          errors.push(`${relPath}: contains prohibited literal matching ${pattern}`);
+        }
+      }
+      if (ABSOLUTE_PATH_RE.test(content)) {
+        errors.push(`${relPath}: contains absolute path`);
+      }
+    }
+
+    // 4. References as non-entry: reference .md files must not have frontmatter
+    const refsDir = join(family.dir, 'references');
+    try {
+      const refEntries = await readdir(refsDir, { withFileTypes: true });
+      for (const ref of refEntries) {
+        if (!ref.isFile() || !ref.name.endsWith('.md')) continue;
+        const refContent = await readFile(join(refsDir, ref.name), 'utf8');
+        if (refContent.startsWith('---')) {
+          errors.push(
+            `family ${family.name}/references/${ref.name}: reference file must not have frontmatter`
+          );
+        }
+      }
+    } catch {
+      // no references dir — that's OK
+    }
+
+    // 5. Frontmatter shape: SKILL.md files must only have name + description
+    for (const entry of PROFESSIONAL_ENTRY_FILES) {
+      const entryPath = join(family.dir, entry);
+      let content;
+      try {
+        content = await readFile(entryPath, 'utf8');
+      } catch {
+        continue; // already reported as missing
+      }
+      const { fields } = parseFrontmatter(content);
+      const allowed = new Set(['name', 'description']);
+      for (const key of Object.keys(fields)) {
+        if (!allowed.has(key)) {
+          errors.push(
+            `family ${family.name}/${entry}: unexpected frontmatter field "${key}"`
+          );
+        }
+      }
+      // description must be third-person (should not start with first-person)
+      if (fields.description && /^(I|We)\s/i.test(fields.description)) {
+        errors.push(
+          `family ${family.name}/${entry}: description must be third-person`
+        );
+      }
+    }
+  }
+
+  return errors;
+}
+
+async function main() {
+  const errors = [];
+  const extendedTypes = [];
+
+  for (const requiredRoot of ['core', 'extended']) {
+    const path = join(templatesDir, requiredRoot);
+    if (!(await isDir(path)) || (await subdirs(path)).length === 0) {
+      errors.push({ type: `templates/${requiredRoot}`, missing: ['non-empty directory'] });
+    }
+  }
+
+  // 1. core 目录：每个子目录即一个类型
+  const coreDir = join(templatesDir, 'core');
+  for (const typeName of await subdirs(coreDir)) {
+    const missing = await checkTypeDir(join(coreDir, typeName));
+    if (missing.length > 0) {
+      errors.push({ type: `core/${typeName}`, missing });
+    }
+  }
+
+  // 2. extended 目录：每类（contracts, domain, ops, governance, agent）下各有类型子目录
+  const extendedDir = join(templatesDir, 'extended');
+  for (const category of await subdirs(extendedDir)) {
+    for (const typeName of await subdirs(join(extendedDir, category))) {
+      extendedTypes.push(typeName);
+      const missing = await checkTypeDir(join(extendedDir, category, typeName));
+      if (missing.length > 0) {
+        errors.push({ type: `extended/${category}/${typeName}`, missing });
+      }
+    }
+  }
+
+  for (const catalogFile of CATALOG_FILES) {
+    let text = '';
+    try {
+      text = await readFile(catalogFile, 'utf8');
+    } catch {
+      errors.push({ type: catalogFile, missing: ['catalog file'] });
+      continue;
+    }
+    for (const typeName of extendedTypes) {
+      if (!text.includes(typeName)) {
+        errors.push({ type: catalogFile, missing: [`catalog entry for ${typeName}`] });
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    for (const err of errors) {
+      console.error(
+        `Template integrity violation: ${err.type} is missing ${err.missing.join(', ')}`
+      );
+    }
+    console.error(
+      `\n${errors.length} type(s) have incomplete templates. ` +
+        `Each type directory must contain: ${REQUIRED_FILES.join(', ')}`
+    );
+    process.exitCode = 1;
+  } else {
+    console.log(
+      `Template integrity check passed: ${extendedTypes.length} extended type(s) have ` +
+        'required files and catalog coverage.'
+    );
+  }
+}
+
+main();

package/scripts/check-workflow-profile.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// @feature ACA17
+// @scenario S-51
+// @scenario S-53
+// @scenario S-54
+// @decision D-ACA-17
+// Thin CLI wrapper. scripts/lib/workflow-profile.mjs is the single resolver.
+import { resolve } from 'node:path';
+import { buildCheckerOutput } from './lib/workflow-profile.mjs';
+
+export async function checkWorkflowProfile({ root = process.cwd(), action = 'review', domain, profilePath, target } = {}) {
+  const projectRoot = resolve(root);
+  const checker = await buildCheckerOutput({ root: projectRoot, profilePath, intent: action, domain, target });
+  return {
+    ...checker,
+    root: projectRoot,
+    action,
+    domain,
+    profile: checker.profile_path,
+    worker: checker.worker_path ? checker.worker_path.split('/').slice(-2, -1)[0] : null,
+    dry_run: true,
+  };
+}
+
+const isMain = import.meta.url === `file://${process.argv[1]}`;
+if (isMain) {
+  const args = process.argv.slice(2);
+  const value = flag => {
+    const index = args.indexOf(flag);
+    return index >= 0 ? args[index + 1] : undefined;
+  };
+  if (args.includes('--help')) {
+    console.log('Usage: node check-workflow-profile.mjs --root <path> --action <generate|review|repair|audit|batch> --domain <type> [--profile <json|yaml>] [--target <path>] [--format json|text]');
+    process.exit(0);
+  }
+  let result;
+  try {
+    result = await checkWorkflowProfile({
+      root: value('--root') ?? process.cwd(),
+      action: value('--action') ?? 'review',
+      domain: value('--domain'),
+      profilePath: value('--profile'),
+      target: value('--target'),
+    });
+  } catch (error) {
+    result = {
+      status: 'BLOCKED', schema: null, profile_path: null, execution_mode: null,
+      worker_path: null, checklist_paths: [], validators: [], template_paths: [],
+      diagnostics: [`Checker failed closed: ${error.message}`],
+      next: 'Fix the malformed or unsafe profile and run this check again.',
+      root: resolve(value('--root') ?? process.cwd()),
+      action: value('--action') ?? 'review', domain: value('--domain'), profile: null,
+      worker: null, dry_run: true,
+    };
+  }
+  if ((value('--format') ?? 'json') === 'text') {
+    console.log(`${result.status}: ${result.action}/${result.domain ?? '(missing)'}`);
+    for (const item of result.diagnostics) console.log(`- ${item}`);
+    console.log(`Next: ${result.next}`);
+  } else {
+    console.log(JSON.stringify(result, null, 2));
+  }
+  process.exit(result.status === 'OK' ? 0 : 2);
+}

package/scripts/doctor.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// @scenario S-06 @feature ACA3
+// @scenario S-44 @feature ACA13
+// @decision D-ACA-15
+import { spawnSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { inspectArtifactGraphRuntime } from './lib/artifact-graph-runtime.mjs';
+
+// Parse --root from args (same as artifact-graph CLI convention)
+const args = process.argv.slice(2);
+let projectRoot = process.cwd();
+const rootIdx = args.indexOf('--root');
+if (rootIdx !== -1 && args[rootIdx + 1]) {
+  projectRoot = resolve(args[rootIdx + 1]);
+}
+
+const runtime = await inspectArtifactGraphRuntime({ projectRoot });
+
+if (!runtime.ok) {
+  const lines = [
+    `artifact-chain-assistant: doctor pre-check failed`,
+    `  reason: ${runtime.reason}`,
+  ];
+  if (runtime.cliPath) lines.push(`  cli: ${runtime.cliPath}`);
+  if (runtime.packagePath) lines.push(`  package: ${runtime.packagePath}`);
+  if (runtime.actualVersion != null) lines.push(`  actual version: ${runtime.actualVersion}`);
+  if (runtime.expectedVersion != null) lines.push(`  expected version: ${runtime.expectedVersion}`);
+  if (runtime.remediation) lines.push(`  fix: ${runtime.remediation}`);
+  process.stderr.write(lines.join('\n') + '\n');
+  process.exitCode = 1;
+} else {
+  // Forward all args to the real artifact-graph doctor
+  const result = spawnSync(runtime.cliPath, ['doctor', ...args], {
+    cwd: process.cwd(),
+    stdio: 'inherit',
+  });
+
+  if (result.error) {
+    process.stderr.write(`artifact-chain-assistant: failed to run artifact-graph doctor: ${result.error.message}\n`);
+    process.exitCode = 127;
+  } else {
+    process.exitCode = result.status ?? 1;
+  }
+}

package/scripts/install-git-hooks.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// @scenario S-04 @feature ACA4
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const args = process.argv.slice(2);
+const cli = existsSync(join(process.cwd(), 'node_modules/.bin/artifact-graph'))
+  ? join(process.cwd(), 'node_modules/.bin/artifact-graph')
+  : 'artifact-graph';
+const result = spawnSync(cli, ['hooks', 'install-git', ...args], {
+  cwd: process.cwd(),
+  stdio: 'inherit',
+});
+
+if (result.error) {
+  process.stderr.write(`artifact-chain-assistant: failed to run artifact-graph hooks install-git: ${result.error.message}\n`);
+  process.exitCode = 127;
+} else {
+  process.exitCode = result.status ?? 1;
+}

package/scripts/lib/artifact-graph-runtime.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+// @scenario S-44 @feature ACA13 @feature ACA3
+// @decision D-ACA-15
+import { access, readFile, realpath } from 'node:fs/promises';
+import { delimiter, join, dirname, resolve } from 'node:path';
+import { loadCompatibilityPolicy } from './compatibility-policy.mjs';
+
+/**
+ * Locate the artifact-graph CLI in a target project, resolve its package version,
+ * and compare against the plugin's compatibility policy.
+ *
+ * Resolution order:
+ *   1. <projectRoot>/node_modules/.bin/artifact-graph
+ *   2. PATH lookup for artifact-graph
+ *   3. ARTIFACT_GRAPH_LEGACY_CLI env var (explicit fallback)
+ *
+ * For the resolved CLI, look up its owning package.json (name === "artifact-graph")
+ * and compare the version field against policy.artifactGraph.verifiedVersion.
+ *
+ * @param {{ projectRoot: string, env?: Record<string,string> }} opts
+ * @returns {Promise<{ok: boolean, cliPath?: string, packagePath?: string, actualVersion?: string, expectedVersion?: string, reason?: string, remediation?: string}>}
+ */
+export async function inspectArtifactGraphRuntime({ projectRoot, env }) {
+  const pluginRoot = resolve(import.meta.dirname, '..', '..');
+  let policy;
+  try {
+    policy = await loadCompatibilityPolicy(pluginRoot);
+  } catch (error) {
+    return {
+      ok: false,
+      reason: 'policy_load_failed',
+      remediation: `Failed to load compatibility policy: ${error.message}`,
+      expectedVersion: null,
+    };
+  }
+
+  const expectedVersion = policy.artifactGraph.verifiedVersion;
+  const installSpec = policy.artifactGraph.installSpec;
+
+  // 1. Try project-local CLI first
+  const localBin = join(projectRoot, 'node_modules', '.bin', 'artifact-graph');
+  let cliPath = await resolveIfExecutable(localBin);
+
+  // 2. Try PATH
+  if (!cliPath) {
+    cliPath = await findOnPath(env ?? process.env);
+  }
+
+  // 3. Try explicit legacy CLI override
+  if (!cliPath) {
+    const legacy = (env ?? process.env).ARTIFACT_GRAPH_LEGACY_CLI;
+    if (legacy) {
+      cliPath = await resolveIfExecutable(legacy);
+    }
+  }
+
+  if (!cliPath) {
+    return {
+      ok: false,
+      reason: 'cli_not_found',
+      expectedVersion,
+      remediation: `artifact-graph CLI not found. Run: pnpm add -D ${installSpec}`,
+    };
+  }
+
+  // 4. Resolve the owning package.json
+  const { packagePath, version } = await resolvePackageVersion(cliPath);
+
+  if (!version) {
+    return {
+      ok: false,
+      cliPath,
+      packagePath,
+      reason: 'version_unresolved',
+      expectedVersion,
+      remediation: `Could not determine artifact-graph version from ${packagePath || cliPath}. Run: pnpm add -D ${installSpec}`,
+    };
+  }
+
+  if (version !== expectedVersion) {
+    return {
+      ok: false,
+      cliPath,
+      packagePath,
+      actualVersion: version,
+      expectedVersion,
+      reason: 'version_mismatch',
+      remediation: `artifact-graph version is ${version}, expected ${expectedVersion}. Run: pnpm add -D ${installSpec}`,
+    };
+  }
+
+  return {
+    ok: true,
+    cliPath,
+    packagePath,
+    actualVersion: version,
+    expectedVersion,
+  };
+}
+
+/**
+ * Resolve a path to its realpath if it exists and is executable (X_OK).
+ */
+async function resolveIfExecutable(path) {
+  try {
+    const real = await realpath(path);
+    await access(real, 1); // X_OK = 1
+    return real;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Search PATH for artifact-graph binary.
+ * Does NOT check ARTIFACT_GRAPH_LEGACY_CLI — that's the caller's fallback.
+ */
+export async function findOnPath(env) {
+  const pathEnv = env.PATH || '';
+  const pathDirs = pathEnv.split(delimiter);
+
+  for (const dir of pathDirs) {
+    if (!dir) continue;
+    const candidate = join(dir, 'artifact-graph');
+    const resolved = await resolveIfExecutable(candidate);
+    if (resolved) return resolved;
+  }
+
+  return null;
+}
+
+/**
+ * Given a CLI path, find the owning artifact-graph package.json and its version.
+ *
+ * Strategy:
+ * 1. Walk up from the CLI directory looking for package.json with name === "artifact-graph".
+ * 2. If CLI is under .bin/, also try walking up from the sibling artifact-graph/ package directory.
+ *
+ * Returns { packagePath, version } or { packagePath: null, version: null }.
+ */
+export async function resolvePackageVersion(cliPath) {
+  // Strategy 1: walk up from CLI location
+  const result = await walkUpForPackage(dirname(cliPath));
+  if (result.packagePath) return result;
+
+  // Strategy 2: if CLI is under a .bin/ directory, check sibling package directories
+  const dir = dirname(cliPath);
+  const parentDir = dirname(dir);
+  if (dir.endsWith('.bin') || dir.endsWith('.bin/')) {
+    // Check parentDir/artifact-graph/package.json directly
+    const siblingPkg = join(parentDir, 'artifact-graph', 'package.json');
+    try {
+      const raw = await readFile(siblingPkg, 'utf8');
+      const pkg = JSON.parse(raw);
+      if (pkg.name === 'artifact-graph') {
+        return { packagePath: siblingPkg, version: pkg.version || null };
+      }
+    } catch {
+      // No sibling package found
+    }
+  }
+
+  return { packagePath: null, version: null };
+}
+
+async function walkUpForPackage(startDir) {
+  let dir = startDir;
+  const seen = new Set();
+
+  while (dir && !seen.has(dir)) {
+    seen.add(dir);
+    const pkgPath = join(dir, 'package.json');
+    try {
+      const raw = await readFile(pkgPath, 'utf8');
+      const pkg = JSON.parse(raw);
+      if (pkg.name === 'artifact-graph') {
+        return { packagePath: pkgPath, version: pkg.version || null };
+      }
+    } catch {
+      // No package.json at this level, or not valid JSON
+    }
+
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return { packagePath: null, version: null };
+}