pi-better-background-tasks 0.2.20 → 0.4.0

package/src/process.ts

@@ -183,14 +183,15 @@ export function runCommandOnce(
   validateCommandSpec(spec);
   const startedAt = Date.now();
   const child = spawnArgs(spec, true, ["ignore", "pipe", "pipe"]);
-  let stdout = "";
-  let stderr = "";
+  const cap = Math.max(1, Math.floor(maxBufferBytes));
+  const stdoutCapture = createCaptureBuffer();
+  const stderrCapture = createCaptureBuffer();
   let timedOut = false;
-  child.stdout?.on("data", (chunk: Buffer) => {
-    if (Buffer.byteLength(stdout) < maxBufferBytes) stdout += chunk.toString("utf8");
+  child.stdout?.on("data", (chunk: Buffer | string) => {
+    captureChunk(stdoutCapture, chunk, cap);
   });
-  child.stderr?.on("data", (chunk: Buffer) => {
-    if (Buffer.byteLength(stderr) < maxBufferBytes) stderr += chunk.toString("utf8");
+  child.stderr?.on("data", (chunk: Buffer | string) => {
+    captureChunk(stderrCapture, chunk, cap);
   });
   return new Promise((resolve, reject) => {
     // The group outlives the leader as long as any member is alive, so the
@@ -239,19 +240,105 @@ export function runCommandOnce(
     });
     child.on("close", (exitCode, signal) => {
       settle();
+      const stdout = finishCapture(stdoutCapture);
+      const stderr = finishCapture(stderrCapture);
+      const captureTruncated = stdout.discardedBytes > 0 || stderr.discardedBytes > 0;
       resolve({
         exitCode,
         signal,
-        stdout,
-        stderr,
+        stdout: stdout.text,
+        stderr: stderr.text,
         startedAt,
         endedAt: Date.now(),
         ...(timedOut ? { timedOut: true } : {}),
+        ...(stdout.discardedBytes > 0 ? { stdoutDiscardedBytes: stdout.discardedBytes } : {}),
+        ...(stderr.discardedBytes > 0 ? { stderrDiscardedBytes: stderr.discardedBytes } : {}),
+        ...(captureTruncated ? { captureTruncated: true } : {}),
       });
     });
   });
 }
 
+interface CaptureBuffer {
+  chunks: Buffer[];
+  storedBytes: number;
+  discardedBytes: number;
+  truncated: boolean;
+}
+
+function createCaptureBuffer(): CaptureBuffer {
+  return { chunks: [], storedBytes: 0, discardedBytes: 0, truncated: false };
+}
+
+function asBuffer(chunk: Buffer | string): Buffer {
+  return Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+}
+
+/** Largest UTF-8 prefix of `buffer` that fits in `maxBytes`. */
+export function utf8PrefixLength(buffer: Buffer, maxBytes: number): number {
+  if (maxBytes <= 0) return 0;
+  if (buffer.length <= maxBytes) return buffer.length;
+  let end = maxBytes;
+  while (end > 0 && (buffer[end]! & 0xc0) === 0x80) end -= 1;
+  if (end === 0 && (buffer[0]! & 0xc0) === 0x80) return 0;
+  const lead = buffer[end]!;
+  const need = lead <= 0x7f ? 1
+    : (lead & 0xe0) === 0xc0 ? 2
+    : (lead & 0xf0) === 0xe0 ? 3
+    : (lead & 0xf8) === 0xf0 ? 4
+    : 1;
+  return end + need <= maxBytes ? end + need : end;
+}
+
+function captureChunk(target: CaptureBuffer, chunk: Buffer | string, maxBytes: number): void {
+  const buffer = asBuffer(chunk);
+  if (target.truncated) {
+    target.discardedBytes += buffer.length;
+    return;
+  }
+  const room = maxBytes - target.storedBytes;
+  if (buffer.length <= room) {
+    target.chunks.push(buffer);
+    target.storedBytes += buffer.length;
+    return;
+  }
+  const take = utf8PrefixLength(buffer, room);
+  if (take > 0) {
+    target.chunks.push(buffer.subarray(0, take));
+    target.storedBytes += take;
+  }
+  target.discardedBytes += buffer.length - take;
+  target.truncated = true;
+}
+
+/**
+ * Length of `buffer` without a trailing UTF-8 sequence that the cap cut short.
+ * Chunk boundaries can split a code point; once capture overflows, the bytes
+ * that would have completed it were discarded, so the dangling lead bytes are
+ * discarded too instead of decoding to U+FFFD.
+ */
+export function completeUtf8Length(buffer: Buffer): number {
+  let start = buffer.length - 1;
+  while (start >= 0 && buffer.length - start < 4 && (buffer[start]! & 0xc0) === 0x80) start -= 1;
+  if (start < 0) return buffer.length;
+  const lead = buffer[start]!;
+  const need = lead <= 0x7f ? 1
+    : (lead & 0xe0) === 0xc0 ? 2
+    : (lead & 0xf0) === 0xe0 ? 3
+    : (lead & 0xf8) === 0xf0 ? 4
+    : 1;
+  return start + need > buffer.length ? start : buffer.length;
+}
+
+function finishCapture(target: CaptureBuffer): { text: string; discardedBytes: number } {
+  const stored = Buffer.concat(target.chunks, target.storedBytes);
+  const keep = target.truncated ? completeUtf8Length(stored) : stored.length;
+  return {
+    text: stored.subarray(0, keep).toString("utf8"),
+    discardedBytes: target.discardedBytes + (stored.length - keep),
+  };
+}
+
 /**
  * Stop a task's process tree.
  *

package/src/registry.ts

@@ -92,15 +92,92 @@ export function onMetaChanged(listener: () => void): () => void {
 }
 
 export function readMeta(id: string): BackgroundTaskMeta | undefined {
+  return inspectMeta(id).meta;
+}
+
+export interface MetaInspection {
+  id: string;
+  meta?: BackgroundTaskMeta;
+  found: boolean;
+  readable: boolean;
+  error?: string;
+}
+
+function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Parsed JSON that lacks the identifying fields is corrupt, not a task. */
+function metaShapeProblem(meta: unknown, id: string): string | undefined {
+  if (!meta || typeof meta !== "object" || Array.isArray(meta)) return "not an object";
+  const value = meta as Partial<BackgroundTaskMeta>;
+  if (value.id !== id) return `id ${JSON.stringify(value.id ?? null)} does not match ${JSON.stringify(id)}`;
+  if (typeof value.status !== "string" || !value.status) return "missing status";
+  if (typeof value.logPath !== "string" || !value.logPath) return "missing logPath";
+  if (typeof value.startedAt !== "number" || !Number.isFinite(value.startedAt)) return "missing startedAt";
+  return undefined;
+}
+
+/**
+ * Distinguish missing, unreadable, and healthy metadata. Callers must not treat
+ * an unreadable file as proof that a task does not exist.
+ */
+export function inspectMeta(id: string): MetaInspection {
+  const path = metaPathFor(id);
   try {
     registryIo.metadataFileReads += 1;
-    const meta = JSON.parse(readFileSync(metaPathFor(id), "utf8")) as BackgroundTaskMeta;
-    metaCache.set(id, meta);
-    return meta;
-  } catch {
+    const raw = readFileSync(path, "utf8");
+    try {
+      const meta = JSON.parse(raw) as BackgroundTaskMeta;
+      const invalid = metaShapeProblem(meta, id);
+      if (invalid) {
+        metaCache.delete(id);
+        return { id, found: true, readable: false, error: `invalid metadata: ${invalid}` };
+      }
+      metaCache.set(id, meta);
+      return { id, meta, found: true, readable: true };
+    } catch (error) {
+      metaCache.delete(id);
+      return { id, found: true, readable: false, error: `invalid JSON: ${errorText(error)}` };
+    }
+  } catch (error) {
     metaCache.delete(id);
-    return undefined;
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") {
+      try {
+        statSync(taskDir(id));
+        return { id, found: true, readable: false, error: "metadata file is missing" };
+      } catch {
+        return { id, found: false, readable: false };
+      }
+    }
+    return { id, found: true, readable: false, error: errorText(error) };
+  }
+}
+
+export interface TaskIndex {
+  records: MetaInspection[];
+  indexError?: string;
+}
+
+/** List every task directory, including unreadable metadata. */
+export function listTaskRecords(): TaskIndex {
+  let ids: string[];
+  try {
+    registryIo.fullDirectoryReads += 1;
+    ids = readdirSync(tasksDir());
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return { records: [] };
+    return { records: [], indexError: errorText(error) };
   }
+  return {
+    records: ids.map((id) => inspectMeta(id)).sort((a, b) => {
+      const aTime = a.meta?.startedAt ?? 0;
+      const bTime = b.meta?.startedAt ?? 0;
+      return bTime - aTime;
+    }),
+  };
 }
 
 export function removeMeta(meta: BackgroundTaskMeta): boolean {
@@ -164,11 +241,11 @@ function readOwnedMeta(id: string): BackgroundTaskMeta | undefined {
   return metaCache.get(id) ?? readMeta(id);
 }
 
-function originOf(meta: BackgroundTaskMeta): BackgroundTaskCallbackOrigin {
+export function originOf(meta: BackgroundTaskMeta): BackgroundTaskCallbackOrigin {
   return meta.callbackOrigin ?? { cwd: meta.cwd };
 }
 
-function belongsToOrigin(meta: BackgroundTaskMeta, origin: BackgroundTaskCallbackOrigin): boolean {
+export function belongsToOrigin(meta: BackgroundTaskMeta, origin: BackgroundTaskCallbackOrigin): boolean {
   const candidate = originOf(meta);
   if (candidate.cwd !== origin.cwd) return false;
   if (candidate.sessionId || origin.sessionId) return candidate.sessionId === origin.sessionId;