@linxiraos/pi-utils 1.1.27 → 1.2.0

package/src/chalk.ts

@@ -257,14 +257,74 @@ function applyStyles(input: string, styles: readonly Style[]): string {
 	for (let index = styles.length - 1; index >= 0; index--) {
 		const style = styles[index];
 		if (!style) continue;
-		output = output.split(style.close).join(style.close + style.open);
+		if (output.includes(style.close)) output = output.split(style.close).join(style.close + style.open);
 		opening = style.open + opening;
 		closing += style.close;
 	}
-	output = output.replace(/\r?\n/g, match => `${closing}${match}${opening}`);
+	if (output.includes("\n")) output = output.replace(/\r?\n/g, match => `${closing}${match}${opening}`);
 	return opening + output + closing;
 }
 
+const BUILDER_CONTEXT = Symbol("chalk.context");
+const BUILDER_STYLES = Symbol("chalk.styles");
+const BUILDER_HEX_CACHE = Symbol("chalk.hexCache");
+// Bounds per-builder hex children when callers derive colors dynamically.
+const MAX_CACHED_HEX_BUILDERS = 256;
+
+interface BuilderState {
+	[BUILDER_CONTEXT]: ChalkContext;
+	[BUILDER_STYLES]: readonly Style[];
+	[BUILDER_HEX_CACHE]?: Map<string, ChalkInstance>;
+}
+
+type Builder = ChalkInstance & BuilderState;
+
+/** Child builders are created on first access and cached on the parent builder. */
+function defineStyleGetter(proto: object, name: string, style: Style): void {
+	Object.defineProperty(proto, name, {
+		get(this: Builder) {
+			const child = createBuilder(this[BUILDER_CONTEXT], [...this[BUILDER_STYLES], style]);
+			Object.defineProperty(this, name, { value: child });
+			return child;
+		},
+	});
+}
+
+const builderPrototype: object = Object.create(Function.prototype);
+Object.defineProperty(builderPrototype, "level", {
+	get(this: Builder) {
+		return this[BUILDER_CONTEXT].level;
+	},
+	set(this: Builder, level: number) {
+		this[BUILDER_CONTEXT].level = level;
+	},
+});
+for (const name in STYLES) {
+	const style = STYLES[name];
+	if (style) defineStyleGetter(builderPrototype, name, style);
+}
+defineStyleGetter(builderPrototype, "grey", STYLES.gray!);
+defineStyleGetter(builderPrototype, "bgGray", STYLES.bgBlackBright!);
+defineStyleGetter(builderPrototype, "bgGrey", STYLES.bgBlackBright!);
+Object.defineProperty(builderPrototype, "hex", {
+	value(this: Builder, color: string): ChalkInstance {
+		const context = this[BUILDER_CONTEXT];
+		const key = `${context.level}:${color}`;
+		let cache = this[BUILDER_HEX_CACHE];
+		const cached = cache?.get(key);
+		if (cached) return cached;
+		const child = createBuilder(context, [...this[BUILDER_STYLES], hexStyle(color, context.level)]);
+		if (!cache) {
+			cache = new Map();
+			this[BUILDER_HEX_CACHE] = cache;
+		} else if (cache.size >= MAX_CACHED_HEX_BUILDERS) {
+			cache.clear();
+		}
+		cache.set(key, child);
+		return child;
+	},
+});
+
 function createBuilder(context: ChalkContext, styles: readonly Style[]): ChalkInstance {
 	const builder = ((...values: unknown[]) => {
 		let text = "";
@@ -274,27 +334,10 @@ function createBuilder(context: ChalkContext, styles: readonly Style[]): ChalkIn
 		}
 		if (text.length === 0 || context.level === 0) return text;
 		return applyStyles(text, styles);
-	}) as ChalkInstance;
-	Object.defineProperty(builder, "level", {
-		get: () => context.level,
-		set: (level: number) => {
-			context.level = level;
-		},
-	});
-	for (const name in STYLES) {
-		const style = STYLES[name];
-		if (style) Object.defineProperty(builder, name, { get: () => createBuilder(context, [...styles, style]) });
-	}
-	Object.defineProperty(builder, "grey", { get: () => createBuilder(context, [...styles, STYLES.gray!]) });
-	Object.defineProperty(builder, "bgGray", {
-		get: () => createBuilder(context, [...styles, STYLES.bgBlackBright!]),
-	});
-	Object.defineProperty(builder, "bgGrey", {
-		get: () => createBuilder(context, [...styles, STYLES.bgBlackBright!]),
-	});
-	Object.defineProperty(builder, "hex", {
-		value: (color: string) => createBuilder(context, [...styles, hexStyle(color, context.level)]),
-	});
+	}) as Builder;
+	Object.setPrototypeOf(builder, builderPrototype);
+	builder[BUILDER_CONTEXT] = context;
+	builder[BUILDER_STYLES] = styles;
 	return builder;
 }
 

