@linxiraos/pi-utils 1.0.0

package/dist/types/dirs.d.ts

@@ -0,0 +1,282 @@
+/**
+ * Centralized path helpers for omp config directories.
+ *
+ * Uses PI_CONFIG_DIR (default ".omp") for the config root and
+ * PI_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/omp/. This requires running `omp config migrate` first to
+ * move data to the new locations. No filesystem existence checks are performed
+ * — if the env var is set, omp trusts that the migration has been done.
+ */
+/** App name (e.g. "zeta") */
+export declare const APP_NAME: string;
+/** Config directory name (e.g. ".zeta") */
+export declare const CONFIG_DIR_NAME: string;
+/** Ordered main settings filenames: canonical write target first, legacy-compatible YAML fallback second. */
+export declare const MAIN_CONFIG_FILENAMES: readonly ["config.yml", "config.yaml"];
+/** Version (e.g. "1.0.0") */
+export declare const VERSION: string;
+/** Minimum Bun version */
+export declare const MIN_BUN_VERSION: string;
+/**
+ * Normalize and validate a profile name. Returns `undefined` for the implicit
+ * default (empty string, whitespace, or the explicit "default" sentinel) and
+ * throws for syntactically invalid or platform-reserved names.
+ *
+ * Exported so consumers of `@linxiraos/pi-utils/dirs` (CLI bootstrap, tests,
+ * downstream tools) can validate user input without re-deriving the rules.
+ */
+export declare function normalizeProfileName(profile: string | undefined): string | undefined;
+/**
+ * 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).
+ */
+export declare function resolveProfileEnv(omp: string | undefined, pi: string | undefined): string | undefined;
+export declare function resolveEquivalentPath(inputPath: string): string;
+export declare function normalizePathForComparison(inputPath: string): string;
+export declare function pathIsWithin(root: string, candidate: string): boolean;
+export declare function relativePathWithinRoot(root: string, candidate: string): string | null;
+/** Get the project directory. */
+export declare function getProjectDir(): string;
+/** Set the project directory. */
+export declare function setProjectDir(dir: string): void;
+/**
+ * Whether `dir` resolves to an existing directory. Any stat failure — a deleted
+ * path (ENOENT), permission error, or a non-directory — returns `false`, so
+ * callers can decide whether a directory is safe to `chdir` into or adopt as a
+ * working directory before {@link setProjectDir} throws on it.
+ */
+export declare function directoryExists(dir: string): Promise<boolean>;
+/** Get the config directory name relative to home (e.g. ".zeta" or PI_CONFIG_DIR override). Falls back to ".omp" for backward compatibility. */
+export declare function getConfigDirName(): string;
+/** Get the config agent directory name relative to home (e.g. ".omp/agent" or PI_CONFIG_DIR + "/agent"). */
+export declare function getConfigAgentDirName(): string;
+/**
+ * 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
+ * `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
+ * rebuild re-reads only the directory vars, never the profile selection. The
+ * `preProfileAgentDirEnv` snapshot is intentionally left untouched.
+ */
+export declare function refreshDirsFromEnv(): void;
+/** Get the config root directory (~/.omp). */
+export declare function getConfigRootDir(): string;
+/** Set the coding agent directory. Creates a fresh resolver, invalidating all cached paths. */
+export declare function setAgentDir(dir: string): void;
+/**
+ * Test-only: reset the pre-profile `PI_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
+ * lifecycle is owned by `setAgentDir` / `setProfile` and a runtime caller has
+ * no business clearing it.
+ */
+export declare function __resetProfileSnapshotForTests(): void;
+/**
+ * Test-only: rebuild profile + directory state from the current process env.
+ * Production code keeps the module-load profile stable; tests that mutate
+ * `setAgentDir`/`setProfile` need an exact restore point after they put env vars
+ * back.
+ */
+export declare function __resetDirsFromEnvForTests(): void;
+/** Activate a named profile. Passing undefined or "default" returns to the default profile. */
+export declare function setProfile(profile: string | undefined): void;
+/** Get the active named profile. Undefined means the default profile. */
+export declare function getActiveProfile(): string | undefined;
+/** Resolve the config root that backs a profile without activating it. */
+export declare function getProfileRootDir(profile: string | undefined): string;
+/** Get the agent config directory (~/.omp/agent). */
+export declare function getAgentDir(): string;
+/** Get the project-local config directory (.zeta). Falls back to .omp for backward compatibility. */
+export declare function getProjectAgentDir(cwd?: string): string;
+/** Get the reports directory (~/.omp/reports). */
+export declare function getReportsDir(): string;
+/** Get the logs directory (~/.omp/logs). */
+export declare function getLogsDir(): string;
+/** Get this process's dated log path (~/.omp/logs/omp.YYYY-MM-DD.PID.log). */
+export declare function getLogPath(date?: Date, pid?: number): string;
+/**
+ * Get the plugins directory (~/.omp/plugins or its XDG equivalent).
+ *
+ * No-arg form (production callers) goes through the XDG-aware DirResolver so
+ * reads and writes always agree. The optional `home` parameter is for test
+ * isolation: when it differs from `os.homedir()` it short-circuits the resolver
+ * and returns `<home>/<configDir>/plugins` so tests with a temp HOME get a
+ * deterministic path. Passing `os.homedir()` explicitly is identical to the
+ * no-arg form — XDG semantics are preserved.
+ */
+export declare function getPluginsDir(home?: string): string;
+/** Where npm installs packages (~/.omp/plugins/node_modules). */
+export declare function getPluginsNodeModules(home?: string): string;
+/** Plugin manifest (~/.omp/plugins/package.json). */
+export declare function getPluginsPackageJson(home?: string): string;
+/** Plugin lock file (~/.omp/plugins/omp-plugins.lock.json). */
+export declare function getPluginsLockfile(home?: string): string;
+/** Get the remote mount directory (~/.omp/remote). */
+export declare function getRemoteDir(): string;
+/**
+ * Relocate the base directory for agent-managed worktrees (PR checkouts, task
+ * isolation, and `omp 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 `~/.omp/wt` default.
+ *
+ * `~` is expanded and a relative path is rejected (see {@link resolveWorktreeBase}).
+ * 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 declare function setWorktreesDir(dir: string | undefined): string | undefined;
+/**
+ * Get the agent-managed worktrees directory. Resolution order: the
+ * `OMP_WORKTREE_DIR` env var, then the {@link setWorktreesDir} override (the
+ * `worktree.base` setting), then the `~/.omp/wt` default. The env var and the
+ * override are both `~`-expanded and must be absolute; a relative value is
+ * ignored and resolution falls through.
+ */
+export declare function getWorktreesDir(): string;
+/** Get the SSH control socket directory (~/.omp/ssh-control). */
+export declare function getSshControlDir(): string;
+/** Get the remote host info directory (~/.omp/remote-host). */
+export declare function getRemoteHostDir(): string;
+/** Get the managed Python venv directory (~/.omp/python-env). */
+export declare function getPythonEnvDir(): string;
+/** Get the shared Python gateway state directory (~/.omp/agent/python-gateway; XDG default: $XDG_STATE_HOME/omp/python-gateway). */
+export declare function getPythonGatewayDir(): string;
+/** Get the puppeteer sandbox directory (~/.omp/puppeteer). */
+export declare function getPuppeteerDir(): string;
+/** Get the browser relay extension install directory (~/.omp/browser-relay). */
+export declare function getBrowserRelayDir(): string;
+/** Get DOCS_RS cache directory () */
+export declare function getDocsRsCacheDir(): string;
+/** Get the auto-QA grievances SQLite database path (~/.omp/autoqa.db; XDG: $XDG_DATA_HOME/omp/autoqa.db). */
+export declare function getAutoQaDbPath(): string;
+/**
+ * Stable 7-character hex digest of an absolute filesystem path.
+ *
+ * Used to pack the project identity into a single short fs-safe segment
+ * (e.g. PR-checkout and task-isolation worktree dirs under `~/.omp/wt/`).
+ * Bun.hash is non-cryptographic — collision space is ~2^28, which is fine
+ * for naming a handful of repos on a single machine. Same input on the
+ * same Bun runtime yields the same output.
+ */
+export declare function hashPath(absPath: string): string;
+/** Get the path to a single worktree directory (~/.omp/wt/<segment>). */
+export declare function getWorktreeDir(segment: string): string;
+/** Get the GPU cache path (~/.omp/gpu_cache.json). */
+export declare function getGpuCachePath(): string;
+/**
+ * Get the GitHub view cache database path (~/.omp/cache/github-cache.db).
+ * Honors the `OMP_GITHUB_CACHE_DB` env var when set so tests can isolate the
+ * cache file without touching the rest of the config root.
+ */
+export declare function getGithubCacheDbPath(): string;
+/**
+ * Get the encrypted auth-broker snapshot cache path (~/.omp/cache/auth-broker-snapshot.enc).
+ * Honors the `OMP_AUTH_BROKER_SNAPSHOT_CACHE` env var when set so tests and
+ * operators can isolate or relocate the cache file.
+ */
+export declare function getAuthBrokerSnapshotCachePath(): string;
+/** Get the local FastEmbed model cache directory (~/.omp/cache/fastembed). */
+export declare function getFastembedCacheDir(): string;
+/** Get the on-demand fastembed runtime install root (~/.omp/cache/fastembed-runtime). */
+export declare function getFastembedRuntimeDir(): string;
+/** Get the natives directory (~/.omp/natives). */
+export declare function getNativesDir(): string;
+/** Get the stats database path (~/.omp/stats.db). */
+export declare function getStatsDbPath(): string;
+/** Get the autoresearch state directory (~/.omp/autoresearch). */
+export declare function getAutoresearchDir(): string;
+/** Get the per-project autoresearch state directory (~/.omp/autoresearch/<encoded-project>). */
+export declare function getAutoresearchProjectDir(encodedProject: string): string;
+/** Get the per-project autoresearch SQLite database path (~/.omp/autoresearch/<encoded-project>.db). */
+export declare function getAutoresearchDbPath(encodedProject: string): string;
+/** Get the per-run artifact directory (~/.omp/autoresearch/<encoded-project>/runs/<runId>). */
+export declare function getAutoresearchRunDir(encodedProject: string, runId: number): string;
+/** Get the security-analysis state directory (~/.omp/security). */
+export declare function getSecurityDir(): string;
+/** Get one project's security-analysis state directory (~/.omp/security/<project-key>). */
+export declare function getSecurityProjectDir(projectKey: string): string;
+/** Get the path to agent.db (SQLite database for settings and auth storage). */
+export declare function getAgentDbPath(agentDir?: string): string;
+/** Get the last-seen-changelog-version marker file (~/.omp/agent/last-changelog-version). */
+export declare function getLastChangelogVersionPath(agentDir?: string): string;
+/** Get the path to history.db (SQLite database for session history). */
+export declare function getHistoryDbPath(agentDir?: string): string;
+/** Get the path to models.db (model cache database). */
+export declare function getModelDbPath(agentDir?: string): string;
+/** Get the tiny title model cache directory (~/.omp/agent/cache/tiny-models). */
+export declare function getTinyModelsCacheDir(agentDir?: string): string;
+/** Get the document conversion cache directory (~/.omp/agent/cache/document-conversions; XDG default: $XDG_CACHE_HOME/omp/cache/document-conversions). */
+export declare function getDocumentConversionCacheDir(agentDir?: string): string;
+/** Get the sessions directory (~/.omp/agent/sessions). */
+export declare function getSessionsDir(agentDir?: string): string;
+/** Get the content-addressed blob store directory (~/.omp/agent/blobs). */
+export declare function getBlobsDir(agentDir?: string): string;
+/** Get the custom themes directory (~/.omp/agent/themes). */
+export declare function getCustomThemesDir(agentDir?: string): string;
+/** Get the tools directory (~/.omp/agent/tools). */
+export declare function getToolsDir(agentDir?: string): string;
+/** Get the slash commands directory (~/.omp/agent/commands). */
+export declare function getCommandsDir(agentDir?: string): string;
+/** Get the prompts directory (~/.omp/agent/prompts). */
+export declare function getPromptsDir(agentDir?: string): string;
+/** Get the user-level Python modules directory (~/.omp/agent/modules). */
+export declare function getAgentModulesDir(agentDir?: string): string;
+/** Get the memories directory (~/.omp/agent/memories). */
+export declare function getMemoriesDir(agentDir?: string): string;
+/** Get the terminal sessions directory (~/.omp/agent/terminal-sessions). */
+export declare function getTerminalSessionsDir(agentDir?: string): string;
+/** Get the crash log path (~/.omp/agent/omp-crash.log). */
+export declare function getCrashLogPath(agentDir?: string): string;
+/** Get the debug log path (~/.omp/agent/omp-debug.log). */
+export declare function getDebugLogPath(agentDir?: string): string;
+/** Get the secret placeholder key path (~/.omp/agent/secret-placeholder.key; XDG default: $XDG_STATE_HOME/omp/secret-placeholder.key). Adopts a legacy key on first XDG resolution. */
+export declare function getSecretPlaceholderKeyPath(): string;
+/** Get the daemon runtime directory for a project (~/.omp/run/daemons/<hash>; XDG default: $XDG_STATE_HOME/omp/run/daemons/<hash>). */
+export declare function getDaemonRuntimeDir(projectDir: string): string;
+/** Get a profile-independent runtime directory for a machine-global daemon service. */
+export declare function getGlobalDaemonRuntimeDir(service: string): string;
+/** Get the provider in-flight root directory (~/.omp/run/provider-inflight; XDG default: $XDG_STATE_HOME/omp/run/provider-inflight). */
+export declare function getProviderInFlightRoot(): string;
+/** Get the marketplaces registry path (~/.omp/marketplaces.json; XDG default: $XDG_DATA_HOME/omp/marketplaces.json). Adopts a legacy registry on first XDG resolution. */
+export declare function getMarketplacesRegistryPath(): string;
+/** Get the project-level Python modules directory (.omp/modules). */
+export declare function getProjectModulesDir(cwd?: string): string;
+/** Get the project-level prompts directory (.omp/prompts). */
+export declare function getProjectPromptsDir(cwd?: string): string;
+/** Get the project-level plugin overrides path (.omp/plugin-overrides.json). */
+export declare function getProjectPluginOverridesPath(cwd?: string): string;
+/** Get the primary MCP config file path (first candidate). */
+export declare function getMCPConfigPath(scope: "user" | "project", cwd?: string): string;
+/** Get the SSH config file path. */
+export declare function getSSHConfigPath(scope: "user" | "project", cwd?: string): string;
+/** Get the project-level tracking directory (<project>/.zeta/tracking). */
+export declare function getProjectTrackingDir(cwd?: string): string;
+/** Get the global tracking index path (~/.zeta/agent/tracking-index.json). */
+export declare function getTrackingIndexPath(agentDir?: string): string;
+/**
+ * Persistent per-install UUID stored at `~/.omp/install-id`.
+ *
+ * Generated lazily on first call and persisted with `O_CREAT|O_EXCL` so
+ * concurrent first-call races don't clobber each other (loser re-reads the
+ * winner's id). Survives independently of agent state: deleting
+ * `~/.omp/agent/` does not regenerate it. Server-side dedup for grievance
+ * pushes (and similar telemetry) keys on this id.
+ *
+ * Anchored to the base config root (`~/.omp/install-id`) regardless of the
+ * active profile: install identity is per-install, not per-profile, so every
+ * profile shares one id and the global cache stays correct no matter the
+ * profile / `getInstallId` call order.
+ */
+export declare function getInstallId(): string;
+/** Test-only: clear cached install id. Never call from production code. */
+export declare function __resetInstallIdCacheForTests(): void;

