@oss-autopilot/core 0.52.0 → 0.53.0

package/dist/cli.js

@@ -9,7 +9,7 @@
  * handlers so only the invoked command's dependencies are evaluated.
  */
 import { Command } from 'commander';
-import { getGitHubTokenAsync, enableDebug, debug, getCLIVersion } from './core/index.js';
+import { getGitHubTokenAsync, enableDebug, debug, getCLIVersion, stateFileExists } from './core/index.js';
 import { commands } from './cli-registry.js';
 const VERSION = getCLIVersion();
 const program = new Command();
@@ -51,5 +51,23 @@ program.hook('preAction', async (thisCommand, actionCommand) => {
         }
     }
 });
+// First-run detection: if no subcommand was provided and no state file exists,
+// show a quick-start guide and exit before Commander displays generic help.
+const userArgs = process.argv.slice(2);
+const hasSubcommand = userArgs.some((a) => !a.startsWith('-'));
+const hasHelpOrVersion = userArgs.some((a) => a === '--help' || a === '-h' || a === '--version' || a === '-V');
+if (!hasSubcommand && !hasHelpOrVersion && !stateFileExists()) {
+    console.log(`
+OSS Autopilot — AI copilot for open source contributions
+
+Looks like this is your first run! Quick start:
+  1. Initialize:   oss-autopilot init <github-username>
+  2. Find issues:  oss-autopilot search 10
+  3. Daily check:  oss-autopilot daily
+
+Run oss-autopilot --help for all commands.
+`);
+    process.exit(0);
+}
 // Parse and execute
 program.parse();

package/dist/core/github.d.ts

@@ -11,6 +11,11 @@ export interface RateLimitInfo {
     /** ISO timestamp when the rate limit window resets. */
     resetAt: string;
 }
