@runeditrun/rer 0.2.120 → 0.2.122

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 (152) hide show
  1. package/cli/README.md +173 -5
  2. package/cli/archive.mjs +1 -1
  3. package/cli/authoring.mjs +1 -1
  4. package/cli/browser-runtime.mjs +33 -18
  5. package/cli/business/agent-help.mjs +11 -11
  6. package/cli/business/agent-verbs.mjs +9 -8
  7. package/cli/business/api.mjs +11 -7
  8. package/cli/business/carry.mjs +4 -3
  9. package/cli/business/choices.mjs +1 -1
  10. package/cli/business/command.mjs +33 -11
  11. package/cli/business/connect.mjs +4 -4
  12. package/cli/business/credential-file.mjs +102 -0
  13. package/cli/business/errors.mjs +5 -2
  14. package/cli/business/invocation.mjs +7 -4
  15. package/cli/business/keychain.mjs +6 -2
  16. package/cli/business/local-commands.mjs +9 -3
  17. package/cli/business/mcp-bridge.mjs +2 -1
  18. package/cli/business/questions.mjs +1 -1
  19. package/cli/business/run-child.mjs +5 -5
  20. package/cli/business/run-grant.mjs +27 -8
  21. package/cli/business/run-mask.mjs +8 -1
  22. package/cli/business/scan-command.mjs +1 -1
  23. package/cli/business/service.mjs +4 -2
  24. package/cli/business/state.mjs +2 -2
  25. package/cli/checkout-folders.mjs +1 -1
  26. package/cli/checkout-preparation.mjs +4 -4
  27. package/cli/command-guidance.mjs +9 -0
  28. package/cli/companion/command.mjs +4 -3
  29. package/cli/companion/providers/sandbox.mjs +1 -1
  30. package/cli/companion/setup.mjs +4 -4
  31. package/cli/contract.mjs +8 -8
  32. package/cli/demo.mjs +1 -1
  33. package/cli/deploy-command.mjs +10 -5
  34. package/cli/deploy-hook.mjs +3 -2
  35. package/cli/deploy-inputs.mjs +20 -3
  36. package/cli/deploy-owner-input.mjs +2 -2
  37. package/cli/deploy-settings.mjs +14 -0
  38. package/cli/deploy-source.mjs +1 -1
  39. package/cli/deploy-variables.mjs +7 -1
  40. package/cli/deploy.mjs +6 -4
  41. package/cli/deployment-record.mjs +1 -1
  42. package/cli/dev-identity.mjs +4 -4
  43. package/cli/door-clauses.mjs +2 -2
  44. package/cli/door-mode.mjs +7 -7
  45. package/cli/door.mjs +7 -7
  46. package/cli/errors.mjs +15 -1
  47. package/cli/export-summary.mjs +1 -1
  48. package/cli/export.mjs +1 -1
  49. package/cli/hosted-export.mjs +1 -1
  50. package/cli/hosted-output.mjs +2 -2
  51. package/cli/human-error.mjs +8 -2
  52. package/cli/hydration/browser.mjs +1 -1
  53. package/cli/hydration/check.mjs +1 -1
  54. package/cli/import-summary.mjs +2 -2
  55. package/cli/inspect.mjs +9 -4
  56. package/cli/lifecycle.mjs +10 -10
  57. package/cli/listen.mjs +1 -1
  58. package/cli/listing.mjs +1 -1
  59. package/cli/local-env.mjs +1 -1
  60. package/cli/local.mjs +4 -4
  61. package/cli/managed-server.mjs +36 -13
  62. package/cli/output.mjs +2 -1
  63. package/cli/owner-entry-ready.mjs +92 -0
  64. package/cli/parse.mjs +19 -9
  65. package/cli/port.mjs +3 -3
  66. package/cli/portability-runtime.mjs +16 -0
  67. package/cli/portability.mjs +4 -4
  68. package/cli/production-auth.mjs +4 -2
  69. package/cli/production-mail.mjs +1 -1
  70. package/cli/project.mjs +2 -0
  71. package/cli/rehearse/options.mjs +3 -3
  72. package/cli/release-candidate.mjs +2 -2
  73. package/cli/release.mjs +5 -5
  74. package/cli/server-registry.mjs +3 -3
  75. package/cli/server-resources.mjs +1 -1
  76. package/cli/setup-input.mjs +6 -6
  77. package/cli/signin.mjs +11 -10
  78. package/cli/site-render.mjs +1 -1
  79. package/cli/size/schema.mjs +1 -1
  80. package/cli/size/verify-step.mjs +1 -1
  81. package/cli/transfers.mjs +4 -4
  82. package/edition-authoring/api-source.mjs +121 -0
  83. package/edition-authoring/archive-source.mjs +1 -86
  84. package/edition-authoring/base-copies.mjs +5 -3
  85. package/global/CHANGELOG.md +47 -0
  86. package/global/browser-runtime.mjs +9 -5
  87. package/global/cli/command.mjs +6 -5
  88. package/global/cli/install.mjs +6 -3
  89. package/global/cli/path-link.mjs +11 -22
  90. package/global/cli/repo-command.mjs +4 -3
  91. package/global/cli/repository-contract.mjs +3 -3
  92. package/global/door/command.mjs +39 -38
  93. package/global/door/control.mjs +3 -3
  94. package/global/door/pages.mjs +6 -5
  95. package/global/door/server.mjs +8 -5
  96. package/global/door/sites.mjs +14 -13
  97. package/global/launch/capacity.mjs +2 -2
  98. package/global/launch/dev.mjs +6 -6
  99. package/global/launch/door.mjs +1 -1
  100. package/global/launch/facts.mjs +2 -2
  101. package/global/launch/failure.mjs +1 -1
  102. package/global/launch/prepare.mjs +3 -3
  103. package/global/launch/render.mjs +3 -2
  104. package/global/launch/worker.mjs +1 -1
  105. package/global/list.mjs +4 -4
  106. package/global/main.mjs +32 -31
  107. package/global/registry.mjs +1 -1
  108. package/global/run.mjs +5 -5
  109. package/global/update/command.mjs +5 -5
  110. package/global/update/notice.mjs +1 -1
  111. package/global/version.mjs +1 -1
  112. package/install.sh +17 -4
  113. package/modules/deploy-kit/README.md +11 -3
  114. package/modules/deploy-kit/asset-health.mjs +6 -4
  115. package/modules/deploy-kit/cancellation.mjs +26 -0
  116. package/modules/deploy-kit/d1-import-diagnostics.mjs +3 -2
  117. package/modules/deploy-kit/deploy.mjs +8 -3
  118. package/modules/deploy-kit/diagnostics.mjs +11 -4
  119. package/modules/deploy-kit/health-request.mjs +16 -9
  120. package/modules/deploy-kit/health.mjs +14 -11
  121. package/modules/deploy-kit/owner-cli.mjs +55 -25
  122. package/modules/deploy-kit/owner-remove.mjs +7 -6
  123. package/modules/deploy-kit/owner-secret-copy.mjs +2 -1
  124. package/modules/deploy-kit/owner-secret.mjs +8 -5
  125. package/modules/deploy-kit/owner.mjs +49 -30
  126. package/modules/deploy-kit/provider-transport.mjs +2 -0
  127. package/modules/deploy-kit/provider.mjs +10 -9
  128. package/modules/deploy-kit/readiness-window.mjs +5 -3
  129. package/modules/deploy-kit/site.mjs +1 -1
  130. package/modules/deploy-kit/teardown.mjs +5 -4
  131. package/modules/deploy-kit/validation.mjs +1 -0
  132. package/modules/deploy-kit/worker.mjs +1 -0
  133. package/modules/operator-auth/dev/index.mjs +4 -3
  134. package/modules/operator-auth/dev/sign-in-as.mjs +2 -1
  135. package/modules/operator-auth/dev-gate.mjs +3 -2
  136. package/modules/operator-auth/routes.mjs +2 -1
  137. package/modules/operator-auth/terminal-guidance.mjs +3 -0
  138. package/onboarding/adapter-settings.mjs +1 -0
  139. package/onboarding/adapter.mjs +3 -3
  140. package/onboarding/agent-handoff.mjs +1 -1
  141. package/onboarding/busy.mjs +1 -1
  142. package/onboarding/launcher.mjs +1 -1
  143. package/onboarding/local/environment.mjs +1 -1
  144. package/onboarding/local/operation.mjs +12 -4
  145. package/onboarding/local/owner.mjs +2 -2
  146. package/onboarding/operator-installer.mjs +4 -3
  147. package/onboarding/operator-migrations.mjs +1 -1
  148. package/onboarding/operator-prerequisites.mjs +26 -14
  149. package/onboarding/operator-settings.mjs +28 -0
  150. package/onboarding/process-diagnostics.mjs +2 -2
  151. package/onboarding/project-vite.mjs +1 -1
  152. package/package.json +1 -1
