@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 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 { runRepl } from '../src/repl.mjs';
8
- import { runComponent, runEval } from '../src/runner.mjs';
8
+ import { assertPlaywrightInstalled } from '../src/playwright-check.mjs';
9
9
 
10
- function buildSharedOptions(y) {
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: 'chromium',
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: false,
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: 'cli',
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: 0,
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: false,
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: false,
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: false,
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: false,
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
- async (argv) => {
125
- const exitCode = await runEval(argv);
126
- process.exit(exitCode);
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: 'c',
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: false,
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
- async (argv) => {
171
- const exitCode = await runComponent(argv);
172
- process.exit(exitCode);
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
- buildSharedOptions(y).check((argv) => {
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
- async (argv) => {
192
- const exitCode = await runRepl(argv);
193
- process.exit(exitCode);
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
@@ -2,4 +2,4 @@
2
2
  * Copyright (C) 2026 salesforce.com, inc.
3
3
  */
4
4
  'use strict';
5
- /*! version: 0.28.3 */
5
+ /*! version: 0.28.4 */
package/dist/index.mjs.js CHANGED
@@ -2,4 +2,4 @@
2
2
  * Copyright (C) 2026 salesforce.com, inc.
3
3
  */
4
4
 
5
- /*! version: 0.28.3 */
5
+ /*! version: 0.28.4 */