@oh-my-pi/pi-utils 18.11.0 → 18.11.2

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [18.11.2] - 2026-10-16
+
+### Added
+
+- Exported `sqliteFileIdentity()`, so a caller holding a long-lived SQLite connection can tell when its path now names a different file (e.g. after a corrupt store was quarantined and replaced) ([#14361](https://github.com/can1357/oh-my-pi/pull/14361) by [@F0Rextasy](https://github.com/F0Rextasy))
+- Added `slugify()`, the shared lowercase ASCII kebab-case helper with an optional `maxLength` ([#14283](https://github.com/can1357/oh-my-pi/pull/14283) by [@jaredlyon](https://github.com/jaredlyon))
+
+### Fixed
+
+- Fixed an unhandled rejection when a subprocess is spawned with an already-aborted signal ([#15750](https://github.com/can1357/oh-my-pi/pull/15750) by [@harshaygadekar](https://github.com/harshaygadekar))
+
 ## [18.10.0] - 2026-10-12
 
 ### Added

package/dist/types/incoming-json.d.ts

@@ -48,6 +48,18 @@
  * await args.key("path").value<string>(); // "a.ts"
  * ```
  */
+/**
+ * @internal exported for tests — monotonic count of members re-lexed by
+ * selecting scans: one per object member or array element a scan walked over
+ * on the way to the member it was asked for.
+ *
+ * Cursor resumption (see {@link ContainerIndex}) is what keeps a full
+ * traversal linear in the document instead of quadratic, and losing it
+ * changes nothing about the pulled values — only how many members get
+ * re-lexed. Read the live binding before and after a traversal to measure
+ * exactly that.
+ */
+export declare let rescannedMembers: number;
 /** Location component in a pulled JSON path: an object member name or an array index. */
 export type PullPathSegment = string | number;
 /** JSON shape observed by a started pull. */

package/dist/types/index.d.ts

@@ -31,6 +31,7 @@ export * as ptree from "./ptree.js";
 export { AbortError, ChildProcess, Exception, NonZeroExitError } from "./ptree.js";
 export * from "./runtime-install.js";
 export * from "./sanitize-text.js";
+export * from "./slugify.js";
 export * from "./snowflake.js";
 export * from "./sqlite.js";
 export * from "./stderr-guard.js";

package/dist/types/mime.d.ts

@@ -26,5 +26,26 @@ export type ImageMetadata = {
     hasAlpha?: boolean;
 };
 export declare function parseImageMetadata(header: Uint8Array): ImageMetadata | null;
+/** Why base64 image data is unusable; `undefined` when it is canonical and non-empty. */
+export type Base64ImageDataFailure = "invalid base64 image data" | "empty image data";
+/**
+ * Non-empty decoded bytes on success, or a validation failure reason, never both.
+ * Check `reason` before using `bytes`; successful base64 decoding does not establish
+ * that the bytes represent a supported or decodable image.
+ */
+export type Base64ImageDecodeResult = {
+    bytes: Buffer;
+    reason?: never;
+} | {
+    bytes?: never;
+    reason: Base64ImageDataFailure;
+};
+/**
+ * Validate standard base64 image data without decoding it. Padding may be omitted, but
+ * present padding must be canonical, the trailing bits must be zero, and the data non-empty.
+ */
+export declare function base64ImageDataFailureReason(data: string): Base64ImageDataFailure | undefined;
+/** Decode standard base64 image data under the {@link base64ImageDataFailureReason} rules. */
+export declare function decodeBase64ImageData(data: string): Base64ImageDecodeResult;
 export declare function readImageMetadataSync(filePath: string, maxBytes?: number): ImageMetadata | null;
 export declare function readImageMetadata(filePath: string, maxBytes?: number): Promise<ImageMetadata | null>;

package/dist/types/slugify.d.ts

@@ -0,0 +1,4 @@
+/** Lowercase ASCII kebab slug: [^a-z0-9]+ → "-", edge dashes trimmed; optional maxLength truncates then re-trims trailing dashes; throws RangeError unless maxLength is a non-negative integer. Returns "" when nothing survives. */
+export declare function slugify(input: string, options?: {
+    maxLength?: number;
+}): string;

package/dist/types/sqlite.d.ts

@@ -1,5 +1,17 @@
 /** Shared SQLite opening, error attribution, and result-code classification for persistent stores. */
 import { Database } from "bun:sqlite";
+/**
+ * A store's identity as `dev:ino:birthtimeMs`, `null` when the path holds no
+ * file, or `undefined` when the stat itself failed and no conclusion is safe.
+ */
+export type SqliteFileIdentity = string | null | undefined;
+/**
+ * Identity of the file currently at `dbPath`. Quarantine moves a corrupt store
+ * aside and recreates one at the same path, so a connection cached on the path
+ * alone keeps writing to the unlinked inode: callers that hold a long-lived
+ * handle compare this before reusing it.
+ */
+export declare function sqliteFileIdentity(dbPath: string): SqliteFileIdentity;
 /** Controls opt-in replacement of an unrecoverably corrupt SQLite store. */
 export interface SqliteOpenOptions {
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-utils",
-	"version": "18.11.0",
+	"version": "18.11.2",
 	"description": "Shared utilities for pi packages",
 	"keywords": [
 		"cli",
@@ -57,7 +57,7 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "18.11.0"
+		"@oh-my-pi/pi-natives": "18.11.2"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/incoming-json.ts

@@ -67,6 +67,19 @@ import { parseJsonWithRepair } from "./json-parse";
 /** Maximum container nesting before a scan reports the value as pending forever. */
 const MAX_DEPTH = 128;
 
+/**
+ * @internal exported for tests — monotonic count of members re-lexed by
+ * selecting scans: one per object member or array element a scan walked over
+ * on the way to the member it was asked for.
+ *
+ * Cursor resumption (see {@link ContainerIndex}) is what keeps a full
+ * traversal linear in the document instead of quadratic, and losing it
+ * changes nothing about the pulled values — only how many members get
+ * re-lexed. Read the live binding before and after a traversal to measure
+ * exactly that.
+ */
+export let rescannedMembers = 0;
+
 /** Location component in a pulled JSON path: an object member name or an array index. */
 export type PullPathSegment = string | number;
 
@@ -325,6 +338,7 @@ function selectKey(
 		lex.ws();
 		if (lex.atEnd) return PENDING;
 		if (key === wanted) return selectValue(lex, path, at, ended, depth + 1, slot);
+		rescannedMembers++;
 		const skipped = scanValue(lex, ended, depth + 1);
 		if (skipped.tag !== "located" || skipped.end === undefined) return PENDING;
 		lex.ws();
@@ -370,6 +384,7 @@ function selectIndex(
 		}
 		const slot = index.elements[element] ?? (index.tail ??= { offset: lex.pos });
 		if (element === wanted) return selectValue(lex, path, at, ended, depth + 1, slot);
+		rescannedMembers++;
 		const skipped = scanValue(lex, ended, depth + 1);
 		if (skipped.tag !== "located" || skipped.end === undefined) return PENDING;
 		if (element === index.elements.length) {

package/src/index.ts

@@ -31,6 +31,7 @@ export * as ptree from "./ptree";
 export { AbortError, ChildProcess, Exception, NonZeroExitError } from "./ptree";
 export * from "./runtime-install";
 export * from "./sanitize-text";
+export * from "./slugify";
 export * from "./snowflake";
 export * from "./sqlite";
 export * from "./stderr-guard";

package/src/mime.ts

@@ -143,6 +143,50 @@ export function parseImageMetadata(header: Uint8Array): ImageMetadata | null {
 	);
 }
 
+/** Why base64 image data is unusable; `undefined` when it is canonical and non-empty. */
+export type Base64ImageDataFailure = "invalid base64 image data" | "empty image data";
+
+/**
+ * Non-empty decoded bytes on success, or a validation failure reason, never both.
+ * Check `reason` before using `bytes`; successful base64 decoding does not establish
+ * that the bytes represent a supported or decodable image.
+ */
+export type Base64ImageDecodeResult =
+	| { bytes: Buffer; reason?: never }
+	| { bytes?: never; reason: Base64ImageDataFailure };
+
+const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+/**
+ * Validate standard base64 image data without decoding it. Padding may be omitted, but
+ * present padding must be canonical, the trailing bits must be zero, and the data non-empty.
+ */
+export function base64ImageDataFailureReason(data: string): Base64ImageDataFailure | undefined {
+	if (data.length === 0) return "empty image data";
+
+	const match = /^([A-Za-z0-9+/]+)(={0,2})$/.exec(data);
+	if (!match) return "invalid base64 image data";
+	const encoded = match[1];
+	const paddingLength = match[2].length;
+	const remainder = encoded.length % 4;
+	if (remainder === 1 || (paddingLength === 1 && remainder !== 3) || (paddingLength === 2 && remainder !== 2)) {
+		return "invalid base64 image data";
+	}
+
+	const lastSextet = BASE64_ALPHABET.indexOf(encoded[encoded.length - 1]);
+	if ((remainder === 2 && (lastSextet & 0b1111) !== 0) || (remainder === 3 && (lastSextet & 0b11) !== 0)) {
+		return "invalid base64 image data";
+	}
+	return undefined;
+}
+
+/** Decode standard base64 image data under the {@link base64ImageDataFailureReason} rules. */
+export function decodeBase64ImageData(data: string): Base64ImageDecodeResult {
+	const reason = base64ImageDataFailureReason(data);
+	if (reason) return { reason };
+	return { bytes: Buffer.from(data, "base64") };
+}
+
 export function readImageMetadataSync(filePath: string, maxBytes = IMAGE_METADATA_HEADER_BYTES): ImageMetadata | null {
 	return peekFileSync(filePath, maxBytes, parseImageMetadata);
 }

package/src/ptree.ts

@@ -443,7 +443,9 @@ export class ChildProcess<In extends InMask = InMask> {
 	// ── Output helpers ───────────────────────────────────────────────────
 
 	async #throwIfAborted(): Promise<void> {
-		const exitReason = this.exitReason;
+		// A kill() issued before Bun reports the root's exit only records the
+		// reason as pending; output readers that do not wait for exit must still see it.
+		const exitReason = this.#exitReason ?? this.#exitReasonPending;
 		if (!exitReason?.aborted) return;
 		if (this.#terminating) await this.#terminating;
 		throw exitReason;
@@ -589,10 +591,11 @@ export class ChildProcess<In extends InMask = InMask> {
 	// ── Signal / timeout ─────────────────────────────────────────────────
 
 	attachSignal(signal: AbortSignal): void {
+		const cleanup = this.#exited.catch(() => {});
 		const onAbort = () => this.kill(new AbortError(signal.reason, "<cancelled>"));
 		if (signal.aborted) return void onAbort();
 		signal.addEventListener("abort", onAbort, { once: true });
-		this.#exited.catch(() => {}).finally(() => signal.removeEventListener("abort", onAbort));
+		cleanup.finally(() => signal.removeEventListener("abort", onAbort));
 	}
 
 	#clearTimeout(): void {

package/src/slugify.ts

@@ -0,0 +1,11 @@
+/** Lowercase ASCII kebab slug: [^a-z0-9]+ → "-", edge dashes trimmed; optional maxLength truncates then re-trims trailing dashes; throws RangeError unless maxLength is a non-negative integer. Returns "" when nothing survives. */
+export function slugify(input: string, options?: { maxLength?: number }): string {
+	if (options?.maxLength !== undefined && !(Number.isInteger(options.maxLength) && options.maxLength >= 0)) {
+		throw new RangeError(`slugify maxLength must be a non-negative integer, got ${options.maxLength}`);
+	}
+	const slug = input
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "");
+	return options?.maxLength === undefined ? slug : slug.slice(0, options.maxLength).replace(/-+$/g, "");
+}

package/src/sqlite.ts

@@ -11,7 +11,11 @@ const BUSY_MAX_ATTEMPTS = 4;
 const BUSY_BASE_DELAY_MS = 100;
 const SQLITE_STORE_SUFFIXES = ["-wal", "-shm", "-journal", ""];
 
-type SqliteFileIdentity = string | null | undefined;
+/**
+ * A store's identity as `dev:ino:birthtimeMs`, `null` when the path holds no
+ * file, or `undefined` when the stat itself failed and no conclusion is safe.
+ */
+export type SqliteFileIdentity = string | null | undefined;
 
 /**
  * Corrupt handles held open by in-process openers awaiting recovery, keyed by
@@ -77,7 +81,13 @@ class SqliteAttemptFailure extends Error {
 	}
 }
 
-function sqliteFileIdentity(dbPath: string): SqliteFileIdentity {
+/**
+ * Identity of the file currently at `dbPath`. Quarantine moves a corrupt store
+ * aside and recreates one at the same path, so a connection cached on the path
+ * alone keeps writing to the unlinked inode: callers that hold a long-lived
+ * handle compare this before reusing it.
+ */
+export function sqliteFileIdentity(dbPath: string): SqliteFileIdentity {
 	try {
 		const stat = fs.statSync(dbPath);
 		return `${stat.dev}:${stat.ino}:${stat.birthtimeMs}`;