@gh-symphony/cli 0.0.17 → 0.0.18

package/README.md

@@ -25,6 +25,13 @@ Verify the installation:
 gh-symphony --version
 ```
 
+Validate the machine and repo prerequisites before first use:
+
+```bash
+gh-symphony doctor
+gh-symphony doctor --json
+```
+
 Enable shell completion:
 
 ```bash
@@ -113,6 +120,7 @@ The interactive wizard will:
 ### Project Management
 
 ```bash
+gh-symphony doctor                   # Validate auth, config, WORKFLOW.md, and runtime command
 gh-symphony project list             # List all configured projects
 gh-symphony project remove <id>      # Remove a project
 ```
@@ -154,11 +162,28 @@ gh-symphony recover                 # Recover stalled runs
 gh-symphony recover --dry-run       # Preview what would be recovered
 ```
 
+## Diagnostics
+
+`gh-symphony doctor` validates the most common first-run prerequisites in one pass:
+
+- `gh` installation, auth, and required scopes
+- managed project selection plus GitHub Project binding resolution
+- config/runtime/workspace path writability
+- repository `WORKFLOW.md` presence and parse validity
+- runtime command availability on `PATH`
+
+Use JSON output for scripts and CI smoke checks:
+
+```bash
+gh-symphony doctor --json
+```
+
 ## Command Reference
 
 ```
 Setup:
   init                Interactive repository setup wizard
+  doctor              Run first-run diagnostics
   config show         Show current configuration
   config set          Set a configuration value
   config edit         Open config in $EDITOR

package/dist/{chunk-IWR4UQEJ.js → chunk-5YLETHMR.js}

@@ -1,9 +1,17 @@
 #!/usr/bin/env node
