@gh-symphony/cli 0.0.7 → 0.0.9

package/README.md

@@ -25,6 +25,20 @@ Verify the installation:
 gh-symphony --version
 ```
 
+Enable shell completion:
+
+```bash
+gh-symphony completion bash >> ~/.bashrc
+gh-symphony completion zsh >> ~/.zshrc
+gh-symphony completion fish > ~/.config/fish/completions/gh-symphony.fish
+```
+
+If your `zsh` config does not already initialize completion, add this before the generated script line:
+
+```bash
+autoload -Uz compinit && compinit
+```
+
 ## 2. Set Repository
 
 Navigate to the repository you want to orchestrate, then run:
@@ -60,10 +74,9 @@ The interactive wizard will:
 
 1. Authenticate via `gh` CLI
 2. Let you select a **GitHub Project**
-3. Select repositories to orchestrate
-4. Optionally limit processing to issues assigned to the authenticated user
-5. Configure the workspace root directory
-6. Write project configuration to `~/.gh-symphony/`
+3. Optionally limit processing to issues assigned to the authenticated user
+4. Optionally customize advanced settings for repository filtering and workspace root directory
+5. Write project configuration to `~/.gh-symphony/`
 
 ### Project Management
 
@@ -126,6 +139,7 @@ Orchestration:
   run <issue>         Dispatch a single issue
   recover             Recover stalled runs
   logs                View orchestrator logs
+  completion <shell>  Print shell completion for bash/zsh/fish
 
 Project Management:
   project add          Add a new project (interactive wizard)

package/dist/commands/logs.js

@@ -2,7 +2,8 @@ import { readFile, readdir } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { createReadStream } from "node:fs";
 import { createInterface } from "node:readline";
-import { loadActiveProjectConfig, loadProjectConfig, orchestratorLogPath, } from "../config.js";
+import { orchestratorLogPath } from "../config.js";
+import { handleMissingManagedProjectConfig, resolveManagedProjectConfig, } from "../project-selection.js";
 function parseLogsArgs(args) {
     const parsed = { follow: false };
     for (let i = 0; i < args.length; i += 1) {
@@ -31,14 +32,6 @@ function parseLogsArgs(args) {
 }
 const handler = async (args, options) => {
     const parsed = parseLogsArgs(args);
-    const projectConfig = parsed.projectId
-        ? await loadProjectConfig(options.configDir, parsed.projectId)
-        : await loadActiveProjectConfig(options.configDir);
-    if (!projectConfig) {
-        process.stderr.write("No project configured. Run 'gh-symphony project add' first.\n");
-        process.exitCode = 1;
-        return;
-    }
     // If --run is specified, read that run's events
     if (parsed.run) {
         const eventsPath = join(resolve(options.configDir), "orchestrator", "runs", parsed.run, "events.ndjson");
@@ -47,6 +40,8 @@ const handler = async (args, options) => {
             const lines = content.trim().split("\n").filter(Boolean);
             for (const line of lines) {
                 const event = JSON.parse(line);
+                if (parsed.projectId && event.projectId !== parsed.projectId)
+                    continue;
                 if (parsed.level && event.level !== parsed.level)
                     continue;
                 if (parsed.issue && event.issueIdentifier !== parsed.issue)
@@ -62,6 +57,14 @@ const handler = async (args, options) => {
     }
     // Default: read orchestrator log or scan all events
     if (parsed.follow) {
+        const projectConfig = await resolveManagedProjectConfig({
+            configDir: options.configDir,
+            requestedProjectId: parsed.projectId,
+        });
+        if (!projectConfig) {
+            handleMissingManagedProjectConfig();
+            return;
+        }
         const logPath = orchestratorLogPath(options.configDir, projectConfig.projectId);
         try {
             const stream = createReadStream(logPath, { encoding: "utf8" });
@@ -103,6 +106,8 @@ const handler = async (args, options) => {
                 const lines = content.trim().split("\n").filter(Boolean);
                 for (const line of lines) {
                     const event = JSON.parse(line);
+                    if (parsed.projectId && event.projectId !== parsed.projectId)
+                        continue;
                     if (parsed.level && event.level !== parsed.level)
                         continue;
                     if (parsed.issue && event.issueIdentifier !== parsed.issue)

package/dist/commands/project.js

@@ -364,7 +364,7 @@ async function projectAddNonInteractive(flags, options) {
         return;
     }
     const projectId = generateProjectId(project.title, project.id);
-    const workspaceDir = flags.workspaceDir ?? `${options.configDir}/workspaces`;
+    const workspaceDir = flags.workspaceDir ?? join(options.configDir, "workspaces");
     await writeConfig(options.configDir, {
         projectId,
         project,
@@ -382,6 +382,7 @@ async function projectAddNonInteractive(flags, options) {
 }
 async function projectAddInteractive(options) {
     p.intro("gh-symphony - Project Setup");
+    const defaultWorkspaceDir = join(options.configDir, "workspaces");
     const existingConfig = await loadGlobalConfig(options.configDir);
     if (existingConfig) {
         const action = await abortIfCancelled(p.select({
@@ -451,7 +452,7 @@ async function projectAddInteractive(options) {
         return;
     }
     const selectedProjectId = await abortIfCancelled(p.select({
-        message: "Step 1/4 - Select a GitHub Project board:",
+        message: "Step 1/2 - Select a GitHub Project board:",
         options: projects.map((project) => ({
             value: project.id,
             label: `${project.owner.login}/${project.title}`,
@@ -477,32 +478,49 @@ async function projectAddInteractive(options) {
         process.exitCode = 1;
         return;
     }
-    const selectedRepos = await abortIfCancelled(p.multiselect({
-        message: "Step 2/4 - Select repositories to orchestrate:",
-        options: projectDetail.linkedRepositories.map((repo) => ({
-            value: repo,
-            label: `${repo.owner}/${repo.name}`,
-        })),
-        required: true,
-    }));
     const assignedOnly = await abortIfCancelled(p.confirm({
-        message: "Step 3/4 - Only process issues assigned to the authenticated GitHub user?",
+        message: "Step 2/2 - Only process issues assigned to the authenticated GitHub user?",
         initialValue: false,
     }));
-    const workspaceDir = await abortIfCancelled(p.text({
-        message: "Step 4/4 - Workspace root directory:",
-        placeholder: `${options.configDir}/workspaces`,
-        defaultValue: `${options.configDir}/workspaces`,
-        validate(value) {
-            return value.trim().length > 0
-                ? undefined
-                : "Workspace directory is required.";
-        },
+    const customizeAdvancedOptions = await abortIfCancelled(p.confirm({
+        message: "Customize advanced options? (default: No)",
+        initialValue: false,
     }));
+    let selectedRepos = projectDetail.linkedRepositories;
+    let workspaceDir = defaultWorkspaceDir;
+    if (customizeAdvancedOptions) {
+        const filterRepositories = await abortIfCancelled(p.confirm({
+            message: "Filter specific repositories? (default: No)",
+            initialValue: false,
+        }));
+        if (filterRepositories) {
+            selectedRepos = await abortIfCancelled(p.multiselect({
+                message: "Select repositories to orchestrate:",
+                options: projectDetail.linkedRepositories.map((repo) => ({
+                    value: repo,
+                    label: `${repo.owner}/${repo.name}`,
+                })),
+                required: true,
+            }));
+        }
+        workspaceDir = await abortIfCancelled(p.text({
+            message: "Workspace root directory:",
+            placeholder: defaultWorkspaceDir,
+            defaultValue: defaultWorkspaceDir,
+            validate(value) {
+                return value.trim().length > 0
+                    ? undefined
+                    : "Workspace directory is required.";
+            },
+        }));
+    }
+    const repoSummary = selectedRepos.length === projectDetail.linkedRepositories.length
+        ? `${selectedRepos.map((repo) => `${repo.owner}/${repo.name}`).join(", ")}  (all ${selectedRepos.length} linked)`
+        : `${selectedRepos.map((repo) => `${repo.owner}/${repo.name}`).join(", ")}  (${selectedRepos.length} of ${projectDetail.linkedRepositories.length} linked)`;
     p.note([
         `User:       ${login}`,
         `Project:    ${projectDetail.title}`,
-        `Repos:      ${selectedRepos.map((repo) => `${repo.owner}/${repo.name}`).join(", ")}`,
+        `Repos:      ${repoSummary}`,
         `Assigned:   ${assignedOnly ? `Only issues assigned to ${login}` : "All project issues"}`,
         `Workspace:  ${workspaceDir}`,
     ].join("\n"), "Configuration Summary");

package/dist/commands/recover.js

@@ -1,7 +1,8 @@
 import { readFile, readdir } from "node:fs/promises";
 import { join } from "node:path";
 import { runCli as orchestratorRunCli } from "@gh-symphony/orchestrator";
-import { resolveRuntimeRoot, resolveProjectConfig, syncProjectToRuntime, } from "../orchestrator-runtime.js";
+import { resolveRuntimeRoot, syncProjectToRuntime, } from "../orchestrator-runtime.js";
+import { handleMissingManagedProjectConfig, resolveManagedProjectConfig, } from "../project-selection.js";
 function parseRecoverArgs(args) {
     const parsed = { dryRun: false };
     for (let i = 0; i < args.length; i += 1) {
@@ -18,10 +19,12 @@ function parseRecoverArgs(args) {
 }
 const handler = async (args, options) => {
     const parsed = parseRecoverArgs(args);
-    const projectConfig = await resolveProjectConfig(options.configDir, parsed.projectId);
+    const projectConfig = await resolveManagedProjectConfig({
+        configDir: options.configDir,
+        requestedProjectId: parsed.projectId,
+    });
     if (!projectConfig) {
-        process.stderr.write("No project configured. Run 'gh-symphony project add' first.\n");
-        process.exitCode = 1;
+        handleMissingManagedProjectConfig();
         return;
     }
     const runtimeRoot = resolveRuntimeRoot(options.configDir);

package/dist/commands/run.js

@@ -1,5 +1,6 @@
 import { runCli as orchestratorRunCli } from "@gh-symphony/orchestrator";
-import { resolveRuntimeRoot, resolveProjectConfig, syncProjectToRuntime, } from "../orchestrator-runtime.js";
+import { resolveRuntimeRoot, syncProjectToRuntime, } from "../orchestrator-runtime.js";
+import { handleMissingManagedProjectConfig, resolveManagedProjectConfig, } from "../project-selection.js";
 function parseRunArgs(args) {
     const parsed = {
         watch: false,
@@ -27,10 +28,12 @@ const handler = async (args, options) => {
         process.exitCode = 2;
         return;
     }
-    const projectConfig = await resolveProjectConfig(options.configDir, parsed.projectId);
+    const projectConfig = await resolveManagedProjectConfig({
+        configDir: options.configDir,
+        requestedProjectId: parsed.projectId,
+    });
     if (!projectConfig) {
-        process.stderr.write("No project configured. Run 'gh-symphony project add' first.\n");
-        process.exitCode = 1;
+        handleMissingManagedProjectConfig();
         return;
     }
     const runtimeRoot = resolveRuntimeRoot(options.configDir);

package/dist/commands/start.js

@@ -2,10 +2,10 @@ import { writeFile, mkdir, readFile, rm } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { spawn } from "node:child_process";
 import { once } from "node:events";
-import { parseCliArgs } from "./parse-cli-args.js";
 import { daemonPidPath, orchestratorLogPath, orchestratorPortPath, } from "../config.js";
 import { OrchestratorService, createStore, startOrchestratorStatusServer, } from "@gh-symphony/orchestrator";
-import { resolveProjectConfig, resolveRuntimeRoot, syncProjectToRuntime, } from "../orchestrator-runtime.js";
+import { resolveRuntimeRoot, syncProjectToRuntime, } from "../orchestrator-runtime.js";
+import { handleMissingManagedProjectConfig, resolveManagedProjectConfig, } from "../project-selection.js";
 import { bold, dim, green, red, yellow, cyan, setNoColor } from "../ansi.js";
 import { getGhToken } from "../github/gh-auth.js";
 function timestamp() {
@@ -20,18 +20,31 @@ function logLine(icon, msg) {
 }
 // ── Arg parsing ───────────────────────────────────────────────────────────────
 function parseStartArgs(args) {
-    const parsed = parseCliArgs(args, {
-        daemon: { type: "boolean", short: "d" },
-        project: { type: "string" },
-        "project-id": { type: "string" },
-    });
-    if ("error" in parsed) {
-        return { daemon: false, error: parsed.error };
-    }
-    return {
-        daemon: Boolean(parsed.values.daemon),
-        projectId: (parsed.values["project-id"] ?? parsed.values.project),
+    const parsed = {
+        daemon: false,
     };
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--daemon" || arg === "-d") {
+            parsed.daemon = true;
+            continue;
+        }
+        if (arg === "--project" || arg === "--project-id") {
+            const value = args[i + 1];
+            if (!value || value.startsWith("-")) {
+                parsed.error = `Option '${arg}' argument missing`;
+                return parsed;
+            }
+            parsed.projectId = value;
+            i += 1;
+            continue;
+        }
+        if (arg?.startsWith("-")) {
+            parsed.error = `Unknown option '${arg}'`;
+            return parsed;
+        }
+    }
+    return parsed;
 }
 // ── Tick logging ──────────────────────────────────────────────────────────────
 function logTickResult(snapshot, prevSnapshot, isFirst) {
@@ -110,15 +123,12 @@ const handler = async (args, options) => {
         process.exitCode = 2;
         return;
     }
-    if (!parsed.projectId) {
-        process.stderr.write("Usage: gh-symphony start --project-id <project-id> [--daemon]\n");
-        process.exitCode = 2;
-        return;
-    }
-    const projectConfig = await resolveProjectConfig(options.configDir, parsed.projectId);
+    const projectConfig = await resolveManagedProjectConfig({
+        configDir: options.configDir,
+        requestedProjectId: parsed.projectId,
+    });
     if (!projectConfig) {
-        process.stderr.write("No project configured. Run 'gh-symphony project add' first.\n");
-        process.exitCode = 1;
+        handleMissingManagedProjectConfig();
         return;
     }
     const runtimeRoot = resolveRuntimeRoot(options.configDir);

package/dist/commands/status.js

@@ -1,12 +1,12 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { resolveRuntimeRoot, resolveProjectConfig, syncProjectToRuntime, } from "../orchestrator-runtime.js";
+import { resolveRuntimeRoot, syncProjectToRuntime, } from "../orchestrator-runtime.js";
+import { handleMissingManagedProjectConfig, resolveManagedProjectConfig, } from "../project-selection.js";
 import { bold, dim, green, red, yellow, cyan, stripAnsi } from "../ansi.js";
 import { clearScreen, showCursor, hideCursor } from "../ansi.js";
 import { renderDashboard } from "../dashboard/renderer.js";
 import { resolveProjectOrchestratorStatusBaseUrl } from "../orchestrator-status-endpoint.js";
 import { requestOrchestratorRefresh } from "./status-refresh.js";
-import { parseCliArgs } from "./parse-cli-args.js";
 const WATCH_REFRESH_TIMEOUT_MS = 1_500;
 function healthIcon(health) {
     switch (health) {
@@ -109,18 +109,31 @@ function renderLegacyStatus(snapshot, noColor) {
     return lines.join("\n");
 }
 function parseStatusArgs(args) {
-    const parsed = parseCliArgs(args, {
-        watch: { type: "boolean", short: "w" },
-        project: { type: "string" },
-        "project-id": { type: "string" },
-    });
-    if ("error" in parsed) {
-        return { watch: false, error: parsed.error };
-    }
-    return {
-        watch: Boolean(parsed.values.watch),
-        projectId: (parsed.values["project-id"] ?? parsed.values.project),
+    const parsed = {
+        watch: false,
     };
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--watch" || arg === "-w") {
+            parsed.watch = true;
+            continue;
+        }
+        if (arg === "--project" || arg === "--project-id") {
+            const value = args[i + 1];
+            if (!value || value.startsWith("-")) {
+                parsed.error = `Option '${arg}' argument missing`;
+                return parsed;
+            }
+            parsed.projectId = value;
+            i += 1;
+            continue;
+        }
+        if (arg?.startsWith("-")) {
+            parsed.error = `Unknown option '${arg}'`;
+            return parsed;
+        }
+    }
+    return parsed;
 }
 async function readStatusSnapshot(runtimeRoot, projectId) {
     try {
@@ -140,10 +153,12 @@ const handler = async (args, options) => {
         process.exitCode = 2;
         return;
     }
-    const projectConfig = await resolveProjectConfig(options.configDir, parsed.projectId);
+    const projectConfig = await resolveManagedProjectConfig({
+        configDir: options.configDir,
+        requestedProjectId: parsed.projectId,
+    });
     if (!projectConfig) {
-        process.stderr.write("No project configured. Run 'gh-symphony project add' first.\n");
-        process.exitCode = 1;
+        handleMissingManagedProjectConfig();
         return;
     }
     const runtimeRoot = resolveRuntimeRoot(options.configDir);

package/dist/commands/stop.js

@@ -1,19 +1,32 @@
 import { readFile, rm } from "node:fs/promises";
 import { daemonPidPath, orchestratorPortPath } from "../config.js";
-import { parseCliArgs } from "./parse-cli-args.js";
+import { handleMissingManagedProjectConfig, resolveManagedProjectConfig, } from "../project-selection.js";
 function parseStopArgs(args) {
-    const parsed = parseCliArgs(args, {
-        force: { type: "boolean" },
-        project: { type: "string" },
-        "project-id": { type: "string" },
-    });
-    if ("error" in parsed) {
-        return { force: false, error: parsed.error };
-    }
-    return {
-        force: Boolean(parsed.values.force),
-        projectId: (parsed.values["project-id"] ?? parsed.values.project),
+    const parsed = {
+        force: false,
     };
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--force") {
+            parsed.force = true;
+            continue;
+        }
+        if (arg === "--project" || arg === "--project-id") {
+            const value = args[i + 1];
+            if (!value || value.startsWith("-")) {
+                parsed.error = `Option '${arg}' argument missing`;
+                return parsed;
+            }
+            parsed.projectId = value;
+            i += 1;
+            continue;
+        }
+        if (arg?.startsWith("-")) {
+            parsed.error = `Unknown option '${arg}'`;
+            return parsed;
+        }
+    }
+    return parsed;
 }
 const handler = async (args, options) => {
     const parsed = parseStopArgs(args);
@@ -23,13 +36,16 @@ const handler = async (args, options) => {
         process.exitCode = 2;
         return;
     }
-    if (!parsed.projectId) {
-        process.stderr.write("Usage: gh-symphony stop --project-id <project-id> [--force]\n");
-        process.exitCode = 2;
+    const resolvedForce = parsed.force;
+    const projectConfig = await resolveManagedProjectConfig({
+        configDir: options.configDir,
+        requestedProjectId: parsed.projectId,
+    });
+    if (!projectConfig) {
+        handleMissingManagedProjectConfig();
         return;
     }
-    const resolvedForce = parsed.force;
-    const resolvedProjectId = parsed.projectId;
+    const resolvedProjectId = projectConfig.projectId;
     const pidPath = daemonPidPath(options.configDir, resolvedProjectId);
     const portPath = orchestratorPortPath(options.configDir, resolvedProjectId);
     let pidStr;

package/dist/completion.d.ts

@@ -0,0 +1 @@
+export declare function renderCompletionScript(shell: "bash" | "zsh" | "fish"): string;

package/dist/completion.js

@@ -0,0 +1,204 @@
+const TOP_LEVEL_COMMANDS = [
+    "init",
+    "start",
+    "stop",
+    "status",
+    "run",
+    "recover",
+    "logs",
+    "project",
+    "repo",
+    "config",
+    "completion",
+    "help",
+    "version",
+];
+const GLOBAL_OPTIONS = [
+    "--config",
+    "--config-dir",
+    "--verbose",
+    "-v",
+    "--json",
+    "--no-color",
+    "--help",
+    "-h",
+    "--version",
+    "-V",
+];
+const GLOBAL_OPTIONS_WITH_VALUES = ["--config", "--config-dir"];
+const COMMAND_OPTIONS = {
+    completion: ["bash", "zsh", "fish"],
+    start: ["--project-id", "--project", "--daemon", "-d", ...GLOBAL_OPTIONS],
+    stop: ["--project-id", "--project", "--force", ...GLOBAL_OPTIONS],
+    status: ["--project-id", "--project", "--watch", "-w", ...GLOBAL_OPTIONS],
+    run: ["--project-id", "--project", "--watch", "-w", ...GLOBAL_OPTIONS],
+    recover: ["--project-id", "--project", "--dry-run", ...GLOBAL_OPTIONS],
+    logs: [
+        "--project-id",
+        "--project",
+        "--follow",
+        "-f",
+        "--issue",
+        "--run",
+        "--level",
+        ...GLOBAL_OPTIONS,
+    ],
+    project: ["add", "list", "remove", "start", "stop", "switch", "status"],
+    "project:add": [
+        "--non-interactive",
+        "--project",
+        "--workspace-dir",
+        "--assigned-only",
+        ...GLOBAL_OPTIONS,
+    ],
+    "project:list": [...GLOBAL_OPTIONS],
+    "project:remove": [...GLOBAL_OPTIONS],
+    "project:start": [
+        "--project-id",
+        "--project",
+        "--daemon",
+        "-d",
+        ...GLOBAL_OPTIONS,
+    ],
+    "project:stop": ["--project-id", "--project", "--force", ...GLOBAL_OPTIONS],
+    "project:switch": [...GLOBAL_OPTIONS],
+    "project:status": [
+        "--project-id",
+        "--project",
+        "--watch",
+        "-w",
+        ...GLOBAL_OPTIONS,
+    ],
+    repo: ["list", "add", "remove"],
+    "repo:list": [...GLOBAL_OPTIONS],
+    "repo:add": [...GLOBAL_OPTIONS],
+    "repo:remove": [...GLOBAL_OPTIONS],
+    config: ["show", "set", "edit"],
+    "config:show": [...GLOBAL_OPTIONS],
+    "config:set": [...GLOBAL_OPTIONS],
+    "config:edit": [...GLOBAL_OPTIONS],
+};
+function quoteWords(values) {
+    return values.join(" ");
+}
+function renderBashCasePatterns() {
+    return Object.entries(COMMAND_OPTIONS)
+        .map(([key, values]) => {
+        const [command, subcommand] = key.split(":");
+        if (!subcommand) {
+            if (command === "completion") {
+                return `    completion)\n      COMPREPLY=( $(compgen -W "${quoteWords(values)}" -- "$cur") )\n      return\n      ;;`;
+            }
+            if (command === "project" ||
+                command === "repo" ||
+                command === "config") {
+                return `    ${command})\n      COMPREPLY=( $(compgen -W "${quoteWords(values)}" -- "$cur") )\n      return\n      ;;`;
+            }
+            return `    ${command})\n      COMPREPLY=( $(compgen -W "${quoteWords(values)}" -- "$cur") )\n      return\n      ;;`;
+        }
+        return `    ${command}:${subcommand})\n      COMPREPLY=( $(compgen -W "${quoteWords(values)}" -- "$cur") )\n      return\n      ;;`;
+    })
+        .join("\n");
+}
+function renderFishLines() {
+    const lines = GLOBAL_OPTIONS.map((option) => option.startsWith("--")
+        ? `complete -c gh-symphony -f -l ${option.slice(2)}`
+        : `complete -c gh-symphony -f -s ${option.slice(1)}`);
+    for (const command of TOP_LEVEL_COMMANDS) {
+        lines.push(`complete -c gh-symphony -f -n '__fish_use_subcommand' -a '${command}'`);
+    }
+    for (const subcommand of COMMAND_OPTIONS.project ?? []) {
+        lines.push(`complete -c gh-symphony -f -n '__fish_seen_subcommand_from project' -a '${subcommand}'`);
+    }
+    for (const subcommand of COMMAND_OPTIONS.repo ?? []) {
+        lines.push(`complete -c gh-symphony -f -n '__fish_seen_subcommand_from repo' -a '${subcommand}'`);
+    }
+    for (const subcommand of COMMAND_OPTIONS.config ?? []) {
+        lines.push(`complete -c gh-symphony -f -n '__fish_seen_subcommand_from config' -a '${subcommand}'`);
+    }
+    for (const shell of COMMAND_OPTIONS.completion ?? []) {
+        lines.push(`complete -c gh-symphony -f -n '__fish_seen_subcommand_from completion' -a '${shell}'`);
+    }
+    return lines.join("\n");
+}
+export function renderCompletionScript(shell) {
+    if (shell === "fish") {
+        return `${renderFishLines()}\n`;
+    }
+    const bashFunction = `# shellcheck shell=bash
+_gh_symphony_find_context() {
+  GH_SYMPHONY_COMMAND=""
+  GH_SYMPHONY_SUBCOMMAND=""
+
+  local idx=1
+  local token=""
+  local expects_value=0
+
+  while (( idx < COMP_CWORD )); do
+    token="\${COMP_WORDS[idx]}"
+
+    if (( expects_value )); then
+      expects_value=0
+      (( idx++ ))
+      continue
+    fi
+
+    case "\${token}" in
+      ${GLOBAL_OPTIONS_WITH_VALUES.map((option) => `${option}`).join("|")})
+        expects_value=1
+        ;;
+      ${GLOBAL_OPTIONS_WITH_VALUES.map((option) => `${option}=*`).join("|")})
+        ;;
+      ${GLOBAL_OPTIONS.filter((option) => !GLOBAL_OPTIONS_WITH_VALUES.includes(option)).join("|")})
+        ;;
+      -*)
+        ;;
+      *)
+        if [[ -z "\${GH_SYMPHONY_COMMAND}" ]]; then
+          GH_SYMPHONY_COMMAND="\${token}"
+        elif [[ -z "\${GH_SYMPHONY_SUBCOMMAND}" ]]; then
+          GH_SYMPHONY_SUBCOMMAND="\${token}"
+        fi
+        ;;
+    esac
+
+    (( idx++ ))
+  done
+}
+
+_gh_symphony_completion() {
+  local cur prev path
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev=""
+  if (( COMP_CWORD > 0 )); then
+    prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  fi
+
+  _gh_symphony_find_context
+  path="\${GH_SYMPHONY_COMMAND}"
+
+  if [[ -z "\${path}" ]]; then
+    COMPREPLY=( $(compgen -W "${quoteWords(TOP_LEVEL_COMMANDS)} ${quoteWords(GLOBAL_OPTIONS)}" -- "$cur") )
+    return
+  fi
+
+  if [[ "\${path}" == "project" || "\${path}" == "repo" || "\${path}" == "config" || "\${path}" == "completion" ]]; then
+    if [[ -n "\${GH_SYMPHONY_SUBCOMMAND}" ]]; then
+      path="\${path}:\${GH_SYMPHONY_SUBCOMMAND}"
+    fi
+  fi
+
+  case "\${path}" in
+${renderBashCasePatterns()}
+  esac
+}
+`;
+    if (shell === "zsh") {
+        return `autoload -Uz compinit && compinit
+autoload -U +X bashcompinit && bashcompinit
+${bashFunction}complete -F _gh_symphony_completion gh-symphony
+`;
+    }
+    return `${bashFunction}complete -F _gh_symphony_completion gh-symphony
+`;
+}

package/dist/index.d.ts

@@ -5,10 +5,5 @@ export type GlobalOptions = {
     json: boolean;
     noColor: boolean;
 };
-export declare function parseGlobalOptions(argv: string[]): {
-    options: GlobalOptions;
-    command: string;
-    args: string[];
-};
 export type CommandHandler = (args: string[], options: GlobalOptions) => Promise<void>;
 export declare function runCli(argv: string[]): Promise<void>;

package/dist/index.js

@@ -1,44 +1,9 @@
 #!/usr/bin/env node
 import { realpathSync } from "node:fs";
 import { pathToFileURL } from "node:url";
+import { Command, CommanderError, InvalidArgumentError, Option, } from "commander";
 import { resolveConfigDir } from "./config.js";
-export function parseGlobalOptions(argv) {
-    const globalFlags = {
-        configDir: resolveConfigDir(),
-        verbose: false,
-        json: false,
-        noColor: false,
-    };
-    const remaining = [];
-    let i = 0;
-    while (i < argv.length) {
-        const arg = argv[i];
-        if (arg === "--config" || arg === "--config-dir") {
-            globalFlags.configDir = resolveConfigDir(argv[i + 1]);
-            i += 2;
-            continue;
-        }
-        if (arg === "--verbose" || arg === "-v") {
-            globalFlags.verbose = true;
-            i += 1;
-            continue;
-        }
-        if (arg === "--json") {
-            globalFlags.json = true;
-            i += 1;
-            continue;
-        }
-        if (arg === "--no-color") {
-            globalFlags.noColor = true;
-            i += 1;
-            continue;
-        }
-        remaining.push(arg);
-        i += 1;
-    }
-    const [command = "help", ...args] = remaining;
-    return { options: globalFlags, command, args };
-}
+import { renderCompletionScript } from "./completion.js";
 const COMMANDS = {
     init: () => import("./commands/init.js"),
     start: () => import("./commands/start.js"),
@@ -50,32 +15,355 @@ const COMMANDS = {
     project: () => import("./commands/project.js"),
     repo: () => import("./commands/repo.js"),
     config: () => import("./commands/config-cmd.js"),
-    help: () => import("./commands/help.js"),
     version: () => import("./commands/version.js"),
 };
-export async function runCli(argv) {
-    const { options, command, args } = parseGlobalOptions(argv);
+function addGlobalOptions(command) {
+    return command
+        .option("--config <dir>", "Config directory")
+        .addOption(new Option("--config-dir <dir>").hideHelp())
+        .option("-v, --verbose", "Enable verbose output")
+        .option("--json", "Output in JSON format")
+        .option("--no-color", "Disable color output");
+}
+function resolveGlobalOptions(values) {
+    const configInput = typeof values.config === "string"
+        ? values.config
+        : typeof values.configDir === "string"
+            ? values.configDir
+            : undefined;
+    const options = {
+        configDir: resolveConfigDir(configInput),
+        verbose: Boolean(values.verbose),
+        json: Boolean(values.json),
+        noColor: Boolean(values.noColor),
+    };
     if (options.noColor) {
         process.env.NO_COLOR = "1";
     }
-    if (command === "--help" || command === "-h") {
-        const helpModule = await COMMANDS.help();
-        await helpModule.default(args, options);
+    return options;
+}
+function resolveProjectId(values) {
+    return values.projectId ?? values.project;
+}
+function pushOption(args, flag, value) {
+    if (typeof value === "string" && value.length > 0) {
+        args.push(flag, value);
         return;
     }
-    if (command === "--version" || command === "-V") {
+    if (value === true) {
+        args.push(flag);
+    }
+}
+async function invokeHandler(key, args, values) {
+    const module = await COMMANDS[key]();
+    await module.default(args, resolveGlobalOptions(values));
+}
+function shellArgument(value) {
+    if (value === "bash" || value === "zsh" || value === "fish") {
+        return value;
+    }
+    throw new InvalidArgumentError("Shell must be one of: bash, zsh, fish");
+}
+function hasVersionFlag(argv) {
+    return argv.some((arg) => arg === "--version" || arg === "-V");
+}
+function resolveVersionOptions(argv) {
+    const options = {
+        configDir: resolveConfigDir(),
+        verbose: argv.some((arg) => arg === "--verbose" || arg === "-v"),
+        json: argv.includes("--json"),
+        noColor: argv.includes("--no-color"),
+    };
+    if (options.noColor) {
+        process.env.NO_COLOR = "1";
+    }
+    return options;
+}
+function createProgram() {
+    let actionInvoked = false;
+    const markInvoked = () => {
+        actionInvoked = true;
+    };
+    const program = addGlobalOptions(new Command()
+        .name("gh-symphony")
+        .description("AI Coding Agent Orchestrator")
+        .exitOverride()
+        .helpOption("-h, --help", "Show help")
+        .addHelpCommand("help [command]", "Show help for command")
+        .showHelpAfterError("(run with --help for usage)")
+        .option("-V, --version", "Show version"));
+    addGlobalOptions(program
+        .command("init")
+        .description("Interactive project setup wizard")
+        .allowExcessArguments(false)).action(async function () {
+        markInvoked();
+        await invokeHandler("init", [], this.optsWithGlobals());
+    });
+    addGlobalOptions(program
+        .command("start")
+        .description("Start the orchestrator")
+        .option("-d, --daemon", "Start in daemon mode")
+        .option("--project-id <projectId>", "Project identifier")
+        .addOption(new Option("--project <projectId>").hideHelp())
+        .allowExcessArguments(false)).action(async function () {
+        markInvoked();
+        const values = this.optsWithGlobals();
+        const args = [];
+        pushOption(args, "--project-id", resolveProjectId(values));
+        pushOption(args, "--daemon", values.daemon);
+        await invokeHandler("start", args, values);
+    });
+    addGlobalOptions(program
+        .command("stop")
+        .description("Stop the background orchestrator")
+        .option("--force", "Force stop with SIGKILL")
+        .option("--project-id <projectId>", "Project identifier")
+        .addOption(new Option("--project <projectId>").hideHelp())
+        .allowExcessArguments(false)).action(async function () {
+        markInvoked();
+        const values = this.optsWithGlobals();
+        const args = [];
+        pushOption(args, "--project-id", resolveProjectId(values));
+        pushOption(args, "--force", values.force);
+        await invokeHandler("stop", args, values);
+    });
+    addGlobalOptions(program
+        .command("status")
+        .description("Show orchestrator status")
+        .option("-w, --watch", "Watch status continuously")
+        .option("--project-id <projectId>", "Project identifier")
+        .addOption(new Option("--project <projectId>").hideHelp())
+        .allowExcessArguments(false)).action(async function () {
+        markInvoked();
+        const values = this.optsWithGlobals();
+        const args = [];
+        pushOption(args, "--project-id", resolveProjectId(values));
+        pushOption(args, "--watch", values.watch);
+        await invokeHandler("status", args, values);
+    });
+    addGlobalOptions(program
+        .command("run")
+        .description("Dispatch a single issue")
+        .argument("<issue>", "Issue identifier")
+        .option("-w, --watch", "Watch status after dispatch")
+        .option("--project-id <projectId>", "Project identifier")
+        .addOption(new Option("--project <projectId>").hideHelp())
+        .allowExcessArguments(false)).action(async function (issue) {
+        markInvoked();
+        const values = this.optsWithGlobals();
+        const args = [issue];
+        pushOption(args, "--project-id", resolveProjectId(values));
+        pushOption(args, "--watch", values.watch);
+        await invokeHandler("run", args, values);
+    });
+    addGlobalOptions(program
+        .command("recover")
+        .description("Recover stalled runs")
+        .option("--dry-run", "Show recoverable runs without recovering")
+        .option("--project-id <projectId>", "Project identifier")
+        .addOption(new Option("--project <projectId>").hideHelp())
+        .allowExcessArguments(false)).action(async function () {
+        markInvoked();
+        const values = this.optsWithGlobals();
+        const args = [];
+        pushOption(args, "--project-id", resolveProjectId(values));
+        pushOption(args, "--dry-run", values.dryRun);
+        await invokeHandler("recover", args, values);
+    });
+    addGlobalOptions(program
+        .command("logs")
+        .description("View orchestrator logs")
+        .option("-f, --follow", "Follow new log lines")
+        .option("--issue <issue>", "Filter by issue identifier")
+        .option("--run <runId>", "Read events for a specific run")
+        .option("--level <level>", "Filter by log level")
+        .option("--project-id <projectId>", "Project identifier")
+        .addOption(new Option("--project <projectId>").hideHelp())
+        .allowExcessArguments(false)).action(async function () {
+        markInvoked();
+        const values = this.optsWithGlobals();
+        const args = [];
+        pushOption(args, "--project-id", resolveProjectId(values));
+        pushOption(args, "--follow", values.follow);
+        pushOption(args, "--issue", values.issue);
+        pushOption(args, "--run", values.run);
+        pushOption(args, "--level", values.level);
+        await invokeHandler("logs", args, values);
+    });
+    const project = addGlobalOptions(program.command("project").description("Manage configured projects"));
+    project.action(async function () {
+        markInvoked();
+        await invokeHandler("project", [], this.optsWithGlobals());
+    });
+    addGlobalOptions(project
+        .command("add")
+        .description("Add a new project")
+        .option("--non-interactive", "Run without prompts")
+        .option("--project <id>", "GitHub Project ID")
+        .option("--workspace-dir <path>", "Workspace directory")
+        .option("--assigned-only", "Limit processing to assigned issues")
+        .allowExcessArguments(false)).action(async function () {
+        markInvoked();
+        const values = this.optsWithGlobals();
+        const args = [];
+        pushOption(args, "--non-interactive", values.nonInteractive);
+        pushOption(args, "--project", values.project);
+        pushOption(args, "--workspace-dir", values.workspaceDir);
+        pushOption(args, "--assigned-only", values.assignedOnly);
+        await invokeHandler("project", ["add", ...args], values);
+    });
+    addGlobalOptions(project.command("list").description("List configured projects")).action(async function () {
+        markInvoked();
+        const values = this.optsWithGlobals();
+        await invokeHandler("project", ["list"], values);
+    });
+    addGlobalOptions(project
+        .command("remove")
+        .description("Remove a project")
+        .argument("<projectId>", "Project identifier")
+        .allowExcessArguments(false)).action(async function (projectId) {
+        markInvoked();
+        await invokeHandler("project", ["remove", projectId], this.optsWithGlobals());
+    });
+    addGlobalOptions(project
+        .command("start")
+        .description("Start a specific project")
+        .option("-d, --daemon", "Start in daemon mode")
+        .option("--project-id <projectId>", "Project identifier")
+        .addOption(new Option("--project <projectId>").hideHelp())
+        .allowExcessArguments(false)).action(async function () {
+        markInvoked();
+        const values = this.optsWithGlobals();
+        const args = ["start"];
+        pushOption(args, "--project-id", resolveProjectId(values));
+        pushOption(args, "--daemon", values.daemon);
+        await invokeHandler("project", args, values);
+    });
+    addGlobalOptions(project
+        .command("stop")
+        .description("Stop a specific project")
+        .option("--force", "Force stop with SIGKILL")
+        .option("--project-id <projectId>", "Project identifier")
+        .addOption(new Option("--project <projectId>").hideHelp())
+        .allowExcessArguments(false)).action(async function () {
+        markInvoked();
+        const values = this.optsWithGlobals();
+        const args = ["stop"];
+        pushOption(args, "--project-id", resolveProjectId(values));
+        pushOption(args, "--force", values.force);
+        await invokeHandler("project", args, values);
+    });
+    addGlobalOptions(project.command("switch").description("Switch the active project")).action(async function () {
+        markInvoked();
+        await invokeHandler("project", ["switch"], this.optsWithGlobals());
+    });
+    addGlobalOptions(project
+        .command("status")
+        .description("Show status for a specific project")
+        .option("-w, --watch", "Watch status continuously")
+        .option("--project-id <projectId>", "Project identifier")
+        .addOption(new Option("--project <projectId>").hideHelp())
+        .allowExcessArguments(false)).action(async function () {
+        markInvoked();
+        const values = this.optsWithGlobals();
+        const args = ["status"];
+        pushOption(args, "--project-id", resolveProjectId(values));
+        pushOption(args, "--watch", values.watch);
+        await invokeHandler("project", args, values);
+    });
+    const repo = addGlobalOptions(program
+        .command("repo")
+        .description("Manage repositories in the active project"));
+    repo.action(async function () {
+        markInvoked();
+        await invokeHandler("repo", [], this.optsWithGlobals());
+    });
+    addGlobalOptions(repo.command("list").description("List repositories")).action(async function () {
+        markInvoked();
+        await invokeHandler("repo", ["list"], this.optsWithGlobals());
+    });
+    addGlobalOptions(repo
+        .command("add")
+        .description("Add a repository")
+        .argument("<owner/name>", "Repository spec")
+        .allowExcessArguments(false)).action(async function (repoSpec) {
+        markInvoked();
+        await invokeHandler("repo", ["add", repoSpec], this.optsWithGlobals());
+    });
+    addGlobalOptions(repo
+        .command("remove")
+        .description("Remove a repository")
+        .argument("<owner/name>", "Repository spec")
+        .allowExcessArguments(false)).action(async function (repoSpec) {
+        markInvoked();
+        await invokeHandler("repo", ["remove", repoSpec], this.optsWithGlobals());
+    });
+    const config = addGlobalOptions(program.command("config").description("Manage CLI configuration"));
+    config.action(async function () {
+        markInvoked();
+        await invokeHandler("config", [], this.optsWithGlobals());
+    });
+    addGlobalOptions(config.command("show").description("Show configuration")).action(async function () {
+        markInvoked();
+        await invokeHandler("config", ["show"], this.optsWithGlobals());
+    });
+    addGlobalOptions(config
+        .command("set")
+        .description("Set a configuration value")
+        .argument("<key>", "Configuration key")
+        .argument("<value>", "Configuration value")
+        .allowExcessArguments(false)).action(async function (key, value) {
+        markInvoked();
+        await invokeHandler("config", ["set", key, value], this.optsWithGlobals());
+    });
+    addGlobalOptions(config.command("edit").description("Open config in $EDITOR")).action(async function () {
+        markInvoked();
+        await invokeHandler("config", ["edit"], this.optsWithGlobals());
+    });
+    addGlobalOptions(program
+        .command("completion")
+        .description("Print shell completion script")
+        .argument("<shell>", "Shell name", shellArgument)
+        .allowExcessArguments(false)).action(async function (shell) {
+        markInvoked();
+        process.stdout.write(renderCompletionScript(shell));
+    });
+    program
+        .command("version")
+        .description("Show version")
+        .allowExcessArguments(false)
+        .action(async function () {
+        markInvoked();
+        await invokeHandler("version", [], this.optsWithGlobals());
+    });
+    return { program, wasInvoked: () => actionInvoked };
+}
+export async function runCli(argv) {
+    const { program, wasInvoked } = createProgram();
+    if (hasVersionFlag(argv)) {
         const versionModule = await COMMANDS.version();
-        await versionModule.default(args, options);
+        await versionModule.default([], resolveVersionOptions(argv));
         return;
     }
-    const loader = COMMANDS[command];
-    if (!loader) {
-        process.stderr.write(`Unknown command: ${command}\nRun 'gh-symphony help' for usage.\n`);
-        process.exitCode = 2;
-        return;
+    try {
+        await program.parseAsync(["node", "gh-symphony", ...argv], {
+            from: "node",
+        });
+        if (!wasInvoked()) {
+            program.outputHelp();
+        }
+    }
+    catch (error) {
+        if (error instanceof CommanderError &&
+            error.code === "commander.helpDisplayed") {
+            return;
+        }
+        if (error instanceof CommanderError) {
+            process.exitCode = error.exitCode;
+            return;
+        }
+        throw error;
     }
-    const module = await loader();
-    await module.default(args, options);
 }
 async function main() {
     await runCli(process.argv.slice(2));

package/dist/project-selection.d.ts

@@ -0,0 +1,8 @@
+import { type CliProjectConfig } from "./config.js";
+type ResolveProjectSelectionInput = {
+    configDir: string;
+    requestedProjectId?: string;
+};
+export declare function resolveManagedProjectConfig(input: ResolveProjectSelectionInput): Promise<CliProjectConfig | null>;
+export declare function handleMissingManagedProjectConfig(): void;
+export {};

package/dist/project-selection.js

@@ -0,0 +1,56 @@
+import * as p from "@clack/prompts";
+import { loadGlobalConfig, loadProjectConfig, } from "./config.js";
+function isInteractiveTerminal() {
+    return process.stdin.isTTY === true && process.stdout.isTTY === true;
+}
+function explicitProjectRequiredMessage() {
+    return "Multiple projects are configured. Re-run with --project-id in non-interactive environments.\n";
+}
+export async function resolveManagedProjectConfig(input) {
+    if (input.requestedProjectId) {
+        return loadProjectConfig(input.configDir, input.requestedProjectId);
+    }
+    const global = await loadGlobalConfig(input.configDir);
+    const projectIds = global?.projects ?? [];
+    if (projectIds.length === 0) {
+        return null;
+    }
+    if (projectIds.length === 1) {
+        return loadProjectConfig(input.configDir, projectIds[0]);
+    }
+    if (!isInteractiveTerminal()) {
+        process.stderr.write(explicitProjectRequiredMessage());
+        process.exitCode = 1;
+        return null;
+    }
+    const projects = await Promise.all(projectIds.map(async (projectId) => ({
+        projectId,
+        config: await loadProjectConfig(input.configDir, projectId),
+    })));
+    const selected = await p.select({
+        message: "Select a project:",
+        options: projects.map(({ projectId, config }) => ({
+            value: projectId,
+            label: config?.displayName ?? config?.slug ?? projectId,
+            hint: projectId === global?.activeProject
+                ? "current"
+                : config && config.displayName && config.displayName !== projectId
+                    ? projectId
+                    : undefined,
+        })),
+        maxItems: 10,
+    });
+    if (p.isCancel(selected)) {
+        p.cancel("Cancelled.");
+        process.exitCode = 130;
+        return null;
+    }
+    return loadProjectConfig(input.configDir, selected);
+}
+export function handleMissingManagedProjectConfig() {
+    if (process.exitCode) {
+        return;
+    }
+    process.stderr.write("No project configured. Run 'gh-symphony project add' first.\n");
+    process.exitCode = 1;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gh-symphony/cli",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "license": "MIT",
   "author": "hojinzs",
   "description": "Interactive CLI for GitHub Symphony orchestration",
@@ -36,10 +36,11 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.9.1",
-    "@gh-symphony/orchestrator": "0.0.7",
-    "@gh-symphony/core": "0.0.7",
-    "@gh-symphony/tracker-github": "0.0.7",
-    "@gh-symphony/worker": "0.0.7"
+    "commander": "^14.0.1",
+    "@gh-symphony/core": "0.0.9",
+    "@gh-symphony/worker": "0.0.9",
+    "@gh-symphony/tracker-github": "0.0.9",
+    "@gh-symphony/orchestrator": "0.0.9"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",