@oss-autopilot/core 1.17.4 → 3.0.0

package/dist/core/dates.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Date math + relative-time formatting helpers.
+ * Extracted from utils.ts under #1116.
+ */
+/**
+ * Calculates the number of whole days between two dates, clamped to zero.
+ *
+ * Returns `0` if `from` is after `to` — reversed ranges and clock-skew do not
+ * produce negative values. Partial days are truncated (e.g., 1.9 days -> 1).
+ *
+ * @example
+ * daysBetween(new Date('2024-01-01'), new Date('2024-01-10'))
+ * // 9
+ */
+export declare function daysBetween(from: Date, to?: Date): number;
+/**
+ * Formats a timestamp as a human-readable relative time string.
+ *
+ * Returns minutes for < 1 hour, hours for < 1 day, days for < 30 days,
+ * and a locale-formatted date string for anything older.
+ *
+ * @example
+ * formatRelativeTime('2024-01-20T10:00:00Z')
+ * // "5d ago" (if called on Jan 25)
+ */
+export declare function formatRelativeTime(dateStr: string): string;
+/**
+ * Creates a descending date comparator function for use with `Array.prototype.sort()`.
+ *
+ * Items with `null` or `undefined` dates are treated as epoch (sorted last).
+ *
+ * @example
+ * const prs = [{ createdAt: '2024-01-01' }, { createdAt: '2024-06-15' }];
+ * prs.sort(byDateDescending(pr => pr.createdAt));
+ * // [{ createdAt: '2024-06-15' }, { createdAt: '2024-01-01' }]
+ */
+export declare function byDateDescending<T>(getDate: (item: T) => string | number | null | undefined): (a: T, b: T) => number;

package/dist/core/dates.js

@@ -0,0 +1,60 @@
+/**
+ * Date math + relative-time formatting helpers.
+ * Extracted from utils.ts under #1116.
+ */
+/**
+ * Calculates the number of whole days between two dates, clamped to zero.
+ *
+ * Returns `0` if `from` is after `to` — reversed ranges and clock-skew do not
+ * produce negative values. Partial days are truncated (e.g., 1.9 days -> 1).
+ *
+ * @example
+ * daysBetween(new Date('2024-01-01'), new Date('2024-01-10'))
+ * // 9
+ */
+export function daysBetween(from, to = new Date()) {
+    return Math.max(0, Math.floor((to.getTime() - from.getTime()) / (1000 * 60 * 60 * 24)));
+}
+/**
+ * Formats a timestamp as a human-readable relative time string.
+ *
+ * Returns minutes for < 1 hour, hours for < 1 day, days for < 30 days,
+ * and a locale-formatted date string for anything older.
+ *
+ * @example
+ * formatRelativeTime('2024-01-20T10:00:00Z')
+ * // "5d ago" (if called on Jan 25)
+ */
+export function formatRelativeTime(dateStr) {
+    const date = new Date(dateStr);
+    const diffMs = Date.now() - date.getTime();
+    if (diffMs < 0)
+        return 'just now';
+    const diffMins = Math.floor(diffMs / 60000);
+    const diffHours = Math.floor(diffMs / 3600000);
+    const diffDays = Math.floor(diffMs / 86400000);
+    if (diffMins < 60)
+        return `${diffMins}m ago`;
+    if (diffHours < 24)
+        return `${diffHours}h ago`;
+    if (diffDays < 30)
+        return `${diffDays}d ago`;
+    return date.toLocaleDateString();
+}
+/**
+ * Creates a descending date comparator function for use with `Array.prototype.sort()`.
+ *
+ * Items with `null` or `undefined` dates are treated as epoch (sorted last).
+ *
+ * @example
+ * const prs = [{ createdAt: '2024-01-01' }, { createdAt: '2024-06-15' }];
+ * prs.sort(byDateDescending(pr => pr.createdAt));
+ * // [{ createdAt: '2024-06-15' }, { createdAt: '2024-01-01' }]
+ */
+export function byDateDescending(getDate) {
+    return (a, b) => {
+        const dateA = new Date(getDate(a) || 0).getTime();
+        const dateB = new Date(getDate(b) || 0).getTime();
+        return dateB - dateA;
+    };
+}

