clckernel 1.2.19 → 2.0.1

package/src/config.js

@@ -1,250 +1,48 @@
 /**
- * CLC Kernel - extended .clckernel.yml / .clc-forge.yml loader / validator / resolver.
- * Backbone = src/catalog.js. Invalid config -> actionable ConfigError;
- * never a silent fallback.
+ * CLC Kernel - .clckernel.yaml for install and update.
+ * The schema lives in tools/_config.js, which the guards use too: one
+ * validator for the kernel and the project. Invalid config -> ConfigError
+ * naming the file and the key; never a silent fallback.
  */
 
-const { parseYaml } = require('../tools/yaml.js');
 const {
-  SAFEGUARD_CATALOG,
-  VALID_SEVERITIES,
-  VALID_GATE_MODES,
-  applyTo,
-  severityFor,
-} = require('./catalog.js');
+  ConfigError,
+  CONFIG_NAMES,
+  DEPRECATED_KEYS,
+  defaultConfig,
+  validateConfig,
+  parseConfigText,
+  loadConfig: loadProjectConfig,
+  globMatcher,
+} = require('../tools/_config.js');
 
 /**
- * Canonical 10-phase workflow order (design §3.1). NOTE: catalog VALID_PHASES
- * is the per-entry `phase` field, NOT this workflow — the `phases` config key
- * validates against this list.
+ * Parses config text into its raw mapping ({} for an empty document).
+ * @param {string} yamlString
+ * @param {string} [file] - Config file name, for messages
+ * @returns {object}
+ * @throws {ConfigError}
  */
