@gh-symphony/cli 0.0.20 → 0.0.22

package/dist/{chunk-ROGRTUFI.js → chunk-QIRE2VXS.js}

@@ -54,9 +54,15 @@ async function saveGlobalConfig(configDir, config) {
   await writeJsonFile(configFilePath(configDir), config);
 }
 async function loadProjectConfig(configDir, projectId) {
-  return readJsonFile(
-    projectConfigPath(configDir, projectId)
-  );
+  const config = await readJsonFile(projectConfigPath(configDir, projectId));
+  if (!config) {
+    return null;
+  }
+  const repository = config.repository ?? firstConfiguredRepository(config);
+  return {
+    ...config,
+    ...repository ? { repository } : {}
+  };
 }
 async function saveProjectConfig(configDir, projectId, config) {
   await writeJsonFile(projectConfigPath(configDir, projectId), config);
@@ -91,6 +97,11 @@ function isFileMissing(error) {
     error && typeof error === "object" && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR")
   );
 }
+function firstConfiguredRepository(config) {
+  return config.repositories?.find(
+    (repository) => typeof repository.owner === "string" && repository.owner.length > 0 && typeof repository.name === "string" && repository.name.length > 0
+  );
+}
 
 export {
   resolveConfigDir,

package/dist/{chunk-3AWF54PI.js → chunk-ZHOKYUO3.js}

@@ -2,34 +2,57 @@
 import {
   abortIfCancelled,
   generateProjectId,
+  warnIfProjectDiscoveryPartial,
   writeConfig
-} from "./chunk-RN2PACNV.js";
+} from "./chunk-HMLBBZNY.js";
 import {
   start_default
-} from "./chunk-EKKT5USP.js";
+} from "./chunk-E7HYEEZD.js";
+import {
+  explainIssueDispatch,
+  isActiveRunRecordStatus,
+  parseIssueIdentifier,
+  resolveTrackerAdapter
+} from "./chunk-PUDXVBSN.js";
+import {
+  findGithubProjectIssue
+} from "./chunk-2TSM3INR.js";
 import {
   GhAuthError,
   GitHubScopeError,
   checkRequiredScopes,
   createClient,
+  discoverUserProjects,
+  getGhToken,
   getGhTokenWithSource,
   getProjectDetail,
   listUserProjects,
   resolveGitHubAuth,
   validateToken
-} from "./chunk-TILHWBP6.js";
+} from "./chunk-C67H3OUL.js";
+import {
+  WorkflowConfigStore
+} from "./chunk-EEQQWTXS.js";
 import {
   status_default
-} from "./chunk-XN5ABWZ6.js";
+} from "./chunk-DFLXHNYQ.js";
 import {
-  stripAnsi
-} from "./chunk-MVRF7BES.js";
+  bold,
+  green,
+  red,
+  stripAnsi,
+  yellow
+} from "./chunk-36KYEDEO.js";
 import {
   resolveRuntimeRoot
-} from "./chunk-5NV3LSAJ.js";
+} from "./chunk-IWFX2FMA.js";
 import {
   stop_default
-} from "./chunk-Y6TYJMNT.js";
+} from "./chunk-GSX2FV3M.js";
+import {
+  handleMissingManagedProjectConfig,
+  resolveManagedProjectConfig
+} from "./chunk-DDL4BWSL.js";
 import {
   daemonPidPath,
   httpStatusPath,
@@ -37,16 +60,42 @@ import {
   loadProjectConfig,
   projectConfigDir,
   saveGlobalConfig
-} from "./chunk-ROGRTUFI.js";
+} from "./chunk-QIRE2VXS.js";
 
 // src/commands/project.ts
 import * as p from "@clack/prompts";
 import { execFile as execFileCallback } from "child_process";
 import { promisify } from "util";
-import { readFile } from "fs/promises";
+import { readdir, readFile } from "fs/promises";
 import { join } from "path";
+import { resolve } from "path";
 var execFile = promisify(execFileCallback);
 var KNOWN_REQUIRED_SCOPES = ["repo", "read:org", "project"];
