openspec-stack-init 1.0.1 → 1.0.3

package/README.md

@@ -19,14 +19,30 @@ npx openspec-stack-init ./my-project --dry-run
 
 ## What it installs
 
-| Tool | What it does | Non-interactive flag used |
+| Tool | What it does | How |
 |---|---|---|
-| **OpenSpec** | Spec-driven development | `openspec init --tools claude --profile expanded --force` |
-| **Beads** | Git-backed issue tracker / agent memory | `bd init --quiet` + `bd setup claude` |
+| **OpenSpec** | Spec-driven development | `openspec init --tools claude --profile core --force` |
+| **Beads** | Git-backed issue tracker / agent memory | `bd init --quiet` + `bd setup claude` (CLI hooks) |
 | **claude-mem** | Automatic session memory via hooks | `claude plugin marketplace add` + `claude plugin install` |
 | **openspec-to-beads** | Syncs OpenSpec tasks.md → Beads issues | `npx @smithery/cli skill add` |
 | **/migrate-to-openspec** | Brownfield migration skill | Copied to `.claude/skills/migrate-to-openspec/` |
 
+### Beads: CLI vs Claude Code Plugin
+
+This package installs **Beads CLI level** only:
+
+- `bd init` — creates `.beads/` and `issues.jsonl` in your project (git-committed)
+- `bd setup claude` — installs `SessionStart` and `PreCompact` hooks so Claude Code gets task context automatically
+
+There is also an **optional Beads Claude Code Plugin** that adds slash commands (`/beads:ready`, `/beads:create`, etc.) and an MCP server. It cannot be installed automatically from a shell script — install it manually inside Claude Code if you want it:
+
+```
+/plugin marketplace add steveyegge/beads
+/plugin install beads
+```
+
+For most projects the CLI level is sufficient — Claude Code agents call `bd` via bash.
+
 ## Prerequisites
 
 > ⚠️ **This package does NOT install the tools below for you.**
@@ -101,4 +117,4 @@ node src/index.js ./target-project
 ```bash
 npm publish --access public
 # Then anyone can run: npx openspec-stack-init
-```
+```

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "openspec-stack-init",
-  "version": "1.0.1",
+  "version": "1.0.3",
+  "type": "module",
   "description": "Initialize OpenSpec + Beads + claude-mem + skills in any project",
   "author": {
     "name": "VirtualMaestro",
@@ -20,11 +21,6 @@
   "scripts": {
     "start": "node src/index.js"
   },
-  "dependencies": {
-    "chalk": "^5.3.0",
-    "execa": "^8.0.1",
-    "ora": "^8.0.1"
-  },
   "engines": {
     "node": ">=18.0.0"
   },

package/src/index.js

@@ -9,8 +9,8 @@
 //   npx openspec-stack-init --dry-run        — preview without executing
 
 import { execSync, spawnSync } from "child_process";
-import { existsSync, mkdirSync, writeFileSync, appendFileSync, readFileSync } from "fs";
-import { resolve, basename, join } from "path";
+import { existsSync, mkdirSync, writeFileSync, appendFileSync, readFileSync, statSync, unlinkSync } from "fs";
+import { resolve, basename, join, sep, dirname } from "path";
 import { platform } from "os";
 import process from "process";
 
@@ -60,6 +60,21 @@ function run(cmd, opts = {}) {
     });
     return true;
   } catch (e) {
+    // Provide detailed error information
+    const errorMsg = opts.silent && e.stderr
+      ? e.stderr.toString().trim()
+      : e.message;
+
+    if (!opts.silent) {
+      log.error(`Command failed: ${cmd}`);
+      if (errorMsg) {
+        log.error(`Error: ${errorMsg}`);
+      }
+      if (e.status) {
+        log.error(`Exit code: ${e.status}`);
+      }
+    }
+
     return false;
   }
 }
@@ -77,18 +92,46 @@ function hasCmd(cmd) {
 
 /** Write file only if it doesn't exist (or DRY_RUN) */
 function writeIfMissing(filePath, content, description) {
-  const full = join(TARGET_DIR, filePath);
+  // Normalize path separators for cross-platform compatibility
+  const normalizedPath = filePath.split(/[/\\]+/).join(sep);
+
+  // Resolve full path
+  const full = resolve(TARGET_DIR, normalizedPath);
+
+  // SECURITY: Verify resolved path stays within TARGET_DIR
+  const normalizedTarget = resolve(TARGET_DIR);
+  if (!full.startsWith(normalizedTarget + sep) && full !== normalizedTarget) {
+    log.error(`Security: Path traversal detected in "${filePath}"`);
+    log.error(`Attempted to write outside target directory`);
+    process.exit(1);
+  }
+
   if (existsSync(full)) {
     log.skip(`${filePath} already exists`);
     return;
   }
+
   if (DRY_RUN) {
     log.info(`[DRY RUN] Would create: ${filePath}`);
     return;
   }
-  mkdirSync(join(TARGET_DIR, filePath.split("/").slice(0, -1).join("/")), { recursive: true });
-  writeFileSync(full, content, "utf8");
-  log.ok(`Created ${filePath}${description ? ` — ${description}` : ""}`);
+
+  // Use dirname instead of string manipulation
+  const parentDir = dirname(full);
+  try {
+    mkdirSync(parentDir, { recursive: true });
+  } catch (err) {
+    log.error(`Failed to create directory ${parentDir}: ${err.message}`);
+    process.exit(1);
+  }
+
+  try {
+    writeFileSync(full, content, "utf8");
+    log.ok(`Created ${filePath}${description ? ` — ${description}` : ""}`);
+  } catch (err) {
+    log.error(`Failed to write ${filePath}: ${err.message}`);
+    process.exit(1);
+  }
 }
 
 /** Append to .gitignore if entry is missing */
@@ -110,7 +153,7 @@ function gitignoreAdd(entry, comment) {
 // ─── Banner ───────────────────────────────────────────────────────────────────
 console.log(`
 ${c.bold}╔══════════════════════════════════════════╗
