@prompts-gpt/client 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## Unreleased
+
+### Security
+
+- Validate `constraints` and `desiredOutput` length (max 1600 chars) client-side before network requests
+- Validate token prefix (`pgpt_`) in `saveLocalCredentials` to reject malformed tokens at save time
+- Sanitize Copilot prompt-file variable names to strip `$`, `{`, `}` injection characters
+- Sanitize managed-block content to prevent marker injection via prompt content
+- Validate API URL scheme (must be `https` or `http`) in `normalizeApiUrl`
+- Auto-generate client-side request IDs (`pgcli_*`) when caller doesn't provide one for correlation
+
+### Fixed
+
+- Fix package version mismatch between `package.json` (0.2.1) and CHANGELOG (0.2.2)
+- Fix npm publish failure on unsupported CI providers by removing forced provenance from package metadata
+- Fix race condition in file writes: use atomic `wx` flag with `EEXIST` catch instead of `existsSync` + `wx`
+- Fix `formatPromptMarkdown` producing double blank lines when both `usageNotes` and `variables` are empty
+- Fix `normalizeAgentTargets` deduplication when `all` is mixed with explicit targets (e.g. `all,codex`)
+- Fix `normalizeAgentTargets` returning empty array for empty string input
+- Fix `loadLocalCredentials` returning empty-string token instead of `null` for whitespace-only stored tokens
+- Fix `safeSlug` for unicode-only input by normalizing NFKD and stripping combining marks
+- Fix `ensureGitignoreEntry` to preserve CRLF line endings on Windows-style `.gitignore` files
+- Fix `parseRetryAfterHeader` to cap parsed values at 10 minutes, preventing unbounded waits
+- Fix `assertInside` / `assertSafeOutputDir` boundary comparison for paths at the project root
+- Fix `writePromptIndex` to escape `[` and `]` in Markdown link text to prevent broken rendering
+- Fix `yamlScalar` to handle multi-line strings by normalizing `\r\n` before quoting
+- Serialize agent file writes sequentially to prevent concurrent write races on shared files
+
+### Improvements
+
+- Add `--dry-run` flag to `sync` and `install-agents` commands for previewing changes
+- Add dedicated CLI exit code `4` for rate-limit errors (HTTP 429)
+- Use longer default timeout (60s) for prompt generation requests
+- Add `DEFAULT_GENERATE_TIMEOUT_MS` constant for prompt generation timeout
+
+### Packaging
+
+- Add npm `homepage` and `bugs.email` metadata so package consumers have a first-party support path from the registry page
+- Clarify the project-local CLI install path and pre-publish `npm pack --dry-run` verification flow in the README
+
+## 0.2.2 (2026-05-16)
+
+### Local Sync
+
+- Reject prompt filename collisions after slug normalization before writing local artifacts
+- Respect each prompt pack's declared `agentTargets` when generating Codex, Cursor, VS Code, and Copilot files
+- Skip existing non-managed agent files unless `--overwrite` is explicitly passed
+- Expand `manifest.json` with agent targets, recommended path, and generated file locations for downstream discovery
+- Emit GitHub Copilot prompt files in prompt-file format instead of generic prompt-pack Markdown
+- Add `.github/instructions/prompts-gpt.instructions.md` so Copilot treats synced agent artifacts as generated files
+
+## 0.2.1 (2026-05-16)
+
+### Packaging
+
+- Add an explicit `default` export target for better ESM consumer and bundler compatibility
+- Enable npm provenance on publish for stronger package registry attestation
+- Remove the redundant `typesVersions` entry and rely on the package `types` field plus export metadata
+
+### Documentation
+
+- Replace stale `npx`-only examples with `npm exec` flows that pin to the latest published package
+- Clarify that the importable SDK does not read `process.env` and requires explicit `fetch`
+- Align CI/CD examples with the real CLI contract of passing tokens as flags instead of ambient env reads
+- Document the packed artifact contents shipped to npm
+
 ## 0.2.0 (2026-05-16)
 
 ### Security
@@ -26,7 +92,7 @@
 
 ## 0.1.1 (2026-05-16)
 
-- Remove public GitHub repository, homepage, and bugs metadata from the npm package manifest.
+- Remove public GitHub repository metadata from the npm package manifest while the source repository remains non-public.
 - Preserve executable permissions for the `prompts-gpt` CLI after package builds.
 
 ## 0.1.0 (2026-05-16)

package/README.md

@@ -12,7 +12,7 @@ AI coding agents work best when they have stable, discoverable instructions insi
 |-------|-------------------|
 | **Codex** | `AGENTS.md` managed block |
 | **Cursor** | `.cursor/rules/prompts-gpt-*.mdc` |
