specweave 0.23.1 → 0.23.4

package/plugins/specweave/lib/hooks/sync-cache.js

@@ -11,9 +11,10 @@
  * Part of increment 0047-us-task-linkage (T-012).
  */
 
-import fs from 'fs-extra';
+import { readFileSync, statSync, existsSync, promises as fs } from 'fs';
 import path from 'path';
 import crypto from 'crypto';
+import { mkdirpSync } from '../utils/fs-native.js';
 
 /**
  * In-memory cache with TTL
@@ -97,7 +98,7 @@ const globalCache = new SyncCache();
  */
 export function getFileHash(filePath) {
   try {
-    const content = fs.readFileSync(filePath, 'utf-8');
+    const content = readFileSync(filePath, 'utf-8');
     return crypto.createHash('sha256').update(content).digest('hex');
   } catch (error) {
     return null;
@@ -145,7 +146,7 @@ export function getCachedTasks(tasksPath, parser) {
  */
 export function getCachedUSMetadata(usFilePath) {
   try {
-    const stats = fs.statSync(usFilePath);
+    const stats = statSync(usFilePath);
     const cacheKey = `us-metadata:${usFilePath}`;
 
     const cached = globalCache.get(cacheKey);
@@ -156,7 +157,7 @@ export function getCachedUSMetadata(usFilePath) {
     }
 
     // File changed or not in cache - read and cache
-    const content = fs.readFileSync(usFilePath, 'utf-8');
+    const content = readFileSync(usFilePath, 'utf-8');
     const metadata = {
       mtime: stats.mtimeMs,
       metadata: {
@@ -198,7 +199,7 @@ export async function batchFileUpdates(updates) {
   // Write files sequentially within same directory (better disk I/O)
   for (const [dir, fileUpdates] of updatesByDir.entries()) {
     // Ensure directory exists once per directory
-    await fs.ensureDir(dir);
+    await fs.mkdir(dir, { recursive: true });
 
     // Write all files in this directory
     await Promise.all(
@@ -220,13 +221,13 @@ export async function batchFileUpdates(updates) {
 export function needsSync(usFilePath, tasks, tasksPath) {
   try {
     // Check if US file exists
-    if (!fs.existsSync(usFilePath)) {
+    if (!existsSync(usFilePath)) {
       return false; // File doesn't exist, can't sync
     }
 
     // Get file modification times
-    const usStats = fs.statSync(usFilePath);
-    const tasksStats = fs.statSync(tasksPath);
+    const usStats = statSync(usFilePath);
+    const tasksStats = statSync(tasksPath);
 
     // If tasks.md is newer than US file, sync is needed
     if (tasksStats.mtimeMs > usStats.mtimeMs) {

package/plugins/specweave/lib/hooks/sync-living-docs.js

@@ -1,15 +1,31 @@
 #!/usr/bin/env node
-import fs from "fs-extra";
+import { promises as fs, existsSync } from "fs";
 import path from "path";
 import { execSync } from "child_process";
+import { mkdirpSync } from "../utils/fs-native.js";
 async function syncLivingDocs(incrementId) {
   try {
     console.log(`
 \u{1F4DA} Checking living docs sync for increment: ${incrementId}`);
+    // Load and validate config with error handling
     const configPath = path.join(process.cwd(), ".specweave", "config.json");
     let config = {};
-    if (fs.existsSync(configPath)) {
-      config = JSON.parse(await fs.readFile(configPath, "utf-8"));
+
+    try {
+      if (existsSync(configPath)) {
+        const rawContent = await fs.readFile(configPath, "utf-8");
+        config = JSON.parse(rawContent);
+      } else {
+        console.log("\u26A0\uFE0F  No config.json found, using safe defaults (all permissions disabled)");
+        console.log("   To configure: Run 'specweave init' or create .specweave/config.json");
+        config = { sync: { settings: {} } };
+      }
+    } catch (error) {
+      console.error("\u274C Failed to load config.json:", error.message);
+      console.error("   File may be corrupted or contain invalid JSON");
+      console.error("   Using safe defaults (all permissions denied)");
+      console.error("   To fix: Check .specweave/config.json for syntax errors");
+      config = { sync: { settings: {} } };
     }
     const syncEnabled = config.hooks?.post_task_completion?.sync_living_docs ?? false;
     if (!syncEnabled) {
@@ -18,6 +34,22 @@ async function syncLivingDocs(incrementId) {
       return;
     }
     console.log("\u2705 Living docs sync enabled");
+
+    // ========================================================================
+    // GATE 1: canUpsertInternalItems (v0.24.0+ - Internal Docs Permission)
+    // ========================================================================
+    // This permission controls whether SpecWeave can CREATE/UPDATE internal docs.
+    // If false, ALL living docs sync is blocked (both local and external).
+    const canUpsertInternal = config.sync?.settings?.canUpsertInternalItems ?? false;
+
+    if (!canUpsertInternal) {
+      console.log("\u26D4 Living docs sync BLOCKED (canUpsertInternalItems = false)");
+      console.log("   To enable: Set sync.settings.canUpsertInternalItems = true in config.json");
+      console.log("   No internal docs or external tools will be updated");
+      return;
+    }
+
+    console.log("\u2705 Internal docs sync permitted (canUpsertInternalItems = true)");
     const intelligentEnabled = config.livingDocs?.intelligent?.enabled ?? false;
     let specCopied = false;
     let changedDocs = [];
@@ -54,6 +86,25 @@ async function syncLivingDocs(incrementId) {
       return;
     }
 
+    // ========================================================================
+    // GATE 3: autoSyncOnCompletion (v0.24.0+ - Automatic vs Manual Sync)
+    // ========================================================================
+    // This setting controls whether sync to external tools happens automatically
+    // on increment completion or requires manual /specweave:sync-* commands.
+    // DEFAULT: true (automatic sync enabled for better UX)
+    const autoSync = config.sync?.settings?.autoSyncOnCompletion ?? true;
+
+    if (!autoSync) {
+      console.log("\u26A0\uFE0F  Automatic external sync DISABLED (autoSyncOnCompletion = false)");
+      console.log("   Living docs updated locally, but external tools NOT synced");
+      console.log("   To sync manually: Run /specweave-github:sync or /specweave-jira:sync");
+      console.log("   To enable auto-sync: Set sync.settings.autoSyncOnCompletion = true");
+      console.log("\u2705 Living docs sync complete (manual external sync required)\n");
+      return;
+    }
+
+    console.log("\u2705 Automatic external sync permitted (autoSyncOnCompletion = true)");
+
     // T-034E: Use FormatPreservationSyncService for origin-aware sync
     await syncWithFormatPreservation(incrementId);
 
@@ -184,7 +235,7 @@ async function extractAndMergeLivingDocs(incrementId) {
     } = await import("../../../../dist/src/utils/spec-parser.js");
     const projectRoot = process.cwd();
     const incrementSpecPath = path.join(projectRoot, ".specweave", "increments", incrementId, "spec.md");
-    if (!fs.existsSync(incrementSpecPath)) {
+    if (!existsSync(incrementSpecPath)) {
       console.log(`\u26A0\uFE0F  Increment spec not found: ${incrementSpecPath}`);
       return false;
     }
@@ -198,7 +249,7 @@ async function extractAndMergeLivingDocs(incrementId) {
     const specId = incrementSpec.implementsSpec || extractSpecId(incrementId);
     const livingDocsDir = path.join(projectRoot, ".specweave", "docs", "internal", "specs", "default");
     const livingDocsPath = path.join(livingDocsDir, `${specId}-${incrementId.replace(/^\d+-/, "")}.md`);
-    const livingDocsExists = fs.existsSync(livingDocsPath);
+    const livingDocsExists = existsSync(livingDocsPath);
     if (livingDocsExists) {
       console.log(`   \u{1F4DA} Living docs spec exists, merging user stories...`);
       const livingSpec = await parseLivingDocsSpec(livingDocsPath);
@@ -253,7 +304,7 @@ async function extractAndMergeLivingDocs(incrementId) {
         created: (/* @__PURE__ */ new Date()).toISOString().split("T")[0],
         lastUpdated: (/* @__PURE__ */ new Date()).toISOString().split("T")[0]
       };
-      await fs.ensureDir(livingDocsDir);
+      mkdirpSync(livingDocsDir);
       await writeLivingDocsSpec(livingDocsPath, livingSpec);
       console.log(`   \u2705 Created new living docs spec: ${specId}`);
       console.log(`   \u2705 Added ${incrementSpec.userStories.length} user stories`);

package/plugins/specweave/lib/hooks/sync-us-tasks.js

@@ -10,7 +10,7 @@
  * Part of increment 0047-us-task-linkage implementation.
  */
 
-import fs from 'fs-extra';
+import { readFileSync, existsSync, promises as fs } from 'fs';
 import path from 'path';
 import { parseTasksWithUSLinks, getAllTasks } from '../vendor/generators/spec/task-parser.js';
 import { glob } from 'glob';
@@ -32,7 +32,7 @@ export async function syncUSTasksToLivingDocs(incrementId, projectRoot, featureI
     const tasksPath = path.join(projectRoot, '.specweave', 'increments', incrementId, 'tasks.md');
 
     // Check if tasks.md exists
-    if (!fs.existsSync(tasksPath)) {
+    if (!existsSync(tasksPath)) {
       console.log(`   ⚠️  tasks.md not found, skipping task sync`);
       return { success: true, updatedFiles: [], errors: [] };
     }
@@ -451,8 +451,8 @@ function getProjectId(projectRoot, incrementId) {
   try {
     // Try to get from metadata.json
     const metadataPath = path.join(projectRoot, '.specweave', 'increments', incrementId, 'metadata.json');
-    if (fs.existsSync(metadataPath)) {
-      const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
+    if (existsSync(metadataPath)) {
+      const metadata = JSON.parse(readFileSync(metadataPath, 'utf-8'));
       if (metadata.project) {
         return metadata.project;
       }
@@ -460,8 +460,8 @@ function getProjectId(projectRoot, incrementId) {
 
     // Try to get from config.json
     const configPath = path.join(projectRoot, '.specweave', 'config.json');
-    if (fs.existsSync(configPath)) {
-      const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    if (existsSync(configPath)) {
+      const config = JSON.parse(readFileSync(configPath, 'utf-8'));
       if (config.defaultProject) {
         return config.defaultProject;
       }

package/plugins/specweave/lib/hooks/translate-file.js

@@ -1,4 +1,5 @@
-import fs from "fs-extra";
+import { existsSync } from "fs";
+import { promises as fs } from "fs";
 import {
   detectLanguage,
   prepareTranslation,
@@ -9,7 +10,7 @@ import {
 } from "../vendor/utils/translation.js";
 async function translateFile(options) {
   const { filePath, targetLang, preview, verbose } = options;
-  if (!await fs.pathExists(filePath)) {
+  if (!existsSync(filePath)) {
     throw new Error(`File not found: ${filePath}`);
   }
   if (verbose) {

package/plugins/specweave/lib/hooks/translate-file.ts

@@ -16,7 +16,8 @@
  * @see .specweave/increments/0006-llm-native-i18n/reports/DESIGN-POST-GENERATION-TRANSLATION.md
  */
 
-import fs from 'fs-extra';
+import { existsSync } from 'fs';
+import { promises as fs } from 'fs';
 import path from 'path';
 import {
   detectLanguage,
@@ -62,7 +63,7 @@ export async function translateFile(options: CLIOptions): Promise<FileTranslatio
   const { filePath, targetLang, preview, verbose } = options;
 
   // 1. Validate file exists
-  if (!await fs.pathExists(filePath)) {
+  if (!existsSync(filePath)) {
     throw new Error(`File not found: ${filePath}`);
   }
 

package/plugins/specweave/lib/hooks/translate-living-docs.js

@@ -1,13 +1,14 @@
 import { execSync } from "child_process";
-import fs from "fs-extra";
+import { existsSync } from "fs";
+import { promises as fs } from "fs";
 async function translateLivingDocs(incrementId) {
   try {
     const configPath = ".specweave/config.json";
-    if (!fs.existsSync(configPath)) {
+    if (!existsSync(configPath)) {
       console.log("[translate-living-docs] No config found, skipping translation");
       return;
     }
-    const config = await fs.readJson(configPath);
+    const config = JSON.parse(await fs.readFile(configPath, "utf-8"));
     if (!config.language || config.language === "en") {
       console.log("[translate-living-docs] Project language is English, skipping translation");
       return;

package/plugins/specweave/lib/hooks/translate-living-docs.ts

@@ -8,7 +8,8 @@
  */
 
 import { execSync } from 'child_process';
-import fs from 'fs-extra';
+import { existsSync } from 'fs';
+import { promises as fs } from 'fs';
 import path from 'path';
 
 interface Config {
@@ -27,12 +28,12 @@ export async function translateLivingDocs(incrementId: string): Promise<void> {
   try {
     // 1. Load config
     const configPath = '.specweave/config.json';
-    if (!fs.existsSync(configPath)) {
+    if (!existsSync(configPath)) {
       console.log('[translate-living-docs] No config found, skipping translation');
       return;
     }
 
-    const config: Config = await fs.readJson(configPath);
+    const config: Config = JSON.parse(await fs.readFile(configPath, 'utf-8'));
 
     // 2. Check if translation is enabled
     if (!config.language || config.language === 'en') {

package/plugins/specweave/lib/utils/fs-native.js

@@ -0,0 +1,182 @@
+import { promises as fsPromises, existsSync, mkdirSync, readFileSync, writeFileSync, statSync, readdirSync, rmSync, unlinkSync, copyFileSync } from "fs";
+import path from "path";
+async function ensureDir(dirPath) {
+  if (!existsSync(dirPath)) {
+    await fsPromises.mkdir(dirPath, { recursive: true });
+  }
+}
+function ensureDirSync(dirPath) {
+  if (!existsSync(dirPath)) {
+    mkdirSync(dirPath, { recursive: true });
+  }
+}
+function mkdirpSync(dirPath) {
+  ensureDirSync(dirPath);
+}
+async function pathExists(filePath) {
+  return existsSync(filePath);
+}
+async function readJson(filePath) {
+  const content = await fsPromises.readFile(filePath, "utf-8");
+  return JSON.parse(content);
+}
+function readJsonSync(filePath) {
+  const content = readFileSync(filePath, "utf-8");
+  return JSON.parse(content);
+}
+async function writeJson(filePath, data, options) {
+  const spaces = options?.spaces ?? 2;
+  const content = JSON.stringify(data, null, spaces);
+  await fsPromises.writeFile(filePath, content, "utf-8");
+}
+function writeJsonSync(filePath, data, options) {
+  const spaces = options?.spaces ?? 2;
+  const content = JSON.stringify(data, null, spaces);
+  writeFileSync(filePath, content, "utf-8");
+}
+async function remove(targetPath) {
+  if (existsSync(targetPath)) {
+    await fsPromises.rm(targetPath, { recursive: true, force: true });
+  }
+}
+function removeSync(targetPath) {
+  if (existsSync(targetPath)) {
+    rmSync(targetPath, { recursive: true, force: true });
+  }
+}
+async function copy(src, dest, options) {
+  const srcStat = await fsPromises.stat(src);
+  if (srcStat.isFile()) {
+    await fsPromises.mkdir(path.dirname(dest), { recursive: true });
+    await fsPromises.copyFile(src, dest);
+  } else if (srcStat.isDirectory()) {
+    await fsPromises.mkdir(dest, { recursive: true });
+    const entries = await fsPromises.readdir(src, { withFileTypes: true });
+    for (const entry of entries) {
+      const srcPath = path.join(src, entry.name);
+      const destPath = path.join(dest, entry.name);
+      if (options?.filter && !options.filter(srcPath)) {
+        continue;
+      }
+      if (entry.isDirectory()) {
+        await copy(srcPath, destPath, options);
+      } else {
+        await fsPromises.copyFile(srcPath, destPath);
+      }
+    }
+  }
+}
+function copySync(src, dest, options) {
+  const srcStat = statSync(src);
+  if (srcStat.isFile()) {
+    mkdirSync(path.dirname(dest), { recursive: true });
+    copyFileSync(src, dest);
+  } else if (srcStat.isDirectory()) {
+    mkdirSync(dest, { recursive: true });
+    const entries = readdirSync(src, { withFileTypes: true });
+    for (const entry of entries) {
+      const srcPath = path.join(src, entry.name);
+      const destPath = path.join(dest, entry.name);
+      if (options?.filter && !options.filter(srcPath)) {
+        continue;
+      }
+      if (entry.isDirectory()) {
+        copySync(srcPath, destPath, options);
+      } else {
+        copyFileSync(srcPath, destPath);
+      }
+    }
+  }
+}
+async function ensureFile(filePath) {
+  if (!existsSync(filePath)) {
+    await fsPromises.mkdir(path.dirname(filePath), { recursive: true });
+    await fsPromises.writeFile(filePath, "", "utf-8");
+  }
+}
+function ensureFileSync(filePath) {
+  if (!existsSync(filePath)) {
+    mkdirSync(path.dirname(filePath), { recursive: true });
+    writeFileSync(filePath, "", "utf-8");
+  }
+}
+const {
+  readFile,
+  writeFile,
+  appendFile,
+  stat,
+  readdir,
+  access,
+  unlink,
+  rmdir,
+  rename,
+  chmod
+} = fsPromises;
+var fs_native_default = {
+  // Async methods
+  ensureDir,
+  pathExists,
+  readJson,
+  writeJson,
+  remove,
+  copy,
+  ensureFile,
+  readFile,
+  writeFile,
+  appendFile,
+  stat,
+  readdir,
+  access,
+  unlink,
+  // Sync methods
+  ensureDirSync,
+  mkdirpSync,
+  existsSync,
+  readJsonSync,
+  writeJsonSync,
+  removeSync,
+  copySync,
+  ensureFileSync,
+  readFileSync,
+  writeFileSync,
+  statSync,
+  readdirSync,
+  unlinkSync,
+  mkdirSync,
+  rmSync
+};
+export {
+  access,
+  appendFile,
+  chmod,
+  copy,
+  copySync,
+  fs_native_default as default,
+  ensureDir,
+  ensureDirSync,
+  ensureFile,
+  ensureFileSync,
+  existsSync,
+  mkdirSync,
+  mkdirpSync,
+  pathExists,
+  readFile,
+  readFileSync,
+  readJson,
+  readJsonSync,
+  readdir,
+  readdirSync,
+  remove,
+  removeSync,
+  rename,
+  rmSync,
+  rmdir,
+  stat,
+  statSync,
+  unlink,
+  unlinkSync,
+  writeFile,
+  writeFileSync,
+  writeJson,
+  writeJsonSync
+};