@qlzt/dsh-subprocess-local 0.0.0-stage → 0.2.1-alpha.2

package/lib/types/terminal.d.ts

@@ -0,0 +1,80 @@
+/** Local node-pty terminal-process implementation for the subprocess seam. */
+import { PassThrough } from 'node:stream';
+import type { IPty } from 'node-pty';
+import type { SubprocessOutcome, SubprocessTerminalActivity, SubprocessTerminalForeground, SubprocessTerminalHandle, SubprocessTerminalSignal } from '@qlzt/dsh-subprocess';
+import type { BoundProcessOwner } from './managed-owner.ts';
+import type { ProcessInspector } from './process-inspector.ts';
+import type { ShellActivity } from './shell-activity.ts';
+/**
+ * A local terminal whose native managed range or fallback process-session
+ * ownership stays below the PTY backend.
+ * The seam's terminate() promise — no write, inspection, or signal in flight
+ * after settlement — holds here without operation tracking only because every
+ * handle call completes synchronously under the hood (node-pty write, ps-based
+ * inspection). A first genuinely asynchronous step in any handle call must add
+ * the tracking a remote provider needs.
+ */
+export declare class LocalTerminalHandle implements SubprocessTerminalHandle {
+    private readonly terminal;
+    private readonly inspector;
+    private readonly graceMs;
+    private readonly platform;
+    private readonly managedOwner?;
+    private readonly resolveManagedOutcome?;
+    private readonly shellActivity?;
+    private readonly onQuiescence?;
+    private readonly observeShellExit;
+    readonly pid: number;
+    readonly output: PassThrough;
+    readonly done: Promise<SubprocessOutcome>;
+    private readonly outcome;
+    private readonly dataDisposable;
+    private readonly exitDisposable;
+    private cleanup;
+    private managedOwnerCleaned;
+    private exited;
+    private outputPaused;
+    private trackedDescendants;
+    private activityRevision;
+    private activityKey;
+    private quiescent;
+    private managedRangeEmpty;
+    /** The spawned shell's start identity; scans stop adopting members once the root pid no longer carries it. */
+    private readonly rootIdentity;
+    /**
+     * @param terminal - allocated node-pty process.
+     * @param inspector - platform process/session operations.
+     * @param graceMs - TERM-to-KILL and exit-wait grace.
+     * @param platform - host platform; defaults to the running platform, injectable for deterministic tests.
+     */
+    constructor(terminal: IPty, inspector: ProcessInspector, graceMs: number, platform?: NodeJS.Platform, managedOwner?: BoundProcessOwner | undefined, resolveManagedOutcome?: ((outcome: SubprocessOutcome) => SubprocessOutcome) | undefined, shellActivity?: Pick<ShellActivity, "inspect" | "invalidate" | "dispose"> | undefined, onQuiescence?: (() => void) | undefined, observeShellExit?: boolean);
+    /** Whether node-pty has not yet published the top-level exit event. */
+    get running(): boolean;
+    write(data: string): Promise<void>;
+    resize(cols: number, rows: number): Promise<void>;
+    inspectForeground(): Promise<SubprocessTerminalForeground | undefined>;
+    inspectActivity(): Promise<SubprocessTerminalActivity>;
+    signalForeground(signal: SubprocessTerminalSignal): Promise<number>;
+    terminate(): Promise<void>;
+    /**
+     * Force-terminate the observable session synchronously during Node's exit
+     * event. This does not claim quiescence and does not replace terminate().
+     */
+    terminateForHostExit(): void;
+    private forceStopShell;
+    private survivors;
+    private descendants;
+    private waitForMembers;
+    private signalMembers;
+    private forceStopDescendants;
+    private unionMembers;
+    private stopDescendants;
+    private stopShell;
+    private stopShellWindows;
+    private waitForWindowsShellExit;
+    private closeOnce;
+    private cleanupManagedOwner;
+    private closeManagedRange;
+    private settleExitIfGone;
+}
+//# sourceMappingURL=terminal.d.ts.map

