@linxiraos/pi-utils 1.1.9 → 1.1.11

package/dist/types/worker-host.d.ts

@@ -0,0 +1,51 @@
+/** Prefix reserved for argv selectors dispatched by the shared CLI worker host. */
+export declare const WORKER_HOST_SELECTOR_PREFIX = "__omp_worker_";
+/** Whether an argv value selects a worker hosted by the shared CLI entrypoint. */
+export declare function isWorkerHostSelector(value: string | undefined): value is string;
+/** Called by CLI entrypoints whose main module dispatches worker argv selectors. */
+export declare function declareWorkerHostEntry(): void;
+/** Main-module path of the self-dispatching CLI host, or null outside it. */
+export declare function workerHostEntry(): string | null;
+/**
+ * Buffers messages a Bun worker thread receives before its real handler is
+ * attached, then hands them off once it is.
+ *
+ * Bun delivers messages the parent posted before the worker spawned exactly
+ * once — when the worker entry module's top-level evaluation completes — to the
+ * `message` listeners present at that moment. A worker whose handler attaches
+ * via a later `await import(...)` therefore misses that flush. The
+ * self-dispatching CLI host imports each worker module dynamically from inside
+ * its argv dispatch, so the worker's own `parentPort.on("message")` lands after
+ * the flush and the parent's synchronously-posted `init` handshake is dropped —
+ * every run then stalls until the init timeout fires and silently falls back to
+ * the inline worker (issue: eval cells always taking the full timeout).
+ *
+ * The host calls {@link installWorkerInbox} synchronously in the entry's sync
+ * prefix (before importing the worker module) so a `parentPort` listener exists
+ * at flush time; the worker module then {@link consumeWorkerInbox}es it and
+ * binds the real handler, replaying anything buffered. Re-dispatching through
+ * `parentPort.emit("message", …)` is not an option — Bun's port is an
+ * `EventTarget` whose `emit` throws — so the inbox calls the handler directly.
+ */
+export interface WorkerInbox {
+    /** Route buffered and subsequent messages to `handler`; returns an unbind fn. */
+    bind(handler: (message: unknown) => void): () => void;
+}
+/** Minimal `parentPort` surface the inbox needs (Node/Bun `MessagePort`). */
+interface MessageListenerPort {
+    on(event: "message", listener: (value: unknown) => void): unknown;
+}
+/**
+ * Attach a buffering `message` listener on `port` synchronously and stash the
+ * resulting inbox for the worker module to {@link consumeWorkerInbox}. MUST be
+ * called in the entry module's synchronous prefix — before the worker module is
+ * imported — so the listener exists when Bun flushes pre-spawn messages.
+ */
+export declare function installWorkerInbox(port: MessageListenerPort): WorkerInbox;
+/**
+ * Take the inbox installed by {@link installWorkerInbox} for this worker, or
+ * `null` when the worker module was loaded directly (no host pre-buffering, so
+ * the module's own synchronous top-level listener already wins the flush).
+ */
+export declare function consumeWorkerInbox(): WorkerInbox | null;
+export {};

package/dist/types/xml.d.ts

@@ -0,0 +1,31 @@
+/** Behavior-compatible reimplementation of fast-xml-parser's used surface. */
+/** Context supplied to an array-selection callback. */
+export type XMLArraySelector = (tagName: string, jPath: string, isLeafNode: boolean, isAttribute: boolean | null) => boolean;
+/** Options supported by {@link XMLParser}. */
+export interface XMLParserOptions {
+    /** Omits attributes when true (default). */
+    ignoreAttributes?: boolean;
+    /** Prefix applied to attribute property names. */
+    attributeNamePrefix?: string;
+    /** Property used for text alongside children or attributes. */
+    textNodeName?: string;
+    /** Trims ordinary text and attribute values. */
+    trimValues?: boolean;
+    /** Coerces numeric and boolean element text. */
+    parseTagValue?: boolean;
+    /** Coerces numeric and boolean attribute values. */
+    parseAttributeValue?: boolean;
+    /** Controls entity processing and its expansion ceiling. */
+    processEntities?: boolean | {
+        maxTotalExpansions?: number;
+    };
+    /** Selects element or attribute properties that must always be arrays. */
+    isArray?: XMLArraySelector;
+}
+/** Parses XML into the object shape used by the document converters. */
+export declare class XMLParser {
+    #private;
+    constructor(options?: XMLParserOptions);
+    /** Parses one XML document. */
+    parse(xml: string): unknown;
+}

