@oss-autopilot/core 1.17.4 → 3.0.0

package/dist/core/paths.js

@@ -0,0 +1,106 @@
+/**
+ * Filesystem path helpers for the oss-autopilot user data directory.
+ *
+ * All paths root at `~/.oss-autopilot/`, and every getter that returns a
+ * directory path implicitly creates it (with mode 0o700) if missing.
+ *
+ * Extracted from utils.ts under #1116.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+/**
+ * Returns the oss-autopilot data directory path, creating it if it does not exist.
+ *
+ * The directory is located at `~/.oss-autopilot/` and serves as the root for
+ * all persisted user data (state, backups, cache).
+ *
+ * @returns Absolute path to the data directory (e.g., `/Users/you/.oss-autopilot`)
+ *
+ * @example
+ * const dir = getDataDir();
+ * // "/Users/you/.oss-autopilot"
+ */
+export function getDataDir() {
+    const dir = path.join(os.homedir(), '.oss-autopilot');
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    return dir;
+}
+/**
+ * Returns the path to the state file (`~/.oss-autopilot/state.json`).
+ *
+ * Implicitly creates the data directory via {@link getDataDir} if it does not exist.
+ */
+export function getStatePath() {
+    return path.join(getDataDir(), 'state.json');
+}
+/**
+ * Returns the backup directory path, creating it if it does not exist.
+ *
+ * Located at `~/.oss-autopilot/backups/`. Used for automatic state backups
+ * before each write operation.
+ */
+export function getBackupDir() {
+    const dir = path.join(getDataDir(), 'backups');
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    return dir;
+}
+/**
+ * Returns the HTTP cache directory path, creating it if it does not exist.
+ *
+ * Located at `~/.oss-autopilot/cache/`. Used by HttpCache to store
+ * ETag-based response caches for GitHub API endpoints.
+ */
+export function getCacheDir() {
+    const dir = path.join(getDataDir(), 'cache');
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    return dir;
+}
+/**
+ * Returns the path to the local Gist ID file (`~/.oss-autopilot/gist-id`).
+ *
+ * Stores the GitHub Gist ID used by the Gist-based persistence layer,
+ * avoiding a search-by-description API call on every session.
+ */
+export function getGistIdPath() {
+    return path.join(getDataDir(), 'gist-id');
+}
+/**
+ * Returns the path to the local state cache file (`~/.oss-autopilot/state-cache.json`).
+ *
+ * A write-through cache of the Gist-hosted state, used as a fallback when
+ * the GitHub API is unreachable (degraded mode).
+ */
+export function getStateCachePath() {
+    return path.join(getDataDir(), 'state-cache.json');
+}
+/**
+ * Check whether the state file exists without creating the data directory.
+ *
+ * Used for first-run detection in the CLI — we don't want to create
+ * `~/.oss-autopilot/` just to check if the user has ever run the tool.
+ */
+export function stateFileExists() {
+    const stateFile = path.join(os.homedir(), '.oss-autopilot', 'state.json');
+    return fs.existsSync(stateFile);
+}
+/**
+ * Read the CLI package version from package.json relative to the running CLI bundle.
+ * Resolves `../package.json` from `process.argv[1]` (the bundle entry point).
+ * Falls back to '0.0.0' if the file is unreadable.
+ */
+export function getCLIVersion() {
+    try {
+        const pkgPath = path.join(path.dirname(process.argv[1]), '..', 'package.json');
+        return JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version;
+    }
+    catch {
+        return '0.0.0';
+    }
+}

package/dist/core/pr-monitor.js

@@ -14,7 +14,9 @@
  */
 import { getOctokit } from './github.js';
 import { getStateManager } from './state.js';
-import { daysBetween, parseGitHubUrl, extractOwnerRepo, isOwnRepo, DEFAULT_CONCURRENCY } from './utils.js';
+import { daysBetween } from './dates.js';
+import { parseGitHubUrl, extractOwnerRepo, isOwnRepo } from './urls.js';
+import { DEFAULT_CONCURRENCY } from './concurrency.js';
 import { determineStatus } from './status-determination.js';
 import { runWorkerPool } from './concurrency.js';
 import { ConfigurationError, ValidationError, errorMessage, getHttpStatusCode, isRateLimitOrAuthError, } from './errors.js';