-| **VS Code** | `.github/copilot-instructions.md` + `.vscode/*.code-snippets` |
+| **VS Code** | `.github/copilot-instructions.md` + `.github/instructions/*.instructions.md` + `.vscode/*.code-snippets` |
 | **Copilot** | `.github/prompts/*.prompt.md` |
 
 Prompt Markdown files and a `manifest.json` are always written to `.prompts-gpt/` for discovery.
@@ -22,14 +22,14 @@ Prompt Markdown files and a `manifest.json` are always written to `.prompts-gpt/
 ## Quick start
 
 ```bash
-# 1. Initialize with a project token from the dashboard
-npx @prompts-gpt/client init --token <project-token>
+# Run the latest CLI without installing it globally
+npm exec --yes @prompts-gpt/client@latest -- init --token <project-token>
 
-# 2. Sync prompt packs + agent files in one command
-npx @prompts-gpt/client sync --agent all
+# Sync prompt packs + agent files in one command
+npm exec --yes @prompts-gpt/client@latest -- sync --agent all
 
-# 3. Generate a project-aware prompt and sync it
-npx @prompts-gpt/client generate \
+# Generate a project-aware prompt and sync it
+npm exec --yes @prompts-gpt/client@latest -- generate \
   --goal "Review this diff for security issues" \
   --context "Node.js API with PostgreSQL" \
   --agent codex,cursor,vscode
@@ -43,10 +43,21 @@ npx @prompts-gpt/client generate \
 npm install @prompts-gpt/client
 ```
 
+If you want a project-local CLI instead of one-off `npm exec` usage, install it as a dev dependency and call the bin from `package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "prompts:sync": "prompts-gpt sync --agent all",
+    "prompts:generate": "prompts-gpt generate --goal \"Review this diff for security issues\" --agent codex"
+  }
+}
+```
+
 Or run directly with `npx` — no install required:
 
 ```bash
-npx @prompts-gpt/client <command>
+npx @prompts-gpt/client@latest <command>
 ```
 
 **Requires** Node.js 18.18 or later.
@@ -58,17 +69,21 @@ npx @prompts-gpt/client <command>
 Create a project token in the [Prompts-GPT dashboard](https://prompts-gpt.com/dashboard/agents), then:
 
 ```bash
-prompts-gpt init --token pgpt_your_token_here
+prompts-gpt init --token-prompt
 ```
 
 Credentials are saved to `.prompts-gpt/.credentials.json` with `0600` permissions and automatically added to `.gitignore`.
 
-For CI/CD, pass your secret through the shell instead of letting the package read environment variables directly:
+Project tokens are project-scoped, support separate `Read Prompts` and `Generate Prompts` scopes, and should use the shortest practical expiry for the machine or CI job that needs them.
+
+For CI/CD or secret-manager pipes, use stdin instead of putting the raw token in shell history:
 
 ```bash
-prompts-gpt sync --token "$PROMPTS_GPT_TOKEN" --agent all
+printf '%s' "$PROMPTS_GPT_TOKEN" | prompts-gpt sync --token-stdin --agent all
 ```
 
+The importable SDK never reads `process.env` and never captures ambient `globalThis.fetch`. Pass explicit runtime dependencies in code.
+
 ---
 
 ## CLI reference
@@ -76,9 +91,11 @@ prompts-gpt sync --token "$PROMPTS_GPT_TOKEN" --agent all
 ### `init` — Save credentials
 
 ```bash
-prompts-gpt init --token <token> [--api-url <url>] [--cwd <path>]
+prompts-gpt init (--token <token> | --token-stdin | --token-prompt) [--api-url <url>] [--cwd <path>]
 ```
 
+Use `--token-prompt` for local interactive setup and `--token-stdin` for CI or secret-manager pipes.
+
 ### `sync` — Pull + generate + write everything
 
 ```bash
@@ -87,6 +104,8 @@ prompts-gpt sync [--goal "..."] [--limit 25] [--agent all] [--overwrite]
 
 The default workflow. Pulls library prompts, optionally generates one, writes Markdown files, agent integration files, and a manifest.
 
