promptdock 0.1.0

package/dist/installer.js

@@ -0,0 +1,206 @@
+// The two-phase install engine (shared by `install` and `update`):
+//   POST install → download to a SIBLING temp dir → verify EVERY sha256 →
+//   re-validate EVERY path (E8/audit row 10 — the server is untrusted) →
+//   atomic move into place (same-parent rename; staged replace on update) →
+//   write the receipt → best-effort /install/complete.
+// All-or-nothing: any failure discards the temp dir and leaves the target
+// exactly as it was ("integrity check failed — nothing installed").
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { CliError, EXIT, mapFsError, networkError } from "./errors.js";
+import { MAX_SKILL_FILES, MAX_SKILL_FILE_BYTES, MAX_SKILL_TOTAL_BYTES, } from "./generated/constants.js";
+import { sha256Hex, sha256Matches } from "./integrity.js";
+import { validateSkillPaths } from "./paths.js";
+import { writeReceipt, RECEIPT_SCHEMA } from "./receipts.js";
+const INTEGRITY_ABORT = "integrity check failed — nothing installed";
+/** Narrow the untrusted install response; throws INTEGRITY on a bad shape. */
+export function checkInstallResponse(resp) {
+    const bad = () => new CliError(`${INTEGRITY_ABORT} (malformed server response)`, EXIT.INTEGRITY, {
+        footer: "integrity",
+    });
+    if (typeof resp !== "object" || resp === null)
+        throw bad();
+    const r = resp;
+    if (!r.skill || typeof r.skill.version_id !== "string" || typeof r.skill.slug !== "string")
+        throw bad();
+    if (!Array.isArray(r.manifest) || !Array.isArray(r.files))
+        throw bad();
+    for (const e of r.manifest) {
+        if (typeof e?.path !== "string" || typeof e?.sha256 !== "string")
+            throw bad();
+    }
+    for (const f of r.files) {
+        if (typeof f?.path !== "string" || typeof f?.url !== "string")
+            throw bad();
+    }
+    return r;
+}
+/**
+ * E8 client-side re-validation + the shared D7 bounds. A server compromise must
+ * not become an arbitrary file write OR a disk-filling download.
+ */
+export function assertSafeManifest(manifest) {
+    const issues = validateSkillPaths(manifest.map((e) => e.path));
+    if (issues.length > 0) {
+        const first = issues[0];
+        throw new CliError(`unsafe file path in manifest ("${first.path}": ${first.reason}) — refusing to install`, EXIT.INTEGRITY, { footer: "manifest_path" });
+    }
+    if (manifest.length === 0 || manifest.length > MAX_SKILL_FILES) {
+        throw new CliError(`manifest lists ${manifest.length} files (limit ${MAX_SKILL_FILES}) — refusing to install`, EXIT.INTEGRITY, { footer: "manifest_bounds" });
+    }
+    let total = 0;
+    for (const e of manifest) {
+        const bytes = Number(e.bytes) || 0;
+        if (bytes > MAX_SKILL_FILE_BYTES) {
+            throw new CliError(`manifest entry "${e.path}" exceeds the ${MAX_SKILL_FILE_BYTES / (1024 * 1024)}MB per-file limit — refusing to install`, EXIT.INTEGRITY, { footer: "manifest_bounds" });
+        }
+        total += bytes;
+    }
+    if (total > MAX_SKILL_TOTAL_BYTES) {
+        throw new CliError(`manifest totals ${total} bytes (limit ${MAX_SKILL_TOTAL_BYTES}) — refusing to install`, EXIT.INTEGRITY, { footer: "manifest_bounds" });
+    }
+}
+/**
+ * Download every manifest file into `<parent>/.promptdock-staging-*` (SIBLING of
+ * the target so the final rename never crosses filesystems), verifying sha256 +
+ * byte length against the manifest. Throws (and discards the temp dir) on ANY
+ * mismatch — the sha in the manifest is the transport-integrity anchor.
+ */
+export async function downloadAndStage(ctx, api, resp, targetDir) {
+    assertSafeManifest(resp.manifest);
+    const urlByPath = new Map(resp.files.map((f) => [f.path, f.url]));
+    const parent = dirname(targetDir);
+    try {
+        mkdirSync(parent, { recursive: true });
+    }
+    catch (err) {
+        throw mapFsError(err, parent);
+    }
+    const tempDir = join(parent, `.promptdock-staging-${randomBytes(6).toString("hex")}`);
+    const files = [];
+    try {
+        mkdirSync(tempDir, { recursive: true });
+        for (const entry of resp.manifest) {
+            const url = urlByPath.get(entry.path);
+            if (!url) {
+                throw new CliError(`${INTEGRITY_ABORT} (no download URL for "${entry.path}")`, EXIT.INTEGRITY, {
+                    footer: "integrity",
+                });
+            }
+            let res;
+            try {
+                res = await ctx.fetch(url);
+            }
+            catch {
+                throw networkError(api.baseUrl, ctx.env);
+            }
+            if (!res.ok) {
+                // A lapsed signed URL is a free re-request (audit row 13) — say so.
+                throw new CliError(`download failed for "${entry.path}" (HTTP ${res.status}) — re-run the install (the download link may have expired; retrying is free)`, EXIT.NETWORK, { footer: "download" });
+            }
+            const buf = Buffer.from(await res.arrayBuffer());
+            if (buf.byteLength > MAX_SKILL_FILE_BYTES) {
+                throw new CliError(`${INTEGRITY_ABORT} ("${entry.path}" oversized)`, EXIT.INTEGRITY, {
+                    footer: "integrity",
+                });
+            }
+            if (!sha256Matches(buf, entry.sha256)) {
+                throw new CliError(`${INTEGRITY_ABORT} (sha256 mismatch on "${entry.path}")`, EXIT.INTEGRITY, {
+                    footer: "integrity",
+                });
+            }
+            const abs = join(tempDir, entry.path); // path already validated relative + traversal-free
+            try {
+                mkdirSync(dirname(abs), { recursive: true });
+                writeFileSync(abs, buf);
+            }
+            catch (err) {
+                throw mapFsError(err, abs);
+            }
+            files.push({ path: entry.path, sha256: sha256Hex(buf) });
+        }
+        return { tempDir, files };
+    }
+    catch (err) {
+        rmSync(tempDir, { recursive: true, force: true });
+        throw err;
+    }
+}
+/**
+ * Atomic-ish commit: fresh target → one rename; existing target → staged
+ * replace (target → .promptdock-old-*, temp → target, drop old; on failure the
+ * old dir is restored). Same-parent renames only.
+ */
+export function commitStaged(tempDir, targetDir) {
+    const parent = dirname(targetDir);
+    if (!existsSync(targetDir)) {
+        try {
+            renameSync(tempDir, targetDir);
+        }
+        catch (err) {
+            rmSync(tempDir, { recursive: true, force: true });
+            throw mapFsError(err, targetDir);
+        }
+        return;
+    }
+    const oldDir = join(parent, `.promptdock-old-${randomBytes(6).toString("hex")}`);
+    try {
+        renameSync(targetDir, oldDir);
+    }
+    catch (err) {
+        rmSync(tempDir, { recursive: true, force: true });
+        throw mapFsError(err, targetDir);
+    }
+    try {
+        renameSync(tempDir, targetDir);
+    }
+    catch (err) {
+        // Roll the old contents back — the machine must never end up with NOTHING.
+        try {
+            renameSync(oldDir, targetDir);
+        }
+        catch {
+            /* the old dir stays on disk for manual recovery */
+        }
+        rmSync(tempDir, { recursive: true, force: true });
+        throw mapFsError(err, targetDir);
+    }
+    rmSync(oldDir, { recursive: true, force: true });
+}
+/**
+ * The full phase-2: download → verify → commit → receipt → best-effort complete.
+ * `refString` is the canonical handle/slug; `prior` carries a matching update's
+ * receipt so unknown fields survive the rewrite (DX F16).
+ */
+export async function performInstall(ctx, api, opts) {
+    const staged = await downloadAndStage(ctx, api, opts.resp, opts.targetDir);
+    commitStaged(staged.tempDir, opts.targetDir);
+    const receipt = {
+        schema: RECEIPT_SCHEMA,
+        cli_version: ctx.version,
+        skill_id: opts.resp.skill.id,
+        ref: opts.refString,
+        version_id: opts.resp.skill.version_id,
+        version: opts.resp.skill.version,
+        installed_at: new Date(ctx.now()).toISOString(),
+        target: opts.targetId,
+        files: staged.files,
+    };
+    try {
+        writeReceipt(opts.targetDir, receipt, opts.prior);
+    }
+    catch (err) {
+        throw mapFsError(err, join(opts.targetDir, ".promptdock.json"));
+    }
+    // E5 phase 2 — best-effort: the files are on disk either way; the server's
+    // grace sweep expires an uncompleted ticket, and a retryable complete is
+    // idempotent. Never fail a finished install over this call.
+    try {
+        await api.request("POST", `/api/v1/cli/skills/${opts.resp.skill.id}/install/complete`);
+    }
+    catch {
+        /* best-effort */
+    }
+    return receipt;
+}