-║         AI Stack Init  v1.0              ║
+║    OpenSpec Stack Init  v1.0             ║
 ║  OpenSpec + Beads + claude-mem + skills  ║
 ╚══════════════════════════════════════════╝${c.reset}
   Project : ${c.cyan}${PROJECT_NAME}${c.reset}
@@ -123,6 +166,29 @@ if (!existsSync(TARGET_DIR)) {
   process.exit(1);
 }
 
+// Validate it's actually a directory
+try {
+  const stats = statSync(TARGET_DIR);
+  if (!stats.isDirectory()) {
+    log.error(`Target path is not a directory: ${TARGET_DIR}`);
+    process.exit(1);
+  }
+} catch (err) {
+  log.error(`Failed to access target directory: ${err.message}`);
+  process.exit(1);
+}
+
+// Test write permissions
+const testFile = join(TARGET_DIR, `.openspec-test-${Date.now()}`);
+try {
+  writeFileSync(testFile, '');
+  unlinkSync(testFile);
+} catch (permErr) {
+  log.error(`No write permission for directory: ${TARGET_DIR}`);
+  log.error(`Error: ${permErr.message}`);
+  process.exit(1);
+}
+
 // ─── 1. Dependency check ──────────────────────────────────────────────────────
 log.step("Checking required tools");
 
