specweave 0.30.18 → 0.30.19

package/plugins/specweave/hooks/lib/update-status-line.sh

@@ -174,12 +174,24 @@ fi
 TASKS_FILE="$INCREMENTS_DIR/$CURRENT_INCREMENT/tasks.md"
 SPEC_FILE="$INCREMENTS_DIR/$CURRENT_INCREMENT/spec.md"
 
-# Count tasks with single awk call
+# Count tasks with single awk call (per-task completion tracking!)
+# Bug fix: Each task counts as 0 or 1 completed, regardless of marker count
 read -r TOTAL_TASKS COMPLETED_TASKS < <(
   awk '
-    /^###? T-/ { total++ }
-    /\*\*Completed\*\*:|\*\*Status\*\*:[ \t]*\[x\]/ { completed++ }
-    END { print total+0, completed+0 }
+    BEGIN { total=0; completed=0; in_task=0; task_complete=0 }
+    /^###? T-/ {
+      if (in_task && task_complete) completed++
+      total++
+      in_task=1
+      task_complete=0
+    }
+    /\*\*Completed\*\*:|\*\*Status\*\*:[ \t]*\[x\]|^\[x\]/ {
+      if (in_task) task_complete=1
+    }
+    END {
+      if (in_task && task_complete) completed++
+      print total, completed
+    }
   ' "$TASKS_FILE" 2>/dev/null || echo "0 0"
 )
 

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

