@oss-autopilot/core 1.17.1 → 1.17.3

package/dist/commands/startup.js

@@ -222,38 +222,46 @@ export async function runStartup() {
     }
     // 3. Run daily check
     const daily = await executeDailyCheck(token);
-    // 4. Launch interactive SPA dashboard
-    // Skip opening on first run (0 PRs) — the welcome flow handles onboarding
+    // 4. Launch interactive SPA dashboard.
+    //
+    // Launched unconditionally once setup and auth pass. A prior heuristic skipped
+    // launch whenever `totalActivePRs === 0`, assuming that meant a genuine first
+    // run and deferring to the CLI's welcome flow. That gate also swallowed the
+    // dashboard in three legitimate cases: a misconfigured/stale `githubUsername`
+    // (Search API returns zero), transient GitHub API flakes (state still holds
+    // merged PRs but the live count is zero), and users genuinely between PRs.
+    // The dashboard's own empty-state UI renders "no PRs" cleanly, so always
+    // surfacing it is the right default.
     let dashboardUrl;
     let dashboardStatus;
-    if (daily.digest.summary.totalActivePRs > 0) {
-        try {
-            const spaResult = await launchDashboardServer();
-            if (spaResult) {
-                dashboardUrl = spaResult.url;
-                if (spaResult.alreadyRunning) {
-                    const refreshed = await triggerDashboardRefresh(spaResult.port);
-                    dashboardStatus = refreshed ? 'refreshed' : 'running';
-                }
-                else {
-                    dashboardStatus = 'opened';
-                }
-                // Always surface the dashboard: `open`/`xdg-open`/`start` focus an
-                // existing tab matching the URL instead of duplicating it, so this is
-                // safe whether the server was just started or was already running.
-                // Closes #830 properly. The original fix assumed "server running"
-                // implied "tab open", but the user can close the tab while the daemon
-                // keeps running, leaving subsequent /oss runs with no visible dashboard.
-                openInBrowser(spaResult.url);
+    let dashboardError;
+    try {
+        const spaResult = await launchDashboardServer();
+        if (spaResult) {
+            dashboardUrl = spaResult.url;
+            if (spaResult.alreadyRunning) {
+                const refreshed = await triggerDashboardRefresh(spaResult.port);
+                dashboardStatus = refreshed ? 'refreshed' : 'running';
             }
             else {
-                console.error('[STARTUP] Dashboard SPA assets not found. Build with: cd packages/dashboard && pnpm run build');
+                dashboardStatus = 'opened';
             }
+            // `open`/`xdg-open`/`start` focus an existing tab matching the URL
+            // instead of duplicating it, so this is safe whether the server was
+            // just started or was already running. Closes #830 properly — a user
+            // can close the dashboard tab while the daemon keeps running, leaving
+            // subsequent /oss runs with no visible dashboard if we didn't re-open.
+            openInBrowser(spaResult.url);
         }
-        catch (error) {
-            console.error('[STARTUP] SPA dashboard launch failed:', errorMessage(error));
+        else {
+            dashboardError = 'Dashboard SPA assets not found. Build with: cd packages/dashboard && pnpm run build';
+            console.error(`[STARTUP] ${dashboardError}`);
         }
     }
+    catch (error) {
+        dashboardError = `SPA dashboard launch failed: ${errorMessage(error)}`;
+        console.error(`[STARTUP] ${dashboardError}`);
+    }
     // Append dashboard status to brief summary
     if (dashboardStatus === 'opened') {
         daily.briefSummary += ' | Dashboard opened in browser';
@@ -272,6 +280,7 @@ export async function runStartup() {
         autoDetected,
         daily,
         dashboardUrl,
+        dashboardError,
         issueList,
     };
 }

package/dist/core/pr-monitor.d.ts

@@ -18,6 +18,8 @@ export { computeDisplayLabel } from './display-utils.js';
 export { classifyCICheck, classifyFailingChecks, getCIStatus } from './ci-analysis.js';
 export { isConditionalChecklistItem } from './checklist-analysis.js';
 export { determineStatus } from './status-determination.js';
+declare function isPlaceholderUsername(username: string): boolean;
+export { isPlaceholderUsername };
 /**
  * Check if a PR has a merge conflict based on GitHub's mergeable flag and mergeable_state.
  * Returns true when mergeable is explicitly false or the mergeable_state is 'dirty'.
@@ -34,10 +36,13 @@ export interface FetchPRsResult {
     prs: FetchedPR[];
     failures: PRCheckFailure[];
     /**
-     * Non-fatal warnings accumulated while fetching. Currently populated when
-     * the GitHub Search API's 1000-result ceiling truncates the user's PR
-     * list — callers (daily, dashboard) surface these so users know the data
-     * may be incomplete (#1057 M25).
+     * Non-fatal warnings accumulated while fetching. Populated by:
+     * - Placeholder auto-repair (stale/example `githubUsername` replaced with
+     *   the authenticated viewer's login before the search runs).
+     * - Post-fetch viewer-mismatch guardrail (configured username differs
+     *   from the authenticated viewer when the search returned zero PRs).
+     * - Search API 1000-result truncation (#1057 M25).
+     * Callers (daily, dashboard) surface these so users see the signal.
      */
     warnings?: string[];
 }

package/dist/core/pr-monitor.js

@@ -32,6 +32,29 @@ export { computeDisplayLabel } from './display-utils.js';
 export { classifyCICheck, classifyFailingChecks, getCIStatus } from './ci-analysis.js';
 export { isConditionalChecklistItem } from './checklist-analysis.js';
 export { determineStatus } from './status-determination.js';
+/**
+ * Known placeholder values that can end up in `config.githubUsername` from
+ * doc snippets, example configs, or aborted setup flows. When the configured
+ * username matches one of these, the PR fetch silently returns zero results
+ * and the dashboard looks like a fresh install. Detecting these lets us
+ * auto-repair the config from the authenticated viewer before fetching.
+ *
+ * Entries must be lowercase — `Lowercase<string>` on the source tuple makes
+ * a non-lowercase entry a compile error, keeping the case-insensitive lookup
+ * contract type-checked instead of comment-documented.
+ */
+const PLACEHOLDER_USERNAMES = [
+    'example-user',
+    'your-username',
+    'your-github-username',
+];
+const KNOWN_PLACEHOLDER_USERNAMES = new Set(PLACEHOLDER_USERNAMES);
+function isPlaceholderUsername(username) {
+    return KNOWN_PLACEHOLDER_USERNAMES.has(username.toLowerCase());
+}
+// Module-private on purpose: callers should only use the predicate so the
+// `.toLowerCase()` contract can't be bypassed by reading the set directly.
+export { isPlaceholderUsername };
 /**
  * Check if a PR has a merge conflict based on GitHub's mergeable flag and mergeable_state.
  * Returns true when mergeable is explicitly false or the mergeable_state is 'dirty'.
@@ -78,17 +101,71 @@ export class PRMonitor {
      * ```
      */
     async fetchUserOpenPRs() {
-        const config = this.stateManager.getState().config;
-        if (!config.githubUsername) {
+        const initialConfig = this.stateManager.getState().config;
+        if (!initialConfig.githubUsername) {
             throw new ConfigurationError('No GitHub username configured. Run setup first.');
         }
-        debug('pr-monitor', `Fetching open PRs for @${config.githubUsername}...`);
+        // Non-fatal warnings threaded into the result (#1057 M25). When the
+        // Search API's hard 1000-result ceiling truncates the user's PR list we
+        // previously silently dropped the overflow; now the caller can surface
+        // it so the daily digest doesn't quietly report a partial view.
+        const warnings = [];
+        // Username used for the search — mutated below if the pre-fetch placeholder
+        // repair fires. Writing to config is separate from rebinding this local.
+        let searchUsername = initialConfig.githubUsername;
+        // Proactive placeholder repair: if the configured username is a known
+        // placeholder (e.g. "example-user" carried over from docs or an aborted
+        // setup), cross-check against the authenticated viewer and persist the
+        // corrected name before fetching. Without this, the search silently
+        // returns zero results and the dashboard looks like a fresh install.
+        // Errors here are non-fatal; rate-limit/auth failures still abort so we
+        // don't mask a revoked token by downgrading to a no-op.
+        let didRepair = false;
+        if (isPlaceholderUsername(searchUsername)) {
+            try {
+                const { data: viewer } = await this.octokit.users.getAuthenticated();
+                const newLogin = viewer.login?.trim();
+                // Guard against an empty/whitespace viewer login (enterprise proxies,
+                // stubbed Octokit clients) and against the pathological case where the
+                // authenticated viewer's login is itself one of our placeholder strings
+                // — persisting either would swap one broken config for another.
+                if (!newLogin || isPlaceholderUsername(newLogin)) {
+                    const message = `Placeholder username "${searchUsername}" detected but authenticated viewer ` +
+                        `returned an unusable login (${JSON.stringify(viewer.login)}); skipping auto-repair.`;
+                    warnings.push(message);
+                    warn(MODULE, message);
+                }
+                else {
+                    this.stateManager.updateConfig({ githubUsername: newLogin });
+                    searchUsername = newLogin;
+                    didRepair = true;
+                    const message = `Configured GitHub username "${initialConfig.githubUsername}" looks like a placeholder. ` +
+                        `Auto-repaired to "${newLogin}" using the authenticated viewer.`;
+                    warnings.push(message);
+                    warn(MODULE, message);
+                }
+            }
+            catch (err) {
+                if (isRateLimitOrAuthError(err))
+                    throw err;
+                // Non-fatal viewer-lookup failures (5xx, network, unexpected shape):
+                // surface as a warning (not debug) so the daily digest shows that
+                // auto-repair was attempted and couldn't complete. Falls through to
+                // the normal fetch with the placeholder, which will then return zero
+                // results — the post-fetch guardrail skips its own getAuthenticated
+                // attempt since this one already failed the same way.
+                const message = `Could not auto-repair placeholder username "${searchUsername}": ${errorMessage(err)}`;
+                warnings.push(message);
+                warn(MODULE, message);
+            }
+        }
+        debug('pr-monitor', `Fetching open PRs for @${searchUsername}...`);
         // Search for all open PRs authored by the user with pagination
         const allItems = [];
         let page = 1;
         const perPage = 100;
         const firstPage = await this.octokit.search.issuesAndPullRequests({
-            q: `is:pr is:open is:public author:${config.githubUsername}`,
+            q: `is:pr is:open is:public author:${searchUsername}`,
             sort: 'updated',
             order: 'desc',
             per_page: perPage,
@@ -101,22 +178,17 @@ export class PRMonitor {
         const SEARCH_API_RESULT_CAP = 1000;
         const MAX_PAGES = Math.ceil(SEARCH_API_RESULT_CAP / perPage); // 10 pages at per_page=100
         const totalPages = Math.min(Math.ceil(totalCount / perPage), MAX_PAGES);
-        // Non-fatal warnings threaded into the result (#1057 M25). When the
-        // Search API's hard 1000-result ceiling truncates the user's PR list we
-        // previously silently dropped the overflow; now the caller can surface
-        // it so the daily digest doesn't quietly report a partial view.
-        const warnings = [];
         // Guardrail: if the Search API returned zero PRs, cross-check the
-        // configured username against the authenticated viewer. A real failure
-        // mode was a stale/placeholder username (e.g. "example-user") silently
-        // producing zero results with no error — the dashboard just showed
-        // "0 active PRs" and looked like a fresh install. getAuthenticated is
-        // advisory; a failure here never breaks the fetch.
-        if (totalCount === 0) {
+        // configured username against the authenticated viewer. This catches
+        // stale usernames (e.g. a renamed GitHub account) that are not in the
+        // known-placeholder set. Skipped when the pre-fetch repair already
+        // reconciled the two — no need to spend a second getAuthenticated call
+        // just to confirm a match we already established.
+        if (totalCount === 0 && !didRepair) {
             try {
                 const { data: viewer } = await this.octokit.users.getAuthenticated();
-                if (viewer.login.toLowerCase() !== config.githubUsername.toLowerCase()) {
-                    const message = `Configured GitHub username @${config.githubUsername} does not match ` +
+                if (viewer.login.toLowerCase() !== searchUsername.toLowerCase()) {
+                    const message = `Configured GitHub username @${searchUsername} does not match ` +
                         `authenticated user @${viewer.login}. Did you mean to run ` +
                         `\`oss-autopilot config username ${viewer.login}\`? Zero PRs returned.`;
                     warnings.push(message);
@@ -135,7 +207,7 @@ export class PRMonitor {
             }
         }
         if (totalCount > SEARCH_API_RESULT_CAP) {
-            warnings.push(`GitHub Search API returned ${totalCount} PRs for @${config.githubUsername}, ` +
+            warnings.push(`GitHub Search API returned ${totalCount} PRs for @${searchUsername}, ` +
                 `but results are capped at ${SEARCH_API_RESULT_CAP}. ` +
                 `Showing the ${SEARCH_API_RESULT_CAP} most recently updated PRs.`);
             warn(MODULE, warnings[warnings.length - 1]);
@@ -143,7 +215,7 @@ export class PRMonitor {
         while (page < totalPages) {
             page++;
             const nextPage = await this.octokit.search.issuesAndPullRequests({
-                q: `is:pr is:open is:public author:${config.githubUsername}`,
+                q: `is:pr is:open is:public author:${searchUsername}`,
                 sort: 'updated',
                 order: 'desc',
                 per_page: perPage,
@@ -163,7 +235,7 @@ export class PRMonitor {
                 warn('pr-monitor', `Skipping PR with unparseable URL: ${item.html_url}`);
                 return false;
             }
-            if (isOwnRepo(parsed.owner, config.githubUsername))
+            if (isOwnRepo(parsed.owner, searchUsername))
                 return false;
             return true;
         });

package/dist/formatters/json.d.ts

@@ -274,6 +274,13 @@ export interface StartupOutput {
     daily?: DailyOutput;
     /** URL of the interactive SPA dashboard server, when running (e.g., "http://localhost:3000") */
     dashboardUrl?: string;
+    /**
+     * Set when the dashboard launch or refresh failed (assets missing, port
+     * conflict, spawn error, etc.). The dashboard is always attempted, so JSON
+     * consumers — which previously saw only a missing `dashboardUrl` — now have
+     * a structured signal to surface or recover from the failure.
+     */
+    dashboardError?: string;
     issueList?: IssueListInfo;
 }
 /**

package/dist/formatters/json.js

@@ -70,6 +70,7 @@ export function toCompactStartupOutput(output) {
         ...rest,
         daily: daily ? toCompactDailyOutput(daily) : undefined,
         dashboardUrl: output.dashboardUrl,
+        dashboardError: output.dashboardError,
         issueList: output.issueList,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oss-autopilot/core",
-  "version": "1.17.1",
+  "version": "1.17.3",
   "description": "CLI and core library for managing open source contributions",
   "type": "module",
   "bin": {
@@ -18,6 +18,10 @@
     "./commands": {
       "import": "./dist/commands/index.js",
       "types": "./dist/commands/index.d.ts"
+    },
+    "./dashboard-schema": {
+      "import": "./dist/core/dashboard-data-schema.js",
+      "types": "./dist/core/dashboard-data-schema.d.ts"
     }
   },
   "files": [