+/** Throttle callbacks used by the Octokit client. Exported for testability. */
+export declare function getRateLimitCallbacks(): {
+    onRateLimit: (retryAfter: number, options: unknown, _octokit: unknown, retryCount: number) => boolean;
+    onSecondaryRateLimit: (retryAfter: number, options: unknown, _octokit: unknown, retryCount: number) => boolean;
+};
 export declare function getOctokit(token: string): Octokit;
 /**
  * Check the GitHub Search API rate limit quota.

package/dist/core/github.js

@@ -12,34 +12,39 @@ let _currentToken = null;
 function formatResetTime(date) {
     return date.toLocaleTimeString('en-US', { hour12: false });
 }
+/** Throttle callbacks used by the Octokit client. Exported for testability. */
+export function getRateLimitCallbacks() {
+    return {
+        onRateLimit: (retryAfter, options, _octokit, retryCount) => {
+            const opts = options;
+            const resetAt = new Date(Date.now() + retryAfter * 1000);
+            if (retryCount < 2) {
+                warn(MODULE, `Rate limit hit (retry ${retryCount + 1}/2, waiting ${retryAfter}s, resets at ${formatResetTime(resetAt)}) — ${opts.method} ${opts.url}`);
+                return true;
+            }
+            warn(MODULE, `Rate limit exceeded, not retrying — ${opts.method} ${opts.url} (resets at ${formatResetTime(resetAt)})`);
+            return false;
+        },
+        onSecondaryRateLimit: (retryAfter, options, _octokit, retryCount) => {
+            const opts = options;
+            const resetAt = new Date(Date.now() + retryAfter * 1000);
+            if (retryCount < 1) {
+                warn(MODULE, `Secondary rate limit hit (retry ${retryCount + 1}/1, waiting ${retryAfter}s, resets at ${formatResetTime(resetAt)}) — ${opts.method} ${opts.url}`);
+                return true;
+            }
+            warn(MODULE, `Secondary rate limit exceeded, not retrying — ${opts.method} ${opts.url} (resets at ${formatResetTime(resetAt)})`);
+            return false;
+        },
+    };
+}
 export function getOctokit(token) {
     // Return cached instance only if token matches
     if (_octokit && _currentToken === token)
         return _octokit;
+    const callbacks = getRateLimitCallbacks();
     _octokit = new ThrottledOctokit({
         auth: token,
-        throttle: {
-            onRateLimit: (retryAfter, options, _octokit, retryCount) => {
-                const opts = options;
-                const resetAt = new Date(Date.now() + retryAfter * 1000);
-                if (retryCount < 2) {
-                    warn(MODULE, `Rate limit hit (retry ${retryCount + 1}/2, waiting ${retryAfter}s, resets at ${formatResetTime(resetAt)}) — ${opts.method} ${opts.url}`);
-                    return true;
-                }
-                warn(MODULE, `Rate limit exceeded, not retrying — ${opts.method} ${opts.url} (resets at ${formatResetTime(resetAt)})`);
-                return false;
-            },
-            onSecondaryRateLimit: (retryAfter, options, _octokit, retryCount) => {
-                const opts = options;
-                const resetAt = new Date(Date.now() + retryAfter * 1000);
-                if (retryCount < 1) {
-                    warn(MODULE, `Secondary rate limit hit (retry ${retryCount + 1}/1, waiting ${retryAfter}s, resets at ${formatResetTime(resetAt)}) — ${opts.method} ${opts.url}`);
-                    return true;
-                }
-                warn(MODULE, `Secondary rate limit exceeded, not retrying — ${opts.method} ${opts.url} (resets at ${formatResetTime(resetAt)})`);
-                return false;
-            },
-        },
+        throttle: callbacks,
     });
     _currentToken = token;
     return _octokit;

package/dist/core/index.d.ts

@@ -8,7 +8,7 @@ export { IssueDiscovery, type IssueCandidate, type SearchPriority, isDocOnlyIssu
 export { IssueConversationMonitor } from './issue-conversation.js';
 export { isBotAuthor, isAcknowledgmentComment } from './comment-utils.js';
 export { getOctokit, checkRateLimit, type RateLimitInfo } from './github.js';
-export { parseGitHubUrl, daysBetween, splitRepo, isOwnRepo, getCLIVersion, getDataDir, getStatePath, getBackupDir, getCacheDir, formatRelativeTime, byDateDescending, getGitHubToken, getGitHubTokenAsync, requireGitHubToken, resetGitHubTokenCache, detectGitHubUsername, DEFAULT_CONCURRENCY, } from './utils.js';
+export { parseGitHubUrl, daysBetween, splitRepo, isOwnRepo, getCLIVersion, getDataDir, getStatePath, getBackupDir, getCacheDir, formatRelativeTime, byDateDescending, getGitHubToken, getGitHubTokenAsync, requireGitHubToken, resetGitHubTokenCache, detectGitHubUsername, stateFileExists, DEFAULT_CONCURRENCY, } from './utils.js';
 export { OssAutopilotError, ConfigurationError, ValidationError, errorMessage, getHttpStatusCode, isRateLimitError, isRateLimitOrAuthError, } from './errors.js';
 export { enableDebug, isDebugEnabled, debug, info, warn, timed } from './logger.js';
 export { HttpCache, getHttpCache, cachedRequest, type CacheEntry } from './http-cache.js';

package/dist/core/index.js

@@ -8,7 +8,7 @@ export { IssueDiscovery, isDocOnlyIssue, applyPerRepoCap, DOC_ONLY_LABELS, } fro
 export { IssueConversationMonitor } from './issue-conversation.js';
 export { isBotAuthor, isAcknowledgmentComment } from './comment-utils.js';
 export { getOctokit, checkRateLimit } from './github.js';
-export { parseGitHubUrl, daysBetween, splitRepo, isOwnRepo, getCLIVersion, getDataDir, getStatePath, getBackupDir, getCacheDir, formatRelativeTime, byDateDescending, getGitHubToken, getGitHubTokenAsync, requireGitHubToken, resetGitHubTokenCache, detectGitHubUsername, DEFAULT_CONCURRENCY, } from './utils.js';
+export { parseGitHubUrl, daysBetween, splitRepo, isOwnRepo, getCLIVersion, getDataDir, getStatePath, getBackupDir, getCacheDir, formatRelativeTime, byDateDescending, getGitHubToken, getGitHubTokenAsync, requireGitHubToken, resetGitHubTokenCache, detectGitHubUsername, stateFileExists, DEFAULT_CONCURRENCY, } from './utils.js';
 export { OssAutopilotError, ConfigurationError, ValidationError, errorMessage, getHttpStatusCode, isRateLimitError, isRateLimitOrAuthError, } from './errors.js';
 export { enableDebug, isDebugEnabled, debug, info, warn, timed } from './logger.js';
 export { HttpCache, getHttpCache, cachedRequest } from './http-cache.js';

package/dist/core/utils.d.ts

@@ -246,6 +246,12 @@ export declare function resetGitHubTokenCache(): void;
  * }
  */
 export declare function getGitHubTokenAsync(): Promise<string | null>;
+/**
+ * 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 declare function stateFileExists(): boolean;
 /**
  * Detect the authenticated GitHub username via the `gh` CLI.
  *

package/dist/core/utils.js

@@ -439,6 +439,15 @@ export async function getGitHubTokenAsync() {
  * (but not consecutive ones and not at the end), and be 1-39 characters.
  */
 const GITHUB_USERNAME_RE = /^[a-zA-Z0-9](?:[a-zA-Z0-9]|-(?=[a-zA-Z0-9])){0,38}$/;
+/**
+ * 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);
+}
 /**
  * Detect the authenticated GitHub username via the `gh` CLI.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oss-autopilot/core",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "CLI and core library for managing open source contributions",
   "type": "module",
   "bin": {
@@ -21,7 +21,9 @@
     }
   },
   "files": [
-    "dist/"
+    "dist/",
+    "!dist/**/*.map",
+    "!dist/core/test-utils.*"
   ],
   "keywords": [
     "open-source",