@prompts-gpt/client 0.2.2 → 0.2.3

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.
Files changed (17) hide show
  1. package/LICENSE +75 -21
  2. package/README.md +83 -288
  3. package/dist/cli.js +993 -104
  4. package/dist/cli.js.map +1 -1
  5. package/dist/index.d.ts +16 -1
  6. package/dist/index.d.ts.map +1 -1
  7. package/dist/index.js +284 -36
  8. package/dist/index.js.map +1 -1
  9. package/dist/runtime.d.ts +205 -0
  10. package/dist/runtime.d.ts.map +1 -0
  11. package/dist/runtime.js +1173 -0
  12. package/dist/runtime.js.map +1 -0
  13. package/dist/sweep.d.ts +174 -0
  14. package/dist/sweep.d.ts.map +1 -0
  15. package/dist/sweep.js +594 -0
  16. package/dist/sweep.js.map +1 -0
  17. package/package.json +2 -2
package/LICENSE CHANGED
@@ -1,21 +1,75 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 Prompts-GPT
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ Prompts-GPT Source Available License
2
+ Version 1.0 — Effective 2026
3
+
4
+ Copyright (c) 2026 Prompts-GPT. All rights reserved.
5
+
6
+ Permission is hereby granted, free of charge, to any person or organization
7
+ ("Licensee") obtaining a copy of this software and associated documentation
8
+ files (the "Software"), to use the Software for personal and commercial
9
+ purposes, subject to the following conditions:
10
+
11
+ 1. GRANT OF LICENSE
12
+
13
+ Licensee may:
14
+
15
+ a) Use the Software without restriction for personal projects,
16
+ commercial products, internal development, CI/CD pipelines,
17
+ and production deployments.
18
+
19
+ b) Install the Software in any number of environments.
20
+
21
+ 2. RESTRICTIONS
22
+
23
+ Licensee shall NOT:
24
+
25
+ a) Redistribute the Software, in whole or in part, as a standalone
26
+ package, download, or bundled component of another software
27
+ distribution system.
28
+
29
+ b) Modify, adapt, translate, reverse engineer, decompile, or
30
+ create derivative works of the Software's source code or
31
+ compiled artifacts.
32
+
33
+ c) Sublicense, rent, lease, sell, or otherwise transfer the
34
+ Software or rights to it to any third party.
35
+
36
+ d) Remove, alter, or obscure any proprietary notices, attribution
37
+ markers, or license text embedded in the Software.
38
+
39
+ e) Use the Software to build a competing prompt management
40
+ platform, agent orchestration service, or equivalent product.
41
+
42
+ 3. ATTRIBUTION
43
+
44
+ Build artifacts and runtime telemetry may contain account attribution
45
+ metadata. Tampering with or removing attribution data is prohibited.
46
+
47
+ 4. INTELLECTUAL PROPERTY
48
+
49
+ The Software is and remains the exclusive property of Prompts-GPT.
50
+ No title or ownership is transferred to Licensee.
51
+
52
+ 5. WARRANTY DISCLAIMER
53
+
54
+ THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
55
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
56
+ OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
57
+ NONINFRINGEMENT.
58
+
59
+ 6. LIMITATION OF LIABILITY
60
+
61
+ IN NO EVENT SHALL PROMPTS-GPT BE LIABLE FOR ANY INDIRECT,
62
+ INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES ARISING
63
+ OUT OF THE USE OR INABILITY TO USE THE SOFTWARE.
64
+
65
+ 7. TERMINATION
66
+
67
+ This license terminates automatically if Licensee breaches any
68
+ term. Upon termination, Licensee must stop using the Software.
69
+
70
+ 8. GOVERNING LAW
71
+
72
+ This agreement is governed by the laws of the State of Delaware,
73
+ USA, without regard to conflict of laws principles.
74
+
75
+ For licensing inquiries: licensing@prompts-gpt.com
package/README.md CHANGED
@@ -1,346 +1,141 @@
1
1
  # @prompts-gpt/client
