@youweichen/pi-harness 0.0.0-stage → 1.1.0

package/dist/server/control-socket.js

@@ -0,0 +1,178 @@
+/**
+ * Local control socket for the pi-harness server.
+ *
+ * Lets the CLI (and humans) query status and quiesce/unquiesce the server
+ * WITHOUT opening a network port or exposing an unauthenticated HTTP
+ * endpoint. Only the local OS user can reach it:
+ *   - POSIX: a mode-0600 Unix domain socket at <dataDir>/pi-harness.sock
+ *   - Windows: a named pipe  \\.\pipe\pi-harness-<port>
+ *
+ * Protocol: one JSON object per line.
+ *   → {"cmd":"status"}        ← {"ok":true, ...serviceStatus}
+ *   → {"cmd":"quiesce"}       ← {"ok":true}
+ *   → {"cmd":"unquiesce"}     ← {"ok":true}
+ *   → anything else           ← {"ok":false,"error":"..."}
+ *
+ * Idle connections are closed after a short timeout so a stuck CLI never
+ * holds the socket.
+ */
+import { createServer, createConnection } from "node:net";
+import { chmodSync, existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+/** How long a control connection may sit idle before the server closes it. */
+const CONTROL_IDLE_TIMEOUT_MS = 5_000;
+/** How long the CLI waits for a reply before giving up. */
+const CONTROL_CLIENT_TIMEOUT_MS = 3_000;
+/** Socket path (POSIX) or pipe name (Windows). */
+export function controlPath(dataDir, port) {
+    return process.platform === "win32"
+        ? `\\\\.\\pipe\\pi-harness-${port}`
+        : join(dataDir, "pi-harness.sock");
+}
+/** Start the control socket; returns a stop function. */
+export function startControlServer(opts) {
+    const { service, dataDir, port } = opts;
+    const path = controlPath(dataDir, port);
+    let server;
+    let stop = false;
+    if (process.platform === "win32") {
+        server = createServer(handleConnection);
+    }
+    else {
+        // Remove a stale socket left by a previous crash (only if it's ours —
+        // an existing socket file that refuses connections is stale).
+        if (existsSync(path)) {
+            try {
+                rmSync(path);
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+        server = createServer(handleConnection);
+    }
+    // A second instance on the same data dir / port would fail to bind — don't
+    // crash the server over it, just log and run without a control socket.
+    server.on("error", (err) => {
+        if (err.code === "EADDRINUSE") {
+            console.warn(`[control] socket ${path} already in use — control socket disabled`);
+        }
+        else {
+            console.warn(`[control] socket error: ${err.message}`);
+        }
+    });
+    function handleConnection(sock) {
+        let buf = "";
+        const timer = setTimeout(() => {
+            sock.destroy();
+        }, CONTROL_IDLE_TIMEOUT_MS);
+        sock.on("data", (chunk) => {
+            buf += chunk.toString("utf8");
+            let nl;
+            while ((nl = buf.indexOf("\n")) >= 0) {
+                const line = buf.slice(0, nl).trim();
+                buf = buf.slice(nl + 1);
+                if (!line)
+                    continue;
+                timer.refresh();
+                let req;
+                try {
+                    req = JSON.parse(line);
+                }
+                catch {
+                    sock.write(JSON.stringify({ ok: false, error: "bad json" }) + "\n");
+                    continue;
+                }
+                let resp;
+                switch (req.cmd) {
+                    case "status":
+                        resp = { ok: true, ...service.serviceStatus() };
+                        resp.activeConversations = (resp.activeConversations ?? 0) + (opts.additionalActiveConversations?.() ?? 0);
+                        break;
+                    case "quiesce":
+                        service.quiesce();
+                        resp = { ok: true };
+                        break;
+                    case "unquiesce":
+                        service.unquiesce();
+                        resp = { ok: true };
+                        break;
+                    default:
+                        resp = { ok: false, error: `unknown cmd: ${String(req.cmd)}` };
+                        break;
+                }
+                sock.write(JSON.stringify(resp) + "\n");
+            }
+        });
+        sock.on("error", () => {
+            /* client vanished */
+        });
+        sock.on("close", () => clearTimeout(timer));
+    }
+    if (process.platform === "win32") {
+        // net.Server on a named pipe: listen on the pipe name directly.
+        server.listen(path, () => {
+            console.log(`  control    : ${path}`);
+        });
+    }
+    else {
+        server.listen(path, () => {
+            try {
+                chmodSync(path, 0o600);
+            }
+            catch {
+                /* best-effort */
+            }
+            console.log(`  control    : ${path}`);
+        });
+    }
+    return () => {
+        stop = true;
+        server.close();
+        try {
+            if (process.platform !== "win32" && existsSync(path))
+                rmSync(path);
+        }
+        catch {
+            /* best-effort */
+        }
+    };
+}
+/**
+ * CLI-side client: send one command and return the parsed reply (or null if
+ * the server is unreachable / timed out).
+ */
+export function sendControlCommand(dataDir, port, cmd) {
+    const path = controlPath(dataDir, port);
+    return new Promise((resolve) => {
+        const sock = createConnection(path);
+        let done = false;
+        const finish = (v) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            sock.destroy();
+            resolve(v);
+        };
+        const timer = setTimeout(() => finish(null), CONTROL_CLIENT_TIMEOUT_MS);
+        let buf = "";
+        sock.on("connect", () => {
+            sock.write(JSON.stringify({ cmd }) + "\n");
+        });
+        sock.on("data", (chunk) => {
+            buf += chunk.toString("utf8");
+            const nl = buf.indexOf("\n");
+            if (nl >= 0) {
+                try {
+                    finish(JSON.parse(buf.slice(0, nl)));
+                }
+                catch {
+                    finish(null);
+                }
+            }
+        });
+        sock.on("error", () => finish(null));
+        sock.on("close", () => finish(null));
+    });
+}

package/dist/server/conversation.js

@@ -0,0 +1,65 @@
+/** Thrown when the service is quiesced (draining) and the request is NEW work
+ *  the admission controller refuses: a brand-new client attach, a prompt,
+ *  a fork, a session resume, or a goal wizard start. index.ts closes the
+ *  WebSocket with 4403 so the browser reconnect loop can retry after the
+ *  server reopens admission (see AgentService.quiesce). */
+export class QuiesceRejectedError extends Error {
+    code = "QUIESCED";
+    constructor(detail) {
+        super(`服务器正在排空存量工作（quiesce）——${detail}`);
+        this.name = "QuiesceRejectedError";
+    }
+}
+/** Cap on simultaneously open conversations of ONE project (each keeps a full
+ *  runtime alive; conversations of other projects keep their own lists). */
+export const MAX_OPEN_CONVERSATIONS = 8;
+export const DEFAULT_CONV_TITLE = "新对话";
+// Mirrors web/src/skill-block.ts's parseSkillBlock (which itself mirrors the
+// pi SDK's dist/core/agent-session.js) — kept in sync by hand, server and
+// web can't share a module across the tsconfig split. When the user sends
+// /skill:name args, the SDK expands the prompt into
+// `<skill name="..." location="...">\n...SKILL.md body...\n</skill>\n\n<args>`;
+// using that raw text as a conversation title would dump (and mid-sentence
+// truncate) the entire skill body instead of something readable.
+const SKILL_BLOCK_TITLE_RE = /^<skill name="([^"]+)" location="[^"]+">\n[\s\S]*?\n<\/skill>(?:\n\n([\s\S]+))?$/;
+export function skillAwareTitleText(text) {
+    const m = text.match(SKILL_BLOCK_TITLE_RE);
+    if (!m)
+        return text;
+    const name = m[1];
+    const args = m[2]?.trim();
+    return `skill:${name}` + (args ? ` · ${args}` : "");
+}
+/** First user text in a session, truncated for the conversation list. */
+export function conversationTitle(session) {
+    try {
+        for (const m of session.agent.state.messages) {
+            if (m.role !== "user")
+                continue;
+            const content = m.content;
+            let text = "";
+            if (typeof content === "string") {
+                text = content;
+            }
+            else if (Array.isArray(content)) {
+                for (const p of content) {
+                    if (p &&
+                        typeof p === "object" &&
+                        p.type === "text" &&
+                        typeof p.text === "string") {
+                        text = p.text;
+                        break;
+                    }
+                }
+            }
+            const trimmed = skillAwareTitleText(text).trim().replace(/\s+/g, " ");
+            if (trimmed.length > 0) {
+                return trimmed.length > 30 ? `${trimmed.slice(0, 30)}…` : trimmed;
+            }
+        }
+    }
+    catch {
+        // best-effort
+    }
+    return DEFAULT_CONV_TITLE;
+}

package/dist/server/dir-browser.js

@@ -0,0 +1,77 @@
+import { access, readdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+/** List subdirectories for the workspace picker (`browse_dirs`).
+ *
+ * Deliberately NOT routed through FilesService.listFiles(), which pins
+ * every listing inside the current workspace — choosing a new workspace
+ * is exactly the case that has to look outside it. Scope is kept narrow
+ * instead: directory *names* only, never file contents, and the same
+ * loopback binding + PI_WEB_TOKEN auth as every other message guards it.
+ * (The agent can already shell out with bash, so this exposes nothing it
+ * could not already reach — it just makes it clickable.)
+ */
+export async function browseDirs(path, emit) {
+    const MAX = 500;
+    const target = resolve(path?.trim() || homedir());
+    try {
+        const dirents = await readdir(target, { withFileTypes: true });
+        const dirs = [];
+        for (const d of dirents) {
+            // Symlinked directories are worth following (project checkouts
+            // are often symlinked), but a broken link must not abort the
+            // whole listing — isDirectory() is false for those, which is
+            // the behaviour we want anyway.
+            if (!d.isDirectory())
+                continue;
+            if (d.name.startsWith("."))
+                continue; // dotfolders: noise here
+            dirs.push(d.name);
+            if (dirs.length >= MAX)
+                break;
+        }
+        dirs.sort((a, b) => a.localeCompare(b));
+        const parent = dirname(target);
+        emit({
+            type: "dir_browse",
+            path: target,
+            parent: parent === target ? null : parent,
+            dirs,
+            truncated: dirs.length >= MAX,
+            drives: await listWindowsDrives(),
+        });
+    }
+    catch (err) {
+        emit({
+            type: "notice",
+            level: "error",
+            text: `无法读取目录：${err.message}`,
+        });
+    }
+}
+/**
+ * Windows drive roots that currently exist ("C:\\", "D:\\", …); empty on
+ * POSIX (where "/" already reaches everything).
+ *
+ * Needed because Windows has no unified filesystem root: dirname("C:\\") is
+ * "C:\\", so the picker's walk-up hits a ceiling on the boot drive and can
+ * never reach D:. Probing A–Z with access() avoids shelling out to wmic /
+ * PowerShell (both slow to spawn, and wmic is gone on recent Windows).
+ * Missing/empty drives simply reject, so they drop out.
+ */
+async function listWindowsDrives() {
+    if (process.platform !== "win32")
+        return undefined;
+    const letters = Array.from({ length: 26 }, (_, i) => String.fromCharCode(65 + i));
+    const found = await Promise.all(letters.map(async (letter) => {
+        const root = `${letter}:\\`;
+        try {
+            await access(root);
+            return root;
+        }
+        catch {
+            return null;
+        }
+    }));
+    return found.filter((d) => d !== null);
+}

package/dist/server/editor-snapshot.js

@@ -0,0 +1,38 @@
+import { realpathSync, statSync, openSync, readSync, closeSync } from "node:fs";
+import { resolve, relative, isAbsolute, sep } from "node:path";
+import { looksLikeText, previewKind } from "./text-sniff.js";
+/** Validate every snapshot before any attachment side effects or history fork. */
+export function validateEditorSnapshots(cwd, attachments) {
+    for (const att of attachments ?? []) {
+        if (att.editorSnapshot === undefined)
+            continue;
+        const s = att.editorSnapshot;
+        if (!s || typeof s.cwd !== "string" || s.cwd !== cwd || typeof s.text !== "string" ||
+            typeof s.dirty !== "boolean" || (s.version !== undefined && typeof s.version !== "string") ||
+            typeof att.path !== "string" || !att.path || att.mode === "lines" || att.imageData || att.fileData || att.uploadPath) {
+            throw new Error("当前文件快照身份或类型无效，请重新打开文件");
+        }
+        if (Buffer.byteLength(s.text, "utf8") > 512 * 1024)
+            throw new Error("当前文件快照超过 512 KiB，请缩减内容或移除标签");
+        const root = realpathSync(cwd);
+        const abs = resolve(cwd, att.path);
+        for (const [boundary, path] of [[resolve(cwd), abs], [root, realpathSync(abs)]]) {
+            const rel = relative(boundary, path);
+            if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+                throw new Error("当前文件路径超出工作区");
+        }
+        if (!statSync(abs).isFile() || !["text", "none"].includes(previewKind(att.path)) || !looksLikeText(Buffer.from(s.text))) {
+            throw new Error("当前文件快照必须是文本文件");
+        }
+        const fd = openSync(abs, "r");
+        try {
+            const sample = Buffer.alloc(4096);
+            const length = readSync(fd, sample, 0, sample.length, 0);
+            if (!looksLikeText(sample.subarray(0, length)))
+                throw new Error("当前文件不是可编辑文本");
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+}

package/dist/server/ensure-bash.js

@@ -0,0 +1,80 @@
+/**
+ * Lightweight bash fallback for Windows.
+ *
+ * When neither Git Bash nor a bash on PATH exists, download busybox-w32
+ * (single self-contained ~1.5MB exe, no installer) into <home>/.pi-web/bin/
+ * and expose it as bash.exe — busybox dispatches on argv[0], so `bash.exe`
+ * runs its bash (ash) applet. The terminal panel (terminals.ts) and the SDK
+ * bash tool (via PATH) then both resolve to it, so the agent never silently
+ * falls back to cmd/PowerShell syntax on a bare Windows box.
+ *
+ * Download is fire-and-forget at server start and never throws: on failure
+ * the terminal simply falls back to $COMSPEC (cmd.exe) as before.
+ */
+import { copyFileSync, existsSync, mkdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Official busybox-w32 64-bit Unicode build (Win10 1903+ / Win11). */
+const BUSYBOX_URL = "https://frippery.org/files/busybox/busybox64u.exe";
+/** busybox.exe is ~660KB; anything far smaller is an error page, not a binary. */
+const MIN_SIZE = 500_000;
+/** Download cap — a stalled connection must not block startup forever. */
+const DOWNLOAD_TIMEOUT_MS = 60_000;
+/** Directory holding the busybox fallback (shared with terminals.ts / PATH). */
+export function windowsBashDir() {
+    return join(homedir(), ".pi-web", "bin");
+}
+/** bash.exe (busybox bash applet) used by the terminal and the SDK bash tool. */
+export function windowsBashPath() {
+    return join(windowsBashDir(), "bash.exe");
+}
+/** True when a standard Git Bash install exists (SDK's preferred shell). */
+export function hasGitBash() {
+    const pf = process.env.ProgramFiles;
+    const pf86 = process.env["ProgramFiles(x86)"];
+    for (const cand of [
+        pf ? join(pf, "Git", "bin", "bash.exe") : "",
+        pf86 ? join(pf86, "Git", "bin", "bash.exe") : "",
+    ]) {
+        if (cand && existsSync(cand))
+            return true;
+    }
+    return false;
+}
+/**
+ * Ensure a bash.exe exists on Windows. No-op when Git Bash is already
+ * installed (it is strictly preferred) or the fallback is already present.
+ * Never throws — failures degrade silently to the previous behaviour.
+ *
+ * @returns the bash.exe path when ready, null otherwise.
+ */
+export async function ensureWindowsBash() {
+    if (process.platform !== "win32")
+        return null;
+    const target = windowsBashPath();
+    if (existsSync(target))
+        return target;
+    if (hasGitBash())
+        return null; // Git Bash preferred — nothing to install.
+    const dir = windowsBashDir();
+    mkdirSync(dir, { recursive: true });
+    const tmp = join(dir, `busybox-${process.pid}.tmp`);
+    try {
+        const res = await fetch(BUSYBOX_URL, {
+            signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+        });
+        if (!res.ok)
+            return null;
+        const buf = Buffer.from(await res.arrayBuffer());
+        if (buf.length < MIN_SIZE)
+            return null; // error/HTML page, not the exe.
+        writeFileSync(tmp, buf);
+        renameSync(tmp, join(dir, "busybox.exe"));
+        copyFileSync(join(dir, "busybox.exe"), target);
+        return target;
+    }
+    catch {
+        rmSync(tmp, { force: true });
+        return null;
+    }
+}

package/dist/server/extension-display.js

@@ -0,0 +1,23 @@
+/** Display-only metadata. Toggle/uninstall identities remain owned by the loader. */
+export function extensionDisplay(path, source) {
+    const normalized = path.replaceAll("\\", "/").replace(/\/$/, "");
+    if (source?.startsWith("npm:"))
+        return { name: source.slice(4) };
+    const marker = "/node_modules/";
+    const packagePath = normalized.slice(normalized.lastIndexOf(marker) + marker.length);
+    if (normalized.includes(marker)) {
+        const parts = packagePath.split("/");
+        const name = parts[0]?.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+        if (name)
+            return { name };
+    }
+    const parts = normalized.split("/").filter(Boolean);
+    const filename = parts.pop() ?? "";
+    const stem = filename.replace(/\.(?:[cm]?[jt]s|tsx|jsx)$/i, "");
+    if (!/^(?:index|main|extension|plugin)$/i.test(stem))
+        return { name: stem || source || path };
+    // Entry points commonly sit in build/source folders beneath the extension.
+    while (parts.length && /^(?:src|dist|lib|build|extensions?|\.pi)$/i.test(parts.at(-1)))
+        parts.pop();
+    return { name: parts.at(-1) || source || filename };
+}

package/dist/server/extensions-catalog.js

@@ -0,0 +1,64 @@
+const cache = new Map();
+export async function cachedFetch(url, json = true) {
+    const old = cache.get(url);
+    if (old && old.until > Date.now())
+        return old.value;
+    const value = (async () => { const response = await fetch(url, { signal: AbortSignal.timeout(15000), headers: { Accept: json ? "application/json" : "text/html" } }); if (!response.ok)
+        throw Error(`Package catalog: HTTP ${response.status}`); const text = await response.text(); if (text.length > 8_000_000)
+        throw Error("Catalog response too large"); return json ? JSON.parse(text) : text; })();
+    cache.set(url, { until: Date.now() + 300000, value });
+    if (cache.size > 128)
+        cache.delete(cache.keys().next().value);
+    try {
+        return await value;
+    }
+    catch (error) {
+        cache.delete(url);
+        throw error;
+    }
+}
+export function safeUrl(value) { if (typeof value !== "string")
+    return; try {
+    const u = new URL(value.replace(/^git\+/, ""));
+    if (["https:", "http:"].includes(u.protocol) && !u.username && !u.password)
+        return u.href;
+}
+catch { } }
+const decode = (text) => text.replace(/&(?:amp|quot|lt|gt|apos|#39|#x[0-9a-f]+|#\d+);/gi, entity => ({ "&amp;": "&", "&quot;": '"', "&lt;": "<", "&gt;": ">", "&apos;": "'", "&#39;": "'" }[entity] ?? String.fromCodePoint(Number(entity.startsWith("&#x") ? `0x${entity.slice(3, -1)}` : entity.slice(2, -1)))));
+const plain = (s) => decode(s.replace(/<[^>]*>/g, "")).trim();
+/** Pi currently serves its catalog as HTML. Extract only data attributes/text, never render remote HTML. */
+export function parseCatalog(html, page) {
+    const items = [];
+    for (const match of html.matchAll(/<article\b[^>]*data-package-card="true"[\s\S]*?<\/article>/g)) {
+        const text = match[0], attr = (name) => decode(new RegExp(`${name}="([^"]*)"`).exec(text)?.[1] ?? "");
+        const name = attr("data-package-name");
+        if (!name)
+            continue;
+        const meta = /class="packages-meta">([\s\S]*?)<\/div>/.exec(text)?.[1] ?? "";
+        items.push({ name, description: plain(/class="packages-desc">([\s\S]*?)<\/p>/.exec(text)?.[1] ?? ""), author: plain(/<span>(.*?)<\/span>/.exec(meta)?.[1] ?? ""), downloads: attr("data-package-downloads") && Number.isFinite(Number(attr("data-package-downloads"))) ? Number(attr("data-package-downloads")) : undefined, date: Number(attr("data-package-date")) || undefined, types: attr("data-package-types").split(/[ ,]+/).filter(Boolean), url: `https://pi.dev/packages/${name}`, version: /package-version=([^"&]+)/.exec(text)?.[1], image: safeUrl(/<img[^>]*src="([^"]+)"/.exec(text)?.[1]), repository: safeUrl(/href="(https:\/\/github.com\/(?!earendil-works\/pi\/issues)[^"]+)"/.exec(text)?.[1]) });
+    }
+    if (!items.length && !/packages-grid|No packages|No results/i.test(html))
+        throw Error("Pi catalog format changed; open pi.dev/packages");
+    const pages = Math.max(page, ...[...html.matchAll(/[?&](?:amp;)?page=(\d+)/g)].map(m => Number(m[1])));
+    const count = /class="packages-count">\s*[\d,]+-[\d,]+\s*\/\s*([\d,]+)/.exec(html)?.[1];
+    return { items, page, pages, ...(count ? { total: Number(count.replaceAll(",", "")) } : {}) };
+}
+export async function browseCatalog(query, type, sort, page) {
+    const params = new URLSearchParams({ name: query.slice(0, 200), type: ["extension", "skill", "prompt", "theme"].includes(type) ? type : "", sort: sort === "recent" ? "recent" : "downloads", page: String(Math.max(1, Math.min(1000, page))) });
+    return parseCatalog(await cachedFetch(`https://pi.dev/packages?${params}`, false), page);
+}
+export async function packageReleaseNotes(name) {
+    const meta = await cachedFetch(`https://registry.npmjs.org/${encodeURIComponent(name)}/latest`);
+    const repository = safeUrl(typeof meta.repository === "string" ? meta.repository : meta.repository?.url);
+    const match = repository && /^https:\/\/github.com\/([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/.exec(repository);
+    if (!match)
+        return { title: meta.version ?? "", notes: [] };
+    try {
+        const release = await cachedFetch(`https://api.github.com/repos/${match[1]}/${match[2]}/releases/latest`);
+        const notes = typeof release.body === "string" ? release.body.split("\n").map((line) => line.trim()).filter((line) => /^[-*] /.test(line)).slice(0, 3).map((line) => line.slice(2, 800)) : [];
+        return { title: String(release.tag_name ?? meta.version), notes, url: safeUrl(release.html_url) };
+    }
+    catch {
+        return { title: meta.version ?? "", notes: [], url: `${repository?.replace(/\.git$/, "")}/releases` };
+    }
+}

package/dist/server/extensions-model.js

@@ -0,0 +1,46 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+export const textField = (value) => typeof value === "string" ? value.slice(0, 4000) : undefined;
+export const resourceTypes = ["extensions", "skills", "prompts", "themes"];
+export const sourceOf = (entry) => typeof entry === "string" ? entry : entry.source;
+export function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return {};
+        throw error;
+    }
+}
+export function settingsVersion(cwd, agentDir) {
+    return createHash("sha256").update(JSON.stringify([readJson(join(agentDir, "settings.json")), readJson(join(cwd, ".pi/settings.json"))])).digest("hex");
+}
+export function packageDisabled(entry) { return typeof entry !== "string" && resourceTypes.every(type => Array.isArray(entry[type]) && entry[type].length === 0); }
+export function sourceInfo(source) {
+    const npm = /^npm:((?:@[a-z0-9._-]+\/)?[a-z0-9._-]+)(?:@([^\s]+))?$/i.exec(source);
+    if (npm)
+        return { kind: "npm", name: npm[1], ref: npm[2], pinned: /^\d+\.\d+\.\d+(?:[-+][\w.-]+)?$/.test(npm[2] ?? ""), unpinned: `npm:${npm[1]}` };
+    if (/^(git:|https?:\/\/|git@|ssh:\/\/)/.test(source)) {
+        const ref = /(?:\.git|\/[^/@]+)@(.+)$/.exec(source)?.[1] ?? /#([^#]+)$/.exec(source)?.[1];
+        return { kind: "git", name: source, ref, pinned: !!ref, unpinned: ref ? source.slice(0, -(ref.length + 1)) : source };
+    }
+    return { kind: "local", name: source.split(/[\\/]/).at(-1) || source, pinned: false, unpinned: source };
+}
+export function validateSource(value, cwd) {
+    if (typeof value !== "string" || !value.trim() || value.length > 2048 || /[\x00-\x1f]/.test(value))
+        throw Error("Invalid package source");
+    const source = value.trim();
+    if (source.startsWith("-"))
+        throw Error("Invalid package source");
+    if (source.startsWith("npm:")) {
+        if (sourceInfo(source).kind !== "npm")
+            throw Error("Invalid npm source");
+        return source;
+    }
+    if (/^(git:|https?:\/\/|git@|ssh:\/\/)/.test(source))
+        return source;
+    return resolve(cwd, source.startsWith("~/") ? join(homedir(), source.slice(2)) : source);
+}