package/package.json

@@ -1,59 +1,62 @@
 {
-  "engines": {
-    "bun": ">=1.3.14"
-  },
-  "devDependencies": {
-    "@types/bun": "^1.3.14"
-  },
-  "dependencies": {
-    "@linxiraos/pi-natives": "1.1.9"
-  },
-  "scripts": {
-    "test": "bun test --parallel",
-    "check:types": "tsgo -p tsconfig.json --noEmit",
-    "check": "tsgo -p tsconfig.json --noEmit"
-  },
-  "exports": {
-    "./*.js": "./src/*.ts",
-    "./*": {
-      "import": "./src/*.ts",
-      "types": "./src/*.ts"
-    },
-    "./ar": {
-      "import": "./src/ar/index.ts",
-      "types": "./src/ar/index.ts"
-    },
-    ".": {
-      "import": "./src/index.ts",
-      "types": "./src/index.ts"
-    }
-  },
-  "types": "./src/index.ts",
-  "main": "./src/index.ts",
-  "type": "module",
-  "files": [
-    "src",
-    "README.md",
-    "CHANGELOG.md"
-  ],
-  "repository": {
-    "directory": "packages/utils",
-    "url": "git+https://github.com/Linxira-OS/linxira-zeta.git",
-    "type": "git"
-  },
-  "author": "Can Boluk",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/Linxira-OS/linxira-zeta/issues"
-  },
-  "homepage": "https://linxira-os.github.io/zeta/",
-  "keywords": [
-    "utilities",
-    "cli",
-    "logging",
-    "streams"
-  ],
-  "description": "Shared utilities for pi packages",
-  "version": "1.1.9",
-  "name": "@linxiraos/pi-utils"
+	"name": "@linxiraos/pi-utils",
+	"version": "1.1.11",
+	"description": "Shared utilities for pi packages",
+	"keywords": [
+		"utilities",
+		"cli",
+		"logging",
+		"streams"
+	],
+	"homepage": "https://linxira-os.github.io/zeta/",
+	"bugs": {
+		"url": "https://github.com/Linxira-OS/linxira-zeta/issues"
+	},
+	"license": "MIT",
+	"author": "Can Boluk",
+	"repository": {
+		"directory": "packages/utils",
+		"url": "git+https://github.com/Linxira-OS/linxira-zeta.git",
+		"type": "git"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"CHANGELOG.md",
+		"LICENSE",
+		"THIRD-PARTY-NOTICES.txt",
+		"dist/types"
+	],
+	"type": "module",
+	"main": "./src/index.ts",
+	"types": "./dist/types/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/types/index.d.ts",
+			"import": "./src/index.ts"
+		},
+		"./ar": {
+			"types": "./dist/types/ar/index.d.ts",
+			"import": "./src/ar/index.ts"
+		},
+		"./*": {
+			"types": "./dist/types/*.d.ts",
+			"import": "./src/*.ts"
+		},
+		"./*.js": "./src/*.ts"
+	},
+	"scripts": {
+		"check": "tsgo -p tsconfig.json --noEmit",
+		"check:types": "tsgo -p tsconfig.json --noEmit",
+		"test": "bun test --parallel"
+	},
+	"dependencies": {
+		"@linxiraos/pi-natives": "1.1.11"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.3.14"
+	},
+	"engines": {
+		"bun": ">=1.3.14"
+	}
 }

package/src/dirs.ts

@@ -2,7 +2,7 @@
  * Centralized path helpers for zeta config directories.
  *
  * Uses PI_CONFIG_DIR (default ".zeta") for the config root and
- * PI_CODING_AGENT_DIR to override the agent directory.
+ * ZETA_CODING_AGENT_DIR to override the agent directory.
  *
  * On Linux, if XDG_DATA_HOME / XDG_STATE_HOME / XDG_CACHE_HOME environment
  * variables are set, paths are redirected to XDG-compliant locations under