package/dist/core/repo-score-manager.js

@@ -9,7 +9,7 @@
  */
 import { isBelowMinStars } from './types.js';
 import { debug, warn } from './logger.js';
-import { parseGitHubUrl } from './utils.js';
+import { parseGitHubUrl } from './urls.js';
 const MODULE = 'scoring';
 // ── Scoring constants (#1054) ─────────────────────────────────────────
 // Previously inlined as magic numbers in `calculateScore`. Extracted with

package/dist/core/state-persistence.js

@@ -6,7 +6,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { AgentStateSchema } from './state-schema.js';
-import { getStatePath, getBackupDir, getDataDir } from './utils.js';
+import { getStatePath, getBackupDir, getDataDir } from './paths.js';
 import { errorMessage, ConcurrencyError } from './errors.js';
 import { debug, warn } from './logger.js';
 const MODULE = 'state';

package/dist/core/state.d.ts

@@ -148,18 +148,32 @@ export declare class StateManager {
     getMergedPRs(): StoredMergedPR[];
     /**
      * Add merged PRs to storage, deduplicating by URL.
+     * Entries with URLs that fail {@link parseGitHubUrl} are dropped before
+     * persistence (read-side filters in dashboard-data already skip them, but
+     * this prevents the bad data from reaching disk in the first place).
      * @param prs - Merged PRs to add (duplicates by URL are ignored)
+     * @returns count of entries added vs. dropped (invalid URL)
      */
-    addMergedPRs(prs: StoredMergedPR[]): void;
+    addMergedPRs(prs: StoredMergedPR[]): {
+        added: number;
+        dropped: number;
+    };
     /** Returns the most recent merge date, used as a watermark for incremental fetching. */
     getMergedPRWatermark(): string | undefined;
     /** Returns all stored closed-without-merge PRs (sorted by close date descending via addClosedPRs). */
     getClosedPRs(): StoredClosedPR[];
     /**
      * Add closed PRs to storage, deduplicating by URL.
+     * Entries with URLs that fail {@link parseGitHubUrl} are dropped before
+     * persistence (read-side filters in dashboard-data already skip them, but
+     * this prevents the bad data from reaching disk in the first place).
      * @param prs - Closed PRs to add (duplicates by URL are ignored)
+     * @returns count of entries added vs. dropped (invalid URL)
      */
-    addClosedPRs(prs: StoredClosedPR[]): void;
+    addClosedPRs(prs: StoredClosedPR[]): {
+        added: number;
+        dropped: number;
+    };
     /** Returns the most recent close date, used as a watermark for incremental fetching. */
     getClosedPRWatermark(): string | undefined;
     /**

package/dist/core/state.js

@@ -10,9 +10,28 @@ import * as repoScoring from './repo-score-manager.js';
 import { debug, warn } from './logger.js';
 import { errorMessage, ConfigurationError, ConcurrencyError } from './errors.js';
 import { GistStateStore } from './gist-state-store.js';
-import { getStatePath, getStateCachePath } from './utils.js';
+import { getStatePath, getStateCachePath } from './paths.js';
+import { parseGitHubUrl } from './urls.js';
 export { acquireLock, releaseLock, atomicWriteFileSync } from './state-persistence.js';
 const MODULE = 'state';
+/**
+ * Validate stored-PR URL shape before persistence (mirror of the read-side
+ * filter in dashboard-data#storedToMergedPRs/storedToClosedPRs). Bad URLs are
+ * logged at warn level so operators see the drop in the daily output.
+ */
+function filterValidUrlEntries(entries, kind) {
+    const valid = [];
+    let dropped = 0;
+    for (const entry of entries) {
+        if (parseGitHubUrl(entry.url) === null) {
+            warn(MODULE, `Dropping ${kind} PR with invalid URL: ${entry.url}`);
+            dropped++;
+            continue;
+        }
+        valid.push(entry);
+    }
+    return { valid, dropped };
+}
 /**
  * Push state to the backing Gist when Gist mode is active. Best-effort:
  * network/auth failures are logged via `warn()` but never propagated —
@@ -352,21 +371,29 @@ export class StateManager {
     }
     /**
      * Add merged PRs to storage, deduplicating by URL.
+     * Entries with URLs that fail {@link parseGitHubUrl} are dropped before
+     * persistence (read-side filters in dashboard-data already skip them, but
+     * this prevents the bad data from reaching disk in the first place).
      * @param prs - Merged PRs to add (duplicates by URL are ignored)
+     * @returns count of entries added vs. dropped (invalid URL)
      */
     addMergedPRs(prs) {
         if (prs.length === 0)
-            return;
+            return { added: 0, dropped: 0 };
+        const { valid, dropped } = filterValidUrlEntries(prs, 'merged');
+        if (valid.length === 0)
+            return { added: 0, dropped };
         if (!this.state.mergedPRs)
             this.state.mergedPRs = [];
         const existingUrls = new Set(this.state.mergedPRs.map((pr) => pr.url));
-        const newPRs = prs.filter((pr) => !existingUrls.has(pr.url));
+        const newPRs = valid.filter((pr) => !existingUrls.has(pr.url));
         if (newPRs.length === 0)
-            return;
+            return { added: 0, dropped };
         this.state.mergedPRs.push(...newPRs);
         this.state.mergedPRs.sort((a, b) => b.mergedAt.localeCompare(a.mergedAt));
         debug(MODULE, `Added ${newPRs.length} merged PRs (total: ${this.state.mergedPRs.length})`);
         this.autoSave();
+        return { added: newPRs.length, dropped };
     }
     /** Returns the most recent merge date, used as a watermark for incremental fetching. */
     getMergedPRWatermark() {
@@ -379,21 +406,29 @@ export class StateManager {
     }
     /**
      * Add closed PRs to storage, deduplicating by URL.
+     * Entries with URLs that fail {@link parseGitHubUrl} are dropped before
+     * persistence (read-side filters in dashboard-data already skip them, but
+     * this prevents the bad data from reaching disk in the first place).
      * @param prs - Closed PRs to add (duplicates by URL are ignored)
+     * @returns count of entries added vs. dropped (invalid URL)
      */
     addClosedPRs(prs) {
         if (prs.length === 0)
-            return;
+            return { added: 0, dropped: 0 };
+        const { valid, dropped } = filterValidUrlEntries(prs, 'closed');
+        if (valid.length === 0)
+            return { added: 0, dropped };
         if (!this.state.closedPRs)
             this.state.closedPRs = [];
         const existingUrls = new Set(this.state.closedPRs.map((pr) => pr.url));
-        const newPRs = prs.filter((pr) => !existingUrls.has(pr.url));
+        const newPRs = valid.filter((pr) => !existingUrls.has(pr.url));
         if (newPRs.length === 0)
-            return;
+            return { added: 0, dropped };
         this.state.closedPRs.push(...newPRs);
         this.state.closedPRs.sort((a, b) => b.closedAt.localeCompare(a.closedAt));
         debug(MODULE, `Added ${newPRs.length} closed PRs (total: ${this.state.closedPRs.length})`);
         this.autoSave();
+        return { added: newPRs.length, dropped };
     }
     /** Returns the most recent close date, used as a watermark for incremental fetching. */
     getClosedPRWatermark() {

package/dist/core/types.d.ts

@@ -251,3 +251,60 @@ export interface IssueCandidate {
     viabilityScore: number;
     searchPriority: SearchPriority;
 }
+export interface CapacityAssessment {
+    hasCapacity: boolean;
+    activePRCount: number;
+    maxActivePRs: number;
+    shelvedPRCount: number;
+    criticalIssueCount: number;
+    reason: string;
+}
+export type ActionableIssueType = 'ci_failing' | 'merge_conflict' | 'needs_response' | 'needs_changes' | 'incomplete_checklist';
+export interface ActionableIssue {
+    type: ActionableIssueType;
+    pr: FetchedPR;
+    label: string;
+    /** True if the PR was created after the last daily digest (first time seen). */
+    isNewContribution: boolean;
+}
+/**
+ * Compact version of ActionableIssue for JSON output.
+ * References the PR by URL instead of embedding the full object,
+ * since the full PR is already available in digest.openPRs.
+ */
+export interface CompactActionableIssue {
+    type: ActionableIssueType;
+    prUrl: string;
+    label: string;
+    /** True if the PR was created after the last daily digest (first time seen). */
+    isNewContribution: boolean;
+}
+/**
+ * A single action menu item pre-computed by the CLI.
+ * The orchestration layer can use these directly in AskUserQuestion prompts.
+ */
+export interface ActionMenuItem {
+    /** Stable identifier for routing (e.g., "address_all", "search", "done"). */
+    key: string;
+    /** Display text for the option (e.g., "Work through all 3 issues (Recommended)"). */
+    label: string;
+    /** Explanation shown below the label. */
+    description: string;
+    /** Present when the action would exceed the user's PR capacity limit (#765). */
+    capacityWarning?: string;
+}
+/**
+ * Pre-computed action menu for the orchestration layer.
+ */
+export interface ActionMenu {
+    /** Ordered list of menu items. */
+    items: ActionMenuItem[];
+    /** Context flags for the orchestration layer to decide on issue-list options. */
+    context: {
+        hasActionableIssues: boolean;
+        actionableCount: number;
+        hasCapacity: boolean;
+        hasIssueResponses: boolean;
+        issueResponseCount: number;
+    };
+}

package/dist/core/urls.d.ts

@@ -0,0 +1,63 @@
+/**
+ * GitHub URL parsing + owner/repo helpers.
+ *
+ * All functions enforce an `https://github.com/` prefix and validate
+ * owner/repo characters. Extracted from utils.ts under #1116.
+ */
+/**
+ * Represents a parsed GitHub pull request or issue URL.
+ *
+ * @property owner - The repository owner (e.g., `"facebook"`)
+ * @property repo - The repository name (e.g., `"react"`)
+ * @property number - The PR or issue number
+ * @property type - Whether the URL points to a pull request or an issue
+ */
+export interface ParsedGitHubUrl {
+    owner: string;
+    repo: string;
+    number: number;
+    type: 'pull' | 'issues';
+}
+/**
+ * Parses a GitHub pull request or issue URL into its components.
+ *
+ * Only accepts HTTPS GitHub URLs (`https://github.com/...`). Returns `null` for
+ * invalid URLs, non-GitHub URLs, or URLs with invalid owner/repo characters.
+ *
+ * @example
+ * parseGitHubUrl('https://github.com/facebook/react/pull/123')
+ * // { owner: "facebook", repo: "react", number: 123, type: "pull" }
+ *
+ * @example
+ * parseGitHubUrl('https://example.com/not-github')
+ * // null
+ */
+export declare function parseGitHubUrl(url: string): ParsedGitHubUrl | null;
+/**
+ * Extracts the owner and repo from a GitHub web URL
+ * (e.g. `https://github.com/owner/repo/pull/42`, `https://github.com/owner/repo/`).
+ *
+ * Unlike {@link parseGitHubUrl}, this does **not** require a PR or issue number.
+ *
+ * @example
+ * extractOwnerRepo('https://github.com/vercel/next.js/')
+ * // { owner: "vercel", repo: "next.js" }
+ */
+export declare function extractOwnerRepo(url: string): {
+    owner: string;
+    repo: string;
+} | null;
+/**
+ * Splits an `"owner/repo"` string into its owner and repo components.
+ *
+ * @throws {Error} If the input is not in the form `"owner/repo"`.
+ */
+export declare function splitRepo(repoFullName: string): {
+    owner: string;
+    repo: string;
+};
+/**
+ * Case-insensitive check whether a repo owner matches the given GitHub username.
+ * Used to skip a user's own repos (PRs to your own repos aren't OSS contributions).
+ */
+export declare function isOwnRepo(owner: string, username: string): boolean;

package/dist/core/urls.js

@@ -0,0 +1,101 @@
+/**
+ * GitHub URL parsing + owner/repo helpers.
+ *
+ * All functions enforce an `https://github.com/` prefix and validate
+ * owner/repo characters. Extracted from utils.ts under #1116.
+ */
+// Validation patterns for GitHub owner and repo names
+const OWNER_PATTERN = /^[a-zA-Z0-9_-]+$/;
+const REPO_PATTERN = /^[a-zA-Z0-9_.-]+$/;
+function isValidOwnerRepo(owner, repo) {
+    return OWNER_PATTERN.test(owner) && REPO_PATTERN.test(repo);
+}
+/**
+ * Parses a GitHub pull request or issue URL into its components.
+ *
+ * Only accepts HTTPS GitHub URLs (`https://github.com/...`). Returns `null` for
+ * invalid URLs, non-GitHub URLs, or URLs with invalid owner/repo characters.
+ *
+ * @example
+ * parseGitHubUrl('https://github.com/facebook/react/pull/123')
+ * // { owner: "facebook", repo: "react", number: 123, type: "pull" }
+ *
+ * @example
+ * parseGitHubUrl('https://example.com/not-github')
+ * // null
+ */
+export function parseGitHubUrl(url) {
+    if (!url.startsWith('https://github.com/')) {
+        return null;
+    }
+    const prMatch = url.match(/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/);
+    if (prMatch) {
+        const owner = prMatch[1];
+        const repo = prMatch[2];
+        if (!isValidOwnerRepo(owner, repo)) {
+            return null;
+        }
+        return {
+            owner,
+            repo,
+            number: parseInt(prMatch[3], 10),
+            type: 'pull',
+        };
+    }
+    const issueMatch = url.match(/github\.com\/([^/]+)\/([^/]+)\/issues\/(\d+)/);
+    if (issueMatch) {
+        const owner = issueMatch[1];
+        const repo = issueMatch[2];
+        if (!isValidOwnerRepo(owner, repo)) {
+            return null;
+        }
+        return {
+            owner,
+            repo,
+            number: parseInt(issueMatch[3], 10),
+            type: 'issues',
+        };
+    }
+    return null;
+}
+/**
+ * Extracts the owner and repo from a GitHub web URL
+ * (e.g. `https://github.com/owner/repo/pull/42`, `https://github.com/owner/repo/`).
+ *
+ * Unlike {@link parseGitHubUrl}, this does **not** require a PR or issue number.
+ *
+ * @example
+ * extractOwnerRepo('https://github.com/vercel/next.js/')
+ * // { owner: "vercel", repo: "next.js" }
+ */
+export function extractOwnerRepo(url) {
+    if (!url.startsWith('https://github.com/'))
+        return null;
+    const match = url.match(/github\.com\/([^/]+)\/([^/]+)/);
+    if (!match)
+        return null;
+    const owner = match[1];
+    const repo = match[2];
+    if (!isValidOwnerRepo(owner, repo))
+        return null;
+    return { owner, repo };
+}
+/**
+ * Splits an `"owner/repo"` string into its owner and repo components.
+ *
+ * @throws {Error} If the input is not in the form `"owner/repo"`.
+ */
+export function splitRepo(repoFullName) {
+    const [owner, repo] = repoFullName.split('/');
+    if (!owner || !repo) {
+        throw new Error(`Invalid repo format: expected "owner/repo", got "${repoFullName}"`);
+    }
+    return { owner, repo };
+}
+/**
+ * Case-insensitive check whether a repo owner matches the given GitHub username.
+ * Used to skip a user's own repos (PRs to your own repos aren't OSS contributions).
+ */
+export function isOwnRepo(owner, username) {
+    return owner.toLowerCase() === username.toLowerCase();
+}