@ptkl/toolkit 1.0.0 → 1.1.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 +19 -2
- package/dist/commands/forge.js +91 -4
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -207,8 +207,8 @@ ptkl forge list
|
|
|
207
207
|
Dry-run install or uninstall scripts locally against the active profile.
|
|
208
208
|
|
|
209
209
|
```bash
|
|
210
|
-
ptkl forge install -p <path> [--env dev|live] [-b]
|
|
211
|
-
ptkl forge uninstall -p <path> [--env dev|live] [-b]
|
|
210
|
+
ptkl forge install -p <path> [--env dev|live] [-b] [--var KEY=value]
|
|
211
|
+
ptkl forge uninstall -p <path> [--env dev|live] [-b] [--var KEY=value]
|
|
212
212
|
```
|
|
213
213
|
|
|
214
214
|
| Flag | Description |
|
|
@@ -216,6 +216,23 @@ ptkl forge uninstall -p <path> [--env dev|live] [-b]
|
|
|
216
216
|
| `-p, --path <path>` | **(required)** Path to the app directory |
|
|
217
217
|
| `--env <env>` | Run for a specific env only (omit to run both) |
|
|
218
218
|
| `-b, --bundle` | Build the bundle before running the script |
|
|
219
|
+
| `--var <key=value>` | Set one app variable (`$variables`) for the run. Repeatable. |
|
|
220
|
+
| `--vars <list>` | Set several at once: `'KEY=value;KEY2=value2'`. Repeatable. |
|
|
221
|
+
| `--vars-file <path>` | JSON file of variables — flat, or env-keyed `{ "dev": {...}, "live": {...} }` |
|
|
222
|
+
|
|
223
|
+
On the platform, the install script reads the app's stored variables for the environment
|
|
224
|
+
through the `$variables` global. Locally there is no app record, so pass them in:
|
|
225
|
+
|
|
226
|
+
```bash
|
|
227
|
+
ptkl forge install -p ./my-app --env dev \
|
|
228
|
+
--var WEBHOOK_URL=https://staging.example.com/hook \
|
|
229
|
+
--var MAX_RETRIES=3
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
Values are parsed as JSON when valid (`3` → number, `true` → boolean, `{"a":1}` → object)
|
|
233
|
+
and kept as strings otherwise. Sources merge in order `--vars-file` → `--vars` → `--var`,
|
|
234
|
+
so a base file can be overridden per run. These flags affect the local dry run only —
|
|
235
|
+
they never write to the deployed app's variables.
|
|
219
236
|
|
|
220
237
|
### `ptkl forge remove-version`
|
|
221
238
|
|
package/dist/commands/forge.js
CHANGED
|
@@ -19,6 +19,76 @@ function parseJSON(label, raw) {
|
|
|
19
19
|
process.exit(1);
|
|
20
20
|
}
|
|
21
21
|
}
|
|
22
|
+
/** Values are JSON when they parse as JSON, otherwise the raw string —
|
|
23
|
+
* same convention as `ptkl forge variables add`. */
|
|
24
|
+
function parseVarValue(raw) {
|
|
25
|
+
try {
|
|
26
|
+
return JSON.parse(raw);
|
|
27
|
+
}
|
|
28
|
+
catch {
|
|
29
|
+
return raw;
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
/** `KEY=value` → `{ KEY: <parsed value> }`. Splits on the FIRST `=` so values may contain `=`. */
|
|
33
|
+
function parseVarPair(pair, flag) {
|
|
34
|
+
const trimmed = pair.trim();
|
|
35
|
+
const eq = trimmed.indexOf('=');
|
|
36
|
+
if (eq < 1) {
|
|
37
|
+
console.error(`${flag} must be in KEY=value form (got '${pair}')`);
|
|
38
|
+
process.exit(1);
|
|
39
|
+
}
|
|
40
|
+
return [trimmed.slice(0, eq).trim(), parseVarValue(trimmed.slice(eq + 1))];
|
|
41
|
+
}
|
|
42
|
+
/** `--vars` payload: `KEY=value;KEY2=value2` (also accepts newline-separated). */
|
|
43
|
+
function parseVarList(list) {
|
|
44
|
+
const out = {};
|
|
45
|
+
for (const pair of list.split(/[;\n]/)) {
|
|
46
|
+
if (!pair.trim())
|
|
47
|
+
continue;
|
|
48
|
+
const [key, value] = parseVarPair(pair, '--vars');
|
|
49
|
+
out[key] = value;
|
|
50
|
+
}
|
|
51
|
+
return out;
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* Build the `$variables` map the local script run should see, mirroring what the
|
|
55
|
+
* platform injects from the app's stored variables (`app.variables[env]`).
|
|
56
|
+
*
|
|
57
|
+
* Sources, lowest precedence first:
|
|
58
|
+
* 1. `--vars-file <path>` — JSON, either a flat map or env-keyed (`{ dev: {...}, live: {...} }`)
|
|
59
|
+
* 2. `--vars KEY=v;KEY2=v2`
|
|
60
|
+
* 3. `--var KEY=v` (repeatable)
|
|
61
|
+
*/
|
|
62
|
+
function collectVariables(options, env) {
|
|
63
|
+
let fromFile = {};
|
|
64
|
+
if (options.varsFile) {
|
|
65
|
+
const filePath = isAbsolute(options.varsFile) ? options.varsFile : join(process.cwd(), options.varsFile);
|
|
66
|
+
if (!existsSync(filePath)) {
|
|
67
|
+
console.error(`--vars-file not found: ${filePath}`);
|
|
68
|
+
process.exit(1);
|
|
69
|
+
}
|
|
70
|
+
const parsed = parseJSON('--vars-file', readFileSync(filePath, 'utf-8'));
|
|
71
|
+
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
|
|
72
|
+
console.error(`--vars-file must contain a JSON object`);
|
|
73
|
+
process.exit(1);
|
|
74
|
+
}
|
|
75
|
+
// Env-keyed shape ({ dev: {...}, live: {...} }) mirrors how variables are stored
|
|
76
|
+
// on the app; anything else is treated as a flat map applied to every env.
|
|
77
|
+
const keys = Object.keys(parsed);
|
|
78
|
+
const envKeyed = keys.length > 0 && keys.every(k => (k === 'dev' || k === 'live') && parsed[k] && typeof parsed[k] === 'object' && !Array.isArray(parsed[k]));
|
|
79
|
+
fromFile = envKeyed ? (parsed[env] ?? {}) : parsed;
|
|
80
|
+
}
|
|
81
|
+
const fromList = (options.vars ?? []).reduce((acc, list) => ({ ...acc, ...parseVarList(list) }), {});
|
|
82
|
+
const fromPairs = (options.var ?? []).reduce((acc, pair) => {
|
|
83
|
+
const [key, value] = parseVarPair(pair, '--var');
|
|
84
|
+
return { ...acc, [key]: value };
|
|
85
|
+
}, {});
|
|
86
|
+
return { ...fromFile, ...fromList, ...fromPairs };
|
|
87
|
+
}
|
|
88
|
+
/** commander collector for repeatable options. */
|
|
89
|
+
function collect(value, previous = []) {
|
|
90
|
+
return previous.concat([value]);
|
|
91
|
+
}
|
|
22
92
|
function formatBuildError(reason) {
|
|
23
93
|
const lines = [];
|
|
24
94
|
if (reason.id || reason.loc) {
|
|
@@ -111,12 +181,18 @@ class ForgeCommand {
|
|
|
111
181
|
.requiredOption("-p, --path <path>", "Path to the app directory (where ptkl.config.js is located)")
|
|
112
182
|
.option("--env <env>", "Run for a specific env only (dev or live). Omit to run for both.")
|
|
113
183
|
.option("-b, --bundle", "Build the bundle before running the install script")
|
|
184
|
+
.option("--var <key=value>", "Set an app variable for the run ($variables). Repeatable.", collect)
|
|
185
|
+
.option("--vars <list>", "Set several app variables at once: 'KEY=value;KEY2=value2'. Repeatable.", collect)
|
|
186
|
+
.option("--vars-file <path>", "JSON file of app variables — flat map, or env-keyed { dev: {...}, live: {...} }")
|
|
114
187
|
.action((options) => this.install(options)))
|
|
115
188
|
.addCommand(new Command("uninstall")
|
|
116
189
|
.description("Dry-run the app uninstall script locally against the active profile (no actual uninstallation). Runs for both dev and live by default.")
|
|
117
190
|
.requiredOption("-p, --path <path>", "Path to the app directory (where ptkl.config.js is located)")
|
|
118
191
|
.option("--env <env>", "Run for a specific env only (dev or live). Omit to run for both.")
|
|
119
192
|
.option("-b, --bundle", "Build the bundle before running the uninstall script")
|
|
193
|
+
.option("--var <key=value>", "Set an app variable for the run ($variables). Repeatable.", collect)
|
|
194
|
+
.option("--vars <list>", "Set several app variables at once: 'KEY=value;KEY2=value2'. Repeatable.", collect)
|
|
195
|
+
.option("--vars-file <path>", "JSON file of app variables — flat map, or env-keyed { dev: {...}, live: {...} }")
|
|
120
196
|
.action((options) => this.uninstall(options)))
|
|
121
197
|
// --- Deployed-app management (appservice) -------------------------------------------
|
|
122
198
|
// These subcommands use the shared scaffold (src/lib/sdk.ts + src/lib/scaffold.ts) and
|
|
@@ -1200,7 +1276,7 @@ class ForgeCommand {
|
|
|
1200
1276
|
await this.bundle({ path, upload: false });
|
|
1201
1277
|
const envs = env ? [env] : ['dev', 'live'];
|
|
1202
1278
|
for (const e of envs) {
|
|
1203
|
-
await ForgeCommand._runScript(path, 'install', e);
|
|
1279
|
+
await ForgeCommand._runScript(path, 'install', e, collectVariables(options, e));
|
|
1204
1280
|
}
|
|
1205
1281
|
}
|
|
1206
1282
|
async uninstall(options) {
|
|
@@ -1210,10 +1286,10 @@ class ForgeCommand {
|
|
|
1210
1286
|
await this.bundle({ path, upload: false });
|
|
1211
1287
|
const envs = env ? [env] : ['dev', 'live'];
|
|
1212
1288
|
for (const e of envs) {
|
|
1213
|
-
await ForgeCommand._runScript(path, 'uninstall', e);
|
|
1289
|
+
await ForgeCommand._runScript(path, 'uninstall', e, collectVariables(options, e));
|
|
1214
1290
|
}
|
|
1215
1291
|
}
|
|
1216
|
-
static async _runScript(appPath, scriptType, env = 'dev') {
|
|
1292
|
+
static async _runScript(appPath, scriptType, env = 'dev', variables = {}) {
|
|
1217
1293
|
appPath = isAbsolute(appPath) ? appPath : join(process.cwd(), appPath);
|
|
1218
1294
|
const module = await import(`${appPath}/ptkl.config.js`);
|
|
1219
1295
|
const { name, distPath, scripts } = module.default ?? {};
|
|
@@ -1241,7 +1317,16 @@ class ForgeCommand {
|
|
|
1241
1317
|
}
|
|
1242
1318
|
};
|
|
1243
1319
|
global.axiosAdapter = axios;
|
|
1244
|
-
|
|
1320
|
+
// In the platform runtime the sandbox is seeded with the app's stored variables for
|
|
1321
|
+
// the env being installed (`app.variables[env]` → `$variables`). Locally there is no
|
|
1322
|
+
// app record yet, so the variables come from --var/--vars/--vars-file.
|
|
1323
|
+
global.$variables = variables;
|
|
1324
|
+
global.$currentEnv = env;
|
|
1325
|
+
const varKeys = Object.keys(variables);
|
|
1326
|
+
console.log(`Running ${scriptType} script for '${name}' (profile: ${profile.name}, env: ${env})...`);
|
|
1327
|
+
console.log(varKeys.length
|
|
1328
|
+
? `$variables: ${varKeys.join(', ')}\n`
|
|
1329
|
+
: `$variables: none — pass --var KEY=value to inject them\n`);
|
|
1245
1330
|
// The bundle is: `return async()=>{try{ ...code... }catch(err){return {_error_:true,...}}}`
|
|
1246
1331
|
// new Function(scriptCode) creates a function whose body is that code.
|
|
1247
1332
|
// Calling it returns the async function, which we then await.
|
|
@@ -1250,6 +1335,8 @@ class ForgeCommand {
|
|
|
1250
1335
|
// Cleanup globals
|
|
1251
1336
|
delete global.window;
|
|
1252
1337
|
delete global.axiosAdapter;
|
|
1338
|
+
delete global.$variables;
|
|
1339
|
+
delete global.$currentEnv;
|
|
1253
1340
|
if (result && result._error_) {
|
|
1254
1341
|
const displayMessage = result?.response?.data?.message || result.message ||
|
|
1255
1342
|
(result.errors && result.errors.length > 0
|