specweave 0.23.2 → 0.23.4

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
+};

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

@@ -0,0 +1,283 @@
+/**
+ * Native Node.js fs API Helpers
+ *
+ * Drop-in replacements for fs-extra methods using only Node.js stdlib.
+ * All methods use native Node.js 20+ APIs with no external dependencies.
+ *
+ * Migration from fs-extra:
+ * - import fs from 'fs-extra' → import * as fs from './utils/fs-native.js'
+ * - All fs-extra methods work as drop-in replacements
+ *
+ * Benefits:
+ * - Zero bundle overhead (no npm packages)
+ * - Works in marketplace (no node_modules needed)
+ * - Faster startup (native APIs)
+ * - Better debugging (native stack traces)
+ */
+
+import { promises as fsPromises, existsSync, mkdirSync, readFileSync, writeFileSync, statSync, readdirSync, rmSync, unlinkSync, copyFileSync } from 'fs';
+import { execSync } from 'child_process';
+import path from 'path';
+
+/**
+ * Ensures that a directory exists. If the directory does not exist, it is created.
+ * @param dirPath - The directory path to ensure
+ */
+export async function ensureDir(dirPath: string): Promise<void> {
+  if (!existsSync(dirPath)) {
+    await fsPromises.mkdir(dirPath, { recursive: true });
+  }
+}
+
+/**
+ * Synchronous version of ensureDir
+ */
+export function ensureDirSync(dirPath: string): void {
+  if (!existsSync(dirPath)) {
+    mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+/**
+ * Alias for ensureDirSync (fs-extra compatibility)
+ */
+export function mkdirpSync(dirPath: string): void {
+  ensureDirSync(dirPath);
+}
+
+/**
+ * Check if a path exists
+ * @param filePath - The path to check
+ */
+export async function pathExists(filePath: string): Promise<boolean> {
+  return existsSync(filePath);
+}
+
+/**
+ * Synchronous version of pathExists
+ */
+export { existsSync };
+
+/**
+ * Read a JSON file and parse it
+ * @param filePath - The JSON file path
+ */
+export async function readJson(filePath: string): Promise<any> {
+  const content = await fsPromises.readFile(filePath, 'utf-8');
+  return JSON.parse(content);
+}
+
+/**
+ * Synchronous version of readJson
+ */
+export function readJsonSync(filePath: string): any {
+  const content = readFileSync(filePath, 'utf-8');
+  return JSON.parse(content);
+}
+
+/**
+ * Write a JSON file with formatting
+ * @param filePath - The JSON file path
+ * @param data - The data to write
+ * @param options - Options (spaces for indentation)
+ */
+export async function writeJson(
+  filePath: string,
+  data: any,
+  options?: { spaces?: number }
+): Promise<void> {
+  const spaces = options?.spaces ?? 2;
+  const content = JSON.stringify(data, null, spaces);
+  await fsPromises.writeFile(filePath, content, 'utf-8');
+}
+
+/**
+ * Synchronous version of writeJson
+ */
+export function writeJsonSync(
+  filePath: string,
+  data: any,
+  options?: { spaces?: number }
+): void {
+  const spaces = options?.spaces ?? 2;
+  const content = JSON.stringify(data, null, spaces);
+  writeFileSync(filePath, content, 'utf-8');
+}
+
+/**
+ * Remove a file or directory (recursively)
+ * @param targetPath - The path to remove
+ */
+export async function remove(targetPath: string): Promise<void> {
+  if (existsSync(targetPath)) {
+    await fsPromises.rm(targetPath, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Synchronous version of remove
+ */
+export function removeSync(targetPath: string): void {
+  if (existsSync(targetPath)) {
+    rmSync(targetPath, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Copy a file or directory
+ * @param src - Source path
+ * @param dest - Destination path
+ * @param options - Copy options
+ */
+export async function copy(
+  src: string,
+  dest: string,
+  options?: { overwrite?: boolean; filter?: (src: string) => boolean }
+): Promise<void> {
+  const srcStat = await fsPromises.stat(src);
+
+  if (srcStat.isFile()) {
+    // Copy single file
+    await fsPromises.mkdir(path.dirname(dest), { recursive: true });
+    await fsPromises.copyFile(src, dest);
+  } else if (srcStat.isDirectory()) {
+    // Copy directory recursively
+    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);
+
+      // Apply filter if provided
+      if (options?.filter && !options.filter(srcPath)) {
+        continue;
+      }
+
+      if (entry.isDirectory()) {
+        await copy(srcPath, destPath, options);
+      } else {
+        await fsPromises.copyFile(srcPath, destPath);
+      }
+    }
+  }
+}
+
+/**
+ * Synchronous version of copy
+ */
+export function copySync(
+  src: string,
+  dest: string,
+  options?: { overwrite?: boolean; filter?: (src: string) => boolean }
+): void {
+  const srcStat = statSync(src);
+
+  if (srcStat.isFile()) {
+    // Copy single file
+    mkdirSync(path.dirname(dest), { recursive: true });
+    copyFileSync(src, dest);
+  } else if (srcStat.isDirectory()) {
+    // Copy directory recursively
+    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);
+
+      // Apply filter if provided
+      if (options?.filter && !options.filter(srcPath)) {
+        continue;
+      }
+
+      if (entry.isDirectory()) {
+        copySync(srcPath, destPath, options);
+      } else {
+        copyFileSync(srcPath, destPath);
+      }
+    }
+  }
+}
+
+/**
+ * Ensure a file exists (create if it doesn't)
+ * @param filePath - The file path
+ */
+export async function ensureFile(filePath: string): Promise<void> {
+  if (!existsSync(filePath)) {
+    await fsPromises.mkdir(path.dirname(filePath), { recursive: true });
+    await fsPromises.writeFile(filePath, '', 'utf-8');
+  }
+}
+
+/**
+ * Synchronous version of ensureFile
+ */
+export function ensureFileSync(filePath: string): void {
+  if (!existsSync(filePath)) {
+    mkdirSync(path.dirname(filePath), { recursive: true });
+    writeFileSync(filePath, '', 'utf-8');
+  }
+}
+
+// Re-export common fs/promises methods for convenience
+export const {
+  readFile,
+  writeFile,
+  appendFile,
+  stat,
+  readdir,
+  access,
+  unlink,
+  rmdir,
+  rename,
+  chmod,
+} = fsPromises;
+
+// Re-export common synchronous methods
+export {
+  readFileSync,
+  writeFileSync,
+  statSync,
+  readdirSync,
+  unlinkSync,
+  mkdirSync,
+  rmSync,
+};
+
+// Default export for convenience
+export 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,
+};