fix: Windows install + config docs (closes #32, #34) (#35)

* fix(npm): use PowerShell Expand-Archive on Windows

Windows lacks the unzip command, so the postinstall extraction silently
failed and stacklit.exe never landed in npm/bin/. Switch to
Expand-Archive (ships with Windows 10+) for .zip on win32, surface
extraction output via stdio inherit, and fail loudly when the binary is
missing after extraction.

Closes #32

* docs: align config docs with .stacklitrc.json

The README and USAGE guide showed a TOML schema, but the loader in
internal/config reads .stacklitrc.json. Update both docs to JSON so the
example matches the file the tool actually loads.

Closes #34

* fix(npm): harden Windows install against quoting and silent failures

Address PR review feedback from Copilot:

- Use execFileSync instead of execSync for all extraction commands so
  paths are passed as args, never interpolated into a shell string. The
  original PowerShell command wrapped paths in single quotes inside a
  double-quoted string, so a single quote in __dirname (e.g.
  C:\\Users\\O'Connor\\...) would have broken parsing or altered the
  command.
- On Windows, hand the archive and bin paths to PowerShell via env vars
  ($env:STACKLIT_ARCHIVE / $env:STACKLIT_BINDIR) and use -LiteralPath
  so the script body has no string interpolation at all.
- Move archive.tmp cleanup into a finally so a failed extraction doesn't
  leave the temp file behind.
- Set process.exitCode = 1 in the top-level catch so npm postinstall
  reports a non-zero status when extraction fails or the binary is
  missing afterward. Download failures still return silently, matching
  the existing 'let the bin script show a helpful error' behavior.

* chore: revert unintended stacklit.json regeneration

The post-commit hook regenerated stacklit.json (new merkle hash and
timestamp) when committing the npm fix. That regeneration is unrelated
to this PR's scope, so revert it to keep the diff focused on
npm/install.js.

Author: thegdsks

README.md

@@ -267,16 +267,18 @@ stacklit setup cursor            # configure Cursor + MCP
 ```
 
 <details>
-<summary>Configuration (stacklit.toml)</summary>
+<summary>Configuration (.stacklitrc.json)</summary>
 
-```toml
-ignore = ["vendor/", "generated/"]
-max_depth = 3
-
-[output]
-json = "stacklit.json"
-mermaid = "DEPENDENCIES.md"
-html = "stacklit.html"
+```json
+{
+  "ignore": ["vendor/", "generated/"],
+  "max_depth": 3,
+  "output": {
+    "json": "stacklit.json",
+    "mermaid": "DEPENDENCIES.md",
+    "html": "stacklit.html"
+  }
+}
 ```
 
 </details>

USAGE.md

@@ -152,28 +152,24 @@ The server auto-reloads when `stacklit.json` changes on disk.
 
 ## Configuration
 
-Create `stacklit.toml` in your project root (optional):
+Create `.stacklitrc.json` in your project root (optional):
 
-```toml
-# Paths to ignore on top of .gitignore
-ignore = ["vendor/", "generated/", "*.pb.go"]
-
-# Module detection depth (default: 4)
-max_depth = 3
-
-# Max modules before collapsing (default: 200)
-max_modules = 150
-
-# Max exports per module (default: 10)
-max_exports = 15
-
-# Output file names
-[output]
-json = "stacklit.json"
-mermaid = "DEPENDENCIES.md"
-html = "stacklit.html"
+```json
+{
+  "ignore": ["vendor/", "generated/", "*.pb.go"],
+  "max_depth": 3,
+  "max_modules": 150,
+  "max_exports": 15,
+  "output": {
+    "json": "stacklit.json",
+    "mermaid": "DEPENDENCIES.md",
+    "html": "stacklit.html"
+  }
+}
 ```
 
+Keys: `ignore` (extra paths on top of `.gitignore`), `max_depth` (module detection depth, default 4), `max_modules` (collapse threshold, default 200), `max_exports` (per module, default 10), and `output` (override generated file names).
+
 ---
 
 ## Reading stacklit.json

npm/install.js

@@ -2,7 +2,7 @@ const os = require('os');
 const fs = require('fs');
 const path = require('path');
 const https = require('https');
-const { execSync } = require('child_process');
+const { execFileSync } = require('child_process');
 
 const VERSION = '0.3.0';
 const REPO = 'glincker/stacklit';
@@ -77,25 +77,58 @@ async function install() {
     return;
   }
 
-  // Extract
-  if (archivePath.endsWith('.zip') || url.endsWith('.zip')) {
-    execSync(`unzip -o "${archivePath}" stacklit.exe -d "${binDir}"`, { stdio: 'ignore' });
-  } else {
-    execSync(`tar -xzf "${archivePath}" -C "${binDir}" stacklit`, { stdio: 'ignore' });
-  }
-
-  // Make executable
-  if (os.platform() !== 'win32') {
-    fs.chmodSync(binPath, 0o755);
+  try {
+    // Extract. execFileSync passes args directly to the binary, so no shell
+    // quoting of paths is needed. On Windows we hand paths to PowerShell via
+    // env vars so a single quote in __dirname (e.g. C:\Users\O'Connor\...)
+    // cannot terminate the script string.
+    if (url.endsWith('.zip')) {
+      if (os.platform() === 'win32') {
+        execFileSync(
+          'powershell',
+          [
+            '-NoProfile',
+            '-ExecutionPolicy', 'Bypass',
+            '-Command',
+            'Expand-Archive -Force -LiteralPath $env:STACKLIT_ARCHIVE -DestinationPath $env:STACKLIT_BINDIR',
+          ],
+          {
+            stdio: 'inherit',
+            env: { ...process.env, STACKLIT_ARCHIVE: archivePath, STACKLIT_BINDIR: binDir },
+          }
+        );
+      } else {
+        execFileSync('unzip', ['-o', archivePath, 'stacklit.exe', '-d', binDir], { stdio: 'inherit' });
+      }
+    } else {
+      execFileSync('tar', ['-xzf', archivePath, '-C', binDir, 'stacklit'], { stdio: 'inherit' });
+    }
+
+    if (!fs.existsSync(binPath)) {
+      throw new Error(`extraction completed but ${binPath} is missing`);
+    }
+
+    if (os.platform() !== 'win32') {
+      fs.chmodSync(binPath, 0o755);
+    }
+  } finally {
+    if (fs.existsSync(archivePath)) {
+      try {
+        fs.unlinkSync(archivePath);
+      } catch (cleanupErr) {
+        // best-effort cleanup; warn but don't mask the original failure
+        console.warn(`Could not remove ${archivePath}: ${cleanupErr.message}`);
+      }
+    }
   }
 
-  // Cleanup
-  fs.unlinkSync(archivePath);
-
   console.log('stacklit installed successfully.');
 }
 
 install().catch((err) => {
   console.error('Installation failed:', err.message);
   console.error('You can install manually: go install github.com/glincker/stacklit/cmd/stacklit@latest');
+  // Surface the failure to npm so postinstall doesn't appear to succeed when
+  // the binary is actually missing or extraction broke.
+  process.exitCode = 1;
 });