2
2
 
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**.
3
+ CLI and SDK for syncing [Prompts-GPT](https://prompts-gpt.com) prompt packs into any project — with integrations for **Codex**, **Claude Code**, **Cursor**, **VS Code**, **GitHub Copilot**, **Continue**, **Gemini CLI**, **Windsurf**, **Cline**, **Junie**, and **Amp**.
4
4
 
5
5
  ---
6
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
23
-
24
- ```bash
25
- # Run the latest CLI without installing it globally
26
- npm exec --yes @prompts-gpt/client@latest -- init --token <project-token>
27
-
28
- # Sync prompt packs + agent files in one command
29
- npm exec --yes @prompts-gpt/client@latest -- sync --agent all
30
-
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
36
- ```
37
-
38
- ---
39
-
40
- ## Install
7
+ ## Get Started
41
8
 
42
9
  ```bash
43
- npm install @prompts-gpt/client
44
- ```
45
-
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
- ```
10
+ # 1. Install
11
+ npm install -D @prompts-gpt/client
56
12
 
57
- Or run directly with `npx` — no install required:
13
+ # 2. Save your project token
14
+ npx prompts-gpt init --token-prompt
58
15
 
59
- ```bash
60
- npx @prompts-gpt/client@latest <command>
16
+ # 3. Sync prompts and run
17
+ npx prompts-gpt load-config
18
+ npx prompts-gpt run
61
19
  ```
62
20
 
63
- **Requires** Node.js 18.18 or later.
21
+ **Requires** Node.js 18.18+.
64
22
 
65
23
  ---
66
24
 
67
- ## Authentication
68
-
69
- Create a project token in the [Prompts-GPT dashboard](https://prompts-gpt.com/dashboard/agents), then:
25
+ ## What It Does
70
26
 
71
- ```bash
72
- prompts-gpt init --token-prompt
73
- ```
27
+ Bridges the Prompts-GPT cloud library with the agent instruction files each tool reads:
74
28
 
75
- Credentials are saved to `.prompts-gpt/.credentials.json` with `0600` permissions and automatically added to `.gitignore`.
76
-
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.
78
-
79
- For CI/CD or secret-manager pipes, use stdin instead of putting the raw token in shell history:
80
-
81
- ```bash
82
- printf '%s' "$PROMPTS_GPT_TOKEN" | prompts-gpt sync --token-stdin --agent all
83
- ```
84
-
85
- The importable SDK never reads `process.env` and never captures ambient `globalThis.fetch`. Pass explicit runtime dependencies in code.
29
+ | Agent | Written files |
30
+ |-------|--------------|
31
+ | Codex | `AGENTS.md` |
32
+ | Claude Code | `CLAUDE.md` |
33
+ | Cursor | `.cursor/rules/*.mdc` + `.cursor/commands/*.md` |
34
+ | VS Code | `.github/copilot-instructions.md` + `.vscode/*.code-snippets` |
35
+ | Copilot | `.github/prompts/*.prompt.md` |
36
+ | Continue | `.continue/rules/*.md` |
37
+ | Gemini CLI | `GEMINI.md` |
38
+ | Windsurf | `.windsurf/rules/*.md` |
39
+ | Cline | `.clinerules/*.md` |
40
+ | Junie | `.junie/guidelines.md` |
41
+ | Amp | `AGENT.md` |
86
42
 
87
43
  ---
88
44
 
89
- ## CLI reference
90
-
91
- ### `init` — Save credentials
92
-
93
- ```bash
94
- prompts-gpt init (--token <token> | --token-stdin | --token-prompt) [--api-url <url>] [--cwd <path>]
95
- ```
96
-
97
- Use `--token-prompt` for local interactive setup and `--token-stdin` for CI or secret-manager pipes.
45
+ ## Important Use Notes
98
46
 
99
- ### `sync` — Pull + generate + write everything
47
+ - `@prompts-gpt/client` is the published npm package. If you see examples that reference internal app modules such as `lib/sdk`, those are app-internal examples, not the public package import path.
48
+ - Local orchestration can send prompt text, code context, and repository files to third-party model providers and agent CLIs. Review each provider's terms, privacy settings, and permitted automation paths before using private or regulated data.
49
+ - Run artifacts are written locally and can include prompts, model output, logs, and worktree snapshots. Treat `.scripts/runs` as sensitive and do not commit or share it casually.
100
50
 
101
- ```bash
102
- prompts-gpt sync [--goal "..."] [--limit 25] [--agent all] [--overwrite]
103
- ```
51
+ ---
104
52
 
105
- The default workflow. Pulls library prompts, optionally generates one, writes Markdown files, agent integration files, and a manifest.
53
+ ## CLI Commands
54
+
55
+ | Command | Description |
56
+ |---------|-------------|
57
+ | `init` | Save project token |
58
+ | `load-config` | Pull full config from Prompts Studio |
59
+ | `sync` | Pull + generate + write agent files |
60
+ | `run` | Execute one prompt with a local agent |
61
+ | `run-batch` | Execute multiple prompts |
62
+ | `sweep` | Multi-iteration execution |
63
+ | `setup` | Scaffold local config |
64
+ | `status` | Show workspace readiness |
65
+ | `list` | Show prompts, sweeps, agents |
66
+ | `providers` | Show detected CLIs |
67
+ | `doctor` | Validate prerequisites |
68
+ | `validate` | Check config for errors |
69
+
70
+ Run `prompts-gpt help <command>` for detailed options.
106
71
 
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.
72
+ ---
108
73
 
109
- ### `pull` — Download prompt packs
74
+ ## Examples
110
75
 
111
76
  ```bash
112
- prompts-gpt pull [--query "repo audit"] [--category coding] [--tool Codex] [--limit 25] [--overwrite]
113
- ```
77
+ # Run a single prompt
78
+ prompts-gpt run --prompt-file .prompts-gpt/review.md --agent cursor
114
79
 
115
- ### `generate` — Create a project-aware prompt
80
+ # Run a sweep (multi-iteration)
81
+ prompts-gpt sweep --prompt-file .prompts-gpt/sweeps/design.md --iterations 3
116
82
 
117
- ```bash
118
- prompts-gpt generate --goal "Review this diff" [--context "Next.js app"] [--tool Codex] [--agent codex,cursor]
119
- ```
83
+ # Sync from cloud
84
+ prompts-gpt sync --agent all
120
85
 
121
- ### `install-agents` — Write agent files only
122
-
123
- ```bash
124
- prompts-gpt install-agents [--agent codex,cursor,vscode,copilot]
86
+ # CI/CD — pipe token from secret
87
+ printf '%s' "$PROMPTS_GPT_TOKEN" | prompts-gpt sync --token-stdin --agent all
125
88
  ```
126
89
 
127
- ### `project` — Print project info
90
+ ---
128
91
 
129
- ```bash
130
- prompts-gpt project
131
- ```
92
+ ## Configuration
132
93
 
133
- ### `version` / `help`
94
+ Create `.prompts-gpt/config.json` via `prompts-gpt setup`, or manually:
134
95
 
135
- ```bash
136
- prompts-gpt version
137
- prompts-gpt help
96
+ ```json
97
+ {
98
+ "providerOrder": ["codex", "cursor", "claude", "copilot"],
99
+ "defaultAgent": "router",
100
+ "timeoutSeconds": 900,
101
+ "artifactsDir": ".scripts/runs"
102
+ }
138
103
  ```
139
104
 
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.
105
+ All options can be overridden via environment variables. See `prompts-gpt help setup`.
156
106
 
157
107
  ---
158
108
 
159
- ## Programmatic SDK
109
+ ## SDK
160
110
 
161
111
  ```typescript
162
- import {
163
- DEFAULT_PROMPTS_GPT_API_URL,
164
- PromptsGptClient,
165
- syncPrompts,
166
- writeAgentFiles,
167
- formatPromptMarkdown,
168
- } from "@prompts-gpt/client";
112
+ import { PromptsGptClient, syncPrompts } from "@prompts-gpt/client";
169
113
 
170
114
  const client = new PromptsGptClient({
171
- token: "pgpt_your_token_here",
172
- apiUrl: DEFAULT_PROMPTS_GPT_API_URL,
115
+ token: "pgpt_your_token",
116
+ apiUrl: "https://prompts-gpt.com",
173
117
  fetch,
174
118
  });
175
119
 
176
- // Fetch project context
177
- const project = await client.getProject();
178
- console.log(project.brandName, project.websiteUrl);
179
-
180
- // Pull prompt packs from the library
181
- const prompts = await client.pullPrompts({ limit: 10, tool: "Codex" });
182
-
183
- // Generate a project-aware prompt
184
- const generated = await client.generatePrompt({
185
- goal: "Review production diffs for security issues",
186
- context: "Node.js microservice with PostgreSQL",
187
- tool: "Codex",
188
- });
189
-
190
- // Sync everything to disk (Markdown + agent files + manifest)
191
- const result = await syncPrompts([...prompts, generated], {
192
- agent: "all",
193
- overwrite: true,
194
- });
195
-
196
- console.log(`Wrote ${result.markdown.written.length} prompts`);
197
- console.log(`Synced ${result.agents.written.length} agent files`);
198
- ```
199
-
200
- ### Runtime requirements
201
-
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.
205
-
206
- ### API methods
207
-
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 |
213
-
214
- ### File-writing utilities
215
-
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
269
-
270
- ```typescript
271
- import { PromptsGptApiError } from "@prompts-gpt/client";
272
-
273
- try {
274
- await client.pullPrompts();
275
- } catch (error) {
276
- if (error instanceof PromptsGptApiError) {
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
281
- }
282
- }
283
- ```
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
120
+ const prompts = await client.pullPrompts();
121
+ await syncPrompts(prompts, { agent: "all" });
301
122
  ```
302
123
 
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
124
  ---
330
125
 
331
126
  ## Security
332
127
 
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
128
+ - Credentials stored with `0600` permissions
129
+ - Credentials added to `.gitignore`
130
+ - Token prefix (`pgpt_`) validated before requests
131
+ - HTTPS enforced for non-localhost
337
132
  - 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
133
+ - Secret redaction in command previews and error output
134
+ - SIGINT/SIGTERM cleanup releases locks
135
+ - Run artifact directories are intended to stay local and may contain sensitive prompt, output, and diff data
341
136
 
342
137
  ---
343
138
 
344
139
  ## License
345
140
 
346
- [MIT](./LICENSE)
141
+ [Prompts-GPT Source Available License](./LICENSE) — free for personal and commercial use. Redistribution and modification of the package are not permitted.