@@ -154,16 +220,31 @@ log.step("OpenSpec — init");
 if (existsSync(join(TARGET_DIR, "openspec"))) {
   log.skip("openspec/ already exists");
 } else if (hasCmd("openspec")) {
-  // --tools claude   : select Claude Code without interactive prompt
-  // --profile expanded: enable all workflow commands (new, ff, verify, sync, etc.)
-  // --force          : skip all remaining prompts, auto-cleanup legacy files
-  const ok = run("openspec init --tools claude --profile expanded --force");
+  // --tools claude : select Claude Code without interactive prompt
+  // --profile core : valid profile for init (expanded is set separately after)
+  // --force        : skip all remaining prompts, auto-cleanup legacy files
+  const ok = run("openspec init --tools claude --profile core --force");
   if (ok) {
-    log.ok("OpenSpec initialized (expanded profile, Claude tools)");
+    log.ok("OpenSpec initialized (core profile, Claude tools)");
+
+    // Remove default config.yaml so custom template can be written in Step 3
+    const defaultConfig = join(TARGET_DIR, "openspec", "config.yaml");
+    if (existsSync(defaultConfig)) {
+      unlinkSync(defaultConfig);
+    }
+
+    // Switch to expanded profile to unlock: new, ff, verify, sync, bulk-archive, onboard
+    // openspec config profile sets the global default, openspec update regenerates skill files
+    const expanded = run("openspec config profile expanded", { silent: true }) &&
+                     run("openspec update --tools claude --force", { silent: true });
+    if (expanded) {
+      log.ok("OpenSpec profile upgraded to expanded");
+    } else {
+      log.warn("Could not auto-upgrade to expanded profile.");
+      log.warn("Run manually: openspec config profile  →  then select expanded  →  openspec update");
+    }
   } else {
-    // Fallback: openspec init may not support --force on older versions
-    log.warn("Non-interactive init failed — trying interactive...");
-    log.warn("Run manually: openspec init --tools claude --profile expanded");
+    log.warn("OpenSpec init failed — run manually: openspec init --tools claude --profile core --force");
   }
 } else {
   log.warn("openspec not found — skipping");
@@ -183,15 +264,16 @@ context: |
   Project: ${PROJECT_NAME}
 
   # TODO: fill in your actual stack and conventions
-  # Tech stack: Unity 2022, C#, Flutter backend
-  # Architecture: HMVC
-  # Testing: NUnit
-  # Key constraints: legacy codebase, brownfield migration
+  # Tech stack: e.g. TypeScript, React, Node.js / Unity, C# / Python, Django
+  # Architecture: e.g. MVC, HMVC, ECS, Redux, MVVM, microservices
+  # Testing: e.g. Jest, NUnit, pytest
+  # Key constraints: e.g. legacy codebase, must support IE11, no breaking API changes
 
 rules:
   proposal:
     - Always include a rollback plan for legacy code changes
     - List all affected modules
+    - Always include an "## Alternatives Considered" section listing at least 2 alternative approaches with their pros, cons, and reason for rejection. Format each as: "### Option: <name> / Pros: ... / Cons: ... / Why rejected: ..."
   specs:
     - Use Given/When/Then format for scenarios
   design:
@@ -214,10 +296,12 @@ const beadsInitialized =
 if (beadsInitialized) {
   log.skip("Beads already initialized");
 } else if (hasCmd("bd")) {
-  // --quiet: non-interactive, no prompts, no spinner
-  const ok = run("bd init --quiet");
+  // --quiet: non-interactive mode
+  // echo N: answers "Contributing to someone else's repo? [y/N]" automatically
+  const bdCmd = "echo N | bd init --quiet";
+  const ok = run(bdCmd);
   if (ok) log.ok("Beads initialized (quiet mode)");
-  else log.warn("bd init failed — run manually: bd init --quiet");
+  else log.warn("bd init failed — run manually: echo N | bd init --quiet");
 } else {
   log.warn("bd not found — skipping Beads init");
 }
@@ -279,21 +363,26 @@ log.step("Skill — /migrate-to-openspec (brownfield migration)");
 
 // The skill files are bundled alongside this script in ../skills/
 import { fileURLToPath } from "url";
-import { dirname, join as pathJoin } from "path";
 import { cpSync } from "fs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const skillSrc = pathJoin(__dirname, "..", "skills", "migrate-to-openspec");
+const skillSrc = join(__dirname, "..", "skills", "migrate-to-openspec");
 const skillDst = join(TARGET_DIR, ".claude", "skills", "migrate-to-openspec");
 
 if (existsSync(skillDst)) {
   log.skip(".claude/skills/migrate-to-openspec/ already exists");
 } else if (existsSync(skillSrc)) {
   if (!DRY_RUN) {
-    mkdirSync(join(TARGET_DIR, ".claude", "skills"), { recursive: true });
-    cpSync(skillSrc, skillDst, { recursive: true });
-    log.ok("Skill /migrate-to-openspec installed → .claude/skills/migrate-to-openspec/");
+    try {
+      mkdirSync(join(TARGET_DIR, ".claude", "skills"), { recursive: true });
+      cpSync(skillSrc, skillDst, { recursive: true });
+      log.ok("Skill /migrate-to-openspec installed → .claude/skills/migrate-to-openspec/");
+    } catch (err) {
+      log.error(`Failed to install skill: ${err.message}`);
+      log.warn("Continuing without skill installation...");
+      // Don't exit - skill is optional enhancement
+    }
   } else {
     log.info("[DRY RUN] Would install: .claude/skills/migrate-to-openspec/");
   }