feat: added flags --dry-run --yes and --help (same with no-args) + update catalog on git key

Author: ekaone

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekaone/json-cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "AI-powered CLI task runner with JSON command plans",
   "keywords": ["ai", "agent", "cli", "task-runner", "llm"],
   "author": {

src/catalog.ts

@@ -4,11 +4,24 @@ import { z } from "zod";
 // Allowed commands per type — the whitelist that prevents hallucination
 // ---------------------------------------------------------------------------
 export const CATALOG = {
-  npm:   ["install", "run", "build", "test", "publish", "ci"],
-  pnpm:  ["install", "run", "build", "test", "publish", "add", "remove"],
-  yarn:  ["install", "run", "build", "test", "publish", "add", "remove"],
-  bun:   ["install", "run", "build", "test", "publish", "add", "remove"],
-  git:   ["init", "add", "commit", "push", "pull", "clone", "status", "log"],
+  npm: ["install", "run", "build", "test", "publish", "ci"],
+  pnpm: ["install", "run", "build", "test", "publish", "add", "remove"],
+  yarn: ["install", "run", "build", "test", "publish", "add", "remove"],
+  bun: ["install", "run", "build", "test", "publish", "add", "remove"],
+  git: [
+    "init",
+    "add",
+    "commit",
+    "push",
+    "pull",
+    "clone",
+    "status",
+    "log",
+    "branch",
+    "checkout",
+    "merge",
+    "stash",
+  ],
   shell: ["any"], // escape hatch — always requires extra confirmation
 } as const;
 
@@ -18,16 +31,16 @@ export type CommandType = keyof typeof CATALOG;
 // Zod schemas — Layer 2 defense against hallucinated output
 // ---------------------------------------------------------------------------
 export const StepSchema = z.object({
-  id:          z.number(),
-  type:        z.enum(["npm", "pnpm", "yarn", "bun", "git", "shell"]),
-  command:     z.string(),
-  args:        z.array(z.string()).default([]),
+  id: z.number(),
+  type: z.enum(["npm", "pnpm", "yarn", "bun", "git", "shell"]),
+  command: z.string(),
+  args: z.array(z.string()).default([]),
   description: z.string(),
-  cwd:         z.string().optional(), // optional working directory override
+  cwd: z.string().optional(), // optional working directory override
 });
 
 export const PlanSchema = z.object({
-  goal:  z.string(),
+  goal: z.string(),
   steps: z.array(StepSchema).min(1).max(10),
 });
 
@@ -60,7 +73,10 @@ export function validateStep(step: Step): { valid: boolean; reason?: string } {
 // ---------------------------------------------------------------------------
 export function buildCatalogPrompt(): string {
   const lines = Object.entries(CATALOG).map(([type, commands]) => {
-    const list = commands[0] === "any" ? "any shell command (use sparingly)" : commands.join(", ");
+    const list =
+      commands[0] === "any"
+        ? "any shell command (use sparingly)"
+        : commands.join(", ");
     return `  - ${type}: [${list}]`;
   });
 

src/cli.ts

@@ -4,16 +4,57 @@ import { generatePlan } from "./planner.js";
 import { runPlan } from "./runner.js";
 import type { Step } from "./catalog.js";
 
+// ---------------------------------------------------------------------------
+// Help
+// ---------------------------------------------------------------------------
+function showHelp(): void {
+  p.intro("json-cli — AI-powered CLI task runner");
+  p.log.message(`Usage\n  json-cli "<your goal>" [options]\n`);
+  p.log.message(
+    `Options
+  --provider <name>   AI provider: claude | openai | ollama  (default: claude)
+  --yes               Skip confirmation prompt
+  --dry-run           Show plan without executing
+  --help              Show this help message`,
+  );
+  p.log.message(
+    `Examples
+  json-cli "please run tests"
+  json-cli "run tests and build"
+  json-cli "run tests and build" --yes
+  json-cli "git add, commit with message 'fix: bug', push"
+  json-cli "clone https://github.com/user/repo, install deps, run dev"
+  json-cli "run tests and publish" --provider openai
+  json-cli "run tests" --dry-run`,
+  );
+  p.outro("Docs: https://github.com/ekaone/json-cli");
+}
+
 // ---------------------------------------------------------------------------
 // Parse CLI args
-// e.g. json-cli "run tests" --provider claude
+// e.g. json-cli "run tests" --provider claude --yes --dry-run
 // ---------------------------------------------------------------------------
-function parseArgs(): { prompt: string; provider: ProviderName } {
+function parseArgs(): {
+  prompt: string;
+  provider: ProviderName;
+  yes: boolean;
+  dryRun: boolean;
+} {
   const args = process.argv.slice(2);
+
+  // show help if no args or --help flag
+  if (args.length === 0 || args.includes("--help")) {
+    showHelp();
+    process.exit(0);
+  }
+
   const providerFlag = args.indexOf("--provider");
   const provider: ProviderName =
     providerFlag !== -1 ? (args[providerFlag + 1] as ProviderName) : "claude";
 
+  const yes = args.includes("--yes");
+  const dryRun = args.includes("--dry-run");
+
   const prompt = args
     .filter(
       (a, i) =>
@@ -22,13 +63,11 @@ function parseArgs(): { prompt: string; provider: ProviderName } {
     .join(" ");
 
   if (!prompt) {
-    console.error(
-      'Usage: json-cli "<your goal>" [--provider claude|openai|ollama]',
-    );
-    process.exit(1);
+    showHelp();
+    process.exit(0);
   }
 
-  return { prompt, provider };
+  return { prompt, provider, yes, dryRun };
 }
 
 // ---------------------------------------------------------------------------
@@ -46,9 +85,11 @@ function formatStep(step: Step): string {
 // Main
 // ---------------------------------------------------------------------------
 async function main() {
-  const { prompt, provider: providerName } = parseArgs();
+  const { prompt, provider: providerName, yes, dryRun } = parseArgs();
 
-  p.intro(`json-cli — powered by ${providerName}`);
+  p.intro(
+    `json-cli — powered by ${providerName}${dryRun ? "  (dry run)" : ""}`,
+  );
 
   // Step 1: Generate plan
   const spinner = p.spinner();
@@ -82,27 +123,37 @@ async function main() {
     );
   }
 
-  // Step 4: Confirm
-  const confirmed = await p.confirm({ message: "Proceed?" });
-  if (p.isCancel(confirmed) || !confirmed) {
-    p.cancel("Aborted.");
-    process.exit(0);
+  // Step 4: Dry run — show plan and exit
+  if (dryRun) {
+    p.outro("Dry run complete — no commands were executed.");
+    setTimeout(() => process.exit(0), 50);
   }
 
-  // Step 5: Execute
+  // Step 5: Confirm — skip if --yes
+  if (!yes) {
+    const confirmed = await p.confirm({ message: "Proceed?" });
+    if (p.isCancel(confirmed) || !confirmed) {
+      p.cancel("Aborted.");
+      setTimeout(() => process.exit(0), 50);
+    }
+  } else {
+    p.log.info("Skipping confirmation (--yes)");
+  }
+
+  // Step 6: Execute
   console.log("");
   const result = await runPlan(plan, (step, i, total) => {
     p.log.step(`Step ${i + 1}/${total}: ${formatStep(step)}`);
   });
 
-  // Step 6: Result
+  // Step 7: Result
   if (result.success) {
     p.outro("✅ All steps completed successfully.");
   } else {
     p.log.error(
       `❌ Failed at step ${result.failedStep?.id}: ${result.failedStep?.description}\n${result.error ?? ""}`,
     );
-    process.exit(1);
+    setTimeout(() => process.exit(1), 50);
   }
 }
 

src/runner.ts

@@ -17,19 +17,29 @@ function resolveCommand(step: Step): { bin: string; args: string[] } {
 // ---------------------------------------------------------------------------
 // Run a single step, streaming stdout/stderr live
 // ---------------------------------------------------------------------------
-export async function runStep(step: Step): Promise<{ success: boolean; error?: string }> {
+export async function runStep(
+  step: Step,
+): Promise<{ success: boolean; error?: string }> {
   const { bin, args } = resolveCommand(step);
 
   try {
     await execa(bin, args, {
-      cwd:    step.cwd ?? process.cwd(),
+      cwd: step.cwd ?? process.cwd(),
       stdout: "inherit", // stream directly to terminal
       stderr: "inherit",
     });
     return { success: true };
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return { success: false, error: message };
+  } catch (err: any) {
+    const parts = [
+      `Command: ${bin} ${args.join(" ")}`,
+      err?.exitCode ? `Exit code: ${err.exitCode}` : null,
+      err?.stderr ? `Reason: ${err.stderr.trim()}` : null,
+      !err?.stderr ? (err?.message ?? String(err)) : null,
+    ]
+      .filter(Boolean)
+      .join("\n   ");
+
+    return { success: false, error: parts };
   }
 }
 
@@ -38,7 +48,7 @@ export async function runStep(step: Step): Promise<{ success: boolean; error?: s
 // ---------------------------------------------------------------------------
 export async function runPlan(
   plan: Plan,
-  onStep: (step: Step, index: number, total: number) => void
+  onStep: (step: Step, index: number, total: number) => void,
 ): Promise<{ success: boolean; failedStep?: Step; error?: string }> {
   const total = plan.steps.length;