cc-devflow 4.3.0 → 4.5.0

package/bin/adapt.js

@@ -3,7 +3,7 @@
  * CLI Entry Point - bin/adapt.js (v2.0)
  *
  * Usage:
- *   npm run adapt                        # Compile all (commands + skills + rules)
+ *   npm run adapt                        # Compile all platform outputs (skills + optional commands + rules)
  *   npm run adapt -- --platform codex    # Compile for Codex only
  *   npm run adapt -- --all               # Compile for all platforms (explicit)
  *   npm run adapt -- --check             # Check for drift
@@ -80,7 +80,7 @@ function showHelp() {
   console.log(`
 Usage: npm run adapt [options]
 
-Adapter Compiler - Compile CC-DevFlow to multi-platform formats
+Adapter Compiler - Compile CC-DevFlow skills, optional commands, and rules
 
 Options:
   --platform <name>   Compile for specific platform (${PLATFORMS.join(', ')})
@@ -215,10 +215,6 @@ async function main() {
       console.log(`  Files skipped: ${result.filesSkipped}`);
       console.log(`  Resources copied: ${result.resourcesCopied}`);
       console.log(`  Resources skipped: ${result.resourcesSkipped}`);
-      console.log(`  Skills emitted: ${result.skillsEmitted}`);
-      console.log(`  Agents emitted: ${result.agentsEmitted}`);
-      console.log(`  Module rules emitted: ${result.moduleRulesEmitted}`);
-      console.log(`  Hooks emitted: ${result.hooksEmitted}`);
       console.log(`  Skills registered: ${result.skillsRegistered}`);
       console.log(`  Rules generated: ${result.rulesGenerated}`);
       process.exit(0);

package/bin/cc-devflow-cli.js

@@ -1,29 +1,46 @@
 #!/usr/bin/env node
-/**
- * [INPUT]: 依赖 .claude 模板、adapt 编译入口与 harness 运行时入口。
- * [OUTPUT]: 提供 init/adapt/harness 命令，并在目标仓库自动补齐 harness npm scripts。
- * [POS]: cc-devflow 的统一 CLI 门面，串联安装、编译与运行时发布链路。
- * [PROTOCOL]: 变更时更新此头部，然后检查 CLAUDE.md
- */
 const fs = require('fs');
 const path = require('path');
 const { spawnSync } = require('child_process');
 
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
 const TEMPLATE_DIR = path.join(PACKAGE_ROOT, '.claude');
+const TEMPLATE_SKILLS_DIR = path.join(TEMPLATE_DIR, 'skills');
+const DISTRIBUTION_CONFIG = require(path.join(PACKAGE_ROOT, 'config', 'distributable-skills.json'));
+const {
+  doctorUserConfig,
+  getConfigValue,
+  resolveUserConfig,
+  setConfigValue,
+  writeConfigTemplate
+} = require(path.join(PACKAGE_ROOT, 'lib/skill-runtime/config.js'));
 const ADAPT_BIN = path.join(PACKAGE_ROOT, 'bin', 'adapt.js');
 const ADAPTER_BIN = path.join(PACKAGE_ROOT, 'bin', 'cc-devflow.js');
-const HARNESS_BIN = path.join(PACKAGE_ROOT, 'bin', 'harness.js');
-const HARNESS_SCRIPT_COMMANDS = {
-  'harness:init': 'init',
-  'harness:pack': 'pack',
-  'harness:plan': 'plan',
-  'harness:dispatch': 'dispatch',
-  'harness:verify': 'verify',
-  'harness:release': 'release',
-  'harness:resume': 'resume',
-  'harness:janitor': 'janitor'
-};
+const TEMPLATE_IGNORES = new Set(['.DS_Store', 'tsc-cache']);
+const DISTRIBUTED_SKILLS = Array.from(
+  new Set(DISTRIBUTION_CONFIG.distributedSkills || DISTRIBUTION_CONFIG.publicSkills || [])
+);
+const DISTRIBUTED_SKILL_SET = new Set(DISTRIBUTED_SKILLS);
+
+function shouldIncludeTemplatePath(src) {
+  const relativePath = path.relative(TEMPLATE_DIR, src);
+
+  if (!relativePath || relativePath === '') {
+    return true;
+  }
+
+  const segments = relativePath.split(path.sep);
+  const skillIndex = segments.indexOf('skills');
+
+  if (skillIndex !== -1 && segments.length > skillIndex + 1) {
+    const skillName = segments[skillIndex + 1];
+    if (!DISTRIBUTED_SKILL_SET.has(skillName)) {
+      return false;
+    }
+  }
+
+  return !segments.some((segment) => TEMPLATE_IGNORES.has(segment));
+}
 
 function showHelp() {
   console.log(`
@@ -32,11 +49,15 @@ Usage: cc-devflow <command> [options]
 Commands:
   init                Install .claude template into a project
   adapt               Compile .claude into multi-platform outputs
-  harness             Run harness runtime commands (init/verify/release/janitor...)
+  config init         Create a YAML config template
+  config get          Print one resolved config value
+  config set          Set one project/user/local config value
+  config resolve      Print resolved YAML config with key-level trace
+  config doctor       Validate config and local ignore safety
 
 Init options:
   --dir <path>         Target project path (default: cwd)
-  --force              Overwrite existing .claude
+  --force              Force-upgrade managed skills without deleting other .claude files
 
 Adapt options:
   --cwd <path>         Target project path (default: cwd)
@@ -47,12 +68,26 @@ Adapt options:
   --rules              Generate rules entry files only
   --verbose            Show detailed output
 
+Config options:
+  --cwd <path>         Project path used for project/local config lookup
+  --user               Read/write ~/.cc-devflow/config.yml
+  --project            Read/write .cc-devflow/config.yml
+  --local              Read/write .cc-devflow/config.local.yml
+  --scope <name>       Backward-compatible scope alias: user, project, or local
+  --format <name>      Output format: json or policy
+  --document-language  CLI override for output.document_language
+  --trace              Include key-level source trace with policy output
+  --force              Overwrite an existing config template
+
 Examples:
   cc-devflow init
   cc-devflow init --dir /path/to/project
   cc-devflow adapt --platform cursor
   cc-devflow adapt --cwd /path/to/project --platform codex
-  cc-devflow harness release --change-id REQ-123
+  cc-devflow config init --cwd /path/to/project --project
+  cc-devflow config set output.document_language zh-CN --cwd /path/to/project --project
+  cc-devflow config set output.document_language zh-CN --user
+  cc-devflow config resolve --cwd /path/to/project --format policy
 `);
 }
 
@@ -106,188 +141,294 @@ function parseCliArgs(args) {
   return { options, rest };
 }
 
-function copyIncremental(src, dest) {
+function copyManagedDirectory(src, dest, options = {}) {
+  const { force = false } = options;
+
+  if (!shouldIncludeTemplatePath(src)) {
+    return;
+  }
+
   const stats = fs.statSync(src);
   if (stats.isDirectory()) {
-    if (!fs.existsSync(dest)) {
-      fs.mkdirSync(dest);
-    }
+    fs.mkdirSync(dest, { recursive: true });
     const entries = fs.readdirSync(src);
     for (const entry of entries) {
-      copyIncremental(path.join(src, entry), path.join(dest, entry));
-    }
-  } else {
-    if (!fs.existsSync(dest)) {
-      // Case 1: File missing - Copy it
-      fs.copyFileSync(src, dest);
-      console.log(`[NEW] ${path.relative(process.cwd(), dest)}`);
-    } else {
-      // Case 2: File exists - Compare content
-      try {
-        const srcContent = fs.readFileSync(src);
-        const destContent = fs.readFileSync(dest);
-
-        if (!srcContent.equals(destContent)) {
-          // Content differs - Overwrite original
-          fs.unlinkSync(dest);
-          fs.copyFileSync(src, dest);
-          console.log(`[UPDATE] ${path.relative(process.cwd(), dest)}`);
-        }
-        // else: Content identical - Silent skip
-      } catch (err) {
-        console.warn(`[WARN] Could not compare ${path.relative(process.cwd(), dest)}: ${err.message}`);
-      }
+      copyManagedDirectory(path.join(src, entry), path.join(dest, entry), options);
     }
+    return;
   }
-}
 
-function detectJsonIndent(content) {
-  const match = content.match(/\n([ \t]+)"[^"\n]+":/);
-  if (!match) {
-    return 2;
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+    console.log(`[NEW] ${path.relative(process.cwd(), dest)}`);
+    return;
   }
 
-  const indent = match[1];
-  return indent.includes('\t') ? '\t' : indent.length;
-}
+  try {
+    const srcContent = fs.readFileSync(src);
+    const destContent = fs.readFileSync(dest);
 
-function hasLocalHarnessBinary(targetRoot) {
-  return fs.existsSync(path.join(targetRoot, 'bin', 'harness.js'));
+    if (!force && srcContent.equals(destContent)) {
+      return;
+    }
+
+    fs.copyFileSync(src, dest);
+    console.log(`[UPDATE] ${path.relative(process.cwd(), dest)}`);
+  } catch (err) {
+    console.warn(`[WARN] Could not compare ${path.relative(process.cwd(), dest)}: ${err.message}`);
+  }
 }
 
-function getHarnessScriptCommand(targetRoot, subcommand) {
-  if (hasLocalHarnessBinary(targetRoot)) {
-    return `node bin/harness.js ${subcommand}`;
+function syncDistributedSkills(targetRoot, options = {}) {
+  const { force = false } = options;
+  const targetClaudeDir = path.join(targetRoot, '.claude');
+  const targetSkillsDir = path.join(targetClaudeDir, 'skills');
+
+  fs.mkdirSync(targetSkillsDir, { recursive: true });
+
+  for (const skillName of DISTRIBUTED_SKILLS) {
+    const sourceSkillDir = path.join(TEMPLATE_SKILLS_DIR, skillName);
+    const targetSkillDir = path.join(targetSkillsDir, skillName);
+
+    if (!fs.existsSync(sourceSkillDir)) {
+      throw new Error(`Managed skill template not found: ${sourceSkillDir}`);
+    }
+
+    copyManagedDirectory(sourceSkillDir, targetSkillDir, { force });
   }
-  return `cc-devflow harness ${subcommand}`;
 }
 
-function ensureHarnessScripts(targetRoot) {
-  const pkgPath = path.join(targetRoot, 'package.json');
-  if (!fs.existsSync(pkgPath)) {
-    console.warn(`[WARN] Missing package.json in ${targetRoot}; skipping harness script bootstrap.`);
-    return;
+function runInit(args) {
+  const { options } = parseCliArgs(args);
+
+  if (options.help) {
+    showHelp();
+    return 0;
   }
 
-  let raw;
-  let packageJson;
-  try {
-    raw = fs.readFileSync(pkgPath, 'utf8');
-    packageJson = JSON.parse(raw);
-  } catch (error) {
-    console.warn(`[WARN] Skipping harness script bootstrap: cannot parse package.json (${error.message})`);
-    return;
+  const targetRoot = path.resolve(options.dir || options.cwd || process.cwd());
+  const targetDir = path.join(targetRoot, '.claude');
+
+  if (!fs.existsSync(TEMPLATE_DIR)) {
+    console.error(`Template not found: ${TEMPLATE_DIR}`);
+    return 1;
   }
 
-  if (!packageJson || typeof packageJson !== 'object' || Array.isArray(packageJson)) {
-    console.warn('[WARN] Skipping harness script bootstrap: package.json root must be an object.');
-    return;
+  // Case 1: Directory does not exist - Create managed skill roots only
+  if (!fs.existsSync(targetDir)) {
+    syncDistributedSkills(targetRoot);
+    console.log(`Initialized managed .claude skills in ${targetRoot}`);
+    return 0;
   }
 
-  if (!packageJson.scripts || typeof packageJson.scripts !== 'object' || Array.isArray(packageJson.scripts)) {
-    packageJson.scripts = {};
+  // Case 2: Directory exists + Force - Force-upgrade managed skills only
+  if (options.force) {
+    console.log('Force flag detected. Reinstalling managed skills without deleting unrelated .claude files...');
+    syncDistributedSkills(targetRoot, { force: true });
+    console.log(`Reinstalled managed .claude skills in ${targetRoot}`);
+    return 0;
   }
 
-  const hasLocalBinary = hasLocalHarnessBinary(targetRoot);
-  const added = [];
-  const repaired = [];
-  let changed = false;
+  // Case 3: Directory exists - Incremental Update
+  console.log(`Target ${targetDir} already exists. Performing incremental update...`);
+  syncDistributedSkills(targetRoot);
+  console.log('Incremental update complete. Existing .claude files were preserved.');
+  return 0;
+}
+
+function parseConfigArgs(args) {
+  const parsed = {
+    cwd: null,
+    documentLanguage: null,
+    force: false,
+    format: 'json',
+    scope: 'project',
+    trace: false
+  };
+  const rest = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--force') {
+      parsed.force = true;
+      continue;
+    }
 
-  for (const [scriptName, subcommand] of Object.entries(HARNESS_SCRIPT_COMMANDS)) {
-    const desired = getHarnessScriptCommand(targetRoot, subcommand);
-    const existing = packageJson.scripts[scriptName];
+    if (arg === '--trace') {
+      parsed.trace = true;
+      continue;
+    }
 
-    if (typeof existing === 'undefined') {
-      packageJson.scripts[scriptName] = desired;
-      added.push(scriptName);
-      changed = true;
+    if (arg === '--user') {
+      parsed.scope = 'user';
       continue;
     }
 
-    if (typeof existing !== 'string') {
+    if (arg === '--project') {
+      parsed.scope = 'project';
       continue;
     }
 
-    // Auto-repair legacy value when local harness binary does not exist.
-    if (!hasLocalBinary && existing.trim() === `node bin/harness.js ${subcommand}`) {
-      packageJson.scripts[scriptName] = desired;
-      repaired.push(scriptName);
-      changed = true;
+    if (arg === '--local') {
+      parsed.scope = 'local';
       continue;
     }
 
-    // Auto-repair previous injected npx-based value to deterministic runtime path.
-    if (!hasLocalBinary && existing.trim() === `npx --yes cc-devflow harness ${subcommand}`) {
-      packageJson.scripts[scriptName] = desired;
-      repaired.push(scriptName);
-      changed = true;
+    if (arg === '--cwd') {
+      parsed.cwd = args[++i];
       continue;
     }
 
-    // Auto-repair previous absolute-path fallback value (not portable across machines).
-    const escapedHarnessBin = HARNESS_BIN.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const absoluteLegacy = new RegExp(`^node\\s+["']?${escapedHarnessBin}["']?\\s+${subcommand}(\\s*\\|\\|\\s*cc-devflow\\s+harness\\s+${subcommand})?$`);
-    if (!hasLocalBinary && absoluteLegacy.test(existing.trim())) {
-      packageJson.scripts[scriptName] = desired;
-      repaired.push(scriptName);
-      changed = true;
+    if (arg.startsWith('--cwd=')) {
+      parsed.cwd = arg.slice('--cwd='.length);
+      continue;
     }
+
+    if (arg === '--scope') {
+      parsed.scope = args[++i];
+      continue;
+    }
+
+    if (arg.startsWith('--scope=')) {
+      parsed.scope = arg.slice('--scope='.length);
+      continue;
+    }
+
+    if (arg === '--format') {
+      parsed.format = args[++i];
+      continue;
+    }
+
+    if (arg.startsWith('--format=')) {
+      parsed.format = arg.slice('--format='.length);
+      continue;
+    }
+
+    if (arg === '--document-language') {
+      parsed.documentLanguage = args[++i];
+      continue;
+    }
+
+    if (arg.startsWith('--document-language=')) {
+      parsed.documentLanguage = arg.slice('--document-language='.length);
+      continue;
+    }
+
+    rest.push(arg);
   }
 
-  if (!changed) {
-    return;
+  parsed.rest = rest;
+  return parsed;
+}
+
+function parseConfigOverrides(options) {
+  if (!options.documentLanguage) {
+    return {};
   }
 
-  const indent = detectJsonIndent(raw);
-  fs.writeFileSync(pkgPath, `${JSON.stringify(packageJson, null, indent)}\n`);
+  return {
+    output: {
+      document_language: options.documentLanguage
+    }
+  };
+}
 
-  if (added.length > 0) {
-    console.log(`[UPDATE] package.json (added ${added.join(', ')})`);
+function runConfig(args) {
+  const [subcommand, ...rest] = args;
+  const options = parseConfigArgs(rest);
+  const cwd = path.resolve(options.cwd || process.cwd());
+
+  if (subcommand === 'init') {
+    const configPath = writeConfigTemplate({
+      cwd,
+      force: options.force,
+      scope: options.scope
+    });
+    console.log(`Config template ready: ${configPath}`);
+    return 0;
   }
-  if (repaired.length > 0) {
-    console.log(`[UPDATE] package.json (repaired ${repaired.join(', ')})`);
+
+  if (subcommand === 'get') {
+    const keyPath = options.rest[0];
+    if (!keyPath) {
+      console.error('Config key is required.');
+      return 3;
+    }
+
+    const resolved = resolveUserConfig({
+      cwd,
+      overrides: parseConfigOverrides(options)
+    });
+    const value = getConfigValue(resolved.config, keyPath);
+    if (value === undefined) {
+      return 4;
+    }
+    process.stdout.write(`${typeof value === 'object' ? JSON.stringify(value, null, 2) : String(value)}\n`);
+    return 0;
   }
-}
 
-function runInit(args) {
-  const { options } = parseCliArgs(args);
+  if (subcommand === 'set') {
+    const [keyPath, value] = options.rest;
+    if (!keyPath || value === undefined) {
+      console.error('Use: cc-devflow config set <key> <value>');
+      return 3;
+    }
 
-  if (options.help) {
-    showHelp();
+    const configPath = setConfigValue(keyPath, value, {
+      cwd,
+      scope: options.scope
+    });
+    console.log(`Updated ${configPath}`);
     return 0;
   }
 
-  const targetRoot = path.resolve(options.dir || options.cwd || process.cwd());
-  const targetDir = path.join(targetRoot, '.claude');
+  if (subcommand === 'doctor') {
+    const result = doctorUserConfig({
+      cwd,
+      overrides: parseConfigOverrides(options)
+    });
 
-  if (!fs.existsSync(TEMPLATE_DIR)) {
-    console.error(`Template not found: ${TEMPLATE_DIR}`);
-    return 1;
+    if (result.ok) {
+      console.log('Config OK');
+      return 0;
+    }
+
+    for (const warning of result.warnings) {
+      console.error(`Config warning: ${warning}`);
+    }
+    return 2;
   }
 
-  // Case 1: Directory does not exist - Clean Install
-  if (!fs.existsSync(targetDir)) {
-    fs.cpSync(TEMPLATE_DIR, targetDir, { recursive: true });
-    ensureHarnessScripts(targetRoot);
-    console.log(`Initialized .claude in ${targetRoot}`);
-    return 0;
+  if (subcommand !== 'resolve') {
+    console.error('Unknown config command. Use: cc-devflow config init|get|set|resolve|doctor');
+    return 3;
   }
 
-  // Case 2: Directory exists + Force - Hard Reset
-  if (options.force) {
-    console.log('Force flag detected. Resetting .claude directory...');
-    fs.rmSync(targetDir, { recursive: true, force: true });
-    fs.cpSync(TEMPLATE_DIR, targetDir, { recursive: true });
-    ensureHarnessScripts(targetRoot);
-    console.log(`Re-initialized .claude in ${targetRoot}`);
+  const resolved = resolveUserConfig({
+    cwd,
+    overrides: parseConfigOverrides(options)
+  });
+
+  if (options.format === 'policy') {
+    process.stdout.write(resolved.policy || '');
+    if (options.trace) {
+      process.stdout.write('\nTrace:\n');
+      for (const entry of resolved.trace) {
+        const sourcePath = entry.path ? ` ${entry.path}` : '';
+        process.stdout.write(`- ${entry.key} = ${entry.value} (${entry.source}${sourcePath})\n`);
+      }
+    }
     return 0;
   }
 
-  // Case 3: Directory exists - Incremental Update
-  console.log(`Target ${targetDir} already exists. Performing incremental update...`);
-  copyIncremental(TEMPLATE_DIR, targetDir);
-  ensureHarnessScripts(targetRoot);
-  console.log('Incremental update complete. Existing files were preserved.');
+  if (options.format !== 'json') {
+    console.error(`Unknown config format: ${options.format}`);
+    return 3;
+  }
+
+  process.stdout.write(`${JSON.stringify(resolved, null, 2)}\n`);
   return 0;
 }
 
@@ -308,8 +449,6 @@ function runAdapt(args) {
     return 1;
   }
 
-  ensureHarnessScripts(targetRoot);
-
   const result = spawnSync(process.execPath, [ADAPT_BIN, ...rest], {
     stdio: 'inherit',
     cwd: targetRoot
@@ -323,24 +462,6 @@ function runAdapt(args) {
   return typeof result.status === 'number' ? result.status : 1;
 }
 
-function runHarness(args) {
-  const { options, rest } = parseCliArgs(args);
-
-  const targetRoot = path.resolve(options.cwd || process.cwd());
-  const cliArgs = options.help || rest.length === 0 ? ['--help'] : rest;
-  const result = spawnSync(process.execPath, [HARNESS_BIN, ...cliArgs], {
-    stdio: 'inherit',
-    cwd: targetRoot
-  });
-
-  if (result.error) {
-    console.error(`Failed to run harness: ${result.error.message}`);
-    return 1;
-  }
-
-  return typeof result.status === 'number' ? result.status : 1;
-}
-
 function runAdapter(command, args) {
   const result = spawnSync(process.execPath, [ADAPTER_BIN, command, ...args], {
     stdio: 'inherit'
@@ -371,8 +492,8 @@ function main() {
     return runAdapt(rest);
   }
 
-  if (command === 'harness') {
-    return runHarness(rest);
+  if (command === 'config') {
+    return runConfig(rest);
   }
 
   return runAdapter(command, rest);

package/config/distributable-skills.json

@@ -0,0 +1,24 @@
+{
+  "publicSkills": [
+    "cc-roadmap",
+    "cc-plan",
+    "cc-investigate",
+    "cc-do",
+    "cc-check",
+    "cc-act"
+  ],
+  "distributedSkills": [
+    "cc-roadmap",
+    "cc-plan",
+    "cc-investigate",
+    "cc-do",
+    "cc-check",
+    "cc-act",
+    "cc-spec-init",
+    "cc-simplify"
+  ],
+  "internalSkills": [
+    "docs-sync",
+    "npm-release"
+  ]
+}

package/config/schema/cc-devflow-config.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CC-DevFlow User Config",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "integer",
+      "enum": [1]
+    },
+    "output": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "document_language": {
+          "type": "string",
+          "enum": ["en", "zh-CN"]
+        }
+      }
+    },
+    "agent_preferences": {
+      "type": "object",
+      "description": "Advisory user preferences. These can be non-standard, but they do not override workflow contracts.",
+      "additionalProperties": {
+        "oneOf": [
+          { "type": "string" },
+          { "type": "number" },
+          { "type": "boolean" },
+          {
+            "type": "array",
+            "items": {
+              "type": ["string", "number", "boolean", "object", "array", "null"]
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": true
+          },
+          { "type": "null" }
+        ]
+      }
+    }
+  },
+  "required": ["version"]
+}