@@ -36,7 +36,7 @@ export const USER_AGENT = `zeta/${VERSION}`;
 export const MIN_BUN_VERSION: string = engines.bun.replace(/[^0-9.]/g, "");
 
 const PROFILE_NAME_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;
-const PROFILE_ENV_KEYS = ["OMP_PROFILE", "PI_PROFILE"] as const;
+const PROFILE_ENV_KEYS = ["ZETA_PROFILE"] as const;
 
 /**
  * Names Windows treats as reserved device aliases. Matches the basename
@@ -76,24 +76,21 @@ export function normalizeProfileName(profile: string | undefined): string | unde
 }
 
 /**
- * Resolve the active profile from the two profile env vars. `OMP_PROFILE` is the
- * canonical variable and takes precedence; `PI_PROFILE` is the legacy
- * compatibility fallback, consulted only when `OMP_PROFILE` is undefined. An
- * explicitly-empty `OMP_PROFILE` therefore selects the default profile rather
- * than silently inheriting `PI_PROFILE`. Delegates validation/normalization to
- * {@link normalizeProfileName} (which throws on a syntactically invalid value).
+ * Resolve the active profile from `ZETA_PROFILE`. Delegates
+ * validation/normalization to {@link normalizeProfileName} (which throws on a
+ * syntactically invalid value).
  */