package/dist/integrity.d.ts

@@ -0,0 +1,4 @@
+/** sha256 hex of a buffer — the manifest's integrity anchor. */
+export declare function sha256Hex(data: Uint8Array | Buffer): string;
+/** Constant-shape compare (case-forgiving hex; empty expected = never matches). */
+export declare function sha256Matches(data: Uint8Array | Buffer, expectedHex: string): boolean;

package/dist/integrity.js

@@ -0,0 +1,11 @@
+import { createHash } from "node:crypto";
+/** sha256 hex of a buffer — the manifest's integrity anchor. */
+export function sha256Hex(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+/** Constant-shape compare (case-forgiving hex; empty expected = never matches). */
+export function sha256Matches(data, expectedHex) {
+    if (!/^[0-9a-fA-F]{64}$/.test(expectedHex))
+        return false;
+    return sha256Hex(data) === expectedHex.toLowerCase();
+}

package/dist/paths.d.ts

@@ -0,0 +1,5 @@
+export type PathIssue = {
+    path: string;
+    reason: string;
+};
+export declare function validateSkillPaths(paths: string[]): PathIssue[];

package/dist/paths.js

@@ -0,0 +1,63 @@
+// Port of lib/validation/skills.ts validateSkillPaths (E8 / audit row 10): the
+// CLI RE-CHECKS every manifest path before ANY write — a compromised server must
+// never become an arbitrary file write on an installer machine. Keep this port
+// line-for-line with the app original; test/paths-parity.test.ts mirrors the
+// app's vectors so a one-sided edit is a red test.
+const WINDOWS_RESERVED = new Set([
+    "con", "prn", "aux", "nul",
+    ...Array.from({ length: 9 }, (_, i) => `com${i + 1}`),
+    ...Array.from({ length: 9 }, (_, i) => `lpt${i + 1}`),
+]);
+export function validateSkillPaths(paths) {
+    const issues = [];
+    const seen = new Map(); // normalized key -> original
+    for (const p of paths) {
+        if (p.length === 0 || p.length > 256) {
+            issues.push({ path: p, reason: "path length" });
+            continue;
+        }
+        if (p.includes("\\")) {
+            issues.push({ path: p, reason: "backslash separator" });
+            continue;
+        }
+        if (p.startsWith("/") || /^[a-zA-Z]:/.test(p)) {
+            issues.push({ path: p, reason: "absolute path" });
+            continue;
+        }
+        if (/[\u0000-\u001f\u007f]/.test(p)) {
+            issues.push({ path: p, reason: "control characters" });
+            continue;
+        }
+        const segments = p.split("/");
+        let bad = false;
+        for (const seg of segments) {
+            if (seg === "" || seg === "." || seg === "..") {
+                issues.push({ path: p, reason: "path traversal segment" });
+                bad = true;
+                break;
+            }
+            const base = seg.toLowerCase().split(".")[0];
+            if (WINDOWS_RESERVED.has(base)) {
+                issues.push({ path: p, reason: `Windows reserved name "${seg}"` });
+                bad = true;
+                break;
+            }
+            if (seg.endsWith(" ") || seg.endsWith(".")) {
+                issues.push({ path: p, reason: "trailing space/dot segment" });
+                bad = true;
+                break;
+            }
+        }
+        if (bad)
+            continue;
+        // Case-insensitive + NFC-normalized collision detection (macOS/Windows default FS).
+        const key = p.normalize("NFC").toLowerCase();
+        const prior = seen.get(key);
+        if (prior !== undefined && prior !== p) {
+            issues.push({ path: p, reason: `collides with "${prior}" on case-insensitive filesystems` });
+            continue;
+        }
+        seen.set(key, p);
+    }
+    return issues;
+}

package/dist/receipts.d.ts

@@ -0,0 +1,58 @@
+export declare const RECEIPT_NAME = ".promptdock.json";
+export declare const RECEIPT_SCHEMA = 1;
+export type ReceiptFile = {
+    path: string;
+    sha256: string;
+};
+export type Receipt = {
+    schema: number;
+    cli_version: string;
+    skill_id: string;
+    /** canonical `handle/slug` */
+    ref: string;
+    version_id: string;
+    version: number;
+    installed_at: string;
+    /** target registry id, or "custom" for --dir installs */
+    target: string;
+    files: ReceiptFile[];
+    /** forward-compat: unknown fields from newer CLIs survive rewrites */
+    [key: string]: unknown;
+};
+export type ReadReceipt = {
+    kind: "ok";
+    receipt: Receipt;
+} | {
+    kind: "none";
+} | {
+    kind: "newer_schema";
+    schema: number;
+} | {
+    kind: "invalid";
+};
+export declare function readReceipt(dir: string): ReadReceipt;
+/** Write the receipt; `prior` carries unknown fields forward (DX F16). */
+export declare function writeReceipt(dir: string, receipt: Receipt, prior?: Receipt): void;
+export type InstalledSkill = {
+    dir: string;
+    targetId: string;
+    scope: "local" | "global";
+    read: ReadReceipt;
+};
+/**
+ * Scan the known target dirs for receipts (U2/DX F5 scope rules: bare commands
+ * see project-local; -g sees global; --all sees both). Never follows symlinked
+ * skill dirs (a symlinked dir could point outside the scan root).
+ */
+export declare function scanReceipts(opts: {
+    cwd: string;
+    home: string;
+    scope: "local" | "global" | "both";
+    targetId?: string;
+}): InstalledSkill[];
+/**
+ * DX5 local-edit guard: diff on-disk hashes vs the receipt manifest. A missing
+ * file or a symlink where a regular file should be counts as modified (the
+ * guard's job is "would uninstall/update destroy human work?").
+ */
+export declare function modifiedFiles(dir: string, receipt: Receipt): string[];

package/dist/receipts.js

@@ -0,0 +1,121 @@
+// <dir>/.promptdock.json — the install receipt (DX5, audit row 4). THE ONLY
+// uninstall/update authority: the CLI never deletes a file a receipt doesn't
+// list. schema:1; unknown fields are PRESERVED across rewrites; a NEWER schema
+// is a "run npx promptdock@latest" refusal, never a guessy uninstall (DX F16).
+import { lstatSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { sha256Hex } from "./integrity.js";
+import { TARGETS, targetBaseDir } from "./registry.js";
+export const RECEIPT_NAME = ".promptdock.json";
+export const RECEIPT_SCHEMA = 1;
+export function readReceipt(dir) {
+    let raw;
+    try {
+        raw = readFileSync(join(dir, RECEIPT_NAME), "utf8");
+    }
+    catch {
+        return { kind: "none" };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { kind: "invalid" };
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return { kind: "invalid" };
+    const r = parsed;
+    if (typeof r.schema !== "number")
+        return { kind: "invalid" };
+    if (r.schema > RECEIPT_SCHEMA)
+        return { kind: "newer_schema", schema: r.schema };
+    if (typeof r.skill_id !== "string" ||
+        typeof r.ref !== "string" ||
+        typeof r.version_id !== "string" ||
+        !Array.isArray(r.files)) {
+        return { kind: "invalid" };
+    }
+    const files = [];
+    for (const f of r.files) {
+        if (typeof f !== "object" || f === null)
+            return { kind: "invalid" };
+        const { path, sha256 } = f;
+        if (typeof path !== "string" || typeof sha256 !== "string")
+            return { kind: "invalid" };
+        files.push({ path, sha256 });
+    }
+    return { kind: "ok", receipt: { ...r, files } };
+}
+/** Write the receipt; `prior` carries unknown fields forward (DX F16). */
+export function writeReceipt(dir, receipt, prior) {
+    const merged = prior ? { ...prior, ...receipt } : receipt;
+    writeFileSync(join(dir, RECEIPT_NAME), JSON.stringify(merged, null, 2) + "\n");
+}
+/**
+ * Scan the known target dirs for receipts (U2/DX F5 scope rules: bare commands
+ * see project-local; -g sees global; --all sees both). Never follows symlinked
+ * skill dirs (a symlinked dir could point outside the scan root).
+ */
+export function scanReceipts(opts) {
+    const out = [];
+    const scopes = opts.scope === "both" ? ["local", "global"] : [opts.scope];
+    const targets = opts.targetId
+        ? TARGETS.filter((t) => t.id === opts.targetId)
+        : TARGETS;
+    const seenDirs = new Set();
+    for (const scope of scopes) {
+        for (const t of targets) {
+            const base = targetBaseDir(t, { cwd: opts.cwd, home: opts.home, global: scope === "global" });
+            let entries;
+            try {
+                entries = readdirSync(base);
+            }
+            catch {
+                continue;
+            }
+            for (const name of entries) {
+                const dir = join(base, name);
+                if (seenDirs.has(dir))
+                    continue; // claude local==global base when cwd==home
+                try {
+                    if (!lstatSync(dir).isDirectory())
+                        continue; // skips symlinked dirs too
+                }
+                catch {
+                    continue;
+                }
+                const read = readReceipt(dir);
+                if (read.kind === "none")
+                    continue;
+                seenDirs.add(dir);
+                out.push({ dir, targetId: t.id, scope, read });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * DX5 local-edit guard: diff on-disk hashes vs the receipt manifest. A missing
+ * file or a symlink where a regular file should be counts as modified (the
+ * guard's job is "would uninstall/update destroy human work?").
+ */
+export function modifiedFiles(dir, receipt) {
+    const modified = [];
+    for (const f of receipt.files) {
+        const abs = join(dir, f.path);
+        try {
+            const st = lstatSync(abs);
+            if (!st.isFile()) {
+                modified.push(f.path);
+                continue;
+            }
+            if (sha256Hex(readFileSync(abs)) !== f.sha256.toLowerCase())
+                modified.push(f.path);
+        }
+        catch {
+            modified.push(f.path);
+        }
+    }
+    return modified;
+}

package/dist/ref.d.ts

@@ -0,0 +1,11 @@
+export type SkillRef = {
+    handle: string;
+    slug: string;
+};
+/**
+ * Accepts `handle/slug`, `@handle/slug`, and pasted promptdock.ai skill URLs;
+ * case-folds both halves (handles are citext). Null when the string can't be a
+ * ref (callers render the not-found help).
+ */
+export declare function parseSkillRef(input: string): SkillRef | null;
+export declare function formatRef(ref: SkillRef): string;

package/dist/ref.js

@@ -0,0 +1,32 @@
+// Port of lib/validation/skills.ts parseSkillRef (DX2 forgiveness). The regex
+// halves come from the GENERATED constants, and test/paths-parity.test.ts pins
+// this port against the app's test vectors — keep the logic line-for-line.
+import { SKILL_HANDLE_RE_SOURCE, SKILL_SLUG_RE_SOURCE } from "./generated/constants.js";
+const SLUG_RE = new RegExp(SKILL_SLUG_RE_SOURCE);
+const HANDLE_RE = new RegExp(SKILL_HANDLE_RE_SOURCE);
+/**
+ * Accepts `handle/slug`, `@handle/slug`, and pasted promptdock.ai skill URLs;
+ * case-folds both halves (handles are citext). Null when the string can't be a
+ * ref (callers render the not-found help).
+ */
+export function parseSkillRef(input) {
+    let s = input.trim();
+    const url = s.match(/^(?:https?:\/\/)?(?:www\.)?promptdock\.ai\/(?:dashboard\/)?skill\/([^/\s?#]+)\/([^/\s?#]+)/i);
+    if (url)
+        s = `${url[1]}/${url[2]}`;
+    if (s.startsWith("@"))
+        s = s.slice(1);
+    const parts = s.split("/");
+    if (parts.length !== 2)
+        return null;
+    const handle = parts[0].toLowerCase();
+    const slug = parts[1].toLowerCase();
+    if (!HANDLE_RE.test(handle))
+        return null;
+    if (!SLUG_RE.test(slug))
+        return null;
+    return { handle, slug };
+}
+export function formatRef(ref) {
+    return `${ref.handle}/${ref.slug}`;
+}

package/dist/registry.d.ts

@@ -0,0 +1,43 @@
+export type TargetDef = {
+    id: string;
+    label: string;
+    /** project-local skills base dir (relative to cwd); install dir = base/<slug> */
+    localBase: string;
+    /** global skills base dir (relative to home) */
+    globalBase: string;
+    /** dir whose presence means "this tool is set up here" (relative to cwd) */
+    detectLocal: string;
+    /** dir whose presence means "this tool is set up for this user" (relative to home) */
+    detectGlobal: string;
+    experimental: boolean;
+};
+export declare const TARGETS: TargetDef[];
+export declare function targetById(id: string): TargetDef | null;
+/** The skills BASE dir for a target in a scope (receipt scans walk base/<slug>). */
+export declare function targetBaseDir(t: TargetDef, opts: {
+    cwd: string;
+    home: string;
+    global: boolean;
+}): string;
+/** The install dir for a slug. */
+export declare function targetInstallDir(t: TargetDef, opts: {
+    cwd: string;
+    home: string;
+    global: boolean;
+    slug: string;
+}): string;
+export type DetectedTarget = TargetDef & {
+    detected: boolean;
+};
+/**
+ * D-UX11 ordering: detected tools float to the top (registry order preserved
+ * within each group); the preselect is index 0 (first detected, else Claude).
+ */
+export declare function detectTargets(opts: {
+    cwd: string;
+    home: string;
+    global: boolean;
+    exists?: (p: string) => boolean;
+}): DetectedTarget[];
+/** DX1/DX F2/F16 — the per-target next step, incl. the RELOAD caveat. */
+export declare function nextStepLine(targetId: string, slug: string): string;

package/dist/registry.js

@@ -0,0 +1,111 @@
+// U3/D-UX11 target registry — DATA, not a plugin system. Paths are each tool's
+// convention; every tool except Claude Code ships "(experimental)" (DX5 — the
+// convention is best-effort until verified against that tool's docs). Detection
+// floats detected tools to the top and preselects the first (D-UX11).
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+export const TARGETS = [
+    {
+        id: "claude",
+        label: "Claude Code",
+        localBase: ".claude/skills",
+        globalBase: ".claude/skills",
+        detectLocal: ".claude",
+        detectGlobal: ".claude",
+        experimental: false,
+    },
+    {
+        id: "codex",
+        label: "Codex",
+        localBase: ".codex/skills",
+        globalBase: ".codex/skills",
+        detectLocal: ".codex",
+        detectGlobal: ".codex",
+        experimental: true,
+    },
+    {
+        id: "gemini",
+        label: "Gemini CLI",
+        localBase: ".gemini/skills",
+        globalBase: ".gemini/skills",
+        detectLocal: ".gemini",
+        detectGlobal: ".gemini",
+        experimental: true,
+    },
+    {
+        id: "cursor",
+        label: "Cursor",
+        localBase: ".cursor/skills",
+        globalBase: ".cursor/skills",
+        detectLocal: ".cursor",
+        detectGlobal: ".cursor",
+        experimental: true,
+    },
+    {
+        id: "copilot",
+        label: "GitHub Copilot",
+        localBase: ".github/skills",
+        globalBase: ".copilot/skills",
+        detectLocal: ".github",
+        detectGlobal: ".copilot",
+        experimental: true,
+    },
+    {
+        id: "kimi",
+        label: "Kimi",
+        localBase: ".kimi/skills",
+        globalBase: ".kimi/skills",
+        detectLocal: ".kimi",
+        detectGlobal: ".kimi",
+        experimental: true,
+    },
+    {
+        id: "openai",
+        label: "OpenAI/GPT",
+        localBase: ".openai/skills",
+        globalBase: ".openai/skills",
+        detectLocal: ".openai",
+        detectGlobal: ".openai",
+        experimental: true,
+    },
+];
+export function targetById(id) {
+    return TARGETS.find((t) => t.id === id) ?? null;
+}
+/** The skills BASE dir for a target in a scope (receipt scans walk base/<slug>). */
+export function targetBaseDir(t, opts) {
+    return opts.global ? join(opts.home, t.globalBase) : join(opts.cwd, t.localBase);
+}
+/** The install dir for a slug. */
+export function targetInstallDir(t, opts) {
+    return join(targetBaseDir(t, opts), opts.slug);
+}
+/**
+ * D-UX11 ordering: detected tools float to the top (registry order preserved
+ * within each group); the preselect is index 0 (first detected, else Claude).
+ */
+export function detectTargets(opts) {
+    const exists = opts.exists ?? existsSync;
+    const all = TARGETS.map((t) => ({
+        ...t,
+        detected: exists(opts.global ? join(opts.home, t.detectGlobal) : join(opts.cwd, t.detectLocal)),
+    }));
+    return [...all.filter((t) => t.detected), ...all.filter((t) => !t.detected)];
+}
+/** DX1/DX F2/F16 — the per-target next step, incl. the RELOAD caveat. */
+export function nextStepLine(targetId, slug) {
+    switch (targetId) {
+        case "claude":
+            return `Next: start a NEW session in Claude Code (open sessions don't see new skills) and type /${slug}`;
+        case "codex":
+            return `Next: restart Codex so it picks up the new skill, then invoke ${slug}.`;
+        case "gemini":
+            return `Next: restart Gemini CLI so it picks up the new skill.`;
+        case "cursor":
+            return `Next: reload Cursor so it picks up the new skill.`;
+        case "copilot":
+            return `Next: reload your editor so Copilot picks up the new skill.`;
+        default:
+            return `Next: restart your agent tool so it picks up the new skill.`;
+    }
+}