package/cli/README.md CHANGED
@@ -81,6 +81,31 @@ starts waiting on an existing server have one five-minute elapsed deadline,
81
81
  including control requests and polling. Loopback HTTP requests use an elapsed
82
82
  deadline, so a response that keeps sending bytes cannot extend readiness.
83
83
 
84
+ Signed: Run Edit Run fleet, 2026-11-17.
85
+
86
+ Before announcing `RER_READY`, `RER_OPEN` or the JSON `ready` event, managed
87
+ dev keeps its persona API check and opens the intended owner link in an isolated
88
+ headless browser through the public origin. It follows the fragment exchange,
89
+ cookies and server/client redirects to a 2xx page with visible usable controls,
90
+ without a busy/retry interstitial or loading state. The destination comes from
91
+ the application; no `/setup` path is assumed. Preview and demo also verify their
92
+ native owner entry, then issue a fresh single-use link for the owner.
93
+ Demo verifies that native entry before exchanging its persona dev key, preserving
94
+ the native entry authorization requirement. A front-door server permits routing
95
+ once its runtime can serve requests; registry readiness and ready announcements
96
+ still wait for the browser to verify the destination through that door.
97
+
98
+ This uses the checkout's locked Playwright and provisions its headless browser
99
+ on first use, as verification does. Owner readiness has a 60-second elapsed
100
+ deadline, including provisioning, browser launch and navigation. Set
101
+ `RER_OWNER_READY_TIMEOUT_MS` to positive integer milliseconds to change it.
102
+ Expiry exits 1 with `owner_entry_not_ready`, naming the entry and last destination
103
+ without credentials, for example: `Destination http://127.0.0.1:8787/workspace/start-here:
104
+ HTTP 503 (busy/retry interstitial)`. No ready event or open link is emitted.
105
+ An available persona API or health endpoint alone cannot establish that the
106
+ owner's page is ready. Inline recovery-script text is not mistaken for a visible
107
+ busy page.
108
+
84
109
  `rer dev` runs the local migration hook before starting the app and checking its
85
110
  owner prerequisites. The shared operator hook reads every SQL file in the seed's
86
111
  canonical `migrations/core` inventory, including changes pulled since the last
@@ -88,6 +113,22 @@ build, and prints the applied names. A failed migration stops startup with its
88
113
  captured error and `rer setup` guidance. `rer demo` uses the same inventory in
89
114
  its isolated state directory.
90
115
 
116
+ Signed: Run Edit Run fleet, 2026-11-17.
117
+
118
+ The shared operator adapter returns a named local prerequisite failure: the
119
+ field, found value and expected value. Secret settings report only set/unset.
120
+ This applies to dev and preview, including missing migration names, the durable
121
+ owner claim and the active owner. Legacy adapters returning false report their
122
+ `localPrerequisites` result.
123
+ Local operator mail requires `MAIL_PROVIDER=development`: some adopting seeds
124
+ select a real sender for hosted values even with local authentication enabled.
125
+ A hosted mail-off declaration (`none`, public settings and `mailOffSignIn`)
126
+ describes hosted behavior and does not establish a seed's local mail behavior.
127
+ Fresh setup refuses a hosted choice by field name and accepted value;
128
+ ordinary repeat `rer setup` repairs an already stored unsupported mail value to
129
+ `development`, preserving the owner, secrets and data. Hosted mail settings
130
+ remain in the deployment declaration and hosted environment.
131
+
91
132
  Successful terminal setup saves declared nonsecret installer answers in owned
92
133
  0600 storage under `.seed/installer`. A non-interactive repeat reuses those
93
134
  answers, with explicit flags or an answers file taking precedence. Runtime