package/dist/core/errors.d.ts

@@ -46,6 +46,20 @@ export declare class ConcurrencyError extends OssAutopilotError {
     readonly actualMtimeMs: number;
     constructor(expectedMtimeMs: number, actualMtimeMs: number);
 }
+/**
+ * Thrown when a Gist push collides with a concurrent write from another
+ * machine and the in-flight merge attempt also lost the race (#1115).
+ *
+ * Carries the ETag we tried to write against (`expectedEtag`) and the
+ * ETag we observed during the merge refetch (`remoteEtag`) so callers /
+ * tests can assert on the precise mismatch. The message is phrased for
+ * end-users; `state-sync` retries from a fresh fetch.
+ */
+export declare class GistConcurrencyError extends OssAutopilotError {
+    readonly expectedEtag: string | null;
+    readonly remoteEtag: string | null;
+    constructor(expectedEtag: string | null, remoteEtag: string | null);
+}
 /**
  * Extract a human-readable message from an unknown error value.
  */

package/dist/core/errors.js

@@ -69,6 +69,26 @@ export class ConcurrencyError extends OssAutopilotError {
         this.name = 'ConcurrencyError';
     }
 }
+/**
+ * Thrown when a Gist push collides with a concurrent write from another
+ * machine and the in-flight merge attempt also lost the race (#1115).
+ *
+ * Carries the ETag we tried to write against (`expectedEtag`) and the
+ * ETag we observed during the merge refetch (`remoteEtag`) so callers /
+ * tests can assert on the precise mismatch. The message is phrased for
+ * end-users; `state-sync` retries from a fresh fetch.
+ */
+export class GistConcurrencyError extends OssAutopilotError {
+    expectedEtag;
+    remoteEtag;
+    constructor(expectedEtag, remoteEtag) {
+        super('Another machine pushed to the state Gist while this push was in flight, and the merge attempt also collided. ' +
+            'Re-run `oss-autopilot state --sync` to retry — your local mutations are still in memory.', 'CONCURRENCY_ERROR');
+        this.expectedEtag = expectedEtag;
+        this.remoteEtag = remoteEtag;
+        this.name = 'GistConcurrencyError';
+    }
+}
 /**
  * Extract a human-readable message from an unknown error value.
  */
