@prompts-gpt/client 0.1.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,100 @@
1
1
  # Changelog
2
2
 
3
+ ## Unreleased
4
+
5
+ ### Security
6
+
7
+ - Validate `constraints` and `desiredOutput` length (max 1600 chars) client-side before network requests
8
+ - Validate token prefix (`pgpt_`) in `saveLocalCredentials` to reject malformed tokens at save time
9
+ - Sanitize Copilot prompt-file variable names to strip `$`, `{`, `}` injection characters
10
+ - Sanitize managed-block content to prevent marker injection via prompt content
11
+ - Validate API URL scheme (must be `https` or `http`) in `normalizeApiUrl`
12
+ - Auto-generate client-side request IDs (`pgcli_*`) when caller doesn't provide one for correlation
13
+
14
+ ### Fixed
15
+
16
+ - Fix package version mismatch between `package.json` (0.2.1) and CHANGELOG (0.2.2)
17
+ - Fix npm publish failure on unsupported CI providers by removing forced provenance from package metadata
18
+ - Fix race condition in file writes: use atomic `wx` flag with `EEXIST` catch instead of `existsSync` + `wx`
19
+ - Fix `formatPromptMarkdown` producing double blank lines when both `usageNotes` and `variables` are empty
20
+ - Fix `normalizeAgentTargets` deduplication when `all` is mixed with explicit targets (e.g. `all,codex`)
21
+ - Fix `normalizeAgentTargets` returning empty array for empty string input
22
+ - Fix `loadLocalCredentials` returning empty-string token instead of `null` for whitespace-only stored tokens
23
+ - Fix `safeSlug` for unicode-only input by normalizing NFKD and stripping combining marks
24
+ - Fix `ensureGitignoreEntry` to preserve CRLF line endings on Windows-style `.gitignore` files
25
+ - Fix `parseRetryAfterHeader` to cap parsed values at 10 minutes, preventing unbounded waits
26
+ - Fix `assertInside` / `assertSafeOutputDir` boundary comparison for paths at the project root
27
+ - Fix `writePromptIndex` to escape `[` and `]` in Markdown link text to prevent broken rendering
28
+ - Fix `yamlScalar` to handle multi-line strings by normalizing `\r\n` before quoting
29
+ - Serialize agent file writes sequentially to prevent concurrent write races on shared files
30
+
31
+ ### Improvements
32
+
33
+ - Add `--dry-run` flag to `sync` and `install-agents` commands for previewing changes
34
+ - Add dedicated CLI exit code `4` for rate-limit errors (HTTP 429)
35
+ - Use longer default timeout (60s) for prompt generation requests
36
+ - Add `DEFAULT_GENERATE_TIMEOUT_MS` constant for prompt generation timeout
37
+
38
+ ### Packaging
39
+
40
+ - Add npm `homepage` and `bugs.email` metadata so package consumers have a first-party support path from the registry page
41
+ - Clarify the project-local CLI install path and pre-publish `npm pack --dry-run` verification flow in the README
42
+
43
+ ## 0.2.2 (2026-05-16)
44
+
45
+ ### Local Sync
46
+
47
+ - Reject prompt filename collisions after slug normalization before writing local artifacts
48
+ - Respect each prompt pack's declared `agentTargets` when generating Codex, Cursor, VS Code, and Copilot files
49
+ - Skip existing non-managed agent files unless `--overwrite` is explicitly passed
50
+ - Expand `manifest.json` with agent targets, recommended path, and generated file locations for downstream discovery
51
+ - Emit GitHub Copilot prompt files in prompt-file format instead of generic prompt-pack Markdown
52
+ - Add `.github/instructions/prompts-gpt.instructions.md` so Copilot treats synced agent artifacts as generated files
53
+
54
+ ## 0.2.1 (2026-05-16)
55
+
56
+ ### Packaging
57
+
58
+ - Add an explicit `default` export target for better ESM consumer and bundler compatibility
59
+ - Enable npm provenance on publish for stronger package registry attestation
60
+ - Remove the redundant `typesVersions` entry and rely on the package `types` field plus export metadata
61
+
62
+ ### Documentation
63
+
64
+ - Replace stale `npx`-only examples with `npm exec` flows that pin to the latest published package
65
+ - Clarify that the importable SDK does not read `process.env` and requires explicit `fetch`
66
+ - Align CI/CD examples with the real CLI contract of passing tokens as flags instead of ambient env reads
67
+ - Document the packed artifact contents shipped to npm
68
+
69
+ ## 0.2.0 (2026-05-16)
70
+
71
+ ### Security
72
+
73
+ - Token prefix validation now enforced client-side before any network request
74
+ - Response content-type validation prevents processing non-JSON responses
75
+ - Retry delay capped at 30 seconds to prevent retry-after abuse
76
+ - Token length validation on `saveLocalCredentials` prevents oversized storage
77
+ - Control characters stripped from shell-quoted CLI output
78
+
79
+ ### Improvements
80
+
81
+ - Add `accept: application/json` header to all API requests
82
+ - Validate response `content-type` before parsing JSON
83
+ - Cap retry sleep to prevent unbounded waits from malicious `retry-after` headers
84
+ - Improved error messages with structured `code` and `recovery` fields
85
+ - Added `package.json` subpath export for bundler compatibility
86
+ - Extended npm keywords for better discoverability
87
+ - Added `typesVersions` for legacy TypeScript resolution
88
+
89
+ ### Fixed
90
+
91
+ - Fixed potential timeout leak when retries re-create AbortControllers
92
+
93
+ ## 0.1.1 (2026-05-16)
94
+
95
+ - Remove public GitHub repository metadata from the npm package manifest while the source repository remains non-public.
96
+ - Preserve executable permissions for the `prompts-gpt` CLI after package builds.
97
+
3
98
  ## 0.1.0 (2026-05-16)