package/dist/types/docx/converter.d.ts

@@ -0,0 +1,46 @@
+/** A mammoth-compatible diagnostic emitted while converting a document. */
+export interface DocxMessage {
+    readonly type: "warning" | "error";
+    readonly message: string;
+}
+/** The HTML and diagnostics produced by a DOCX conversion. */
+export interface DocxResult {
+    readonly value: string;
+    readonly messages: DocxMessage[];
+}
+/** An in-memory or filesystem DOCX input. */
+export type DocxInput = {
+    readonly buffer: Uint8Array;
+    readonly path?: never;
+} | {
+    readonly path: string;
+    readonly buffer?: never;
+};
+/** An image exposed to a custom image converter. */
+export interface DocxImage {
+    readonly contentType: string;
+    readonly altText: string;
+    /** Read the image payload using mammoth's used encoding surface. */
+    read(encoding: "base64"): Promise<string>;
+}
+/** HTML attributes returned by a custom image converter. */
+export type ImageAttributes = Readonly<Record<string, string>>;
+/** A callback that maps an embedded DOCX image to HTML attributes. */
+export type ImageAttributeConverter = (image: DocxImage) => ImageAttributes | Promise<ImageAttributes>;
+/** An image converter created by `images.imgElement`. */
+export interface ImageConverter {
+    readonly convert: ImageAttributeConverter;
+}
+/** Options supported by the behavior-compatible DOCX converter. */
+export interface ConvertToHtmlOptions {
+    readonly convertImage?: ImageConverter;
+    readonly styleMap?: string | readonly string[];
+    readonly includeDefaultStyleMap?: boolean;
+}
+/** Mammoth-shaped helpers for configuring embedded image conversion. */
+export declare const images: {
+    /** Wrap an image-to-attributes callback for `convertToHtml`. */
+    imgElement(convert: ImageAttributeConverter): ImageConverter;
+};
+/** Convert a DOCX buffer or path to mammoth-compatible HTML. */
+export declare function convertToHtml(input: DocxInput, options?: ConvertToHtmlOptions): Promise<DocxResult>;