-const HARNESS_PHASES = [
-  'research', 'plan', 'test-scenarios', 'hit', 'tdd-red',
-  'green', 'audit', 'rdd-review', 'handover', 'close',
-];
-
-const ENV_SEVERITIES = 'CLCKERNEL_SEVERITIES';
-const LEGACY_ENV_SEVERITIES = 'CLC_FORGE_SEVERITIES';
-const DEFAULT_SCOPE = '.';
-
-class ConfigError extends Error {
-  constructor(path, message, allowed) {
-    const list = Array.isArray(allowed) ? allowed : allowed != null ? [allowed] : [];
-    super(
-      `Invalid .clckernel.yml: key "${path}" — ${message}` +
-        (list.length ? ` (allowed: ${list.join(', ')})` : '')
-    );
-    this.name = 'ConfigError';
-    this.path = path;
-    this.allowed = list;
-    this.fix =
-      list.length
-        ? `Set "${path}" to one of: ${list.join(', ')}. ${message}`
-        : `Correct the value of "${path}". ${message}`;
-  }
-}
-
-function arrOrThrow(raw, path, what) {
-  if (!Array.isArray(raw)) throw new ConfigError(path, `expected an array, got ${raw === null ? 'null' : typeof raw}`, what);
-  if (!raw.length) throw new ConfigError(path, 'must not be empty', what);
-}
-
-function strItems(arr, base) {
-  arr.forEach((v, i) => {
-    if (typeof v !== 'string' || v.trim() === '') {
-      throw new ConfigError(`${base}[${i}]`, 'each item must be a non-empty string');
-    }
-  });
-  return arr;
-}
-
-function listGuards() {
-  return SAFEGUARD_CATALOG.map((e) => e.name);
-}
-
-function validateConfig(raw) {
-  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
-    throw new ConfigError('<root>', 'expected a YAML mapping (object)');
-  }
-
-  const { active_guards, gate_mode, severities, phases, scope, exclude_paths, layers, rules } = raw;
-
-  if (active_guards !== undefined) {
-    arrOrThrow(active_guards, 'active_guards', 'a list of catalog guard names');
-    active_guards.forEach((name, i) => {
-      if (typeof name !== 'string' || name.trim() === '') throw new ConfigError(`active_guards[${i}]`, 'each active guard must be a non-empty string');
-      if (!applyTo(name)) throw new ConfigError(`active_guards[${i}]`, `unknown guard "${name}"`, listGuards());
-    });
-  }
-
-  if (gate_mode !== undefined && (typeof gate_mode !== 'string' || !VALID_GATE_MODES.includes(gate_mode))) {
-    throw new ConfigError('gate_mode', `invalid value "${gate_mode}"`, VALID_GATE_MODES);
-  }
-
-  if (severities !== undefined) {
-    if (!severities || typeof severities !== 'object' || Array.isArray(severities)) {
-      throw new ConfigError('severities', 'expected an object mapping guard -> severity');
-    }
-    for (const [name, severity] of Object.entries(severities)) {
-      if (!applyTo(name)) throw new ConfigError(`severities.${name}`, `unknown guard "${name}"`, listGuards());
-      if (!VALID_SEVERITIES.includes(severity)) throw new ConfigError(`severities.${name}`, `invalid severity "${severity}"`, VALID_SEVERITIES);
-    }
-  }
-
-  if (phases !== undefined) {
-    arrOrThrow(phases, 'phases', 'the canonical 10-phase workflow names');
-    let last = -1;
-    phases.forEach((phase, i) => {
-      if (typeof phase !== 'string' || phase.trim() === '') throw new ConfigError(`phases[${i}]`, 'each phase must be a non-empty string');
-      const idx = HARNESS_PHASES.indexOf(phase);
-      if (idx === -1) throw new ConfigError(`phases[${i}]`, `unknown phase "${phase}"`, HARNESS_PHASES);
-      if (idx <= last) throw new ConfigError(`phases[${i}]`, `phase "${phase}" is out of order — canonical order is ${HARNESS_PHASES.join(' → ')}`);
-      last = idx;
-    });
-  }
-
-  if (scope !== undefined) {
-    const items = typeof scope === 'string' ? [scope] : scope;
-    arrOrThrow(items, 'scope', 'a glob string or array of glob strings');
-    strItems(items, 'scope');
-  }
-
-  if (exclude_paths !== undefined) { arrOrThrow(exclude_paths, 'exclude_paths', 'an array of glob strings'); strItems(exclude_paths, 'exclude_paths'); }
-  if (layers !== undefined) { arrOrThrow(layers, 'layers', 'an array of layer name strings'); strItems(layers, 'layers'); }
-
-  if (rules !== undefined) {
-    arrOrThrow(rules, 'rules', 'an array of legacy rule objects');
-    const seen = new Set();
-    rules.forEach((rule, i) => {
-      if (!rule || typeof rule !== 'object' || Array.isArray(rule)) throw new ConfigError(`rules[${i}]`, 'each rule must be an object');
-      if (typeof rule.name !== 'string' || rule.name.trim() === '') throw new ConfigError(`rules[${i}]`, 'each rule requires a non-empty "name"');
-      if (seen.has(rule.name)) throw new ConfigError(`rules[${i}].name`, `duplicate rule name "${rule.name}"`);
-      seen.add(rule.name);
-      if (rule.severity !== undefined && !['error', 'warning'].includes(rule.severity)) {
-        throw new ConfigError(`rules[${i}].severity`, `invalid severity "${rule.severity}"`, ['error', 'warning']);
-      }
-    });
-  }
-
-  return raw;
-}
-
-const loadConfig = (yamlString) => {
-  if (yamlString === undefined || yamlString === null || yamlString.trim() === '') return {};
-  let raw;
-  try { raw = parseYaml(yamlString); } catch (err) { throw new ConfigError('<root>', `YAML parse error: ${err.message}`); }
-  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new ConfigError('<root>', 'expected a YAML mapping (object) at the top level');
-  return raw;
-};
-
-/** Env override map (tolerant: malformed JSON/non-object ignored). */
-function envSeverities() {
-  const raw =
-    process.env[ENV_SEVERITIES] ||
-    process.env.CLC_KERNEL_SEVERITIES ||
-    process.env[LEGACY_ENV_SEVERITIES];
-  if (!raw) return {};
-  try {
-    const parsed = JSON.parse(raw);
-    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed;
-  } catch { /* ignore malformed env override */ }
-  return {};
-}
-
-/** Catalog names among detected.techTools (design §1.3 JOIN rule). */
-function detectedToolNames(detected) {
-  const names = new Set();
-  if (!detected || !Array.isArray(detected.techTools)) return names;
-  for (const tool of detected.techTools) {
-    const name = tool && typeof tool === 'object' ? tool.name : tool;
-    const entry = applyTo(name);
-    if (entry) names.add(entry.name);
-  }
-  return names;
-}
-
-/** True when a catalog row applies to the detected stack. */
-function rowApplies(row, detected, detectedTools) {
-  if (row.applies_when === 'always') return true;
-  if (!detected || typeof detected !== 'object') return false;
-  if (detectedTools && detectedTools.has(row.name)) return true;
-  const deps = new Set(
-    [detected.projectType, detected.framework, detected.orm]
-      .filter((x) => typeof x === 'string')
-      .map((x) => x.toLowerCase())
-  );
-  for (const alt of row.applies_when.split('|')) {
-    for (const tok of alt.split(',')) {
-      const t = tok.trim();
-      if (t && deps.has(t)) return true;
-    }
-  }
-  return false;
-}
+const loadConfig = (yamlString, file) => parseConfigText(yamlString, file);
 
 /**
- * Generation-time severity precedence: env CLC_FORGE_SEVERITIES > config
- * severities > catalog default > 'error'. (Guard-result still wins at runtime
- * audit — slice C.)
+ * Reads, validates and defaults the config of the project at dir (fresh
+ * read: install and update must see the file as it is now).
+ * @param {string} dir - Project root
+ * @returns {{ file: string|null, path: string|null, config: object, warnings: string[] }}
+ * @throws {ConfigError}
  */
