profclaw 2.0.0 → 2.3.0

package/dist/types/summary.d.ts

@@ -246,11 +246,11 @@ export declare const SummarySchema: z.ZodObject<{
     }[];
     taskId?: string | undefined;
     component?: string | undefined;
+    startedAt?: Date | undefined;
     repository?: string | undefined;
     branch?: string | undefined;
     metadata?: Record<string, unknown> | undefined;
     sessionId?: string | undefined;
-    startedAt?: Date | undefined;
     completedAt?: Date | undefined;
     durationMs?: number | undefined;
     model?: string | undefined;
@@ -278,12 +278,12 @@ export declare const SummarySchema: z.ZodObject<{
     whatChanged: string;
     taskId?: string | undefined;
     component?: string | undefined;
+    startedAt?: Date | undefined;
     repository?: string | undefined;
     branch?: string | undefined;
     labels?: string[] | undefined;
     metadata?: Record<string, unknown> | undefined;
     sessionId?: string | undefined;
-    startedAt?: Date | undefined;
     completedAt?: Date | undefined;
     durationMs?: number | undefined;
     model?: string | undefined;
@@ -341,13 +341,13 @@ export type Artifact = ArtifactReference;
 export declare const CreateSummaryInputSchema: z.ZodObject<{
     taskId: z.ZodOptional<z.ZodString>;
     component: z.ZodOptional<z.ZodString>;
+    startedAt: z.ZodOptional<z.ZodDate>;
     title: z.ZodString;
     repository: z.ZodOptional<z.ZodString>;
     branch: z.ZodOptional<z.ZodString>;
     labels: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString, "many">>>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     sessionId: z.ZodOptional<z.ZodString>;
-    startedAt: z.ZodOptional<z.ZodDate>;
     completedAt: z.ZodOptional<z.ZodDate>;
     durationMs: z.ZodOptional<z.ZodNumber>;
     agent: z.ZodString;
@@ -459,12 +459,12 @@ export declare const CreateSummaryInputSchema: z.ZodObject<{
     whatChanged: string;
     taskId?: string | undefined;
     component?: string | undefined;
+    startedAt?: Date | undefined;
     repository?: string | undefined;
     branch?: string | undefined;
     labels?: string[] | undefined;
     metadata?: Record<string, unknown> | undefined;
     sessionId?: string | undefined;
-    startedAt?: Date | undefined;
     completedAt?: Date | undefined;
     durationMs?: number | undefined;
     model?: string | undefined;
@@ -516,12 +516,12 @@ export declare const CreateSummaryInputSchema: z.ZodObject<{
     whatChanged: string;
     taskId?: string | undefined;
     component?: string | undefined;
+    startedAt?: Date | undefined;
     repository?: string | undefined;
     branch?: string | undefined;
     labels?: string[] | undefined;
     metadata?: Record<string, unknown> | undefined;
     sessionId?: string | undefined;
-    startedAt?: Date | undefined;
     completedAt?: Date | undefined;
     durationMs?: number | undefined;
     model?: string | undefined;

package/dist/utils/auto-update.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Auto-Update Check
+ *
+ * Checks npm registry for newer versions of profclaw and caches the result
+ * for 24 hours so startup is not meaningfully delayed.
+ * Cache file: .profclaw/update-check.json
+ */
+export interface UpdateInfo {
+    currentVersion: string;
+    latestVersion: string;
+    updateAvailable: boolean;
+    releaseUrl?: string;
+}
+/**
+ * Check whether a newer version of `packageName` is available on npm.
+ * Results are cached for 24 hours in .profclaw/update-check.json.
+ */
+export declare function checkForUpdate(packageName?: string): Promise<UpdateInfo>;
+/**
+ * Format an update notification message suitable for printing to the terminal.
+ */
+export declare function formatUpdateMessage(info: UpdateInfo): string;
+//# sourceMappingURL=auto-update.d.ts.map

package/dist/utils/auto-update.js

@@ -0,0 +1,157 @@
+/**
+ * Auto-Update Check
+ *
+ * Checks npm registry for newer versions of profclaw and caches the result
+ * for 24 hours so startup is not meaningfully delayed.
+ * Cache file: .profclaw/update-check.json
+ */
+import fs from 'fs';
+import path from 'path';
+import { createRequire } from 'module';
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const NPM_REGISTRY = 'https://registry.npmjs.org';
+function getCacheDir() {
+    return path.join(process.cwd(), '.profclaw');
+}
+function getCachePath() {
+    return path.join(getCacheDir(), 'update-check.json');
+}
+function readCache() {
+    try {
+        const raw = fs.readFileSync(getCachePath(), 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(info) {
+    try {
+        const dir = getCacheDir();
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        const cache = { checkedAt: Date.now(), info };
+        fs.writeFileSync(getCachePath(), JSON.stringify(cache, null, 2), 'utf8');
+    }
+    catch {
+        // Non-fatal — update check is best-effort
+    }
+}
+function isCacheValid(cache) {
+    return Date.now() - cache.checkedAt < CACHE_TTL_MS;
+}
+function getCurrentVersion(packageName) {
+    try {
+        // Try to read from the package.json that ships with the installed package
+        const require = createRequire(import.meta.url);
+        const pkgPath = require.resolve(`${packageName}/package.json`);
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        return pkg.version;
+    }
+    catch {
+        // Fallback: read from our own package.json (works in dev / monorepo)
+        try {
+            const selfPath = path.resolve(path.dirname(new URL(import.meta.url).pathname), '../../package.json');
+            const pkg = JSON.parse(fs.readFileSync(selfPath, 'utf8'));
+            return pkg.version;
+        }
+        catch {
+            return '0.0.0';
+        }
+    }
+}
+function getPackageName() {
+    try {
+        const selfPath = path.resolve(path.dirname(new URL(import.meta.url).pathname), '../../package.json');
+        const pkg = JSON.parse(fs.readFileSync(selfPath, 'utf8'));
+        return pkg.name;
+    }
+    catch {
+        return 'profclaw';
+    }
+}
+/**
+ * Compare two semver strings.
+ * Returns true when `latest` is strictly newer than `current`.
+ */
+function isNewerVersion(current, latest) {
+    const parse = (v) => v
+        .replace(/^[^0-9]*/, '')
+        .split('.')
+        .map(n => parseInt(n, 10) || 0);
+    const [cMaj, cMin, cPatch] = parse(current);
+    const [lMaj, lMin, lPatch] = parse(latest);
+    if (lMaj !== cMaj)
+        return (lMaj ?? 0) > (cMaj ?? 0);
+    if (lMin !== cMin)
+        return (lMin ?? 0) > (cMin ?? 0);
+    return (lPatch ?? 0) > (cPatch ?? 0);
+}
+/**
+ * Fetch the latest version from the npm registry.
+ * Throws if the network request fails.
+ */
+async function fetchLatestVersion(packageName) {
+    const url = `${NPM_REGISTRY}/${encodeURIComponent(packageName)}/latest`;
+    const response = await fetch(url, {
+        headers: { Accept: 'application/json' },
+        signal: AbortSignal.timeout(5000),
+    });
+    if (!response.ok) {
+        throw new Error(`npm registry returned ${response.status} for ${packageName}`);
+    }
+    const data = (await response.json());
+    return data.version;
+}
+/**
+ * Check whether a newer version of `packageName` is available on npm.
+ * Results are cached for 24 hours in .profclaw/update-check.json.
+ */
+export async function checkForUpdate(packageName) {
+    const pkg = packageName ?? getPackageName();
+    const currentVersion = getCurrentVersion(pkg);
+    // Serve from cache if still fresh
+    const cached = readCache();
+    if (cached && isCacheValid(cached) && cached.info.currentVersion === currentVersion) {
+        return cached.info;
+    }
+    try {
+        const latestVersion = await fetchLatestVersion(pkg);
+        const updateAvailable = isNewerVersion(currentVersion, latestVersion);
+        const info = {
+            currentVersion,
+            latestVersion,
+            updateAvailable,
+            releaseUrl: updateAvailable
+                ? `https://www.npmjs.com/package/${pkg}/v/${latestVersion}`
+                : undefined,
+        };
+        writeCache(info);
+        return info;
+    }
+    catch {
+        // Network failure — return a no-update result without caching
+        return {
+            currentVersion,
+            latestVersion: currentVersion,
+            updateAvailable: false,
+        };
+    }
+}
+/**
+ * Format an update notification message suitable for printing to the terminal.
+ */
+export function formatUpdateMessage(info) {
+    if (!info.updateAvailable)
+        return '';
+    const parts = [
+        `Update available: ${info.currentVersion} → ${info.latestVersion}.`,
+        `Run: npm i -g ${getPackageName()}`,
+    ];
+    if (info.releaseUrl) {
+        parts.push(`  ${info.releaseUrl}`);
+    }
+    return parts.join('  ');
+}
+//# sourceMappingURL=auto-update.js.map

package/dist/utils/offline-detect.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Offline Detection Utility
+ *
+ * Periodically pings the server health endpoint to detect connectivity.
+ * Emits status-change notifications to registered listeners.
+ * Queues commands locally while offline and replays them on reconnect.
+ */
+export type OfflineStatusListener = (online: boolean) => void;
+export interface QueuedCommand {
+    id: string;
+    payload: unknown;
+    queuedAt: number;
+}
+export declare class OfflineDetector {
+    private isOnline;
+    private checkInterval;
+    private listeners;
+    private serverUrl;
+    private commandQueue;
+    /**
+     * Start polling `serverUrl + /health` every `intervalMs` milliseconds.
+     * Defaults to 10 seconds.
+     */
+    start(serverUrl: string, intervalMs?: number): void;
+    /** Stop polling. */
+    stop(): void;
+    /**
+     * Register a listener that is called whenever the online status changes.
+     * Returns an unsubscribe function.
+     */
+    onStatusChange(cb: OfflineStatusListener): () => void;
+    /** Returns the current online status. */
+    getStatus(): boolean;
+    /**
+     * Queue a command for later replay when the server comes back online.
+     * Returns the queued command's id.
+     */
+    queueCommand(payload: unknown): string;
+    /**
+     * Drain and return all queued commands in FIFO order.
+     * The queue is cleared after calling this.
+     */
+    drainQueue(): QueuedCommand[];
+    /** How many commands are currently queued. */
+    queueLength(): number;
+    private check;
+    private ping;
+    private emit;
+}
+/**
+ * Returns the shared singleton OfflineDetector.
+ * Lazily created on first call.
+ */
+export declare function getOfflineDetector(): OfflineDetector;
+//# sourceMappingURL=offline-detect.d.ts.map

package/dist/utils/offline-detect.js

@@ -0,0 +1,121 @@
+/**
+ * Offline Detection Utility
+ *
+ * Periodically pings the server health endpoint to detect connectivity.
+ * Emits status-change notifications to registered listeners.
+ * Queues commands locally while offline and replays them on reconnect.
+ */
+const DEFAULT_INTERVAL_MS = 10_000;
+const HEALTH_PATH = '/health';
+const PING_TIMEOUT_MS = 5_000;
+export class OfflineDetector {
+    isOnline = true;
+    checkInterval = null;
+    listeners = [];
+    serverUrl = '';
+    commandQueue = [];
+    /**
+     * Start polling `serverUrl + /health` every `intervalMs` milliseconds.
+     * Defaults to 10 seconds.
+     */
+    start(serverUrl, intervalMs = DEFAULT_INTERVAL_MS) {
+        this.serverUrl = serverUrl;
+        this.stop(); // clear any existing interval
+        // Run an immediate check, then repeat on the interval
+        void this.check();
+        this.checkInterval = setInterval(() => { void this.check(); }, intervalMs);
+    }
+    /** Stop polling. */
+    stop() {
+        if (this.checkInterval !== null) {
+            clearInterval(this.checkInterval);
+            this.checkInterval = null;
+        }
+    }
+    /**
+     * Register a listener that is called whenever the online status changes.
+     * Returns an unsubscribe function.
+     */
+    onStatusChange(cb) {
+        this.listeners.push(cb);
+        return () => {
+            this.listeners = this.listeners.filter(l => l !== cb);
+        };
+    }
+    /** Returns the current online status. */
+    getStatus() {
+        return this.isOnline;
+    }
+    /**
+     * Queue a command for later replay when the server comes back online.
+     * Returns the queued command's id.
+     */
+    queueCommand(payload) {
+        const id = `cmd-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        this.commandQueue.push({ id, payload, queuedAt: Date.now() });
+        return id;
+    }
+    /**
+     * Drain and return all queued commands in FIFO order.
+     * The queue is cleared after calling this.
+     */
+    drainQueue() {
+        const drained = [...this.commandQueue];
+        this.commandQueue = [];
+        return drained;
+    }
+    /** How many commands are currently queued. */
+    queueLength() {
+        return this.commandQueue.length;
+    }
+    // ── Private ──────────────────────────────────────────────────────────────────
+    async check() {
+        const wasOnline = this.isOnline;
+        const nowOnline = await this.ping();
+        if (nowOnline !== wasOnline) {
+            this.isOnline = nowOnline;
+            this.emit(nowOnline);
+        }
+    }
+    async ping() {
+        const url = `${this.serverUrl}${HEALTH_PATH}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), PING_TIMEOUT_MS);
+        try {
+            const res = await fetch(url, {
+                method: 'GET',
+                signal: controller.signal,
+            });
+            return res.ok;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    emit(online) {
+        for (const listener of this.listeners) {
+            try {
+                listener(online);
+            }
+            catch {
+                // Swallow listener errors to keep the detector running
+            }
+        }
+    }
+}
+// ── Singleton ──────────────────────────────────────────────────────────────────
+let _instance = null;
+/**
+ * Returns the shared singleton OfflineDetector.
+ * Lazily created on first call.
+ */
+export function getOfflineDetector() {
+    if (_instance === null) {
+        _instance = new OfflineDetector();
+    }
+    return _instance;
+}
+//# sourceMappingURL=offline-detect.js.map

package/dist/utils/pid-file.d.ts

@@ -0,0 +1,36 @@
+export interface PidData {
+    pid: number;
+    port: number;
+    startedAt: number;
+}
+/**
+ * Write PID file with process info.
+ * Creates .profclaw/ directory if it doesn't exist.
+ */
+export declare function writePidFile(port: number): void;
+/**
+ * Read PID file.
+ * Returns null if the file doesn't exist or contains malformed data.
+ */
+export declare function readPidFile(): PidData | null;
+/**
+ * Remove PID file if it exists.
+ */
+export declare function removePidFile(): void;
+export interface ServerRunningResult {
+    running: boolean;
+    pid?: number;
+    port?: number;
+}
+/**
+ * Check if a server process described by the PID file is still alive.
+ * If the process is dead but the PID file exists, the stale file is cleaned up.
+ */
+export declare function isServerRunning(): ServerRunningResult;
+/**
+ * Kill the server described by the PID file using SIGTERM.
+ * Polls for up to 5 seconds waiting for the process to exit.
+ * Returns true if the process was killed (or was already gone), false on timeout.
+ */
+export declare function killExistingServer(): boolean;
+//# sourceMappingURL=pid-file.d.ts.map

package/dist/utils/pid-file.js

@@ -0,0 +1,125 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const PROFCLAW_DIR = '.profclaw';
+const PID_FILENAME = 'server.pid';
+function getPidPath() {
+    return join(process.cwd(), PROFCLAW_DIR, PID_FILENAME);
+}
+/**
+ * Write PID file with process info.
+ * Creates .profclaw/ directory if it doesn't exist.
+ */
+export function writePidFile(port) {
+    const dir = join(process.cwd(), PROFCLAW_DIR);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const data = {
+        pid: process.pid,
+        port,
+        startedAt: Date.now(),
+    };
+    writeFileSync(getPidPath(), JSON.stringify(data, null, 2), 'utf-8');
+}
+/**
+ * Read PID file.
+ * Returns null if the file doesn't exist or contains malformed data.
+ */
+export function readPidFile() {
+    const pidPath = getPidPath();
+    if (!existsSync(pidPath)) {
+        return null;
+    }
+    try {
+        const raw = readFileSync(pidPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed !== null &&
+            typeof parsed === 'object' &&
+            'pid' in parsed &&
+            'port' in parsed &&
+            'startedAt' in parsed &&
+            typeof parsed.pid === 'number' &&
+            typeof parsed.port === 'number' &&
+            typeof parsed.startedAt === 'number') {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Remove PID file if it exists.
+ */
+export function removePidFile() {
+    const pidPath = getPidPath();
+    if (existsSync(pidPath)) {
+        try {
+            unlinkSync(pidPath);
+        }
+        catch {
+            // Best effort — ignore failures (e.g. race condition on shutdown)
+        }
+    }
+}
+/**
+ * Check if a server process described by the PID file is still alive.
+ * If the process is dead but the PID file exists, the stale file is cleaned up.
+ */
+export function isServerRunning() {
+    const data = readPidFile();
+    if (!data) {
+        return { running: false };
+    }
+    try {
+        // Signal 0 checks process existence without sending a real signal
+        process.kill(data.pid, 0);
+        return { running: true, pid: data.pid, port: data.port };
+    }
+    catch {
+        // Process doesn't exist — stale PID file
+        removePidFile();
+        return { running: false };
+    }
+}
+/**
+ * Kill the server described by the PID file using SIGTERM.
+ * Polls for up to 5 seconds waiting for the process to exit.
+ * Returns true if the process was killed (or was already gone), false on timeout.
+ */
+export function killExistingServer() {
+    const data = readPidFile();
+    if (!data) {
+        return false;
+    }
+    try {
+        process.kill(data.pid, 'SIGTERM');
+    }
+    catch {
+        // Process already gone
+        removePidFile();
+        return true;
+    }
+    // Poll up to 5 seconds (50 × 100 ms)
+    const MAX_WAIT_MS = 5000;
+    const POLL_INTERVAL_MS = 100;
+    const start = Date.now();
+    while (Date.now() - start < MAX_WAIT_MS) {
+        try {
+            process.kill(data.pid, 0);
+            // Still alive — busy-wait (synchronous polling, acceptable for a CLI shutdown path)
+            const pollUntil = Date.now() + POLL_INTERVAL_MS;
+            while (Date.now() < pollUntil) {
+                // spin wait
+            }
+        }
+        catch {
+            // Process gone
+            removePidFile();
+            return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=pid-file.js.map

package/dist/utils/prevent-sleep.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Sleep Prevention Utility
+ *
+ * Prevents OS sleep/screensaver during long agent runs.
+ * - macOS: uses `caffeinate -i -w {pid}`
+ * - Linux: tries `systemd-inhibit` then falls back to `xdg-screensaver suspend`
+ * - Windows: no-op (PowerShell SetThreadExecutionState not exposed without ffi)
+ */
+export declare class SleepPreventer {
+    private _process;
+    private _active;
+    /**
+     * Start preventing OS sleep.
+     * Safe to call multiple times — subsequent calls are no-ops if already active.
+     */
+    start(): void;
+    /**
+     * Stop preventing sleep and release the system process.
+     */
+    stop(): void;
+    isActive(): boolean;
+}
+/**
+ * Returns the shared singleton SleepPreventer instance.
+ */
+export declare function getSleepPreventer(): SleepPreventer;
+//# sourceMappingURL=prevent-sleep.d.ts.map