@aliou/pi-processes 0.11.2 → 0.12.0

package/extensions/processes/handlers/commands.ts

@@ -4,6 +4,7 @@ import type { ProcessManager } from "../../../src/manager";
 import type { KillResult } from "../../../src/types";
 import {
   CHANNELS,
+  type CommandAdoptPayload,
   type CommandClearPayload,
   type CommandKillPayload,
   type CommandStartPayload,
@@ -51,13 +52,36 @@ export function registerCommandHandlers(
 
       safeReply(command.reply, manager.clearFinished());
     }),
+    events.on(CHANNELS.COMMAND_ADOPT, (payload) => {
+      const command = payload as CommandAdoptPayload;
+
+      try {
+        const info = manager.adopt(
+          command.name,
+          command.command,
+          command.cwd,
+          command.child,
+          {
+            initialStdout: command.initialStdout,
+            initialStderr: command.initialStderr,
+            startTime: command.startTime,
+          },
+        );
+        notifications.register(info.id, {});
+        safeReply(command.reply, { ok: true, info });
+      } catch (error) {
+        safeReply(command.reply, {
+          ok: false,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }),
   ];
 
   return () => {
     for (const dispose of disposers) dispose();
   };
 }
-
 function safeReply<T>(reply: (result: T) => void, result: T): void {
   try {
     reply(result);

package/extensions/shared/protocol/channels.ts

@@ -18,6 +18,9 @@ export const CHANNELS = {
   COMMAND_START: "processes:command:start",
   COMMAND_KILL: "processes:command:kill",
   COMMAND_CLEAR: "processes:command:clear",
+  // Other extensions emit this to hand an already-running child process
+  // over to the manager (e.g. backgrounding a foreground tool command).
+  COMMAND_ADOPT: "processes:command:adopt",
   // Pin handled by the dock extension, if loaded.
   COMMAND_PIN: "processes:command:pin",
 

package/extensions/shared/protocol/commands.ts

@@ -1,3 +1,5 @@
+import type { ChildProcess } from "node:child_process";
+
 import type { KillResult, ProcessInfo } from "../../../src/types";
 
 // UI emits, core handles then calls reply.
@@ -33,3 +35,27 @@ export interface CommandPinPayload {
 }
 
 export type CommandPinResult = { ok: true } | { ok: false; error: string };
+
+// Another extension emits this to hand an already-running child process over
+// to the manager. The child must have been spawned in a detached process
+// group (`detached: true`) with piped stdio — the same shape the manager's
+// own spawns use — so group kill and liveness polling work on it. Payloads
+// cross the event bus by reference, so the live ChildProcess handle arrives
+// intact. If the processes extension is not loaded, no listener replies.
+export interface CommandAdoptPayload {
+  name: string;
+  command: string;
+  cwd: string;
+  child: ChildProcess;
+  /** Stdout captured before handover. */
+  initialStdout?: Buffer;
+  /** Stderr captured before handover. */
+  initialStderr?: Buffer;
+  /** When the command actually started (epoch ms). */
+  startTime?: number;
+  reply: (result: CommandAdoptResult) => void;
+}
+
+export type CommandAdoptResult =
+  | { ok: true; info: ProcessInfo }
+  | { ok: false; error: string };

package/extensions/shared/protocol/index.ts

@@ -6,6 +6,8 @@ export type {
 } from "./broadcasts";
 export { CHANNELS } from "./channels";
 export type {
+  CommandAdoptPayload,
+  CommandAdoptResult,
   CommandClearPayload,
   CommandKillPayload,
   CommandPinPayload,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-processes",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "license": "MIT",
   "type": "module",
   "private": false,

package/src/manager/index.ts

@@ -1,6 +1,8 @@
+import type { ChildProcess } from "node:child_process";
 import { EventEmitter } from "node:events";
 
 import type {
+  AdoptProcessOptions,
   KillResult,
   ManagerEvent,
   ProcessInfo,
@@ -57,6 +59,22 @@ export class ProcessManager {
     return formatProcess(managed);
   }
 
+  /**
+   * Adopt an externally spawned child process. The child must run in a
+   * detached process group with piped stdio (see
+   * ProcessRuntimeController.adopt for the full contract).
+   */
+  adopt(
+    name: string,
+    command: string,
+    cwd: string,
+    child: ChildProcess,
+    opts?: AdoptProcessOptions,
+  ): ProcessInfo {
+    const managed = this.runtime.adopt(name, command, cwd, child, opts);
+    return formatProcess(managed);
+  }
+
   list(): ProcessInfo[] {
     return this.registry.list();
   }

package/src/manager/process-log-store.ts

@@ -13,7 +13,7 @@ import {
 } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-
+import { trimIncompleteUtf8Suffix } from "../utils/buffer";
 import type { ProcessLogPaths } from "./internal-types";
 import { MAX_LOG_FILE_BYTES, MAX_TAIL_READ_BYTES } from "./limits";
 
@@ -401,22 +401,3 @@ function decodeUtf8Bounded(buffer: Buffer, maxOutputBytes: number): string {
 
   return parts.join("");
 }
-
-function trimIncompleteUtf8Suffix(buffer: Buffer): Buffer {
-  if (buffer.length === 0) return buffer;
-  let lead = buffer.length - 1;
-  while (lead >= 0 && (buffer[lead] & 0xc0) === 0x80) lead--;
-  if (lead < 0) return Buffer.alloc(0);
-  const byte = buffer[lead];
-  const expected =
-    byte < 0x80
-      ? 1
-      : (byte & 0xe0) === 0xc0
-        ? 2
-        : (byte & 0xf0) === 0xe0
-          ? 3
-          : (byte & 0xf8) === 0xf0
-            ? 4
-            : 1;
-  return buffer.length - lead < expected ? buffer.subarray(0, lead) : buffer;
-}

package/src/manager/process-output.ts

@@ -1,4 +1,5 @@
 import type { ManagerEvent } from "../types";
+import { trimIncompleteUtf8Suffix } from "../utils/buffer";
 import type { ManagedProcessRecord } from "./internal-types";
 import {
   MAX_LINE_BYTES,
@@ -321,25 +322,3 @@ export class ProcessOutput {
     this.clearAll();
   }
 }
-
-function trimIncompleteUtf8Suffix(buffer: Buffer): Buffer {
-  if (buffer.length === 0) return buffer;
-
-  let lead = buffer.length - 1;
-  while (lead >= 0 && (buffer[lead] & 0xc0) === 0x80) lead--;
-  if (lead < 0) return Buffer.alloc(0);
-
-  const leadByte = buffer[lead];
-  const expectedLength =
-    leadByte < 0x80
-      ? 1
-      : (leadByte & 0xe0) === 0xc0
-        ? 2
-        : (leadByte & 0xf0) === 0xe0
-          ? 3
-          : (leadByte & 0xf8) === 0xf0
-            ? 4
-            : 1;
-  const actualLength = buffer.length - lead;
-  return actualLength < expectedLength ? buffer.subarray(0, lead) : buffer;
-}

package/src/manager/process-runtime-controller.ts

@@ -1,13 +1,23 @@
 import type { ChildProcess } from "node:child_process";
 
-import type { KillResult, ManagerEvent, WriteResult } from "../types";
+import type {
+  AdoptProcessOptions,
+  KillResult,
+  ManagerEvent,
+  WriteResult,
+} from "../types";
 import { LIVE_STATUSES } from "../types";
 import { isProcessGroupAlive, killProcessGroup } from "../utils";
+import { clampToTail } from "../utils/buffer";
 import { spawnCommand } from "../utils/command-executor";
 import { formatSignalInfo } from "../utils/signals";
 import type { ManagedProcessRecord } from "./internal-types";
 import { formatProcess } from "./internal-types";
-import { FINISHED_RECORD_GRACE_MS, MAX_FINISHED_RECORDS } from "./limits";
+import {
+  FINISHED_RECORD_GRACE_MS,
+  MAX_FINISHED_RECORDS,
+  MAX_TAIL_READ_BYTES,
+} from "./limits";
 import type { ProcessLogStore } from "./process-log-store";
 import type { ProcessOutput } from "./process-output";
 import type { ProcessRegistry } from "./process-registry";
@@ -41,10 +51,45 @@ export class ProcessRuntimeController {
   }
 
   start(name: string, command: string, cwd: string): ManagedProcessRecord {
+    const child = spawnCommand(command, cwd, this.getConfiguredShellPath());
+    return this.register(name, command, cwd, child, {});
+  }
+
+  /**
+   * Adopt an externally spawned child process into the manager.
+   *
+   * The child must have been spawned like `spawnCommand` spawns: in a
+   * detached process group (`detached: true`) with piped stdio, so group
+   * kill and liveness polling behave identically to started processes.
+   *
+   * `initialStdout` / `initialStderr` are pre-handover output, each
+   * prepended to the matching log and clamped to MAX_TAIL_READ_BYTES.
+   * `startTime` backdates the record to when the command actually began.
+   */
+  adopt(
+    name: string,
+    command: string,
+    cwd: string,
+    child: ChildProcess,
+    opts?: AdoptProcessOptions,
+  ): ManagedProcessRecord {
+    return this.register(name, command, cwd, child, {
+      initialStdout: opts?.initialStdout,
+      initialStderr: opts?.initialStderr,
+      startTime: opts?.startTime,
+    });
+  }
+
+  private register(
+    name: string,
+    command: string,
+    cwd: string,
+    child: ChildProcess,
+    opts: AdoptProcessOptions,
+  ): ManagedProcessRecord {
     const id = this.registry.nextId();
     const logPaths = this.logs.createLogs(id);
 
-    const child = spawnCommand(command, cwd, this.getConfiguredShellPath());
     // Spawned commands run in detached process groups so TERM/KILL can target
     // the whole tree. `unref()` keeps the manager's Node process from staying
     // alive only because a managed child still exists; extension shutdown and
@@ -57,7 +102,7 @@ export class ProcessRuntimeController {
       pid: child.pid ?? -1,
       command,
       cwd,
-      startTime: Date.now(),
+      startTime: opts.startTime ?? Date.now(),
       endTime: null,
       status: "running",
       exitCode: null,
@@ -107,14 +152,64 @@ export class ProcessRuntimeController {
       return managed;
     }
 
+    if (opts.initialStdout && opts.initialStdout.length > 0) {
+      const clamped = clampToTail(opts.initialStdout, MAX_TAIL_READ_BYTES);
+      this.logs.appendStdout(managed.stdoutFile, clamped);
+      this.output.onStdoutChunk(managed, clamped);
+    }
+    if (opts.initialStderr && opts.initialStderr.length > 0) {
+      const clamped = clampToTail(opts.initialStderr, MAX_TAIL_READ_BYTES);
+      this.logs.appendStderr(managed.stderrFile, clamped);
+      this.output.onStderrChunk(managed, clamped);
+    }
+
     this.wireStdioHandlers(managed, child);
 
     this.emit({ type: "process_started", info: formatProcess(managed) });
+    this.finalizeIfAlreadyClosed(managed, child);
     this.ensureWatcherRunning();
 
     return managed;
   }
 
+  /**
+   * An adopted child may have fully exited (close event fired) before its
+   * handlers were attached here. In that case no close event will ever
+   * reach wireStdioHandlers, so replay the close classification directly.
+   * If the child exited but its streams are still open, the pending close
+   * event will finalize the record through the normal path.
+   */
+  private finalizeIfAlreadyClosed(
+    managed: ManagedProcessRecord,
+    child: ChildProcess,
+  ): void {
+    const exited = child.exitCode !== null || child.signalCode !== null;
+    if (!exited) return;
+
+    const streamsDone =
+      (child.stdout?.destroyed ?? true) && (child.stderr?.destroyed ?? true);
+    if (!streamsDone) return;
+
+    this.releaseRuntimeHandles(managed);
+    if (managed.endTime) return;
+
+    managed.exitCode = child.exitCode;
+    managed.endTime = Date.now();
+    this.output.flush(managed);
+
+    if (child.signalCode) {
+      managed.success = false;
+      managed.endReason = "signal";
+      managed.signal = formatSignalInfo(child.signalCode);
+      this.transition(managed, "killed");
+    } else {
+      managed.success = child.exitCode === 0;
+      managed.endReason = "exit";
+      managed.signal = null;
+      this.transition(managed, "exited");
+    }
+  }
+
   transition(managed: ManagedProcessRecord, next: typeof managed.status): void {
     if (managed.status === next) return;
     managed.status = next;

package/src/types.ts

@@ -54,6 +54,16 @@ export type ManagerEvent =
     }
   | { type: "processes_changed" };
 
+/** Options for adopting an externally spawned child process. */
+export interface AdoptProcessOptions {
+  /** Pre-handover stdout; prepended to the stdout log, clamped to MAX_TAIL_READ_BYTES. */
+  initialStdout?: Buffer;
+  /** Pre-handover stderr; prepended to the stderr log, clamped to MAX_TAIL_READ_BYTES. */
+  initialStderr?: Buffer;
+  /** When the command actually started (epoch ms). Defaults to adoption time. */
+  startTime?: number;
+}
+
 export type KillResult =
   | { ok: true; info: ProcessInfo }
   | { ok: false; info: ProcessInfo; reason: "not_found" | "timeout" | "error" };

package/src/utils/buffer.ts

@@ -0,0 +1,28 @@
+/** Trim trailing bytes that form an incomplete UTF-8 code point. */
+export function trimIncompleteUtf8Suffix(buffer: Buffer): Buffer {
+  if (buffer.length === 0) return buffer;
+
+  let lead = buffer.length - 1;
+  while (lead >= 0 && (buffer[lead] & 0xc0) === 0x80) lead--;
+  if (lead < 0) return Buffer.alloc(0);
+
+  const leadByte = buffer[lead];
+  const expectedLength =
+    leadByte < 0x80
+      ? 1
+      : (leadByte & 0xe0) === 0xc0
+        ? 2
+        : (leadByte & 0xf0) === 0xe0
+          ? 3
+          : (leadByte & 0xf8) === 0xf0
+            ? 4
+            : 1;
+  const actualLength = buffer.length - lead;
+  return actualLength < expectedLength ? buffer.subarray(0, lead) : buffer;
+}
+
+/** Keep the last `maxBytes` of a buffer, trimming any incomplete UTF-8 sequence. */
+export function clampToTail(buf: Buffer, maxBytes: number): Buffer {
+  if (buf.length <= maxBytes) return buf;
+  return trimIncompleteUtf8Suffix(buf.subarray(buf.length - maxBytes));
+}

package/src/utils/index.ts

@@ -1,4 +1,5 @@
 export { hasAnsi, stripAnsi } from "./ansi";
+export { clampToTail, trimIncompleteUtf8Suffix } from "./buffer";
 export { resolveShellExecutable, spawnCommand } from "./command-executor";
 export { formatRuntime, formatStatus, formatTimestamp } from "./format";
 export type { LineMatchMode } from "./match-line";