-function resolveSeverity(name, configSeverities, envMap) {
-  if (envMap[name] && VALID_SEVERITIES.includes(envMap[name])) return envMap[name];
-  if (configSeverities[name] && VALID_SEVERITIES.includes(configSeverities[name])) return configSeverities[name];
-  const cat = severityFor(name);
-  if (cat && VALID_SEVERITIES.includes(cat)) return cat;
-  return 'error';
-}
-
-/**
- * Effective resolved config (catalog defaults merged with overrides).
- * @param {object} raw - validated raw config.
- * @param {object} [detected] - autoDetectStack output (optional; {} when unknown).
- */
-function resolveConfig(raw, detected) {
-  const validated = validateConfig(raw);
-  const gateMode = validated.gate_mode === undefined ? 'hard' : validated.gate_mode;
-  const phases = validated.phases === undefined ? HARNESS_PHASES.slice() : validated.phases;
-  const detectedTools = detectedToolNames(detected);
-  const base = SAFEGUARD_CATALOG.filter((row) => rowApplies(row, detected, detectedTools));
-  const active =
-    Array.isArray(validated.active_guards) && validated.active_guards.length
-      ? validated.active_guards
-      : base.map((row) => row.name);
-  const configSeverities = validated.severities || {};
-  const envMap = envSeverities();
-
-  const effectiveSeverities = {};
-  const __catalog = active.map((name) => {
-    const entry = applyTo(name);
-    const severity = resolveSeverity(name, configSeverities, envMap);
-    effectiveSeverities[name] = severity;
-    return {
-      name,
-      checks: entry ? entry.checks : undefined,
-      applies_when: entry ? entry.applies_when : undefined,
-      severity,
-      gate_mode: gateMode === 'advisory' ? 'advisory' : entry ? entry.gate_mode : 'hard',
-      file: entry ? entry.file : null,
-      manifest: entry ? entry.manifest : false,
-      planned: entry ? entry.planned : false,
-      config_keys: entry ? entry.config_keys : [],
-    };
-  });
-
-  return {
-    activeGuards: active,
-    phases,
-    gateMode,
-    effectiveSeverities,
-    layers: validated.layers || [],
-    scope: validated.scope === undefined ? DEFAULT_SCOPE : validated.scope,
-    excludePaths: validated.exclude_paths || [],
-    framework: detected && detected.framework ? detected.framework : 'unknown',
-    projectType: detected && detected.projectType ? detected.projectType : 'unknown',
-    testRunner: detected && detected.testRunner ? detected.testRunner : 'unknown',
-    rules: validated.rules || [],
-    __catalog,
-  };
-}
-
-module.exports = { loadConfig, validateConfig, resolveConfig, ConfigError, HARNESS_PHASES, ENV_SEVERITIES, DEFAULT_SCOPE };
+function readProjectConfig(dir) {
+  return loadProjectConfig(dir, { cache: false });
+}
+
+module.exports = {
+  ConfigError,
+  CONFIG_NAMES,
+  DEPRECATED_KEYS,
+  defaultConfig,
+  loadConfig,
+  validateConfig,
+  readProjectConfig,
+  globMatcher,
+};