@@ -100,6 +141,25 @@ For older installations without an answer record, a runtime selection outside
100
141
  the installer field's choices cannot replace an adapter-declared local choice.
101
142
  Explicit answers and recorded installer choices still undergo strict validation.
102
143
 
144
+ ## Browser prerequisites
145
+
146
+ Signed: Run Edit Run fleet, 2026-11-16.
147
+
148
+ `rer doctor` and `rer describe` inspect the checkout's Playwright registry
149
+ without launching or downloading a browser. Headless verification needs only
150
+ `chromium-headless-shell` when that Playwright pin provides it; older pins use
151
+ `chromium`. A checkout that also runs headed Chromium declares
152
+ `browser: { headless: false }` in its command adapter. That adds full Chromium
153
+ to verification's headless prerequisite. `rer run` also honors `--headed` and
154
+ `--debug` in the selected Playwright script or its forwarded arguments.
155
+
156
+ Missing executables are named with their use and one browser-only command
157
+ using the checkout's resolved Playwright CLI. Run that command from the checkout
158
+ root to acquire browsers without verification. `rer install` installs locked
159
+ dependencies without browsers. The first `rer verify` (or declared Playwright
160
+ `rer run`) downloads the required target; a headless-only checkout downloads
161
+ only the headless shell, using the pin's own platform and revision.
162
+
103
163
  ## Back up and restore this installation
104
164
 
105
165
  Use `rer export` / `rer import` to back up and restore this installation. This
@@ -109,6 +169,10 @@ restore has no door plan, reviewed fingerprint, reconciliation or Undo. Keep own
109
169
  Local `export --output FILE` and `import --input FILE --yes` use the Base
110
170
  portability implementation through the shared command runner and real Wrangler
111
171
  bindings. Seed adapters declare their database, buckets and archive policy.
172
+ The selected dispatcher supplies `@runeditrun/rer/portability` when it loads a
173
+ package adapter, including an explicitly invoked package CLI outside the
174
+ checkout. An older checkout package therefore cannot silently supply an older
175
+ archive worker. The seed's declared bindings and executable policy still apply.
112
176
  Export writes a new 0600 archive and reports its verified content hash, resource
113
177
  counts, exclusions and configuration names. Import applies migrations, verifies
114
178
  the archive and restores atomically into an empty destination. Stop dev or
