@promptscript/cli 1.0.0-rc.2 → 1.0.0

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 (4) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/README.md +109 -175
  3. package/index.js +1466 -106
  4. package/package.json +5 -5
package/CHANGELOG.md CHANGED
@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [1.0.0](https://github.com/mrwogu/promptscript/compare/v1.0.0-rc.3...v1.0.0) (2026-03-06)
9
+
10
+
11
+ ### chore
12
+
13
+ * prepare release ([d751e4b](https://github.com/mrwogu/promptscript/commit/d751e4bd7bc82d834766980bb0eba71dfd7bf92f))
14
+
15
+ ## [1.0.0-rc.3](https://github.com/mrwogu/promptscript/compare/v1.0.0-rc.2...v1.0.0-rc.3) (2026-02-03)
16
+
17
+
18
+ ### chore
19
+
20
+ * prepare rc release ([5a6a707](https://github.com/mrwogu/promptscript/commit/5a6a707b2d30735729f6cb7a64e97722cb66e05d))
21
+
22
+
23
+ ### Features
24
+
25
+ * **validator:** add security rules for supply chain injection detection ([5802a2f](https://github.com/mrwogu/promptscript/commit/5802a2f7d258fd6577d30d76d9ae1d1ce31ef123))
26
+
8
27
  ## [1.0.0-rc.2](https://github.com/mrwogu/promptscript/compare/v1.0.0-rc.1...v1.0.0-rc.2) (2026-02-01)
9
28
 
10
29
 
package/README.md CHANGED
@@ -1,242 +1,176 @@
1
1
  # @promptscript/cli
2
2
 
3
- > Part of the [PromptScript](https://github.com/mrwogu/promptscript) ecosystem - The Prompt-as-Code for AI Instructions.
3
+ **One source of truth for all your AI coding assistants.**
4
4
 
5
- Command-line interface for PromptScript. Compile, validate, and manage AI instructions at enterprise scale.
5
+ Write AI instructions once in PromptScript, compile to GitHub Copilot, Claude Code, Cursor, Antigravity, and more.
6
6
 
7
- ## 🏗️ Architecture
7
+ [![npm version](https://img.shields.io/npm/v/@promptscript/cli.svg)](https://www.npmjs.com/package/@promptscript/cli)
8
+ [![CI](https://github.com/mrwogu/promptscript/actions/workflows/ci.yml/badge.svg)](https://github.com/mrwogu/promptscript/actions/workflows/ci.yml)
9
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
8
10
 
9
- The CLI bundles all internal packages into a single distributable:
11
+ ---
10
12
 
11
- ```
12
- @promptscript/cli (published)
13
- │
14
- ├─► compiler (pipeline orchestration)
15
- │ ├─► resolver
16
- │ ├─► validator ─────► core
17
- │ └─► formatters ────► core
18
- │
19
- └─► resolver (inheritance & import resolution)
20
- ├─► parser ────────► core
21
- └───────────────────► core
22
- ```
13
+ ## The Problem
23
14
 
24
- See the [PromptScript monorepo](https://github.com/mrwogu/promptscript) for development details.
15
+ Every AI coding tool uses a different config format. As your organization grows, so does the chaos:
25
16
 
26
- ## Installation
27
-
28
- ```bash
29
- npm install -g @promptscript/cli
30
- # or
31
- pnpm add -g @promptscript/cli
32
17
  ```
18
+ 50 repos x 4 AI tools = 200 files to maintain
33
19
 
34
- ## Commands
35
-
36
- ### Initialize Project
37
-
38
- ```bash
39
- prs init [options]
40
-
41
- Options:
42
- -n, --name <name> Project name (auto-detected)
43
- -t, --team <team> Team namespace
44
- --inherit <path> Inheritance path (e.g., @company/team)
45
- --registry <path> Registry path
46
- --targets <targets...> Target AI tools (github, claude, cursor)
47
- -i, --interactive Force interactive mode
48
- -y, --yes Skip prompts, use defaults
49
- -f, --force Force reinitialize even if already initialized
20
+ repo-1/CLAUDE.md repo-1/.cursorrules repo-1/.github/copilot-instructions.md
21
+ repo-2/CLAUDE.md repo-2/.cursorrules repo-2/.github/copilot-instructions.md
22
+ ...
23
+ repo-50/CLAUDE.md repo-50/.cursorrules repo-50/.github/copilot-instructions.md
50
24
  ```
51
25
 
52
- **Auto-detection:** Project name, languages, frameworks, and existing AI tool configurations.
53
-
54
- Creates:
26
+ - A security policy update means editing hundreds of files by hand
27
+ - Standards drift across teams and repos
28
+ - Switching AI tools means rewriting everything
29
+ - No audit trail, no validation, no reuse
55
30
 
56
- - `promptscript.yaml` - Configuration file
57
- - `.promptscript/project.prs` - Main project file
31
+ ## The Solution
58
32
 
59
- ### Compile
33
+ PromptScript lets you **build prompts like code** — with inheritance, composition, parameterization, and compilation to any target format:
60
34
 
61
- ```bash
62
- prs compile [options]
63
-
64
- Options:
65
- -t, --target <target> Specific target (github, claude, cursor)
66
- -a, --all All configured targets (default)
67
- -w, --watch Watch mode for continuous compilation (uses chokidar)
68
- -o, --output <dir> Output directory
69
- --dry-run Preview changes without writing files
70
- --force Force overwrite existing files without prompts
71
- --registry <path> Path or URL to registry
72
- --verbose Show detailed compilation progress
73
- --debug Show debug information (includes verbose)
35
+ ```
36
+ .promptscript/project.prs --> prs compile --> CLAUDE.md
37
+ --> .github/copilot-instructions.md
38
+ --> .cursor/rules/project.mdc
39
+ --> .agent/rules/project.md
74
40
  ```
75
41
 
76
- **Watch Mode:** Uses [chokidar](https://github.com/paulmillr/chokidar) for reliable file watching across all platforms. Automatically recompiles when `.prs` files change.
77
-
78
- **Overwrite Protection:** By default, `prs compile` protects user-created files from accidental overwriting. Files generated by PromptScript contain a marker (`> Auto-generated by PromptScript`) and are overwritten silently. For files without this marker:
79
-
80
- - **Interactive mode:** You'll be prompted to overwrite (y/N/a)
81
- - **Non-interactive mode:** Compilation fails with a list of conflicting files
42
+ Update once, propagate everywhere. Version-controlled, validated, vendor-independent.
82
43
 
83
- Use `--force` to skip all prompts and overwrite everything. Use `--dry-run` to preview conflicts before writing.
44
+ ---
84
45
 
85
- ### Validate
46
+ ## Quick Start
86
47
 
87
48
  ```bash
88
- prs validate [options]
89
-
90
- Options:
91
- --strict Treat warnings as errors
92
- --format <format> Output format (text, json)
93
- ```
94
-
95
- ### Pull Updates
49
+ # Install
50
+ npm install -g @promptscript/cli
96
51
 
97
- ```bash
98
- prs pull [options]
52
+ # Initialize (auto-detects your tech stack)
53
+ prs init
99
54
 
100
- Options:
101
- -f, --force Force overwrite local files
55
+ # Compile to all configured AI tools
56
+ prs compile
102
57
  ```
103
58
 
104
- ### Show Diff
59
+ ### Already have CLAUDE.md or .cursorrules?
105
60
 
106
61
  ```bash
107
- prs diff [options]
108
-
109
- Options:
110
- -t, --target <target> Specific target to diff
111
- --full Show full diff without truncation
112
- --no-pager Disable pager output
62
+ # Auto-detect and migrate existing AI instruction files
63
+ prs init --migrate
113
64
  ```
114
65
 
115
- By default, diff output is shown through a pager (`less`) for easy scrolling. Use `--no-pager` to disable this behavior. You can customize the pager via the `PAGER` environment variable.
66
+ ---
116
67
 
117
- ### Check for Updates
68
+ ## Example
118
69
 
119
- ```bash
120
- prs update-check
121
- ```
70
+ `.promptscript/project.prs`:
122
71
 
123
- Checks if a newer version of the CLI is available on npm and displays the result:
72
+ ```promptscript
73
+ @meta { id: "checkout-service" syntax: "1.0.0" }
124
74
 
125
- ```
126
- @promptscript/cli v1.0.0
127
- ✓ Up to date
128
- ```
75
+ @inherit @company/backend-security
76
+ @use @fragments/testing
77
+ @use @fragments/typescript-strict
129
78
 
130
- Or if an update is available:
79
+ @identity {
80
+ """
81
+ You are an expert Backend Engineer working on the Checkout Service.
82
+ This service handles payments using hexagonal architecture.
83
+ """
84
+ }
131
85
 
132
- ```
133
- @promptscript/cli v1.0.0
134
- Update available: 1.0.0 → 1.1.0 (npm i -g @promptscript/cli)
86
+ @shortcuts {
87
+ "/review": "Security-focused code review"
88
+ "/test": "Write unit tests with Vitest"
89
+ }
135
90
  ```
136
91
 
137
- **Automatic Update Checks:** The CLI automatically checks for updates once every 24 hours when running any command. The check is non-blocking and cached locally. To disable automatic checks, set the `PROMPTSCRIPT_NO_UPDATE_CHECK` environment variable:
92
+ Run `prs compile` and get correctly formatted output for every AI tool your team uses.
138
93
 
139
- ```bash
140
- PROMPTSCRIPT_NO_UPDATE_CHECK=1 prs compile
141
- ```
94
+ ---
142
95
 
143
- ## Environment Variables
96
+ ## Commands
144
97
 
145
- | Variable | Description |
146
- | ------------------------------ | ---------------------------------------------- |
147
- | `PROMPTSCRIPT_NO_UPDATE_CHECK` | Set to `1` to disable automatic update checks |
148
- | `PROMPTSCRIPT_VERBOSE` | Set to `1` to enable verbose output |
149
- | `PROMPTSCRIPT_DEBUG` | Set to `1` to enable debug output |
150
- | `PAGER` | Custom pager for diff output (default: `less`) |
151
- | `NO_COLOR` | Set to disable colored output |
98
+ | Command | Description |
99
+ | :---------------------- | :------------------------------------------- |
100
+ | `prs init` | Initialize project with auto-detection |
101
+ | `prs compile` | Compile to target AI tool formats |
102
+ | `prs compile -w` | Watch mode — recompile on changes |
103
+ | `prs compile --dry-run` | Preview changes without writing files |
104
+ | `prs validate` | Validate `.prs` files with detailed errors |
105
+ | `prs diff` | Show diff between source and compiled output |
106
+ | `prs pull` | Pull updates from registry |
107
+ | `prs update-check` | Check for newer CLI versions |
108
+
109
+ ## Key Features
110
+
111
+ - **Inheritance** — build org-wide, team-level, and project-level configs that cascade like CSS
112
+ - **Composition** — reuse fragments across projects with `@use`
113
+ - **Parameterized templates** — `@inherit @stacks/node(port: 8080, db: "postgres")`
114
+ - **Multi-target compilation** — one source, any number of AI tools
115
+ - **Watch mode** — instant recompilation on file changes
116
+ - **Overwrite protection** — never accidentally clobbers hand-written files
117
+ - **Validation** — catch errors before they reach your AI tools
118
+ - **Registry support** — share configs via Git registries (private or public)
119
+ - **AI-assisted migration** — convert existing `CLAUDE.md`, `.cursorrules`, etc.
120
+
121
+ ## Supported Targets
122
+
123
+ | AI Tool | Output |
124
+ | :--------------------- | :------------------------------------------------- |
125
+ | **GitHub Copilot** | `.github/copilot-instructions.md`, agents, prompts |
126
+ | **Claude Code** | `CLAUDE.md`, skills, local memory |
127
+ | **Cursor** | `.cursor/rules/*.mdc` |
128
+ | **Google Antigravity** | `.agent/rules/*.md` |
152
129
 
153
130
  ## Configuration
154
131
 
155
- Create a `promptscript.yaml` file:
132
+ `promptscript.yaml`:
156
133
 
157
134
  ```yaml
158
135
  version: '1'
159
136
 
160
- project:
161
- id: my-project
162
- team: frontend
163
-
164
- inherit: '@frontend/team'
165
-
166
- registry:
167
- path: './registry'
168
- cache: true # Enable HTTP registry caching
169
- auth: # Authentication for HTTP registry
170
- type: bearer
171
- token: ${REGISTRY_TOKEN} # Environment variable interpolation
172
-
173
137
  input:
174
138
  entry: '.promptscript/project.prs'
175
- include:
176
- - '.promptscript/**/*.prs'
177
- exclude:
178
- - '**/*.local.prs'
179
-
180
- output:
181
- dir: '.' # Output base directory
182
- clean: false # Clean output before compile
183
- targets:
184
- github: '.github/copilot-instructions.md'
185
- claude: 'CLAUDE.md'
186
- cursor: '.cursor/rules/project.mdc'
187
-
188
- watch:
189
- debounce: 300 # Debounce time in ms
190
- ignored:
191
- - '**/node_modules/**'
192
139
 
193
140
  targets:
194
141
  - github
195
142
  - claude
196
143
  - cursor
197
-
198
- validation:
199
- requiredGuards:
200
- - '@core/guards/compliance'
201
- rules:
202
- empty-block: warn
203
- ```
204
-
205
- ## Output Examples
206
-
207
- ### Success
208
-
209
144
  ```
210
- ✔ Compilation successful
211
145
 
212
- ✓ .github/copilot-instructions.md
213
- ✓ CLAUDE.md
214
- ✓ .cursor/rules/project.mdc
146
+ See the [full configuration reference](https://getpromptscript.dev/reference/config/) for registry auth, watch settings, validation rules, and more.
215
147
 
216
- Stats: 234ms (resolve: 45ms, validate: 8ms, format: 181ms)
217
- ```
148
+ ## Environment Variables
218
149
 
219
- ### Watch Mode
150
+ | Variable | Description |
151
+ | ------------------------------ | ---------------------------------------------- |
152
+ | `PROMPTSCRIPT_NO_UPDATE_CHECK` | Set to `1` to disable automatic update checks |
153
+ | `PROMPTSCRIPT_VERBOSE` | Set to `1` to enable verbose output |
154
+ | `PROMPTSCRIPT_DEBUG` | Set to `1` to enable debug output |
155
+ | `PAGER` | Custom pager for diff output (default: `less`) |
156
+ | `NO_COLOR` | Set to disable colored output |
220
157
 
221
- ```
222
- 👀 Watching for changes...
158
+ ## Docker
223
159
 
224
- [12:34:56] File changed: .promptscript/project.prs
225
- ✔ Compilation successful (156ms)
160
+ No Node.js? Use the Docker image:
226
161
 
227
- ✓ .github/copilot-instructions.md
228
- ✓ CLAUDE.md
162
+ ```bash
163
+ docker run --rm -v $(pwd):/workspace ghcr.io/mrwogu/promptscript:latest compile
164
+ docker run --rm -v $(pwd):/workspace ghcr.io/mrwogu/promptscript:latest validate --strict
229
165
  ```
230
166
 
231
- ### Error
167
+ ## Documentation
232
168
 
233
- ```
234
- ✖ Compilation failed
235
-
236
- ✗ @meta.id is required
237
- at .promptscript/project.prs:1:1
238
- suggestion: Add id: "your-id" to @meta
239
- ```
169
+ - [Getting Started](https://getpromptscript.dev/getting-started/) — 5-minute quickstart
170
+ - [Language Reference](https://getpromptscript.dev/reference/syntax/) — full syntax docs
171
+ - [Inheritance Guide](https://getpromptscript.dev/guides/inheritance/) — composition patterns
172
+ - [Migration Guide](https://getpromptscript.dev/guides/migration/) — converting existing files
173
+ - [Enterprise Guide](https://getpromptscript.dev/guides/enterprise/) — scaling across organizations
240
174
 
241
175
  ## License
242
176