@gh-symphony/cli 0.0.21 → 0.0.22

package/README.md

@@ -181,6 +181,7 @@ gh-symphony doctor                   # Validate local prerequisites, auth, confi
 gh-symphony doctor --fix             # Apply safe fixes and guide/launch follow-up recovery commands
 gh-symphony project list             # List all configured projects
 gh-symphony project remove <id>      # Remove a project
+gh-symphony project explain owner/repo#123  # Explain why one issue is not dispatching
 gh-symphony repo add owner/name      # Validate and save a repo target manually
 gh-symphony repo sync                # Add newly linked repositories from the GitHub Project
 gh-symphony repo sync --dry-run      # Preview linked repository drift
@@ -201,6 +202,41 @@ removed, unchanged, and final repository sets.
 
 For empty projects, use `gh-symphony repo add owner/name` after setup to seed the local repository list without re-running the whole wizard.
 
+### Why Is My Issue Not Running?
+
+Use `gh-symphony project explain <owner/repo#number>` before digging through
+logs manually:
+
+```bash
+gh-symphony project explain owner/repo#123
+gh-symphony project explain owner/repo#123 --json
+gh-symphony project explain owner/repo#123 --workflow ./WORKFLOW.md
+```
+
+The command checks project repository linkage, GitHub Project item presence,
+`WORKFLOW.md` active / wait / terminal state mapping, blocker state, existing
+run / retry / convergence ownership, and project or per-state concurrency
+limits.
+
+If the project has no previous local run snapshot and the repository path is
+not stored in the managed project config, pass `--workflow` so the command
+does not guess from the current shell directory.
+
+```text
+Issue dispatch explanation: owner/repo#123
+Not dispatchable: Issue has 1 unresolved blocker.
+
+Checks:
+  ✓ Repository owner/repo is linked to the active managed project.
+  ✓ Issue is present in the bound GitHub Project item set.
+  ✓ Project state "Todo" maps to an active state in WORKFLOW.md.
+  ✗ Issue has 1 unresolved blocker.
+    Hint: Move blocker issues to a terminal state or update the blocker relationship in GitHub.
+```
+
+The remediation hints point to existing commands such as `workflow preview`,
+`doctor`, `project status`, and `logs --issue`.
+
 ## 4. Run the Orchestrator
 
 ### Foreground

package/dist/{chunk-SXGT7LOF.js → chunk-2TSM3INR.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   DEFAULT_WORKFLOW_LIFECYCLE
-} from "./chunk-QEONJ5DZ.js";
+} from "./chunk-EEQQWTXS.js";
 
 // ../tracker-github/src/adapter.ts
 import { createHash } from "crypto";
@@ -951,6 +951,19 @@ var githubProjectTrackerAdapter = {
     };
   }
 };