package/src/color.ts

@@ -399,6 +399,12 @@ export function oklchCusp(h: number): { l: number; c: number } {
 	return { l: lCusp, c: lCusp * sCusp };
 }
 
+/** Angular distance between two hues in degrees (0–180), wrapping at 360. */
+export function hueDistance(a: number, b: number): number {
+	const d = Math.abs(a - b) % 360;
+	return Math.min(d, 360 - d);
+}
+
 /** Slack allowed on linear channels before a color counts as out of sRGB gamut. */
 const GAMUT_EPSILON = 1e-4;
 

package/src/dirs.ts

@@ -1,12 +1,13 @@
 /**
- * Centralized path helpers for zeta-c config directories.
+ * Centralized path helpers for zetacode config directories.
  *
  * Uses PI_CONFIG_DIR (default ".zeta") for the config root and
+ * Uses ZETA_CONFIG_DIR (default ".zeta") for the config root and
  * 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
- * $XDG_*_HOME/zeta/. This requires running `zeta-c config migrate` first to
+ * $XDG_*_HOME/zeta/. This requires running `zetacode config migrate` first to
  * move data to the new locations. No filesystem existence checks are performed
  * — if the env var is set, zeta trusts that the migration has been done.
  */
@@ -22,11 +23,11 @@ import { isEnoent, isEnotdir } from "./fs-error";
  * names, provider attribution headers, splash wordmark. NOT the CLI command. */
 export const APP_NAME: string = "zeta";
 
-/** CLI binary name (`npm i -g @linxiraos/zeta` installs `zeta-c`, with
- * `zeta-cli` and `zetacode` as aliases). Every user-facing "run this command"
- * string and process title uses this; the bare `zeta` name belongs to the
- * @linxiraos/main workspace product, not this package. */
-export const CLI_BIN_NAME: string = "zeta-c";
+/** CLI binary name (`npm i -g @linxiraos/zeta` installs `zetacode`, with
+ * `zetacode` and `zeta-cli` as compatibility aliases). Every user-facing "run
+ * this command" string and process title uses this; the bare `zeta` name
+ * belongs to the @linxiraos/main workspace product, not this package. */
+export const CLI_BIN_NAME: string = "zetacode";
 
 /** Public homepage that inference gateways (OpenRouter, Vercel AI Gateway) credit our traffic to. */
 export const APP_URL: string = "https://linxira-os.github.io/zeta/";
@@ -125,6 +126,14 @@ function getProfileConfigRoot(profile: string | undefined): string {
 	return profile ? path.join(root, "profiles", profile) : root;
 }
 
+function readPiProfileFromEnvSafe(): string | undefined {
+	try {
+		return normalizeProfileName(process.env.ZETA_PROFILE);
+	} catch {
+		return undefined;
+	}
+}
+
 function getProfileAgentDir(profile: string): string {
 	return path.join(getProfileConfigRoot(profile), "agent");
 }
@@ -299,9 +308,9 @@ export function getSafeProjectCwd(): string {
 	return os.homedir();
 }
 
-/** Get the config directory name relative to home (e.g. ".zeta" or PI_CONFIG_DIR override). */
+/** Get the config directory name relative to home (e.g. ".zeta" or ZETA_CONFIG_DIR override). */
 export function getConfigDirName(): string {
-	return process.env.PI_CONFIG_DIR || CONFIG_DIR_NAME;
+	return process.env.ZETA_CONFIG_DIR || CONFIG_DIR_NAME;
 }
 
 /** Get the config agent directory name relative to home (e.g. ".zeta/agent" or PI_CONFIG_DIR + "/agent"). */