@@ -131,7 +131,7 @@ export declare function move(src: string, dest: string, options?: {
 export declare function moveSync(src: string, dest: string, options?: {
     overwrite?: boolean;
 }): void;
-export declare const readFile: typeof fsPromises.readFile, writeFile: typeof fsPromises.writeFile, appendFile: typeof fsPromises.appendFile, stat: typeof fsPromises.stat, readdir: typeof fsPromises.readdir, access: typeof fsPromises.access, unlink: typeof fsPromises.unlink, rmdir: typeof fsPromises.rmdir, rename: typeof fsPromises.rename, chmod: typeof fsPromises.chmod, copyFile: typeof fsPromises.copyFile, mkdtemp: typeof fsPromises.mkdtemp;
+export declare const readFile: typeof fsPromises.readFile, writeFile: typeof fsPromises.writeFile, appendFile: typeof fsPromises.appendFile, stat: typeof fsPromises.stat, lstat: typeof fsPromises.lstat, readdir: typeof fsPromises.readdir, access: typeof fsPromises.access, unlink: typeof fsPromises.unlink, rmdir: typeof fsPromises.rmdir, rename: typeof fsPromises.rename, chmod: typeof fsPromises.chmod, copyFile: typeof fsPromises.copyFile, mkdtemp: typeof fsPromises.mkdtemp, mkdir: typeof fsPromises.mkdir, symlink: typeof fsPromises.symlink, readlink: typeof fsPromises.readlink;
 export declare const renameSync: typeof fsRenameSync;
 export declare const mkdtempSync: typeof fsMkdtempSync;
 export { readFileSync, writeFileSync, statSync, readdirSync, unlinkSync, mkdirSync, rmSync, copyFileSync, };
@@ -156,6 +156,7 @@ declare const _default: {
     rename: typeof fsPromises.rename;
     copyFile: typeof fsPromises.copyFile;
     mkdtemp: typeof fsPromises.mkdtemp;
+    mkdir: typeof fsPromises.mkdir;
     ensureDirSync: typeof ensureDirSync;
     mkdirpSync: typeof mkdirpSync;
     existsSync: typeof existsSync;

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

@@ -267,7 +267,11 @@ export function moveSync(src, dest, options) {
     }
 }
 // Re-export common fs/promises methods for convenience
-export const { readFile, writeFile, appendFile, stat, readdir, access, unlink, rmdir, rename, chmod, copyFile, mkdtemp, } = fsPromises;
+export const { readFile, writeFile, appendFile, stat, lstat, // Added for symlink detection
+readdir, access, unlink, rmdir, rename, chmod, copyFile, mkdtemp, mkdir, // Added for test compatibility
+symlink, // Added for creating symlinks
+readlink, // Added for reading symlink targets
+ } = fsPromises;
 // Create renameSync alias for fs-extra compatibility
 export const renameSync = fsRenameSync;
 // Create mkdtempSync alias
@@ -297,6 +301,7 @@ export default {
     rename,
     copyFile,
     mkdtemp,
+    mkdir,
     // Sync methods
     ensureDirSync,
     mkdirpSync,

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

@@ -1 +1 @@
-{"version":3,"file":"fs-native.js","sourceRoot":"","sources":["../../../src/utils/fs-native.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fs-native.js","sourceRoot":"","sources":["../../../src/utils/fs-native.ts"],"names":[],"mappings":"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"}

package/plugins/specweave-docs/commands/build.md

@@ -1,60 +1,55 @@
 ---
 name: specweave-docs:build
-description: Build static documentation site for deployment. Supports both public and internal docs. Outputs production-ready HTML/CSS/JS.
+description: Build static documentation site for deployment. Auto-setup on first run. Outputs production-ready HTML/CSS/JS.
 ---
 
 # Documentation Build Command
 
 Build production-ready static documentation site for deployment to any static host.
 
-## Usage
+## Your Task
 
-```bash
-# Build INTERNAL docs (SpecWeave living documentation) - DEFAULT
-/specweave-docs:build
+**IMPORTANT**: This command must work in ANY SpecWeave user project, not just the SpecWeave repo itself.
+
+### Step 1: Ensure Docusaurus is Set Up
 
-# Build PUBLIC docs (end-user documentation)
-/specweave-docs:build --public
+First, ensure the cached Docusaurus installation exists:
+
+```bash
+# Check if Docusaurus is set up
+if [ ! -d ".specweave/cache/docs-site/node_modules" ]; then
+  echo "Setting up Docusaurus first..."
+  # Run the same setup as preview command (see preview.md for full setup)
+  # After setup, continue to build
+fi
 ```
 
-## Two Build Targets
+If not set up, follow the same setup steps as `/specweave-docs:preview` (Step 3 in preview.md).
 
-| Site | Output Directory | NPM Script |
-|------|------------------|------------|
-| **Internal** | `docs-site/build-internal/` | `docs:internal:build` |
-| **Public** | `docs-site/build/` | `docs:build` |
+### Step 2: Run Build
 
-## Your Task
+```bash
+cd .specweave/cache/docs-site && npm run build
+```
 
-Execute the appropriate npm script based on user flags:
+### Step 3: Report Output
 
 ```bash
-# Check if user wants public docs
-PUBLIC_FLAG="${1:-}"
-
-cd /path/to/project
-
-if [ "$PUBLIC_FLAG" = "--public" ]; then
-  echo "Building PUBLIC documentation..."
-  echo "Output: docs-site/build/"
-  echo ""
-  npm run docs:build
-  echo ""
-  echo "Build complete! Output: docs-site/build/"
-else
-  echo "Building INTERNAL documentation..."
-  echo "Output: docs-site/build-internal/"
-  echo ""
-  npm run docs:internal:build
-  echo ""
-  echo "Build complete! Output: docs-site/build-internal/"
-fi
+echo ""
+echo "📦 Build Complete!"
+echo ""
+echo "   Output: .specweave/cache/docs-site/build/"
+echo ""
+echo "   Deploy with:"
+echo "   • npx serve .specweave/cache/docs-site/build/"
+echo "   • Copy to your static host"
+echo ""
 ```
 
 ## Output Structure
 
 ```
-docs-site/build-internal/
+.specweave/cache/docs-site/build/
 ├── index.html              <- Landing page
 ├── strategy/
 ├── specs/
@@ -74,41 +69,23 @@ docs-site/build-internal/
 ### 1. Preview Locally
 
 ```bash
-# Internal docs
-cd docs-site && npm run serve:internal
-
-# Public docs
-cd docs-site && npm run serve
-```
-
-### 2. Netlify
-
-```bash
-cd docs-site
-npx netlify deploy --dir=build-internal --prod
-```
-
-### 3. Vercel
-
-```bash
-cd docs-site
-npx vercel --prod
+npx serve .specweave/cache/docs-site/build/
 ```
 
-### 4. GitHub Pages
+### 2. Copy to Custom Location
 
 ```bash
-# Copy build to docs folder (GitHub Pages expects /docs)
-cp -r docs-site/build-internal/* docs/
+# Copy build to docs folder for GitHub Pages
+cp -r .specweave/cache/docs-site/build/* docs/
 git add docs/
 git commit -m "docs: update documentation site"
-git push
 ```
 
-### 5. Static Server
+### 3. Netlify/Vercel
 
 ```bash
-npx serve docs-site/build-internal/
+# Point your deployment to:
+.specweave/cache/docs-site/build/
 ```
 
 ## Build vs Preview
@@ -122,33 +99,30 @@ npx serve docs-site/build-internal/
 | **Optimization** | No | Yes (minified) |
 | **Use Case** | Writing docs | Deployment |
 
-## First-Time Setup
-
-If dependencies not installed:
-
-```bash
-npm run docs:install
-```
-
 ## Troubleshooting
 
 ### Build fails with broken links
 ```bash
 # Preview first to find errors
-npm run docs:internal
+/specweave-docs:preview
 # Fix broken links, then build
-npm run docs:internal:build
+/specweave-docs:build
 ```
 
 ### Out of memory
 ```bash
-# Increase Node memory
-NODE_OPTIONS="--max-old-space-size=4096" npm run docs:internal:build
+NODE_OPTIONS="--max-old-space-size=4096" npm run build
 ```
 
 ### Cache issues
 ```bash
-cd docs-site && npm run clear && npm run build:internal
+cd .specweave/cache/docs-site && npm run clear && npm run build
+```
+
+### Reinstall from scratch
+```bash
+rm -rf .specweave/cache/docs-site
+/specweave-docs:build
 ```
 
 ## See Also

package/plugins/specweave-docs/commands/preview.md

@@ -1,135 +1,229 @@
 ---
 name: specweave-docs:preview
-description: Launch Docusaurus documentation server. Supports both public (port 3016) and internal (port 3015) documentation sites.
+description: Launch Docusaurus documentation server for internal living docs. Auto-setup on first run. Port 3015.
 ---
 
 # Documentation Preview Command
 
 Launch Docusaurus development server with hot reload, Mermaid diagrams, and auto-generated sidebar.
 
-## Usage
-
-```bash
-# Preview INTERNAL docs (SpecWeave living documentation) - DEFAULT
-/specweave-docs:preview
+## Your Task
 
-# Preview PUBLIC docs (end-user documentation)
-/specweave-docs:preview --public
-```
+**IMPORTANT**: This command must work in ANY SpecWeave user project, not just the SpecWeave repo itself.
 
-## Two Documentation Sites
+### Step 1: Check Prerequisites
 
-| Site | Port | Content | NPM Script |
-|------|------|---------|------------|
-| **Internal** | 3015 | `.specweave/docs/internal/` | `docs:internal` |
-| **Public** | 3016 | `docs-site/docs/` | `docs:dev` |
+```bash
+# Verify internal docs exist
+ls -la .specweave/docs/internal/
 
-## Your Task
+# If missing, inform user:
+# "No internal documentation found at .specweave/docs/internal/.
+#  Run 'specweave init' first or create the folder structure."
+```
 
-Execute the appropriate npm script based on user flags:
+### Step 2: Check for Cached Installation
 
 ```bash
-# Check if user wants public docs
-PUBLIC_FLAG="${1:-}"
-
-cd /path/to/project
-
-if [ "$PUBLIC_FLAG" = "--public" ]; then
-  echo "Launching PUBLIC documentation on port 3016..."
-  echo "Content: docs-site/docs/"
-  echo ""
-  npm run docs:dev
+# Check if Docusaurus is already set up in cache
+if [ -d ".specweave/cache/docs-site/node_modules" ]; then
+  echo "✓ Docusaurus installation found in cache"
+  NEEDS_INSTALL=false
 else
-  echo "Launching INTERNAL documentation on port 3015..."
-  echo "Content: .specweave/docs/internal/"
-  echo ""
-  npm run docs:internal
+  echo "⚙ First-time setup: Installing Docusaurus (~30 seconds)..."
+  NEEDS_INSTALL=true
 fi
 ```
 
-### Alternative: Run directly with npx
+### Step 3: First-Time Setup (if needed)
 
-If in a fresh project without the docs-site setup:
+If `NEEDS_INSTALL=true`, create the cached Docusaurus installation:
 
 ```bash
-# For internal docs
-cd docs-site && npm run start:internal
-
-# For public docs
-cd docs-site && npm run start
+# Create cache directory
+mkdir -p .specweave/cache/docs-site
+
+# Create package.json
+cat > .specweave/cache/docs-site/package.json << 'EOF'
+{
+  "name": "specweave-docs-preview",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "start": "docusaurus start --port 3015",
+    "build": "docusaurus build",
+    "clear": "docusaurus clear"
+  },
+  "dependencies": {
+    "@docusaurus/core": "^3.9.2",
+    "@docusaurus/preset-classic": "^3.9.2",
+    "@docusaurus/theme-mermaid": "^3.9.2",
+    "@mdx-js/react": "^3.0.0",
+    "clsx": "^2.0.0",
+    "prism-react-renderer": "^2.3.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "engines": {
+    "node": ">=20.0"
+  }
+}
+EOF
+
+# Create Docusaurus config pointing to internal docs
+cat > .specweave/cache/docs-site/docusaurus.config.ts << 'EOF'
+import {themes as prismThemes} from 'prism-react-renderer';
+import type {Config} from '@docusaurus/types';
+import type * as Preset from '@docusaurus/preset-classic';
+
+const config: Config = {
+  title: 'Internal Documentation',
+  tagline: 'SpecWeave Living Documentation',
+  favicon: 'img/favicon.ico',
+  future: { v4: true },
+  url: 'http://localhost:3015',
+  baseUrl: '/',
+  onBrokenLinks: 'warn',
+  onBrokenMarkdownLinks: 'warn',
+  i18n: { defaultLocale: 'en', locales: ['en'] },
+  markdown: { mermaid: true, format: 'md' },
+  themes: ['@docusaurus/theme-mermaid'],
+  presets: [
+    [
+      'classic',
+      {
+        docs: {
+          // Path relative to this config file → ../../docs/internal/
+          path: '../../docs/internal',
+          routeBasePath: '/',
+          sidebarPath: './sidebars.ts',
+          showLastUpdateTime: true,
+          sidebarCollapsible: true,
+          sidebarCollapsed: true,
+        },
+        blog: false,
+        theme: { customCss: './src/css/custom.css' },
+      } satisfies Preset.Options,
+    ],
+  ],
+  themeConfig: {
+    colorMode: {
+      defaultMode: 'dark',
+      disableSwitch: false,
+      respectPrefersColorScheme: true,
+    },
+    navbar: {
+      title: 'Internal Docs',
+      items: [
+        {to: '/', label: 'Home', position: 'left'},
+        {type: 'search', position: 'right'},
+      ],
+    },
+    footer: {
+      style: 'dark',
+      copyright: `SpecWeave Living Documentation`,
+    },
+    prism: {
+      theme: prismThemes.github,
+      darkTheme: prismThemes.dracula,
+      additionalLanguages: ['bash', 'typescript', 'yaml', 'json'],
+    },
+    mermaid: { theme: {light: 'neutral', dark: 'dark'} },
+  } satisfies Preset.ThemeConfig,
+};
+
+export default config;
+EOF
+
+# Create auto-generated sidebar
+cat > .specweave/cache/docs-site/sidebars.ts << 'EOF'
+import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
+
+const sidebars: SidebarsConfig = {
+  docs: [
+    {
+      type: 'autogenerated',
+      dirName: '.',
+    },
+  ],
+};
+
+export default sidebars;
+EOF
+
+# Create minimal CSS
+mkdir -p .specweave/cache/docs-site/src/css
+cat > .specweave/cache/docs-site/src/css/custom.css << 'EOF'
+:root {
+  --ifm-color-primary: #2563eb;
+  --ifm-code-font-size: 95%;
+}
+[data-theme='dark'] {
+  --ifm-color-primary: #60a5fa;
+}
+EOF
+
+# Create static folder with placeholder favicon
+mkdir -p .specweave/cache/docs-site/static/img
+echo '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><text y=".9em" font-size="90">📚</text></svg>' > .specweave/cache/docs-site/static/img/favicon.ico
+
+# Install dependencies using PUBLIC npm registry (avoids Azure DevOps/private registry issues)
+cd .specweave/cache/docs-site && npm install --registry=https://registry.npmjs.org --legacy-peer-deps
 ```
 
-## What You Get
-
-- **Hot reload** - Edit markdown, see changes instantly
-- **Auto sidebar** - Generated from folder structure
-- **Mermaid diagrams** - Architecture diagrams render beautifully
-- **Dark/light mode** - Toggle in navbar
-- **Local search** - Instant search across all docs
-- **Mobile responsive** - Works on any device
-
-## First-Time Setup
-
-If `docs-site/node_modules` doesn't exist:
+### Step 4: Start the Server
 
 ```bash
-npm run docs:install
+cd .specweave/cache/docs-site && npm start
 ```
 
-This installs Docusaurus dependencies (~200MB, ~30 seconds).
-
-## Ports
+This will:
+- Start Docusaurus on **http://localhost:3015**
+- Enable hot reload (edit markdown, see changes instantly)
+- Render Mermaid diagrams
+- Auto-generate sidebar from folder structure
 
-| Script | Port | URL |
-|--------|------|-----|
-| `docs:dev` | 3016 | http://localhost:3016 |
-| `docs:internal` | 3015 | http://localhost:3015 |
+### Output to User
 
-## Internal Docs Structure
+After starting, display:
 
 ```
-.specweave/docs/internal/
-├── strategy/        → Product strategy
-├── specs/           → Feature specifications (708 files!)
-│   └── specweave/
-│       ├── FS-001/  → Feature folders
-│       ├── FS-002/
-│       └── ...
-├── architecture/    → ADRs, HLDs, diagrams
-├── delivery/        → Release plans, guides
-├── operations/      → Runbooks, NFRs
-└── governance/      → Standards, conventions
+📚 Documentation Preview Server Started!
+
+   URL: http://localhost:3015
+   Content: .specweave/docs/internal/
+
+   Features:
+   • Hot reload - edit markdown, see changes instantly
+   • Mermaid diagrams - architecture diagrams render beautifully
+   • Auto sidebar - generated from folder structure
+   • Dark/light mode - toggle in navbar
+
+   Press Ctrl+C to stop the server.
 ```
 
-## Configuration Files
+## What You Get
 
-| File | Purpose |
-|------|---------|
-| `docusaurus.config.ts` | Public docs config |
-| `docusaurus.config.internal.ts` | Internal docs config |
-| `sidebars.ts` | Public docs sidebar |
-| `sidebars.internal.ts` | Internal docs sidebar |
+- **Hot reload** - Edit markdown, see changes instantly
+- **Auto sidebar** - Generated from folder structure
+- **Mermaid diagrams** - Architecture diagrams render beautifully
+- **Dark/light mode** - Toggle in navbar
+- **Local search** - Instant search across all docs
 
 ## Troubleshooting
 
 ### Port already in use
 ```bash
-# Find process using port
-lsof -i :3015
-
-# Kill it
-kill -9 <PID>
+lsof -i :3015 && kill -9 $(lsof -t -i :3015)
 ```
 
-### Missing dependencies
+### Reinstall from scratch
 ```bash
-npm run docs:install
+rm -rf .specweave/cache/docs-site && /specweave-docs:preview
 ```
 
-### Build errors
-```bash
-cd docs-site && npm run clear && npm run start:internal
-```
+### npm registry issues
+The setup uses `--registry=https://registry.npmjs.org` to bypass private registry configurations.
 
 ## See Also