@@ -148,6 +168,8 @@ export function resolveErrorCode(err) {
         return 'VALIDATION';
     if (err instanceof ConcurrencyError)
         return 'CONCURRENCY';
+    if (err instanceof GistConcurrencyError)
+        return 'CONCURRENCY';
     // Check HTTP status codes (Octokit errors)
     const status = getHttpStatusCode(err);
     if (status === 401)

package/dist/core/gist-state-store.d.ts

@@ -13,6 +13,23 @@
  *  5. If not found anywhere, create a new private Gist with seed files and store the ID
  *  6. Cache all Gist file contents in memory for session-scoped reads
  *  7. Write state to a local cache file for fallback
+ *
+ * Concurrency model (#1115):
+ *
+ *  Each fetch captures the response's `ETag` and stores it as
+ *  `lastFetchedEtag`. The next `push()` sends that ETag back as
+ *  `If-Match` so the GitHub Gist API rejects the write with 412 Precondition
+ *  Failed if another machine pushed in the interval.
+ *
+ *  On 412, the store attempts a single merge: it re-fetches the Gist
+ *  (refreshing the ETag), re-applies the in-memory dirty content on top of
+ *  the now-current remote state, and pushes once more. If that second push
+ *  also returns 412, `push()` throws {@link GistConcurrencyError} — local
+ *  mutations stay in memory so the caller can decide whether to refresh and
+ *  retry. The merge step is intentionally cheap (state is a single JSON
+ *  blob) and treats local dirty changes as authoritative for conflict
+ *  cells, which matches the "last-write-wins by intent" model the rest of
+ *  oss-autopilot already assumes for state.json.
  */
 import { AgentState } from './types.js';
 /** Well-known Gist description used for search-based discovery. */
@@ -30,6 +47,11 @@ export interface BootstrapResult {
 /**
  * Minimal Octokit-shaped interface for the Gist API methods we use.
  * Accepts the real ThrottledOctokit or a plain mock object in tests.
+ *
+ * Responses include the optional `headers` envelope (ETag-based concurrency,
+ * #1115). Tests that don't care about ETags can omit the headers field — the
+ * code path treats a missing ETag as "no concurrency check available, fall
+ * back to last-write-wins".
  */
 export interface OctokitLike {
     gists: {
@@ -37,6 +59,7 @@ export interface OctokitLike {
             gist_id: string;
         }) => Promise<{
             data: GistResponseData;
+            headers?: Record<string, string | undefined>;
         }>;
         list: (params: {
             per_page: number;
@@ -52,14 +75,17 @@ export interface OctokitLike {
             }>;
         }) => Promise<{
             data: GistResponseData;
+            headers?: Record<string, string | undefined>;
         }>;
         update: (params: {
             gist_id: string;
             files: Record<string, {
                 content: string;
             }>;
+            headers?: Record<string, string>;
         }) => Promise<{
             data: GistResponseData;
+            headers?: Record<string, string | undefined>;
         }>;
     };
 }
@@ -84,6 +110,14 @@ export declare class GistStateStore {
     private gistId;
     readonly cachedFiles: Map<string, string>;
     readonly dirtyFiles: Set<string>;
+    /**
+     * ETag captured from the most recent successful Gist fetch (#1115).
+     * Sent back as `If-Match` on `update` so concurrent writes from another
+     * machine surface as 412 Precondition Failed instead of silently winning
+     * the last-write-wins race. `null` when the SDK didn't surface the header
+     * (e.g. test mocks without headers) — in that case we skip the check.
+     */
+    private lastFetchedEtag;
     private readonly octokit;
     private lastRefreshAt;
     private static readonly REFRESH_THROTTLE_MS;
@@ -130,10 +164,22 @@ export declare class GistStateStore {
      */
     setState(stateJson: string): void;
     /**
-     * Push all dirty files to the backing Gist. Retries once on failure.
+     * Push all dirty files to the backing Gist.
+     *
+     * Behavior:
+     *  - When an ETag is available from the previous fetch, sends `If-Match`
+     *    so a 412 surfaces if another machine pushed since we last fetched.
+     *  - On 412, attempts a single merge: re-fetches the Gist (refreshing the
+     *    ETag), re-applies the in-memory dirty content on top of the remote,
+     *    and pushes once more. If the second push also 412s, throws
+     *    {@link GistConcurrencyError} — the caller can decide whether to
+     *    refreshFromGist + retry.
+     *  - On any other error, retries once (existing behavior). If the retry
+     *    also fails, returns `false`.
      *
      * Returns `true` on success (or when there is nothing to push).
-     * Returns `false` if both attempts fail.
+     * Returns `false` if a non-conflict push fails on both attempts.
+     * Throws {@link GistConcurrencyError} on unresolvable conflicts (#1115).
      * Throws if the Gist ID has not been resolved yet (bootstrap not called).
      */
     push(): Promise<boolean>;

package/dist/core/gist-state-store.js

@@ -13,14 +13,41 @@
  *  5. If not found anywhere, create a new private Gist with seed files and store the ID
  *  6. Cache all Gist file contents in memory for session-scoped reads
  *  7. Write state to a local cache file for fallback
+ *
+ * Concurrency model (#1115):
+ *
+ *  Each fetch captures the response's `ETag` and stores it as
+ *  `lastFetchedEtag`. The next `push()` sends that ETag back as
+ *  `If-Match` so the GitHub Gist API rejects the write with 412 Precondition
+ *  Failed if another machine pushed in the interval.
+ *
+ *  On 412, the store attempts a single merge: it re-fetches the Gist
+ *  (refreshing the ETag), re-applies the in-memory dirty content on top of
+ *  the now-current remote state, and pushes once more. If that second push
+ *  also returns 412, `push()` throws {@link GistConcurrencyError} — local
+ *  mutations stay in memory so the caller can decide whether to refresh and
+ *  retry. The merge step is intentionally cheap (state is a single JSON
+ *  blob) and treats local dirty changes as authoritative for conflict
+ *  cells, which matches the "last-write-wins by intent" model the rest of
+ *  oss-autopilot already assumes for state.json.
  */
 import * as fs from 'fs';
 import { AgentStateSchema } from './state-schema.js';
 import { atomicWriteFileSync, createFreshState, migrateV1ToV2, migrateV2ToV3 } from './state-persistence.js';
-import { getGistIdPath, getStateCachePath } from './utils.js';
+import { getGistIdPath, getStateCachePath } from './paths.js';
 import { debug, warn } from './logger.js';
-import { GistPermissionError, isRateLimitError } from './errors.js';
+import { GistPermissionError, GistConcurrencyError, isRateLimitError } from './errors.js';
 const MODULE = 'gist-store';
+/**
+ * Extract the ETag header from an Octokit response, tolerating both lower-
+ * and upper-case header names. Returns `null` when no ETag is present (test
+ * mocks, degraded responses, etc.).
+ */
+function extractEtag(headers) {
+    if (!headers)
+        return null;
+    return headers.etag ?? headers.ETag ?? null;
+}
 /** Well-known Gist description used for search-based discovery. */
 export const GIST_DESCRIPTION = 'oss-autopilot-state';
 /** Primary state file name inside the Gist. */
@@ -32,6 +59,14 @@ export class GistStateStore {
     gistId = null;
     cachedFiles = new Map();
     dirtyFiles = new Set();
+    /**
+     * ETag captured from the most recent successful Gist fetch (#1115).
+     * Sent back as `If-Match` on `update` so concurrent writes from another
+     * machine surface as 412 Precondition Failed instead of silently winning
+     * the last-write-wins race. `null` when the SDK didn't surface the header
+     * (e.g. test mocks without headers) — in that case we skip the check.
+     */
+    lastFetchedEtag = null;
     octokit;
     lastRefreshAt = 0;
     static REFRESH_THROTTLE_MS = 30_000;
@@ -224,10 +259,22 @@ export class GistStateStore {
         this.markDirty(STATE_FILE_NAME);
     }
     /**
-     * Push all dirty files to the backing Gist. Retries once on failure.
+     * Push all dirty files to the backing Gist.
+     *
+     * Behavior:
+     *  - When an ETag is available from the previous fetch, sends `If-Match`
+     *    so a 412 surfaces if another machine pushed since we last fetched.
+     *  - On 412, attempts a single merge: re-fetches the Gist (refreshing the
+     *    ETag), re-applies the in-memory dirty content on top of the remote,
+     *    and pushes once more. If the second push also 412s, throws
+     *    {@link GistConcurrencyError} — the caller can decide whether to
+     *    refreshFromGist + retry.
+     *  - On any other error, retries once (existing behavior). If the retry
+     *    also fails, returns `false`.
      *
      * Returns `true` on success (or when there is nothing to push).
-     * Returns `false` if both attempts fail.
+     * Returns `false` if a non-conflict push fails on both attempts.
+     * Throws {@link GistConcurrencyError} on unresolvable conflicts (#1115).
      * Throws if the Gist ID has not been resolved yet (bootstrap not called).
      */
     async push() {
@@ -237,28 +284,74 @@ export class GistStateStore {
         if (this.gistId === null) {
             throw new Error('GistStateStore: cannot push before bootstrap — gistId is null');
         }
-        // Build PATCH payload from the dirty set
-        const files = {};
-        for (const filename of this.dirtyFiles) {
-            const content = this.cachedFiles.get(filename);
-            if (content !== undefined) {
-                files[filename] = { content };
+        const buildFiles = () => {
+            const out = {};
+            for (const filename of this.dirtyFiles) {
+                const content = this.cachedFiles.get(filename);
+                if (content !== undefined) {
+                    out[filename] = { content };
+                }
             }
-        }
-        const attempt = async () => {
-            await this.octokit.gists.update({ gist_id: this.gistId, files });
-            return true;
+            return out;
         };
-        try {
-            await attempt();
-        }
-        catch (firstErr) {
-            debug(MODULE, `push failed on first attempt, retrying: ${firstErr}`);
+        /** Attempt a single push, capturing the response ETag for the next push. */
+        const attempt = async (etag) => {
             try {
-                await attempt();
+                const params = {
+                    gist_id: this.gistId,
+                    files: buildFiles(),
+                };
+                if (etag) {
+                    params.headers = { 'if-match': etag };
+                }
+                const response = await this.octokit.gists.update(params);
+                // Refresh our cached ETag so the next push uses the post-update value.
+                const newEtag = extractEtag(response.headers);
+                if (newEtag)
+                    this.lastFetchedEtag = newEtag;
+                return { ok: true };
+            }
+            catch (err) {
+                const status = err.status;
+                return { ok: false, status, err };
             }
-            catch (secondErr) {
-                warn(MODULE, `push failed after retry, giving up: ${secondErr}`);
+        };
+        // ── Phase 1: best-shot push with current ETag ─────────────────────
+        let result = await attempt(this.lastFetchedEtag);
+        // ── Phase 2: ETag mismatch — try to merge once ────────────────────
+        if (!result.ok && result.status === 412) {
+            const expectedEtag = this.lastFetchedEtag;
+            debug(MODULE, `push hit 412 (ETag mismatch); attempting merge — refreshing and retrying once`);
+            // Snapshot the dirty contents before refresh (fetchAndCache wipes the cache).
+            const stagedContents = {};
+            for (const filename of this.dirtyFiles) {
+                const content = this.cachedFiles.get(filename);
+                if (content !== undefined)
+                    stagedContents[filename] = content;
+            }
+            try {
+                await this.fetchAndCache(this.gistId);
+            }
+            catch (refreshErr) {
+                warn(MODULE, `Merge refresh after 412 failed: ${refreshErr}`);
+                throw new GistConcurrencyError(expectedEtag, null);
+            }
+            // Re-apply our staged dirty contents on top of the refreshed remote.
+            for (const [filename, content] of Object.entries(stagedContents)) {
+                this.cachedFiles.set(filename, content);
+            }
+            result = await attempt(this.lastFetchedEtag);
+            if (!result.ok && result.status === 412) {
+                warn(MODULE, 'Second push after merge also returned 412; surfacing GistConcurrencyError');
+                throw new GistConcurrencyError(expectedEtag, this.lastFetchedEtag);
+            }
+        }
+        // ── Phase 3: any other failure — retry once (existing behavior) ───
+        if (!result.ok) {
+            debug(MODULE, `push failed on first attempt, retrying: ${result.err}`);
+            result = await attempt(this.lastFetchedEtag);
+            if (!result.ok) {
+                warn(MODULE, `push failed after retry, giving up: ${result.err}`);
                 return false;
             }
         }
@@ -320,11 +413,14 @@ export class GistStateStore {
      * and write the local cache file.
      */
     async fetchAndCache(gistId) {
-        const { data } = await this.octokit.gists.get({ gist_id: gistId });
+        const response = await this.octokit.gists.get({ gist_id: gistId });
         this.gistId = gistId;
+        // Capture the ETag for optimistic-concurrency push (#1115). Header
+        // names from Octokit are lower-cased; tolerate both shapes for robustness.
+        this.lastFetchedEtag = extractEtag(response.headers);
         // Populate in-memory cache with ALL files from the Gist
         this.cachedFiles.clear();
-        for (const [filename, file] of Object.entries(data.files)) {
+        for (const [filename, file] of Object.entries(response.data.files)) {
             if (file && file.content != null) {
                 this.cachedFiles.set(filename, file.content);
             }

package/dist/core/github-stats.js

@@ -2,7 +2,7 @@
  * GitHub Stats - Fetching merged/closed PR counts with star-based filtering.
  * Extracted from PRMonitor to isolate statistics-gathering API calls (#263).
  */
-import { extractOwnerRepo, parseGitHubUrl, isOwnRepo } from './utils.js';
+import { extractOwnerRepo, parseGitHubUrl, isOwnRepo } from './urls.js';
 import { isBelowMinStars } from './types.js';
 import { debug, warn } from './logger.js';
 import { getHttpCache } from './http-cache.js';

package/dist/core/http-cache.js

@@ -12,7 +12,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as crypto from 'crypto';
-import { getCacheDir } from './utils.js';
+import { getCacheDir } from './paths.js';
 import { debug } from './logger.js';
 import { getHttpStatusCode } from './errors.js';
 const MODULE = 'http-cache';

package/dist/core/index.d.ts

@@ -8,7 +8,11 @@ export { PRMonitor, type PRCheckFailure, type FetchPRsResult, computeDisplayLabe
 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, stateFileExists, DEFAULT_CONCURRENCY, } from './utils.js';
+export { parseGitHubUrl, splitRepo, isOwnRepo } from './urls.js';
+export { daysBetween, formatRelativeTime, byDateDescending } from './dates.js';
+export { getCLIVersion, getDataDir, getStatePath, getBackupDir, getCacheDir, stateFileExists } from './paths.js';
+export { getGitHubToken, getGitHubTokenAsync, requireGitHubToken, resetGitHubTokenCache, detectGitHubUsername, } from './auth.js';
+export { DEFAULT_CONCURRENCY } from './concurrency.js';
 export { OssAutopilotError, ConfigurationError, ValidationError, GistPermissionError, errorMessage, getHttpStatusCode, isRateLimitError, isRateLimitOrAuthError, nonFatalCatch, resolveErrorCode, } 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

@@ -9,7 +9,11 @@ export { PRMonitor, computeDisplayLabel, classifyCICheck, classifyFailingChecks,
 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, stateFileExists, DEFAULT_CONCURRENCY, } from './utils.js';
+export { parseGitHubUrl, splitRepo, isOwnRepo } from './urls.js';
+export { daysBetween, formatRelativeTime, byDateDescending } from './dates.js';
+export { getCLIVersion, getDataDir, getStatePath, getBackupDir, getCacheDir, stateFileExists } from './paths.js';
+export { getGitHubToken, getGitHubTokenAsync, requireGitHubToken, resetGitHubTokenCache, detectGitHubUsername, } from './auth.js';
+export { DEFAULT_CONCURRENCY } from './concurrency.js';
 export { OssAutopilotError, ConfigurationError, ValidationError, GistPermissionError, errorMessage, getHttpStatusCode, isRateLimitError, isRateLimitOrAuthError, nonFatalCatch, resolveErrorCode, } from './errors.js';
 export { enableDebug, isDebugEnabled, debug, info, warn, timed } from './logger.js';
 export { HttpCache, getHttpCache, cachedRequest } from './http-cache.js';

package/dist/core/issue-conversation.js

@@ -9,8 +9,9 @@ import { getOctokit } from './github.js';
 import { isBotAuthor, isAcknowledgmentComment } from './comment-utils.js';
 import { paginateAll } from './pagination.js';
 import { getStateManager } from './state.js';
-import { daysBetween, splitRepo, extractOwnerRepo, isOwnRepo, DEFAULT_CONCURRENCY } from './utils.js';
-import { runWorkerPool } from './concurrency.js';
+import { daysBetween } from './dates.js';
+import { splitRepo, extractOwnerRepo, isOwnRepo } from './urls.js';
+import { runWorkerPool, DEFAULT_CONCURRENCY } from './concurrency.js';
 import { ConfigurationError, errorMessage } from './errors.js';
 import { debug, warn } from './logger.js';
 const MODULE = 'issue-conversation';

package/dist/core/paths.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function getDataDir(): string;
+/**
+ * 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 declare function getStatePath(): string;
+/**
+ * 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 declare function getBackupDir(): string;
+/**
+ * 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 declare function getCacheDir(): string;
+/**
+ * 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 declare function getGistIdPath(): string;
+/**
+ * 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 declare function getStateCachePath(): string;
+/**
+ * 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;
+/**
+ * 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 declare function getCLIVersion(): string;