@@ -345,7 +354,7 @@ class DirResolver {
 		const isDefault = this.agentDir === defaultAgent;
 
 		// XDG is a Linux convention. On supported platforms, default profile state
-		// resolves under $XDG_*_HOME/zeta once `zeta-c config init-xdg` has migrated
+		// resolves under $XDG_*_HOME/zeta once `zetacode config init-xdg` has migrated
 		// the user's data. Named profiles follow a stricter rule: the XDG choice
 		// is keyed on the profile-specific XDG path, never the base app root.
 		//
@@ -454,8 +463,12 @@ class DirResolver {
  * without exporting it). Returns `undefined` in those cases so reset falls back
  * to the standard `~/.zeta/agent`.
  */
-function resolvePreProfileAgentDir(profile: string | undefined, agentDirEnv: string | undefined): string | undefined {
-	return isProfileDerivedAgentDir(profile, agentDirEnv) ? undefined : agentDirEnv;
+function resolvePreProfileAgentDir(
+	profile: string | undefined,
+	agentDirEnv: string | undefined,
+	profileAgentDirSource: string | undefined = profile,
+): string | undefined {
+	return isProfileDerivedAgentDir(profile ?? profileAgentDirSource, agentDirEnv) ? undefined : agentDirEnv;
 }
 
 let activeProfile = readProfileFromEnvSafe();
@@ -478,6 +491,9 @@ function resolveActiveAgentDirOverride(): string | undefined {
 	const env = process.env.ZETA_CODING_AGENT_DIR;
 	if (env && /[/\\]profiles[/\\][^/\\]+[/\\]agent$/.test(env.replace(/\\/g, "/"))) return undefined;
 	return resolvePreProfileAgentDir(undefined, env);
+	return activeProfile
+		? undefined
+		: resolvePreProfileAgentDir(undefined, process.env.ZETA_CODING_AGENT_DIR, readPiProfileFromEnvSafe());
 }
 
 let dirs = new DirResolver({
@@ -495,7 +511,11 @@ let dirs = new DirResolver({
  * — and refreshed on `setAgentDir`, since that call is the user explicitly
  * redefining the baseline.
  */
-let preProfileAgentDirEnv: string | undefined = resolveActiveAgentDirOverride();
+let preProfileAgentDirEnv: string | undefined = resolvePreProfileAgentDir(
+	activeProfile,
+	process.env.ZETA_CODING_AGENT_DIR,
+	activeProfile ?? readPiProfileFromEnvSafe(),
+);
 // 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
@@ -548,7 +568,11 @@ export function setAgentDir(dir: string): void {
  * no business clearing it.
  */
 export function __resetProfileSnapshotForTests(): void {
-	preProfileAgentDirEnv = resolveActiveAgentDirOverride();
+	preProfileAgentDirEnv = resolvePreProfileAgentDir(
+		activeProfile,
+		process.env.ZETA_CODING_AGENT_DIR,
+		activeProfile ?? readPiProfileFromEnvSafe(),
+	);
 }
 
 /**
@@ -573,11 +597,18 @@ export function setProfile(profile: string | undefined): void {
 		// snapshot — the "pre-profile" baseline is the state before profiles
 		// entered the picture, not the state between two activations.
 		preProfileAgentDirEnv = resolveActiveAgentDirOverride();
+		preProfileAgentDirEnv = resolvePreProfileAgentDir(
+			undefined,
+			process.env.ZETA_CODING_AGENT_DIR,
+			readPiProfileFromEnvSafe(),
+		);
 	}
 	activeProfile = next;
 	if (activeProfile) {
 		dirs = new DirResolver({ profile: activeProfile });
 		process.env.ZETA_PROFILE = activeProfile;
+		process.env.OMP_PROFILE = activeProfile;
+		process.env.PI_PROFILE = activeProfile;
 		process.env.ZETA_CODING_AGENT_DIR = dirs.agentDir;
 	} else {
 		for (const key of PROFILE_ENV_KEYS) {
@@ -669,13 +700,26 @@ export function getPluginsPackageJson(home?: string): string {
 	return path.join(getPluginsDir(home), "package.json");
 }
 
-/** Plugin lock file (~/.zeta/plugins/omp-plugins.lock.json). The on-disk
- * filename stays upstream-compatible so existing installs keep their runtime
- * state (enabled features, versions) across upgrades — never rebrand it. */
+/**
+ * Plugin lock file (~/.zeta/plugins/omp-plugins.lock.json).
+ *
+ * The on-disk filename stays upstream-compatible: it carries per-plugin runtime
+ * state (enabled flag, version), so renaming it would reset every existing
+ * install's plugins on upgrade. That is the reason for the compat, not a
+ * general rule — see `document/brand-surface-rules.md`, which classifies this
+ * surface as DUAL (read both spellings, write the Zeta one) rather than
+ * permanently frozen.
+ */
 export function getPluginsLockfile(home?: string): string {
 	return path.join(getPluginsDir(home), "omp-plugins.lock.json");
 }
 
+/** Zeta-named lockfile, written going forward; `getPluginsLockfile` is read first. */
+export const PLUGINS_LOCKFILE_CANONICAL = "zeta-plugins.lock.json";
+
+/** Pre-rename lockfile name still produced by earlier installs. */
+export const PLUGINS_LOCKFILE_LEGACY = "omp-plugins.lock.json";
+
 /**
  * Normalize a plugin id into a safe single path segment (spec §4.2): lowercased,
  * every character outside `[a-z0-9._-]` (including `/` and `\`, so scoped npm
@@ -762,11 +806,17 @@ export function getRemoteDir(): string {
  * empty/whitespace input or a path that is still relative after expansion.
  *
  * A worktree base is process-global and consumed by both creation
- * (PR checkout, task isolation) and cleanup (`zeta worktree`). A relative value
+ * (PR checkout, task isolation) and cleanup (`zetacode worktree`). A relative value
  * would resolve against whatever cwd happened to launch `zeta`, so checkout and
  * cleanup could disagree — we refuse it rather than silently bind it to cwd.
+ * Worktree bases and the natives directory are process-global: a worktree base
+ * is consumed by both creation (PR checkout, task isolation) and cleanup
+ * (`zetacode worktree`), and every launch extracts or loads the native addon from
+ * the same natives directory. A relative value would resolve against whatever
+ * cwd happened to launch `zetacode`, so those readers could disagree — we refuse it
+ * rather than silently bind it to cwd.
  */
-function resolveWorktreeBase(value: string | undefined): string | undefined {
+function resolveAbsoluteDir(value: string | undefined): string | undefined {
 	const trimmed = value?.trim();
 	if (!trimmed) return undefined;
 	let p = trimmed;
@@ -779,17 +829,17 @@ let worktreesDirOverride: string | undefined;
 
 /**
  * Relocate the base directory for agent-managed worktrees (PR checkouts, task
- * isolation, and `zeta worktree` cleanup all read the same base). Driven by the
+ * isolation, and `zetacode worktree` cleanup all read the same base). Driven by the
  * `worktree.base` setting in coding-agent; pass `undefined`/empty to clear and
  * fall back to `OMP_WORKTREE_DIR` or the `~/.zeta/wt` default.
  *
- * `~` is expanded and a relative path is rejected (see {@link resolveWorktreeBase}).
+ * `~` is expanded and a relative path is rejected (see {@link resolveAbsoluteDir}).
  * Returns the absolute path that took effect, or `undefined` if the input was
  * cleared or rejected — callers can warn on a non-empty input that returns
  * `undefined`.
  */
 export function setWorktreesDir(dir: string | undefined): string | undefined {
-	worktreesDirOverride = resolveWorktreeBase(dir);
+	worktreesDirOverride = resolveAbsoluteDir(dir);
 	return worktreesDirOverride;
 }
 
@@ -801,7 +851,7 @@ export function setWorktreesDir(dir: string | undefined): string | undefined {
  * ignored and resolution falls through.
  */
 export function getWorktreesDir(): string {
-	return resolveWorktreeBase(process.env.OMP_WORKTREE_DIR) ?? worktreesDirOverride ?? dirs.rootSubdir("wt", "data");
+	return resolveAbsoluteDir(process.env.OMP_WORKTREE_DIR) ?? worktreesDirOverride ?? dirs.rootSubdir("wt", "data");
 }
 
 /** Get the SSH control socket directory (~/.zeta/ssh-control). */
@@ -928,8 +978,18 @@ export function getFastembedRuntimeDir(): string {
 }
 
 /** Get the natives directory (~/.zeta/natives). */
+/**
+ * Get the directory the native addon loads downloaded tree-sitter wasm
+ * grammars from (`<natives dir>/grammars`, `~/.zeta/natives/grammars`). The
+ * natives loader configures the addon with the same path.
+ */
+export function getNativeGrammarsDir(): string {
+	return path.join(getNativesDir(), "grammars");
+}
+
+/** Get the natives directory. PI_NATIVES_DIR overrides the usual cache root; relative values are ignored. */
 export function getNativesDir(): string {
-	return dirs.rootSubdir("natives", "cache");
+	return resolveAbsoluteDir(process.env.PI_NATIVES_DIR) ?? dirs.rootSubdir("natives", "cache");
 }
 
 /** Get the stats database path (~/.zeta/stats.db). */

package/src/docx/converter.ts

@@ -1,6 +1,6 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { archiveEntryText, readArchiveEntries } from "../ar";
+import { ZipPackage } from "../ar";
 import { attribute, childElements, descendants, firstChild, localName, parseXml, type XmlElement } from "./xml";
 
 /** A mammoth-compatible diagnostic emitted while converting a document. */
@@ -26,6 +26,8 @@ export interface DocxImage {
 	readonly altText: string;
 	/** Read the image payload using mammoth's used encoding surface. */
 	read(encoding: "base64"): Promise<string>;
+	/** Read the raw image bytes without a base64 round trip. */
+	readBytes(): Promise<Uint8Array>;
 }
 
 /** HTML attributes returned by a custom image converter. */
@@ -119,7 +121,8 @@ interface NumberingLevel {
 }
 
 interface ConversionContext {
-	readonly entries: ReadonlyMap<string, Uint8Array>;
+	/** Lazily inflated DOCX members, capped on total inflated bytes. */
+	readonly package: ZipPackage;
 	readonly relationships: ReadonlyMap<string, Relationship>;
 	readonly contentTypes: ReadonlyMap<string, string>;
 	readonly styles: ReadonlyMap<string, Style>;
@@ -373,8 +376,8 @@ async function renderImage(element: XmlElement, context: ConversionContext): Pro
 	const relationship = relationshipId ? context.relationships.get(relationshipId) : undefined;
 	if (!relationship || relationship.external) return "";
 	const memberPath = relationshipPath(relationship.target);
-	const bytes = context.entries.get(memberPath);
-	if (!bytes) {
+	const docx = context.package;
+	if (!docx.members.has(memberPath)) {
 		context.messages.push({ type: "warning", message: `Could not find image ${memberPath}` });
 		return "";
 	}
@@ -391,8 +394,12 @@ async function renderImage(element: XmlElement, context: ConversionContext): Pro
 		altText,
 		async read(encoding: "base64"): Promise<string> {
 			if (encoding !== "base64") throw new Error(`Unsupported image encoding: ${encoding}`);
+			const bytes = await readImageMember(docx, memberPath);
 			return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("base64");
 		},
+		readBytes(): Promise<Uint8Array> {
+			return readImageMember(docx, memberPath);
+		},
 	};
 	const converted = await context.convertImage.convert(image);
 	const attributes = Object.entries(converted)
@@ -403,6 +410,13 @@ async function renderImage(element: XmlElement, context: ConversionContext): Pro
 	return attributes ? `<img ${attributes} />` : "<img />";
 }
 
+/** Bytes of an image member already known to exist. */
+async function readImageMember(docx: ZipPackage, memberPath: string): Promise<Uint8Array> {
+	const bytes = await docx.readBytes(memberPath);
+	if (!bytes) throw new Error(`Could not find image ${memberPath}`);
+	return bytes;
+}
+
 function renderFootnoteReference(element: XmlElement, context: ConversionContext): string {
 	const id = attribute(element, "w:id");
 	if (!id || !context.footnotes.has(id)) return "";
@@ -655,21 +669,21 @@ function defaultImageConverter(): ImageConverter {
 /** Convert a DOCX buffer or path to mammoth-compatible HTML. */
 export async function convertToHtml(input: DocxInput, options: ConvertToHtmlOptions = {}): Promise<DocxResult> {
 	const bytes = "buffer" in input && input.buffer ? input.buffer : await fs.readFile(input.path);
-	const entries = await readArchiveEntries({ bytes, format: "zip" });
-	const documentXml = archiveEntryText(entries, "word/document.xml");
+	const docx = await ZipPackage.open(bytes);
+	const documentXml = await docx.readText("word/document.xml");
 	if (!documentXml) throw new Error("Invalid DOCX: missing word/document.xml");
 	const context: ConversionContext = {
-		entries,
-		relationships: parseRelationships(archiveEntryText(entries, "word/_rels/document.xml.rels")),
-		contentTypes: parseContentTypes(archiveEntryText(entries, "[Content_Types].xml")),
-		styles: parseStyles(archiveEntryText(entries, "word/styles.xml")),
-		numbering: parseNumbering(archiveEntryText(entries, "word/numbering.xml")),
+		package: docx,
+		relationships: parseRelationships(await docx.readText("word/_rels/document.xml.rels")),
+		contentTypes: parseContentTypes(await docx.readText("[Content_Types].xml")),
+		styles: parseStyles(await docx.readText("word/styles.xml")),
+		numbering: parseNumbering(await docx.readText("word/numbering.xml")),
 		messages: [],
 		warnedStyles: new Set(),
 		customStyles: parseCustomStyles(options.styleMap),
 		includeDefaultStyleMap: options.includeDefaultStyleMap !== false,
 		convertImage: options.convertImage ?? defaultImageConverter(),
-		footnotes: parseFootnotes(archiveEntryText(entries, "word/footnotes.xml")),
+		footnotes: parseFootnotes(await docx.readText("word/footnotes.xml")),
 		usedFootnotes: [],
 		footnoteOrdinals: new Map(),
 	};