forgedock 1.0.0 → 1.0.2

package/README.md

@@ -217,19 +217,36 @@ The path from here to there is incremental. Each piece — the knowledge store,
 
 ## Install
 
+**Step 1: Install commands**
+
 ```bash
 npx forgedock
 ```
 
-That's it. One command — installs all pipeline commands into your Claude Code environment.
+This symlinks all pipeline commands into your Claude Code environment (`~/.claude/commands/`).
+
+**Step 2: Generate config**
+
+```bash
+npx forgedock init         # Auto-detects your repo, owner, and branches
+```
+
+Creates `forge.yaml` in your project root — the config file that makes ForgeDock work with your repo instead of a hardcoded one. Edit it to fill in your project details.
+
+**Step 3: AI-powered setup (optional)**
+
+```
+/forgedock-init            # Inside Claude Code — guided full config walkthrough
+```
 
-Requires [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and [GitHub CLI](https://cli.github.com/). ForgeDock reads your project's `CLAUDE.md` for conventions — no extra config needed.
+Requires [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and [GitHub CLI](https://cli.github.com/).
 
 **Other commands:**
 
 ```bash
 npx forgedock update      # Pull latest commands
 npx forgedock uninstall   # Remove all commands
+npx forgedock help        # Show all commands
 ```
 
 ---

package/bin/forgedock.mjs

@@ -3,13 +3,27 @@
 import { fileURLToPath } from "url";
 import { dirname, join, relative } from "path";
 import { mkdir, symlink, readlink, lstat, readdir, stat } from "fs/promises";
-import { existsSync, appendFileSync, readFileSync } from "fs";
+import {
+  existsSync,
+  appendFileSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+} from "fs";
 import { execSync } from "child_process";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const FORGE_HOME = dirname(__dirname);
 const COMMANDS_DIR = join(FORGE_HOME, "commands");
+
+if (!process.env.HOME) {
+  console.error(
+    "Error: HOME environment variable is not set. Cannot determine install location.",
+  );
+  process.exit(1);
+}
+
 const TARGET_DIR = join(process.env.HOME, ".claude", "commands");
 
 const args = process.argv.slice(2);
@@ -73,7 +87,7 @@ async function install() {
         }
       } else {
         console.log(
-          `  ${YELLOW}WARNING${RESET}: ${rel} is a regular file — skipping (remove it manually to let ForgeDock manage it)`
+          `  ${YELLOW}WARNING${RESET}: ${rel} is a regular file — skipping (remove it manually to let ForgeDock manage it)`,
         );
         skipped++;
       }
@@ -87,7 +101,7 @@ async function install() {
 
   console.log("");
   console.log(
-    `Done. ${GREEN}Installed: ${installed}${RESET}, Updated: ${updated}, Skipped: ${skipped}`
+    `Done. ${GREEN}Installed: ${installed}${RESET}, Updated: ${updated}, Skipped: ${skipped}`,
   );
   console.log("");
 
@@ -102,7 +116,7 @@ async function install() {
       if (!content.includes("FORGE_HOME")) {
         appendFileSync(
           profile,
-          `\n# ForgeDock — autonomous development pipeline\nexport FORGE_HOME="${FORGE_HOME}"\n`
+          `\n# ForgeDock — autonomous development pipeline\nexport FORGE_HOME="${FORGE_HOME}"\n`,
         );
         console.log(`  Added FORGE_HOME to ${profile}`);
         profileUpdated = true;
@@ -111,9 +125,19 @@ async function install() {
   }
 
   console.log(
-    `${GREEN}ForgeDock commands are now available as slash commands in any Claude Code session.${RESET}`
+    `${GREEN}ForgeDock commands are now available as slash commands in any Claude Code session.${RESET}`,
   );
   console.log("");
+
+  // forge.yaml advisory — guide users to run init if config is missing
+  const forgeYamlPath = join(process.cwd(), "forge.yaml");
+  if (!existsSync(forgeYamlPath)) {
+    console.log(`${YELLOW}No forge.yaml found in current directory.${RESET}`);
+    console.log(
+      `  Run ${CYAN}npx forgedock init${RESET} in your project root to generate forge.yaml`,
+    );
+    console.log("");
+  }
 }
 
 async function uninstall() {
@@ -188,24 +212,273 @@ async function update() {
       }
     } catch (err) {
       console.log(
-        `  ${YELLOW}Cannot fast-forward — local changes exist. Skipping.${RESET}`
+        `  ${YELLOW}Cannot fast-forward — local changes exist. Skipping.${RESET}`,
       );
     }
   } else {
-    console.log(`  Installed via npm. Run ${CYAN}npm update -g forgedock${RESET} to update.`);
+    console.log(
+      `  Installed via npm. Run ${CYAN}npm update -g forgedock${RESET} to update.`,
+    );
   }
   console.log("");
 }
 
+async function init() {
+  console.log("");
+  console.log(`${BOLD}ForgeDock${RESET} — Generating forge.yaml`);
+  console.log("");
+
+  const cwd = process.cwd();
+  const worktreeBase = join(cwd, ".claude", "worktrees");
+  const outputPath = join(cwd, "forge.yaml");
+
+  // --- Detect git remote URL and parse owner/repo ---
+  let owner = "your-github-org";
+  let repo = "your-repo-name";
+  let remoteDetected = false;
+
+  try {
+    const remoteUrl = execSync("git remote get-url origin", {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+
+    // SSH: git@github.com:owner/repo.git
+    const sshMatch = remoteUrl.match(/^git@[^:]+:([^/]+)\/(.+?)(?:\.git)?$/);
+    // HTTPS: https://github.com/owner/repo.git
+    const httpsMatch = remoteUrl.match(
+      /^https?:\/\/[^/]+\/([^/]+)\/(.+?)(?:\.git)?$/,
+    );
+
+    if (sshMatch) {
+      owner = sshMatch[1];
+      repo = sshMatch[2];
+      remoteDetected = true;
+    } else if (httpsMatch) {
+      owner = httpsMatch[1];
+      repo = httpsMatch[2];
+      remoteDetected = true;
+    } else {
+      console.log(
+        `  ${YELLOW}Warning${RESET}: Could not parse git remote URL — using placeholder values`,
+      );
+    }
+  } catch {
+    console.log(
+      `  ${YELLOW}Warning${RESET}: No git remote found — using placeholder values`,
+    );
+  }
+
+  if (remoteDetected) {
+    console.log(`  Detected repo:   ${CYAN}${owner}/${repo}${RESET}`);
+  }
+
+  // --- Detect default branch ---
+  let defaultBranch = "main";
+  try {
+    const headRef = execSync("git symbolic-ref refs/remotes/origin/HEAD", {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    // refs/remotes/origin/main → main
+    defaultBranch = headRef.replace(/^refs\/remotes\/origin\//, "");
+    console.log(`  Default branch:  ${CYAN}${defaultBranch}${RESET}`);
+  } catch {
+    // Fallback: try git rev-parse
+    try {
+      defaultBranch = execSync("git rev-parse --abbrev-ref HEAD", {
+        cwd,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+      if (defaultBranch === "HEAD") defaultBranch = "main";
+      console.log(
+        `  Default branch:  ${CYAN}${defaultBranch}${RESET} (from current branch)`,
+      );
+    } catch {
+      console.log(
+        `  ${YELLOW}Warning${RESET}: Could not detect default branch — defaulting to "main"`,
+      );
+    }
+  }
+
+  // --- Detect staging branch ---
+  let stagingBranch = "staging";
+  try {
+    const remoteBranches = execSync("git branch -r", {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    if (remoteBranches.includes("origin/staging")) {
+      stagingBranch = "staging";
+      console.log(`  Staging branch:  ${CYAN}staging${RESET} (detected)`);
+    } else {
+      stagingBranch = defaultBranch;
+      console.log(
+        `  Staging branch:  ${CYAN}${defaultBranch}${RESET} (no staging branch found — using default)`,
+      );
+    }
+  } catch {
+    console.log(
+      `  ${YELLOW}Warning${RESET}: Could not read remote branches — defaulting staging to "${defaultBranch}"`,
+    );
+    stagingBranch = defaultBranch;
+  }
+
+  // --- Handle existing forge.yaml ---
+  if (existsSync(outputPath)) {
+    const baseBak = join(cwd, "forge.yaml.bak");
+    const backupPath = existsSync(baseBak)
+      ? join(
+          cwd,
+          `forge.yaml.bak.${new Date().toISOString().replace(/[:.]/g, "-")}`,
+        )
+      : baseBak;
+    const backupName = backupPath.split("/").pop();
+    renameSync(outputPath, backupPath);
+    console.log(`  ${YELLOW}Backed up${RESET}: forge.yaml → ${backupName}`);
+  }
+
+  // --- Generate forge.yaml content ---
+  const projectName = repo
+    .split(/[-_]/)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ");
+
+  const content = `# forge.yaml — ForgeDock Configuration
+#
+# Auto-generated by: npx forgedock init
+# Edit this file with your project details.
+#
+# Required sections: project, paths, branches
+# Optional sections: repos, project_board, services, review, verification
+#
+# See docs/CONFIG.md for full reference.
+
+# =============================================================================
+# PROJECT (REQUIRED)
+# =============================================================================
+
+project:
+  name: "${projectName}"
+  owner: "${owner}"
+  repo: "${repo}"
+  description: ""
+
+# =============================================================================
+# PATHS (REQUIRED)
+# =============================================================================
+
+paths:
+  root: "${cwd}"
+  worktree_base: "${worktreeBase}"
+
+# =============================================================================
+# BRANCHES (REQUIRED)
+# =============================================================================
+
+branches:
+  default: "${defaultBranch}"
+  staging: "${stagingBranch}"
+  feature_pattern: "milestone/{slug}"
+
+# =============================================================================
+# REPOS (OPTIONAL)
+# Multi-repo configuration. Remove the # to enable.
+# =============================================================================
+
+# repos:
+#   default:
+#     repo: "${owner}/${repo}"
+#     staging_branch: "${stagingBranch}"
+#   satellites:
+#     - prefix: "mcp"
+#       repo: "${owner}/your-satellite-repo"
+#       staging_branch: "main"
+#       local_path: "${join(cwd, "..", "your-satellite-repo")}"
+
+# =============================================================================
+# PROJECT BOARD (OPTIONAL)
+# GitHub Projects v2 integration.
+# To find IDs: gh project list --owner ${owner}
+# =============================================================================
+
+# project_board:
+#   owner: "${owner}"
+#   project_number: 1
+#   project_id: "PVT_kwHOxxxxxxxxxxxxxxxx"
+#   field_ids:
+#     status: "PVTSSF_xxxxxxxxxxxxxxxxxxxxxxxx"
+#     lane: "PVTSSF_xxxxxxxxxxxxxxxxxxxxxxxx"
+#     component: "PVTSSF_xxxxxxxxxxxxxxxxxxxxxxxx"
+#     priority: "PVTSSF_xxxxxxxxxxxxxxxxxxxxxxxx"
+#     workflow: "PVTSSF_xxxxxxxxxxxxxxxxxxxxxxxx"
+
+# =============================================================================
+# REVIEW (OPTIONAL)
+# Context injected into review agent prompts.
+# =============================================================================
+
+# review:
+#   tech_stack: "Node.js, TypeScript, PostgreSQL"
+#   context: |
+#     Describe your repo structure and any unusual conventions here.
+
+# =============================================================================
+# VERIFICATION (OPTIONAL)
+# Health-check patterns for quality gate and validate commands.
+# =============================================================================
+
+# verification:
+#   health_endpoint: "https://api.${repo}.io/health"
+#   health_patterns:
+#     - '"status": "ok"'
+`;
+
+  writeFileSync(outputPath, content, "utf-8");
+
+  console.log(`  ${GREEN}Created${RESET}: forge.yaml`);
+  console.log("");
+  console.log(`${BOLD}Next steps:${RESET}`);
+  console.log(
+    `  1. Edit ${CYAN}forge.yaml${RESET} — fill in your project details`,
+  );
+  console.log(`     Required: project.name, project.description`);
+  if (!remoteDetected) {
+    console.log(
+      `     Required: project.owner, project.repo (could not auto-detect)`,
+    );
+  }
+  console.log(
+    `  2. Add ${CYAN}forge.yaml${RESET} to ${CYAN}.gitignore${RESET} if it contains sensitive paths`,
+  );
+  console.log(
+    `  3. Run ${CYAN}/forgedock-init${RESET} inside Claude Code for guided AI-powered setup`,
+  );
+  console.log("");
+}
+
 function help() {
   console.log("");
-  console.log(`${BOLD}ForgeDock${RESET} — GitHub as a knowledge graph for AI agents`);
+  console.log(
+    `${BOLD}ForgeDock${RESET} — GitHub as a knowledge graph for AI agents`,
+  );
   console.log("");
   console.log("Usage:");
-  console.log(`  ${CYAN}npx forgedock${RESET}            Install commands (default)`);
+  console.log(
+    `  ${CYAN}npx forgedock${RESET}            Install commands (default)`,
+  );
   console.log(`  ${CYAN}npx forgedock install${RESET}    Install commands`);
+  console.log(
+    `  ${CYAN}npx forgedock init${RESET}       Generate forge.yaml config for your project`,
+  );
   console.log(`  ${CYAN}npx forgedock uninstall${RESET}  Remove commands`);
-  console.log(`  ${CYAN}npx forgedock update${RESET}     Pull latest & reinstall`);
+  console.log(
+    `  ${CYAN}npx forgedock update${RESET}     Pull latest & reinstall`,
+  );
   console.log(`  ${CYAN}npx forgedock help${RESET}       Show this help`);
   console.log("");
 }
@@ -214,6 +487,9 @@ switch (command) {
   case "install":
     await install();
     break;
+  case "init":
+    await init();
+    break;
   case "uninstall":
     await uninstall();
     break;