@ptkl/toolkit 0.10.4 → 0.14.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.
package/README.md CHANGED
@@ -124,6 +124,107 @@ You can override the active profile for any command using the global `--profile`
124
124
  ptkl --profile production apps upload -a app -d ./my-app
125
125
  ```
126
126
 
127
+ ## Forge
128
+
129
+ Commands for building and running Protokol Forge apps locally.
130
+
131
+ ### `ptkl forge dev`
132
+
133
+ Start a local development server for a forge app with hot module replacement.
134
+
135
+ ```bash
136
+ ptkl forge dev -p <path> [options]
137
+ ```
138
+
139
+ #### Options
140
+
141
+ | Flag | Description |
142
+ |------|-------------|
143
+ | `-p, --path <path>` | **(required)** Path to the app directory |
144
+ | `--view <view>` | Which view to serve (defaults to `main`) |
145
+ | `--platform-url <url>` | Platform UI URL for consent/permission flows |
146
+ | `-m, --mode <mode>` | Vite mode (defaults to `development`) |
147
+ | `--env <env>` | Target environment (`dev` or `live`) |
148
+
149
+ #### Multi-view development
150
+
151
+ Forge apps can declare multiple views in `ptkl.config.js`:
152
+
153
+ ```js
154
+ export default {
155
+ name: 'my-app',
156
+ views: {
157
+ main: path.resolve(__dirname, 'src/main.tsx'),
158
+ 'product-details': {
159
+ entry: path.resolve(__dirname, 'src/productDetails.tsx'),
160
+ access: 'public',
161
+ permissions: ['read my-integration::items'],
162
+ },
163
+ },
164
+ }
165
+ ```
166
+
167
+ By default, `ptkl forge dev` serves the `main` view. Use `--view` to serve a different one:
168
+
169
+ ```bash
170
+ # Serve the main platform view (default)
171
+ ptkl forge dev -p .
172
+
173
+ # Serve a public view for standalone testing
174
+ ptkl forge dev -p . --view product-details
175
+ ```
176
+
177
+ The `--view` flag swaps the entry point in the app's `index.html` so Vite serves the selected view with full HMR. Each view runs as a standalone app on its own dev server.
178
+
179
+ Embeddable platform views (not `main`, not `public`) are automatically built in watch mode and published to the local dev hub for cross-app testing via `AppView`.
180
+
181
+ ### `ptkl forge bundle`
182
+
183
+ Build and optionally upload a forge app bundle.
184
+
185
+ ```bash
186
+ ptkl forge bundle -p <path> [options]
187
+ ```
188
+
189
+ #### Options
190
+
191
+ | Flag | Description |
192
+ |------|-------------|
193
+ | `-p, --path <path>` | **(required)** Path to the app directory |
194
+ | `-u, --upload` | Upload the bundle after building |
195
+ | `-m, --mode <mode>` | Vite build mode (defaults to `production`) |
196
+
197
+ ### `ptkl forge list`
198
+
199
+ List all forge apps in the current profile's project.
200
+
201
+ ```bash
202
+ ptkl forge list
203
+ ```
204
+
205
+ ### `ptkl forge install` / `ptkl forge uninstall`
206
+
207
+ Dry-run install or uninstall scripts locally against the active profile.
208
+
209
+ ```bash
210
+ ptkl forge install -p <path> [--env dev|live] [-b]
211
+ ptkl forge uninstall -p <path> [--env dev|live] [-b]
212
+ ```
213
+
214
+ | Flag | Description |
215
+ |------|-------------|
216
+ | `-p, --path <path>` | **(required)** Path to the app directory |
217
+ | `--env <env>` | Run for a specific env only (omit to run both) |
218
+ | `-b, --bundle` | Build the bundle before running the script |
219
+
220
+ ### `ptkl forge remove-version`
221
+
222
+ Remove a specific version of a forge app.
223
+
224
+ ```bash
225
+ ptkl forge remove-version -r <ref> -v <version>
226
+ ```
227
+
127
228
  ## Version
128
229
 
129
230
  Current version: 0.7.0
File without changes