4
99
 
5
100
  Initial release.
package/README.md CHANGED
@@ -1,147 +1,271 @@
1
1
  # @prompts-gpt/client
2
2
 
3
- CLI and SDK for downloading Prompts-GPT prompt packs into a local project and syncing them into agent-readable files for Codex, Cursor, VS Code, and GitHub Copilot.
3
+ CLI and Node.js SDK for syncing [Prompts-GPT](https://prompts-gpt.com) prompt packs into any local project with first-class integrations for **Codex**, **Cursor**, **VS Code**, and **GitHub Copilot**.
4
4
 
5
- ## Quick Start
5
+ ---
6
+
7
+ ## Why
8
+
9
+ AI coding agents work best when they have stable, discoverable instructions inside the repository. This package bridges Prompts-GPT's cloud prompt library with the local files each agent reads:
10
+
11
+ | Agent | What gets written |
12
+ |-------|-------------------|
13
+ | **Codex** | `AGENTS.md` managed block |
14
+ | **Cursor** | `.cursor/rules/prompts-gpt-*.mdc` |
15
+ | **VS Code** | `.github/copilot-instructions.md` + `.github/instructions/*.instructions.md` + `.vscode/*.code-snippets` |
16
+ | **Copilot** | `.github/prompts/*.prompt.md` |
17
+
18
+ Prompt Markdown files and a `manifest.json` are always written to `.prompts-gpt/` for discovery.
19
+
20
+ ---
21
+
22
+ ## Quick start
6
23
 
7
24
  ```bash
8
- # Initialize with a project token
9
- npx @prompts-gpt/client init --token <project-token>
25
+ # Run the latest CLI without installing it globally
26
+ npm exec --yes @prompts-gpt/client@latest -- init --token <project-token>
10
27
 
11
- # Sync prompt packs and agent files
12
- npx @prompts-gpt/client sync --limit 25 --agent all
28
+ # Sync prompt packs + agent files in one command
29
+ npm exec --yes @prompts-gpt/client@latest -- sync --agent all
13
30
 
14
- # Generate a project-aware prompt
15
- npx @prompts-gpt/client generate --goal "Review this diff" --context "Next.js app" --agent codex,cursor,vscode
31
+ # Generate a project-aware prompt and sync it
32
+ npm exec --yes @prompts-gpt/client@latest -- generate \
33
+ --goal "Review this diff for security issues" \
34
+ --context "Node.js API with PostgreSQL" \
35
+ --agent codex,cursor,vscode
16
36
  ```
17
37
 
18
- ## Installation
38
+ ---
39
+
40
+ ## Install
19
41
 
20
42
  ```bash
21
43
  npm install @prompts-gpt/client
22
44
  ```
23
45
 
24
- Or use directly with `npx`:
46
+ 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:
47
+
48
+ ```json
49
+ {
50
+ "scripts": {
51
+ "prompts:sync": "prompts-gpt sync --agent all",
52
+ "prompts:generate": "prompts-gpt generate --goal \"Review this diff for security issues\" --agent codex"
53
+ }
54
+ }
55
+ ```
56
+
57
+ Or run directly with `npx` — no install required:
25
58
 
26
59
  ```bash
27
- npx @prompts-gpt/client <command>
60
+ npx @prompts-gpt/client@latest <command>
28
61
  ```
29
62
 
30
- **Requirements:** Node.js >= 18.18
63
+ **Requires** Node.js 18.18 or later.
64
+
65
+ ---
31
66
 
32
67
  ## Authentication
33
68
 
34
- Create a project token in the [Prompts-GPT dashboard](https://prompts-gpt.com/dashboard/agents), then initialize:
69
+ Create a project token in the [Prompts-GPT dashboard](https://prompts-gpt.com/dashboard/agents), then:
35
70
 
36
71
  ```bash
37
- prompts-gpt init --token pgpt_your_token_here
72
+ prompts-gpt init --token-prompt
38
73
  ```
39
74
 
40
- This saves credentials to `.prompts-gpt/.credentials.json` (automatically added to `.gitignore`).
75
+ Credentials are saved to `.prompts-gpt/.credentials.json` with `0600` permissions and automatically added to `.gitignore`.
41
76
 
42
- Alternatively, set the `PROMPTS_GPT_TOKEN` environment variable.
77
+ 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.
43
78
 
44
- ## CLI Commands
45
-
46
- ### `init`
47
-
48
- Save a project token to the local credentials file.
79
+ For CI/CD or secret-manager pipes, use stdin instead of putting the raw token in shell history:
49
80
 
50
81
  ```bash
51
- prompts-gpt init --token <token> [--api-url https://prompts-gpt.com] [--cwd /path/to/repo]
82
+ printf '%s' "$PROMPTS_GPT_TOKEN" | prompts-gpt sync --token-stdin --agent all
52
83
  ```
53
84
 
54
- ### `pull`
85
+ The importable SDK never reads `process.env` and never captures ambient `globalThis.fetch`. Pass explicit runtime dependencies in code.
86
+
87
+ ---
88
+
89
+ ## CLI reference
55
90
 
56
- Download prompt packs from the library.
91
+ ### `init` Save credentials
57
92
 
58
93
  ```bash
59
- prompts-gpt pull [--query "repo audit"] [--category coding] [--tool Codex] [--limit 25] [--out .prompts-gpt] [--overwrite]
94
+ prompts-gpt init (--token <token> | --token-stdin | --token-prompt) [--api-url <url>] [--cwd <path>]
60
95
  ```
61
96
 
62
- ### `generate`
97
+ Use `--token-prompt` for local interactive setup and `--token-stdin` for CI or secret-manager pipes.
63
98
 
64
- Generate a project-aware prompt via the API.
99
+ ### `sync` Pull + generate + write everything
65
100
 
66
101
  ```bash
67
- prompts-gpt generate --goal "Review this diff" [--context "Next.js app"] [--tool Codex] [--agent codex,cursor]
102
+ prompts-gpt sync [--goal "..."] [--limit 25] [--agent all] [--overwrite]
68
103
  ```
69
104
 
70
- ### `sync`
105
+ The default workflow. Pulls library prompts, optionally generates one, writes Markdown files, agent integration files, and a manifest.
106
+
107
+ 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.
71
108
 
72
- Pull library prompts and/or generate a prompt, then write Markdown files, agent integration files, and a manifest.
109
+ ### `pull` Download prompt packs
73
110
 
74
111
  ```bash
75
- prompts-gpt sync [--goal "Review this diff"] [--limit 25] [--agent all] [--out .prompts-gpt] [--overwrite]
112
+ prompts-gpt pull [--query "repo audit"] [--category coding] [--tool Codex] [--limit 25] [--overwrite]
76
113
  ```
77
114
 
78
- ### `install-agents`
115
+ ### `generate` — Create a project-aware prompt
79
116
 
80
- Pull prompts and write only the agent integration files (no Markdown).
117
+ ```bash
118
+ prompts-gpt generate --goal "Review this diff" [--context "Next.js app"] [--tool Codex] [--agent codex,cursor]
119
+ ```
120
+
121
+ ### `install-agents` — Write agent files only
81
122
 
82
123
  ```bash
83
124
  prompts-gpt install-agents [--agent codex,cursor,vscode,copilot]
84
125
  ```
85
126
 
86
- ### `project`
87
-
88
- Print the project name and website from the API.
127
+ ### `project` — Print project info
89
128
 
90
129
  ```bash
91
130
  prompts-gpt project
92
131
  ```
93
132
 
94
- ## Programmatic Usage
133
+ ### `version` / `help`
134
+
135
+ ```bash
136
+ prompts-gpt version
137
+ prompts-gpt help
138
+ ```
139
+
140
+ ### Common flags
141
+
142
+ | Flag | Description |
143
+ |------|-------------|
144
+ | `--token <token>` | Project API token |
145
+ | `--token-stdin` | Read the token from stdin |
146
+ | `--token-prompt` | Prompt for the token without echoing it |
147
+ | `--api-url <url>` | Custom API base URL |
148
+ | `--cwd <path>` | Target directory for config and generated files |
149
+ | `--agent <targets>` | Comma-separated: `codex`, `cursor`, `vscode`, `copilot`, or `all` |
150
+ | `--overwrite` | Replace existing files instead of skipping |
151
+ | `--out <dir>` | Output directory (default: `.prompts-gpt`) |
152
+
153
+ ### Supported tools
154
+
155
+ Codex, Claude Code, Cursor, GitHub Copilot, ChatGPT, Gemini, Perplexity, Grok, DeepSeek, Claude.
156
+
157
+ ---
158
+
159
+ ## Programmatic SDK
95
160
 
96
161
  ```typescript
97
- import { PromptsGptClient, syncPrompts } from "@prompts-gpt/client";
162
+ import {
163
+ DEFAULT_PROMPTS_GPT_API_URL,
164
+ PromptsGptClient,
165
+ syncPrompts,
166
+ writeAgentFiles,
167
+ formatPromptMarkdown,
168
+ } from "@prompts-gpt/client";
98
169
 
99
170
  const client = new PromptsGptClient({
100
- token: process.env.PROMPTS_GPT_TOKEN,
171
+ token: "pgpt_your_token_here",
172
+ apiUrl: DEFAULT_PROMPTS_GPT_API_URL,
173
+ fetch,
101
174
  });
102
175
 
103
176
  // Fetch project context
104
177
  const project = await client.getProject();
105
- console.log(project.brandName);
178
+ console.log(project.brandName, project.websiteUrl);
106
179
 
107
- // Pull prompt packs
180
+ // Pull prompt packs from the library
108
181
  const prompts = await client.pullPrompts({ limit: 10, tool: "Codex" });
109
182
 
110
- // Generate a prompt
183
+ // Generate a project-aware prompt
111
184
  const generated = await client.generatePrompt({
112
185
  goal: "Review production diffs for security issues",
113
186
  context: "Node.js microservice with PostgreSQL",
114
187
  tool: "Codex",
115
188
  });
116
189
 
117
- // Sync everything to disk
190
+ // Sync everything to disk (Markdown + agent files + manifest)
118
191
  const result = await syncPrompts([...prompts, generated], {
119
192
  agent: "all",
120
193
  overwrite: true,
121
194
  });
195
+
196
+ console.log(`Wrote ${result.markdown.written.length} prompts`);
197
+ console.log(`Synced ${result.agents.written.length} agent files`);
122
198
  ```
123
199
 
124
- ## Generated Files
200
+ ### Runtime requirements
125
201
 
126
- | Target | Files | Description |
127
- |--------|-------|-------------|
128
- | Markdown | `.prompts-gpt/*.md` | Prompt packs with YAML frontmatter |
129
- | Manifest | `.prompts-gpt/manifest.json` | Index for agent discovery |
130
- | Codex | `AGENTS.md` | Managed block with prompt-pack links |
131
- | Cursor | `.cursor/rules/prompts-gpt-*.mdc` | Per-prompt rule files |
132
- | VS Code | `.github/copilot-instructions.md`, `.vscode/*.code-snippets` | Copilot instructions and snippets |
133
- | Copilot | `.github/prompts/*.prompt.md` | Prompt files for GitHub Copilot |
202
+ - `PromptsGptClient` requires an explicit `fetch` implementation. In Node.js 18.18+ you can pass the built-in `fetch`.
203
+ - The SDK is ESM-only. Use `import`, not `require`.
204
+ - File-writing helpers only write inside the provided project directory and reject path traversal.
134
205
 
135
- ## Configuration
206
+ ### API methods
136
207
 
137
- | Environment Variable | Description |
138
- |---------------------|-------------|
139
- | `PROMPTS_GPT_TOKEN` | Project API token (alternative to `init`) |
140
- | `PROMPTS_GPT_API_URL` | Custom API base URL for self-hosted instances |
208
+ | Method | Description |
209
+ |--------|-------------|
210
+ | `client.getProject()` | Returns project context (brand, competitors, keywords) |
211
+ | `client.pullPrompts(query?)` | Fetches prompt packs from the library |
212
+ | `client.generatePrompt(input)` | Generates a prompt using project context |
141
213
 
142
- ## Error Handling
214
+ ### File-writing utilities
143
215
 
144
- The client throws `PromptsGptApiError` for API errors with structured fields:
216
+ | Function | Description |
217
+ |----------|-------------|
218
+ | `syncPrompts(prompts, opts)` | Full sync: Markdown + agents + manifest |
219
+ | `writePromptMarkdownFiles(prompts, opts)` | Write `.md` files only |
220
+ | `writeAgentFiles(prompts, opts)` | Write agent integration files only |
221
+ | `writePromptManifest(prompts, opts)` | Write `manifest.json` only |
222
+ | `formatPromptMarkdown(prompt)` | Render a single prompt as Markdown |
223
+ | `saveLocalCredentials(input)` | Save token to `.prompts-gpt/.credentials.json` |
224
+ | `loadLocalCredentials(cwd?)` | Load saved credentials |
225
+
226
+ ---
227
+
228
+ ## Generated file structure
229
+
230
+ After running `sync --agent all`, your repository will contain:
231
+
232
+ ```
233
+ .prompts-gpt/
234
+ manifest.json # Machine-readable index
235
+ README.md # Human-readable index
236
+ senior-code-reviewer.md # Prompt pack (YAML frontmatter + Markdown)
237
+ ...
238
+
239
+ AGENTS.md # Codex: managed <!-- prompts-gpt:start --> block
240
+
241
+ .cursor/rules/
242
+ prompts-gpt-senior-code-reviewer.mdc # Cursor rule file
243
+
244
+ .github/
245
+ copilot-instructions.md # VS Code / Copilot shared instructions
246
+ instructions/
247
+ prompts-gpt.instructions.md # Copilot path-specific instructions for generated artifacts
248
+ prompts/
249
+ prompts-gpt-senior-code-reviewer.prompt.md # Copilot prompt file
250
+
251
+ .vscode/
252
+ prompts-gpt.code-snippets # VS Code snippets
253
+ ```
254
+
255
+ `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.
256
+
257
+ ---
258
+
259
+ ## Environment variables
260
+
261
+ | Variable | Description |
262
+ |----------|-------------|
263
+ | `PROMPTS_GPT_TOKEN` | Shell variable you can expand into `--token` for CI or local scripts |
264
+ | `PROMPTS_GPT_API_URL` | Shell variable you can expand into `--api-url` for self-hosted instances |
265
+
266
+ ---
267
+
268
+ ## Error handling
145
269
 
146
270
  ```typescript
147
271
  import { PromptsGptApiError } from "@prompts-gpt/client";
@@ -150,22 +274,73 @@ try {
150
274
  await client.pullPrompts();
151
275
  } catch (error) {
152
276
  if (error instanceof PromptsGptApiError) {
153
- console.error(error.message); // Human-readable message
154
- console.error(error.code); // Machine-readable code (e.g. AUTH_ERROR)
155
- console.error(error.status); // HTTP status code
156
- console.error(error.recovery); // Suggested fix
277
+ console.error(error.message); // Human-readable message
278
+ console.error(error.code); // Machine-readable code
279
+ console.error(error.status); // HTTP status (e.g. 401, 429)
280
+ console.error(error.recovery); // Suggested fix
157
281
  }
158
282
  }
159
283
  ```
160
284
 
285
+ **Error codes:** `AUTH_ERROR`, `VALIDATION_ERROR`, `RATE_LIMIT_ERROR`, `TIMEOUT`, `NETWORK_ERROR`, `INVALID_RESPONSE`, `MISSING_FETCH`.
286
+
287
+ The client automatically retries on `429`, `502`, `503`, and `504` responses with exponential backoff and jitter.
288
+
289
+ 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.
290
+
291
+ ---
292
+
293
+ ## CI/CD usage
294
+
295
+ ```yaml
296
+ # GitHub Actions example
297
+ - name: Sync Prompts-GPT agent files
298
+ env:
299
+ PROMPTS_GPT_TOKEN: ${{ secrets.PROMPTS_GPT_TOKEN }}
300
+ run: npm exec --yes @prompts-gpt/client@latest -- sync --token "$PROMPTS_GPT_TOKEN" --agent all --overwrite
301
+ ```
302
+
303
+ Use `npm exec` here so the job always resolves the package bin explicitly and does not depend on a preinstalled global CLI.
304
+
305
+ ---
306
+
307
+ ## Package contents
308
+
309
+ The published tarball includes:
310
+
311
+ - `dist/` ESM JavaScript, source maps, and `.d.ts` files
312
+ - `README.md`
313
+ - `CHANGELOG.md`
314
+ - `LICENSE`
315
+ - `package.json`
316
+
317
+ This package intentionally does not publish source TypeScript, test fixtures, or local credential files.
318
+
319
+ Before publishing a new release, run:
320
+
321
+ ```bash
322
+ TMPDIR=/private/tmp npm_config_cache=/private/tmp/prompts-gpt-npm-cache npm pack --dry-run
323
+ ```
324
+
325
+ That verifies the `files` whitelist, the generated `dist/` output, and the executable mode on `dist/cli.js` without mutating the real npm cache.
326
+
327
+ 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`.
328
+
329
+ ---
330
+
161
331
  ## Security
162
332
 
163
- - Credentials are stored with `0600` file permissions
164
- - Tokens are validated to start with the `pgpt_` prefix before sending
165
- - HTTPS is enforced in production
166
- - Path traversal is blocked for all file writes
167
- - Project context sent to `generate` is ephemeral and not persisted
333
+ - Credentials stored with `0600` file permissions (owner read/write only)
334
+ - Token prefix (`pgpt_`) validated before any network request
335
+ - HTTPS enforced in production
336
+ - Response content-type validated before JSON parsing
337
+ - Path traversal blocked for all file writes
338
+ - Control characters sanitized from CLI output
339
+ - Retry delays capped to prevent abuse via `retry-after`
340
+ - Context sent to `generate` is ephemeral — never persisted server-side
341
+
342
+ ---
168
343
 
169
344
  ## License
170
345
 
171
- MIT
346
+ [MIT](./LICENSE)