package/lib/types/windows-inspector.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Windows process-table operations for terminal readiness, signalling, and
+ * teardown: Toolhelp32 snapshot enumeration with GetProcessTimes creation-time
+ * identity and process-handle wait-state liveness, the shell pid as a pseudo
+ * process group (Windows has no POSIX groups), and taskkill tree signalling.
+ * The koffi bindings load lazily so
+ * non-Windows processes never touch Win32 libraries; all decision logic takes
+ * an injectable internals boundary so suites can pin it on any host.
+ * @module dsh-subprocess-local/windows-inspector
+ */
+import type { SubprocessTerminalSignal } from '@qlzt/dsh-subprocess';
+import type { ProcessIdentity, ProcessInspector, ProcessSnapshot } from './process-inspector.ts';
+/** One Toolhelp32 process-table row. */
+export interface ProcessEntry {
+    pid: number;
+    parentPid: number;
+}
+/** Creation identity plus the process object's current wait state. */
+export interface WindowsProcessState {
+    /** GetProcessTimes creation identity used to fence PID reuse. */
+    started: string;
+    /** Whether a zero-time process-handle wait reports the process still running. */
+    active: boolean;
+}
+/** Injectable Windows process operations used by one local PTY session. */
+export interface WindowsProcessInspectorInternals {
+    /** Enumerate the current process table (pid/parent pairs). */
+    snapshot(): ProcessEntry[];
+    /** Return one process's creation identity and wait state, or undefined when unreadable. */
+    processState(pid: number): WindowsProcessState | undefined;
+    /** Terminate one process tree; `force` maps to taskkill `/F`. */
+    taskkill(pid: number, force: boolean): void;
+}
+/**
+ * Walk a process table from one root in children-first order, retaining only
+ * members whose start identity is readable (unreadable members are detector
+ * misses, exactly like an unreadable `/proc` entry on Linux).
+ * @param entries - the process table snapshot.
+ * @param rootPid - the tree root to descend from.
+ * @param started - creation-time identity resolver for one member.
+ * @returns the root and its current transitive descendants, children first.
+ */
+export declare function windowsProcessTree(entries: ProcessEntry[], rootPid: number, started: (pid: number) => string | undefined): ProcessIdentity[];
+/**
+ * Windows {@link ProcessInspector}. The shell pid stands in for a foreground
+ * process group: it is a stable pseudo-group that lets the prompt-marker
+ * readiness path compare foreground identities, while every actual signal
+ * targets the console-wide tree through taskkill (SIGINT is delivered by the
+ * terminal handle as a `\x03` input write and never reaches this layer).
+ */
+export declare class WindowsProcessInspector implements ProcessInspector {
+    private readonly internals;
+    constructor(internals?: WindowsProcessInspectorInternals);
+    foregroundPgid(shellPid: number): number;
+    isStdinWaiting(_pgid: number, _shellPid: number): boolean;
+    isAlive(identity: ProcessIdentity): boolean;
+    snapshot(): ProcessSnapshot;
+    signalGroup(pgid: number, signal: SubprocessTerminalSignal): void;
+    signalProcess(identity: ProcessIdentity, signal: 'SIGTERM' | 'SIGKILL'): void;
+}
+/**
+ * Create the Windows process inspector.
+ * @param internals - injectable process operations; defaults to the koffi-backed table.
+ * @returns the Windows inspector.
+ */
+export declare function createWindowsProcessInspector(internals?: WindowsProcessInspectorInternals): WindowsProcessInspector;
+declare const nativePtr: unique symbol;
+/** Koffi 3 native pointer (a BigInt address), branded so it cannot silently enter numeric contexts. */
+export type NativePtr = bigint & {
+    readonly [nativePtr]: true;
+};
+/**
+ * True for NULL and INVALID_HANDLE_VALUE returns from Win32 handle APIs.
+ * @param value - a handle as koffi may hand it back (pointer, null, or 0n).
+ * @returns whether the value signals an invalid handle.
+ */
+export declare function isInvalidHandle(value: NativePtr | null | undefined): boolean;
+export {};
+//# sourceMappingURL=windows-inspector.d.ts.map

