@orkestrel/process 0.0.8 → 0.0.9

package/dist/src/server/index.d.cts

@@ -5,10 +5,8 @@ import { ExecutableOptions } from '@orkestrel/process';
 import { ExecuteInput } from '@orkestrel/process';
 import { ExecuteOptions } from '@orkestrel/process';
 import { ExecuteResult } from '@orkestrel/process';
-import { ExecuteResult as ExecuteResult_2 } from '@orkestrel/process';
 import { ExecuteSyncOptions } from '@orkestrel/process';
 import { ProcessCommand } from '@orkestrel/process';
-import { ProcessCommand as ProcessCommand_2 } from '@orkestrel/process';
 import { ProcessEventMap } from '@orkestrel/process';
 import { ProcessExit } from '@orkestrel/process';
 import { ProcessInterface } from '@orkestrel/process';
@@ -120,6 +118,30 @@ export declare function buildPlatformSpawn(command: ProcessCommand, file: string
  */
 export declare function buildSpawn(command: ProcessCommand, options?: ExecutableOptions): SpawnInput;
 
+/**
+ * Bounds one delivered stream chunk to the bytes a capture still has room for.
+ *
+ * @remarks
+ * A chunk that is not a buffer contributes nothing and reports `undefined` rather than throwing,
+ * because a stream `data` listener receives an `unknown` payload. The cut is byte-exact and might
+ * land inside a multibyte sequence, because {@link buildExecuteResult} performs the single
+ * code-point-boundary trim over the whole capture rather than over each chunk. Give the capture one
+ * byte more room than its limit, so that final trim can read the first excluded byte and retreat off
+ * a split sequence. A chunk that fits its room is returned as the delivered buffer itself rather
+ * than a copy, because a capture appending it copies again and never writes through it; a chunk that
+ * overruns its room returns a copy of the bytes that fit. Treat the return as read-only either way.
+ *
+ * @param chunk - The delivered chunk, ignored when it is not a buffer
+ * @param room - The bytes the capture still accepts
+ * @returns The bytes to retain, or `undefined` when the chunk contributes none
+ *
+ * @example
+ * ```ts
+ * captureChunk(Buffer.from('hello'), 3) // <Buffer 68 65 6c>
+ * ```
+ */
+export declare function captureChunk(chunk: unknown, room: number): Buffer_2 | undefined;
+
 /**
  * Creates one supervised child process.
  *
@@ -192,7 +214,7 @@ export declare function createSession(options: SessionOptions): SessionInterface
  * detach({ file: 'node', arguments: ['daemon.js'] }, { workspace: process.cwd() })
  * ```
  */
-export declare function detach(command: ProcessCommand_2, options?: DetachOptions): void;
+export declare function detach(command: ProcessCommand, options?: DetachOptions): void;
 
 /**
  * Runs one command to completion, buffering its output, and settles with the outcome.
@@ -201,7 +223,9 @@ export declare function detach(command: ProcessCommand_2, options?: DetachOption
  * The executable is resolved through {@link buildSpawn}, so no run uses a shell. On a POSIX host the
  * child is detached, which is what lets its whole process group be terminated. Standard output and
  * error are each byte-bounded by `limit` (default {@link PROCESS_OUTPUT}) and `truncated` reports
- * whether either stream exceeded it. A positive `timeout` and an aborting `signal` both terminate the
+ * whether either stream exceeded it. Each capture keeps one byte beyond `limit`, so the single
+ * code-point-boundary trim in {@link buildExecuteResult} reads the first excluded byte and never
+ * delivers a split multibyte sequence. A positive `timeout` and an aborting `signal` both terminate the
  * child through the same bounded stop, and only the earliest is recorded: a timeout reports
  * `expired` and an abort reports `aborted`, never both. After termination the outcome is awaited for
  * a bounded window, so a descendant holding the child's stdio cannot keep the run pending. That bound
@@ -227,7 +251,7 @@ export declare function detach(command: ProcessCommand_2, options?: DetachOption
  * const result = await execute({ file: 'git', arguments: ['status'] }, { workspace: process.cwd() })
  * ```
  */
-export declare function execute(command: ProcessCommand_2, options?: ExecuteOptions): Promise<ExecuteResult_2>;
+export declare function execute(command: ProcessCommand, options?: ExecuteOptions): Promise<ExecuteResult>;
 
 /**
  * Runs one command to completion synchronously, buffering its output, and returns the outcome.
@@ -253,7 +277,7 @@ export declare function execute(command: ProcessCommand_2, options?: ExecuteOpti
  * const result = executeSync({ file: 'git', arguments: ['--version'] }, { strict: false })
  * ```
  */
-export declare function executeSync(command: ProcessCommand_2, options?: ExecuteSyncOptions): ExecuteResult_2;
+export declare function executeSync(command: ProcessCommand, options?: ExecuteSyncOptions): ExecuteResult;
 
 /**
  * Renders one command into its diagnostic command line.
@@ -715,48 +739,6 @@ export declare function readVariable(environment: Readonly<Record<string, string
  */
 export declare function resolveExecutable(file: string, options?: ExecutableOptions): string | undefined;
 
-/**
- * Accumulates byte totals while retaining a bounded stream head.
- *
- * @example
- * ```ts
- * const retention = new Retention()
- * retention.retain(Buffer.from('hello'), 3)?.toString('utf8') // 'hel'
- * retention.retained // 3
- * ```
- */
-export declare class Retention implements RetentionInterface {
-    #private;
-    /** The bytes delivered by the stream. */
-    get delivered(): number;
-    /** The bytes retained from the stream head. */
-    get retained(): number;
-    /**
-     * Retains a delivered chunk within a byte limit.
-     *
-     * @param chunk - The delivered chunk, ignored when it is not a buffer
-     * @param limit - The maximum retained byte count
-     * @returns The retained slice, or `undefined` when the chunk contributes no retained bytes
-     */
-    retain(chunk: unknown, limit: number): Buffer_2 | undefined;
-}
-
-/** Exposes byte totals and bounded stream-head retention. */
-export declare interface RetentionInterface {
-    /** The bytes delivered by the stream. */
-    readonly delivered: number;
-    /** The bytes retained from the stream head. */
-    readonly retained: number;
-    /**
-     * Retains a delivered chunk within a byte limit.
-     *
-     * @param chunk - The delivered chunk, ignored when it is not a buffer
-     * @param limit - The maximum retained byte count
-     * @returns The retained slice, or `undefined` when the chunk contributes no retained bytes
-     */
-    retain(chunk: unknown, limit: number): Buffer_2 | undefined;
-}
-
 /**
  * Supervises one child and publishes its standard output as raw bytes.
  *
@@ -911,9 +893,12 @@ export declare function stopChild(child: ProcessChild, grace: number, confirm: n
  * Trims a buffer to at most `limit` leading bytes without splitting a UTF-8 sequence.
  *
  * @remarks
- * Keeps the head — the captured start of a one-shot run's output. When the cut point lands inside
- * a multibyte sequence, the end retreats to the sequence's start so the retained bytes always end
- * on a code-point boundary and decode without a replacement character.
+ * Keeps the head — the captured start of a one-shot run's output. The end retreats only when a
+ * sequence genuinely spans the cut: the byte at `limit` carries the continuation bit pattern, and a
+ * lead byte within the preceding three bytes declares a length that reaches it. The retained bytes
+ * then end on a code-point boundary and decode without a replacement character. A byte at `limit`
+ * that carries the continuation pattern without such a lead byte is invalid UTF-8 rather than a
+ * split sequence, so the full `limit` survives instead of a valid byte being dropped for it.
  *
  * @param bytes - The accumulated bytes
  * @param limit - The maximum retained byte count

package/dist/src/server/index.d.ts

@@ -5,10 +5,8 @@ import { ExecutableOptions } from '@orkestrel/process';
 import { ExecuteInput } from '@orkestrel/process';
 import { ExecuteOptions } from '@orkestrel/process';
 import { ExecuteResult } from '@orkestrel/process';
-import { ExecuteResult as ExecuteResult_2 } from '@orkestrel/process';
 import { ExecuteSyncOptions } from '@orkestrel/process';
 import { ProcessCommand } from '@orkestrel/process';
-import { ProcessCommand as ProcessCommand_2 } from '@orkestrel/process';
 import { ProcessEventMap } from '@orkestrel/process';
 import { ProcessExit } from '@orkestrel/process';
 import { ProcessInterface } from '@orkestrel/process';
@@ -120,6 +118,30 @@ export declare function buildPlatformSpawn(command: ProcessCommand, file: string
  */
 export declare function buildSpawn(command: ProcessCommand, options?: ExecutableOptions): SpawnInput;
 
+/**
+ * Bounds one delivered stream chunk to the bytes a capture still has room for.
+ *
+ * @remarks
+ * A chunk that is not a buffer contributes nothing and reports `undefined` rather than throwing,
+ * because a stream `data` listener receives an `unknown` payload. The cut is byte-exact and might
+ * land inside a multibyte sequence, because {@link buildExecuteResult} performs the single
+ * code-point-boundary trim over the whole capture rather than over each chunk. Give the capture one
+ * byte more room than its limit, so that final trim can read the first excluded byte and retreat off
+ * a split sequence. A chunk that fits its room is returned as the delivered buffer itself rather
+ * than a copy, because a capture appending it copies again and never writes through it; a chunk that
+ * overruns its room returns a copy of the bytes that fit. Treat the return as read-only either way.
+ *
+ * @param chunk - The delivered chunk, ignored when it is not a buffer
+ * @param room - The bytes the capture still accepts
+ * @returns The bytes to retain, or `undefined` when the chunk contributes none
+ *
+ * @example
+ * ```ts
+ * captureChunk(Buffer.from('hello'), 3) // <Buffer 68 65 6c>
+ * ```
+ */
+export declare function captureChunk(chunk: unknown, room: number): Buffer_2 | undefined;
+
 /**
  * Creates one supervised child process.
  *
@@ -192,7 +214,7 @@ export declare function createSession(options: SessionOptions): SessionInterface
  * detach({ file: 'node', arguments: ['daemon.js'] }, { workspace: process.cwd() })
  * ```
  */
-export declare function detach(command: ProcessCommand_2, options?: DetachOptions): void;
+export declare function detach(command: ProcessCommand, options?: DetachOptions): void;
 
 /**
  * Runs one command to completion, buffering its output, and settles with the outcome.
@@ -201,7 +223,9 @@ export declare function detach(command: ProcessCommand_2, options?: DetachOption
  * The executable is resolved through {@link buildSpawn}, so no run uses a shell. On a POSIX host the
  * child is detached, which is what lets its whole process group be terminated. Standard output and
  * error are each byte-bounded by `limit` (default {@link PROCESS_OUTPUT}) and `truncated` reports
- * whether either stream exceeded it. A positive `timeout` and an aborting `signal` both terminate the
+ * whether either stream exceeded it. Each capture keeps one byte beyond `limit`, so the single
+ * code-point-boundary trim in {@link buildExecuteResult} reads the first excluded byte and never
+ * delivers a split multibyte sequence. A positive `timeout` and an aborting `signal` both terminate the
  * child through the same bounded stop, and only the earliest is recorded: a timeout reports
  * `expired` and an abort reports `aborted`, never both. After termination the outcome is awaited for
  * a bounded window, so a descendant holding the child's stdio cannot keep the run pending. That bound
@@ -227,7 +251,7 @@ export declare function detach(command: ProcessCommand_2, options?: DetachOption
  * const result = await execute({ file: 'git', arguments: ['status'] }, { workspace: process.cwd() })
  * ```
  */
-export declare function execute(command: ProcessCommand_2, options?: ExecuteOptions): Promise<ExecuteResult_2>;
+export declare function execute(command: ProcessCommand, options?: ExecuteOptions): Promise<ExecuteResult>;
 
 /**
  * Runs one command to completion synchronously, buffering its output, and returns the outcome.
@@ -253,7 +277,7 @@ export declare function execute(command: ProcessCommand_2, options?: ExecuteOpti
  * const result = executeSync({ file: 'git', arguments: ['--version'] }, { strict: false })
  * ```
  */
-export declare function executeSync(command: ProcessCommand_2, options?: ExecuteSyncOptions): ExecuteResult_2;
+export declare function executeSync(command: ProcessCommand, options?: ExecuteSyncOptions): ExecuteResult;
 
 /**
  * Renders one command into its diagnostic command line.
@@ -715,48 +739,6 @@ export declare function readVariable(environment: Readonly<Record<string, string
  */
 export declare function resolveExecutable(file: string, options?: ExecutableOptions): string | undefined;
 
-/**
- * Accumulates byte totals while retaining a bounded stream head.
- *
- * @example
- * ```ts
- * const retention = new Retention()
- * retention.retain(Buffer.from('hello'), 3)?.toString('utf8') // 'hel'
- * retention.retained // 3
- * ```
- */
-export declare class Retention implements RetentionInterface {
-    #private;
-    /** The bytes delivered by the stream. */
-    get delivered(): number;
-    /** The bytes retained from the stream head. */
-    get retained(): number;
-    /**
-     * Retains a delivered chunk within a byte limit.
-     *
-     * @param chunk - The delivered chunk, ignored when it is not a buffer
-     * @param limit - The maximum retained byte count
-     * @returns The retained slice, or `undefined` when the chunk contributes no retained bytes
-     */
-    retain(chunk: unknown, limit: number): Buffer_2 | undefined;
-}
-
-/** Exposes byte totals and bounded stream-head retention. */
-export declare interface RetentionInterface {
-    /** The bytes delivered by the stream. */
-    readonly delivered: number;
-    /** The bytes retained from the stream head. */
-    readonly retained: number;
-    /**
-     * Retains a delivered chunk within a byte limit.
-     *
-     * @param chunk - The delivered chunk, ignored when it is not a buffer
-     * @param limit - The maximum retained byte count
-     * @returns The retained slice, or `undefined` when the chunk contributes no retained bytes
-     */
-    retain(chunk: unknown, limit: number): Buffer_2 | undefined;
-}
-
 /**
  * Supervises one child and publishes its standard output as raw bytes.
  *
@@ -911,9 +893,12 @@ export declare function stopChild(child: ProcessChild, grace: number, confirm: n
  * Trims a buffer to at most `limit` leading bytes without splitting a UTF-8 sequence.
  *
  * @remarks
- * Keeps the head — the captured start of a one-shot run's output. When the cut point lands inside
- * a multibyte sequence, the end retreats to the sequence's start so the retained bytes always end
- * on a code-point boundary and decode without a replacement character.
+ * Keeps the head — the captured start of a one-shot run's output. The end retreats only when a
+ * sequence genuinely spans the cut: the byte at `limit` carries the continuation bit pattern, and a
+ * lead byte within the preceding three bytes declares a length that reaches it. The retained bytes
+ * then end on a code-point boundary and decode without a replacement character. A byte at `limit`
+ * that carries the continuation pattern without such a lead byte is invalid UTF-8 rather than a
+ * split sequence, so the full `limit` survives instead of a valid byte being dropped for it.
  *
  * @param bytes - The accumulated bytes
  * @param limit - The maximum retained byte count