@saga-ai/cli 0.1.0 → 0.1.2

package/README.md

@@ -2,16 +2,20 @@
 
 Command-line interface for SAGA (Structured Autonomous Goal Achievement) - a structured development workflow that combines human-guided epic planning with autonomous story execution.
 
-## Installation
-
-```bash
-npm install -g @saga-ai/cli
-```
-
 ## Requirements
 
 - Node.js >= 18.0.0
-- [Claude CLI](https://docs.anthropic.com/en/docs/claude-cli) (for `implement` command)
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (for `implement` command)
+
+## Usage
+
+Run commands using npx (no global installation required):
+
+```bash
+npx @saga-ai/cli init
+npx @saga-ai/cli implement <story-slug>
+npx @saga-ai/cli dashboard
+```
 
 ## Commands
 

package/dist/cli.cjs

@@ -26,9 +26,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 
-// node_modules/commander/lib/error.js
+// node_modules/.pnpm/commander@12.1.0/node_modules/commander/lib/error.js
 var require_error = __commonJS({
-  "node_modules/commander/lib/error.js"(exports2) {
+  "node_modules/.pnpm/commander@12.1.0/node_modules/commander/lib/error.js"(exports2) {
     var CommanderError2 = class extends Error {
       /**
        * Constructs the CommanderError class
@@ -61,9 +61,9 @@ var require_error = __commonJS({
   }
 });
 
-// node_modules/commander/lib/argument.js
+// node_modules/.pnpm/commander@12.1.0/node_modules/commander/lib/argument.js
 var require_argument = __commonJS({
-  "node_modules/commander/lib/argument.js"(exports2) {
+  "node_modules/.pnpm/commander@12.1.0/node_modules/commander/lib/argument.js"(exports2) {
     var { InvalidArgumentError: InvalidArgumentError2 } = require_error();
     var Argument2 = class {
       /**
@@ -188,9 +188,9 @@ var require_argument = __commonJS({
   }
 });
 
-// node_modules/commander/lib/help.js
+// node_modules/.pnpm/commander@12.1.0/node_modules/commander/lib/help.js
 var require_help = __commonJS({
-  "node_modules/commander/lib/help.js"(exports2) {
+  "node_modules/.pnpm/commander@12.1.0/node_modules/commander/lib/help.js"(exports2) {
     var { humanReadableArgName } = require_argument();
     var Help2 = class {
       constructor() {
@@ -602,9 +602,9 @@ var require_help = __commonJS({
   }
 });
 
-// node_modules/commander/lib/option.js
+// node_modules/.pnpm/commander@12.1.0/node_modules/commander/lib/option.js
 var require_option = __commonJS({
-  "node_modules/commander/lib/option.js"(exports2) {
+  "node_modules/.pnpm/commander@12.1.0/node_modules/commander/lib/option.js"(exports2) {
     var { InvalidArgumentError: InvalidArgumentError2 } = require_error();
     var Option2 = class {
       /**
@@ -874,9 +874,9 @@ var require_option = __commonJS({
   }
 });
 
-// node_modules/commander/lib/suggestSimilar.js
+// node_modules/.pnpm/commander@12.1.0/node_modules/commander/lib/suggestSimilar.js
 var require_suggestSimilar = __commonJS({
-  "node_modules/commander/lib/suggestSimilar.js"(exports2) {
+  "node_modules/.pnpm/commander@12.1.0/node_modules/commander/lib/suggestSimilar.js"(exports2) {
     var maxDistance = 3;
     function editDistance(a, b) {
       if (Math.abs(a.length - b.length) > maxDistance)
@@ -954,9 +954,9 @@ var require_suggestSimilar = __commonJS({
   }
 });
 
-// node_modules/commander/lib/command.js
+// node_modules/.pnpm/commander@12.1.0/node_modules/commander/lib/command.js
 var require_command = __commonJS({
-  "node_modules/commander/lib/command.js"(exports2) {
+  "node_modules/.pnpm/commander@12.1.0/node_modules/commander/lib/command.js"(exports2) {
     var EventEmitter = require("node:events").EventEmitter;
     var childProcess = require("node:child_process");
     var path = require("node:path");
@@ -2997,9 +2997,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
   }
 });
 
-// node_modules/commander/index.js
+// node_modules/.pnpm/commander@12.1.0/node_modules/commander/index.js
 var require_commander = __commonJS({
-  "node_modules/commander/index.js"(exports2) {
+  "node_modules/.pnpm/commander@12.1.0/node_modules/commander/index.js"(exports2) {
     var { Argument: Argument2 } = require_argument();
     var { Command: Command2 } = require_command();
     var { CommanderError: CommanderError2, InvalidArgumentError: InvalidArgumentError2 } = require_error();
@@ -3019,7 +3019,7 @@ var require_commander = __commonJS({
   }
 });
 
-// node_modules/commander/esm.mjs
+// node_modules/.pnpm/commander@12.1.0/node_modules/commander/esm.mjs
 var import_index = __toESM(require_commander(), 1);
 var {
   program,
@@ -3083,6 +3083,62 @@ Make sure the path points to a SAGA project root.`
 
 // src/commands/init.ts
 var WORKTREES_PATTERN = ".saga/worktrees/";
+function runInitDryRun(targetPath) {
+  const sagaDir = (0, import_node_path2.join)(targetPath, ".saga");
+  const sagaExists = (0, import_node_fs2.existsSync)(sagaDir);
+  const directories = [
+    { name: "epics", path: (0, import_node_path2.join)(sagaDir, "epics") },
+    { name: "archive", path: (0, import_node_path2.join)(sagaDir, "archive") },
+    { name: "worktrees", path: (0, import_node_path2.join)(sagaDir, "worktrees") }
+  ].map((dir) => ({
+    path: dir.path,
+    exists: (0, import_node_fs2.existsSync)(dir.path),
+    action: (0, import_node_fs2.existsSync)(dir.path) ? "exists (skip)" : "will create"
+  }));
+  const gitignorePath = (0, import_node_path2.join)(targetPath, ".gitignore");
+  const gitignoreExists = (0, import_node_fs2.existsSync)(gitignorePath);
+  let hasPattern = false;
+  if (gitignoreExists) {
+    const content = (0, import_node_fs2.readFileSync)(gitignorePath, "utf-8");
+    hasPattern = content.includes(WORKTREES_PATTERN);
+  }
+  let gitignoreAction;
+  if (!gitignoreExists) {
+    gitignoreAction = "will create with worktrees pattern";
+  } else if (hasPattern) {
+    gitignoreAction = "already has pattern (skip)";
+  } else {
+    gitignoreAction = "will append worktrees pattern";
+  }
+  return {
+    targetPath,
+    sagaExists,
+    directories,
+    gitignore: {
+      path: gitignorePath,
+      exists: gitignoreExists,
+      hasPattern,
+      action: gitignoreAction
+    }
+  };
+}
+function printInitDryRunResults(result) {
+  console.log("Dry Run - Init Command");
+  console.log("======================\n");
+  console.log(`Target directory: ${result.targetPath}`);
+  console.log(`SAGA project exists: ${result.sagaExists ? "yes" : "no"}
+`);
+  console.log("Directories:");
+  for (const dir of result.directories) {
+    const icon = dir.exists ? "-" : "+";
+    console.log(`  ${icon} ${dir.path}`);
+    console.log(`    Action: ${dir.action}`);
+  }
+  console.log("\nGitignore:");
+  console.log(`  Path: ${result.gitignore.path}`);
+  console.log(`  Action: ${result.gitignore.action}`);
+  console.log("\nDry run complete. No changes made.");
+}
 function resolveTargetPath(explicitPath) {
   if (explicitPath) {
     return explicitPath;
@@ -3138,6 +3194,11 @@ async function initCommand(options) {
     }
   }
   const targetPath = resolveTargetPath(options.path);
+  if (options.dryRun) {
+    const dryRunResult = runInitDryRun(targetPath);
+    printInitDryRunResults(dryRunResult);
+    return;
+  }
   createDirectoryStructure(targetPath);
   updateGitignore(targetPath);
   console.log(`Initialized .saga/ at ${targetPath}`);
@@ -3171,25 +3232,32 @@ var WORKER_OUTPUT_SCHEMA = {
   required: ["status", "summary"]
 };
 function findStory(projectPath, storySlug) {
-  const epicsDir = (0, import_node_path3.join)(projectPath, ".saga", "epics");
-  if (!(0, import_node_fs3.existsSync)(epicsDir)) {
+  const worktreesDir = (0, import_node_path3.join)(projectPath, ".saga", "worktrees");
+  if (!(0, import_node_fs3.existsSync)(worktreesDir)) {
     return null;
   }
-  const epicDirs = (0, import_node_fs3.readdirSync)(epicsDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+  const epicDirs = (0, import_node_fs3.readdirSync)(worktreesDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
   for (const epicSlug of epicDirs) {
-    const storiesDir = (0, import_node_path3.join)(epicsDir, epicSlug, "stories");
-    if (!(0, import_node_fs3.existsSync)(storiesDir)) {
+    const epicWorktreeDir = (0, import_node_path3.join)(worktreesDir, epicSlug);
+    const storyWorktree = (0, import_node_path3.join)(epicWorktreeDir, storySlug);
+    if (!(0, import_node_fs3.existsSync)(storyWorktree)) {
       continue;
     }
-    const storyDir = (0, import_node_path3.join)(storiesDir, storySlug);
-    const storyPath = (0, import_node_path3.join)(storyDir, "story.md");
+    const storyPath = (0, import_node_path3.join)(
+      storyWorktree,
+      ".saga",
+      "epics",
+      epicSlug,
+      "stories",
+      storySlug,
+      "story.md"
+    );
     if ((0, import_node_fs3.existsSync)(storyPath)) {
-      const worktreePath = (0, import_node_path3.join)(projectPath, ".saga", "worktrees", epicSlug, storySlug);
       return {
         epicSlug,
         storySlug,
         storyPath,
-        worktreePath
+        worktreePath: storyWorktree
       };
     }
   }
@@ -3228,6 +3296,135 @@ This may indicate an incomplete story setup.`
 function getSkillRoot(pluginRoot) {
   return (0, import_node_path3.join)(pluginRoot, "skills", "execute-story");
 }
+function checkCommandExists(command) {
+  try {
+    const result = (0, import_node_child_process.spawnSync)("which", [command], { encoding: "utf-8" });
+    if (result.status === 0 && result.stdout.trim()) {
+      return { exists: true, path: result.stdout.trim() };
+    }
+    return { exists: false };
+  } catch {
+    return { exists: false };
+  }
+}
+function runDryRun(storyInfo, projectPath, pluginRoot) {
+  const checks = [];
+  let allPassed = true;
+  if (pluginRoot) {
+    checks.push({
+      name: "SAGA_PLUGIN_ROOT",
+      path: pluginRoot,
+      passed: true
+    });
+  } else {
+    checks.push({
+      name: "SAGA_PLUGIN_ROOT",
+      passed: false,
+      error: "Environment variable not set"
+    });
+    allPassed = false;
+  }
+  const claudeCheck = checkCommandExists("claude");
+  checks.push({
+    name: "claude CLI",
+    path: claudeCheck.path,
+    passed: claudeCheck.exists,
+    error: claudeCheck.exists ? void 0 : "Command not found in PATH"
+  });
+  if (!claudeCheck.exists) allPassed = false;
+  if (pluginRoot) {
+    const skillRoot = getSkillRoot(pluginRoot);
+    const workerPromptPath = (0, import_node_path3.join)(skillRoot, WORKER_PROMPT_RELATIVE);
+    if ((0, import_node_fs3.existsSync)(workerPromptPath)) {
+      checks.push({
+        name: "Worker prompt",
+        path: workerPromptPath,
+        passed: true
+      });
+    } else {
+      checks.push({
+        name: "Worker prompt",
+        path: workerPromptPath,
+        passed: false,
+        error: "File not found"
+      });
+      allPassed = false;
+    }
+  }
+  checks.push({
+    name: "Story found",
+    path: `${storyInfo.storySlug} (epic: ${storyInfo.epicSlug})`,
+    passed: true
+  });
+  if ((0, import_node_fs3.existsSync)(storyInfo.worktreePath)) {
+    checks.push({
+      name: "Worktree exists",
+      path: storyInfo.worktreePath,
+      passed: true
+    });
+  } else {
+    checks.push({
+      name: "Worktree exists",
+      path: storyInfo.worktreePath,
+      passed: false,
+      error: "Directory not found"
+    });
+    allPassed = false;
+  }
+  if ((0, import_node_fs3.existsSync)(storyInfo.worktreePath)) {
+    const storyMdPath = computeStoryPath(
+      storyInfo.worktreePath,
+      storyInfo.epicSlug,
+      storyInfo.storySlug
+    );
+    if ((0, import_node_fs3.existsSync)(storyMdPath)) {
+      checks.push({
+        name: "story.md in worktree",
+        path: storyMdPath,
+        passed: true
+      });
+    } else {
+      checks.push({
+        name: "story.md in worktree",
+        path: storyMdPath,
+        passed: false,
+        error: "File not found"
+      });
+      allPassed = false;
+    }
+  }
+  return {
+    success: allPassed,
+    checks,
+    story: {
+      epicSlug: storyInfo.epicSlug,
+      storySlug: storyInfo.storySlug,
+      worktreePath: storyInfo.worktreePath
+    }
+  };
+}
+function printDryRunResults(result) {
+  console.log("Dry Run Validation");
+  console.log("==================\n");
+  for (const check of result.checks) {
+    const icon = check.passed ? "\u2713" : "\u2717";
+    const status = check.passed ? "OK" : "FAILED";
+    if (check.passed) {
+      console.log(`${icon} ${check.name}: ${check.path || status}`);
+    } else {
+      console.log(`${icon} ${check.name}: ${check.error}`);
+      if (check.path) {
+        console.log(`  Expected: ${check.path}`);
+      }
+    }
+  }
+  console.log("");
+  if (result.success) {
+    console.log("Dry run complete. All checks passed. Ready to implement.");
+  } else {
+    console.log("Dry run failed. Please fix the issues above before running implement.");
+  }
+}
 function loadWorkerPrompt(pluginRoot) {
   const skillRoot = getSkillRoot(pluginRoot);
   const promptPath = (0, import_node_path3.join)(skillRoot, WORKER_PROMPT_RELATIVE);
@@ -3236,10 +3433,8 @@ function loadWorkerPrompt(pluginRoot) {
   }
   return (0, import_node_fs3.readFileSync)(promptPath, "utf-8");
 }
-function buildScopeSettings(pluginRoot) {
-  const skillRoot = getSkillRoot(pluginRoot);
-  const validatorPath = (0, import_node_path3.join)(skillRoot, "scripts", "scope_validator.py");
-  const hookCommand = `python3 ${validatorPath}`;
+function buildScopeSettings() {
+  const hookCommand = "npx @saga-ai/cli scope-validator";
   return {
     hooks: {
       PreToolUse: [
@@ -3337,7 +3532,7 @@ function runLoop(epicSlug, storySlug, maxCycles, maxTime, model, projectDir, plu
       storySlug
     };
   }
-  const settings = buildScopeSettings(pluginRoot);
+  const settings = buildScopeSettings();
   const startTime = Date.now();
   let cycles = 0;
   const summaries = [];
@@ -3416,17 +3611,23 @@ async function implementCommand(storySlug, options) {
   if (!storyInfo) {
     console.error(`Error: Story '${storySlug}' not found in SAGA project.`);
     console.error(`
-Searched in: ${(0, import_node_path3.join)(projectPath, ".saga", "epics")}`);
-    console.error("\nMake sure the story exists and has a story.md file.");
+Searched in: ${(0, import_node_path3.join)(projectPath, ".saga", "worktrees")}`);
+    console.error("\nMake sure the story worktree exists and has a story.md file.");
+    console.error("Run /generate-stories to create story worktrees.");
     process.exit(1);
   }
+  const pluginRoot = process.env.SAGA_PLUGIN_ROOT;
+  if (options.dryRun) {
+    const dryRunResult = runDryRun(storyInfo, projectPath, pluginRoot);
+    printDryRunResults(dryRunResult);
+    process.exit(dryRunResult.success ? 0 : 1);
+  }
   if (!(0, import_node_fs3.existsSync)(storyInfo.worktreePath)) {
     console.error(`Error: Worktree not found at ${storyInfo.worktreePath}`);
     console.error("\nThe story worktree has not been created yet.");
     console.error("Make sure the story was properly generated with /generate-stories.");
     process.exit(1);
   }
-  const pluginRoot = process.env.SAGA_PLUGIN_ROOT;
   if (!pluginRoot) {
     console.error("Error: SAGA_PLUGIN_ROOT environment variable is not set.");
     console.error("\nThis variable is required for the implementation script.");
@@ -3476,23 +3677,114 @@ async function dashboardCommand(options) {
   console.log("Note: Dashboard server implementation pending (Backend Server story)");
 }
 
+// src/commands/scope-validator.ts
+function getFilePathFromInput(toolInput) {
+  try {
+    const data = JSON.parse(toolInput);
+    return data.file_path || data.path || null;
+  } catch {
+    return null;
+  }
+}
+function normalizePath(path) {
+  if (path.startsWith("./")) {
+    return path.slice(2);
+  }
+  return path;
+}
+function isArchiveAccess(path) {
+  return path.includes(".saga/archive");
+}
+function checkStoryAccess(path, allowedEpic, allowedStory) {
+  if (!path.includes(".saga/epics/")) {
+    return true;
+  }
+  const parts = path.split("/");
+  const epicsIdx = parts.indexOf("epics");
+  if (epicsIdx === -1) {
+    return true;
+  }
+  if (parts.length <= epicsIdx + 1) {
+    return true;
+  }
+  const pathEpic = parts[epicsIdx + 1];
+  if (parts.length > epicsIdx + 3 && parts[epicsIdx + 2] === "stories") {
+    const pathStory = parts[epicsIdx + 3];
+    return pathEpic === allowedEpic && pathStory === allowedStory;
+  } else {
+    return pathEpic === allowedEpic;
+  }
+}
+function printScopeViolation(filePath, epicSlug, storySlug, reason) {
+  console.error(`SCOPE VIOLATION: ${reason}
+
+Attempted path: ${filePath}
+
+Your scope is limited to:
+  Epic: ${epicSlug}
+  Story: ${storySlug}
+  Allowed: .saga/epics/${epicSlug}/stories/${storySlug}/
+
+To access other stories, start a new /implement session for that story.`);
+}
+async function scopeValidatorCommand() {
+  const epicSlug = process.env.SAGA_EPIC_SLUG || "";
+  const storySlug = process.env.SAGA_STORY_SLUG || "";
+  if (!epicSlug || !storySlug) {
+    console.error(
+      "ERROR: scope-validator requires SAGA_EPIC_SLUG and SAGA_STORY_SLUG environment variables"
+    );
+    process.exit(2);
+  }
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const toolInput = Buffer.concat(chunks).toString("utf-8");
+  const filePath = getFilePathFromInput(toolInput);
+  if (!filePath) {
+    process.exit(0);
+  }
+  const normPath = normalizePath(filePath);
+  if (isArchiveAccess(normPath)) {
+    printScopeViolation(
+      filePath,
+      epicSlug,
+      storySlug,
+      "Access to archive folder blocked\nReason: The archive folder contains completed stories and is read-only during execution."
+    );
+    process.exit(2);
+  }
+  if (!checkStoryAccess(normPath, epicSlug, storySlug)) {
+    printScopeViolation(
+      filePath,
+      epicSlug,
+      storySlug,
+      "Access to other story blocked\nReason: Workers can only access their assigned story's files."
+    );
+    process.exit(2);
+  }
+  process.exit(0);
+}
+
 // src/cli.ts
 var packageJsonPath = (0, import_node_path4.join)(__dirname, "..", "package.json");
 var packageJson = JSON.parse((0, import_node_fs4.readFileSync)(packageJsonPath, "utf-8"));
 var program2 = new Command();
-program2.name("saga").description("CLI for SAGA - Structured Autonomous Goal Achievement").version(packageJson.version);
+program2.name("saga").description("CLI for SAGA - Structured Autonomous Goal Achievement").version(packageJson.version).addHelpCommand("help [command]", "Display help for a command");
 program2.option("-p, --path <dir>", "Path to SAGA project directory (overrides auto-discovery)");
-program2.command("init").description("Initialize .saga/ directory structure").action(async () => {
+program2.command("init").description("Initialize .saga/ directory structure").option("--dry-run", "Show what would be created without making changes").action(async (options) => {
   const globalOpts = program2.opts();
-  await initCommand({ path: globalOpts.path });
+  await initCommand({ path: globalOpts.path, dryRun: options.dryRun });
 });
-program2.command("implement <story-slug>").description("Run story implementation").option("--max-cycles <n>", "Maximum number of implementation cycles", parseInt).option("--max-time <n>", "Maximum time in minutes", parseInt).option("--model <name>", "Model to use for implementation").action(async (storySlug, options) => {
+program2.command("implement <story-slug>").description("Run story implementation").option("--max-cycles <n>", "Maximum number of implementation cycles", parseInt).option("--max-time <n>", "Maximum time in minutes", parseInt).option("--model <name>", "Model to use for implementation").option("--dry-run", "Validate dependencies without running implementation").action(async (storySlug, options) => {
   const globalOpts = program2.opts();
   await implementCommand(storySlug, {
     path: globalOpts.path,
     maxCycles: options.maxCycles,
     maxTime: options.maxTime,
-    model: options.model
+    model: options.model,
+    dryRun: options.dryRun
   });
 });
 program2.command("dashboard").description("Start the dashboard server").option("--port <n>", "Port to run the server on (default: 3847)", parseInt).action(async (options) => {
@@ -3502,6 +3794,9 @@ program2.command("dashboard").description("Start the dashboard server").option("
     port: options.port
   });
 });
+program2.command("scope-validator").description("Validate file operations against story scope (internal)").action(async () => {
+  await scopeValidatorCommand();
+});
 program2.on("command:*", (operands) => {
   console.error(`error: unknown command '${operands[0]}'`);
   process.exit(1);

package/package.json

@@ -1,18 +1,12 @@
 {
   "name": "@saga-ai/cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "CLI for SAGA - Structured Autonomous Goal Achievement",
   "type": "module",
   "bin": {
     "saga": "./dist/cli.cjs"
   },
   "main": "./dist/cli.cjs",
-  "scripts": {
-    "build": "esbuild src/cli.ts --bundle --platform=node --outfile=dist/cli.cjs --format=cjs --banner:js='#!/usr/bin/env node'",
-    "dev": "npm run build && node dist/cli.js",
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
   "keywords": [
     "claude",
     "saga",
@@ -43,5 +37,12 @@
   "files": [
     "dist/",
     "README.md"
-  ]
-}
+  ],
+  "scripts": {
+    "build": "esbuild src/cli.ts --bundle --platform=node --outfile=dist/cli.cjs --format=cjs --banner:js='#!/usr/bin/env node'",
+    "dev": "npm run build && node dist/cli.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "publish:npm": "pnpm build && pnpm test && pnpm publish --access public"
+  }
+}