claudeos-core 1.6.0 → 1.6.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [1.6.1] — 2026-04-09
+
+### Fixed
+
+- **Path traversal hardening (Windows)** — `plan-validator` and `sync-checker` now use case-insensitive path comparison on Windows, preventing UNC/case-mismatch bypass of root boundary check
+- **Null pointer crash in `stack-detector.js`** — `readFileSafe()` return value for `pnpm-workspace.yaml` now guarded; prevents crash when file exists but is unreadable
+- **Empty pass3 prompt generation** — `prompt-generator.js` now early-returns with warning when pass3 template is missing, instead of silently writing header+footer-only prompt
+- **Domain group boundary off-by-one** — `splitDomainGroups` changed `>=` to `>` for file count threshold; groups now fill up to exactly `MAX_FILES_PER_GROUP` (40) instead of flushing one file early
+- **Perl regex injection in `bootstrap.sh`** — All placeholder substitution migrated from `perl -pi -e` to Node.js `String.replace()`; eliminates regex special character risk in domain names; `perl` is no longer a prerequisite
+- **Flask default port** — `plan-installer` now maps Flask to port 5000 (was falling through to 8080)
+- **Health-checker dependency chain** — `sync-checker` is now automatically skipped when `manifest-generator` fails, instead of running against missing `sync-map.json`
+- **`pass-json-validator` null template crash** — Added null guard before `typeof` check; `null` no longer passes `typeof === "object"` gate
+- **`pass-json-validator` missing backend frameworks** — Added `"fastify"` and `"flask"` to backend framework list; these stacks previously skipped backend section validation
+- **Init error messages** — Pass 1/2/3 failure messages now include actionable guidance (check output above, retry with `--force`, verify prompt file)
+- **Manifest-generator error context** — `.catch()` handler now prefixes error with tool name
+- **Line counting off-by-one** — `statSafe()` and `manifest-generator stat()` no longer count trailing newline as an extra line
+- **Windows CRLF drift** — `plan-validator` now normalizes `\r\n` → `\n` before content comparison; prevents false drift on Windows
+- **`stale-report.js` mutation** — `Object.assign(ex.summary, patch)` replaced with spread operator to avoid in-place mutation
+- **Undefined in sync-checker Set** — Malformed mappings with missing `sourcePath` no longer insert `undefined` into the registered paths Set
+- **BOM frontmatter detection** — `content-validator` now strips UTF-8 BOM (`\uFEFF`) before checking `---` frontmatter marker
+- **Health-checker stderr loss** — Error output now combines both `stdout` and `stderr` instead of preferring one
+- **`bootstrap.sh` exit code preservation** — EXIT trap now captures and restores `$?` instead of always exiting 0
+- **`bootstrap.sh` NODE_MAJOR stderr** — `node -e` stderr redirected to `/dev/null` to prevent parse failure from noise
+
 ## [1.6.0] — 2026-04-08
 
 ### Added

package/bin/commands/init.js

