sidekick-shared 0.27.5 → 0.28.0

package/dist/esm/providers/diagnostics.js

@@ -0,0 +1,83 @@
+const AVAILABLE_STATUS = { available: true, kind: 'available' };
+/** Small per-provider diagnostic state; it never stores transcript or environment contents. */
+export class ProviderDiagnosticTracker {
+    providerId;
+    options;
+    lastEmittedSignature = null;
+    lastStatus = {
+        operation: 'construct',
+        usable: true,
+        degraded: false,
+        runtimeStatus: AVAILABLE_STATUS,
+        diagnostics: [],
+    };
+    constructor(providerId, options = {}) {
+        this.providerId = providerId;
+        this.options = options;
+    }
+    available(operation) {
+        this.lastEmittedSignature = null;
+        this.lastStatus = {
+            operation,
+            usable: true,
+            degraded: false,
+            runtimeStatus: AVAILABLE_STATUS,
+            diagnostics: [],
+        };
+    }
+    degraded(operation, runtimeStatus, diagnostic, usable = true) {
+        const value = { providerId: this.providerId, ...diagnostic };
+        this.lastStatus = {
+            operation,
+            usable,
+            degraded: true,
+            runtimeStatus,
+            diagnostics: [value],
+        };
+        const signature = `${value.kind}\0${value.severity}\0${value.phase}\0${value.message}`;
+        if (signature === this.lastEmittedSignature)
+            return;
+        this.lastEmittedSignature = signature;
+        try {
+            this.options.onDiagnostic?.(value);
+        }
+        catch {
+            // Diagnostics are observational and cannot break provider operations.
+        }
+    }
+    getLastOperationStatus() {
+        return {
+            ...this.lastStatus,
+            runtimeStatus: { ...this.lastStatus.runtimeStatus },
+            diagnostics: [...this.lastStatus.diagnostics],
+        };
+    }
+}
+export function diagnosticFromRuntimeStatus(providerId, phase, status) {
+    if (status.kind === 'available')
+        return null;
+    const kind = status.kind;
+    return {
+        providerId,
+        kind,
+        severity: status.kind === 'query_failed' ? 'error' : 'warning',
+        phase,
+        message: status.message ?? defaultRuntimeMessage(providerId, status.kind),
+    };
+}
+function defaultRuntimeMessage(providerId, kind) {
+    switch (kind) {
+        case 'home_unavailable':
+            return `${providerId} data home is unavailable.`;
+        case 'config_unreadable':
+            return `${providerId} configuration is unreadable.`;
+        case 'db_missing':
+            return `${providerId} database is unavailable; file fallback is active.`;
+        case 'sqlite_missing':
+            return 'The sqlite3 executable is unavailable; file fallback is active.';
+        case 'sqlite_blocked':
+            return 'The sqlite3 executable could not be started; file fallback is active.';
+        case 'query_failed':
+            return `${providerId} database query failed; fallback data may be incomplete.`;
+    }
+}

package/dist/esm/providers/directoryListingCache.js

