goke 6.12.3 → 6.13.0

package/dist/__test__/daemon.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Tests for the daemon background process support.
+ *
+ * Tests the DaemonContext lifecycle: PID file management, isDaemon detection,
+ * start/stop/isRunning, forCommand, heartbeat, and instance ID safety.
+ *
+ * Server-mode tests (isDaemon=true) run in child processes to avoid
+ * scheduling process.exit() timers inside the vitest runner.
+ */
+export {};
+//# sourceMappingURL=daemon.test.d.ts.map

package/dist/__test__/daemon.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon.test.d.ts","sourceRoot":"","sources":["../../src/__test__/daemon.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/__test__/daemon.test.js

@@ -0,0 +1,296 @@
+/**
+ * Tests for the daemon background process support.
+ *
+ * Tests the DaemonContext lifecycle: PID file management, isDaemon detection,
+ * start/stop/isRunning, forCommand, heartbeat, and instance ID safety.
+ *
+ * Server-mode tests (isDaemon=true) run in child processes to avoid
+ * scheduling process.exit() timers inside the vitest runner.
+ */
+import { describe, expect, test, afterEach } from 'vitest';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+const execFileAsync = promisify(execFile);
+const DAEMON_DIR = path.join(os.homedir(), '.config', 'goke', 'daemons');
+function pidFilePath(cliName, commandName) {
+    const safeName = `${cliName}--${commandName}`
+        .replace(/\s+/g, '-')
+        .replace(/[^a-zA-Z0-9_-]/g, '');
+    return path.join(DAEMON_DIR, `${safeName}.pid.json`);
+}
+function readPidFile(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function killIfAlive(pid) {
+    if (isProcessAlive(pid)) {
+        try {
+            process.kill(pid, 'SIGKILL');
+        }
+        catch { }
+    }
+}
+// Track PIDs to clean up after tests
+const spawnedPids = [];
+const testPidFiles = [];
+afterEach(async () => {
+    for (const pid of spawnedPids) {
+        await killIfAlive(pid);
+    }
+    spawnedPids.length = 0;
+    for (const f of testPidFiles) {
+        try {
+            fs.unlinkSync(f);
+        }
+        catch { }
+    }
+    testPidFiles.length = 0;
+});
+// Helper script that simulates a daemon process: writes PID file with
+// instance ID and heartbeat, stays alive until SIGTERM or timeout.
+function writeDaemonHelper(scriptPath) {
+    fs.writeFileSync(scriptPath, `
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import crypto from 'node:crypto'
+
+const DAEMON_DIR = path.join(os.homedir(), '.config', 'goke', 'daemons')
+const cliName = process.env.TEST_CLI_NAME || 'test-daemon-cli'
+const cmdName = process.env.TEST_CMD_NAME || 'bg'
+const safeName = cliName + '--' + cmdName
+const pidFile = path.join(DAEMON_DIR, safeName + '.pid.json')
+
+fs.mkdirSync(path.dirname(pidFile), { recursive: true })
+
+const instanceId = crypto.randomBytes(8).toString('hex')
+const pidData = { pid: process.pid, id: instanceId, startedAt: Date.now(), heartbeatAt: Date.now() }
+fs.writeFileSync(pidFile, JSON.stringify(pidData), { mode: 0o600 })
+
+const hb = setInterval(() => {
+  try {
+    const current = JSON.parse(fs.readFileSync(pidFile, 'utf-8'))
+    if (current.id === instanceId) {
+      current.heartbeatAt = Date.now()
+      fs.writeFileSync(pidFile, JSON.stringify(current), { mode: 0o600 })
+    }
+  } catch {}
+}, 2000)
+hb.unref()
+
+const timeoutMs = Number(process.env.GOKE_DAEMON_TIMEOUT) || 60000
+const timer = setTimeout(() => {
+  try {
+    const current = JSON.parse(fs.readFileSync(pidFile, 'utf-8'))
+    if (current.id === instanceId) fs.unlinkSync(pidFile)
+  } catch {}
+  process.exit(0)
+}, timeoutMs)
+
+process.on('SIGTERM', () => {
+  clearTimeout(timer)
+  clearInterval(hb)
+  try {
+    const current = JSON.parse(fs.readFileSync(pidFile, 'utf-8'))
+    if (current.id === instanceId) fs.unlinkSync(pidFile)
+  } catch {}
+  process.exit(0)
+})
+
+process.on('exit', () => {
+  try {
+    const current = JSON.parse(fs.readFileSync(pidFile, 'utf-8'))
+    if (current.id === instanceId) fs.unlinkSync(pidFile)
+  } catch {}
+})
+`);
+}
+describe('DaemonContext', () => {
+    test('isDaemon is false by default (client mode)', async () => {
+        const { default: goke } = await import('../index.js');
+        const cli = goke('test-cli');
+        let isDaemon;
+        cli.command('run', 'test').action((opts, ctx) => {
+            isDaemon = ctx.daemon.isDaemon;
+        });
+        await cli.parse(['node', 'test', 'run'], { run: true });
+        expect(isDaemon).toBe(false);
+    });
+    test('isDaemon is true when GOKE_DAEMON=1 (tested in child process)', async () => {
+        // Run a small script in a child process that creates a DaemonContext
+        // with the env var set and prints isDaemon. This avoids scheduling
+        // process.exit() timers inside the vitest process.
+        // Uses the compiled dist/ so plain Node can import it (no tsx needed).
+        const scriptPath = path.join(os.tmpdir(), 'goke-daemon-is-daemon-test.mjs');
+        const distDir = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..', '..', 'dist');
+        fs.writeFileSync(scriptPath, `
+import { DaemonContext } from '${distDir}/daemon.js'
+const ctx = new DaemonContext('test-is-daemon', 'cmd', ['node', 'test'])
+console.log(ctx.isDaemon ? 'SERVER' : 'CLIENT')
+// Exit immediately to not leave the daemon alive
+process.exit(0)
+`);
+        testPidFiles.push(pidFilePath('test-is-daemon', 'cmd'));
+        const { stdout } = await execFileAsync(process.execPath, [scriptPath], {
+            env: { ...process.env, GOKE_DAEMON: '1', GOKE_DAEMON_TIMEOUT: '1000' },
+        });
+        expect(stdout.trim()).toBe('SERVER');
+    }, 10_000);
+    test('isRunning returns false when no daemon is running', async () => {
+        const { default: goke } = await import('../index.js');
+        const cli = goke('test-cli');
+        let running;
+        cli.command('check', 'test').action(async (opts, ctx) => {
+            running = await ctx.daemon.isRunning();
+        });
+        await cli.parse(['node', 'test', 'check'], { run: true });
+        expect(running).toBe(false);
+    });
+    test('start spawns a detached daemon, isRunning returns true, stop kills it', async () => {
+        const helperScript = path.join(os.tmpdir(), 'goke-daemon-test-start.mjs');
+        writeDaemonHelper(helperScript);
+        testPidFiles.push(pidFilePath('test-daemon-cli', 'bg'));
+        const { DaemonContext } = await import('../daemon.js');
+        const ctx = new DaemonContext('test-daemon-cli', 'bg', [process.execPath, helperScript, 'bg']);
+        expect(ctx.isDaemon).toBe(false);
+        expect(await ctx.isRunning()).toBe(false);
+        await ctx.start({ timeoutMs: 30_000 });
+        expect(await ctx.isRunning()).toBe(true);
+        const pidData = readPidFile(pidFilePath('test-daemon-cli', 'bg'));
+        expect(pidData).not.toBeNull();
+        expect(pidData.id).toBeTruthy();
+        spawnedPids.push(pidData.pid);
+        await ctx.stop();
+        await new Promise((r) => setTimeout(r, 200));
+        expect(await ctx.isRunning()).toBe(false);
+        try {
+            fs.unlinkSync(helperScript);
+        }
+        catch { }
+    }, 15_000);
+    test('start kills existing daemon before spawning new one', async () => {
+        const helperScript = path.join(os.tmpdir(), 'goke-daemon-test-replace.mjs');
+        writeDaemonHelper(helperScript);
+        testPidFiles.push(pidFilePath('test-daemon-cli', 'bg'));
+        const { DaemonContext } = await import('../daemon.js');
+        const ctx = new DaemonContext('test-daemon-cli', 'bg', [process.execPath, helperScript, 'bg']);
+        await ctx.start({ timeoutMs: 30_000 });
+        const firstPid = readPidFile(pidFilePath('test-daemon-cli', 'bg'));
+        expect(firstPid).not.toBeNull();
+        spawnedPids.push(firstPid.pid);
+        const firstId = firstPid.id;
+        await ctx.start({ timeoutMs: 30_000 });
+        const secondPid = readPidFile(pidFilePath('test-daemon-cli', 'bg'));
+        expect(secondPid).not.toBeNull();
+        spawnedPids.push(secondPid.pid);
+        // PIDs and instance IDs should differ
+        expect(secondPid.pid).not.toBe(firstPid.pid);
+        expect(secondPid.id).not.toBe(firstId);
+        expect(isProcessAlive(firstPid.pid)).toBe(false);
+        expect(isProcessAlive(secondPid.pid)).toBe(true);
+        await ctx.stop();
+        try {
+            fs.unlinkSync(helperScript);
+        }
+        catch { }
+    }, 15_000);
+    test('stop is idempotent when no daemon running', async () => {
+        const { DaemonContext } = await import('../daemon.js');
+        const ctx = new DaemonContext('nonexistent-cli', 'nope', ['node', 'nope']);
+        await ctx.stop();
+        await ctx.stop();
+    });
+    test('forCommand returns context for a different command', async () => {
+        const { DaemonContext } = await import('../daemon.js');
+        const loginCtx = new DaemonContext('myapp', 'login', ['node', 'myapp', 'login']);
+        const meCtx = loginCtx.forCommand('me');
+        // They should reference different PID files
+        expect(await loginCtx.isRunning()).toBe(false);
+        expect(await meCtx.isRunning()).toBe(false);
+        // forCommand context is always client mode
+        expect(meCtx.isDaemon).toBe(false);
+    });
+    test('forCommand can check and stop another commands daemon', async () => {
+        const helperScript = path.join(os.tmpdir(), 'goke-daemon-test-forcommand.mjs');
+        writeDaemonHelper(helperScript);
+        testPidFiles.push(pidFilePath('test-daemon-cli', 'bg'));
+        const { DaemonContext } = await import('../daemon.js');
+        // Start daemon for "bg" command
+        const bgCtx = new DaemonContext('test-daemon-cli', 'bg', [process.execPath, helperScript, 'bg']);
+        await bgCtx.start({ timeoutMs: 30_000 });
+        const pidData = readPidFile(pidFilePath('test-daemon-cli', 'bg'));
+        if (pidData)
+            spawnedPids.push(pidData.pid);
+        // Create a context for "me" command and use forCommand to check "bg"
+        const meCtx = new DaemonContext('test-daemon-cli', 'me', ['node', 'test', 'me']);
+        const bgFromMe = meCtx.forCommand('bg');
+        expect(await bgFromMe.isRunning()).toBe(true);
+        await bgFromMe.stop();
+        await new Promise((r) => setTimeout(r, 200));
+        expect(await bgFromMe.isRunning()).toBe(false);
+        try {
+            fs.unlinkSync(helperScript);
+        }
+        catch { }
+    }, 15_000);
+    test('stale PID file is cleaned up by isRunning', async () => {
+        const pidFile = pidFilePath('stale-test', 'cmd');
+        testPidFiles.push(pidFile);
+        // Write a PID file with a PID that doesn't exist
+        fs.mkdirSync(path.dirname(pidFile), { recursive: true });
+        fs.writeFileSync(pidFile, JSON.stringify({
+            pid: 999999999,
+            id: 'stale-instance',
+            startedAt: Date.now(),
+            heartbeatAt: Date.now(),
+        }));
+        const { DaemonContext } = await import('../daemon.js');
+        const ctx = new DaemonContext('stale-test', 'cmd', ['node', 'test']);
+        expect(await ctx.isRunning()).toBe(false);
+        // PID file should have been cleaned up
+        expect(fs.existsSync(pidFile)).toBe(false);
+    });
+    test('PID file with stale heartbeat is treated as not running', async () => {
+        const pidFile = pidFilePath('heartbeat-test', 'cmd');
+        testPidFiles.push(pidFile);
+        // Write a PID file with current process PID but very old heartbeat
+        fs.mkdirSync(path.dirname(pidFile), { recursive: true });
+        fs.writeFileSync(pidFile, JSON.stringify({
+            pid: process.pid, // alive PID
+            id: 'old-heartbeat',
+            startedAt: Date.now() - 60000,
+            heartbeatAt: Date.now() - 60000, // 60s old, well past the 15s threshold
+        }));
+        const { DaemonContext } = await import('../daemon.js');
+        const ctx = new DaemonContext('heartbeat-test', 'cmd', ['node', 'test']);
+        // Should return false because heartbeat is stale (even though PID is alive)
+        expect(await ctx.isRunning()).toBe(false);
+    });
+    test('daemon context has correct command name from parsed cli', async () => {
+        const { default: goke } = await import('../index.js');
+        const cli = goke('my-app');
+        let capturedDaemon;
+        cli.command('auth login', 'Login').action((opts, ctx) => {
+            capturedDaemon = ctx.daemon;
+        });
+        await cli.parse(['node', 'my-app', 'auth', 'login'], { run: true });
+        expect(capturedDaemon).toBeDefined();
+        expect(capturedDaemon.isDaemon).toBe(false);
+    });
+});

package/dist/__test__/index.test.js

@@ -115,7 +115,7 @@ describe('error formatting', () => {
         expect(exitCode).toBe(1);
         expect(stripStackTrace(stderr.text)).toMatchInlineSnapshot(`"error: connection refused"`);
     });
-    test('error output includes stack trace', async () => {
+    test('GokeError (validation) omits stack trace', async () => {
         const stderr = createTestOutputStream();
         const cli = goke('mycli', { stderr, exit: () => { } });
         cli
@@ -125,10 +125,26 @@ describe('error formatting', () => {
             await cli.parse('node bin build --unknown'.split(' '));
         }
         catch { }
-        // Verify that stderr contains "error:" prefix and a stack trace with "at" lines
         const text = stderr.text;
         expect(text).toContain('error:');
         expect(text).toContain('Unknown option `--unknown`');
+        // GokeError is a user-facing error; stack trace should be suppressed
+        expect(text).not.toMatch(/at /);
+    });
+    test('unexpected error still includes stack trace', async () => {
+        const stderr = createTestOutputStream();
+        const cli = goke('mycli', { stderr, exit: () => { } });
+        cli
+            .command('deploy', 'Deploy app')
+            .action(async () => {
+            throw new Error('unexpected crash');
+        });
+        await cli.parse('node bin deploy'.split(' '));
+        await new Promise(resolve => setTimeout(resolve, 10));
+        const text = stderr.text;
+        expect(text).toContain('error:');
+        expect(text).toContain('unexpected crash');
+        // Non-GokeError should still show the stack trace
         expect(text).toMatch(/at /);
     });
 });

package/dist/daemon-browser.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Browser-safe daemon stub.
+ *
+ * Provides the same DaemonContext interface as daemon.ts but without
+ * Node.js dependencies. start() throws; everything else is a no-op.
+ * Used via the #daemon conditional import in browser/edge runtimes.
+ */
+declare class DaemonContext {
+    readonly isDaemon: false;
+    constructor();
+    forCommand(_commandName: string): DaemonContext;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    isRunning(): Promise<boolean>;
+}
+declare function createDaemonContext(): DaemonContext;
+export { DaemonContext, createDaemonContext };
+export type { DaemonStartOptions } from './daemon.js';
+//# sourceMappingURL=daemon-browser.d.ts.map

package/dist/daemon-browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-browser.d.ts","sourceRoot":"","sources":["../src/daemon-browser.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAM,aAAa;IACjB,QAAQ,CAAC,QAAQ,EAAG,KAAK,CAAS;;IAIlC,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa;IAIzC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAErB,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;CAGpC;AAED,iBAAS,mBAAmB,IAAI,aAAa,CAE5C;AAED,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,CAAA;AAC7C,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA"}

package/dist/daemon-browser.js

@@ -0,0 +1,25 @@
+/**
+ * Browser-safe daemon stub.
+ *
+ * Provides the same DaemonContext interface as daemon.ts but without
+ * Node.js dependencies. start() throws; everything else is a no-op.
+ * Used via the #daemon conditional import in browser/edge runtimes.
+ */
+class DaemonContext {
+    isDaemon = false;
+    constructor() { }
+    forCommand(_commandName) {
+        return new DaemonContext();
+    }
+    async start() {
+        throw new Error('ctx.daemon.start() is only available in Node.js runtimes.');
+    }
+    async stop() { }
+    async isRunning() {
+        return false;
+    }
+}
+function createDaemonContext() {
+    return new DaemonContext();
+}
+export { DaemonContext, createDaemonContext };

package/dist/daemon.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Background daemon support for goke CLIs.
+ *
+ * Lets a command fork itself into a detached background process. The daemon
+ * is identified by CLI name + command name, with a PID file for lifecycle
+ * management. No HTTP server, no ports. Communication between client and
+ * daemon happens via shared files (config, auth, state) that the CLI
+ * already manages.
+ *
+ * How it works:
+ *   1. Command action checks `ctx.daemon.isDaemon` to branch behavior
+ *   2. Client calls `ctx.daemon.start()` which re-spawns the same CLI
+ *      command with GOKE_DAEMON=1 env var, detached + unref'd
+ *   3. Daemon process runs the same action, but `isDaemon` is true
+ *   4. Daemon auto-exits after timeoutMs
+ *   5. PID file tracks the running daemon for stop/isRunning checks
+ *
+ * PID file safety:
+ *   Each daemon writes a unique instance ID (random hex) into the PID file.
+ *   A heartbeat timestamp is updated every 5 seconds. `isRunning()` checks
+ *   both that the PID is alive AND the heartbeat is recent (< 15s). This
+ *   prevents false positives from PID reuse after a daemon crash.
+ *   Cleanup handlers only remove the PID file if its ID matches the current
+ *   instance, so a new daemon won't have its file deleted by an old one's
+ *   exit handler firing late.
+ */
+interface DaemonStartOptions {
+    /** Auto-exit timeout in milliseconds. Default: 10 minutes. */
+    timeoutMs?: number;
+    /** Extra environment variables passed to the daemon process. */
+    env?: Record<string, string>;
+}
+/**
+ * Daemon context available on every command's execution context.
+ *
+ * Lets a command fork itself into a background process. The client side
+ * calls `start()` to spawn the daemon. The daemon side checks `isDaemon`
+ * and does its work. Communication happens via shared files.
+ *
+ * Use `forCommand()` to get a daemon context for a different command.
+ * This is useful for commands like `me` or `logout` that need to check
+ * or stop the `login` daemon.
+ */
+declare class DaemonContext {
+    #private;
+    /** True when this process IS the background daemon. */
+    readonly isDaemon: boolean;
+    constructor(cliName: string, commandName: string, argv: string[], env?: Record<string, string | undefined>);
+    /**
+     * Get a daemon context for a different command on the same CLI.
+     * Useful for cross-command daemon management (e.g. `me` checking `login` daemon).
+     *
+     * The returned context is always in client mode (isDaemon=false) regardless
+     * of the current process's daemon state, since it represents a different command.
+     */
+    forCommand(commandName: string): DaemonContext;
+    /**
+     * Spawn the current command as a detached background daemon process.
+     * Kills any existing daemon for this command first.
+     */
+    start(options?: DaemonStartOptions): Promise<void>;
+    /**
+     * Stop the running daemon for this command.
+     */
+    stop(): Promise<void>;
+    /**
+     * Check if the daemon for this command is currently running.
+     * Verifies both that the PID is alive and the heartbeat is recent
+     * to protect against PID reuse after a crash.
+     */
+    isRunning(): Promise<boolean>;
+}
+/**
+ * Create a DaemonContext for a command.
+ * Called internally by goke when building the execution context.
+ */
+declare function createDaemonContext(cliName: string, commandName: string, argv: string[], env?: Record<string, string | undefined>): DaemonContext;
+export { DaemonContext, createDaemonContext };
+export type { DaemonStartOptions };
+//# sourceMappingURL=daemon.d.ts.map

package/dist/daemon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../src/daemon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AA6IH,UAAU,kBAAkB;IAC1B,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,gEAAgE;IAChE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC7B;AAED;;;;;;;;;;GAUG;AACH,cAAM,aAAa;;IACjB,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;gBAYxB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAc1C;;;;;;OAMG;IACH,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa;IAkF9C;;;OAGG;IACG,KAAK,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAuCxD;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAkB3B;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;CAcpC;AAED;;;GAGG;AACH,iBAAS,mBAAmB,CAC1B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACvC,aAAa,CAEf;AAED,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,CAAA;AAC7C,YAAY,EAAE,kBAAkB,EAAE,CAAA"}