@@ -119,6 +183,9 @@ destination refuses rows erased since. Erasure-fence refusals (`erased_row`,
119
183
  available only when the adapter declares complete resource coverage. Unsupported
120
184
  hosted export exits 2 before effects; unsupported import or transfer capability
121
185
  can refuse with exit 4.
186
+ Failed local transfers write their classified diagnostic into the private
187
+ capture and name its path. If capture could not be created or written, the
188
+ failure says so. Unexpected native messages, SQL and row values stay private.
122
189
 
123
190
  A first-party adapter may also declare `portability.hostedExport` as an argv
124
191
  array, for example `['node', 'scripts/export.mjs']`. With that declaration,
@@ -292,6 +359,36 @@ anything is built or uploaded. The seed owns what an installation does with mail
292
359
  off, and turning mail on later is a `rer deploy --set-secret` of the provider
293
360
  inputs the seed documents.
294
361
 
362
+ A seed can opt into a switchable public selector with one `deploy.json` edit:
363
+
364
+ ```json
365
+ {
366
+ "publicSettings": ["MAIL_PROVIDER"],
367
+ "vars": { "MAIL_PROVIDER": "none" },
368
+ "secrets": [
369
+ { "binding": "MAIL_PROVIDER", "environment": "MAIL_PROVIDER", "optional": true }
370
+ ]
371
+ }
372
+ ```
373
+
374
+ Merge these entries into the existing declaration, keeping its other settings
375
+ and credentials. Retain the same `MAIL_PROVIDER=none` default in Wrangler vars
376
+ and the managed spec's `publicVariableNames`; the selector stays public in the
377
+ managed artifact, outside its secret names. `rer check` accepts this explicit
378
+ public default plus optional transport and reports conflicting source defaults.
379
+ `rer doctor` names the supported declaration when a source overlap is refused.
380
+ Declarations without this combination keep their previous behavior.
381
+
382
+ Use `rer deploy --set-secret MAIL_PROVIDER=sendgrid --set-secret MAIL_API_KEY
383
+ --env-file deploy.env` with the seed's declared sender and credential inputs.
384
+ The existing name-only form still reads the declared environment mapping.
385
+ `NAME=VALUE` is accepted only for opted-in public settings; credentials still
386
+ come from the environment or an owned 0600 `--env-file` and remain masked.
387
+ `rer deploy --unset-secret MAIL_PROVIDER,MAIL_API_KEY` removes those overrides
388
+ and restores the declared public default in the same Worker version. A plain
389
+ deploy preserves a held override. These changes use the existing ownership,
390
+ grouped-version and recovery machinery and preserve the admitted owner.
391
+
295
392
  The adapter must apply that selection to the runtime as well as pass preflight.
296
393
  For example, the foundation declares optional `MAIL_PROVIDER` and `MAIL_FROM`
297
394
  environment-to-binding mappings in `deploy.json`, and makes `MAIL_API_KEY`
@@ -470,7 +567,19 @@ the local plan, while a real deployment validates the hosted identity before upl
470
567
 
471
568
  `--env-file` values are available in the command's preflight, custom hook and
472
569
  child build environment and are redacted; the caller environment is restored
473
- on success and failure. `--remove`, `--set-secret` and `--unset-secret` always go
570
+ on success and failure. If the caller already holds a non-empty
571
+ `CLOUDFLARE_API_TOKEN` (including a `rer business run --grant` child), any
572
+ `CLOUDFLARE_*` or `CF_*` key in `--env-file` is refused before provider calls.
573
+ The error names the file and key, never its value. Remove those keys from the
574
+ file and repeat the command. Without a caller token, file precedence is unchanged.
575
+
576
+ SIGTERM cancels provider requests, response reads, polling waits and owned child
577
+ processes, releases the deployment lock and retains deployment state for resume.
578
+ `rer deploy` exits 143 on SIGTERM (130 on SIGINT); repeat the command with fresh
579
+ credentials to resume. An unconfirmed provider create remains uncertain rather
580
+ than being repeated or adopted by name.
581
+
582
+ `--remove`, `--set-secret` and `--unset-secret` always go
474
583
  through the owner-account controller, without invoking the application's build
475
584
  or deploy hook. `--set-secret A,B` (or the flag repeated) changes several
476
585
  secrets in one Worker version or none, after checking that each is declared
@@ -644,6 +753,40 @@ On loopback, `rer preview` prints `RER_OPEN` for native owner entry.
644
753
  owner session in its isolated demo data. These native entry links work once,
645
754
  expire within 15 minutes and are never saved. Restarting retires them.
646
755
 
756
+ ## Business device credential storage
757
+
758
+ Business state lives in `$RER_BUSINESS_STATE_DIR` when set, otherwise in
759
+ `~/.rer/business`. Device credentials use the OS Keychain on macOS or Secret
760
+ Service on Linux by default; leaving `RER_BUSINESS_CREDENTIAL_DIR` unset preserves
761
+ that behavior.
762
+
763
+ Set `RER_BUSINESS_CREDENTIAL_DIR` to keep the device credential in an atomic
764
+ `0600` file in that directory instead. The directory must be caller-owned, mode
765
+ `0700`, and must not be a symbolic link; unsafe directories are refused. Filenames use a
766
+ digest derived from the platform origin and Business ID. Device secrets never
767
+ appear in filenames or storage diagnostics. With this variable set, device
768
+ credential operations never touch OS credential storage. There is no automatic
769
+ migration between stores: use the same selection to access an existing pairing.
770
+ All public Business commands use the selected backend when accessing device
771
+ credentials.
772
+
773
+ A sealed launcher must set both directories consistently for **every** Business
774
+ invocation, including the service process. Setting the state directory alone does
775
+ not select file credential storage. For a private, per-session pair of directories:
776
+
777
+ ```sh
778
+ umask 077
779
+ business_session_dir="$(mktemp -d)"
780
+ mkdir "$business_session_dir/state" "$business_session_dir/credentials"
781
+ export RER_BUSINESS_STATE_DIR="$business_session_dir/state"
782
+ export RER_BUSINESS_CREDENTIAL_DIR="$business_session_dir/credentials"
783
+ rer business connect --business ID
784
+ rer business status
785
+ ```
786
+
787
+ Keep both values available to subsequent commands and service invocations for
788
+ that session.
789
+
647
790
  ## Run your business demo
648
791
 
649
792
  ```sh
@@ -713,7 +856,9 @@ rer business run --grant GRANT_ID -- any-command 'argument with spaces'
713
856
  `cloudflare.token` in the Business MCP describes the exchange without returning a
714
857
  credential. Only the paired rer exchange receives a child token; the parent OAuth
715
858
  credential stays on the trusted server. The command gets `CLOUDFLARE_API_TOKEN`
716
- and `CLOUDFLARE_ACCOUNT_ID` in its environment. Cloudflare credential aliases from
859
+ and `CLOUDFLARE_ACCOUNT_ID` in its environment. The child also receives
860
+ `RER_BUSINESS_GRANT` set to the grant ID, so a queue or tool can recognise a
861
+ granted command. This marker contains only the ID, never the credential. Cloudflare credential aliases from
717
862
  the caller environment are removed. No shell is inserted and arguments after
718
863
  `--`, including help flags, are passed unchanged. Existing `run [--once]` continues
719
864
  its computer check-in behavior.
@@ -728,12 +873,35 @@ approved credential, never retries with broader or ambient access, and does not
728
873
  protect a process from its own deliberate credential loading.
729
874
 
730
875
  The child expires after at most 15 minutes, bounded also by the grant and the
731
- provider authorization. The wrapper interrupts a command at that expiry. It
732
- requests revocation after success, failure, signals or spawn failure; SIGKILL,
876
+ provider authorization. Before starting the command, stderr shows the child's
877
+ UTC credential expiry and minutes remaining, rounded up. The wrapper interrupts
878
+ a command at that expiry and reports that the credential expired, with
879
+ `run it again to resume` and the caller exit status. Invoke the command again to
880
+ obtain a new credential; the command's own behavior determines how work resumes.
881
+ The old credential is not extended or renewed.
882
+ Child exit codes and Unix terminating signals are preserved. At expiry the wrapper
883
+ sends SIGTERM: shell status 143 holds only for a command that exits on SIGTERM.
884
+ A process still running after the existing three-second grace is killed with
885
+ SIGKILL (shell status 137). A child that handles the signal keeps its own exit code. There is no separate synthetic
886
+ expiry failure code: the expiry message distinguishes it from a child failure. The wrapper requests revocation after success, failure,
887
+ signals or spawn failure; SIGKILL,
733
888
  crashes, network loss and lost acknowledgements may leave a token until server
734
- expiry. Child exit codes and Unix terminating signals are preserved. Cleanup has
889
+ expiry. Cleanup has
735
890
  its own stderr status, including **unconfirmed**, which is never called revoked.
736
891
  The safe lease ID in that status supports `rer business cleanup LEASE` to retry
737
892
  revocation and `rer business cleanup LEASE --status` to read its status. Cleanup
738
893
  needs the original pairing, but does not require the removed deploy action or an
739
894
  active grant. No child token is saved in state, OS storage, logs or MCP output.
895
+
896
+ Expiry guidance: Codex, 17 November 2026.
897
+
898
+ When the exchange refuses, the command never starts and the wrapper exits 1.
899
+ If Business names why, stderr shows one line: `Not started:` and Business's gap
900
+ sentence, then `The grant stays pending; nothing was issued.` for a pending
901
+ grant. When the refusal carries the Cloudflare permission catalogue's shape,
902
+ the line ends with its two counts only, for example
903
+ `catalogue: 93 rows, 7 mention Workers (see the audit row cloudflare.token.catalogue)`;
904
+ the rows themselves stay in that audit row. No other part of the refusal is
905
+ printed. Without a gap, the general refusal line names what to check in Business.
906
+
907
+ Signed: Run Edit Run fleet, 2026-11-17.
package/cli/archive.mjs CHANGED
@@ -3,6 +3,6 @@ import { createReadStream } from 'node:fs';
3
3
  import { diffArchives } from '../modules/portability/diff.mjs';
4
4
  import { invalid } from './errors.mjs';
5
5
  export async function archiveCommand(args,out) {
6
- if (args.length!==3 || args[0]!=='diff') throw invalid('Usage: rer archive diff BEFORE AFTER');
6
+ if (args.length!==3 || args[0]!=='diff') throw invalid('Usage: ~/.local/bin/rer archive diff BEFORE AFTER');
7
7
  const result=await diffArchives(Readable.toWeb(createReadStream(args[1])),Readable.toWeb(createReadStream(args[2]))); out.human(JSON.stringify(result,null,2)); return 0;
8
8
  }
package/cli/authoring.mjs CHANGED
@@ -4,7 +4,7 @@ import {refreshCopies, options as copyOptions} from '../edition-authoring/base-c
4
4
  import {refuse, invalid} from './errors.mjs';
5
5
 
6
6
  export function authoringCommand(options) {
7
- if (options.verb === 'refresh-base' && !options.ref) throw invalid('Provide --ref with the full immutable Base commit. Run rer refresh-base --help.');
7
+ if (options.verb === 'refresh-base' && !options.ref) throw invalid('Provide --ref with the full immutable Base commit. Run ~/.local/bin/rer refresh-base --help.');
8
8
  try {
9
9
  return options.verb === 'adopt-edition' ? adoptEdition(options.cwd) : refreshCopies(options.cwd, copyOptions([
10
10
  ...(options.editionMigration ? options.editionMigration.split(',').flatMap(id => ['--edition-migration', id]) : []),
@@ -9,8 +9,8 @@ import { dirname, join, relative } from 'node:path';
9
9
  import { RerError } from './errors.mjs';
10
10
  import { shared } from './shared.mjs';
11
11
 
12
- export const browserRepair = 'rer install';
13
- export const browserDownload = 'rer verify downloads them the first time it runs';
12
+ export const browserRepair = '~/.local/bin/rer install';
13
+ export const browserDownload = '~/.local/bin/rer verify downloads the required browser on first use; ~/.local/bin/rer install installs dependencies, not browsers';
14
14
 
15
15
  export function checkoutPlaywright(root, { required = true } = {}) {
16
16
  const require = createRequire(join(root, 'package.json'));
@@ -33,42 +33,57 @@ export function checkoutPlaywright(root, { required = true } = {}) {
33
33
  if (required) throw new RerError('browser_dependency_missing', `The checkout's Playwright is missing. Run ${browserRepair} to install its locked dependencies; verification requires playwright-core, @playwright/test or playwright.`, 3);
34
34
  }