@@ -0,0 +1,206 @@
+/**
+ * Directory listings keyed by path and validated by the directory's own
+ * mtime and inode.
+ *
+ * A create, delete, or rename inside a directory bumps that directory's
+ * mtime; an append to an existing file does not. So a listing can be reused
+ * for as long as the directory's mtime and inode are unchanged, and the per
+ * file size/mtime it carries is only refreshed by `refreshFile()` (the watch
+ * event path) or by `revalidateRecent` on catch-up passes. Full discovery is
+ * then one stat per directory instead of one readdir per directory plus one
+ * stat per file.
+ *
+ * @module providers/directoryListingCache
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+export const DEFAULT_DIRECTORY_CACHE_MAX_DIRECTORIES = 10_000;
+export const DEFAULT_DIRECTORY_CACHE_RECENT_WINDOW_MS = 30 * 60_000;
+/**
+ * A directory whose mtime is within this many milliseconds of the moment it
+ * was listed may still receive entries that land on the same coarse mtime
+ * (HFS+, exFAT, SMB), so it is re-listed rather than trusted.
+ */
+const COARSE_MTIME_GUARD_MS = 2_000;
+export class DirectoryListingCache {
+    listings = new Map();
+    maxDirectories;
+    recentWindowMs;
+    constructor(options = {}) {
+        this.maxDirectories = Math.max(1, Math.floor(options.maxDirectories ?? DEFAULT_DIRECTORY_CACHE_MAX_DIRECTORIES));
+        this.recentWindowMs = Math.max(0, options.recentWindowMs ?? DEFAULT_DIRECTORY_CACHE_RECENT_WINDOW_MS);
+    }
+    get size() {
+        return this.listings.size;
+    }
+    /** The cached listing without touching the filesystem, if any. */
+    peek(dir) {
+        return this.listings.get(dir);
+    }
+    /**
+     * List `dir`, reusing the cached listing when the directory is unchanged.
+     * Returns null when `dir` is missing, unreadable, or not a directory.
+     */
+    async listDirectory(dir, accept, options = {}) {
+        let dirStat = options.dirStat;
+        if (!dirStat) {
+            try {
+                dirStat = await fs.promises.stat(dir);
+                count(options.stats, 'directoriesStatted');
+            }
+            catch {
+                this.listings.delete(dir);
+                return null;
+            }
+        }
+        if (!dirStat.isDirectory()) {
+            this.listings.delete(dir);
+            return null;
+        }
+        const cached = this.listings.get(dir);
+        const unchanged = cached !== undefined &&
+            cached.mtimeMs === dirStat.mtimeMs &&
+            cached.ino === dirStat.ino &&
+            dirStat.mtimeMs < cached.listedAtMs - COARSE_MTIME_GUARD_MS;
+        if (cached && unchanged) {
+            this.touch(dir, cached);
+            if (options.revalidateRecent)
+                await this.revalidateRecent(dir, cached, options.stats);
+            return cached;
+        }
+        let entries;
+        try {
+            entries = await fs.promises.readdir(dir, { withFileTypes: true });
+            count(options.stats, 'directoriesListed');
+        }
+        catch {
+            this.listings.delete(dir);
+            return null;
+        }
+        const listedAtMs = Date.now();
+        const files = new Map();
+        const subdirectories = [];
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                subdirectories.push(entry.name);
+                continue;
+            }
+            const isCandidateFile = entry.isFile() && accept(entry.name);
+            if (!isCandidateFile && !entry.isSymbolicLink())
+                continue;
+            const fullPath = path.join(dir, entry.name);
+            // A file already in the listing keeps its cached stat unless it is
+            // recent enough to be live; a directory change is a create, delete, or
+            // rename, and only the new names need a fresh stat.
+            const previous = cached?.files.get(entry.name);
+            if (isCandidateFile && previous && !this.isRecent(previous, listedAtMs)) {
+                files.set(entry.name, previous);
+                continue;
+            }
+            if (entry.isSymbolicLink() && !accept(entry.name)) {
+                // Symlinked directories are followed so linked project folders count.
+                try {
+                    const target = await fs.promises.stat(fullPath);
+                    count(options.stats, 'directoriesStatted');
+                    if (target.isDirectory())
+                        subdirectories.push(entry.name);
+                }
+                catch {
+                    // Dangling link.
+                }
+                continue;
+            }
+            try {
+                const stat = await fs.promises.stat(fullPath);
+                count(options.stats, 'filesStatted');
+                if (stat.isFile())
+                    files.set(entry.name, { sizeBytes: stat.size, mtimeMs: stat.mtimeMs });
+                else if (stat.isDirectory())
+                    subdirectories.push(entry.name);
+            }
+            catch {
+                // Vanished between readdir and stat.
+            }
+        }
+        const listing = {
+            mtimeMs: dirStat.mtimeMs,
+            ino: dirStat.ino,
+            listedAtMs,
+            files,
+            subdirectories,
+        };
+        this.touch(dir, listing);
+        return listing;
+    }
+    /**
+     * Stat one file and reflect the result in its parent's cached listing when
+     * that listing exists. Returns null when the path is missing or not a file.
+     * Never creates a listing: a partial listing must not pass for a full one.
+     */
+    async refreshFile(fullPath, stats) {
+        const dir = path.dirname(fullPath);
+        const name = path.basename(fullPath);
+        const listing = this.listings.get(dir);
+        try {
+            const stat = await fs.promises.stat(fullPath);
+            count(stats, 'filesStatted');
+            if (!stat.isFile()) {
+                listing?.files.delete(name);
+                return null;
+            }
+            const fileStat = { sizeBytes: stat.size, mtimeMs: stat.mtimeMs };
+            listing?.files.set(name, fileStat);
+            return fileStat;
+        }
+        catch {
+            listing?.files.delete(name);
+            return null;
+        }
+    }
+    /** Drop one directory's listing, or every listing. */
+    invalidate(dir) {
+        if (dir === undefined)
+            this.listings.clear();
+        else
+            this.listings.delete(dir);
+    }
+    async revalidateRecent(dir, listing, stats) {
+        const now = Date.now();
+        for (const [name, cached] of [...listing.files]) {
+            if (!this.isRecent(cached, now))
+                continue;
+            await this.refreshFile(path.join(dir, name), stats);
+        }
+    }
+    isRecent(stat, now) {
+        return now - stat.mtimeMs <= this.recentWindowMs;
+    }
+    touch(dir, listing) {
+        this.listings.delete(dir);
+        this.listings.set(dir, listing);
+        while (this.listings.size > this.maxDirectories) {
+            const oldest = this.listings.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.listings.delete(oldest);
+        }
+    }
+}
+/**
+ * Split a watcher-reported root-relative path into segments. Both separators
+ * are accepted (Windows watchers report backslashes). Returns null for an
+ * empty path or one that escapes the root.
+ */
+export function splitWatchedPath(relativePath) {
+    const segments = relativePath.split(/[\\/]+/).filter((segment) => segment.length > 0);
+    if (segments.length === 0)
+        return null;
+    if (segments.some((segment) => segment === '.' || segment === '..'))
+        return null;
+    return segments;
+}
+function count(stats, field) {
+    if (!stats)
+        return;
+    stats[field] = (stats[field] ?? 0) + 1;
+}