+Existing prompt Markdown, Cursor rules, Copilot prompt files, and VS Code snippet files are skipped unless you pass `--overwrite`. Managed Prompts-GPT blocks inside `AGENTS.md` and `.github/copilot-instructions.md` remain idempotent and update in place, and a shared `.github/instructions/prompts-gpt.instructions.md` file teaches Copilot to treat synced artifacts as generated outputs.
+
 ### `pull` — Download prompt packs
 
 ```bash
@@ -123,6 +142,8 @@ prompts-gpt help
 | Flag | Description |
 |------|-------------|
 | `--token <token>` | Project API token |
+| `--token-stdin` | Read the token from stdin |
+| `--token-prompt` | Prompt for the token without echoing it |
 | `--api-url <url>` | Custom API base URL |
 | `--cwd <path>` | Target directory for config and generated files |
 | `--agent <targets>` | Comma-separated: `codex`, `cursor`, `vscode`, `copilot`, or `all` |
@@ -139,6 +160,7 @@ Codex, Claude Code, Cursor, GitHub Copilot, ChatGPT, Gemini, Perplexity, Grok, D
 
 ```typescript
 import {
+  DEFAULT_PROMPTS_GPT_API_URL,
   PromptsGptClient,
   syncPrompts,
   writeAgentFiles,
@@ -147,7 +169,7 @@ import {
 
 const client = new PromptsGptClient({
   token: "pgpt_your_token_here",
-  apiUrl: "https://prompts-gpt.com",
+  apiUrl: DEFAULT_PROMPTS_GPT_API_URL,
   fetch,
 });
 
@@ -175,6 +197,12 @@ console.log(`Wrote ${result.markdown.written.length} prompts`);
 console.log(`Synced ${result.agents.written.length} agent files`);
 ```
 
+### Runtime requirements
+
+- `PromptsGptClient` requires an explicit `fetch` implementation. In Node.js 18.18+ you can pass the built-in `fetch`.
+- The SDK is ESM-only. Use `import`, not `require`.
+- File-writing helpers only write inside the provided project directory and reject path traversal.
+
 ### API methods
 
 | Method | Description |
@@ -215,6 +243,8 @@ AGENTS.md                    # Codex: managed <!-- prompts-gpt:start --> block
 
 .github/
   copilot-instructions.md   # VS Code / Copilot shared instructions
+  instructions/
+    prompts-gpt.instructions.md  # Copilot path-specific instructions for generated artifacts
   prompts/
     prompts-gpt-senior-code-reviewer.prompt.md  # Copilot prompt file
 
@@ -222,14 +252,16 @@ AGENTS.md                    # Codex: managed <!-- prompts-gpt:start --> block
   prompts-gpt.code-snippets  # VS Code snippets
 ```
 
+`manifest.json` includes each prompt's supported agent targets, recommended local path, and generated file locations so downstream tools can discover the synced artifacts without guessing paths.
+
 ---
 
 ## Environment variables
 
 | Variable | Description |
 |----------|-------------|
-| `PROMPTS_GPT_TOKEN` | Project API token (alternative to `init`) |
-| `PROMPTS_GPT_API_URL` | Custom API base URL for self-hosted instances |
+| `PROMPTS_GPT_TOKEN` | Shell variable you can expand into `--token` for CI or local scripts |
+| `PROMPTS_GPT_API_URL` | Shell variable you can expand into `--api-url` for self-hosted instances |
 
 ---
 
@@ -254,6 +286,8 @@ try {
 
 The client automatically retries on `429`, `502`, `503`, and `504` responses with exponential backoff and jitter.
 
+SDK responses include `X-Request-Id` plus rate-limit headers so CLI errors can be correlated with one server-side request path during support or incident triage.
+
 ---
 
 ## CI/CD usage
@@ -263,9 +297,35 @@ The client automatically retries on `429`, `502`, `503`, and `504` responses wit
 - name: Sync Prompts-GPT agent files
   env:
     PROMPTS_GPT_TOKEN: ${{ secrets.PROMPTS_GPT_TOKEN }}
-  run: npx @prompts-gpt/client sync --agent all --overwrite
+  run: npm exec --yes @prompts-gpt/client@latest -- sync --token "$PROMPTS_GPT_TOKEN" --agent all --overwrite
 ```
 
+Use `npm exec` here so the job always resolves the package bin explicitly and does not depend on a preinstalled global CLI.
+
+---
+
+## Package contents
+
+The published tarball includes:
+
+- `dist/` ESM JavaScript, source maps, and `.d.ts` files
+- `README.md`
+- `CHANGELOG.md`
+- `LICENSE`
+- `package.json`
+
+This package intentionally does not publish source TypeScript, test fixtures, or local credential files.
+
+Before publishing a new release, run:
+
+```bash
+TMPDIR=/private/tmp npm_config_cache=/private/tmp/prompts-gpt-npm-cache npm pack --dry-run
+```
+
+That verifies the `files` whitelist, the generated `dist/` output, and the executable mode on `dist/cli.js` without mutating the real npm cache.
+
+Publish with the default npm flow unless the release runs inside a provider that supports npm provenance attestation. If you want provenance, enable it explicitly in that CI job instead of forcing it in `package.json`.
+
 ---
 
 ## Security