package/lib/types/windows-job.d.ts

@@ -0,0 +1,30 @@
+/** Windows parent-side launch and ownership for the private Job runner. */
+import { spawn } from 'node:child_process';
+import type { SubprocessSpawnSpec } from '@qlzt/dsh-subprocess';
+import { loadWin32ProcessBindings, probeCurrentTokenJobSupport } from '@qlzt/dsh-win32-process';
+import type { ManagedProcessLaunch } from './managed-owner.ts';
+import type { RunnerInvocation } from './runner-launch.ts';
+/** Test seams for runner launch and dynamic capability checks. */
+export interface WindowsJobInternals {
+    spawn?: typeof spawn;
+    runnerInvocation?: RunnerInvocation;
+    resolveRunnerInvocation?: () => RunnerInvocation;
+    runnerAvailable?: (invocation: RunnerInvocation) => boolean;
+    loadWin32ProcessBindings?: typeof loadWin32ProcessBindings;
+    probeCurrentTokenJobSupport?: typeof probeCurrentTokenJobSupport;
+}
+/**
+ * Re-check the runner entry, bindings, and current Job capability for every spawn.
+ * @param internals - optional runner and Win32 capability seams used by tests.
+ * @returns whether the Windows native containment path is currently available.
+ */
+export declare function probeWindowsJob(internals?: WindowsJobInternals): boolean;
+/**
+ * Launch one target through a runner that uniquely owns its Job handle.
+ * @param spec - ordinary target request.
+ * @param targetEnv - validated complete target environment.
+ * @param internals - optional runner launch seams used by tests.
+ * @returns direct streams, result, and runner-owned managed range.
+ */
+export declare function launchWindowsJob(spec: SubprocessSpawnSpec, targetEnv: Record<string, string>, internals?: WindowsJobInternals): ManagedProcessLaunch;
+//# sourceMappingURL=windows-job.d.ts.map

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@qlzt/dsh-subprocess-local",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Local-subprocess implementation of the DeepSeek Harness subprocess seam",
+  "version": "0.2.1-alpha.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://gitee.com/zsping1989/deepseek-harness.git",
+    "directory": "packages/subprocess/subprocess-local"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./runner": {
+      "types": "./lib/types/bin.d.ts",
+      "default": "./lib/runner.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json",
+    "./output": {
+      "types": "./lib/types/output.d.ts",
+      "default": "./lib/output.js"
+    }
+  },
+  "files": [
+    "lib/index.js",
+    "lib/runner.js",
+    "lib/runner-*.js",
+    "lib/output.js",
+    "scripts/ensure-spawn-helper.mjs",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qlzt/dsh-subprocess": "0.2.1-alpha.2",
+    "@qlzt/dsh-timeout": "0.2.1-alpha.2",
+    "@deepseek-ai/cordis": "~4.0.5-alpha.1"
+  },
+  "dependencies": {
+    "@qlzt/dsh-lazy-require": "0.2.1-alpha.2",
+    "@qlzt/dsh-win32-process": "0.2.1-alpha.2",
+    "koffi": "3.1.1",
+    "node-pty": "1.2.0-beta.15"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-loader-smoke": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-subprocess": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-timeout": "0.2.1-alpha.2",
+    "@deepseek-ai/cordis": "~4.0.5-alpha.1"
+  },
+  "scripts": {
+    "postinstall": "node scripts/ensure-spawn-helper.mjs"
+  },
+  "dsh": {}
+}

package/scripts/ensure-spawn-helper.mjs

@@ -0,0 +1,16 @@
+/** Restore the executable bit stripped from node-pty's prebuilt helper. */
+
+import { chmodSync, existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const entry = fileURLToPath(import.meta.resolve('node-pty'))
+const packageRoot = dirname(dirname(entry))
+const candidates = [
+  join(packageRoot, 'prebuilds', `${process.platform}-${process.arch}`, 'spawn-helper'),
+  join(packageRoot, 'build', 'Release', 'spawn-helper'),
+]
+
+for (const helper of candidates) {
+  if (existsSync(helper)) chmodSync(helper, 0o755)
+}