goke 6.13.0 → 6.14.1

package/dist/__test__/daemon.test.js

@@ -282,6 +282,97 @@ process.exit(0)
         // Should return false because heartbeat is stale (even though PID is alive)
         expect(await ctx.isRunning()).toBe(false);
     });
+    test('start with attach: true pipes stdout/stderr and waits for exit', async () => {
+        const helperScript = path.join(os.tmpdir(), 'goke-daemon-test-attach.mjs');
+        // This helper writes to stdout/stderr and exits after a short delay.
+        // The PID file setup mirrors the standard daemon helper.
+        fs.writeFileSync(helperScript, `
+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 || 'attach-test'
+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 })
+
+// Write to stdout and stderr so the parent can see it
+console.log('DAEMON_STDOUT_MESSAGE')
+console.error('DAEMON_STDERR_MESSAGE')
+
+// Exit after a short delay
+setTimeout(() => {
+  try {
+    const current = JSON.parse(fs.readFileSync(pidFile, 'utf-8'))
+    if (current.id === instanceId) fs.unlinkSync(pidFile)
+  } catch {}
+  process.exit(0)
+}, 500)
+`);
+        testPidFiles.push(pidFilePath('test-daemon-cli', 'attach-test'));
+        const { DaemonContext } = await import('../daemon.js');
+        const ctx = new DaemonContext('test-daemon-cli', 'attach-test', [
+            process.execPath, helperScript, 'attach-test',
+        ]);
+        // attach: true should wait for the daemon to finish
+        await ctx.start({ attach: true, timeoutMs: 10_000 });
+        // After start resolves, the daemon should have exited and cleaned up its PID file
+        expect(await ctx.isRunning()).toBe(false);
+        try {
+            fs.unlinkSync(helperScript);
+        }
+        catch { }
+    }, 15_000);
+    test('start with attach: true throws on non-zero exit', async () => {
+        const helperScript = path.join(os.tmpdir(), 'goke-daemon-test-attach-fail.mjs');
+        fs.writeFileSync(helperScript, `
+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 || 'attach-fail'
+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 })
+
+console.error('Something went wrong')
+
+setTimeout(() => {
+  try {
+    const current = JSON.parse(fs.readFileSync(pidFile, 'utf-8'))
+    if (current.id === instanceId) fs.unlinkSync(pidFile)
+  } catch {}
+  process.exit(1)
+}, 500)
+`);
+        testPidFiles.push(pidFilePath('test-daemon-cli', 'attach-fail'));
+        const { DaemonContext } = await import('../daemon.js');
+        const ctx = new DaemonContext('test-daemon-cli', 'attach-fail', [
+            process.execPath, helperScript, 'attach-fail',
+        ]);
+        await expect(ctx.start({ attach: true, timeoutMs: 10_000 }))
+            .rejects.toThrow('exited with code 1');
+        try {
+            fs.unlinkSync(helperScript);
+        }
+        catch { }
+    }, 15_000);
     test('daemon context has correct command name from parsed cli', async () => {
         const { default: goke } = await import('../index.js');
         const cli = goke('my-app');

package/dist/daemon.d.ts

@@ -29,6 +29,15 @@ interface DaemonStartOptions {
     timeoutMs?: number;
     /** Extra environment variables passed to the daemon process. */
     env?: Record<string, string>;
+    /**
+     * When true, pipe daemon stdout/stderr to the parent process and wait
+     * for the daemon to exit before resolving. This lets interactive users
+     * see real-time logs and error messages from the daemon.
+     *
+     * When false (default), the daemon runs fully detached with no stdio
+     * and start() returns as soon as the PID file is confirmed.
+     */
+    attach?: boolean;
 }
 /**
  * Daemon context available on every command's execution context.
@@ -57,6 +66,11 @@ declare class DaemonContext {
     /**
      * Spawn the current command as a detached background daemon process.
      * Kills any existing daemon for this command first.
+     *
+     * When `attach: true`, pipes daemon stdout/stderr to the parent and
+     * waits for the daemon to exit. Throws if the daemon exits with a
+     * non-zero code. This is useful for interactive login flows where the
+     * user wants to see real-time logs and error messages.
      */
     start(options?: DaemonStartOptions): Promise<void>;
     /**

package/dist/daemon.d.ts.map

@@ -1 +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"}
+{"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;IAC5B;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;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;;;;;;;;OAQG;IACG,KAAK,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAoExD;;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"}

package/dist/daemon.js

@@ -259,9 +259,15 @@ class DaemonContext {
     /**
      * Spawn the current command as a detached background daemon process.
      * Kills any existing daemon for this command first.
+     *
+     * When `attach: true`, pipes daemon stdout/stderr to the parent and
+     * waits for the daemon to exit. Throws if the daemon exits with a
+     * non-zero code. This is useful for interactive login flows where the
+     * user wants to see real-time logs and error messages.
      */
     async start(options) {
         const timeoutMs = options?.timeoutMs ?? 10 * 60 * 1000;
+        const attach = options?.attach ?? false;
         // Kill existing daemon if running
         await this.stop();
         const env = {
@@ -275,18 +281,47 @@ class DaemonContext {
         const execPath = this.#argv[0];
         const args = this.#argv.slice(1);
         const child = spawn(execPath, args, {
-            detached: true,
-            stdio: 'ignore',
+            // Detach only when running in background so the daemon outlives the
+            // parent. In attached mode, keep the child in the same process group
+            // so signals propagate naturally and the parent stays alive.
+            detached: !attach,
+            stdio: attach ? ['ignore', 'inherit', 'inherit'] : 'ignore',
             env,
         });
-        child.unref();
+        // Only unref when detached (non-attached) so the parent can exit
+        // immediately. In attached mode, the parent must stay alive to wait for
+        // the child's 'close' event — unref() would let the event loop drain
+        // and the parent would exit before the child finishes.
+        if (!attach) {
+            child.unref();
+        }
+        // Register close/error listeners immediately after spawn, before the
+        // PID file polling loop. If the child exits very quickly (writes PID
+        // file then exits), registering listeners after seeing the PID file
+        // could miss the 'close' event and hang the promise forever.
+        let childDone;
+        if (attach) {
+            childDone = new Promise((resolve, reject) => {
+                child.on('close', (code) => {
+                    if (code && code !== 0) {
+                        reject(new Error(`Daemon "${this.#cliName} ${this.#commandName}" exited with code ${code}`));
+                    }
+                    else {
+                        resolve();
+                    }
+                });
+                child.on('error', reject);
+            });
+        }
         // Brief wait to confirm the daemon started and wrote its PID file
         const startDeadline = Date.now() + 5000;
         while (Date.now() < startDeadline) {
             await new Promise((r) => setTimeout(r, 100));
             const pidData = readPidFile(this.#pidFile);
             if (pidData && isProcessAlive(pidData.pid)) {
-                return;
+                if (!attach)
+                    return;
+                return childDone;
             }
         }
         throw new Error(`Failed to start daemon for "${this.#cliName} ${this.#commandName}"`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "goke",
-  "version": "6.13.0",
+  "version": "6.14.1",
   "type": "module",
   "description": "Simple yet powerful framework for building command-line apps. Inspired by cac.",
   "repository": {

package/src/__test__/daemon.test.ts

@@ -318,6 +318,100 @@ process.exit(0)
     expect(await ctx.isRunning()).toBe(false)
   })
 
+  test('start with attach: true pipes stdout/stderr and waits for exit', async () => {
+    const helperScript = path.join(os.tmpdir(), 'goke-daemon-test-attach.mjs')
+    // This helper writes to stdout/stderr and exits after a short delay.
+    // The PID file setup mirrors the standard daemon helper.
+    fs.writeFileSync(helperScript, `
+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 || 'attach-test'
+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 })
+
+// Write to stdout and stderr so the parent can see it
+console.log('DAEMON_STDOUT_MESSAGE')
+console.error('DAEMON_STDERR_MESSAGE')
+
+// Exit after a short delay
+setTimeout(() => {
+  try {
+    const current = JSON.parse(fs.readFileSync(pidFile, 'utf-8'))
+    if (current.id === instanceId) fs.unlinkSync(pidFile)
+  } catch {}
+  process.exit(0)
+}, 500)
+`)
+    testPidFiles.push(pidFilePath('test-daemon-cli', 'attach-test'))
+
+    const { DaemonContext } = await import('../daemon.js')
+    const ctx = new DaemonContext('test-daemon-cli', 'attach-test', [
+      process.execPath, helperScript, 'attach-test',
+    ])
+
+    // attach: true should wait for the daemon to finish
+    await ctx.start({ attach: true, timeoutMs: 10_000 })
+
+    // After start resolves, the daemon should have exited and cleaned up its PID file
+    expect(await ctx.isRunning()).toBe(false)
+
+    try { fs.unlinkSync(helperScript) } catch {}
+  }, 15_000)
+
+  test('start with attach: true throws on non-zero exit', async () => {
+    const helperScript = path.join(os.tmpdir(), 'goke-daemon-test-attach-fail.mjs')
+    fs.writeFileSync(helperScript, `
+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 || 'attach-fail'
+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 })
+
+console.error('Something went wrong')
+
+setTimeout(() => {
+  try {
+    const current = JSON.parse(fs.readFileSync(pidFile, 'utf-8'))
+    if (current.id === instanceId) fs.unlinkSync(pidFile)
+  } catch {}
+  process.exit(1)
+}, 500)
+`)
+    testPidFiles.push(pidFilePath('test-daemon-cli', 'attach-fail'))
+
+    const { DaemonContext } = await import('../daemon.js')
+    const ctx = new DaemonContext('test-daemon-cli', 'attach-fail', [
+      process.execPath, helperScript, 'attach-fail',
+    ])
+
+    await expect(ctx.start({ attach: true, timeoutMs: 10_000 }))
+      .rejects.toThrow('exited with code 1')
+
+    try { fs.unlinkSync(helperScript) } catch {}
+  }, 15_000)
+
   test('daemon context has correct command name from parsed cli', async () => {
     const { default: goke } = await import('../index.js')
     const cli = goke('my-app')

package/src/daemon.ts

@@ -169,6 +169,15 @@ interface DaemonStartOptions {
   timeoutMs?: number
   /** Extra environment variables passed to the daemon process. */
   env?: Record<string, string>
+  /**
+   * When true, pipe daemon stdout/stderr to the parent process and wait
+   * for the daemon to exit before resolving. This lets interactive users
+   * see real-time logs and error messages from the daemon.
+   *
+   * When false (default), the daemon runs fully detached with no stdio
+   * and start() returns as soon as the PID file is confirmed.
+   */
+  attach?: boolean
 }
 
 /**
@@ -305,9 +314,15 @@ class DaemonContext {
   /**
    * Spawn the current command as a detached background daemon process.
    * Kills any existing daemon for this command first.
+   *
+   * When `attach: true`, pipes daemon stdout/stderr to the parent and
+   * waits for the daemon to exit. Throws if the daemon exits with a
+   * non-zero code. This is useful for interactive login flows where the
+   * user wants to see real-time logs and error messages.
    */
   async start(options?: DaemonStartOptions): Promise<void> {
     const timeoutMs = options?.timeoutMs ?? 10 * 60 * 1000
+    const attach = options?.attach ?? false
 
     // Kill existing daemon if running
     await this.stop()
@@ -325,12 +340,39 @@ class DaemonContext {
     const args = this.#argv.slice(1)
 
     const child = spawn(execPath, args, {
-      detached: true,
-      stdio: 'ignore',
+      // Detach only when running in background so the daemon outlives the
+      // parent. In attached mode, keep the child in the same process group
+      // so signals propagate naturally and the parent stays alive.
+      detached: !attach,
+      stdio: attach ? ['ignore', 'inherit', 'inherit'] : 'ignore',
       env,
     })
 
-    child.unref()
+    // Only unref when detached (non-attached) so the parent can exit
+    // immediately. In attached mode, the parent must stay alive to wait for
+    // the child's 'close' event — unref() would let the event loop drain
+    // and the parent would exit before the child finishes.
+    if (!attach) {
+      child.unref()
+    }
+
+    // Register close/error listeners immediately after spawn, before the
+    // PID file polling loop. If the child exits very quickly (writes PID
+    // file then exits), registering listeners after seeing the PID file
+    // could miss the 'close' event and hang the promise forever.
+    let childDone: Promise<void> | undefined
+    if (attach) {
+      childDone = new Promise<void>((resolve, reject) => {
+        child.on('close', (code) => {
+          if (code && code !== 0) {
+            reject(new Error(`Daemon "${this.#cliName} ${this.#commandName}" exited with code ${code}`))
+          } else {
+            resolve()
+          }
+        })
+        child.on('error', reject)
+      })
+    }
 
     // Brief wait to confirm the daemon started and wrote its PID file
     const startDeadline = Date.now() + 5000
@@ -338,7 +380,8 @@ class DaemonContext {
       await new Promise((r) => setTimeout(r, 100))
       const pidData = readPidFile(this.#pidFile)
       if (pidData && isProcessAlive(pidData.pid)) {
-        return
+        if (!attach) return
+        return childDone
       }
     }