+async function findGithubProjectIssue(project, identifier, dependencies = {}) {
+  const parsed = parseIssueIdentifier(identifier);
+  if (!parsed) {
+    return null;
+  }
+  const trackerConfig = resolveGitHubTrackerConfig(project, dependencies);
+  return fetchGithubProjectIssueByRepositoryAndNumber(
+    trackerConfig,
+    { owner: parsed.owner, name: parsed.name },
+    parsed.number,
+    dependencies.fetchImpl
+  );
+}
 async function listProjectIssues(project, dependencies = {}) {
   const trackerConfig = resolveGitHubTrackerConfig(project, dependencies);
   const loadProjectIssues = () => fetchGithubProjectIssues(trackerConfig, dependencies.fetchImpl);
@@ -1053,8 +1066,20 @@ function parseIssueNumber(identifier) {
   const match = identifier.match(/#(\d+)$/);
   return match ? Number.parseInt(match[1] ?? "0", 10) : 0;
 }
+function parseIssueIdentifier(identifier) {
+  const match = identifier.match(/^([^/\s#]+)\/([^/\s#]+)#(\d+)$/);
+  if (!match) {
+    return null;
+  }
+  return {
+    owner: match[1],
+    name: match[2],
+    number: Number.parseInt(match[3], 10)
+  };
+}
 
 export {
   fetchGithubProjectIssueByRepositoryAndNumber,
+  findGithubProjectIssue,
   resolveTrackerAdapter
 };

package/dist/{chunk-A67CMOYE.js → chunk-2UW7NQLX.js}

@@ -8,7 +8,7 @@ import {
   resolveGitHubGraphQLToken,
   shouldReuseAgentCredentialCache,
   writeAgentCredentialCache
-} from "./chunk-QEONJ5DZ.js";
+} from "./chunk-EEQQWTXS.js";
 
 // ../runtime-codex/src/runtime.ts
 import { spawn } from "child_process";

package/dist/{chunk-MVRF7BES.js → chunk-36KYEDEO.js}

@@ -51,6 +51,14 @@ function showCursor() {
   return "\x1B[?25h";
 }
 
+// src/format/repository.ts
+function formatRepositoryDisplay(snapshot, fallback = "repository") {
+  if (snapshot.repository) {
+    return `${snapshot.repository.owner}/${snapshot.repository.name}`;
+  }
+  return snapshot.slug ?? fallback;
+}
+
 export {
   bold,
   dim,
@@ -64,5 +72,6 @@ export {
   setNoColor,
   clearScreen,
   hideCursor,
-  showCursor
+  showCursor,
+  formatRepositoryDisplay
 };

package/dist/{chunk-C7G7RJ4G.js → chunk-DDL4BWSL.js}

@@ -2,7 +2,7 @@
 import {
   loadGlobalConfig,
   loadProjectConfig
-} from "./chunk-ROGRTUFI.js";
+} from "./chunk-QIRE2VXS.js";
 
 // src/project-selection.ts
 import * as p from "@clack/prompts";

package/dist/{chunk-XN5ABWZ6.js → chunk-DFLXHNYQ.js}

@@ -5,6 +5,7 @@ import {
   clearScreen,
   cyan,
   dim,
+  formatRepositoryDisplay,
   green,
   hideCursor,
   magenta,
@@ -12,14 +13,17 @@ import {
   showCursor,
   stripAnsi,
   yellow
-} from "./chunk-MVRF7BES.js";
+} from "./chunk-36KYEDEO.js";
 import {
   resolveRuntimeRoot
-} from "./chunk-5NV3LSAJ.js";
+} from "./chunk-IWFX2FMA.js";
+import {
+  rejectRemovedProjectId
+} from "./chunk-GDE6FYN4.js";
 import {
   handleMissingManagedProjectConfig,
   resolveManagedProjectConfig
-} from "./chunk-C7G7RJ4G.js";
+} from "./chunk-DDL4BWSL.js";
 
 // src/commands/status.ts
 import { readFile } from "fs/promises";
@@ -212,7 +216,9 @@ function renderDashboard(snapshots, options) {
     const hasActiveRuns = snap.activeRuns.length > 0;
     const hasRetries = snap.retryQueue.length > 0;
     if (!hasActiveRuns && !hasRetries) continue;
-    lines.push(sectionDivider(snap.slug, width, c));
+    lines.push(
+      sectionDivider(formatRepositoryDisplay(snap), width, c)
+    );
     if (hasActiveRuns) {
       lines.push(tableHeaderRow(c));
       for (const rawRun of snap.activeRuns) {
@@ -280,7 +286,7 @@ function resolveProjectTokenDelta(snapshot) {
 function renderLegacyStatus(snapshot, noColor) {
   const apply = noColor ? (s) => stripAnsi(s) : (s) => s;
   const lines = [];
-  const headerTitle = `gh-symphony \u2219 ${snapshot.slug}`;
+  const headerTitle = `gh-symphony \u2219 ${formatRepositoryDisplay(snapshot)}`;
   const headerWidth = 45;
   const headerPadding = Math.max(
     0,
@@ -363,16 +369,6 @@ function parseStatusArgs(args) {
       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;
@@ -381,33 +377,33 @@ function parseStatusArgs(args) {
   return parsed;
 }
 async function readStatusSnapshot(runtimeRoot, projectId) {
-  try {
-    const statusPath = join(
-      runtimeRoot,
-      "projects",
-      projectId,
-      "status.json"
-    );
-    const content = await readFile(statusPath, "utf-8");
-    return JSON.parse(content);
-  } catch {
-    return null;
+  for (const statusPath of [
+    join(runtimeRoot, "status.json"),
+    join(runtimeRoot, "projects", projectId, "status.json")
+  ]) {
+    try {
+      const content = await readFile(statusPath, "utf-8");
+      return JSON.parse(content);
+    } catch {
+    }
   }
+  return null;
 }
 var handler = async (args, options) => {
+  if (rejectRemovedProjectId(args)) {
+    return;
+  }
   const parsed = parseStatusArgs(args);
   if (parsed.error) {
     process.stderr.write(`${parsed.error}
 `);
-    process.stderr.write(
-      "Usage: gh-symphony status [--project-id <project-id>] [--watch]\n"
-    );
+    process.stderr.write("Usage: gh-symphony status [--watch]\n");
     process.exitCode = 2;
     return;
   }
   const projectConfig = await resolveManagedProjectConfig({
     configDir: options.configDir,
-    requestedProjectId: parsed.projectId
+    requestedProjectId: void 0
   });
   if (!projectConfig) {
     handleMissingManagedProjectConfig();

package/dist/{chunk-KY6WKH66.js → chunk-E7HYEEZD.js}

@@ -5,7 +5,7 @@ import {
   createStore,
   releaseProjectLock,
   resolveOrchestratorLogLevel
-} from "./chunk-MYVJ6HK4.js";
+} from "./chunk-PUDXVBSN.js";
 import {
   getGhToken
 } from "./chunk-C67H3OUL.js";
@@ -17,29 +17,33 @@ import {
   parseRecentEvents,
   readJsonFile,
   safeReadDir
-} from "./chunk-QEONJ5DZ.js";
+} from "./chunk-EEQQWTXS.js";
 import {
   bold,
   cyan,
   dim,
+  formatRepositoryDisplay,
   green,
   red,
   setNoColor,
   yellow
-} from "./chunk-MVRF7BES.js";
+} from "./chunk-36KYEDEO.js";
 import {
   resolveRuntimeRoot
-} from "./chunk-5NV3LSAJ.js";
+} from "./chunk-IWFX2FMA.js";
+import {
+  rejectRemovedProjectId
+} from "./chunk-GDE6FYN4.js";
 import {
   handleMissingManagedProjectConfig,
   resolveManagedProjectConfig
-} from "./chunk-C7G7RJ4G.js";
+} from "./chunk-DDL4BWSL.js";
 import {
   daemonPidPath,
   httpStatusPath,
   orchestratorLogPath,
   writeJsonFile
-} from "./chunk-ROGRTUFI.js";
+} from "./chunk-QIRE2VXS.js";
 
 // src/commands/start.ts
 import { writeFile, mkdir, readFile as readFile2, rm } from "fs/promises";
@@ -55,24 +59,30 @@ var RECENT_EVENT_CHUNK_SIZE = 4096;
 var MAX_RECENT_EVENT_SCAN_BYTES = 64 * 1024;
 var RUN_RECORD_LOAD_CONCURRENCY = 8;
 var DashboardFsReader = class {
-  constructor(runtimeRoot, projectId) {
+  constructor(runtimeRoot) {
     this.runtimeRoot = runtimeRoot;
-    this.projectId = projectId;
-    assertValidDashboardProjectId(projectId);
     this.resolvedRuntimeRoot = resolve(runtimeRoot);
   }
   resolvedRuntimeRoot;
   projectDir() {
-    return join(this.resolvedRuntimeRoot, "projects", this.projectId);
+    return this.resolvedRuntimeRoot;
   }
   runDir(runId) {
     assertValidDashboardRunId(runId);
-    return join(this.projectDir(), "runs", runId);
+    return join(this.resolvedRuntimeRoot, "runs", runId);
   }
   async loadProjectStatus() {
-    return readJsonFile(
-      join(this.projectDir(), "status.json")
-    );
+    const snapshot = await readJsonFile(join(this.projectDir(), "status.json"));
+    if (!snapshot) {
+      return null;
+    }
+    const status = { ...snapshot };
+    delete status.projectId;
+    delete status.slug;
+    if (!isRepositoryRef(status.repository)) {
+      return null;
+    }
+    return status;
   }
   async loadProjectState() {
     const snapshot = await this.loadProjectStatus();
@@ -216,7 +226,6 @@ async function statusForIssue(reader, issueIdentifier) {
   const currentRunCandidate = issueRecord.currentRunId ? await reader.loadRun(issueRecord.currentRunId) : null;
   const currentRun = isMatchingIssueRun(
     currentRunCandidate,
-    reader.projectId,
     issueRecord.issueId,
     issueIdentifier
   ) ? currentRunCandidate : null;
@@ -300,13 +309,6 @@ function findLatestRunForIssue(matchingRuns) {
   );
   return sortedRuns[0] ?? null;
 }
-function assertValidDashboardProjectId(projectId) {
-  if (projectId.length === 0 || projectId === "." || projectId === ".." || projectId.includes("/") || projectId.includes("\\")) {
-    throw new Error(
-      `Invalid project ID "${projectId}". Project IDs must not contain path separators or traversal segments.`
-    );
-  }
-}
 function assertValidDashboardRunId(runId) {
   if (runId.length === 0 || runId === "." || runId === ".." || runId.includes("/") || runId.includes("\\")) {
     throw new Error(
@@ -314,6 +316,13 @@ function assertValidDashboardRunId(runId) {
     );
   }
 }
+function isRepositoryRef(value) {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const repository = value;
+  return typeof repository.owner === "string" && repository.owner.length > 0 && typeof repository.name === "string" && repository.name.length > 0 && typeof repository.cloneUrl === "string";
+}
 async function mapWithConcurrency(items, concurrency, mapper) {
   const results = new Array(items.length);
   let nextIndex = 0;
@@ -507,7 +516,7 @@ function createControlPlaneHandler(options) {
   };
 }
 async function startControlPlaneServer(options) {
-  const reader = new DashboardFsReader(options.runtimeRoot, options.projectId);
+  const reader = new DashboardFsReader(options.runtimeRoot);
   const handler2 = createControlPlaneHandler({
     reader,
     onRefreshRequest: options.onRefreshRequest
@@ -721,16 +730,6 @@ function parseStartArgs(args) {
       i += 1;
       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 === "--log-level") {
       const value = args[i + 1];
       if (!value || value.startsWith("-")) {
@@ -756,7 +755,9 @@ function logTickResult(snapshot, prevSnapshot, isFirst) {
     const healthColor = snapshot.health === "degraded" ? red : snapshot.health === "running" ? green : cyan;
     logLine(
       green("\u25CF"),
-      `Project ${bold(snapshot.slug)} connected ${dim("(")}${healthColor(snapshot.health)}${dim(")")}`
+      `Repository ${bold(formatRepositoryDisplay(snapshot))} connected ${dim(
+        "("
+      )}${healthColor(snapshot.health)}${dim(")")}`
     );
     if (snapshot.summary.activeRuns > 0) {
       logLine(cyan("\u25B8"), `${snapshot.summary.activeRuns} active run(s)`);
@@ -885,7 +886,7 @@ async function removeHttpBindingState(configDir, projectId) {
   await rm(httpStatusPath(configDir, projectId), { force: true });
 }
 async function startHttpServer(input) {
-  const reader = new DashboardFsReader(input.runtimeRoot, input.projectId);
+  const reader = new DashboardFsReader(input.runtimeRoot);
   for (let port = input.initialPort; port <= 65535; port += 1) {
     const server = createServer3((request, response) => {
       void (async () => {
@@ -955,6 +956,9 @@ var handler = async (args, options) => {
   setNoColor(options.noColor);
   let parsed;
   try {
+    if (rejectRemovedProjectId(args)) {
+      return;
+    }
     parsed = parseStartArgs(args);
   } catch (error) {
     process.stderr.write(
@@ -968,24 +972,33 @@ var handler = async (args, options) => {
     process.stderr.write(`${parsed.error}
 `);
     process.stderr.write(
-      "Usage: gh-symphony start --project-id <project-id> [--daemon] [--once] [--http [port]] [--web [port]]\n"
+      "Usage: gh-symphony start [--daemon] [--once] [--http [port]] [--web [port]]\n"
     );
     process.exitCode = 2;
     return;
   }
   if (parsed.daemon && parsed.once) {
-    process.stderr.write("Options '--daemon' and '--once' cannot be used together\n");
+    process.stderr.write(
+      "Options '--daemon' and '--once' cannot be used together\n"
+    );
     process.exitCode = 2;
     return;
   }
   const projectConfig = await resolveManagedProjectConfig({
     configDir: options.configDir,
-    requestedProjectId: parsed.projectId
+    requestedProjectId: void 0
   });
   if (!projectConfig) {
     handleMissingManagedProjectConfig();
     return;
   }
+  if (!hasConfiguredRepository(projectConfig)) {
+    process.stderr.write(
+      "No repository is configured in this project. Run 'gh-symphony repo add owner/name' first.\n"
+    );
+    process.exitCode = 1;
+    return;
+  }
   const runtimeRoot = resolveRuntimeRoot(options.configDir);
   const projectId = projectConfig.projectId;
   let logLevel;
@@ -1094,7 +1107,6 @@ var handler = async (args, options) => {
         host: HTTP_HOST,
         port: parsed.webPort,
         runtimeRoot,
-        projectId,
         onRefreshRequest: () => service.requestReconcile()
       }) : parsed.httpPort !== void 0 ? await startHttpServer({
         runtimeRoot,
@@ -1238,19 +1250,27 @@ async function shutdownForegroundOrchestrator(input) {
   }
   return (input.exit ?? process.exit)(0);
 }
+function hasConfiguredRepository(config) {
+  return Boolean(config.repository?.owner && config.repository.name);
+}
 async function tailWorkerLog(runtimeRoot, projectId, runId, issueIdentifier) {
-  try {
-    const logPath = join3(runtimeRoot, "projects", projectId, "runs", runId, "worker.log");
-    const content = await readFile2(logPath, "utf8");
-    const lines = content.split("\n").filter((l) => l.trim());
-    if (lines.length === 0) return;
-    const tail = lines.slice(-30);
-    logLine(red("\u2717"), red(`Worker stderr (${issueIdentifier}):`));
-    for (const line of tail) {
-      process.stdout.write(`  ${dim(line)}
+  for (const logPath of [
+    join3(runtimeRoot, "runs", runId, "worker.log"),
+    join3(runtimeRoot, "projects", projectId, "runs", runId, "worker.log")
+  ]) {
+    try {
+      const content = await readFile2(logPath, "utf8");
+      const lines = content.split("\n").filter((l) => l.trim());
+      if (lines.length === 0) return;
+      const tail = lines.slice(-30);
+      logLine(red("\u2717"), red(`Worker stderr (${issueIdentifier}):`));
+      for (const line of tail) {
+        process.stdout.write(`  ${dim(line)}
 `);
+      }
+      return;
+    } catch {
     }
-  } catch {
   }
 }
 var start_default = handler;
@@ -1264,8 +1284,6 @@ async function startDaemon(options, projectId, logLevel, httpPort, webPort) {
     [
       process.argv[1],
       "start",
-      "--project",
-      projectId,
       ...httpPort !== void 0 ? ["--http", String(httpPort)] : [],
       ...webPort !== void 0 ? ["--web", String(webPort)] : [],
       ...logLevel ? ["--log-level", logLevel] : []
@@ -1289,7 +1307,7 @@ async function startDaemon(options, projectId, logLevel, httpPort, webPort) {
   process.stdout.write(
     `Orchestrator started in background (PID: ${child.pid}).
 Logs: ${logPath}
-Stop with: gh-symphony project stop --project-id ${projectId}
+Stop with: gh-symphony repo stop
 `
   );
 }