-export function resolveProfileEnv(omp: string | undefined, pi: string | undefined): string | undefined {
-	return normalizeProfileName(omp !== undefined ? omp : pi);
+export function resolveProfileEnv(profile: string | undefined): string | undefined {
+	return normalizeProfileName(profile);
 }
 
 function getProfileFromEnv(): string | undefined {
-	return resolveProfileEnv(process.env.OMP_PROFILE, process.env.PI_PROFILE);
+	return resolveProfileEnv(process.env.ZETA_PROFILE);
 }
 
 /**
  * Module-load profile resolution. Unlike {@link getProfileFromEnv}, an invalid
- * OMP_PROFILE/PI_PROFILE value does NOT throw here — a bad env var must not
+ * ZETA_PROFILE value does NOT throw here — a bad env var must not
  * crash a bare `import` of this module with an uncaught stack trace before the
  * CLI's error handling is in scope. The default profile is used instead; the
  * CLI re-validates the env (see `runCli` in coding-agent/src/cli.ts) so the
@@ -116,14 +113,6 @@ function getProfileConfigRoot(profile: string | undefined): string {
 	return profile ? path.join(root, "profiles", profile) : root;
 }
 
-function readPiProfileFromEnvSafe(): string | undefined {
-	try {
-		return normalizeProfileName(process.env.PI_PROFILE);
-	} catch {
-		return undefined;
-	}
-}
-
 function getProfileAgentDir(profile: string): string {
 	return path.join(getProfileConfigRoot(profile), "agent");
 }
@@ -398,14 +387,14 @@ class DirResolver {
 }
 
 /**
- * Decide which `PI_CODING_AGENT_DIR` value to capture as the pre-profile
+ * Decide which `ZETA_CODING_AGENT_DIR` value to capture as the pre-profile
  * baseline. A value equal to a profile's derived agent dir is profile-derived
  * (propagated by a parent's `setProfile`), so it must NOT be snapshotted as the
  * default-mode baseline — otherwise default mode would resolve to the profile's
- * agent dir. The profile source can be the active profile or a lower-priority
- * `PI_PROFILE` that was bypassed because `OMP_PROFILE` explicitly selected the
- * default profile. Returns `undefined` in those cases so reset falls back to the
- * standard `~/.zeta/agent`.
+ * agent dir. The profile source can be the active profile or an inherited
+ * `ZETA_PROFILE` (for example a parent CLI process that resolved a profile
+ * without exporting it). Returns `undefined` in those cases so reset falls back
+ * to the standard `~/.zeta/agent`.
  */
 function resolvePreProfileAgentDir(
 	profile: string | undefined,
@@ -420,14 +409,21 @@ let activeProfile = readProfileFromEnvSafe();
 /**
  * Resolve the agent-dir override for the current `activeProfile` from the live
  * environment. A named profile derives its own agent dir (no override); default
- * mode honors a non-profile `PI_CODING_AGENT_DIR` (see
+ * mode honors a non-profile `ZETA_CODING_AGENT_DIR` (see
  * {@link resolvePreProfileAgentDir}). Shared by the module-load resolver and
  * {@link refreshDirsFromEnv} so both apply identical logic.
  */
 function resolveActiveAgentDirOverride(): string | undefined {
-	return activeProfile
-		? undefined
-		: resolvePreProfileAgentDir(undefined, process.env.PI_CODING_AGENT_DIR, readPiProfileFromEnvSafe());
+	if (activeProfile) return undefined;
+	// A ZETA_CODING_AGENT_DIR pointing under a profile subtree
+	// (`profiles/<name>/agent`) is derived state inherited from a parent that
+	// activated a profile — with a single profile key there is no second env var
+	// to consult, so the directory shape is the only witness. Treat it as absent
+	// for default-mode resolution (and the pre-profile snapshot), or default mode
+	// would silently resolve into a profile's agent dir.
+	const env = process.env.ZETA_CODING_AGENT_DIR;
+	if (env && /[/\\]profiles[/\\][^/\\]+[/\\]agent$/.test(env.replace(/\\/g, "/"))) return undefined;
+	return resolvePreProfileAgentDir(undefined, env);
 }
 
 let dirs = new DirResolver({
@@ -435,21 +431,16 @@ let dirs = new DirResolver({
 	profile: activeProfile,
 });
 /**
- * Snapshot of `PI_CODING_AGENT_DIR` from before the first named-profile
+ * Snapshot of `ZETA_CODING_AGENT_DIR` from before the first named-profile
  * activation. Reset paths restore this value (or its absence) instead of
  * unconditionally deleting the env var. Without the snapshot, a process started
- * with `PI_CODING_AGENT_DIR=/custom` then `setProfile("work")` then
+ * with `ZETA_CODING_AGENT_DIR=/custom` then `setProfile("work")` then
  * `setProfile(undefined)` would silently lose `/custom` and fall back to
  * `~/.zeta/agent`. Captured at module load — ignoring a profile-derived value
- * inherited from a parent's `setProfile` (see {@link resolvePreProfileAgentDir})
- * — and refreshed on `setAgentDir`, since that call is the user explicitly
- * redefining the baseline.
+ * inherited from a parent's `setProfile` (detected by directory shape in
+ * {@link resolveActiveAgentDirOverride}) — and refreshed on `setAgentDir`.
  */
-let preProfileAgentDirEnv: string | undefined = resolvePreProfileAgentDir(
-	activeProfile,
-	process.env.PI_CODING_AGENT_DIR,
-	activeProfile ?? readPiProfileFromEnvSafe(),
-);
+let preProfileAgentDirEnv: string | undefined = resolveActiveAgentDirOverride();
 // Anchor home for the resolver. Captured at module load to stay stable across
 // test mocks of `os.homedir()`. `getPluginsDir(home)` compares against this so
 // production callers (`home === RESOLVER_HOME`) hit the XDG-aware resolver while
@@ -459,7 +450,7 @@ const RESOLVER_HOME = os.homedir();
 /**
  * Rebuild the dirs resolver from the current environment, reusing the profile
  * resolved at module load. Directory-affecting keys (XDG_*_HOME and, in default
- * mode, `PI_CODING_AGENT_DIR`) loaded from a profile/agent `.env` only reach
+ * mode, `ZETA_CODING_AGENT_DIR`) loaded from a profile/agent `.env` only reach
  * `process.env` *after* this module froze the resolver at import time, so
  * `env.ts` calls this once after applying its `.env` files. The agent `.env`
  * location derives from the profile name + home before this runs, so the
@@ -486,15 +477,14 @@ export function getConfigRootDir(): string {
 export function setAgentDir(dir: string): void {
 	activeProfile = undefined;
 	dirs = new DirResolver({ agentDirOverride: dir });
-	process.env.PI_CODING_AGENT_DIR = dir;
-	preProfileAgentDirEnv = dir;
+	process.env.ZETA_CODING_AGENT_DIR = dir;
 	for (const key of PROFILE_ENV_KEYS) {
 		delete process.env[key];
 	}
 }
 
 /**
- * Test-only: reset the pre-profile `PI_CODING_AGENT_DIR` snapshot to whatever
+ * Test-only: reset the pre-profile `ZETA_CODING_AGENT_DIR` snapshot to whatever
  * the current environment looks like. Cross-suite test pollution can otherwise
  * leak a stale snapshot through `setAgentDir` and corrupt `setProfile(undefined)`
  * restore semantics. Production code MUST NOT call this — the snapshot's
@@ -502,11 +492,7 @@ export function setAgentDir(dir: string): void {
  * no business clearing it.
  */
 export function __resetProfileSnapshotForTests(): void {
-	preProfileAgentDirEnv = resolvePreProfileAgentDir(
-		activeProfile,
-		process.env.PI_CODING_AGENT_DIR,
-		activeProfile ?? readPiProfileFromEnvSafe(),
-	);
+	preProfileAgentDirEnv = resolveActiveAgentDirOverride();
 }
 
 /**
@@ -521,35 +507,29 @@ export function __resetDirsFromEnvForTests(): void {
 	refreshDirsFromEnv();
 }
 
-/** Activate a named profile. Passing undefined or "default" returns to the default profile. */
 export function setProfile(profile: string | undefined): void {
 	const next = normalizeProfileName(profile);
 	if (next && !activeProfile) {
 		// First activation of a named profile in this process: snapshot the
-		// current PI_CODING_AGENT_DIR so a later reset can restore the user's
+		// current ZETA_CODING_AGENT_DIR so a later reset can restore the user's
 		// explicit override. Subsequent profile switches keep the original
 		// snapshot — the "pre-profile" baseline is the state before profiles
 		// entered the picture, not the state between two activations.
-		preProfileAgentDirEnv = resolvePreProfileAgentDir(
-			undefined,
-			process.env.PI_CODING_AGENT_DIR,
-			readPiProfileFromEnvSafe(),
-		);
+		preProfileAgentDirEnv = resolveActiveAgentDirOverride();
 	}
 	activeProfile = next;
 	if (activeProfile) {
 		dirs = new DirResolver({ profile: activeProfile });
-		process.env.OMP_PROFILE = activeProfile;
-		process.env.PI_PROFILE = activeProfile;
-		process.env.PI_CODING_AGENT_DIR = dirs.agentDir;
+		process.env.ZETA_PROFILE = activeProfile;
+		process.env.ZETA_CODING_AGENT_DIR = dirs.agentDir;
 	} else {
 		for (const key of PROFILE_ENV_KEYS) {
 			delete process.env[key];
 		}
 		if (preProfileAgentDirEnv === undefined) {
-			delete process.env.PI_CODING_AGENT_DIR;
+			delete process.env.ZETA_CODING_AGENT_DIR;
 		} else {
-			process.env.PI_CODING_AGENT_DIR = preProfileAgentDirEnv;
+			process.env.ZETA_CODING_AGENT_DIR = preProfileAgentDirEnv;
 		}
 		dirs = new DirResolver({ agentDirOverride: preProfileAgentDirEnv });
 	}

package/src/env.ts

@@ -112,9 +112,10 @@ export function filterChildShellEnv(
 	env: Record<string, string | undefined>,
 	cwd: string = process.cwd(),
 ): Record<string, string> {
+	const runtimeLaunchEnvValues = env === Bun.env || env === process.env ? launchEnvValues : undefined;
 	const result = filterProcessEnv(env);
 	const projectEnv = parseEnvFile(path.join(cwd, ".env"));
-	const launchNodeEnv = launchEnvValues ? launchEnvValues.get("NODE_ENV") : env.NODE_ENV;
+	const launchNodeEnv = runtimeLaunchEnvValues ? runtimeLaunchEnvValues.get("NODE_ENV") : env.NODE_ENV;
 	const nodeEnvName = `.env.${launchNodeEnv || "development"}`;
 	const modeEnv = parseEnvFile(path.join(cwd, nodeEnvName));
 	const localEnv = parseEnvFile(path.join(cwd, ".env.local"));
@@ -128,7 +129,7 @@ export function filterChildShellEnv(
 	};
 	let fallbackLaunchEnv: Record<string, string> | undefined;
 	let expandedFallbackLaunchEnv: Record<string, string> | undefined;
-	if (!launchEnvValues && nodeEnvName !== ".env.development") {
+	if (!runtimeLaunchEnvValues && nodeEnvName !== ".env.development") {
 		const fallbackModeEnv = parseEnvFile(path.join(cwd, ".env.development"));
 		const fallbackModeLocalEnv = parseEnvFile(path.join(cwd, ".env.development.local"));
 		const candidate = { ...projectEnv, ...fallbackModeEnv, ...localEnv, ...fallbackModeLocalEnv };
@@ -147,7 +148,7 @@ export function filterChildShellEnv(
 	}
 	const allLaunchEnv = fallbackLaunchEnv ? { ...launchEnv, ...fallbackLaunchEnv } : launchEnv;
 	for (const key in allLaunchEnv) {
-		const launchValue = launchEnvValues?.get(key);
+		const launchValue = runtimeLaunchEnvValues?.get(key);
 		if (launchValue !== undefined) {
 			// Launcher-owned name: it keeps the launcher's own value. Bun overwrites
 			// an empty launcher value with the dotenv one, so restore the launcher
@@ -163,7 +164,7 @@ export function filterChildShellEnv(
 			}
 			continue;
 		}
-		if (launchEnvValues || projectEnvNamesLoadedByOmp.has(key)) {
+		if (runtimeLaunchEnvValues || projectEnvNamesLoadedByOmp.has(key)) {
 			// Strong provenance: the launch environment is known and this name is
 			// absent from it, or OMP itself injected the value — either way it came
 			// from a project dotenv file, not the parent shell.
@@ -211,8 +212,7 @@ function parseEnvLine(line: string): { key: string; value: string } | undefined
 
 /**
  * Parses a .env file synchronously into key-value string pairs using
- * {@link parseEnvLine} for Bun-compatible line semantics, then mirrors valid
- * `OMP_` variables to their `PI_` aliases.
+ * {@link parseEnvLine} for Bun-compatible line semantics.
  */
 export function parseEnvFile(filePath: string): Record<string, string> {
 	const result: Record<string, string> = {};
@@ -226,13 +226,6 @@ export function parseEnvFile(filePath: string): Record<string, string> {
 		// File doesn't exist or can't be read - return empty result
 	}
 
-	// OMP_ overrides PI_
-	for (const k in result) {
-		if (k.startsWith("OMP_")) {
-			result[`PI_${k.slice(4)}`] = result[k];
-		}
-	}
-
 	return result;
 }
 
@@ -258,7 +251,7 @@ for (const file of [projectEnv, agentEnv, piEnv, homeEnv]) {
 	}
 }
 
-// Directory-affecting keys (XDG_*_HOME, and in default mode PI_CODING_AGENT_DIR)
+// Directory-affecting keys (XDG_*_HOME, and in default mode ZETA_CODING_AGENT_DIR)
 // may have just arrived from the profile/agent `.env` applied above. The dirs
 // resolver cached its paths at module load — before this file ran — so rebuild
 // it now from the updated env. `getAgentDir()` already located the `.env` from

package/src/procmgr.ts

@@ -82,6 +82,13 @@ export function isPowerShell(shell: string): boolean {
 	return basename === "powershell.exe" || basename === "powershell" || basename === "pwsh.exe" || basename === "pwsh";
 }
 
+const POSIX_SHELL_PATTERN = /(?:^|[\\/])(?:sh|bash|dash|ash|ksh|zsh)(?:\.exe)?$/i;
+
+/** Whether the executable is a known shell whose command language uses POSIX quoting. */
+export function isPosixShell(shell: string): boolean {
+	return POSIX_SHELL_PATTERN.test(shell);
+}
+
 /**
  * Get shell prefix for wrapping commands (profilers, strace, etc.).
  */