package/dist/types/docx/xml.d.ts

@@ -0,0 +1,26 @@
+interface XmlText {
+    readonly kind: "text";
+    readonly value: string;
+}
+/** A minimal XML element used by the DOCX reader. */
+export interface XmlElement {
+    readonly kind: "element";
+    readonly name: string;
+    readonly attributes: ReadonlyMap<string, string>;
+    readonly children: readonly XmlNode[];
+}
+/** A node in the DOCX reader's minimal XML tree. */
+export type XmlNode = XmlElement | XmlText;
+/** Return the namespace-independent part of an XML qualified name. */
+export declare function localName(name: string): string;
+/** Parse XML into a small namespace-tolerant element tree. */
+export declare function parseXml(source: string): XmlElement;
+/** Return direct element children, optionally filtered by local name. */
+export declare function childElements(element: XmlElement, name?: string): XmlElement[];
+/** Return the first direct child with the given local name. */
+export declare function firstChild(element: XmlElement | undefined, name: string): XmlElement | undefined;
+/** Return an attribute by qualified or namespace-independent name. */
+export declare function attribute(element: XmlElement | undefined, name: string): string | undefined;
+/** Return all descendant elements with a given local name. */
+export declare function descendants(element: XmlElement, name: string): XmlElement[];
+export {};

package/dist/types/docx/zip.d.ts

@@ -0,0 +1,6 @@
+/** The decompressed members of a DOCX ZIP package. */
+export type ZipEntries = ReadonlyMap<string, Uint8Array>;
+/** Decode a ZIP package by walking its central directory. */
+export declare function readZip(bytes: Uint8Array): ZipEntries;
+/** Decode a ZIP member as UTF-8 text. */
+export declare function readZipText(entries: ZipEntries, name: string): string | undefined;

package/dist/types/docx.d.ts

@@ -0,0 +1,11 @@
+/** Behavior-compatible reimplementation of mammoth's used surface. */
+export { type ConvertToHtmlOptions, convertToHtml, type DocxImage, type DocxInput, type DocxMessage, type DocxResult, type ImageAttributeConverter, type ImageAttributes, type ImageConverter, images, } from "./docx/converter.js";
+import { convertToHtml } from "./docx/converter.js";
+/** Mammoth-shaped default export for drop-in consumer imports. */
+declare const docx: {
+    convertToHtml: typeof convertToHtml;
+    images: {
+        imgElement(convert: import("./docx.js").ImageAttributeConverter): import("./docx.js").ImageConverter;
+    };
+};
+export default docx;