@prompts-gpt/client 0.2.0 → 0.2.2

package/dist/index.js

@@ -1,4 +1,4 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 export const DEFAULT_PROMPTS_GPT_API_URL = "https://prompts-gpt.com";
@@ -10,17 +10,24 @@ export class PromptsGptApiError extends Error {
     status;
     code;
     recovery;
+    requestId;
+    fieldErrors;
+    retryAfterMs;
     constructor(message, options) {
         super(message);
         this.name = "PromptsGptApiError";
         this.status = options?.status ?? 0;
         this.code = options?.code ?? "UNKNOWN_ERROR";
         this.recovery = options?.recovery ?? "Retry the request or create a fresh project token.";
+        this.requestId = options?.requestId ?? null;
+        this.fieldErrors = options?.fieldErrors;
+        this.retryAfterMs = options?.retryAfterMs ?? null;
     }
 }
 const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_GENERATE_TIMEOUT_MS = 60_000;
 const MAX_RETRIES = 2;
-const RETRYABLE_STATUS_CODES = new Set([429, 502, 503, 504]);
+const RETRYABLE_STATUS_CODES = new Set([408, 429, 502, 503, 504]);
 export class PromptsGptClient {
     apiUrl;
     token;
@@ -28,27 +35,27 @@ export class PromptsGptClient {
     timeoutMs;
     constructor(options) {
         this.apiUrl = safeNormalizeApiUrl(options.apiUrl);
-        this.token = options.token;
+        this.token = options.token?.trim() || null;
         this.fetchImpl = options.fetch;
         this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     }
-    async getProject() {
-        const data = await this.request("/api/sdk/v1/project");
+    async getProject(options = {}) {
+        const data = await this.request("/api/sdk/v1/project", options);
         return data.project;
     }
-    async pullPrompts(query = {}) {
-        const params = new URLSearchParams();
-        for (const [key, value] of Object.entries(query)) {
-            if (value === undefined || value === null || value === "")
-                continue;
-            params.set(key === "query" ? "q" : key, String(value));
-        }
-        const qs = params.toString();
+    async pullPrompts(query = {}, options = {}) {
+        const qs = serializePromptQuery(query);
         const suffix = qs ? `?${qs}` : "";
-        const data = await this.request(`/api/sdk/v1/prompts${suffix}`);
+        const data = await this.request(`/api/sdk/v1/prompts${suffix}`, options);
+        if (!Array.isArray(data.prompts)) {
+            throw new PromptsGptApiError("Prompts-GPT returned an invalid prompts payload.", {
+                code: "INVALID_RESPONSE",
+                recovery: "Retry the request. If it keeps failing, verify the SDK API version.",
+            });
+        }
         return data.prompts;
     }
-    async generatePrompt(input) {
+    async generatePrompt(input, options = {}) {
         const trimmedGoal = input.goal?.trim() ?? "";
         if (trimmedGoal.length < 8) {
             throw new PromptsGptApiError("Goal must be at least 8 characters.", { code: "VALIDATION_ERROR" });
@@ -60,9 +67,19 @@ export class PromptsGptClient {
         if (trimmedContext.length > 1600) {
             throw new PromptsGptApiError("Context must be 1600 characters or fewer.", { code: "VALIDATION_ERROR" });
         }
+        const trimmedConstraints = input.constraints?.trim() ?? "";
+        if (trimmedConstraints.length > 1600) {
+            throw new PromptsGptApiError("Constraints must be 1600 characters or fewer.", { code: "VALIDATION_ERROR" });
+        }
+        const trimmedDesiredOutput = input.desiredOutput?.trim() ?? "";
+        if (trimmedDesiredOutput.length > 1600) {
+            throw new PromptsGptApiError("Desired output must be 1600 characters or fewer.", { code: "VALIDATION_ERROR" });
+        }
         const data = await this.request("/api/sdk/v1/prompts/generate", {
             method: "POST",
             body: input,
+            timeoutMs: options.timeoutMs ?? DEFAULT_GENERATE_TIMEOUT_MS,
+            ...options,
         });
         return data.prompt;
     }
@@ -71,7 +88,7 @@ export class PromptsGptClient {
             throw new PromptsGptApiError("Project token is missing.", {
                 status: 401,
                 code: "AUTH_ERROR",
-                recovery: "Run `prompts-gpt init --token <token>` or set PROMPTS_GPT_TOKEN.",
+                recovery: "Run `prompts-gpt init --token <token>` or pass `--token`, `--token-stdin`, or `--token-prompt` to the CLI command.",
             });
         }
         if (!this.token.startsWith("pgpt_")) {
@@ -87,58 +104,98 @@ export class PromptsGptClient {
             });
         }
         const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        const releaseLinkedAbort = linkAbortSignal(options.signal, controller);
+        const timeoutMs = normalizeTimeoutMs(options.timeoutMs ?? this.timeoutMs);
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        timeout.unref?.();
+        const method = options.method ?? "GET";
         try {
+            if (options.signal?.aborted) {
+                throw new PromptsGptApiError(`Request to ${pathname} was aborted by the caller.`, {
+                    code: "REQUEST_ABORTED",
+                    recovery: "Start a new request when you are ready to continue.",
+                });
+            }
             const url = new URL(pathname, this.apiUrl);
+            const headers = {
+                authorization: `Bearer ${this.token}`,
+                accept: "application/json",
+                "x-prompts-gpt-client": `@prompts-gpt/client/${getClientVersion()}`,
+            };
+            if (!options.omitUserAgent) {
+                headers["user-agent"] = `prompts-gpt-client/${getClientVersion()}`;
+            }
+            const outgoingRequestId = options.requestId?.trim() || generateRequestId();
+            headers["x-request-id"] = outgoingRequestId;
+            if (options.body) {
+                headers["content-type"] = "application/json";
+            }
             const response = await fetchFn(url, {
-                method: options.method ?? "GET",
-                headers: {
-                    authorization: `Bearer ${this.token}`,
-                    accept: "application/json",
-                    "user-agent": `prompts-gpt-client/${getClientVersion()}`,
-                    ...(options.body ? { "content-type": "application/json" } : {}),
-                },
+                method,
+                headers,
                 body: options.body ? JSON.stringify(options.body) : undefined,
                 signal: controller.signal,
             });
+            const requestId = response.headers?.get?.("x-request-id") ?? outgoingRequestId;
+            const retryAfterMs = parseRetryAfterHeader(response.headers?.get?.("retry-after"));
             const contentType = response.headers?.get?.("content-type") ?? "";
-            if (!contentType.includes("application/json") && response.status !== 204) {
+            if (!isJsonContentType(contentType) && response.status !== 204) {
                 throw new PromptsGptApiError(`Unexpected response content-type: ${contentType || "none"}`, {
                     status: response.status,
                     code: "INVALID_RESPONSE",
                     recovery: "Verify the API URL is correct and the server is accessible.",
+                    requestId,
+                    retryAfterMs,
                 });
             }
-            const payload = await response.json().catch(() => null);
-            if (!response.ok || !payload?.ok) {
-                if (retryCount < MAX_RETRIES && RETRYABLE_STATUS_CODES.has(response.status)) {
-                    const retryAfter = parseInt(response.headers?.get?.("retry-after") ?? "", 10);
-                    const baseDelay = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : (retryCount + 1) * 1000;
-                    const jitter = Math.random() * 500;
-                    await sleep(Math.min(baseDelay + jitter, 30_000));
+            const payload = await parseJsonResponse(response);
+            const apiResponse = parseApiResponse(payload);
+            if (!response.ok || !apiResponse || !apiResponse.ok) {
+                if (!apiResponse) {
+                    throw new PromptsGptApiError("Prompts-GPT returned an unexpected API envelope.", {
+                        status: response.status,
+                        code: "INVALID_RESPONSE",
+                        recovery: "Retry the request. If it keeps failing, verify the SDK API version.",
+                        requestId,
+                        retryAfterMs,
+                    });
+                }
+                if (shouldRetryRequest({ method, status: response.status, retryCount, retryAfterMs })) {
+                    await sleep(computeRetryDelayMs(retryCount, retryAfterMs));
                     return this.request(pathname, options, retryCount + 1);
                 }
-                const error = payload?.error;
+                const error = !apiResponse.ok ? apiResponse.error : null;
                 throw new PromptsGptApiError(error?.message ?? `Prompts-GPT request failed with ${response.status}.`, {
                     status: response.status,
                     code: error?.code,
                     recovery: error?.recovery,
+                    requestId,
+                    retryAfterMs,
+                    fieldErrors: error?.fieldErrors,
                 });
             }
-            return payload.data;
+            return apiResponse.data;
         }
         catch (error) {
             if (error instanceof PromptsGptApiError)
                 throw error;
+            if (!options.omitUserAgent && isUserAgentRuntimeError(error)) {
+                return this.request(pathname, { ...options, omitUserAgent: true }, retryCount);
+            }
             if (error?.name === "AbortError") {
-                throw new PromptsGptApiError(`Request to ${pathname} timed out after ${this.timeoutMs}ms.`, {
+                if (options.signal?.aborted) {
+                    throw new PromptsGptApiError(`Request to ${pathname} was aborted by the caller.`, {
+                        code: "REQUEST_ABORTED",
+                        recovery: "Start a new request when you are ready to continue.",
+                    });
+                }
+                throw new PromptsGptApiError(`Request to ${pathname} timed out after ${timeoutMs}ms.`, {
                     code: "TIMEOUT",
                     recovery: "Check your network connection or increase the timeout.",
                 });
             }
-            if (retryCount < MAX_RETRIES && isNetworkError(error)) {
-                const jitter = Math.random() * 500;
-                await sleep(Math.min((retryCount + 1) * 1000 + jitter, 30_000));
+            if (retryCount < MAX_RETRIES && method === "GET" && isNetworkError(error)) {
+                await sleep(computeRetryDelayMs(retryCount));
                 return this.request(pathname, options, retryCount + 1);
             }
             throw new PromptsGptApiError(error?.message ?? "Network request failed.", {
@@ -147,6 +204,7 @@ export class PromptsGptClient {
             });
         }
         finally {
+            releaseLinkedAbort();
             clearTimeout(timeout);
         }
     }
@@ -154,12 +212,140 @@ export class PromptsGptClient {
 function isNetworkError(error) {
     if (!error)
         return false;
+    const name = String(error.name ?? "").toLowerCase();
     const message = String(error.message ?? "").toLowerCase();
-    return message.includes("fetch") || message.includes("network") || message.includes("econnrefused") || message.includes("enotfound");
+    return (name === "typeerror" ||
+        message.includes("fetch") ||
+        message.includes("network") ||
+        message.includes("econnrefused") ||
+        message.includes("enotfound") ||
+        message.includes("eai_again") ||
+        message.includes("ecancelled") ||
+        message.includes("socket"));
+}
+function isUserAgentRuntimeError(error) {
+    const message = String(error?.message ?? "").toLowerCase();
+    return message.includes("user-agent") && message.includes("not allowed");
+}
+function linkAbortSignal(signal, controller) {
+    if (!signal)
+        return () => undefined;
+    if (signal.aborted) {
+        controller.abort(signal.reason);
+        return () => undefined;
+    }
+    const abort = () => controller.abort(signal.reason);
+    signal.addEventListener("abort", abort, { once: true });
+    return () => signal.removeEventListener("abort", abort);
+}
+function normalizeTimeoutMs(value) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new PromptsGptApiError("Timeout must be a positive number of milliseconds.", {
+            code: "VALIDATION_ERROR",
+            recovery: "Provide a timeout greater than 0.",
+        });
+    }
+    return Math.min(Math.trunc(value), 300_000);
+}
+function serializePromptQuery(query) {
+    const params = new URLSearchParams();
+    const promptQuery = typeof query.query === "string" && query.query.trim() ? query.query : query.q;
+    if (typeof promptQuery === "string" && promptQuery.trim()) {
+        params.set("q", promptQuery.trim());
+    }
+    for (const [key, value] of Object.entries({
+        category: query.category,
+        tool: query.tool,
+        outputType: query.outputType,
+    })) {
+        if (typeof value === "string" && value.trim()) {
+            params.set(key, value.trim());
+        }
+    }
+    if (query.limit !== undefined && query.limit !== null && query.limit !== "") {
+        const limit = typeof query.limit === "string" ? Number(query.limit) : query.limit;
+        if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+            throw new PromptsGptApiError("Prompt limit must be an integer between 1 and 100.", {
+                code: "VALIDATION_ERROR",
+                recovery: "Choose a limit between 1 and 100.",
+            });
+        }
+        params.set("limit", String(limit));
+    }
+    return params.toString();
+}
+function isJsonContentType(contentType) {
+    const normalized = contentType.toLowerCase();
+    return normalized.includes("application/json") || normalized.includes("+json");
+}
+async function parseJsonResponse(response) {
+    if (response.status === 204)
+        return { ok: true, data: {} };
+    const rawBody = await response.text();
+    if (!rawBody.trim())
+        return null;
+    try {
+        return JSON.parse(rawBody);
+    }
+    catch {
+        throw new PromptsGptApiError("Prompts-GPT returned malformed JSON.", {
+            status: response.status,
+            code: "INVALID_RESPONSE",
+            recovery: "Retry the request. If it keeps failing, verify the API URL and server health.",
+            requestId: response.headers?.get?.("x-request-id") ?? null,
+        });
+    }
+}
+function parseApiResponse(payload) {
+    if (!payload || typeof payload !== "object" || !("ok" in payload))
+        return null;
+    if (payload.ok === true && "data" in payload) {
+        return payload;
+    }
+    if (payload.ok === false && "error" in payload) {
+        return payload;
+    }
+    return null;
+}
+function shouldRetryRequest({ method, status, retryCount, retryAfterMs, }) {
+    if (retryCount >= MAX_RETRIES)
+        return false;
+    if (method !== "GET")
+        return false;
+    if (!RETRYABLE_STATUS_CODES.has(status))
+        return false;
+    if (retryAfterMs !== null && retryAfterMs > 300_000)
+        return false;
+    return true;
+}
+function computeRetryDelayMs(retryCount, retryAfterMs = null) {
+    const baseDelay = retryAfterMs && retryAfterMs > 0 ? retryAfterMs : (retryCount + 1) * 1_000;
+    const jitter = Math.random() * 500;
+    return Math.min(baseDelay + jitter, 30_000);
+}
+function parseRetryAfterHeader(value) {
+    if (!value)
+        return null;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    const seconds = Number(trimmed);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        const ms = seconds * 1_000;
+        return Math.min(ms, 600_000);
+    }
+    const retryAt = Date.parse(trimmed);
+    if (Number.isNaN(retryAt))
+        return null;
+    return Math.min(Math.max(retryAt - Date.now(), 0), 600_000);
 }
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function generateRequestId() {
+    const hex = Array.from({ length: 8 }, () => Math.floor(Math.random() * 256).toString(16).padStart(2, "0")).join("");
+    return `pgcli_${hex}`;
+}
 let cachedVersion = null;
 function getClientVersion() {
     if (cachedVersion)
@@ -174,16 +360,21 @@ function getClientVersion() {
     return cachedVersion;
 }
 export async function saveLocalCredentials(input) {
-    if (!input.token?.trim())
+    const trimmedToken = input.token?.trim();
+    if (!trimmedToken)
         throw new Error("Token is required.");
-    if (input.token.trim().length > 256)
+    if (trimmedToken.length > 256)
         throw new Error("Token value is too long.");
+    if (!trimmedToken.startsWith("pgpt_"))
+        throw new Error("Token must start with the 'pgpt_' prefix.");
     const cwd = input.cwd ?? process.cwd();
     const outDir = path.resolve(cwd, DEFAULT_PROMPTS_GPT_OUT_DIR);
     await mkdir(outDir, { recursive: true });
-    await writeFile(path.join(outDir, PROMPTS_GPT_CREDENTIALS_FILE), `${JSON.stringify({ token: input.token.trim(), apiUrl: normalizeApiUrl(input.apiUrl ?? DEFAULT_PROMPTS_GPT_API_URL) }, null, 2)}\n`, { mode: 0o600 });
+    await writeFile(path.join(outDir, PROMPTS_GPT_CREDENTIALS_FILE), `${JSON.stringify({ token: trimmedToken, apiUrl: normalizeApiUrl(input.apiUrl ?? DEFAULT_PROMPTS_GPT_API_URL) }, null, 2)}\n`, { mode: 0o600 });
+    const credentialsPath = path.join(outDir, PROMPTS_GPT_CREDENTIALS_FILE);
+    await chmod(credentialsPath, 0o600).catch(() => undefined);
     await ensureGitignoreEntry(cwd, `${DEFAULT_PROMPTS_GPT_OUT_DIR}/${PROMPTS_GPT_CREDENTIALS_FILE}`);
-    return { credentialsPath: path.join(outDir, PROMPTS_GPT_CREDENTIALS_FILE) };
+    return { credentialsPath };
 }
 export async function loadLocalCredentials(cwd = process.cwd()) {
     const credentialsPath = path.resolve(cwd, DEFAULT_PROMPTS_GPT_OUT_DIR, PROMPTS_GPT_CREDENTIALS_FILE);
@@ -199,8 +390,9 @@ export async function loadLocalCredentials(cwd = process.cwd()) {
             }
             catch { }
         }
+        const rawToken = typeof parsed.token === "string" ? parsed.token.trim() : null;
         return {
-            token: typeof parsed.token === "string" ? parsed.token : null,
+            token: rawToken || null,
             apiUrl,
         };
     }
@@ -210,7 +402,12 @@ export async function loadLocalCredentials(cwd = process.cwd()) {
 }
 export async function syncPrompts(prompts, options = {}) {
     const markdown = await writePromptMarkdownFiles(prompts, options);
-    const agents = await writeAgentFiles(prompts, options);
+    const agents = await writeAgentFiles(prompts, {
+        cwd: options.cwd,
+        agent: options.agent,
+        agents: options.agents,
+        overwriteAgentFiles: options.overwrite,
+    });
     const manifest = await writePromptManifest(prompts, { cwd: options.cwd, outDir: options.outDir });
     return { markdown, agents, manifest };
 }
@@ -218,18 +415,31 @@ export async function writePromptMarkdownFiles(prompts, options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const outDir = assertSafeOutputDir(cwd, options.outDir ?? DEFAULT_PROMPTS_GPT_OUT_DIR);
     const overwrite = Boolean(options.overwrite);
+    const normalizedPrompts = assertUniquePromptFileStems(prompts);
     await mkdir(outDir, { recursive: true });
     const written = [];
     const skipped = [];
-    for (const prompt of prompts) {
-        const filePath = path.join(outDir, `${safeSlug(prompt.slug || prompt.title)}.md`);
+    for (const { prompt, stem } of normalizedPrompts) {
+        const filePath = path.join(outDir, `${stem}.md`);
         assertInside(filePath, outDir);
-        if (!overwrite && existsSync(filePath)) {
-            skipped.push(filePath);
-            continue;
+        if (overwrite) {
+            await writeFile(filePath, formatPromptMarkdown(prompt));
+            written.push(filePath);
+        }
+        else {
+            try {
+                await writeFile(filePath, formatPromptMarkdown(prompt), { flag: "wx" });
+                written.push(filePath);
+            }
+            catch (err) {
+                if (err.code === "EEXIST") {
+                    skipped.push(filePath);
+                }
+                else {
+                    throw err;
+                }
+            }
         }
-        await writeFile(filePath, formatPromptMarkdown(prompt), { flag: overwrite ? "w" : "wx" });
-        written.push(filePath);
     }
     await writePromptIndex(prompts, { outDir });
     return { outDir, written, skipped };
@@ -237,45 +447,72 @@ export async function writePromptMarkdownFiles(prompts, options = {}) {
 export async function writeAgentFiles(prompts, options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const targets = normalizeAgentTargets(options.agent ?? options.agents ?? "all");
-    const overwrite = Boolean(options.overwriteAgentFiles ?? true);
+    const overwrite = Boolean(options.overwriteAgentFiles);
     const written = [];
     const skipped = [];
-    const allFiles = targets.flatMap((target) => buildAgentFiles(target, prompts).map((file) => ({ ...file, target })));
+    const normalizedPrompts = assertUniquePromptFileStems(prompts);
+    const allFiles = targets.flatMap((target) => buildAgentFiles(target, normalizedPrompts.filter(({ prompt }) => promptSupportsAgentTarget(prompt, target))).map((file) => ({ ...file, target })));
+    assertUniqueAgentFilePaths(allFiles);
     const dirSet = new Set(allFiles.map((file) => path.dirname(assertSafeProjectFile(cwd, file.path))));
     await Promise.all([...dirSet].map((dir) => mkdir(dir, { recursive: true })));
-    await Promise.all(allFiles.map(async (file) => {
+    for (const file of allFiles) {
         const filePath = assertSafeProjectFile(cwd, file.path);
         if (file.managedBlock) {
-            const existing = existsSync(filePath) ? await readFile(filePath, "utf8") : "";
+            let existing = "";
+            try {
+                existing = await readFile(filePath, "utf8");
+            }
+            catch { }
             await writeFile(filePath, upsertManagedBlock(existing, file.content));
             written.push(filePath);
-            return;
+            continue;
+        }
+        if (overwrite) {
+            await writeFile(filePath, file.content);
+            written.push(filePath);
         }
-        if (!overwrite && existsSync(filePath)) {
-            skipped.push(filePath);
-            return;
+        else {
+            try {
+                await writeFile(filePath, file.content, { flag: "wx" });
+                written.push(filePath);
+            }
+            catch (err) {
+                if (err.code === "EEXIST") {
+                    skipped.push(filePath);
+                }
+                else {
+                    throw err;
+                }
+            }
         }
-        await writeFile(filePath, file.content, { flag: overwrite ? "w" : "wx" });
-        written.push(filePath);
-    }));
+    }
     return { written, skipped, targets };
 }
 export async function writePromptManifest(prompts, options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const outDir = assertSafeOutputDir(cwd, options.outDir ?? DEFAULT_PROMPTS_GPT_OUT_DIR);
+    const normalizedPrompts = assertUniquePromptFileStems(prompts);
     await mkdir(outDir, { recursive: true });
     const manifestPath = path.join(outDir, PROMPTS_GPT_MANIFEST_FILE);
     const payload = {
         version: 1,
         generatedAt: new Date().toISOString(),
-        count: prompts.length,
-        prompts: prompts.map((prompt) => ({
-            slug: safeSlug(prompt.slug || prompt.title),
+        count: normalizedPrompts.length,
+        prompts: normalizedPrompts.map(({ prompt, stem }) => ({
+            slug: stem,
             title: prompt.title,
+            summary: prompt.summary ?? "",
             source: prompt.source ?? "library",
             category: prompt.category ?? "Prompt Library",
+            difficulty: prompt.difficulty ?? "Intermediate",
+            outputType: prompt.outputType ?? "Text",
             supportedTools: prompt.supportedTools ?? [],
-            file: `${safeSlug(prompt.slug || prompt.title)}.md`,
+            agentTargets: normalizePromptAgentTargets(prompt),
+            variables: prompt.variables ?? [],
+            tags: prompt.tags ?? [],
+            recommendedPath: prompt.recommendedPath ?? null,
+            file: `${stem}.md`,
+            files: buildDiscoverablePromptFiles(stem, prompt),
         })),
     };
     await writeFile(manifestPath, `${JSON.stringify(payload, null, 2)}\n`);
@@ -302,11 +539,8 @@ export function formatPromptMarkdown(prompt) {
         "",
         prompt.promptText ?? "",
         "",
-        prompt.variables?.length ? "## Variables" : "",
-        ...(prompt.variables?.length ? prompt.variables.map((variable) => `- \`${variable}\``) : []),
-        prompt.variables?.length ? "" : "",
-        prompt.usageNotes ? "## Usage Notes" : "",
-        prompt.usageNotes ?? "",
+        ...(prompt.variables?.length ? ["## Variables", "", ...prompt.variables.map((variable) => `- \`${variable}\``), ""] : []),
+        ...(prompt.usageNotes ? ["## Usage Notes", "", prompt.usageNotes] : []),
         "",
     ].reduce((acc, line, index, list) => {
         if (line === "" && index > 0 && list[index - 1] === "" && (index < 2 || list[index - 2] === ""))
@@ -323,10 +557,10 @@ function buildAgentFiles(target, prompts) {
                 content: [
                     "# Prompts-GPT Agent Instructions",
                     "",
-                    "Prompts synced by `prompts-gpt sync` live in `.prompts-gpt/`. Use the manifest and prompt files before starting related work.",
+                    "Prompts synced by `prompts-gpt sync` live in `.prompts-gpt/`. Start with [.prompts-gpt/manifest.json](.prompts-gpt/manifest.json), then open the prompt packs linked below before starting related work.",
                     "",
                     "## Available Prompt Packs",
-                    ...prompts.map((prompt) => `- ${prompt.title}: .prompts-gpt/${safeSlug(prompt.slug || prompt.title)}.md`),
+                    ...prompts.map(({ prompt, stem }) => `- [${prompt.title}](.prompts-gpt/${stem}.md)`),
                     "",
                     "When a prompt pack is relevant, load it, adapt variables to the current task, and keep verification tied to the prompt's acceptance criteria.",
                     "",
@@ -334,12 +568,12 @@ function buildAgentFiles(target, prompts) {
             }];
     }
     if (target === "cursor") {
-        return prompts.map((prompt) => ({
-            path: `.cursor/rules/prompts-gpt-${safeSlug(prompt.slug || prompt.title)}.mdc`,
+        return prompts.map(({ prompt, stem }) => ({
+            path: `.cursor/rules/prompts-gpt-${stem}.mdc`,
             content: [
                 "---",
-                `description: ${prompt.summary || prompt.title}`,
-                "globs:",
+                `description: ${yamlScalar(prompt.summary || prompt.title)}`,
+                "globs: []",
                 "alwaysApply: false",
                 "---",
                 "",
@@ -360,9 +594,26 @@ function buildAgentFiles(target, prompts) {
                 content: [
                     "# Prompts-GPT Copilot Instructions",
                     "",
-                    "Use `.prompts-gpt/manifest.json` and `.prompts-gpt/*.md` as reusable prompt packs for this repository.",
+                    "Use [../.prompts-gpt/manifest.json](../.prompts-gpt/manifest.json) and the linked `.prompts-gpt/*.md` prompt packs as reusable repository context.",
+                    "",
+                    ...prompts.map(({ prompt, stem }) => `- [${prompt.title}](../.prompts-gpt/${stem}.md)`),
+                    "",
+                ].join("\n"),
+            },
+            {
+                path: ".github/instructions/prompts-gpt.instructions.md",
+                content: [
+                    "---",
+                    'applyTo: "AGENTS.md,.prompts-gpt/**/*.md,.github/copilot-instructions.md,.github/prompts/**/*.prompt.md,.cursor/rules/**/*.mdc,.vscode/prompts-gpt.code-snippets"',
+                    "---",
+                    "",
+                    "# Prompts-GPT managed artifacts",
+                    "",
+                    "These files are generated or refreshed by `prompts-gpt sync` and `prompts-gpt install-agents`.",
                     "",
-                    ...prompts.map((prompt) => `- ${prompt.title}: .prompts-gpt/${safeSlug(prompt.slug || prompt.title)}.md`),
+                    "- Treat `.prompts-gpt/manifest.json` as the source of truth for discoverable prompt packs and generated agent files.",
+                    "- Prefer updating the upstream prompt pack or rerunning sync instead of manually editing generated agent artifacts.",
+                    "- Preserve the managed `prompts-gpt` blocks inside `AGENTS.md` and `.github/copilot-instructions.md`.",
                     "",
                 ].join("\n"),
             },
@@ -373,27 +624,123 @@ function buildAgentFiles(target, prompts) {
         ];
     }
     if (target === "copilot") {
-        return prompts.map((prompt) => ({
-            path: `.github/prompts/prompts-gpt-${safeSlug(prompt.slug || prompt.title)}.prompt.md`,
-            content: formatPromptMarkdown(prompt),
+        return prompts.map(({ prompt, stem }) => ({
+            path: `.github/prompts/prompts-gpt-${stem}.prompt.md`,
+            content: formatCopilotPromptMarkdown(prompt, stem),
         }));
     }
     return [];
 }
 function buildVsCodeSnippets(prompts) {
-    return prompts.reduce((snippets, prompt) => {
+    return prompts.reduce((snippets, { prompt, stem }) => {
         snippets[`Prompts-GPT: ${prompt.title}`] = {
-            prefix: `pgpt-${safeSlug(prompt.slug || prompt.title)}`,
+            prefix: `pgpt-${stem}`,
             description: prompt.summary || prompt.title,
             body: String(prompt.promptText || "").split(/\r?\n/),
         };
         return snippets;
     }, {});
 }
+function normalizePromptAgentTargets(prompt) {
+    const validSet = new Set(SUPPORTED_AGENT_TARGETS);
+    const declaredTargets = Array.isArray(prompt.agentTargets)
+        ? prompt.agentTargets.map((target) => String(target).trim().toLowerCase()).filter(Boolean)
+        : [];
+    return [...new Set(declaredTargets.filter((target) => validSet.has(target)))];
+}
+function promptSupportsAgentTarget(prompt, target) {
+    const declaredTargets = normalizePromptAgentTargets(prompt);
+    return declaredTargets.length === 0 || declaredTargets.includes(target);
+}
+function assertUniquePromptFileStems(prompts) {
+    const byStem = new Map();
+    const normalizedPrompts = prompts.map((prompt) => {
+        const stem = safeSlug(prompt.slug || prompt.title);
+        const matches = byStem.get(stem) ?? [];
+        matches.push(prompt);
+        byStem.set(stem, matches);
+        return { prompt, stem };
+    });
+    const collisions = [...byStem.entries()].filter(([, items]) => items.length > 1);
+    if (collisions.length > 0) {
+        const details = collisions
+            .map(([stem, items]) => `${stem} <- ${items.map((item) => item.title || item.slug || "Untitled prompt").join(", ")}`)
+            .join("; ");
+        throw new Error(`Refusing to sync prompts with colliding file names after slug normalization: ${details}`);
+    }
+    return normalizedPrompts;
+}
+function assertUniqueAgentFilePaths(files) {
+    const pathCounts = new Map();
+    for (const file of files) {
+        const targets = pathCounts.get(file.path) ?? [];
+        targets.push(file.target);
+        pathCounts.set(file.path, targets);
+    }
+    const collisions = [...pathCounts.entries()].filter(([, targets]) => targets.length > 1 && !targets.every((target) => target === targets[0]));
+    if (collisions.length > 0) {
+        const details = collisions.map(([filePath, targets]) => `${filePath} <- ${targets.join(", ")}`).join("; ");
+        throw new Error(`Refusing to sync duplicate agent file paths: ${details}`);
+    }
+}
+function buildDiscoverablePromptFiles(stem, prompt) {
+    const agentTargets = new Set(normalizePromptAgentTargets(prompt));
+    const supports = (target) => agentTargets.size === 0 || agentTargets.has(target);
+    return {
+        markdown: `.prompts-gpt/${stem}.md`,
+        codexInstructions: supports("codex") ? "AGENTS.md" : null,
+        cursorRule: supports("cursor") ? `.cursor/rules/prompts-gpt-${stem}.mdc` : null,
+        vscodeInstructions: supports("vscode") ? ".github/copilot-instructions.md" : null,
+        copilotPathInstructions: supports("vscode") ? ".github/instructions/prompts-gpt.instructions.md" : null,
+        vscodeSnippets: supports("vscode") ? ".vscode/prompts-gpt.code-snippets" : null,
+        copilotPrompt: supports("copilot") ? `.github/prompts/prompts-gpt-${stem}.prompt.md` : null,
+    };
+}
+function formatCopilotPromptMarkdown(prompt, stem) {
+    const sections = [
+        "---",
+        "mode: agent",
+        `description: ${yamlScalar(prompt.summary || prompt.title)}`,
+        "---",
+        "",
+        `# ${prompt.title}`,
+        "",
+        `Use [../../.prompts-gpt/${stem}.md](../../.prompts-gpt/${stem}.md) as the canonical prompt-pack reference and verify generated work against [../../.prompts-gpt/manifest.json](../../.prompts-gpt/manifest.json).`,
+        "",
+        prompt.summary ?? "",
+        "",
+        "## Task",
+        "",
+        prompt.promptText ?? "",
+    ];
+    if (prompt.variables?.length) {
+        sections.push("", "## Inputs", "");
+        for (const variable of prompt.variables) {
+            const sanitizedName = safeSlug(variable) || "value";
+            const sanitizedLabel = String(variable).replace(/[{}$]/g, "");
+            sections.push(`- ${sanitizedLabel}: \${input:${sanitizedName}:Provide ${sanitizedLabel}}`);
+        }
+    }
+    if (prompt.usageNotes) {
+        sections.push("", "## Usage Notes", "", prompt.usageNotes);
+    }
+    sections.push("");
+    return sections
+        .reduce((acc, line, index, list) => {
+        if (line === "" && index > 0 && list[index - 1] === "" && (index < 2 || list[index - 2] === ""))
+            return acc;
+        acc.push(line);
+        return acc;
+    }, [])
+        .join("\n");
+}
 function upsertManagedBlock(existing, content) {
     const start = "<!-- prompts-gpt:start -->";
     const end = "<!-- prompts-gpt:end -->";
-    const block = `${start}\n${content.trim()}\n${end}`;
+    const sanitizedContent = content.trim()
+        .replace(/<!-- prompts-gpt:start -->/g, "")
+        .replace(/<!-- prompts-gpt:end -->/g, "");
+    const block = `${start}\n${sanitizedContent}\n${end}`;
     const pattern = new RegExp(`${escapeRegExp(start)}[\\s\\S]*?${escapeRegExp(end)}`);
     if (pattern.test(existing)) {
         return `${existing.replace(pattern, block).trimEnd()}\n`;
@@ -404,6 +751,9 @@ function upsertManagedBlock(existing, content) {
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+function escapeMarkdownLinkText(value) {
+    return value.replace(/[[\]]/g, "\\$&");
+}
 async function writePromptIndex(prompts, { outDir }) {
     const indexPath = path.join(outDir, "README.md");
     const content = [
@@ -412,7 +762,12 @@ async function writePromptIndex(prompts, { outDir }) {
         "These prompts were synced by `prompts-gpt`. Re-run `prompts-gpt sync` to refresh Markdown and agent files.",
         "",
         "## Prompts",
-        ...prompts.map((prompt) => `- [${prompt.title}](./${safeSlug(prompt.slug || prompt.title)}.md) - ${prompt.summary ?? ""}`),
+        ...prompts.map((prompt) => {
+            const agentTargets = normalizePromptAgentTargets(prompt);
+            const suffix = agentTargets.length ? ` Targets: ${agentTargets.join(", ")}.` : "";
+            const escapedTitle = escapeMarkdownLinkText(prompt.title);
+            return `- [${escapedTitle}](./${safeSlug(prompt.slug || prompt.title)}.md) - ${prompt.summary ?? ""}${suffix}`;
+        }),
         "",
     ].join("\n");
     assertInside(indexPath, outDir);
@@ -421,8 +776,11 @@ async function writePromptIndex(prompts, { outDir }) {
 function normalizeAgentTargets(value) {
     const raw = Array.isArray(value) ? value.join(",") : String(value ?? "all");
     const targets = raw.split(",").map((item) => item.trim().toLowerCase()).filter(Boolean);
-    const expanded = targets.includes("all") ? [...SUPPORTED_AGENT_TARGETS] : targets;
-    const unique = [...new Set(expanded)];
+    if (targets.includes("all"))
+        return [...SUPPORTED_AGENT_TARGETS];
+    const unique = [...new Set(targets)];
+    if (unique.length === 0)
+        return [...SUPPORTED_AGENT_TARGETS];
     const validSet = new Set(SUPPORTED_AGENT_TARGETS);
     const invalid = unique.filter((target) => !validSet.has(target));
     if (invalid.length)
@@ -431,6 +789,9 @@ function normalizeAgentTargets(value) {
 }
 function normalizeApiUrl(value) {
     const url = new URL(value);
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new Error(`API URL must use https or http, got ${url.protocol}`);
+    }
     url.pathname = "/";
     url.search = "";
     url.hash = "";
@@ -447,10 +808,14 @@ function safeNormalizeApiUrl(value) {
         });
     }
 }
+function isInsideDirectory(child, parent) {
+    const normalizedParent = parent.endsWith(path.sep) ? parent : `${parent}${path.sep}`;
+    return child.startsWith(normalizedParent) || child === parent;
+}
 function assertSafeOutputDir(cwd, outDir) {
     const root = path.resolve(cwd);
     const resolved = path.resolve(root, outDir);
-    if (!resolved.startsWith(`${root}${path.sep}`)) {
+    if (!isInsideDirectory(resolved, root) || resolved === root) {
         throw new Error("Output directory must be a subdirectory of the current project.");
     }
     return resolved;
@@ -458,33 +823,45 @@ function assertSafeOutputDir(cwd, outDir) {
 function assertSafeProjectFile(cwd, filePath) {
     const root = path.resolve(cwd);
     const resolved = path.resolve(root, filePath);
-    if (!resolved.startsWith(`${root}${path.sep}`)) {
+    if (!isInsideDirectory(resolved, root) || resolved === root) {
         throw new Error("Agent file path must stay inside the current project.");
     }
     return resolved;
 }
 function assertInside(filePath, directory) {
-    if (!filePath.startsWith(`${directory}${path.sep}`)) {
+    if (!isInsideDirectory(filePath, directory) || filePath === directory) {
         throw new Error("Refusing to write outside the prompt output directory.");
     }
 }
 function safeSlug(value) {
-    return String(value ?? "prompt")
+    const raw = String(value ?? "");
+    if (!raw.trim())
+        return "prompt";
+    const slug = raw
         .toLowerCase()
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/g, "")
         .replace(/[^a-z0-9]+/g, "-")
         .replace(/^-+|-+$/g, "")
-        .slice(0, 90) || "prompt";
+        .slice(0, 90);
+    return slug || "prompt";
 }
 function yamlScalar(value) {
-    return JSON.stringify(String(value ?? ""));
+    const s = String(value ?? "");
+    if (s.includes("\n") || s.includes("\r")) {
+        return JSON.stringify(s.replace(/\r\n?/g, "\n"));
+    }
+    return JSON.stringify(s);
 }
 async function ensureGitignoreEntry(cwd, entry) {
     const gitignorePath = path.resolve(cwd, ".gitignore");
     const existing = existsSync(gitignorePath) ? await readFile(gitignorePath, "utf8") : "";
+    const eol = existing.includes("\r\n") ? "\r\n" : "\n";
     const lines = existing.split(/\r?\n/).map((line) => line.trim());
     if (lines.includes(entry))
         return;
-    const prefix = existing && !existing.endsWith("\n") ? "\n" : "";
-    await writeFile(gitignorePath, `${existing}${prefix}${entry}\n`);
+    const needsLeadingNewline = existing.length > 0 && !existing.endsWith("\n") && !existing.endsWith("\r\n");
+    const prefix = needsLeadingNewline ? eol : "";
+    await writeFile(gitignorePath, `${existing}${prefix}${entry}${eol}`);
 }
 //# sourceMappingURL=index.js.map