package/dist/esm/providers/factory.js

@@ -0,0 +1,54 @@
+import { ClaudeCodeProvider } from './claudeCode';
+import { CodexProvider } from './codex';
+import { OpenCodeProvider } from './openCode';
+import { SESSION_PROVIDER_IDS } from './types';
+/**
+ * Constructs built-in providers without probing the filesystem or binaries.
+ * A broken provider is isolated and reported instead of aborting host startup.
+ */
+export function createSessionProviders(options = {}) {
+    const diagnostics = [];
+    const diagnosticIndexes = new Map();
+    const providers = [];
+    const selected = new Set(options.providerIds ?? SESSION_PROVIDER_IDS);
+    const emit = (diagnostic) => {
+        const key = `${diagnostic.providerId}\0${diagnostic.kind}\0${diagnostic.phase}`;
+        const existingIndex = diagnosticIndexes.get(key);
+        if (existingIndex === undefined) {
+            diagnosticIndexes.set(key, diagnostics.length);
+            diagnostics.push(diagnostic);
+        }
+        else {
+            diagnostics[existingIndex] = diagnostic;
+        }
+        try {
+            options.onDiagnostic?.(diagnostic);
+        }
+        catch {
+            // A host diagnostic callback cannot break provider setup.
+        }
+    };
+    for (const providerId of SESSION_PROVIDER_IDS) {
+        if (!selected.has(providerId))
+            continue;
+        try {
+            const providerOptions = { onDiagnostic: emit };
+            providers.push(providerId === 'claude-code'
+                ? new ClaudeCodeProvider(providerOptions)
+                : providerId === 'opencode'
+                    ? new OpenCodeProvider(providerOptions)
+                    : new CodexProvider(providerOptions));
+        }
+        catch {
+            const diagnostic = {
+                providerId,
+                kind: 'construction_failed',
+                severity: 'error',
+                phase: 'construct',
+                message: `${providerId} could not be constructed and was omitted.`,
+            };
+            emit(diagnostic);
+        }
+    }
+    return { providers, diagnostics };
+}