package/src/detector.js

@@ -1,5 +1,5 @@
 /**
- * CLC Forge — Universal Auto-Discovery Engine
+ * CLC Kernel — Universal Auto-Discovery Engine
  * Inspects repository signatures to auto-match the right polyglot Stack Adapter
  * (Next.js, FastAPI, Django, Astro, Rails, Go, Rust, Laravel).
  */
@@ -30,58 +30,257 @@ const adapters = [
   new LaravelAdapter()
 ];
 
-function autoDetectStack(targetDir) {
-  // 1. Check registered polyglot adapters
+/**
+ * Builds the project config for a given adapter, exactly as auto-detection
+ * does for a matched adapter. A null adapter yields the generic config.
+ * Used by autoDetectStack and by the "Elegir otro stack" prompt, so a stack
+ * chosen by hand provisions exactly what a detected one would.
+ * @param {string} targetDir - Project root
+ * @param {object|null} adapter - One of `adapters`, or null for generic
+ * @returns {object} Project config
+ */
+function buildStackConfig(targetDir, adapter) {
+  // Phase-1 technologies (Celery, Redis, PostgreSQL, Docker)
+  const techDetector = new TechnologyDetector();
+  const detectedTechs = techDetector.detect(targetDir);
+  const techTools = techDetector.getToolsForTech(detectedTechs);
+  const gitHooks = fs.existsSync(path.join(targetDir, '.husky')) ? 'husky' : 'githooks';
+
+  if (!adapter) {
+    // No adapter: report the stack as unknown instead of guessing one; the
+    // generator installs a generic, stack-agnostic harness.
+    return {
+      projectType: 'unknown',
+      framework: 'unknown',
+      styling: 'none',
+      uiLibrary: 'none',
+      testRunner: 'unknown',
+      gitHooks,
+      orm: 'none',
+      adapter: null,
+      techTools
+    };
+  }
+
+  return {
+    projectType: adapter.projectType,
+    framework: adapter.name,
+    styling: adapter.projectType === 'frontend' ? 'Tailwind CSS v4' : 'N/A',
+    uiLibrary: adapter.projectType === 'frontend' ? 'Component Primitives' : 'N/A',
+    testRunner: adapter.testRunner,
+    gitHooks,
+    orm: 'Framework Native',
+    adapter,
+    techTools
+  };
+}
+
+/** Ecosystem of each code adapter: one directory gets at most one part per ecosystem. */
+const ECOSYSTEMS = {
+  'Next.js (App Router)': 'node',
+  'Astro Framework': 'node',
+  'FastAPI Framework': 'python',
+  'Django Framework': 'python',
+  'Ruby on Rails': 'ruby',
+  'Go (Golang)': 'go',
+  'Rust Engine': 'rust',
+  'PHP / Laravel': 'php',
+};
+
+/** Conventional part locations: a literal dir or `dir/*` (one level below dir). */
+const CONVENTIONAL_PART_DIRS = [
+  'frontend', 'backend', 'web', 'api', 'server', 'client', 'apps/*', 'services/*', 'packages/*',
+];
+
+/** Directories never inspected as parts. */
+const SKIPPED_DIRS = new Set(['node_modules', '.git', 'vendor', 'dist', 'build']);
+
+/** Maximum depth of a part below the root (`apps/web` is 2). */
+const MAX_PART_DEPTH = 2;
+
+/**
+ * Part dirs go into the hook inside quotes; only plain relative names are
+ * accepted so no quoting or expansion can ever be involved.
+ */
+const SAFE_PART_DIR = /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/;
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Workspace patterns declared by the root: package.json `workspaces` (array
+ * or `{ packages }`) and pnpm-workspace.yaml `packages:` entries.
+ * @param {string} targetDir - Project root
+ * @returns {string[]}
+ */
+function workspacePatterns(targetDir) {
+  const patterns = [];
+  const pkg = readJson(path.join(targetDir, 'package.json'));
+  const ws = pkg && pkg.workspaces;
+  const list = Array.isArray(ws) ? ws : (ws && Array.isArray(ws.packages) ? ws.packages : []);
+  patterns.push(...list.filter((p) => typeof p === 'string'));
+
+  let yaml = '';
+  try {
+    yaml = fs.readFileSync(path.join(targetDir, 'pnpm-workspace.yaml'), 'utf-8');
+  } catch {
+    return patterns;
+  }
+  let inPackages = false;
+  for (const raw of yaml.split(/\r?\n/)) {
+    const line = raw.replace(/\s+#.*$/, '').replace(/^#.*$/, '');
+    if (/^\S/.test(line)) {
+      inPackages = /^packages\s*:\s*$/.test(line);
+      continue;
+    }
+    const item = inPackages && line.match(/^\s+-\s+(['"]?)([^'"]+)\1\s*$/);
+    if (item) patterns.push(item[2].trim());
+  }
+  return patterns;
+}
+
+/**
+ * Directories a pattern names: a literal relative dir, or `dir/*` for every
+ * subdirectory of dir. Other glob forms (`**`, `{a,b}`, negations) are
+ * ignored: there is no glob engine here, on purpose.
+ * @param {string} targetDir - Project root
+ * @param {string} pattern - Workspace or conventional pattern
+ * @returns {string[]} Relative dirs (posix separators)
+ */
+function expandPattern(targetDir, pattern) {
+  const clean = pattern.replace(/^\.\//, '').replace(/\/+$/, '');
+  const star = clean.match(/^([^*?[\]{}!]+)\/\*$/);
+  if (star) {
+    const base = star[1];
+    let entries;
+    try {
+      entries = fs.readdirSync(path.join(targetDir, base), { withFileTypes: true });
+    } catch {
+      return [];
+    }
+    return entries.filter((e) => e.isDirectory()).map((e) => `${base}/${e.name}`);
+  }
+  return /[*?[\]{}!]/.test(clean) || !clean ? [] : [clean];
+}
+
+/** True when rel is a directory worth inspecting as a part. */
+function isCandidateDir(targetDir, rel) {
+  const segments = rel.split('/');
+  if (segments.length > MAX_PART_DEPTH || !SAFE_PART_DIR.test(rel)) return false;
+  if (segments.some((s) => SKIPPED_DIRS.has(s) || s === '.' || s === '..')) return false;
+  try {
+    return fs.lstatSync(path.join(targetDir, rel)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** Code adapters (never Agent-OS) matching dir, at most one per ecosystem, in list order. */
+function codeAdaptersFor(dir) {
+  const seen = new Set();
+  const found = [];
   for (const adapter of adapters) {
-    if (adapter.detect(targetDir)) {
-      // Detect Phase-1 technologies (Celery, Redis, PostgreSQL, Docker)
-      const techDetector = new TechnologyDetector();
-      const detectedTechs = techDetector.detect(targetDir);
-      const techTools = techDetector.getToolsForTech(detectedTechs);
-
-      return {
-        projectType: adapter.projectType,
-        framework: adapter.name,
-        styling: adapter.projectType === 'frontend' ? 'Tailwind CSS v4' : 'N/A',
-        uiLibrary: adapter.projectType === 'frontend' ? 'Component Primitives' : 'N/A',
-        testRunner: adapter.testRunner,
-        gitHooks: fs.existsSync(path.join(targetDir, '.husky')) ? 'husky' : 'githooks',
-        orm: 'Framework Native',
-        adapter,
-        techTools
-      };
+    if (adapter.projectType === 'agent-os' || !adapter.detect(dir)) continue;
+    const ecosystem = ECOSYSTEMS[adapter.name] || adapter.name;
+    if (seen.has(ecosystem)) continue;
+    seen.add(ecosystem);
+    found.push(adapter);
+  }
+  return found;
+}
+
+/**
+ * Code parts of a repository (sdds/fullstack-monorepo, decision 1): the root,
+ * declared workspaces and conventional dirs, each tested against the code
+ * adapters. Agent-OS is never a part. Root parts come first, then subdir
+ * parts sorted by dir.
+ * @param {string} targetDir - Project root
+ * @returns {Array<{dir: string, adapter: object}>}
+ */
+function detectParts(targetDir) {
+  const parts = codeAdaptersFor(targetDir).map((adapter) => ({ dir: '.', adapter }));
+  const dirs = new Set();
+  for (const pattern of [...workspacePatterns(targetDir), ...CONVENTIONAL_PART_DIRS]) {
+    for (const rel of expandPattern(targetDir, pattern)) {
+      if (isCandidateDir(targetDir, rel)) dirs.add(rel);
     }
   }
+  for (const rel of [...dirs].sort()) {
+    for (const adapter of codeAdaptersFor(path.join(targetDir, rel))) parts.push({ dir: rel, adapter });
+  }
+  return parts;
+}
 
-  // 2. Fallback detection
+/** Technology tools detected in the root and every part dir, deduplicated by name. */
+function partsTechTools(targetDir, parts) {
   const techDetector = new TechnologyDetector();
-  const detectedTechs = techDetector.detect(targetDir);
-  const techTools = techDetector.getToolsForTech(detectedTechs);
+  const tools = [];
+  const names = new Set();
+  const dirs = ['.', ...parts.map((p) => p.dir)];
+  for (const rel of [...new Set(dirs)]) {
+    for (const tool of techDetector.getToolsForTech(techDetector.detect(path.join(targetDir, rel)))) {
+      if (names.has(tool.name)) continue;
+      names.add(tool.name);
+      tools.push(tool);
+    }
+  }
+  return tools;
+}
 
-  const config = {
-    projectType: 'unknown',
-    framework: 'unknown',
-    styling: 'none',
-    uiLibrary: 'none',
-    testRunner: 'unknown',
+/**
+ * Config of a multi-part repository. `adapter` and `framework` are the first
+ * part's, kept for code that reads one stack; `parts` drives provisioning.
+ * projectType is 'monorepo' when no part sits at the root, else 'fullstack'.
+ * @param {string} targetDir - Project root
+ * @param {Array<{dir: string, adapter: object}>} parts - From detectParts
+ * @returns {object} Project config
+ */
+function buildPartsConfig(targetDir, parts) {
+  const hasFront = parts.some((p) => p.adapter.projectType === 'frontend');
+  return {
+    projectType: parts.some((p) => p.dir === '.') ? 'fullstack' : 'monorepo',
+    // The first part's name, like `adapter`: code that reads one framework
+    // keeps working; `parts` lists all of them.
+    framework: parts[0].adapter.name,
+    styling: hasFront ? 'Tailwind CSS v4' : 'N/A',
+    uiLibrary: hasFront ? 'Component Primitives' : 'N/A',
+    testRunner: parts.map((p) => `${p.adapter.testRunner} (${p.dir})`).join(', '),
     gitHooks: fs.existsSync(path.join(targetDir, '.husky')) ? 'husky' : 'githooks',
-    orm: 'none',
-    adapter: null,
-    techTools
+    orm: 'Framework Native',
+    adapter: parts[0].adapter,
+    parts: parts.map((p) => ({
+      dir: p.dir,
+      adapter: p.adapter,
+      framework: p.adapter.name,
+      projectType: p.adapter.projectType,
+      testRunner: p.adapter.testRunner,
+    })),
+    techTools: partsTechTools(targetDir, parts),
   };
+}
 
-  if (fs.existsSync(path.join(targetDir, 'src', 'app')) || fs.existsSync(path.join(targetDir, 'src', 'pages'))) {
-    config.projectType = 'frontend';
-    config.framework = 'Next.js';
-    config.testRunner = 'Vitest';
-    config.styling = 'Tailwind CSS v4';
-  } else {
-    config.projectType = 'backend';
-    config.framework = 'FastAPI';
-    config.testRunner = 'Pytest';
+/**
+ * Detects the project config. One code part at the root (or none) keeps the
+ * single-stack config exactly as before: adapters are tried in list order,
+ * except that a code stack beats Agent-OS (sdds/agent-os-generic, decision 1).
+ * Several parts, or a part in a subdir, yield a multi-part config
+ * (sdds/fullstack-monorepo).
+ * @param {string} targetDir - Project root
+ * @returns {object} Project config
+ */
+function autoDetectStack(targetDir) {
+  const parts = detectParts(targetDir);
+  if (parts.length > 1 || (parts.length === 1 && parts[0].dir !== '.')) {
+    return buildPartsConfig(targetDir, parts);
   }
-
-  return config;
+  const matched = adapters.filter((a) => a.detect(targetDir));
+  const adapter = matched.find((a) => a.projectType !== 'agent-os') || matched[0] || null;
+  return buildStackConfig(targetDir, adapter);
 }
 
-module.exports = { autoDetectStack };
+module.exports = { autoDetectStack, buildStackConfig, detectParts, adapters };

package/src/doctor.js

@@ -6,9 +6,17 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execSync } = require('child_process');
+const { spawnSync } = require('child_process');
+
+/** Parses the file given as argv[1]; the path never touches a shell. */
+const PY_PARSE_SCRIPT = 'import ast, sys\nast.parse(open(sys.argv[1]).read())';
 const { colors } = require('./ui');
 
+/**
+ * Runs every health check against targetDir and prints the results.
+ * @param {string} targetDir - Project to inspect
+ * @returns {number} Number of failed checks (0 means healthy)
+ */
 function runDoctor(targetDir) {
   console.log(`\n${colors.bold}${colors.cyan}CLC KERNEL DOCTOR — HEALTH CHECK${colors.reset}\n`);
   console.log(`  Target Repository: ${colors.cyan}${targetDir}${colors.reset}\n`);
@@ -52,14 +60,14 @@ function runDoctor(targetDir) {
 
       // Parse-test Python guard scripts via ast.parse()
       if (file.endsWith('.py') && file.startsWith('check_')) {
-        try {
-          execSync(
-            `python3 -c "import ast; ast.parse(open('${toolPath}').read())"`,
-            { stdio: 'pipe' }
-          );
+        const res = spawnSync('python3', ['-c', PY_PARSE_SCRIPT, toolPath], { encoding: 'utf-8' });
+        if (!res.error && res.status === 0) {
           checks.push({ name: `tool/${file} parses`, status: true });
-        } catch (e) {
-          checks.push({ name: `tool/${file} parses`, status: false, detail: e.message });
+        } else {
+          const detail = res.error
+            ? res.error.message
+            : (res.stderr || '').trim().split('\n').pop() || `python3 exited ${res.status}`;
+          checks.push({ name: `tool/${file} parses`, status: false, detail });
         }
       }
     });
@@ -116,10 +124,11 @@ function runDoctor(targetDir) {
 
   console.log('\n---------------------------------------------------------------');
   if (passedCount === checks.length) {
-    console.log(` ${colors.bgEmerald} HEALTHY ${colors.reset} ${colors.emerald}${colors.bold}Repository meets 100% of the CLC Kernel standard.${colors.reset}\n`);
+    console.log(` ${colors.bgEmerald} HEALTHY ${colors.reset} ${colors.emerald}${colors.bold}All ${checks.length} doctor checks passed.${colors.reset}\n`);
   } else {
     console.log(` ${colors.amber}  ${checks.length - passedCount} issue(s) detected. Run \`npx clckernel\` to repair.${colors.reset}\n`);
   }
+  return checks.length - passedCount;
 }
 
 module.exports = { runDoctor };