35
35
 
36
- export async function browserDoctor(root) {
36
+ // Verification uses headless Chromium. A checkout that also needs headed
37
+ // Chromium declares commandAdapter.browser = { headless: false }.
38
+ export async function browserDoctor(root, { headless = true } = {}) {
37
39
  let resolved;
38
40
  try { resolved = checkoutPlaywright(root); }
39
41
  catch (error) { return { ok: false, issue: error instanceof RerError ? error.message : `The checkout's Playwright could not be inspected. Run ${browserRepair}.`, fix: browserRepair, executables: [] }; }
42
+ const shell = resolved.registry.findExecutable('chromium-headless-shell');
43
+ const names = headless && shell ? ['chromium-headless-shell'] : ['chromium', ...(shell ? ['chromium-headless-shell'] : [])];
40
44
  const executables = [];
41
- for (const name of ['chromium', 'chromium-headless-shell']) {
45
+ for (const name of names) {
42
46
  // Releases before the separate headless shell use the Chromium executable.
43
- const executable = resolved.registry.findExecutable(name);
44
- if (!executable && name === 'chromium-headless-shell') continue;
47
+ const executable = name === 'chromium-headless-shell' ? shell : resolved.registry.findExecutable(name);
45
48
  const path = executable?.executablePath();
46
49
  let ok = false;
47
50
  if (path) try { await access(path, process.platform === 'win32' ? constants.F_OK : constants.X_OK); ok = true; } catch {}
48
- executables.push({ name, ...(path ? { path } : {}), ok });
51
+ const reason = name === 'chromium-headless-shell' ? 'headless verification' : headless ? 'headless verification with this Playwright pin (no separate headless shell)' : 'declared headed browser use';
52
+ executables.push({ name, ...(path ? { path } : {}), ok, reason });
49
53
  }
50
54
  // Not yet downloaded is the normal state until a command needs the browser.
51
- const missing = executables.filter(executable => !executable.ok).map(executable => executable.name);
52
- return { ok: true, package: resolved.name, executables, ...(missing.length ? { note: `Playwright browsers not downloaded yet: ${missing.join(', ')}; ${browserDownload}.` } : {}) };
55
+ const missing = executables.filter(executable => !executable.ok);
56
+ const target = headless && shell ? 'chromium-headless-shell' : 'chromium';
57
+ const command = browserInstallCommand(root, resolved.cli, target);
58
+ return { ok: true, package: resolved.name, headless, executables, ...(missing.length ? { command, note: `Playwright browser not downloaded yet: ${missing.map(({ name, reason }) => `${name} (needed for ${reason})`).join(', ')}. Browser-only install: ${command}; ${browserDownload}.` } : {}) };
53
59
  }
54
60
 
55
- export async function ensureChromium(root, store, signal, { required = true } = {}) {
61
+ // Quote project-relative paths for a command copied into the checkout's shell.
62
+ function browserInstallCommand(root, cli, target) {
63
+ const path = relative(root, cli).split('\\').join('/');
64
+ const quoted = /^[a-zA-Z0-9_./@-]+$/.test(path) ? path : process.platform === 'win32' ? `"${path}"` : "'" + path.replaceAll("'", "'\\''") + "'";
65
+ return `pnpm exec node ${quoted} install ${target}`;
66
+ }
67
+
68
+ export async function ensureChromium(root, store, signal, { required = true, ...use } = {}) {
56
69
  // A first-party adapter without browser dependencies remains valid.
57
70
  // Verification requires Playwright; rer run provisions it when declared.
58
71
  const resolved = checkoutPlaywright(root, { required });
59
72
  if (!resolved) return;
60
- if (await browsersPresent(root)) return;
61
- const { cli } = resolved;
73
+ const browser = await browserDoctor(root, use);
74
+ if (!browser.note) return;
75
+ const target = browser.headless && resolved.registry.findExecutable('chromium-headless-shell') ? 'chromium-headless-shell' : 'chromium';
62
76
  const { dependencyEnvironment } = await shared('dependency-environment.mjs');
63
77
  const env = dependencyEnvironment();
64
78
  if (process.env.PLAYWRIGHT_BROWSERS_PATH !== undefined) env.PLAYWRIGHT_BROWSERS_PATH = process.env.PLAYWRIGHT_BROWSERS_PATH;
65
- await store.run('Installing Chromium and its headless shell from the checkout’s Playwright', 'pnpm', ['exec', 'node', cli, 'install', 'chromium'], { cwd: root, signal, env, display: `pnpm exec node ${relative(root, cli)} install chromium` });
66
- const absent = (await browserDoctor(root)).executables.filter(executable => !executable.ok).map(executable => executable.name);
67
- if (absent.length) throw new RerError('browser_install_incomplete', `The checkout's Playwright did not install every browser it pins (missing: ${absent.join(', ')}). Run the same command again; it retries the download.`, 3);
79
+ await store.run(`Installing ${target} from the checkout’s Playwright`, 'pnpm', ['exec', 'node', resolved.cli, 'install', target], { cwd: root, signal, env, display: browser.command });
80
+ const after = await browserDoctor(root, use);
81
+ const absent = after.executables.filter(executable => !executable.ok).map(executable => executable.name);
82
+ if (absent.length) throw new RerError('browser_install_incomplete', `The checkout's Playwright did not install the required browser (missing: ${absent.join(', ')}). Run ${browser.command} again; it retries the download.`, 3);
68
83
  }
69
84
 
70
- // Whether every browser the checkout's Playwright pins is on disk.
71
- export async function browsersPresent(root) {
72
- const browser = await browserDoctor(root).catch(() => undefined);
85
+ // Whether the executables needed by this checkout's declared use are on disk.
86
+ export async function browsersPresent(root, use) {
87
+ const browser = await browserDoctor(root, use).catch(() => undefined);
73
88
  return Boolean(browser?.ok && !browser.note);
74
89
  }
@@ -3,7 +3,7 @@ import { rows, families } from './agent-table.mjs';
3
3
  const verb = name => name.split(' ')[1];
4
4
  const exits = `Exits 0 done, 1 refused or failed (the server's message is printed), 2 usage, 3 not built yet, 75 still working when\n--timeout ran out. A verb the owner has not granted this computer names where the owner grants it: Business, under Computers.`;
5
5
  const flags = `
6
- --app ID, --installation-id ID The installed app (from rer business installations list)
6
+ --app ID, --installation-id ID The installed app (from ~/.local/bin/rer business installations list)
7
7
  --FLAG VALUE Any other flag is an argument of the tool: --change-id, --preparation-id,
8
8
  --domain-id, --request-key, --method, --surface, --hostname, --public-path
9
9
  (kebab-case becomes snake_case). A value that starts with { or [ is JSON;
@@ -15,12 +15,12 @@ ${exits}`;
15
15
 
16
16
  /** The lines the advanced-commands help adds for the agent verbs. */
17
17
  export const agentUsage = `
18
- Agent verbs (Usage: rer business FAMILY VERB [--flags] [--json])
19
- Act on the company's installed apps from this computer, with no browser. Needs rer business connect first.
18
+ Agent verbs (Usage: ~/.local/bin/rer business FAMILY VERB [--flags] [--json])
19
+ Act on the company's installed apps from this computer, with no browser. Needs ~/.local/bin/rer business connect first.
20
20
  ${Object.entries(rows).map(([name, row]) => ` ${name.padEnd(24)} ${row.about}`).join('\n')}
21
21
  tools List the tools the Business server offers
22
22
  call TOOL [--flags] Call a tool that has no verb of its own yet
23
- mcp A local stdio MCP server for Claude Code or Codex: add \`rer business mcp\` as a server
23
+ mcp A local stdio MCP server for Claude Code or Codex: add \`~/.local/bin/rer business mcp\` as a server
24
24
  and the agent never handles a token
25
25
  change request --app ID "WHAT TO CHANGE" [--wait] [--publish]
26
26
  --wait follows the change to its preview; --publish also publishes it and waits for live
@@ -29,25 +29,25 @@ ${exits}
29
29
 
30
30
  const family = name => Object.entries(rows).filter(([key]) => key.split(' ')[0] === name)
31
31
  .map(([key, row]) => ` ${verb(key).padEnd(22)} ${row.about}`).join('\n');
32
- const help = name => `Usage: rer business ${name} VERB [--flags] [--json]
32
+ const help = name => `Usage: ~/.local/bin/rer business ${name} VERB [--flags] [--json]
33
33
  ${family(name)}
34
34
  ${flags}
35
35
  `;
36
36
 
37
37
  export const agentHelp = {
38
38
  ...Object.fromEntries(families.map(name => [name, help(name)])),
39
- tools: `Usage: rer business tools [--json]
40
- List the tools the Business server offers: name and a one-line description. Use rer business call TOOL to call one that has no verb.
39
+ tools: `Usage: ~/.local/bin/rer business tools [--json]
40
+ List the tools the Business server offers: name and a one-line description. Use ~/.local/bin/rer business call TOOL to call one that has no verb.
41
41
  `,
42
- call: `Usage: rer business call TOOL [--flag VALUE ...] [--args JSON] [--json]
42
+ call: `Usage: ~/.local/bin/rer business call TOOL [--flag VALUE ...] [--args JSON] [--json]
43
43
  Call any Business tool by name, such as installation.status. Flags become the tool's arguments (kebab-case to snake_case).
44
44
  Exits 0 done, 1 refused or failed, 3 not built yet.
45
45
  `,
46
- mcp: `Usage: rer business mcp
46
+ mcp: `Usage: ~/.local/bin/rer business mcp
47
47
  Run a local MCP server on stdin and stdout (newline-delimited JSON-RPC, revision 2025-11-25) that forwards to the Business
48
48
  MCP. It keeps the short-lived bearer fresh from this computer's pairing, so the agent that starts it never handles a token.
49
- Claude Code: claude mcp add business -- rer business mcp
49
+ Claude Code: claude mcp add business -- ~/.local/bin/rer business mcp
50
50
  Codex: add [mcp_servers.business] with command = "rer" and args = ["business", "mcp"]
51
- Needs rer business connect first. Only protocol messages go to stdout; diagnostics go to stderr.
51
+ Needs ~/.local/bin/rer business connect first. Only protocol messages go to stdout; diagnostics go to stderr.
52
52
  `,
53
53
  };
@@ -8,6 +8,7 @@ import { parseArguments, place, missing, Usage } from './agent-args.mjs';
8
8
  import { plain, refusalText, clean } from './agent-output.mjs';
9
9
  import { waitFor, failedState, stateName, exitStillWaiting } from './agent-wait.mjs';
10
10
  import { agentUsage } from './agent-help.mjs';
11
+ import { maskDeviceText } from './run-mask.mjs';
11
12
 
12
13
  export const exitNotBuilt = 3;
13
14
 
@@ -62,7 +63,7 @@ const waiters = { change, update };
62
63
 
63
64
  async function work(row, parsed, session, out) {
64
65
  const args = place(row, parsed), absent = missing(row, args), { control } = parsed;
65
- if (absent.length) throw new Usage(`${row.tool} needs ${absent.map(name => `--${name.replaceAll('_', '-')}`).join(', ')}. Run rer business ${row.name.split(' ')[0]} --help.`);
66
+ if (absent.length) throw new Usage(`${row.tool} needs ${absent.map(name => `--${name.replaceAll('_', '-')}`).join(', ')}. Run ~/.local/bin/rer business ${row.name.split(' ')[0]} --help.`);
66
67
  for (const flag of ['wait', 'publish']) {
67
68
  if (control[flag] && !(row.wait && (flag === 'wait' || row.tool.startsWith('change.')))) throw new Usage(`${row.name} does not take --${flag}.`);
68
69
  }
@@ -73,8 +74,8 @@ async function work(row, parsed, session, out) {
73
74
  // Lines for a person go to stdout; with --json only the final structuredContent does, and progress goes to stderr.
74
75
  function output(json) {
75
76
  return {
76
- line: text => (json ? process.stderr : process.stdout).write(text + '\n'),
77
- result: (tool, data) => { if (json) process.stdout.write(JSON.stringify(data) + '\n'); else for (const line of plain(tool, data)) process.stdout.write(line + '\n'); },
77
+ line: text => (json ? process.stderr : process.stdout).write(maskDeviceText(text) + '\n'),
78
+ result: (tool, data) => { if (json) process.stdout.write(maskDeviceText(JSON.stringify(data)) + '\n'); else for (const line of plain(tool, data)) process.stdout.write(line + '\n'); },
78
79
  };
79
80
  }
80
81
 
@@ -88,7 +89,7 @@ async function listTools(session, json) {
88
89
  cursor = response.result?.nextCursor;
89
90
  if (!cursor) break;
90
91
  }
91
- if (json) process.stdout.write(JSON.stringify({ tools }) + '\n');
92
+ if (json) process.stdout.write(maskDeviceText(JSON.stringify({ tools })) + '\n');
92
93
  else for (const tool of tools) process.stdout.write(`${clean(tool.name, 80)} ${clean(String(tool.description ?? '').split('\n')[0], 160)}`.trimEnd() + '\n');
93
94
  }
94
95
 
@@ -100,11 +101,11 @@ export async function agentCommand(argv) {
100
101
  let row, tail = rest;
101
102
  if (first === 'tools') { row = { name: 'tools' }; tail = [second, ...rest].filter(item => item !== undefined); }
102
103
  else if (first === 'call') {
103
- if (!/^[a-z][a-z0-9_.]{0,80}$/.test(second ?? '')) return usage('Name the tool: rer business call TOOL [--flag VALUE].');
104
+ if (!/^[a-z][a-z0-9_.]{0,80}$/.test(second ?? '')) return usage('Name the tool: ~/.local/bin/rer business call TOOL [--flag VALUE].');
104
105
  row = { name: `call ${second}`, tool: second };
105
106
  } else {
106
107
  row = rows[`${first} ${second}`] && { name: `${first} ${second}`, ...rows[`${first} ${second}`] };
107
- if (!row) return usage(`Unknown command: rer business ${first}${second ? ` ${clean(second, 40)}` : ''}.`);
108
+ if (!row) return usage(`Unknown command: ~/.local/bin/rer business ${first}${second ? ` ${clean(second, 40)}` : ''}.`);
108
109
  }
109
110
  let parsed;
110
111
  try { parsed = await parseArguments(tail); } catch (error) { if (error instanceof Usage) return usage(error.message); throw error; }
@@ -121,11 +122,11 @@ export async function agentCommand(argv) {
121
122
  if (error instanceof Usage) return usage(error.message);
122
123
  if (error instanceof Refused) {
123
124
  const text = refusalText(error.data, ownerLink(state));
124
- if (parsed.control.json) process.stdout.write(JSON.stringify(error.data ?? {}) + '\n');
125
+ if (parsed.control.json) process.stdout.write(maskDeviceText(JSON.stringify(error.data ?? {})) + '\n');
125
126
  process.stderr.write(text + '\n');
126
127
  return error.data?.status === 'not_built' ? exitNotBuilt : 1;
127
128
  }
128
- if (error.data && parsed.control.json) process.stdout.write(JSON.stringify(error.data) + '\n');
129
+ if (error.data && parsed.control.json) process.stdout.write(maskDeviceText(JSON.stringify(error.data)) + '\n');
129
130
  process.stderr.write(describe(error) + '\n');
130
131
  return error.exitCode ?? 1;
131
132
  }
@@ -24,9 +24,10 @@ export class ApiError extends Error {
24
24
  }
25
25
  }
26
26
 
27
- async function refusal(response, quiet = false) {
27
+ async function refusal(response, quiet = false, detail) {
28
28
  let text = '';
29
- try { text = (await response.text()).slice(0, 4096); } catch { /* The status alone is the reason. */ }
29
+ // A caller that reads its own detail gets the platform's whole error envelope (at most 64 KB); others read 4 KB.
30
+ try { text = (await response.text()).slice(0, detail ? 65_536 : 4096); } catch { /* The status alone is the reason. */ }
30
31
  let body = null;
31
32
  try { body = JSON.parse(text); } catch { /* A plain-text reason is used as it is. */ }
32
33
  const line = value => typeof value === 'string' && value.trim() ? redact(value).replace(/\s+/g, ' ').trim().slice(0, 300) : null;
@@ -35,8 +36,11 @@ async function refusal(response, quiet = false) {
35
36
  const code = typeof body?.code === 'string' && /^[a-z][a-z0-9_]{0,79}$/.test(body.code) ? body.code : null;
36
37
  // Pairing responses can echo secrets, including the short user code. Only
37
38
  // the bounded machine code is needed by that flow, never server prose.
38
- return new ApiError(response.status, quiet ? null : reason, quiet ? null : requestId, code,
39
+ const error = new ApiError(response.status, quiet ? null : reason, quiet ? null : requestId, code,
39
40
  quiet ? {} : { state: body?.state === 'waiting_for_owner' ? body.state : undefined, link: line(body?.link) });
41
+ // Only the fields the caller picks and bounds travel with the error, never the body itself.
42
+ if (detail && body && typeof body === 'object' && !Array.isArray(body)) error.detail = detail(body);
43
+ return error;
40
44
  }
41
45
 
42
46
  const network = {
@@ -68,12 +72,12 @@ export class Api {
68
72
  || !Number.isFinite(Date.parse(result.expires_at)) || Date.parse(result.expires_at) <= Date.now()) throw Error('Business server returned an invalid scoped bearer.');
69
73
  return result;
70
74
  }
71
- async post(path, body, { token = this.credential, signal, timeout = 30_000, headers = {}, withStatus = false, quiet = false } = {}) {
72
- return this.request('POST', path, body, { token, signal, timeout, headers, withStatus, quiet });
75
+ async post(path, body, { token = this.credential, signal, timeout = 30_000, headers = {}, withStatus = false, quiet = false, detail } = {}) {
76
+ return this.request('POST', path, body, { token, signal, timeout, headers, withStatus, quiet, detail });
73
77
  }
74
78
  async get(path) { return this.request('GET', path); }
75
79
  async delete(path) { return this.request('DELETE', path); }
76
- async request(method, path, body, { token = this.credential, signal, timeout = 30_000, headers = {}, withStatus = false, quiet = false } = {}) {
80
+ async request(method, path, body, { token = this.credential, signal, timeout = 30_000, headers = {}, withStatus = false, quiet = false, detail } = {}) {
77
81
  if (!path.startsWith('/api/business/') || path.includes('..') || path.includes('?') || path.includes('#')) throw Error('Invalid Business route.');
78
82
  let response;
79
83
  try {
@@ -83,7 +87,7 @@ export class Api {
83
87
  ...(body === undefined ? {} : { body: JSON.stringify(body) }), signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(timeout)]) : AbortSignal.timeout(timeout),
84
88
  });
85
89
  } catch (error) { if (signal?.aborted) throw signal.reason; throw unreachable(this.origin, error); }
86
- if (!response.ok) throw await refusal(response, quiet);
90
+ if (!response.ok) throw await refusal(response, quiet, detail);
87
91
  // Successful bodies are untrusted: callers validate them and print only fields they template.
88
92
  if (response.status === 202 && response.headers.get('content-length') === '0' || response.status === 204) return null;
89
93
  const text = await response.text();
@@ -1,5 +1,6 @@
1
1
  import { Api } from './api.mjs';
2
2
  import { createCredentialStore } from './keychain.mjs';
3
+ import { credentialLocation } from './credential-file.mjs';
3
4
  import { deviceCredentialHandle, loadState } from './state.mjs';
4
5
  import { localCause } from './errors.mjs';
5
6
  import { carryCheckouts, firstParty, writeCarry } from './carry-files.mjs';
@@ -31,10 +32,10 @@ function warning(origin, error, checkout, report = true) {
31
32
  const reason = error.status ? `the server refused the request (HTTP ${error.status})`
32
33
  : error.name === 'TimeoutError' || error.name === 'AbortError' ? 'the server did not answer within 5 seconds'
33
34
  : error.message?.startsWith('Could not reach the Business server at ') ? 'the server is unreachable'
34
- : error.message === 'credential unavailable' ? 'the Business credential is unavailable in OS credential storage'
35
+ : error.message === 'credential unavailable' ? `the Business credential is unavailable in ${credentialLocation()}`
35
36
  : error.preparation ? error.message
36
- : localCause(error) ?? (['the response names another Business', 'the Business profile is invalid', 'the checkout is not first-party', 'the carry path is linked or not a regular file', 'the existing file is not a carry for this paired Business', 'the carry registry is invalid', 'the checkout is not set up yet: run rer setup'].includes(error.message) ? error.message : 'the Business profile could not be refreshed');
37
- const step = error.code === 'ENOENT' ? ' Open the app with rer dev --cwd FOLDER, then run business next again.' : '';
37
+ : localCause(error) ?? (['the response names another Business', 'the Business profile is invalid', 'the checkout is not first-party', 'the carry path is linked or not a regular file', 'the existing file is not a carry for this paired Business', 'the carry registry is invalid', 'the checkout is not set up yet: run ~/.local/bin/rer setup'].includes(error.message) ? error.message : 'the Business profile could not be refreshed');
38
+ const step = error.code === 'ENOENT' ? ' Open the app with ~/.local/bin/rer dev --cwd FOLDER, then run business next again.' : '';
38
39
  const text = `Business carry at ${origin}${checkout ? ` for ${JSON.stringify(checkout)}` : ''}: ${reason}; keeping any local carry.${step}\n`;
39
40
  if (report) process.stderr.write(text);
40
41
  return text;
@@ -100,7 +100,7 @@ export async function applyChoices(api, state, { reconnecting = false } = {}) {
100
100
  : `No local app carry files changed for ${JSON.stringify(carried.name)}.\n`);
101
101
  for (const checkout of carried.unchanged) process.stdout.write(`Already current: ${join(checkout, '.rer/local/business.json')}\n`);
102
102
  if (carried.failed) process.stdout.write(`${carried.failed} local app carry ${carried.failed === 1 ? 'file could' : 'files could'} not be refreshed; see the carry warnings.\n`);
103
- if (!count && !carried.unchanged.length && !carried.failed) process.stdout.write(`No local apps were found. Run ${businessCommand('next')} in the folder where rer list shows your apps.\n`);
103
+ if (!count && !carried.unchanged.length && !carried.failed) process.stdout.write(`No local apps were found. Run ${businessCommand('next')} in the folder where ~/.local/bin/rer list shows your apps.\n`);
104
104
  }
105
105
  return { applied: lines.length, serviceInstalled };
106
106
  }