@@ -242,11 +242,11 @@ async function cmdInit(parsedArgs) {
     const elapsed1 = formatElapsed(Date.now() - t1);
 
     if (!ok) {
-      throw new InitError(`Pass 1-${i} failed`);
+      throw new InitError(`Pass 1-${i} failed. Check the claude error output above.\n    If this persists, try: npx claudeos-core init --force`);
     }
 
     if (!fileExists(pass1Json)) {
-      throw new InitError(`pass1-${i}.json was not created`);
+      throw new InitError(`pass1-${i}.json was not created. Claude may have run but not produced expected output.\n    Ensure the prompt instructs Claude to write to claudeos-core/generated/pass1-${i}.json`);
     }
 
     log(`    ✅ pass1-${i}.json created (${elapsed1})`);
@@ -272,11 +272,11 @@ async function cmdInit(parsedArgs) {
     const elapsed2 = formatElapsed(Date.now() - t2);
 
     if (!ok) {
-      throw new InitError("Pass 2 failed");
+      throw new InitError("Pass 2 failed. Check the claude error output above.\n    If this persists, try: npx claudeos-core init --force");
     }
 
     if (!fileExists(pass2Json)) {
-      throw new InitError("pass2-merged.json was not created");
+      throw new InitError("pass2-merged.json was not created. Claude may have run but not produced expected output.");
     }
 
     log(`    ✅ pass2-merged.json created (${elapsed2})`);
@@ -298,11 +298,11 @@ async function cmdInit(parsedArgs) {
   const elapsed3 = formatElapsed(Date.now() - t3);
 
   if (!ok3) {
-    throw new InitError("Pass 3 failed");
+    throw new InitError("Pass 3 failed. Check the claude error output above.\n    If this persists, try: npx claudeos-core init --force");
   }
 
   if (!fileExists(path.join(PROJECT_ROOT, "CLAUDE.md"))) {
-    throw new InitError("CLAUDE.md was not created. Pass 3 may have failed silently.");
+    throw new InitError("CLAUDE.md was not created. Claude ran but did not produce CLAUDE.md.\n    Verify pass3-prompt.md instructs Claude to create CLAUDE.md at project root.");
   }
   log(`    ✅ Pass 3 complete (${elapsed3})`);
   log("");

package/bootstrap.sh

@@ -5,8 +5,8 @@
 # One-click full system auto-build
 # Automatically splits Pass 1 into N runs based on project size
 #
-# Prerequisites: bash, node (v18+), claude CLI, perl
-# For cross-platform use without perl, use: node bin/cli.js init
+# Prerequisites: bash, node (v18+), claude CLI
+# Cross-platform alternative: node bin/cli.js init
 #
 # Usage: bash claudeos-core-tools/bootstrap.sh --lang ko
 #        bash claudeos-core-tools/bootstrap.sh              (interactive)
@@ -27,7 +27,7 @@ GENERATED_DIR="$PROJECT_ROOT/claudeos-core/generated"
 cd "$PROJECT_ROOT"
 
 # Cleanup temp files on exit (Ctrl+C, errors, etc.)
-trap 'rm -f "$GENERATED_DIR"/_tmp_*.md "$GENERATED_DIR"/_tmp_*.md.final 2>/dev/null' EXIT
+trap 'rc=$?; rm -f "$GENERATED_DIR"/_tmp_*.md "$GENERATED_DIR"/_tmp_*.md.final 2>/dev/null; exit $rc' EXIT
 
 # ─── Language selection (required) ──────────────────────────────
 SUPPORTED_LANGS=("en" "ko" "zh-CN" "ja" "es" "vi" "hi" "ru" "fr" "de")
@@ -97,7 +97,7 @@ if ! command -v node &> /dev/null; then
   exit 1
 fi
 
-NODE_MAJOR=$(node -e "console.log(process.versions.node.split('.')[0])")
+NODE_MAJOR=$(node -e "console.log(process.versions.node.split('.')[0])" 2>/dev/null)
 if ! [[ "$NODE_MAJOR" =~ ^[0-9]+$ ]] || [ "$NODE_MAJOR" -lt 18 ]; then
   echo ""
   echo "  ❌ Node.js v18+ required (current: v$(node --version))"
@@ -115,13 +115,7 @@ if ! command -v claude &> /dev/null; then
   exit 1
 fi
 
-if ! command -v perl &> /dev/null; then
-  echo ""
-  echo "  ❌ perl not found (required for placeholder substitution)."
-  echo "  Install perl or use the Node.js CLI instead: npx claudeos-core init"
-  echo ""
-  exit 1
-fi
+## perl is no longer required — placeholder substitution now uses Node.js
 
 
 
@@ -246,18 +240,20 @@ for i in $(seq 1 "$TOTAL_GROUPS"); do
   if [ ! -f "$PROMPT_FILE" ]; then
     PROMPT_FILE="$GENERATED_DIR/pass1-prompt.md"
   fi
-  # Substitute placeholders via temp file (avoids sed special char issues and $() newline stripping)
+  # Substitute placeholders via temp file (uses Node.js for safe literal replacement)
   TMP_PROMPT="$GENERATED_DIR/_tmp_pass1_prompt.md"
   cp "$PROMPT_FILE" "$TMP_PROMPT"
-  # Use perl with $ENV{} for safe literal replacement (no shell interpolation into Perl code)
   export _DOMAIN_LIST="$DOMAIN_LIST"
   export _PASS_NUM="$i"
-  perl -pi -e 's/\{\{DOMAIN_GROUP\}\}/$ENV{_DOMAIN_LIST}/g' "$TMP_PROMPT"
-  perl -pi -e 's/\{\{PASS_NUM\}\}/$ENV{_PASS_NUM}/g' "$TMP_PROMPT"
-  # inject_project_root: pipe through perl, write to final temp file
   export _PROJECT_ROOT="$PROJECT_ROOT"
-  perl -pe 's/\{\{PROJECT_ROOT\}\}/$ENV{_PROJECT_ROOT}/g' "$TMP_PROMPT" > "${TMP_PROMPT}.final"
-  mv "${TMP_PROMPT}.final" "$TMP_PROMPT"
+  node -e "
+    const fs = require('fs');
+    let c = fs.readFileSync(process.argv[1], 'utf8');
+    c = c.replace(/\{\{DOMAIN_GROUP\}\}/g, process.env._DOMAIN_LIST);
+    c = c.replace(/\{\{PASS_NUM\}\}/g, process.env._PASS_NUM);
+    c = c.replace(/\{\{PROJECT_ROOT\}\}/g, process.env._PROJECT_ROOT);
+    fs.writeFileSync(process.argv[1], c);
+  " "$TMP_PROMPT"
 
   echo "    ⏳ [Pass 1-${i}/${TOTAL_GROUPS}] Running claude -p (no output is normal, please wait)..."
   if ! (cd "$PROJECT_ROOT" && cat "$TMP_PROMPT" | claude -p --dangerously-skip-permissions); then
@@ -288,7 +284,12 @@ if [ -f "$GENERATED_DIR/pass2-merged.json" ]; then
 else
   TMP_PASS2="$GENERATED_DIR/_tmp_pass2_prompt.md"
   export _PROJECT_ROOT="$PROJECT_ROOT"
-  perl -pe 's/\{\{PROJECT_ROOT\}\}/$ENV{_PROJECT_ROOT}/g' "$GENERATED_DIR/pass2-prompt.md" > "$TMP_PASS2"
+  node -e "
+    const fs = require('fs');
+    let c = fs.readFileSync(process.argv[1], 'utf8');
+    c = c.replace(/\{\{PROJECT_ROOT\}\}/g, process.env._PROJECT_ROOT);
+    fs.writeFileSync(process.argv[2], c);
+  " "$GENERATED_DIR/pass2-prompt.md" "$TMP_PASS2"
 
   echo "    ⏳ [Pass 2] Running claude -p (no output is normal, please wait)..."
   if ! (cd "$PROJECT_ROOT" && cat "$TMP_PASS2" | claude -p --dangerously-skip-permissions); then
@@ -313,7 +314,12 @@ echo "[6] Pass 3 — Generating all files..."
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 TMP_PASS3="$GENERATED_DIR/_tmp_pass3_prompt.md"
 export _PROJECT_ROOT="$PROJECT_ROOT"
-perl -pe 's/\{\{PROJECT_ROOT\}\}/$ENV{_PROJECT_ROOT}/g' "$GENERATED_DIR/pass3-prompt.md" > "$TMP_PASS3"
+node -e "
+  const fs = require('fs');
+  let c = fs.readFileSync(process.argv[1], 'utf8');
+  c = c.replace(/\{\{PROJECT_ROOT\}\}/g, process.env._PROJECT_ROOT);
+  fs.writeFileSync(process.argv[2], c);
+" "$GENERATED_DIR/pass3-prompt.md" "$TMP_PASS3"
 
 echo "    ⏳ [Pass 3] Running claude -p (no output is normal, please wait)..."
 if ! (cd "$PROJECT_ROOT" && cat "$TMP_PASS3" | claude -p --dangerously-skip-permissions); then

package/content-validator/index.js

@@ -107,7 +107,7 @@ async function main() {
         continue;
       }
       // All rules must have paths: frontmatter (value varies by category — e.g. ["**/*"] for core/backend, scoped patterns for infra/sync)
-      const hasFrontmatter = c.startsWith("---");
+      const hasFrontmatter = c.replace(/^\uFEFF/, "").startsWith("---");
       const hasPathsKey = c.includes("paths:");
       if (!hasFrontmatter) {
         warnings.push({ file: r, type: "NO_FRONTMATTER", msg: "Missing YAML frontmatter (---)" });

package/health-checker/index.js

@@ -32,7 +32,7 @@ function run(name, script) {
     });
     return { name, ok: true, output };
   } catch (e) {
-    return { name, ok: false, output: e.stdout || e.stderr || e.message || "", exitCode: e.status || 1 };
+    return { name, ok: false, output: [e.stdout, e.stderr].filter(Boolean).join("\n") || e.message || "", exitCode: e.status || 1 };
   }
 }
 
@@ -43,15 +43,17 @@ function main() {
 
   // ─── [0] Run manifest-generator first (prerequisite) ──────────────────
   // Must run first because sync-checker reads sync-map.json
+  let manifestOk = false;
   const manifestScript = path.join(TOOLS, "manifest-generator/index.js");
   if (fs.existsSync(manifestScript)) {
     process.stdout.write("  ⏳ manifest-generator — generating metadata...");
     const r = run("manifest-generator", manifestScript);
     if (r.ok) {
       console.log(" ✅");
+      manifestOk = true;
     } else {
       console.log(" ❌");
-      console.log("  ⚠️  manifest-generator failed. Subsequent sync-checker results may be inaccurate.");
+      console.log("  ⚠️  manifest-generator failed. sync-checker will be skipped.");
     }
   } else {
     console.log("  ⏭️  manifest-generator — not found");
@@ -75,6 +77,12 @@ function main() {
       results.push({ name: t.name, status: "skipped" });
       continue;
     }
+    // Skip sync-checker if manifest-generator failed (depends on sync-map.json)
+    if (t.name === "sync-checker" && !manifestOk) {
+      console.log(`  ⏭️  ${t.name} — skipped (manifest-generator failed)`);
+      results.push({ name: t.name, status: "skipped" });
+      continue;
+    }
     process.stdout.write(`  ⏳ ${t.name} — ${t.desc}...`);
     const r = run(t.name, t.script);
     if (r.ok) {

package/lib/safe-fs.js

@@ -91,7 +91,7 @@ function statSafe(filePath) {
     const c = fs.readFileSync(filePath, "utf-8");
     const s = fs.statSync(filePath);
     return {
-      lines: c.split("\n").length,
+      lines: c.endsWith("\n") ? c.split("\n").length - 1 : c.split("\n").length,
       bytes: s.size,
       modified: s.mtime.toISOString().split("T")[0],
     };

package/lib/stale-report.js

@@ -27,8 +27,7 @@ function updateStaleReport(genDir, key, data, summaryPatch) {
   }
   ex[key] = data;
   if (summaryPatch) {
-    if (!ex.summary) ex.summary = {};
-    Object.assign(ex.summary, summaryPatch);
+    ex.summary = { ...(ex.summary || {}), ...summaryPatch };
   }
   fs.writeFileSync(rp, JSON.stringify(ex, null, 2));
 }

package/manifest-generator/index.js

@@ -38,13 +38,17 @@ function rel(p) {
 }
 
 function stat(f) {
-  const s = fs.statSync(f);
-  const c = fs.readFileSync(f, "utf-8");
-  return {
-    lines: c.split("\n").length,
-    bytes: s.size,
-    modified: s.mtime.toISOString().split("T")[0],
-  };
+  try {
+    const s = fs.statSync(f);
+    const c = fs.readFileSync(f, "utf-8");
+    return {
+      lines: c.endsWith("\n") ? c.split("\n").length - 1 : c.split("\n").length,
+      bytes: s.size,
+      modified: s.mtime.toISOString().split("T")[0],
+    };
+  } catch (_e) {
+    return { lines: 0, bytes: 0, modified: "unknown" };
+  }
 }
 
 function frontmatter(f) {
@@ -158,7 +162,7 @@ async function main() {
 }
 
 if (require.main === module) {
-  main().catch(e => { console.error(e); process.exit(1); });
+  main().catch(e => { console.error(`\n  ❌ Manifest Generator failed: ${e.message || e}`); process.exit(1); });
 }
 
 module.exports = { main };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudeos-core",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "description": "Auto-generate Claude Code documentation from your actual source code — Standards, Rules, Skills, and Guides tailored to your project",
   "main": "bin/cli.js",
   "bin": {

package/pass-json-validator/index.js

@@ -86,7 +86,7 @@ async function main() {
       console.log(`    domains: ${pa.domains.length}`);
       console.log(`    lang: ${pa.lang || "en (default)"}`);
       const tmpl = pa.templates || pa.template;
-      if (typeof tmpl === "object") {
+      if (tmpl && typeof tmpl === "object") {
         console.log(`    templates: backend=${tmpl.backend || "none"}, frontend=${tmpl.frontend || "none"}`);
         if (pa.isMultiStack) console.log(`    mode: 🔀 multi-stack`);
       } else {
@@ -195,7 +195,7 @@ async function main() {
           const framework = paData.stack?.framework;
           const language = paData.stack?.language;
           const architecture = paData.stack?.architecture;
-          isBackend = !frontend || ["express", "nestjs", "django", "fastapi", "spring-boot"].includes(framework);
+          isBackend = !frontend || ["express", "nestjs", "fastify", "django", "fastapi", "flask", "spring-boot"].includes(framework);
           isKotlin = language === "kotlin";
           isKotlinCqrs = isKotlin && (architecture === "cqrs" || paData.stack?.multiModule);
         } catch (_e) { /* If project-analysis parsing fails, conservatively assume backend */ }

package/plan-installer/domain-grouper.js

@@ -14,7 +14,7 @@ function splitDomainGroups(domains, type, template) {
 
   for (const d of domains) {
     // Flush current group before adding if it would exceed limits
-    if (current.length > 0 && (fileCount + d.totalFiles >= MAX_FILES_PER_GROUP || current.length >= MAX_DOMAINS_PER_GROUP)) {
+    if (current.length > 0 && (fileCount + d.totalFiles > MAX_FILES_PER_GROUP || current.length >= MAX_DOMAINS_PER_GROUP)) {
       groups.push({ type, template, domains: [...current], estimatedFiles: fileCount });
       current = [];
       fileCount = 0;

package/plan-installer/index.js

@@ -92,6 +92,7 @@ async function main() {
 
   // Save outputs
   const defaultPort = (stack.framework === "fastapi" || stack.framework === "django") ? 8000
+    : stack.framework === "flask" ? 5000
     : (stack.framework === "express" || stack.framework === "nestjs" || stack.framework === "fastify") ? 3000 : 8080;
   const analysis = {
     analyzedAt: new Date().toISOString(), lang,

package/plan-installer/prompt-generator.js

@@ -63,7 +63,11 @@ function generatePrompts(templates, lang, templatesDir, generatedDir) {
 
   if (primaryTemplate) {
     const primaryBody = readTemplate(primaryTemplate, "pass3");
-    let combinedBody = primaryBody || "";
+    if (!primaryBody) {
+      console.log(`    ⚠️  pass3 template not found for ${primaryTemplate}, skipping`);
+      return;
+    }
+    let combinedBody = primaryBody;
 
     if (templates.backend && templates.frontend && templates.backend !== templates.frontend) {
       const frontendBody = readTemplate(templates.frontend, "pass3");

package/plan-installer/stack-detector.js

@@ -252,8 +252,10 @@ async function detectStack(ROOT) {
         else if (pkg.workspaces && Array.isArray(pkg.workspaces.packages)) wsPatterns = pkg.workspaces.packages;
         if (wsPatterns.length === 0 && existsSafe(path.join(ROOT, "pnpm-workspace.yaml"))) {
           const wy = readFileSafe(path.join(ROOT, "pnpm-workspace.yaml"));
-          const wm = [...wy.matchAll(/- ['"]?([^'"#\n]+)['"]?/g)].map(m => m[1].trim());
-          if (wm.length > 0) wsPatterns = wm;
+          if (wy) {
+            const wm = [...wy.matchAll(/- ['"]?([^'"#\n]+)['"]?/g)].map(m => m[1].trim());
+            if (wm.length > 0) wsPatterns = wm;
+          }
         }
         if (wsPatterns.length > 0) stack.workspaces = wsPatterns;
       }

package/plan-validator/index.js

@@ -28,6 +28,16 @@ function rel(p) {
   return path.relative(ROOT, p).replace(/\\/g, "/");
 }
 
+function isWithinRoot(absPath) {
+  let resolved = path.resolve(absPath);
+  let root = path.resolve(ROOT);
+  if (process.platform === "win32") {
+    resolved = resolved.toLowerCase();
+    root = root.toLowerCase();
+  }
+  return resolved === root || resolved.startsWith(root + path.sep);
+}
+
 // Aliases for backward compatibility (used by tests and main())
 function extractFileBlocks(content) { return parseFileBlocks(content, { includeContent: true }); }
 function extractCodeBlocks(content) { return parseCodeBlocks(content, { includeContent: true }); }
@@ -70,9 +80,7 @@ async function main() {
       const abs = path.join(ROOT, b.path);
 
       // Block path traversal attempts (allow files at ROOT level and below)
-      const resolvedAbs = path.resolve(abs);
-      const resolvedRoot = path.resolve(ROOT);
-      if (resolvedAbs !== resolvedRoot && !resolvedAbs.startsWith(resolvedRoot + path.sep)) {
+      if (!isWithinRoot(abs)) {
         console.log(`     ⚠️  SKIPPED: ${b.path} (path traversal blocked)`);
         continue;
       }
@@ -93,9 +101,9 @@ async function main() {
         continue;
       }
 
-      // File exists — compare content (normalize trailing newlines only)
-      const diskContent = fs.readFileSync(abs, "utf-8").replace(/\n+$/, "");
-      const planContent = b.content.replace(/\n+$/, "");
+      // File exists — compare content (normalize CRLF + trailing newlines)
+      const diskContent = fs.readFileSync(abs, "utf-8").replace(/\r\n/g, "\n").replace(/\n+$/, "");
+      const planContent = b.content.replace(/\r\n/g, "\n").replace(/\n+$/, "");
 
       if (diskContent === planContent) {
         synced++;

package/sync-checker/index.js

@@ -34,6 +34,16 @@ function rel(p) {
   return path.relative(ROOT, p).replace(/\\/g, "/");
 }
 
+function isWithinRoot(absPath) {
+  let resolved = path.resolve(absPath);
+  let root = path.resolve(ROOT);
+  if (process.platform === "win32") {
+    resolved = resolved.toLowerCase();
+    root = root.toLowerCase();
+  }
+  return resolved === root || resolved.startsWith(root + path.sep);
+}
+
 async function main() {
   console.log("\n╔═══════════════════════════════════════╗");
   console.log("║  ClaudeOS-Core — Sync Checker         ║");
@@ -55,7 +65,7 @@ async function main() {
     console.log("  ❌ sync-map.json has no mappings array.\n");
     process.exit(1);
   }
-  const reg = new Set(sm.mappings.map((m) => m.sourcePath));
+  const reg = new Set(sm.mappings.map((m) => m.sourcePath).filter(Boolean));
   const issues = { unreg: [], orphan: [] };
 
   // ─── [1/2] Disk → Plan: detect unregistered files ───────
@@ -83,9 +93,7 @@ async function main() {
   for (const m of sm.mappings) {
     const abs = path.join(ROOT, m.sourcePath);
     // Skip path traversal attempts (allow files at ROOT level and below)
-    const resolvedAbs = path.resolve(abs);
-    const resolvedRoot = path.resolve(ROOT);
-    if (resolvedAbs !== resolvedRoot && !resolvedAbs.startsWith(resolvedRoot + path.sep)) continue;
+    if (!isWithinRoot(abs)) continue;
     if (!fs.existsSync(abs)) {
       issues.orphan.push({ path: m.sourcePath, plan: m.planFile });
     }