@pugi/cli 0.1.0-beta.9 → 0.1.0-beta.91

package/dist/core/pugi-md/context-injector.js

@@ -0,0 +1,76 @@
+/**
+ * Aggregate byte cap on the full rendered block. 96 KB = 3 files at
+ * the per-file cap, which is enough for cwd + parent + homedir while
+ * leaving plenty of prompt budget for the rest of the system prompt.
+ * Anything beyond is replaced with a truncation marker.
+ */
+export const MAX_INJECT_BYTES = 96 * 1024;
+/**
+ * Marker line emitted when the aggregate cap is hit. Visible to the
+ * model so it knows ambient context was clipped; visible to the
+ * operator via the doctor probe so they can decide whether to trim
+ * their `PUGI.md` hierarchy.
+ */
+export const TRUNCATION_MARKER = '<ambient-context-truncated reason="aggregate-cap" />';
+/**
+ * Render a HierarchyFile array into the system-prompt block. Returns
+ * `''` when `files` is empty. Each file becomes one
+ * `<ambient-context source="..." level="...">...</ambient-context>`
+ * stanza separated by a single newline.
+ *
+ * Determinism: same input always produces byte-identical output.
+ */
+export function renderAmbientContext(files) {
+    if (files.length === 0)
+        return '';
+    const stanzas = [];
+    let bytes = 0;
+    let truncated = false;
+    for (const file of files) {
+        const stanza = renderStanza(file);
+        const stanzaBytes = Buffer.byteLength(stanza, 'utf8') + 1; // newline join cost
+        if (bytes + stanzaBytes > MAX_INJECT_BYTES) {
+            truncated = true;
+            break;
+        }
+        stanzas.push(stanza);
+        bytes += stanzaBytes;
+    }
+    if (truncated)
+        stanzas.push(TRUNCATION_MARKER);
+    return stanzas.join('\n');
+}
+/**
+ * Build a single `<ambient-context>` stanza for one HierarchyFile.
+ * The `source` attribute carries the absolute path (after realpath)
+ * so the model can cite which file a piece of guidance came from
+ * when it explains its decisions to the operator.
+ */
+function renderStanza(file) {
+    const sourceAttr = escapeAttr(file.path);
+    const levelAttr = String(file.level);
+    // No trailing newline inside `content` — the join adds one between
+    // stanzas. Trimming the file's trailing whitespace keeps the tag
+    // close to the content for readability when an engineer dumps the
+    // assembled prompt for debugging.
+    const trimmed = file.content.replace(/\s+$/g, '');
+    return [
+        `<ambient-context source="${sourceAttr}" level="${levelAttr}">`,
+        trimmed,
+        `</ambient-context>`,
+    ].join('\n');
+}
+/**
+ * Escape an XML attribute value. We expect operator-controlled paths
+ * (not adversarial input) but `&`, `"` and `<` are still possible in
+ * symlinked / unicode paths so we escape them defensively. The model
+ * has been trained to read this attribute as opaque metadata.
+ */
+function escapeAttr(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+//# sourceMappingURL=context-injector.js.map

package/dist/core/pugi-md/walk-up.js

@@ -0,0 +1,207 @@
+/**
+ * — `PUGI.md` hierarchy walk-up to `$HOME`.
+ *
+ * the upstream tool walks from `cwd` upward toward the user's homedir and
+ * concatenates every `CLAUDE.md` it finds at each intermediate level
+ * (deepest overrides shallowest). Pugi parity: same walk, looking for
+ * `PUGI.md` first at each level and accepting `CLAUDE.md` as a fallback
+ * — operators often have a leftover `~/CLAUDE.md` or a parent-dir
+ * `CLAUDE.md` from a previous the upstream tool session and we want their
+ * ambient guidance picked up automatically without a migration step.
+ *
+ * Why this is a separate module from `core/context/markdown-traverse.ts`:
+ *
+ *  - `markdown-traverse.ts` is the *workspace-bounded* walk (cwd → up
+ *    to but NOT including `workspaceRoot`). It guards every read by
+ *    `realpathSync` containment against the workspace root and
+ *    refuses to escape — by design, because the per-dir markdown is
+ *    part of the project's first-party context.
+ *
+ *  - This module is the *home-bounded* walk (cwd → up to `homedir()`,
+ *    OR until depth limit). It picks up the operator's personal /
+ *    global guidance that lives ABOVE the workspace root. The two
+ *    surfaces are complementary: workspace markdown encodes project
+ *    conventions; this hierarchy walk encodes operator-level taste
+ *    (preferred libraries, "always run prettier", style guides).
+ *
+ * Contract:
+ *
+ *  - Walks from `cwd` upward. At each directory checks `PUGI.md`
+ *    (preferred); when absent falls back to `CLAUDE.md`. Only ONE
+ *    file per level is loaded — preferred wins.
+ *  - Stops at `homedir()` INCLUSIVE — the file at `~/PUGI.md` or
+ *    `~/CLAUDE.md` IS loaded (the upstream tool parity: a `~/CLAUDE.md`
+ *    applies to every project the operator opens).
+ *  - Hard depth cap of `MAX_WALK_DEPTH` (20) directories regardless
+ *    of how far cwd is from homedir; defense against symlinked or
+ *    malicious cwd values.
+ *  - Per-file byte cap `MAX_FILE_BYTES` (32 KB); over-cap files are
+ *    truncated, not rejected, so a runaway `PUGI.md` does not break
+ *    the prompt budget.
+ *  - Returns shallow-to-deep order (cwd FIRST, homedir LAST). The
+ *    caller is responsible for rendering precedence — the upstream tool's
+ *    rule is "deeper overrides shallower", which means the LAST
+ *    entry in the rendered system prompt wins. Our order matches
+ *    that convention so the context injector can splice directly.
+ *
+ * Safety:
+ *
+ *  - No `realpath` on the directories themselves: the operator's
+ *    cwd may live under a workspace symlink (common with macOS
+ *    `/private/var/...`) and we want to honor what the operator
+ *    sees in their shell. We DO resolve the candidate file via
+ *    `realpathSync` before reading, but only to defeat
+ *    symlinks-pointing-outside-homedir attacks; an off-tree symlink
+ *    is skipped silently.
+ *  - Catch + skip every fs error per file. The walk-up surface MUST
+ *    NEVER break engine boot — missing read perms on a parent dir
+ *    is the common case (e.g. `/etc` on a corp laptop) and the
+ *    fallback is "no ambient context", not a crash.
+ *
+ * Pure module: no logging, no network, no fs writes.
+ */
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+/**
+ * Hard ceiling on parent-dir traversal depth. 20 is generous — even
+ * deep monorepo layouts rarely sit more than 8-10 levels below the
+ * homedir on a developer's laptop. The cap exists so a misconfigured
+ * cwd (e.g. cwd outside the user's home filesystem entirely) cannot
+ * cause a multi-second fs scan of unrelated directories.
+ */
+export const MAX_WALK_DEPTH = 20;
+/**
+ * Per-file byte cap. 32 KB matches the per-dir markdown traverse
+ * aggregate budget — generous enough for a fully written-out
+ * project / personal `PUGI.md` (~8000 words) while keeping any one
+ * file from blowing the prompt budget on its own.
+ */
+export const MAX_FILE_BYTES = 32 * 1024;
+/**
+ * Filenames consulted at each level, in lookup order. `PUGI.md` is
+ * preferred — when both files coexist in a directory the Pugi-native
+ * file wins and the the upstream tool shim is ignored. This is the same
+ * precedence used by `markdown-traverse.ts` for workspace-bounded
+ * walks; keeping the two surfaces consistent removes the "why does
+ * Pugi sometimes read CLAUDE.md and sometimes PUGI.md?" foot-gun.
+ */
+export const HIERARCHY_SOURCES = ['PUGI.md', 'CLAUDE.md'];
+/**
+ * Walk from `cwd` upward, collecting ambient `PUGI.md` / `CLAUDE.md`
+ * files at each level until we reach the homedir (inclusive) or the
+ * depth cap.
+ *
+ * Returns an array ordered shallowest-first (cwd → homedir). When no
+ * files are found, returns `[]`. When `cwd` is OUTSIDE the homedir
+ * tree (e.g. the operator runs `pugi` from `/tmp`), the walk still
+ * proceeds upward but stops the moment we reach a filesystem root
+ * without ever entering the homedir — useful for ops/admin invocations
+ * where there is genuinely no personal context to load.
+ */
+export function walkUpPugiMd(cwd, opts = {}) {
+    const limit = clampLimit(opts.limit);
+    const home = opts.homedir;
+    let absCwd;
+    try {
+        absCwd = resolve(cwd);
+    }
+    catch {
+        return [];
+    }
+    const absHome = home ? resolve(home) : undefined;
+    const results = [];
+    let current = absCwd;
+    let level = 0;
+    const visited = new Set();
+    while (level <= limit) {
+        if (visited.has(current))
+            break; // pathological symlink loop guard
+        visited.add(current);
+        const found = tryLoadDirectory(current, level);
+        if (found)
+            results.push(found);
+        // Inclusive home boundary: load home if we are here, then stop.
+        if (absHome && current === absHome)
+            break;
+        const parent = dirname(current);
+        if (parent === current)
+            break; // hit filesystem root before homedir
+        current = parent;
+        level += 1;
+    }
+    return results;
+}
+/**
+ * Pick the first matching file in `dir`, read + cap it, and produce
+ * a HierarchyFile row. Returns `undefined` when no file in
+ * `HIERARCHY_SOURCES` exists or all reads error out (perms, symlink
+ * escape, etc.). NEVER throws — fs errors degrade to "no file at
+ * this level".
+ */
+function tryLoadDirectory(dir, level) {
+    for (const source of HIERARCHY_SOURCES) {
+        const candidate = resolve(dir, source);
+        if (!existsSync(candidate))
+            continue;
+        // Realpath the FILE to defeat symlink-points-elsewhere attacks.
+        // We do not realpath the directory itself — operators often run
+        // pugi from inside a workspace symlink and the walk should honor
+        // the path they see.
+        let realPath;
+        try {
+            realPath = realpathSync(candidate);
+        }
+        catch {
+            // Broken symlink or perms issue on the link itself. Skip this
+            // file and try the next source in the same directory.
+            continue;
+        }
+        let rawBytes;
+        try {
+            rawBytes = statSync(realPath).size;
+        }
+        catch {
+            continue;
+        }
+        let content;
+        try {
+            content = readFileSync(realPath, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        let truncated = false;
+        if (Buffer.byteLength(content, 'utf8') > MAX_FILE_BYTES) {
+            // Trim by character index sized to the byte cap. Mild over-trim
+            // on multi-byte boundaries is acceptable — we never under-trim
+            // (we'd exceed the cap) and the truncation is operator-visible
+            // via the `truncated` flag.
+            content = content.slice(0, MAX_FILE_BYTES);
+            truncated = true;
+        }
+        return {
+            path: realPath,
+            content,
+            level,
+            source,
+            truncated,
+            rawBytes,
+        };
+    }
+    return undefined;
+}
+/**
+ * Bound the limit to `[0, MAX_WALK_DEPTH]`. A negative or zero value
+ * still permits the cwd-level file to load (level 0 is always
+ * considered) — passing `limit: 0` means "current directory only".
+ */
+function clampLimit(limit) {
+    if (typeof limit !== 'number' || !Number.isFinite(limit))
+        return MAX_WALK_DEPTH;
+    if (limit < 0)
+        return 0;
+    if (limit > MAX_WALK_DEPTH)
+        return MAX_WALK_DEPTH;
+    return Math.floor(limit);
+}
+//# sourceMappingURL=walk-up.js.map

package/dist/core/python/uv-installer.js

@@ -0,0 +1,270 @@
+/**
+ * uv binary downloader + cache для Python skills runtime (#175 follow-up).
+ *
+ * Extends `uv-resolver.ts`: that module locates an existing uv on disk
+ * across 4 tiers; this module populates the second tier
+ * (`~/.pugi/bin/uv`) by fetching the official Astral release asset,
+ * verifying SHA-256, atomically installing к the bundled location, и
+ * leaving a `.uv-version` marker so later runs can tell which version
+ * landed without spawning the binary.
+ *
+ * Design choices:
+ *  - Pin a single version (`DEFAULT_UV_VERSION`) с frozen SHA-256
+ *    table. Multi-version cache + auto-upgrade is out of scope here.
+ *  - tarball-only support (.tar.gz). Linux + macOS only. Windows ships
+ *    `detectUvAsset` mapping but `downloadUv` throws unsupported when
+ *    handed the .zip — Windows install today goes through
+ *    `PUGI_UV_PATH` or Astral's PowerShell installer (uvInstallHint).
+ *    A real .zip extraction primitive lands в a follow-up.
+ *  - Atomic install: download к `uv.tmp.<rand>`, fsync directory,
+ *    rename к `uv`. Checksum mismatch deletes the tmp и throws —
+ *    final path is never partially written.
+ *  - All network I/O goes through the `opts.fetch` seam so the spec
+ *    never hits GitHub. Tests inject a stub Response с canned bytes.
+ *
+ * Refreshing pinned checksums:
+ *  gh release download <ver> --repo astral-sh/uv \
+ *    -p 'uv-aarch64-apple-darwin.tar.gz.sha256' \
+ *    -p 'uv-x86_64-apple-darwin.tar.gz.sha256' \
+ *    -p 'uv-x86_64-unknown-linux-gnu.tar.gz.sha256' \
+ *    -p 'uv-aarch64-unknown-linux-gnu.tar.gz.sha256' \
+ *    -p 'uv-x86_64-pc-windows-msvc.zip.sha256' -D /tmp/uv-sums
+ *  for f in /tmp/uv-sums/*.sha256; do head -1 "$f"; done
+ * Then paste the hex digests into `PINNED_CHECKSUMS` below.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { chmod, mkdir, open, rename, rm, stat, unlink, writeFile, readFile, } from 'node:fs/promises';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { createWriteStream } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { x as tarExtract } from 'tar';
+export const DEFAULT_UV_VERSION = '0.5.11';
+/**
+ * SHA-256 digests pinned per supported asset для `DEFAULT_UV_VERSION`.
+ *
+ * Source-of-truth: <https://github.com/astral-sh/uv/releases/download/
+ * 0.5.11/{asset}.sha256>. Verified. If you bump
+ * DEFAULT_UV_VERSION, refresh these via the gh-release-download recipe
+ * в the file header.
+ */
+const PINNED_CHECKSUMS = Object.freeze({
+    '0.5.11': Object.freeze({
+        'darwin-arm64': '695f3640d5b1a4e28de7e36e3a2e14072852dcc6c70bf9e4deec6ada00d516b4',
+        'darwin-x64': '7e23d1d892c23f9e74245c4fd3d3e246438ce9b34460f85eee61f784de137b0b',
+        'linux-x64': '14411de26cdea5f5139fafaf2b675b1c633e744dd49c6d6a9fc8817ec065158b',
+        'linux-arm64': '055c329c38a93c01d378349d51cb4d521d1998c8a79355ddc00f863ce451942f',
+        'win32-x64': '3e8203e6434b45427f20824419f8d8d53f970a76d94ccdcad07f8498fa01a9d0',
+    }),
+});
+const ASSET_TEMPLATES = Object.freeze({
+    'darwin-arm64': {
+        name: 'uv-aarch64-apple-darwin.tar.gz',
+        archive: 'tar.gz',
+        innerDir: 'uv-aarch64-apple-darwin',
+        exeName: 'uv',
+    },
+    'darwin-x64': {
+        name: 'uv-x86_64-apple-darwin.tar.gz',
+        archive: 'tar.gz',
+        innerDir: 'uv-x86_64-apple-darwin',
+        exeName: 'uv',
+    },
+    'linux-x64': {
+        name: 'uv-x86_64-unknown-linux-gnu.tar.gz',
+        archive: 'tar.gz',
+        innerDir: 'uv-x86_64-unknown-linux-gnu',
+        exeName: 'uv',
+    },
+    'linux-arm64': {
+        name: 'uv-aarch64-unknown-linux-gnu.tar.gz',
+        archive: 'tar.gz',
+        innerDir: 'uv-aarch64-unknown-linux-gnu',
+        exeName: 'uv',
+    },
+    'win32-x64': {
+        name: 'uv-x86_64-pc-windows-msvc.zip',
+        archive: 'zip',
+        innerDir: '',
+        exeName: 'uv.exe',
+    },
+});
+/**
+ * Translate a (platform, arch) pair к the canonical uv release asset.
+ *
+ * Throws when the host is unsupported (e.g. linux-arm 32-bit) — the
+ * caller should surface `uvInstallHint()` instead of attempting a
+ * download.
+ */
+export function detectUvAsset(platform, arch, version = DEFAULT_UV_VERSION) {
+    const key = mapPlatformArch(platform, arch);
+    if (!key) {
+        throw new Error(`uv installer: unsupported host platform=${platform} arch=${arch}. ` +
+            `Set PUGI_UV_PATH к an existing uv binary or install via the official script.`);
+    }
+    const tmpl = ASSET_TEMPLATES[key];
+    const sumTable = PINNED_CHECKSUMS[version];
+    if (!sumTable) {
+        throw new Error(`uv installer: no pinned checksums for version ${version}. ` +
+            `Either pass a version с entries в PINNED_CHECKSUMS or refresh the table.`);
+    }
+    const sha256 = sumTable[key];
+    if (!sha256) {
+        throw new Error(`uv installer: missing pinned sha256 for ${version}/${key}.`);
+    }
+    return {
+        assetName: tmpl.name,
+        url: `https://github.com/astral-sh/uv/releases/download/${version}/${tmpl.name}`,
+        sha256,
+        exeName: tmpl.exeName,
+        archive: tmpl.archive,
+        innerDir: tmpl.innerDir,
+    };
+}
+/**
+ * Download + verify + install uv к `<homeDir>/.pugi/bin/uv`.
+ * Atomic: nothing visible to the resolver lands until checksum passes.
+ */
+export async function downloadUv(opts = {}) {
+    const version = opts.version ?? DEFAULT_UV_VERSION;
+    const home = opts.homeDir ?? homedir();
+    const plat = opts.platform ?? process.platform;
+    const arch = opts.arch ?? process.arch;
+    const httpFetch = opts.fetch ?? fetch;
+    const asset = detectUvAsset(plat, arch, version);
+    if (asset.archive !== 'tar.gz') {
+        // Windows .zip extraction lands в a follow-up. Today, Windows
+        // users go through PUGI_UV_PATH or Astral's PowerShell installer.
+        throw new Error(`uv installer: archive=${asset.archive} not supported yet. ` +
+            `On Windows, run PowerShell: irm https://astral.sh/uv/install.ps1 | iex, ` +
+            `then point PUGI_UV_PATH at the resulting uv.exe.`);
+    }
+    const binDir = path.join(home, '.pugi', 'bin');
+    await mkdir(binDir, { recursive: true });
+    // Download к a randomly-named tmp в the same dir so rename() is atomic.
+    const tmpArchive = path.join(binDir, `.uv-archive.${randomBytes(8).toString('hex')}.tar.gz`);
+    const tmpExtractDir = path.join(binDir, `.uv-extract.${randomBytes(8).toString('hex')}`);
+    const finalBinary = path.join(binDir, asset.exeName);
+    const tmpBinary = `${finalBinary}.tmp.${randomBytes(8).toString('hex')}`;
+    const versionMarker = path.join(binDir, '.uv-version');
+    let downloadedHash = '';
+    try {
+        // 1. Fetch + stream к tmp file while hashing on the fly.
+        const response = await httpFetch(asset.url);
+        if (!response.ok) {
+            throw new Error(`uv installer: download failed ${response.status} ${response.statusText} for ${asset.url}`);
+        }
+        if (!response.body) {
+            throw new Error(`uv installer: fetch returned empty body for ${asset.url}`);
+        }
+        downloadedHash = await streamToFileWithHash(response.body, tmpArchive);
+        // 2. Verify SHA-256 BEFORE touching extraction.
+        const expectedSha = (opts.expectedSha256 ?? asset.sha256).toLowerCase();
+        if (downloadedHash.toLowerCase() !== expectedSha) {
+            throw new Error(`uv installer: SHA-256 mismatch for ${asset.assetName}. ` +
+                `Expected ${expectedSha}, got ${downloadedHash}. ` +
+                `Refusing к install — checksum table may be stale or download was tampered with.`);
+        }
+        // 3. Extract just the uv binary к tmpExtractDir.
+        await mkdir(tmpExtractDir, { recursive: true });
+        const innerPath = asset.innerDir
+            ? `${asset.innerDir}/${asset.exeName}`
+            : asset.exeName;
+        await tarExtract({
+            file: tmpArchive,
+            cwd: tmpExtractDir,
+            filter: (entryPath) => normalizeEntryPath(entryPath) === innerPath,
+        });
+        const extractedBinary = path.join(tmpExtractDir, innerPath);
+        const extractedStat = await stat(extractedBinary).catch(() => null);
+        if (!extractedStat || !extractedStat.isFile()) {
+            throw new Error(`uv installer: archive did not contain expected entry ${innerPath}`);
+        }
+        // 4. Move binary к its final tmp slot в binDir и chmod.
+        await rename(extractedBinary, tmpBinary);
+        await chmod(tmpBinary, 0o755);
+        // 5. Atomic swap — rename() over any existing uv binary.
+        await rename(tmpBinary, finalBinary);
+        // 6. Persist version marker AFTER binary lands so a partial install
+        //   never reports a stale version.
+        await writeFile(versionMarker, `${version}\n`, 'utf8');
+        return { installedAt: finalBinary, version };
+    }
+    catch (err) {
+        // Best-effort cleanup of any tmp artefacts. Final binary is left
+        // alone — either it was atomically swapped (success path) or it
+        // was never touched.
+        await unlink(tmpBinary).catch(() => undefined);
+        throw err;
+    }
+    finally {
+        await unlink(tmpArchive).catch(() => undefined);
+        await rm(tmpExtractDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+/**
+ * Read the `.uv-version` marker. Returns null when the marker is
+ * absent OR unreadable — callers should treat a null as "not installed
+ * via Pugi" и fall back к the resolver.
+ */
+export async function getInstalledVersion(home) {
+    const dir = home ?? homedir();
+    const marker = path.join(dir, '.pugi', 'bin', '.uv-version');
+    try {
+        const raw = await readFile(marker, 'utf8');
+        const trimmed = raw.trim();
+        return trimmed.length > 0 ? trimmed : null;
+    }
+    catch {
+        return null;
+    }
+}
+// --- internals --------------------------------------------------------------
+function mapPlatformArch(platform, arch) {
+    if (platform === 'darwin' && arch === 'arm64')
+        return 'darwin-arm64';
+    if (platform === 'darwin' && arch === 'x64')
+        return 'darwin-x64';
+    if (platform === 'linux' && arch === 'x64')
+        return 'linux-x64';
+    if (platform === 'linux' && arch === 'arm64')
+        return 'linux-arm64';
+    if (platform === 'win32' && arch === 'x64')
+        return 'win32-x64';
+    return null;
+}
+/**
+ * Stream a ReadableStream к disk while computing SHA-256. Returns
+ * the hex digest. Throws on any I/O error after best-effort cleanup
+ * of the partial file.
+ */
+async function streamToFileWithHash(body, dest) {
+    const hash = createHash('sha256');
+    const fileHandle = await open(dest, 'w');
+    const fileStream = createWriteStream(dest, { fd: fileHandle.fd, autoClose: false });
+    try {
+        // Node's `Readable.fromWeb` adapts a fetch body к a Node stream.
+        const nodeStream = Readable.fromWeb(body);
+        nodeStream.on('data', (chunk) => hash.update(chunk));
+        await pipeline(nodeStream, fileStream);
+        await fileHandle.sync().catch(() => undefined);
+        return hash.digest('hex');
+    }
+    finally {
+        await fileHandle.close().catch(() => undefined);
+    }
+}
+/**
+ * Normalize archive entry paths. tar entries may carry a leading `./`
+ * or trailing slash; the filter compares against `<innerDir>/<exe>`.
+ */
+function normalizeEntryPath(entryPath) {
+    let p = entryPath;
+    if (p.startsWith('./'))
+        p = p.slice(2);
+    if (p.endsWith('/'))
+        p = p.slice(0, -1);
+    return p;
+}
+//# sourceMappingURL=uv-installer.js.map

package/dist/core/python/uv-resolver.js

@@ -0,0 +1,83 @@
+/**
+ * uv binary path resolver для Python skills runtime .
+ *
+ * Pugi skills that author Python (data plots, light scripting,
+ * notebook generation) shell out to Astral's `uv` — the de-facto
+ * Python package + interpreter manager since 2024. We do NOT bundle
+ * uv ourselves в the npm tarball; binary distribution is the
+ * follow-up. This module does the cheap part: locate uv on disk и
+ * give callers a single answer about whether Python skills can run.
+ *
+ * Resolution order (first hit wins):
+ *  1. `PUGI_UV_PATH` env var — explicit override, no validation beyond exists()
+ *  2. `~/.pugi/bin/uv` — future bundled location (download follow-up)
+ *  3. `~/.local/bin/uv` — uv's own default install location
+ *  4. PATH lookup via `which` (isaacs, MIT, ~70M weekly DLs — npm itself uses it)
+ *
+ * Pure-ish: reads fs + env, but never spawns processes и never
+ * touches the network. Result is safe к cache for the session.
+ */
+import { stat } from 'node:fs/promises';
+import { homedir, platform } from 'node:os';
+import path from 'node:path';
+import which from 'which';
+/**
+ * Find uv on disk. Returns the first path that exists и appears
+ * к be a regular file. Never throws; not-found resolves к
+ * `{ path: null, source: 'not-found' }`.
+ */
+export async function resolveUvPath(deps = {}) {
+    const env = deps.env ?? process.env;
+    const home = deps.homeDir ?? homedir();
+    const plat = deps.platform ?? platform();
+    const exeName = plat === 'win32' ? 'uv.exe' : 'uv';
+    // 1. Env override
+    const envOverride = env.PUGI_UV_PATH;
+    if (envOverride && await fileExists(envOverride)) {
+        return { path: envOverride, source: 'env-override' };
+    }
+    // 2. Pugi bundled location (follow-up download will populate this)
+    const bundled = path.join(home, '.pugi', 'bin', exeName);
+    if (await fileExists(bundled)) {
+        return { path: bundled, source: 'pugi-bundled' };
+    }
+    // 3. uv's default install location
+    const localBin = path.join(home, '.local', 'bin', exeName);
+    if (await fileExists(localBin)) {
+        return { path: localBin, source: 'local-bin' };
+    }
+    // 4. PATH lookup — honour overridden env.PATH so tests can isolate
+    try {
+        const whichOptions = {};
+        if (env.PATH !== undefined) {
+            whichOptions.path = env.PATH;
+        }
+        const fromPath = await which(exeName, whichOptions);
+        if (fromPath)
+            return { path: fromPath, source: 'path-lookup' };
+    }
+    catch {
+        // which throws when not found — fall through к not-found
+    }
+    return { path: null, source: 'not-found' };
+}
+/** Human-readable install hint, ready для surfacing в pugi doctor. */
+export function uvInstallHint() {
+    const lines = [
+        'uv not found. Install via:',
+        ' macOS / Linux: curl -LsSf https://astral.sh/uv/install.sh | sh',
+        ' Windows:       powershell -c "irm https://astral.sh/uv/install.ps1 | iex"',
+        'Or set PUGI_UV_PATH к an existing binary.',
+    ];
+    return lines.join('\n');
+}
+async function fileExists(filePath) {
+    try {
+        const stats = await stat(filePath);
+        return stats.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=uv-resolver.js.map