+function formatProjectRepoSummary(selectedRepos, totalLinked) {
+  if (totalLinked === 0) {
+    return "none linked yet (0 linked)";
+  }
+  if (selectedRepos.length === totalLinked) {
+    return `${selectedRepos.map((repo) => `${repo.owner}/${repo.name}`).join(", ")}  (all ${selectedRepos.length} linked)`;
+  }
+  if (selectedRepos.length === 0) {
+    return `none selected  (0 of ${totalLinked} linked)`;
+  }
+  return `${selectedRepos.map((repo) => `${repo.owner}/${repo.name}`).join(", ")}  (${selectedRepos.length} of ${totalLinked} linked)`;
+}
+function projectCreatedMessage(projectId, repositoryCount) {
+  const lines = [
+    `Project "${projectId}" created with ${repositoryCount} repositor${repositoryCount === 1 ? "y" : "ies"}.`,
+    "Run 'gh-symphony start' to begin orchestration."
+  ];
+  if (repositoryCount === 0) {
+    lines.push(
+      "Next step: run 'gh-symphony repo add <owner/name>' to register a repository.",
+      "Or add a repo-linked issue to the GitHub Project and re-run setup later."
+    );
+  }
+  return lines.join("\n");
+}
 function displayScopeError(error, retryCommand) {
   const plural = error.requiredScopes.length === 1 ? "" : "s";
   p.log.error(
@@ -86,6 +135,47 @@ function parseProjectAddFlags(args) {
   }
   return flags;
 }
+function parseProjectExplainFlags(args) {
+  const parsed = {};
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    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 === "--workflow" || arg === "--workflow-path") {
+      const value = args[i + 1];
+      if (!value || value.startsWith("-")) {
+        parsed.error = `Option '${arg}' argument missing`;
+        return parsed;
+      }
+      parsed.workflowPath = value;
+      i += 1;
+      continue;
+    }
+    if (arg?.startsWith("-")) {
+      parsed.error = `Unknown option '${arg}'`;
+      return parsed;
+    }
+    if (parsed.identifier) {
+      parsed.error = "Only one issue identifier can be explained at a time";
+      return parsed;
+    }
+    parsed.identifier = arg;
+  }
+  if (!parsed.identifier) {
+    parsed.error = "Issue identifier argument missing";
+  } else if (!parseIssueIdentifier(parsed.identifier)) {
+    parsed.error = "Issue identifier must use the form <owner>/<repo>#<number>";
+  }
+  return parsed;
+}
 var handler = async (args, options) => {
   const [subcommand, ...rest] = args;
   switch (subcommand) {
@@ -110,9 +200,12 @@ var handler = async (args, options) => {
     case "status":
       await status_default(rest, options);
       return;
+    case "explain":
+      await projectExplain(rest, options);
+      return;
     default:
       process.stdout.write(
-        "Usage: gh-symphony project <add|list|remove|start|stop|switch|status>\n"
+        "Usage: gh-symphony project <add|list|remove|start|stop|switch|status|explain>\n"
       );
   }
 };
@@ -210,9 +303,260 @@ async function readPersistedSnapshot(configDir, projectId) {
 async function fetchProjectSnapshot(configDir, projectId) {
   return readPersistedSnapshot(configDir, projectId);
 }
+async function projectExplain(args, options) {
+  const parsed = parseProjectExplainFlags(args);
+  if (parsed.error) {
+    process.stderr.write(`${parsed.error}
+`);
+    process.stderr.write(
+      "Usage: gh-symphony project explain <owner/repo#number> [--project-id <project-id>] [--workflow <path>]\n"
+    );
+    process.exitCode = 2;
+    return;
+  }
+  const projectConfig = await resolveManagedProjectConfig({
+    configDir: options.configDir,
+    requestedProjectId: parsed.projectId
+  });
+  if (!projectConfig) {
+    handleMissingManagedProjectConfig();
+    return;
+  }
+  const identifier = parsed.identifier;
+  const parsedIdentifier = parseIssueIdentifier(identifier);
+  const fallbackRepository = {
+    owner: parsedIdentifier.owner,
+    name: parsedIdentifier.name,
+    cloneUrl: `https://github.com/${parsedIdentifier.owner}/${parsedIdentifier.name}.git`
+  };
+  const workflowRepository = projectConfig.repository ?? fallbackRepository;
+  let token;
+  try {
+    token = getGhToken();
+  } catch (error) {
+    if (error instanceof GhAuthError) {
+      process.stderr.write(
+        `Error: GitHub authentication is required for project explain. ${error.message}
+`
+      );
+      process.stderr.write(
+        "Run 'gh auth login --scopes repo,read:org,project' or set GITHUB_GRAPHQL_TOKEN, then re-run this command.\n"
+      );
+      process.exitCode = 2;
+      return;
+    }
+    throw error;
+  }
+  const trackerAdapter = resolveTrackerAdapter(projectConfig.tracker);
+  const orchestratorProject = {
+    ...projectConfig,
+    repository: workflowRepository
+  };
+  const trackerDependencies = {
+    token,
+    projectItemsCache: createProjectItemsCache()
+  };
+  const runtimeRoot = join(
+    resolveRuntimeRoot(options.configDir),
+    "projects",
+    projectConfig.projectId
+  );
+  const issuesPromise = trackerAdapter.listIssues(
+    orchestratorProject,
+    trackerDependencies
+  );
+  const issuePromise = projectConfig.tracker.adapter === "github-project" ? findGithubProjectIssue(
+    orchestratorProject,
+    identifier,
+    trackerDependencies
+  ) : issuesPromise.then(
+    (issues2) => issues2.find(
+      (candidate) => candidate.identifier.trim().toLowerCase() === identifier.trim().toLowerCase()
+    ) ?? null
+  );
+  const [issues, issue, issueRecords, runs, snapshot] = await Promise.all([
+    issuesPromise,
+    issuePromise,
+    readJsonFile(join(runtimeRoot, "issues.json")),
+    readRuns(runtimeRoot, projectConfig.projectId),
+    readPersistedSnapshot(options.configDir, projectConfig.projectId)
+  ]);
+  let workflow;
+  try {
+    workflow = await loadExplainWorkflow({
+      explicitWorkflowPath: parsed.workflowPath,
+      repository: workflowRepository,
+      runs
+    });
+  } catch (error) {
+    if (error instanceof ProjectExplainWorkflowError) {
+      process.stderr.write(`Error: ${error.message}
+`);
+      process.stderr.write(
+        "Hint: pass --workflow <path-to-WORKFLOW.md> or run 'gh-symphony workflow preview --file <path>' to verify the workflow file.\n"
+      );
+      process.exitCode = 2;
+      return;
+    }
+    throw error;
+  }
+  const activeRunCount = runs.filter(
+    (run) => isActiveRunRecordStatus(run.status)
+  ).length;
+  const report = explainIssueDispatch({
+    identifier,
+    issue,
+    projectRepository: projectConfig.repository ?? null,
+    allIssues: issues,
+    lifecycle: workflow.lifecycle,
+    issueRecords: issueRecords ?? [],
+    runs,
+    activeRunCount,
+    maxConcurrentAgents: workflow.maxConcurrentAgents,
+    maxConcurrentAgentsByState: workflow.maxConcurrentAgentsByState
+  });
+  const enrichedReport = {
+    ...report,
+    project: {
+      id: projectConfig.projectId,
+      slug: projectConfig.slug,
+      tracker: projectConfig.tracker,
+      lastTickAt: snapshot?.lastTickAt ?? null,
+      health: snapshot?.health ?? null
+    }
+  };
+  if (options.json) {
+    process.stdout.write(JSON.stringify(enrichedReport, null, 2) + "\n");
+    return;
+  }
+  process.stdout.write(renderProjectExplainReport(report, options.noColor));
+}
+var ProjectExplainWorkflowError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ProjectExplainWorkflowError";
+  }
+};
+async function loadExplainWorkflow(input) {
+  const workflowPaths = resolveExplainWorkflowCandidates(input);
+  if (workflowPaths.length === 0) {
+    throw new ProjectExplainWorkflowError(
+      "No WORKFLOW.md path could be resolved from --workflow, the configured repository path, or previous run records."
+    );
+  }
+  const failures = [];
+  for (const workflowPath of workflowPaths) {
+    try {
+      const resolution = await new WorkflowConfigStore().load(workflowPath);
+      return {
+        lifecycle: resolution.lifecycle,
+        maxConcurrentAgents: resolution.workflow.agent.maxConcurrentAgents,
+        maxConcurrentAgentsByState: resolution.workflow.agent.maxConcurrentAgentsByState
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      failures.push(`${workflowPath}: ${message}`);
+    }
+  }
+  throw new ProjectExplainWorkflowError(
+    `Unable to load WORKFLOW.md for project explain. Checked: ${failures.join("; ")}`
+  );
+}
+function resolveExplainWorkflowCandidates(input) {
+  const paths = [];
+  if (input.explicitWorkflowPath) {
+    paths.push(resolve(input.explicitWorkflowPath));
+  }
+  if (input.repository.path) {
+    paths.push(join(resolve(input.repository.path), "WORKFLOW.md"));
+  }
+  const newestRuns = [...input.runs].sort(
+    (left, right) => (Date.parse(right.updatedAt) || 0) - (Date.parse(left.updatedAt) || 0)
+  );
+  for (const run of newestRuns) {
+    if (run.workflowPath) {
+      paths.push(resolve(run.workflowPath));
+    }
+    if (run.workingDirectory) {
+      paths.push(join(resolve(run.workingDirectory), "WORKFLOW.md"));
+    }
+  }
+  return [...new Set(paths)];
+}
+function createProjectItemsCache() {
+  const entries = /* @__PURE__ */ new Map();
+  return {
+    getOrLoad(key, load) {
+      const cached = entries.get(key);
+      if (cached) {
+        return cached;
+      }
+      const pending = load().catch((error) => {
+        entries.delete(key);
+        throw error;
+      });
+      entries.set(key, pending);
+      return pending;
+    }
+  };
+}
+async function readRuns(runtimeRoot, projectId) {
+  let runIds;
+  try {
+    runIds = await readdir(join(runtimeRoot, "runs"));
+  } catch {
+    return [];
+  }
+  const runs = await Promise.all(
+    runIds.map(
+      (runId) => readJsonFile(
+        join(runtimeRoot, "runs", runId, "run.json")
+      )
+    )
+  );
+  return runs.filter(
+    (run) => run !== null && run.projectId === projectId
+  );
+}
+async function readJsonFile(path) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function renderProjectExplainReport(report, noColor) {
+  const apply = noColor ? (value) => stripAnsi(value) : (value) => value;
+  const lines = [
+    apply(bold(`Issue dispatch explanation: ${report.issue.identifier}`)),
+    report.summary,
+    "",
+    `State: ${report.issue.state ?? "unknown"}`,
+    `Repository: ${report.issue.repository}`,
+    "",
+    "Checks:"
+  ];
+  for (const check of report.checks) {
+    const marker = check.status === "pass" ? green("\u2713") : check.status === "warn" ? yellow("!") : red("\u2717");
+    lines.push(`  ${apply(marker)} ${check.message}`);
+    if (check.hint) {
+      lines.push(`    Hint: ${check.hint}`);
+    }
+  }
+  lines.push("");
+  lines.push("Related commands:");
+  lines.push("  gh-symphony workflow preview");
+  lines.push("  gh-symphony doctor");
+  lines.push("  gh-symphony project status");
+  lines.push("  gh-symphony logs --issue " + report.issue.identifier);
+  return lines.join("\n") + "\n";
+}
 async function readHttpEndpoint(configDir, projectId) {
   try {
-    const content = await readFile(httpStatusPath(configDir, projectId), "utf8");
+    const content = await readFile(
+      httpStatusPath(configDir, projectId),
+      "utf8"
+    );
     const state = JSON.parse(content);
     return typeof state.endpoint === "string" && state.endpoint.length > 0 ? state.endpoint : null;
   } catch {
@@ -224,7 +568,12 @@ async function readProcessUptime(pid) {
     return "-";
   }
   try {
-    const { stdout } = await execFile("ps", ["-o", "etime=", "-p", String(pid)]);
+    const { stdout } = await execFile("ps", [
+      "-o",
+      "etime=",
+      "-p",
+      String(pid)
+    ]);
     const seconds = parsePsElapsedTime(stdout);
     return seconds === null ? "-" : formatDuration(seconds);
   } catch {
@@ -370,10 +719,9 @@ async function projectAddNonInteractive(flags, options) {
       JSON.stringify({ projectId, status: "created" }) + "\n"
     );
   } else {
-    process.stdout.write(`Project created: ${projectId}
-`);
-    process.stdout.write(`Run 'gh-symphony start' to begin orchestration.
-`);
+    process.stdout.write(
+      projectCreatedMessage(projectId, project.linkedRepositories.length) + "\n"
+    );
   }
 }
 async function projectAddInteractive(flags, options) {
@@ -417,10 +765,12 @@ async function projectAddInteractive(flags, options) {
   s2.start("Loading GitHub Project boards...");
   let projects;
   try {
-    projects = await listUserProjects(client);
+    const discovery = await discoverUserProjects(client);
+    projects = discovery.projects;
     s2.stop(
       `Found ${projects.length} project${projects.length === 1 ? "" : "s"}`
     );
+    warnIfProjectDiscoveryPartial(discovery);
   } catch (error) {
     s2.stop("Failed to load projects.");
     if (error instanceof GitHubScopeError) {
@@ -463,10 +813,8 @@ async function projectAddInteractive(flags, options) {
   }
   if (projectDetail.linkedRepositories.length === 0) {
     p.log.warn(
-      "No linked repositories found in this project. Add issues from repositories to the project first."
+      "No linked repositories found in this project. Add issues from repositories to the project, or run 'gh-symphony repo add owner/name' to validate and save a repository before your first orchestration run."
     );
-    process.exitCode = 1;
-    return;
   }
   const {
     assignedOnly: promptAssignedOnly,
@@ -479,7 +827,10 @@ async function projectAddInteractive(flags, options) {
     assignedOnlyInitialValue: flags.assignedOnly
   });
   const assignedOnly = flags.assignedOnly || promptAssignedOnly;
-  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)`;
+  const repoSummary = formatProjectRepoSummary(
+    selectedRepos,
+    projectDetail.linkedRepositories.length
+  );
   p.note(
     renderProjectRegistrationSummary({
       login,
@@ -516,10 +867,7 @@ async function projectAddInteractive(flags, options) {
     process.exitCode = 1;
     return;
   }
-  p.outro(
-    `Project "${projectId}" created.
-  Run 'gh-symphony start' to begin orchestration.`
-  );
+  p.outro(projectCreatedMessage(projectId, selectedRepos.length));
 }
 async function promptProjectRegistrationOptions(input) {
   const assignedOnly = await abortIfCancelled(
@@ -537,23 +885,25 @@ async function promptProjectRegistrationOptions(input) {
   let selectedRepos = input.projectDetail.linkedRepositories;
   let workspaceDir = input.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: input.projectDetail.linkedRepositories.map((repo) => ({
-            value: repo,
-            label: `${repo.owner}/${repo.name}`
-          })),
-          required: true
+    if (input.projectDetail.linkedRepositories.length > 0) {
+      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: input.projectDetail.linkedRepositories.map((repo) => ({
+              value: repo,
+              label: `${repo.owner}/${repo.name}`
+            })),
+            required: true
+          })
+        );
+      }
     }
     workspaceDir = await abortIfCancelled(
       p.text({
@@ -632,7 +982,9 @@ async function projectRemove(args, options) {
     process.exitCode = 1;
     return;
   }
-  const updatedProjects = global.projects.filter((entry) => entry !== projectId);
+  const updatedProjects = global.projects.filter(
+    (entry) => entry !== projectId
+  );
   if (updatedProjects.length === global.projects.length) {
     process.stderr.write(`Project "${projectId}" not found.
 `);

package/dist/{config-cmd-DNXNL26Z.js → config-cmd-Z3A7V6NC.js}

@@ -3,7 +3,7 @@ import {
   configFilePath,
   loadGlobalConfig,
   saveGlobalConfig
-} from "./chunk-ROGRTUFI.js";
+} from "./chunk-QIRE2VXS.js";
 
 // src/commands/config-cmd.ts
 import { spawn } from "child_process";