@locker/cli 0.28.3 → 0.28.4
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 +142 -0
- package/bin/lws.mjs +150 -29
- package/dist/index.cjs.js +1 -1
- package/dist/index.mjs.js +1 -1
- package/dist/lws-sandbox.js +133 -10
- package/dist/purify.js +2 -2
- package/package.json +6 -5
- package/src/config-resolver.mjs +267 -0
- package/src/gates.mjs +132 -0
- package/src/output.mjs +19 -0
- package/src/playwright-check.mjs +65 -0
- package/src/repl.mjs +15 -0
- package/src/runner.mjs +46 -0
- package/src/sandbox-entry.ts +25 -0
package/README.md
CHANGED
|
@@ -34,6 +34,7 @@ Three subcommands, each with a clearly-shaped contract:
|
|
|
34
34
|
- **`--before` / `--after`** are shared across all three subcommands. Inject system-mode `<script>` tags before (and after) sandboxed user code. Repeatable, argv-order, accepts either a file path or an inline JS string. Use them to seed the DOM, register fixtures, or assert post-execution state.
|
|
35
35
|
- **`--endowments`** is shared across all three subcommands. Inject a JSON, JS, or inline-object value as the 4th argument of `evaluateInSandbox`, exposing those properties to sandboxed code as bare identifiers AND on `globalThis`. **Functions are invocable from inside the sandbox.** In `repl` the bindings persist across every line typed at the prompt.
|
|
36
36
|
- **`--timeout <ms>`** aborts an `lws eval` run after the deadline and exits non-zero. Composes with `--endowments`: endowments inject before the timeout race starts.
|
|
37
|
+
- **`--gates-on` / `--gates-off`** are shared across all three subcommands. They tune the LWS feature gates for a single run. With no flag, the run uses the exact gate set karma (and therefore CI) runs under, so the CLI is a faithful triage harness out of the box. `--gates-on` enables additional named gates on top of that baseline; `--gates-off` disables baseline gates. Both are repeatable (`--gates-on a --gates-on b`) and each value may itself be a comma-separated list (`--gates-on a,b`), matching the `--before` / `--after` shape. Name gates in the short form you actually use (`changesSince.264`); the fully-qualified `com.salesforce.locker.changesSince.264` is accepted too but never required. A gate named in both flags ends up off (off is applied last). The resolved set is reported in short form on the `--verbose` `gates:` line and in the `--json` envelope's `gates` array. Use them to A/B a distortion's gated behavior without rebuilding.
|
|
37
38
|
|
|
38
39
|
---
|
|
39
40
|
|
|
@@ -76,6 +77,10 @@ lws --version
|
|
|
76
77
|
lws eval "console.log('hello-world')"
|
|
77
78
|
```
|
|
78
79
|
|
|
80
|
+
> **Automating `lws` from an agent, skill, or CI script?** See
|
|
81
|
+
> [AGENTS.md](./AGENTS.md) for the machine-actionable setup, the
|
|
82
|
+
> missing-Playwright recovery signal, and the semantic exit-code contract.
|
|
83
|
+
|
|
79
84
|
### As a contributor (working in the LWS monorepo)
|
|
80
85
|
|
|
81
86
|
```sh
|
|
@@ -177,6 +182,27 @@ lws eval --timeout 5000 ./my-script.js
|
|
|
177
182
|
# Endowments + timeout compose: setup, then bounded evaluation
|
|
178
183
|
lws eval --endowments '{"BASE_URL": "https://api.example.com"}' --timeout 3000 \
|
|
179
184
|
./my-fetch-script.js
|
|
185
|
+
|
|
186
|
+
# Feature gates: with no flag, the run uses the karma/CI baseline gate set
|
|
187
|
+
lws eval ./my-script.js
|
|
188
|
+
|
|
189
|
+
# Turn a baseline gate OFF to see the pre-gate behavior (e.g. how a
|
|
190
|
+
# distortion behaved before changesSince.262 landed)
|
|
191
|
+
lws eval --gates-off changesSince.262 ./my-script.js
|
|
192
|
+
|
|
193
|
+
# Turn an extra gate ON, on top of the baseline
|
|
194
|
+
lws eval --gates-on changesSince.266 ./my-script.js
|
|
195
|
+
|
|
196
|
+
# Repeatable, or comma-separated; short or fully-qualified names both work
|
|
197
|
+
lws eval --gates-off changesSince.260 --gates-off changesSince.262 ./my-script.js
|
|
198
|
+
lws eval --gates-off changesSince.260,changesSince.262 ./my-script.js
|
|
199
|
+
lws eval --gates-on com.salesforce.locker.changesSince.266 ./my-script.js
|
|
200
|
+
|
|
201
|
+
# Print the resolved gate list (short names) to stderr before the sandbox boots
|
|
202
|
+
lws eval --verbose --gates-off changesSince.262 "1 + 1"
|
|
203
|
+
|
|
204
|
+
# In --json mode the resolved set rides the envelope as a short-name "gates" array
|
|
205
|
+
lws eval --json --gates-off changesSince.262 "1 + 1"
|
|
180
206
|
```
|
|
181
207
|
|
|
182
208
|
---
|
|
@@ -237,6 +263,10 @@ lws component ./my-component --endowments '{"BASE_URL": "https://api.example.com
|
|
|
237
263
|
# export default { GREETING: 'alice', makeGreeting: (n) => 'hello ' + n };
|
|
238
264
|
lws component ./my-component --endowments ./fixtures/endow.mjs
|
|
239
265
|
|
|
266
|
+
# Render the component with a baseline gate turned off (the gate set
|
|
267
|
+
# resolves the same way as for `lws eval`; see Shared options)
|
|
268
|
+
lws component ./my-component --gates-off changesSince.264
|
|
269
|
+
|
|
240
270
|
# Resolve imports from a vendored namespace tree outside the component's
|
|
241
271
|
# own directory. The directory is the namespace ROOT (the parent of the
|
|
242
272
|
# `<ns>/` subdirs), not a single namespace dir.
|
|
@@ -324,6 +354,10 @@ lws repl --endowments ./fixtures/endow.mjs
|
|
|
324
354
|
# 7
|
|
325
355
|
# lws> greet('alice')
|
|
326
356
|
# 'hi alice'
|
|
357
|
+
|
|
358
|
+
# Open the session with a gate turned off; every line typed at the prompt
|
|
359
|
+
# evaluates under the same resolved gate set.
|
|
360
|
+
lws repl --gates-off changesSince.262
|
|
327
361
|
```
|
|
328
362
|
|
|
329
363
|
### Sample session
|
|
@@ -363,10 +397,53 @@ These flags apply to all three subcommands.
|
|
|
363
397
|
| `--before <file-or-inline>` | string (repeatable) | none | Inject a system-mode `<script>` BEFORE sandboxed user code runs. Each occurrence takes one value, which is either a path to a `.js`/`.mjs`/`.cjs` file or an inline JavaScript string (same heuristic as `eval`'s positional). Multiple `--before` flags inject in argv order, each as its own `<script>` (so `var x` in one file does not collide with `var x` in another). A throw in any before-script exits non-zero before the sandbox runs. In `repl`, before-script injection happens once per session, before the prompt appears; the seeded state persists across every REPL line. |
|
|
364
398
|
| `--after <file-or-inline>` | string (repeatable) | none | Inject a system-mode `<script>` AFTER sandboxed user code runs. Same shape as `--before` (file or inline, repeatable, argv-order). Use it for assertion-style checks: a throw in any after-script flips the exit code to non-zero, signalling a failed run. In `repl`, after-scripts run at session termination (`.exit`, EOF, Ctrl+D) BEFORE the browser closes, so DOM state accumulated across REPL lines is still observable. |
|
|
365
399
|
| `--endowments <value>` | string | none | Inject an object into the sandbox as the 4th argument of `evaluateInSandbox(key, source, context, endowments)`. Inside the sandbox, the object's properties are visible as bare identifiers AND on `globalThis`. The value is one of: a path to a `.json` file (read + parsed), a path to a `.js`/`.mjs`/`.cjs` file (dynamic-imported, default export becomes the object), or an inline JSON string. **Function values are invocable from inside the sandbox**: a Node-side `(a, b) => a + b` shows up as a real callable. In `repl`, the bindings persist for the lifetime of the session and are visible on every line. Symbols, Maps, Sets, Dates, and other non-plain-object values throw at registration time. |
|
|
400
|
+
| `--gates-on <name>` | string (repeatable) | none | Enable an LWS feature gate for this run, added on top of the karma baseline (the default set, see below). Repeatable (`--gates-on a --gates-on b`), and each value may itself be a comma-separated list (`--gates-on a,b`); the two forms are equivalent. Name gates in the short form you use (`changesSince.264`); the fully-qualified `com.salesforce.locker.changesSince.264` is accepted and normalized to the same gate. Names are deduped against the baseline. Resolution order is baseline, then `--gates-on` additions, then `--gates-off` removals last, so a gate listed in both flags resolves to off. The resolved list is registered with the sandbox's feature gater before the first `evaluateInSandbox` call (the moment gate reads freeze for a key), so it is honored for the whole run, and is reported in short form on the `--verbose` `gates:` line and the `--json` envelope's `gates` array. Config key: `gatesOn` (a string or an array of strings). |
|
|
401
|
+
| `--gates-off <name>` | string (repeatable) | none | Disable an LWS feature gate for this run, removed from the karma baseline. Same value shape as `--gates-on` (repeatable, comma lists allowed, short or fully-qualified names). Applied last in the resolution order, so `--gates-off` wins over both the baseline and `--gates-on`. Naming a gate that is not in the resolved set is a no-op. Config key: `gatesOff` (a string or an array of strings). |
|
|
366
402
|
| `--json` | boolean | `false` | Emit a single JSON envelope on stdout at exit instead of plain text. The envelope shape is `{ ok: true, result, timing }` on success and `{ ok: false, error: { message, name }, timing }` on failure. `info()`/`debug()` output is silenced (consumers expect exactly one line). Exit code still reflects success. The envelope is buffered and flushed once at teardown so a sandbox throw after compile collapses into a single `ok: false` line: JSON consumers never see a half-state. **Not allowed with `repl`** (an interactive prompt has no terminal envelope point). |
|
|
367
403
|
| `--quiet` | boolean | `false` | Suppress `info()`, `debug()`, and `result()` output. Errors still print to stderr. Not allowed with `--verbose`. |
|
|
368
404
|
| `--verbose` | boolean | `false` | Print `debug()`-level messages to stderr (server URL, input origin, span markers). Not allowed with `--quiet`. |
|
|
369
405
|
|
|
406
|
+
#### Feature gates and the default set
|
|
407
|
+
|
|
408
|
+
LWS distortions and behavior changes are gated behind named feature flags (`changesSince.264` and friends). A gate that is on changes runtime behavior; a gate that is off leaves the older behavior in place. `lws` resolves the effective gate set for each run and registers it with the sandbox's feature gater before the first evaluation, so the choice applies to the whole run.
|
|
409
|
+
|
|
410
|
+
With no `--gates-on` / `--gates-off` flag, the run uses this default set. It is `LWS_DEFAULT_GATER_FEATURES`, the single source of truth exported by `@locker/shared` and registered as-is by the karma integration suite, so a no-flag `lws` run reproduces what CI runs under:
|
|
411
|
+
|
|
412
|
+
```
|
|
413
|
+
com.salesforce.locker.changesSince.256
|
|
414
|
+
com.salesforce.locker.changesSince.258
|
|
415
|
+
com.salesforce.locker.changesSince.260
|
|
416
|
+
com.salesforce.locker.changesSince.262
|
|
417
|
+
com.salesforce.locker.changesSince.264
|
|
418
|
+
com.salesforce.locker.htmlAnchorElementHrefValidation
|
|
419
|
+
com.salesforce.locker.enableSandboxedSameOriginIframe
|
|
420
|
+
```
|
|
421
|
+
|
|
422
|
+
(That list shows the fully-qualified names as registered with the gater. You never type them that way: name gates in the short form below.)
|
|
423
|
+
|
|
424
|
+
`--gates-on` adds to this set; `--gates-off` subtracts from it. Both flags are repeatable and each value may be a comma-separated list, so these are all equivalent ways to enable two gates:
|
|
425
|
+
|
|
426
|
+
```sh
|
|
427
|
+
lws eval --gates-on changesSince.266 --gates-on someGate "1 + 1"
|
|
428
|
+
lws eval --gates-on changesSince.266,someGate "1 + 1"
|
|
429
|
+
```
|
|
430
|
+
|
|
431
|
+
The resolution order is fixed: default set, then on-additions, then off-removals last. A gate named in both flags therefore resolves to off. Run with `--verbose` to print the resolved gate list to stderr as a single `gates: ...` line before the sandbox boots; the names are printed in short form:
|
|
432
|
+
|
|
433
|
+
```sh
|
|
434
|
+
lws eval --verbose --gates-off changesSince.262 "1 + 1"
|
|
435
|
+
# stderr includes: gates: changesSince.256, changesSince.258, ... (changesSince.262 absent)
|
|
436
|
+
```
|
|
437
|
+
|
|
438
|
+
In `--json` mode the same resolved set rides the envelope as a short-name `gates` array, on both success and failure envelopes:
|
|
439
|
+
|
|
440
|
+
```sh
|
|
441
|
+
lws eval --json --gates-off changesSince.262 "1 + 1"
|
|
442
|
+
# stdout envelope includes: "gates": ["changesSince.256", "changesSince.258", ...]
|
|
443
|
+
```
|
|
444
|
+
|
|
445
|
+
A gate name accepts either the short form (`changesSince.264`, the form you use) or the fully-qualified form (`com.salesforce.locker.changesSince.264`). Internally everything normalizes to the fully-qualified form for set operations and back to the short form for display, so the two are interchangeable and never double-prefix.
|
|
446
|
+
|
|
370
447
|
### Eval-only options
|
|
371
448
|
|
|
372
449
|
These flags apply to `lws eval` only.
|
|
@@ -401,6 +478,71 @@ The check is suppressed in three cases:
|
|
|
401
478
|
|
|
402
479
|
---
|
|
403
480
|
|
|
481
|
+
## Configuration file
|
|
482
|
+
|
|
483
|
+
When you keep passing the same flags (`--browser firefox`, a fixed `--key`, a standard set of `--before` scripts), record them once in a config file instead. Same idea as `jest.config.js` or `.eslintrc`: per-project defaults that you can still override on any single invocation.
|
|
484
|
+
|
|
485
|
+
### Authoring the file
|
|
486
|
+
|
|
487
|
+
Drop an `lws.config.js` at your project root. It can also be `lws.config.mjs` or `lws.config.cjs`; pick whichever module system your project uses (the `.js` extension follows the nearest `package.json` `"type"`). The file exports a plain object whose keys are the **camelCase** forms of the CLI flags:
|
|
488
|
+
|
|
489
|
+
```js
|
|
490
|
+
// lws.config.js (CommonJS)
|
|
491
|
+
module.exports = {
|
|
492
|
+
browser: 'firefox',
|
|
493
|
+
key: 'my-project',
|
|
494
|
+
before: ['./test/setup/seed-dom.js'],
|
|
495
|
+
};
|
|
496
|
+
```
|
|
497
|
+
|
|
498
|
+
```js
|
|
499
|
+
// lws.config.mjs (ESM)
|
|
500
|
+
export default {
|
|
501
|
+
browser: 'chromium',
|
|
502
|
+
headed: true,
|
|
503
|
+
lwcModules: ['./packages/ui/modules'],
|
|
504
|
+
gatesOff: ['changesSince.262'],
|
|
505
|
+
};
|
|
506
|
+
```
|
|
507
|
+
|
|
508
|
+
Keys are camelCase because a few flags are kebab-case on the command line: `--lwc-modules` is `lwcModules`, `--gates-on` is `gatesOn`, and `--gates-off` is `gatesOff` in the file. Everything else is the flag name verbatim (`browser`, `headed`, `key`, `port`, `before`, `after`, `endowments`, `timeout`, `json`, `quiet`, `verbose`, `watch`, `name`, `namespace`). The array-valued keys (`before`, `after`, `lwcModules`, `gatesOn`, `gatesOff`) take an array of strings; `gatesOn`/`gatesOff` also accept a single comma-separated string for convenience. An unknown key (a typo like `broswer`) fails the run with a message naming the offending key and the file it came from, so a misspelling never silently does nothing.
|
|
509
|
+
|
|
510
|
+
### How a config value is resolved (the cascade)
|
|
511
|
+
|
|
512
|
+
Four layers, each overriding the one before it. Highest-priority last:
|
|
513
|
+
|
|
514
|
+
1. **Built-in defaults**: what each flag falls back to when nothing else sets it (`browser: 'chromium'`, `key: 'cli'`, etc.).
|
|
515
|
+
2. **Auto-discovered `lws.config.{js,mjs,cjs}`** (see discovery below).
|
|
516
|
+
3. **An explicit `--config <path>`**: deep-merged *over* the discovered config (so a CI config can specify only the deltas it changes).
|
|
517
|
+
4. **Inline CLI flags**: an inline `--browser webkit` always wins over any file.
|
|
518
|
+
|
|
519
|
+
That last layer is free: yargs' native "an explicit flag beats a default" rule means a flag you type on the command line always overrides the config-sourced default. So a config file changes your *defaults*, never your ability to override per-run.
|
|
520
|
+
|
|
521
|
+
```sh
|
|
522
|
+
# lws.config.js sets browser: 'firefox'.
|
|
523
|
+
lws eval "1 + 1" # runs in firefox (from config)
|
|
524
|
+
lws eval --browser webkit "1 + 1" # runs in webkit (inline flag wins)
|
|
525
|
+
```
|
|
526
|
+
|
|
527
|
+
### Discovery
|
|
528
|
+
|
|
529
|
+
With no `--config` flag, `lws` walks up from the current directory looking for an `lws.config.js` (then `.mjs`, then `.cjs`) in each directory. The walk stops at the first ancestor containing a `package.json` (inclusive) or the filesystem root, so running `lws` from a nested subdirectory inherits the project's top-level config but the search never escapes into a parent workspace or your home directory.
|
|
530
|
+
|
|
531
|
+
`--config <path>` opts out of discovery's *result-replacing* behavior and instead layers on top: the path is resolved against the current directory, loaded, and **deep-merged over** whatever discovery found. Nested objects merge key by key; arrays (like `before`) replace wholesale rather than concatenating, matching how an inline array flag replaces a default rather than appending to it.
|
|
532
|
+
|
|
533
|
+
```sh
|
|
534
|
+
# Inherit lws.config.js, override only what ci.config.js changes
|
|
535
|
+
lws eval --config ./ci.config.js ./smoke.js
|
|
536
|
+
```
|
|
537
|
+
|
|
538
|
+
A config file may not set the `config` key (a config cannot point at another config); that is rejected with a clear message.
|
|
539
|
+
|
|
540
|
+
### `repl` and `json`
|
|
541
|
+
|
|
542
|
+
`lws repl` rejects `--json` (an interactive prompt has no single terminal envelope point). To keep a project-wide `json: true` from bricking the REPL, `repl` is the one command that does **not** inherit `json` from the config file: a config `json: true` still applies to `eval` and `component`, but `repl` ignores it. An explicit `--json` on `repl` is still rejected, config or no config.
|
|
543
|
+
|
|
544
|
+
---
|
|
545
|
+
|
|
404
546
|
## Before-script / after-script recipes
|
|
405
547
|
|
|
406
548
|
Before-scripts and after-scripts are the recommended way to compose **system-mode** state around your sandboxed run. They're injected as plain `<script>` tags into the harness page, so they run with full system-mode trust (full DOM access, no membrane in front of them, no `@locker/rollup-plugin` transform applied).
|
package/bin/lws.mjs
CHANGED
|
@@ -3,33 +3,70 @@
|
|
|
3
3
|
import { hideBin } from 'yargs/helpers';
|
|
4
4
|
import yargs from 'yargs/yargs';
|
|
5
5
|
|
|
6
|
+
import { BUILTIN_DEFAULTS, resolveConfig } from '../src/config-resolver.mjs';
|
|
6
7
|
import { SUPPORTED_BROWSERS } from '../src/constants.mjs';
|
|
7
|
-
import {
|
|
8
|
-
import { runComponent, runEval } from '../src/runner.mjs';
|
|
8
|
+
import { assertPlaywrightInstalled } from '../src/playwright-check.mjs';
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
// The command modules (runner.mjs, repl.mjs) statically import
|
|
11
|
+
// `playwright`, so importing them when the package is absent throws a raw
|
|
12
|
+
// ERR_MODULE_NOT_FOUND before any of our code runs. They are therefore
|
|
13
|
+
// loaded lazily inside each command handler, AFTER assertPlaywrightInstalled
|
|
14
|
+
// confirms the package resolves. config-resolver.mjs and constants.mjs are
|
|
15
|
+
// Playwright-free, so they stay as eager top-level imports: config still
|
|
16
|
+
// resolves (and `--help` / `--version` still work) when playwright is gone.
|
|
17
|
+
//
|
|
18
|
+
// Run the Playwright preflight, then lazily load and run the command. On
|
|
19
|
+
// absence: write the actionable guidance to stderr and exit 1, the same
|
|
20
|
+
// pre-run failure contract as a bad config file. `load` is a thunk that
|
|
21
|
+
// dynamically imports the command module and returns the run's exit code.
|
|
22
|
+
async function runCommand(load) {
|
|
23
|
+
try {
|
|
24
|
+
assertPlaywrightInstalled();
|
|
25
|
+
} catch (err) {
|
|
26
|
+
process.stderr.write(`${err.message}\n`);
|
|
27
|
+
process.exit(1);
|
|
28
|
+
}
|
|
29
|
+
const exitCode = await load();
|
|
30
|
+
process.exit(exitCode);
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
// Build the option set shared by all three subcommands. `config` is the
|
|
34
|
+
// resolved config object (see resolveConfig); each option's `default:` is
|
|
35
|
+
// `config.X ?? BUILTIN_DEFAULTS.X`, so the builtin fallback values live
|
|
36
|
+
// in exactly one place (config-resolver.mjs) and the config-key allowlist
|
|
37
|
+
// is derived from those same keys. yargs' native "explicit flag beats
|
|
38
|
+
// default" precedence then makes an inline CLI flag win over config for
|
|
39
|
+
// free, and `--no-headed` negates a config `headed: true` for free.
|
|
40
|
+
//
|
|
41
|
+
// `sourceJsonFromConfig` lets `repl` opt out of inheriting `json` from
|
|
42
|
+
// config: repl rejects --json (it has no terminal envelope point), so a
|
|
43
|
+
// project-wide `json: true` must not brick `lws repl`.
|
|
44
|
+
function buildSharedOptions(y, config, { sourceJsonFromConfig = true } = {}) {
|
|
45
|
+
const jsonDefault = sourceJsonFromConfig
|
|
46
|
+
? (config.json ?? BUILTIN_DEFAULTS.json)
|
|
47
|
+
: BUILTIN_DEFAULTS.json;
|
|
11
48
|
return (
|
|
12
49
|
y
|
|
13
50
|
.option('browser', {
|
|
14
51
|
describe: 'Browser to use',
|
|
15
52
|
choices: SUPPORTED_BROWSERS,
|
|
16
|
-
default:
|
|
53
|
+
default: config.browser ?? BUILTIN_DEFAULTS.browser,
|
|
17
54
|
type: 'string',
|
|
18
55
|
})
|
|
19
56
|
.option('headed', {
|
|
20
57
|
describe: 'Open a visible browser window',
|
|
21
58
|
type: 'boolean',
|
|
22
|
-
default:
|
|
59
|
+
default: config.headed ?? BUILTIN_DEFAULTS.headed,
|
|
23
60
|
})
|
|
24
61
|
.option('key', {
|
|
25
62
|
describe: 'Sandbox key identifier',
|
|
26
63
|
type: 'string',
|
|
27
|
-
default:
|
|
64
|
+
default: config.key ?? BUILTIN_DEFAULTS.key,
|
|
28
65
|
})
|
|
29
66
|
.option('port', {
|
|
30
67
|
describe: 'Server port (0 = auto-select)',
|
|
31
68
|
type: 'number',
|
|
32
|
-
default:
|
|
69
|
+
default: config.port ?? BUILTIN_DEFAULTS.port,
|
|
33
70
|
})
|
|
34
71
|
// `nargs: 1` is load-bearing: with just `array: true`, yargs
|
|
35
72
|
// greedily consumes every following argument up to the next
|
|
@@ -42,6 +79,7 @@ function buildSharedOptions(y) {
|
|
|
42
79
|
type: 'string',
|
|
43
80
|
array: true,
|
|
44
81
|
nargs: 1,
|
|
82
|
+
default: config.before ?? BUILTIN_DEFAULTS.before,
|
|
45
83
|
})
|
|
46
84
|
.option('after', {
|
|
47
85
|
describe:
|
|
@@ -49,16 +87,46 @@ function buildSharedOptions(y) {
|
|
|
49
87
|
type: 'string',
|
|
50
88
|
array: true,
|
|
51
89
|
nargs: 1,
|
|
90
|
+
default: config.after ?? BUILTIN_DEFAULTS.after,
|
|
52
91
|
})
|
|
53
92
|
.option('endowments', {
|
|
54
93
|
describe:
|
|
55
94
|
'Endowments object: path to .json/.js/.mjs/.cjs file, or inline JSON string. Exposed inside the sandbox as the 4th arg of evaluateInSandbox.',
|
|
56
95
|
type: 'string',
|
|
96
|
+
default: config.endowments ?? BUILTIN_DEFAULTS.endowments,
|
|
97
|
+
})
|
|
98
|
+
// Feature-gate control. The run starts from the same gate set
|
|
99
|
+
// karma (and therefore CI) uses; --gates-on adds to it and
|
|
100
|
+
// --gates-off removes from it. Both are repeatable (array, one
|
|
101
|
+
// value per occurrence, argv-order), matching the --before /
|
|
102
|
+
// --after / --lwc-modules shape. Each value is a gate name in
|
|
103
|
+
// short form (`changesSince.264`, the form engineers actually
|
|
104
|
+
// use) or the fully-qualified `com.salesforce.locker.changesSince.264`;
|
|
105
|
+
// a single value may also be a comma-separated list, so
|
|
106
|
+
// `--gates-on a,b` and `--gates-on a --gates-on b` are equivalent.
|
|
107
|
+
// A gate named in both flags wins as OFF (off is applied last).
|
|
108
|
+
// The config keys are camelCase (gatesOn, gatesOff).
|
|
109
|
+
.option('gates-on', {
|
|
110
|
+
describe:
|
|
111
|
+
'Enable an LWS feature gate for this run, on top of the karma baseline (repeatable; short name like changesSince.264)',
|
|
112
|
+
type: 'string',
|
|
113
|
+
array: true,
|
|
114
|
+
nargs: 1,
|
|
115
|
+
default: config.gatesOn ?? BUILTIN_DEFAULTS.gatesOn,
|
|
116
|
+
})
|
|
117
|
+
.option('gates-off', {
|
|
118
|
+
describe:
|
|
119
|
+
'Disable an LWS feature gate for this run, removing it from the karma baseline (repeatable; short name like changesSince.264)',
|
|
120
|
+
type: 'string',
|
|
121
|
+
array: true,
|
|
122
|
+
nargs: 1,
|
|
123
|
+
default: config.gatesOff ?? BUILTIN_DEFAULTS.gatesOff,
|
|
57
124
|
})
|
|
58
125
|
.option('timeout', {
|
|
59
126
|
describe:
|
|
60
127
|
'Abort the sandbox evaluation after this many milliseconds and exit non-zero',
|
|
61
128
|
type: 'number',
|
|
129
|
+
default: config.timeout ?? BUILTIN_DEFAULTS.timeout,
|
|
62
130
|
})
|
|
63
131
|
// --json is the structured-output mode: a single envelope on
|
|
64
132
|
// stdout at exit, info()/debug() suppressed, errors carried in
|
|
@@ -68,7 +136,7 @@ function buildSharedOptions(y) {
|
|
|
68
136
|
describe:
|
|
69
137
|
'Emit a single JSON envelope on stdout; suppress info/debug; exit code still reflects success',
|
|
70
138
|
type: 'boolean',
|
|
71
|
-
default:
|
|
139
|
+
default: jsonDefault,
|
|
72
140
|
})
|
|
73
141
|
// Verbosity: --quiet suppresses info() and result() in text
|
|
74
142
|
// mode (errors still print to stderr). --verbose enables
|
|
@@ -78,12 +146,21 @@ function buildSharedOptions(y) {
|
|
|
78
146
|
.option('quiet', {
|
|
79
147
|
describe: 'Suppress info/debug output; only errors print',
|
|
80
148
|
type: 'boolean',
|
|
81
|
-
default:
|
|
149
|
+
default: config.quiet ?? BUILTIN_DEFAULTS.quiet,
|
|
82
150
|
})
|
|
83
151
|
.option('verbose', {
|
|
84
152
|
describe: 'Print debug-level information to stderr',
|
|
85
153
|
type: 'boolean',
|
|
86
|
-
default:
|
|
154
|
+
default: config.verbose ?? BUILTIN_DEFAULTS.verbose,
|
|
155
|
+
})
|
|
156
|
+
// --config is a real shared option so it appears in --help and
|
|
157
|
+
// passes .strict(). The value is consumed by the pre-parse pass
|
|
158
|
+
// below (config is resolved before options are built), so the
|
|
159
|
+
// runners ignore argv.config.
|
|
160
|
+
.option('config', {
|
|
161
|
+
describe:
|
|
162
|
+
'Path to a config file (resolved against the current directory); deep-merged over an auto-discovered lws.config.{js,mjs,cjs}',
|
|
163
|
+
type: 'string',
|
|
87
164
|
})
|
|
88
165
|
.check((argv) => {
|
|
89
166
|
if (argv.quiet && argv.verbose) {
|
|
@@ -94,6 +171,42 @@ function buildSharedOptions(y) {
|
|
|
94
171
|
);
|
|
95
172
|
}
|
|
96
173
|
|
|
174
|
+
// Pre-parse pass: extract --config before the real parser builds its
|
|
175
|
+
// options. The config must be known before defaults are set, but yargs
|
|
176
|
+
// needs argv parsed to know --config. A throwaway minimal parser breaks
|
|
177
|
+
// the cycle: `unknown-options-as-args` keeps the subcommand and every
|
|
178
|
+
// other flag as inert positionals, so no .strict()/.demandCommand()
|
|
179
|
+
// errors fire and no command handler runs. Only --config is interpreted.
|
|
180
|
+
function preparseConfigPath() {
|
|
181
|
+
try {
|
|
182
|
+
const preparsed = yargs(hideBin(process.argv))
|
|
183
|
+
.option('config', { type: 'string' })
|
|
184
|
+
.help(false)
|
|
185
|
+
.version(false)
|
|
186
|
+
.parserConfiguration({ 'unknown-options-as-args': true })
|
|
187
|
+
.parseSync();
|
|
188
|
+
return preparsed.config;
|
|
189
|
+
} catch {
|
|
190
|
+
// The pre-parse only needs --config and must never be the thing
|
|
191
|
+
// that fails the run. Any genuine arg error is surfaced by the
|
|
192
|
+
// real parser below.
|
|
193
|
+
return undefined;
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
const explicitConfigPath = preparseConfigPath();
|
|
198
|
+
|
|
199
|
+
let config;
|
|
200
|
+
try {
|
|
201
|
+
config = await resolveConfig({ explicitPath: explicitConfigPath });
|
|
202
|
+
} catch (err) {
|
|
203
|
+
// A bad config file (unknown key, non-object export, missing --config
|
|
204
|
+
// path) is a harness failure, not a sandbox verdict: exit 1, message
|
|
205
|
+
// to stderr, consistent with the other pre-run failure paths.
|
|
206
|
+
process.stderr.write(`${err.message}\n`);
|
|
207
|
+
process.exit(1);
|
|
208
|
+
}
|
|
209
|
+
|
|
97
210
|
await yargs(hideBin(process.argv))
|
|
98
211
|
.scriptName('lws')
|
|
99
212
|
.usage('$0 <command> [options]')
|
|
@@ -101,7 +214,7 @@ await yargs(hideBin(process.argv))
|
|
|
101
214
|
'eval <code-or-file>',
|
|
102
215
|
'Evaluate JavaScript inside the LWS sandbox',
|
|
103
216
|
(y) =>
|
|
104
|
-
buildSharedOptions(y)
|
|
217
|
+
buildSharedOptions(y, config)
|
|
105
218
|
.positional('code-or-file', {
|
|
106
219
|
describe: 'JavaScript string, path to a .js file, or "-" for stdin',
|
|
107
220
|
type: 'string',
|
|
@@ -109,7 +222,7 @@ await yargs(hideBin(process.argv))
|
|
|
109
222
|
.option('watch', {
|
|
110
223
|
describe: 'Re-evaluate when the source file changes (requires a file path)',
|
|
111
224
|
type: 'boolean',
|
|
112
|
-
default:
|
|
225
|
+
default: config.watch ?? BUILTIN_DEFAULTS.watch,
|
|
113
226
|
})
|
|
114
227
|
.check((argv) => {
|
|
115
228
|
// --watch streams a separator-delimited log across many
|
|
@@ -121,16 +234,17 @@ await yargs(hideBin(process.argv))
|
|
|
121
234
|
}
|
|
122
235
|
return true;
|
|
123
236
|
}),
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
237
|
+
(argv) =>
|
|
238
|
+
runCommand(async () => {
|
|
239
|
+
const { runEval } = await import('../src/runner.mjs');
|
|
240
|
+
return runEval(argv);
|
|
241
|
+
}),
|
|
128
242
|
)
|
|
129
243
|
.command(
|
|
130
244
|
'component <directory>',
|
|
131
245
|
'Compile and render an LWC component inside the LWS sandbox',
|
|
132
246
|
(y) =>
|
|
133
|
-
buildSharedOptions(y)
|
|
247
|
+
buildSharedOptions(y, config)
|
|
134
248
|
.positional('directory', {
|
|
135
249
|
describe:
|
|
136
250
|
'Path to an LWC component directory (must contain <name>.js + <name>.html)',
|
|
@@ -139,27 +253,30 @@ await yargs(hideBin(process.argv))
|
|
|
139
253
|
.option('name', {
|
|
140
254
|
describe: 'Custom element tag name (default: derived from directory name)',
|
|
141
255
|
type: 'string',
|
|
256
|
+
default: config.name ?? BUILTIN_DEFAULTS.name,
|
|
142
257
|
})
|
|
143
258
|
.option('namespace', {
|
|
144
259
|
describe: 'LWC namespace',
|
|
145
260
|
type: 'string',
|
|
146
|
-
default:
|
|
261
|
+
default: config.namespace ?? BUILTIN_DEFAULTS.namespace,
|
|
147
262
|
})
|
|
148
263
|
// Explicit LWC namespace-root paths layered before the
|
|
149
264
|
// implicit grandparent default. Repeatable; argv-order is
|
|
150
265
|
// preserved (first match wins in the resolver). nargs: 1
|
|
151
266
|
// pins each occurrence to one value so the positional
|
|
152
|
-
// <directory> doesn't get consumed.
|
|
267
|
+
// <directory> doesn't get consumed. The config key is
|
|
268
|
+
// camelCase (lwcModules); it maps to this kebab-case option.
|
|
153
269
|
.option('lwc-modules', {
|
|
154
270
|
describe: 'Additional LWC namespace-root directory (repeatable, argv-order)',
|
|
155
271
|
type: 'string',
|
|
156
272
|
array: true,
|
|
157
273
|
nargs: 1,
|
|
274
|
+
default: config.lwcModules ?? BUILTIN_DEFAULTS.lwcModules,
|
|
158
275
|
})
|
|
159
276
|
.option('watch', {
|
|
160
277
|
describe: 'Re-compile and reload when files in the directory change',
|
|
161
278
|
type: 'boolean',
|
|
162
|
-
default:
|
|
279
|
+
default: config.watch ?? BUILTIN_DEFAULTS.watch,
|
|
163
280
|
})
|
|
164
281
|
.check((argv) => {
|
|
165
282
|
if (argv.watch === true && argv.json === true) {
|
|
@@ -167,16 +284,19 @@ await yargs(hideBin(process.argv))
|
|
|
167
284
|
}
|
|
168
285
|
return true;
|
|
169
286
|
}),
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
287
|
+
(argv) =>
|
|
288
|
+
runCommand(async () => {
|
|
289
|
+
const { runComponent } = await import('../src/runner.mjs');
|
|
290
|
+
return runComponent(argv);
|
|
291
|
+
}),
|
|
174
292
|
)
|
|
175
293
|
.command(
|
|
176
294
|
'repl',
|
|
177
295
|
'Interactive REPL against a persistent LWS sandbox',
|
|
178
296
|
(y) =>
|
|
179
|
-
|
|
297
|
+
// repl opts out of sourcing `json` from config: it rejects
|
|
298
|
+
// --json, so a project-wide `json: true` must not brick it.
|
|
299
|
+
buildSharedOptions(y, config, { sourceJsonFromConfig: false }).check((argv) => {
|
|
180
300
|
// --json emits a single envelope at exit, which is
|
|
181
301
|
// incompatible with an interactive prompt that streams
|
|
182
302
|
// output line by line. Reject at argv parse so users
|
|
@@ -188,10 +308,11 @@ await yargs(hideBin(process.argv))
|
|
|
188
308
|
}
|
|
189
309
|
return true;
|
|
190
310
|
}),
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
311
|
+
(argv) =>
|
|
312
|
+
runCommand(async () => {
|
|
313
|
+
const { runRepl } = await import('../src/repl.mjs');
|
|
314
|
+
return runRepl(argv);
|
|
315
|
+
}),
|
|
195
316
|
)
|
|
196
317
|
.demandCommand(1, 'Specify a subcommand: eval, component, repl')
|
|
197
318
|
.strict()
|
package/dist/index.cjs.js
CHANGED
package/dist/index.mjs.js
CHANGED