+import {
+  GitHubScopeError,
+  checkRequiredScopes,
+  createClient,
+  getProjectDetail,
+  listUserProjects,
+  validateToken
+} from "./chunk-62L6QQE6.js";
 import {
   GhAuthError,
   ensureGhAuth,
   getGhToken
-} from "./chunk-JO3AXHQI.js";
+} from "./chunk-7UBUBSMH.js";
 import {
   loadGlobalConfig,
   saveGlobalConfig,
@@ -16,357 +24,6 @@ import { createHash } from "crypto";
 import { mkdir as mkdir3, rename, writeFile as writeFile3 } from "fs/promises";
 import { basename, dirname as dirname2, join as join3, relative, resolve } from "path";
 
-// src/github/client.ts
-var DEFAULT_API_URL = "https://api.github.com/graphql";
-var REST_API_URL = "https://api.github.com";
-var GitHubApiError = class extends Error {
-  constructor(message, status) {
-    super(message);
-    this.status = status;
-    this.name = "GitHubApiError";
-  }
-};
-var GitHubScopeError = class extends GitHubApiError {
-  constructor(message, requiredScopes, currentScopes) {
-    super(message);
-    this.requiredScopes = requiredScopes;
-    this.currentScopes = currentScopes;
-    this.name = "GitHubScopeError";
-  }
-};
-function createClient(token, options) {
-  return {
-    token,
-    apiUrl: options?.apiUrl ?? DEFAULT_API_URL,
-    fetchImpl: options?.fetchImpl ?? fetch
-  };
-}
-async function validateToken(client) {
-  const restUrl = client.apiUrl.replace("/graphql", "");
-  const baseUrl = restUrl === client.apiUrl ? REST_API_URL : restUrl;
-  const response = await client.fetchImpl(`${baseUrl}/user`, {
-    headers: {
-      authorization: `Bearer ${client.token}`,
-      accept: "application/vnd.github+json"
-    }
-  });
-  if (!response.ok) {
-    if (response.status === 401) {
-      throw new GitHubApiError("Invalid token: authentication failed.", 401);
-    }
-    throw new GitHubApiError(
-      `GitHub API error: ${response.status} ${response.statusText}`,
-      response.status
-    );
-  }
-  const scopes = response.headers.get("x-oauth-scopes")?.split(",").map((s) => s.trim()).filter(Boolean) ?? [];
-  const user = await response.json();
-  return {
-    login: user.login,
-    name: user.name,
-    scopes
-  };
-}
-function checkRequiredScopes(scopes) {
-  const required = ["repo", "read:org", "project"];
-  const normalizedScopes = scopes.map((s) => s.toLowerCase());
-  const missing = required.filter((r) => !normalizedScopes.includes(r));
-  return { valid: missing.length === 0, missing };
-}
-async function listUserProjects(client) {
-  const data = await graphql(
-    client,
-    VIEWER_PROJECTS_QUERY
-  );
-  const projects = [];
-  for (const node of data.viewer.projectsV2?.nodes ?? []) {
-    if (!node) continue;
-    projects.push(
-      normalizeProjectSummary(node, {
-        login: data.viewer.login,
-        type: "User"
-      })
-    );
-  }
-  for (const orgNode of data.viewer.organizations?.nodes ?? []) {
-    if (!orgNode) continue;
-    for (const projNode of orgNode.projectsV2?.nodes ?? []) {
-      if (!projNode) continue;
-      projects.push(
-        normalizeProjectSummary(projNode, {
-          login: orgNode.login,
-          type: "Organization"
-        })
-      );
-    }
-  }
-  return projects;
-}
-function normalizeProjectSummary(node, owner) {
-  return {
-    id: node.id,
-    title: node.title,
-    shortDescription: node.shortDescription ?? "",
-    url: node.url,
-    openItemCount: node.items?.totalCount ?? 0,
-    owner
-  };
-}
-async function getProjectDetail(client, projectId) {
-  const data = await graphql(
-    client,
-    PROJECT_DETAIL_QUERY,
-    { projectId }
-  );
-  const project = data.node;
-  if (!project || project.__typename !== "ProjectV2") {
-    throw new GitHubApiError(`Project not found: ${projectId}`);
-  }
-  const statusFields = [];
-  const textFields = [];
-  for (const field of project.fields?.nodes ?? []) {
-    if (!field) continue;
-    if (field.__typename === "ProjectV2SingleSelectField") {
-      statusFields.push({
-        id: field.id,
-        name: field.name,
-        options: (field.options ?? []).map((opt) => ({
-          id: opt.id,
-          name: opt.name,
-          description: opt.description ?? null,
-          color: opt.color ?? null
-        }))
-      });
-    } else if (field.__typename === "ProjectV2Field" && field.dataType) {
-      textFields.push({
-        id: field.id,
-        name: field.name,
-        dataType: field.dataType
-      });
-    }
-  }
-  const repoMap = /* @__PURE__ */ new Map();
-  let cursor = null;
-  let hasMore = true;
-  for (const item of project.items?.nodes ?? []) {
-    const repo = item?.content?.repository;
-    if (!repo) continue;
-    const key = `${repo.owner.login}/${repo.name}`;
-    if (!repoMap.has(key)) {
-      repoMap.set(key, {
-        owner: repo.owner.login,
-        name: repo.name,
-        url: repo.url,
-        cloneUrl: repo.url.endsWith(".git") ? repo.url : `${repo.url}.git`
-      });
-    }
-  }
-  hasMore = project.items?.pageInfo?.hasNextPage ?? false;
-  cursor = project.items?.pageInfo?.endCursor ?? null;
-  while (hasMore && cursor) {
-    const pageData = await graphql(
-      client,
-      PROJECT_ITEMS_PAGE_QUERY,
-      { projectId, cursor }
-    );
-    const items = pageData.node?.items;
-    if (!items) break;
-    for (const item of items.nodes ?? []) {
-      const repo = item?.content?.repository;
-      if (!repo) continue;
-      const key = `${repo.owner.login}/${repo.name}`;
-      if (!repoMap.has(key)) {
-        repoMap.set(key, {
-          owner: repo.owner.login,
-          name: repo.name,
-          url: repo.url,
-          cloneUrl: repo.url.endsWith(".git") ? repo.url : `${repo.url}.git`
-        });
-      }
-    }
-    hasMore = items.pageInfo?.hasNextPage ?? false;
-    cursor = items.pageInfo?.endCursor ?? null;
-  }
-  return {
-    id: project.id,
-    title: project.title,
-    url: project.url,
-    statusFields,
-    textFields,
-    linkedRepositories: [...repoMap.values()]
-  };
-}
-async function graphql(client, query, variables) {
-  const response = await client.fetchImpl(client.apiUrl, {
-    method: "POST",
-    headers: {
-      "content-type": "application/json",
-      authorization: `Bearer ${client.token}`
-    },
-    body: JSON.stringify({ query, variables })
-  });
-  if (!response.ok) {
-    const text = await response.text().catch(() => "");
-    throw new GitHubApiError(
-      `GitHub GraphQL request failed: ${response.status} ${response.statusText}. ${text}`,
-      response.status
-    );
-  }
-  const payload = await response.json();
-  if (payload.errors?.length) {
-    const scopeMessages = payload.errors.map((e) => e.message).filter((m) => m.includes("has not been granted the required scopes"));
-    if (scopeMessages.length > 0) {
-      const requiredScopes = /* @__PURE__ */ new Set();
-      let currentScopes = [];
-      for (const msg of scopeMessages) {
-        for (const match of msg.matchAll(
-          /requires one of the following scopes: \['([^']+)'\]/g
-        )) {
-          requiredScopes.add(match[1]);
-        }
-        if (currentScopes.length === 0) {
-          const currMatch = /has only been granted the: \[([^\]]+)\]/.exec(msg);
-          if (currMatch) {
-            currentScopes = currMatch[1].split(",").map((s) => s.trim().replace(/'/g, "")).filter(Boolean);
-          }
-        }
-      }
-      throw new GitHubScopeError(
-        "Token is missing required GitHub scopes.",
-        [...requiredScopes],
-        currentScopes
-      );
-    }
-    throw new GitHubApiError(
-      `GraphQL errors: ${payload.errors.map((e) => e.message).join("; ")}`
-    );
-  }
-  if (!payload.data) {
-    throw new GitHubApiError("GraphQL response missing data.");
-  }
-  return payload.data;
-}
-var VIEWER_PROJECTS_QUERY = `
-  query ViewerProjects {
-    viewer {
-      login
-      projectsV2(first: 50) {
-        nodes {
-          id
-          title
-          shortDescription
-          url
-          items { totalCount }
-        }
-      }
-      organizations(first: 20) {
-        nodes {
-          login
-          projectsV2(first: 50) {
-            nodes {
-              id
-              title
-              shortDescription
-              url
-              items { totalCount }
-            }
-          }
-        }
-      }
-    }
-  }
-`;
-var PROJECT_DETAIL_QUERY = `
-  query ProjectDetail($projectId: ID!) {
-    node(id: $projectId) {
-      __typename
-      ... on ProjectV2 {
-        id
-        title
-        url
-        fields(first: 50) {
-          nodes {
-            __typename
-            ... on ProjectV2SingleSelectField {
-              id
-              name
-              options {
-                id
-                name
-                description
-                color
-              }
-            }
-            ... on ProjectV2Field {
-              id
-              name
-              dataType
-            }
-          }
-        }
-        items(first: 100) {
-          nodes {
-            content {
-              __typename
-              ... on Issue {
-                repository {
-                  name
-                  url
-                  owner { login }
-                }
-              }
-              ... on PullRequest {
-                repository {
-                  name
-                  url
-                  owner { login }
-                }
-              }
-            }
-          }
-          pageInfo {
-            endCursor
-            hasNextPage
-          }
-        }
-      }
-    }
-  }
-`;
-var PROJECT_ITEMS_PAGE_QUERY = `
-  query ProjectItemsPage($projectId: ID!, $cursor: String) {
-    node(id: $projectId) {
-      ... on ProjectV2 {
-        items(first: 100, after: $cursor) {
-          nodes {
-            content {
-              __typename
-              ... on Issue {
-                repository {
-                  name
-                  url
-                  owner { login }
-                }
-              }
-              ... on PullRequest {
-                repository {
-                  name
-                  url
-                  owner { login }
-                }
-              }
-            }
-          }
-          pageInfo {
-            endCursor
-            hasNextPage
-          }
-        }
-      }
-    }
-  }
-`;
-
 // src/mapping/smart-defaults.ts
 var ROLE_PATTERNS = [
   {
@@ -2236,12 +1893,6 @@ function generateProjectId(githubProjectTitle, uniqueKey) {
 }
 
 export {
-  GitHubScopeError,
-  createClient,
-  validateToken,
-  checkRequiredScopes,
-  listUserProjects,
-  getProjectDetail,
   abortIfCancelled,
   init_default,
   writeEcosystem,