raycast-harness 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. package/CHANGELOG.md +274 -0
  2. package/LICENSE +201 -0
  3. package/NOTICE +24 -0
  4. package/README.md +84 -2
  5. package/bin/rx.mjs +4 -0
  6. package/docs/applicability.md +35 -0
  7. package/docs/check-classes.md +70 -0
  8. package/docs/commands.md +270 -0
  9. package/docs/guide.md +305 -0
  10. package/eslint-plugin/index.mjs +52 -0
  11. package/eslint-plugin/lib/shortcut-ast.mjs +146 -0
  12. package/eslint-plugin/rules/copy-error-pairing.mjs +144 -0
  13. package/eslint-plugin/rules/no-ambiguous-shortcut.mjs +78 -0
  14. package/eslint-plugin/rules/no-multiline-emptyview-description.mjs +120 -0
  15. package/eslint-plugin/rules/no-toast-hide-in-cleanup.mjs +89 -0
  16. package/package.json +61 -4
  17. package/schema/preset.schema.json +215 -0
  18. package/src/api-diff/compare.mjs +247 -0
  19. package/src/args.mjs +254 -0
  20. package/src/attest.mjs +249 -0
  21. package/src/audit/artifacts.mjs +99 -0
  22. package/src/audit/entries.mjs +109 -0
  23. package/src/audit/evaluate.mjs +168 -0
  24. package/src/audit/greptile.mjs +349 -0
  25. package/src/audit/protected-paths.mjs +185 -0
  26. package/src/audit/publish-command.mjs +278 -0
  27. package/src/audit/step.mjs +51 -0
  28. package/src/binding.mjs +155 -0
  29. package/src/changelog/parse.mjs +106 -0
  30. package/src/cli.mjs +306 -0
  31. package/src/command-execution.mjs +141 -0
  32. package/src/commands/api-diff.mjs +267 -0
  33. package/src/commands/api-floor.mjs +186 -0
  34. package/src/commands/audit.mjs +430 -0
  35. package/src/commands/changelog.mjs +212 -0
  36. package/src/commands/commands.mjs +43 -0
  37. package/src/commands/contributions.mjs +276 -0
  38. package/src/commands/doctor.mjs +199 -0
  39. package/src/commands/gates.mjs +404 -0
  40. package/src/commands/greptile.mjs +474 -0
  41. package/src/commands/guard.mjs +374 -0
  42. package/src/commands/holdout.mjs +444 -0
  43. package/src/commands/judge.mjs +245 -0
  44. package/src/commands/png.mjs +253 -0
  45. package/src/commands/pr.mjs +389 -0
  46. package/src/commands/preflight.mjs +54 -0
  47. package/src/commands/preset.mjs +219 -0
  48. package/src/commands/publication.mjs +78 -0
  49. package/src/commands/scan.mjs +218 -0
  50. package/src/commands/shortcuts.mjs +285 -0
  51. package/src/commands/stale.mjs +279 -0
  52. package/src/errors.mjs +51 -0
  53. package/src/exec.mjs +78 -0
  54. package/src/fingerprint.mjs +197 -0
  55. package/src/gh.mjs +60 -0
  56. package/src/git.mjs +35 -0
  57. package/src/greptile/compare.mjs +194 -0
  58. package/src/greptile/rounds.mjs +111 -0
  59. package/src/greptile/rules.mjs +250 -0
  60. package/src/greptile/update.mjs +183 -0
  61. package/src/judge/decisions/changelog-user-visible.json +77 -0
  62. package/src/judge/decisions/needs-code.json +76 -0
  63. package/src/judge/decisions/png-provenance.json +117 -0
  64. package/src/judge/decisions/review-finding-triage.json +81 -0
  65. package/src/judge/decisions.mjs +94 -0
  66. package/src/judge/providers.mjs +215 -0
  67. package/src/judge/transport.mjs +41 -0
  68. package/src/output.mjs +131 -0
  69. package/src/payload.mjs +103 -0
  70. package/src/png.mjs +230 -0
  71. package/src/pr/body.mjs +133 -0
  72. package/src/pr/transport.mjs +135 -0
  73. package/src/preflight/catalog.mjs +74 -0
  74. package/src/preflight/checks.mjs +850 -0
  75. package/src/preflight/context.mjs +155 -0
  76. package/src/preflight/gitignore.mjs +183 -0
  77. package/src/preflight/lexer.mjs +101 -0
  78. package/src/preflight/markdown.mjs +246 -0
  79. package/src/preset/applies.mjs +130 -0
  80. package/src/preset/load.mjs +110 -0
  81. package/src/preset/schema.mjs +115 -0
  82. package/src/publication.mjs +101 -0
  83. package/src/publish-tag.mjs +32 -0
  84. package/src/published-copy.mjs +141 -0
  85. package/src/root.mjs +50 -0
  86. package/src/rules/greptile/SOURCE.json +8 -0
  87. package/src/rules/greptile/config.json +433 -0
  88. package/src/rules/greptile/files.json +87 -0
  89. package/src/rules/greptile/rules.md +38 -0
  90. package/src/rules/store.json +35 -0
  91. package/src/shortcuts/scan.mjs +518 -0
  92. package/src/shortcuts/table.mjs +167 -0
  93. package/src/state.mjs +91 -0
  94. package/src/upstream.mjs +284 -0
  95. package/src/util.mjs +22 -0
  96. package/src/verdict.mjs +83 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,274 @@
1
+ # Changelog
2
+
3
+ ## Unreleased
4
+
5
+ - Preflight reads every `.gitignore` the extension ships, nested ones included, each relative to
6
+ its own directory, as the fork-side `git add` does. A nested `!greptile.json` can no longer let
7
+ a review config pass `nested-review-config`, and a file a nested `.gitignore` drops is no longer
8
+ reported as shipping. `readme-links` now requires each target to ship, so a link into `.github/`
9
+ or an ignored file FAILs and names the reason.
10
+ - A Greptile rule that preflight covers mechanically keeps that exemption only while its text and
11
+ scope match the digest the mapping was reviewed against (`GREPTILE_MECHANICAL_RULES`). After
12
+ `rx greptile update` changes such a rule, the audit requires a judgment entry for it again.
13
+ - `rx holdout out` stops with ERROR `holdout-tracked`, before writing an inventory or moving a
14
+ file, when git cannot read the index; before, a corrupt index made every path look untracked.
15
+ `rx holdout out`, `rx pr files --preset` and `rx stale --preset` validate the whole preset
16
+ against its schema, so a mistyped key is ERROR `input` instead of a silent default.
17
+ - The guard treats `gh pr --repo o/r ready 42`, `-R o/r` and any other flag between `pr` and
18
+ `ready` as marking a PR ready, and blocks it.
19
+ - `rx pr files` reports ERROR `github` for a files row with no `filename` string, or with a
20
+ rename source that is malformed or missing on a `renamed` row, instead of skipping the row and
21
+ passing.
22
+ - Chris's 2026-11-03 file ruling (`AGENTS.md`, `CONCEPTS.md`, `CLAUDE.md` and `HANDOFF.md`
23
+ never ship) works through a guarded publish. The plugin preset holds them out with
24
+ `rx holdout`, and `holdout-tracked` names its fix, bound to the root. The fix runs
25
+ `git -C <root> rm --cached -- <path>`, lists the path in that checkout's `.gitignore`, and runs
26
+ `rx holdout in --root <root>` before `rx holdout out` again with the same arguments. The restore
27
+ is needed because the untracked entries still move when the check FAILs. A cross-device holdout
28
+ move that fails partway removes its partial copy, so the copy no longer blocks every later `out`
29
+ unless that removal fails too. A copy whose source could not be removed stays in the inventory
30
+ without counting as moved. `rx stale --preset` (and `rx gates`, which now passes its preset to
31
+ stale) classifies a published file the preset's `holdout.localOnly` lists and the local tree
32
+ lacks as `REMOVE` (`stale-remove`, WARN) instead of the `ONLY-PUB` FAIL. `rx audit record`
33
+ accepts the disposition `remove-published` (`{ path, localHash: "absent", baseline }`) for those
34
+ rows only, and `rx guard` recomputes the same rule. `rx pr files` reports each file's GitHub
35
+ status (`data.files: [{ path, status, previous }]`, the path list kept as `data.paths`), and
36
+ with `--preset` its `pr-local-only` check FAILs when a local-only file is added, modified or
37
+ renamed in rather than removed.
38
+ - Synced with the live skills plugin: the published-copy comparison has a test for a file changed
39
+ inside an already-published directory with an unchanged file list (ported from the live
40
+ `preflight.test.mjs`), and `docs/check-classes.md` no longer lists `AGENTS.md` as a file an
41
+ owner ships on purpose (Chris's 2026-11-03 ruling: `AGENTS.md` and `CONCEPTS.md` stay in the
42
+ mirror, listed in the extension's `.gitignore`).
43
+ - Published-copy access is one scoped operation (`src/published-copy.mjs` `withPublishedCopy`):
44
+ the service owns cache detection, the upstream lock for the whole read and exact-baseline
45
+ validation, and `stale`, `preflight`, `png`, `changelog`, `contributions`, `gates` and
46
+ `audit record` read through it. `repo/stale/baseline.json` is `{ name, published, baseline, at }`
47
+ with no cache path (an older file with one still reads). An external `--published` is neither
48
+ locked nor refreshed, `changelog --published` inside the cache is read under the lock, and
49
+ `gates` reports `ERROR github` when the cache moved between `stale` and `preflight`.
50
+ - One completion kernel (`src/command-execution.mjs`) is shared by the dispatcher and by the
51
+ in-process steps of `rx gates` and `rx audit record`: results recorded before a throw, silence
52
+ as `ERROR protocol` and the conversion of thrown errors are defined once. Two existing
53
+ differences stay explicit options (only the dispatcher logs an unexpected error's stack and
54
+ contains a failure to record an ERROR). No output, verdict or exit code changes.
55
+ - `rx gates` stamps the receipt with exactly the Greptile rules snapshot its `greptile-rules`
56
+ step reported. A final check, `gates-rules-changed`, runs immediately before the receipt is
57
+ written and FAILs with no receipt when another `rx greptile update` installed a copy while gates
58
+ ran. The step has a 30-second deadline: when it expires gates WARNs, installs nothing, kills the
59
+ pending `gh` child (the 1Password `op plugin run` fallback included) and continues on the copy in
60
+ use. Any request still in flight when the step settles, for any reason, is canceled too. The process runner and GitHub transport accept an optional AbortSignal for this. When the
61
+ receipt's rules are not the rules in use, `rx guard` and `rx audit show` prescribe "run rx gates,
62
+ then rx audit record".
63
+ - `rx gates` keeps the Greptile rules current as its first step, `greptile-rules`, with the same
64
+ check-and-update as `rx greptile update`; offline, or when the live rules fail validation, it
65
+ WARNs and continues on the copy in use. The receipt records the rules it ran under
66
+ (`greptileRules`), and a receipt written before this field is not current. `rx audit record`
67
+ refuses a receipt written under other Greptile rules, and `rx guard` and `rx audit show`
68
+ require the receipt, the audit and the rules in use to agree, naming the one that differs.
69
+ - `rx audit record` judges against one snapshot of the Greptile rules taken at the start, and
70
+ writes nothing (`ERROR audit-greptile-rules`) if an `rx greptile update` lands mid-recording.
71
+ `update --dest` restores every file it attempted, including one whose write failed after
72
+ truncating it, verifies each restored file byte for byte, and accepts an older checkout whose
73
+ `SOURCE.json` has no `committed`. In preflight, a package that `src/` appears to import at runtime
74
+ but that is listed only in `devDependencies` is a heuristic WARN, and a published menu-bar-only
75
+ extension without screenshots is a WARN unless its published copy had screenshots and this
76
+ change removes them all.
77
+ - An audit is bound to the Greptile rules it judged: `rx audit record` stores
78
+ `greptileRules { repo, sha, digest }`, and `rx guard` and `rx audit show` block when the rules
79
+ in use differ, so a rule whose text changed cannot reuse an old judgment. Rule copies are
80
+ ordered by upstream commit date (`SOURCE.json` `committed`), must name `raycast/extensions`
81
+ and pass a full schema check; `rx greptile update` WARNs when its copy is not the one in use,
82
+ and `update --dest` writes all or nothing. Preflight `screenshots` covers menu-bar commands,
83
+ `unused-dependencies` FAILs a runtime import of a package listed only in `devDependencies`, and
84
+ `nested-review-config` checks every depth of the payload. Rules that preflight covers only in part
85
+ are judgment rules too: the audit requires 55 Greptile judgment entries.
86
+ - Greptile rules stay current. `rx greptile outdated` (formerly `drift`) says whether the rules
87
+ in use match the last commit on `raycast/extensions` main that touched `.greptile/`, usually in
88
+ one request. `rx greptile update` fetches the live rules, validates them and writes them
89
+ atomically to `~/.cache/raycast-harness/greptile/rules/`; every reader uses the newest valid
90
+ copy that is not older than the one shipped with rx. `update --dest <checkout>` refreshes a
91
+ maintainer checkout's shipped copy. `rx doctor` adds a report-only `greptile-rules` check: PASS
92
+ current, WARN out of date, or WARN could not check.
93
+ - The shipped Greptile rules are refreshed to `raycast/extensions` main `b6bdcb1` (58 rules: 6
94
+ new, 19 changed). New core preflight check `nested-review-config` (Greptile
95
+ `no-nested-review-config`, high), split out of the preset-class `agent-scaffolding`, which now
96
+ only WARNs. `platforms` FAILs a missing field (`platforms-field`), or WARNs when the published
97
+ copy lacks it too. Four new audit judgment rules (40 in total). Every shipped rule is bound to a
98
+ preflight check or listed as judgment (a test enforces it), and a rule in the rules in use that
99
+ this release has not classified is a required, blocking audit entry.
100
+ - `--format md` escapes block syntax and GitHub-flavored autolinks as well as inline syntax, so
101
+ a detail such as `+ added.d.ts`, `- removed.d.ts`, `# note`, `1. item`, `&copy;`, a bare URL,
102
+ a `www.` address or an email address renders as literal text. `rx publication record` needs no
103
+ extension: it records into the git repository containing `--root` or the working directory,
104
+ including a multi-extension checkout root, and a missing git is reported as such. The plugin
105
+ runner records a publication without loading the registry or reaching the network; when rx's
106
+ bytes are not on the machine it exits 2 and says the record was not written.
107
+ - Every command takes `--format text|json|md`. `--json` stays as an exact alias of
108
+ `--format json`, and pairing it with `--format text|md` is `ERROR args`. `md` prints a
109
+ Markdown report of the results (a verdict table, then the details with `file:line` as inline
110
+ code, then the exit code) and does not render `data`. Text and JSON output are byte-identical
111
+ to before. `rx guard` keeps its hook transport when no format is given.
112
+ - `rx publication record <repo> <pr> <sha> [--root <dir>]` writes the plain publication record
113
+ `repo/publication.json` (`{repo, pr, remoteSha, at}`; no attestation, no network). Its writer
114
+ and `rx greptile can-reply --claims-fix` share one validator, and a malformed record is now
115
+ `ERROR input` rather than evidence. The plugin runner records a publication through it.
116
+ - Initial scaffold: verdict protocol, argument parser, root resolution,
117
+ `rx commands --json`, `rx doctor`, commit-message hook.
118
+ - `rx preflight`: the skills plugin's `scripts/preflight.mjs` ported with every one of its
119
+ 27 checks emitted on every run as PASS/FAIL/WARN/N/A; Markdown-aware README embed
120
+ extraction (reference definitions, angle-bracket destinations, HTML attribute whitespace,
121
+ query strings; fenced and inline code excluded); new checks `screenshot-count`,
122
+ `screenshot-format`, `screenshot-size`, `icon-size`, `readme-links`,
123
+ `changelog-placeholder`; preset-bound `pref-description-length`, `pref-label-length`,
124
+ `logger`, `logger-verbose-copy`, `logger-strict-redaction`, `agents-md-paths`,
125
+ `agents-md-scripts`, `agents-md-no-home-paths`, `agents-md-symbols`.
126
+ - Core vs preset: `docs/check-classes.md` classifies every check; preset-class checks take
127
+ values, applicability and severity from `--preset` and are `N/A` without one.
128
+ `schema/preset.schema.json` (`"schema": 1`) and the closed applicability grammar in
129
+ `docs/applicability.md`.
130
+ - `rx preset check <file>`: schema, duplicate ids, anchors, bindings against the rx, ESLint
131
+ and judgment registries, severity downgrades. `rx preset table <file> --into <reference.md>
132
+ [--check]`: regenerates the audit matrix between `<!-- rx:matrix:start -->` and
133
+ `<!-- rx:matrix:end -->`.
134
+ - `rx api-floor --preset <file>`: `@raycast/api` lockfile and manifest-range floors from the
135
+ preset's `dependencies.api` (existing 1.x, 2.x, new extensions), publication from
136
+ `rx stale`'s baseline, npm currency as an advisory that reports `N/A npm unreachable`.
137
+ - `scripts/compare-preflight.mjs` and `test/port-exceptions.json`: legacy-vs-rx equivalence
138
+ over every local `raycast-*` checkout and the fixtures.
139
+ - `rx stale`: sparse fetch of `raycast/extensions` into the shared cache, per-path classifier
140
+ (MINE / CHECK / NEW? / UPSTREAM / ONLY-PUB / UNHANDLED) with blob-history provenance,
141
+ symlink and mode checks; writes `stale/baseline.json`; CHECK and NEW? carry the
142
+ audit-disposition key `{ path, localHash, baseline }`.
143
+ - `rx contributions`: per-file incoming-vs-published decision during a `pull-contributions`
144
+ merge, monorepo-safe, both-direction tree comparison, CHANGELOG containment limited to
145
+ `CHANGELOG.md`, leftover `ext/<name>` bot-stamp detection.
146
+ - `rx changelog`: placeholder count and position, dated history against the published copy
147
+ with recorded privacy redactions (`--redactions`), bullet length, and `--merge` rebuild by
148
+ heading structure that treats a stamped and a placeholder heading as the same entry and
149
+ refuses an ambiguous boundary.
150
+ - `src/upstream.mjs`: one partial clone shared by `stale`, `gates`, `preflight --published`,
151
+ `png` and `contributions`. `src/payload.mjs`: the publisher copy set (ray's fixed skip
152
+ list at any depth) as a shared library.
153
+ - `rx png`: read-only screenshot and icon triage against the published copy with a
154
+ bounds-checked PNG chunk reader and pngjs RGBA decode; outcomes SAME-PIXELS (PASS),
155
+ UNDECIDED (FAIL: 16-bit or differing gAMA/iCCP/sRGB/cHRM), LOCAL-ONLY (N/A keep local),
156
+ OLDER-SHOT (WARN with path, local hash and baseline SHA), NOT-YOURS (FAIL). No `sips`.
157
+ - `rx scan`: gate −2. Literal scan of the payload `ray publish` copies (contents and names,
158
+ ignored and untracked included), the commit messages in ray's
159
+ `HEAD...__raycast_latest_publish_<name>__` range (all history without the tag) and
160
+ `--pr-text` files; binary files WARN; an empty forbidden list is N/A everywhere, never
161
+ PASS; `data.forbiddenHash`.
162
+ - `rx holdout out|in`: moves only untracked preset-classified local-only entries to the repo
163
+ state directory, never tracked files or `ship.keep`, with a hashed inventory; `in` refuses a
164
+ changed destination and verifies every restore.
165
+ - `rx pr verify|files|body`: port of ship's `pr-body.py` with every safeguard (initial only
166
+ onto an unedited body, whole-line anchors exactly once and non-overlapping, re-read before
167
+ the single PATCH, never retried, edit-history gap check, CRLF preserved); `--initial` also
168
+ refuses a body lacking Raycast's PR template checklist verbatim (fetched at run time);
169
+ every live body read is backed up to the cross-repo cache; `--prospective <file>` writes the
170
+ whole composed body on a dry run for `rx scan --pr-text`, and binds `--apply` to that scanned
171
+ file (a recomposition that differs FAILs and writes nothing).
172
+ - `rx greptile fetch|wait|can-reply|drift`: rounds keyed by the summary's `updated_at` with
173
+ `original_commit_id` per finding; single-shot ETag wait where a failed check is ERROR,
174
+ never "no change"; `can-reply` authorizes exact reply bytes per finding, round and head
175
+ with evidence, a forbidden-list scan and a publication record for fix claims (a decline no
176
+ longer needs a new head); the Greptile rule snapshot moves into core at
177
+ `src/rules/greptile/` and `drift --update` writes only into an explicit `--dest` checkout.
178
+ - `rx shortcuts runtime`: extract the installed Raycast app's `Keyboard.Shortcut.Common`
179
+ table (17 constants at 2.10.1.0), app version and shim fingerprint into the cross-repo
180
+ cache; `rx shortcuts check`: compare an extension's resolved ActionPanels and toast actions
181
+ with that table (`shortcut-runtime-table`, `shortcut-ambiguous`, `shortcut-reserved`).
182
+ Missing runtime evidence is an ERROR, never an N/A.
183
+ - `eslint-plugin-raycast-harness` at `raycast-harness/eslint-plugin`:
184
+ `no-multiline-emptyview-description` (moved from the skills plugin),
185
+ `no-ambiguous-shortcut` (toast `primaryAction` included; explicit `table` option),
186
+ `copy-error-pairing` (helper forms accepted), `no-toast-hide-in-cleanup`, with a
187
+ `recommended` flat config.
188
+ - `rx gates`: runs stale → scan → preflight (`--published` only when published) → api-floor →
189
+ `npm run build` → `npx --no-install tsc --noEmit` → `npm run lint`, in-process or through
190
+ execFile, invalidates the previous receipt first and writes `repo/receipt.json` only when no
191
+ step FAILed or ERRORed; missing local tooling is `ERROR tooling`, never an install.
192
+ - `src/fingerprint.mjs`: the receipt fingerprint over the publisher copy set (ignored and
193
+ untracked files included, symlink targets read through), HEAD, publish range, preset and
194
+ forbidden bytes, rx version and the published baseline (`unpublished` for a new
195
+ extension); no git writes.
196
+ - `rx audit record|show`: the agent audit beside the receipt: one entry per applicable
197
+ preset rule and Greptile judgment rule with severity from the preset, embedded
198
+ `shortcuts check` and `png` evidence, dispositions for stale CHECK/NEW? and png
199
+ OLDER-SHOT keyed on path, content hash and baseline, destination/runtime verifications
200
+ for detected external effects; tied to the receipt's fingerprint.
201
+ - `rx guard`: the plugin's PreToolUse hook: allows a publish only as the whole command
202
+ `npm run publish` or `ray publish` (one `cd <dir> &&` and plain output redirections
203
+ admitted; an exact-shape allowlist, no shell parser) and only behind a current receipt
204
+ (matching fingerprints, every step, no FAIL/ERROR) and a current audit with no blocking
205
+ reason; any other command that mentions the word `publish` blocks with the plain-command
206
+ instruction; any mention of marking a PR ready blocks; silent on allow, one JSON deny
207
+ document on block. The dispatcher honors a command's `transport` for this.
208
+ - `rx judge ask|eval`: four decisions (`changelog-user-visible`, `review-finding-triage`,
209
+ `needs-code`, `png-provenance`) with fixtures traced to receipts in the skills plugin's
210
+ learnings; inputs validated against each decision's schema; Jev and Claude Haiku adapters
211
+ behind an injectable transport, D6 provider order, 0.7 threshold with `defer-to-agent`,
212
+ provider errors falling back to agent mode, and eval accuracy. Advisory only.
213
+ - `rx api-diff <from> <to> [--out <dir>]`: packs both `@raycast/api` versions from npm and
214
+ reports the publish-order window, the added, removed and changed files, the
215
+ `types/index.d.ts` unified diff, `dist/types/` and the `oclif.manifest.json` commands, flags
216
+ and changed leaves (with `kind` added/removed/changed); file modes are inventoried; `N/A`
217
+ only when every change is a version field under the two narrow versionOnly rules (JSON
218
+ top-level `version`, or one whole quoted literal in a text file); a pack, extraction or read
219
+ failure, a symlink or special file in a package, or a publish-time tie on an endpoint is
220
+ `ERROR`; `--out` reserves `<dir>/<version>` atomically before npm, never overwrites, and an
221
+ ERROR removes only what the run reserved; temp dirs are removed on every exit path.
222
+ - `rx guard` (plan §9 item 3): a `cd` target that exists but is not a directory
223
+ (`cd ./package.json && npm run publish`) now blocks with "the cd target … is not a
224
+ directory" before any root or receipt is looked up, and an extension found one level down
225
+ through a symlinked child is reported and checked at its physical root in `data.roots` and
226
+ in every sentence.
227
+ - Receipt and audit provenance (plan §9 item 4): `rx gates` and `rx audit record` attest
228
+ `receipt.json` and `audit.json` with an HMAC-SHA256 under a per-machine key at
229
+ `$XDG_CONFIG_HOME/raycast-harness/attest.key` (created on first need at 0600 in a 0700
230
+ directory, race-safe, never replaced; an unusable key is `ERROR attest-key`). `rx guard`
231
+ verifies both attestations before any other check, so a missing key, a missing
232
+ attestation, a different key and a changed file each block with their own sentence; a
233
+ receipt written before this change blocks until `rx gates` runs again. The guard now also
234
+ handles `Write`, `Edit`, `MultiEdit` and `NotebookEdit`, blocking any target inside a
235
+ repository's rx state directory or on the key, and blocks a Bash command that mentions
236
+ `.git/rx` or the key's path. `rx doctor` reports `attest-key`. The contract's limitation (2)
237
+ now says what the attestation proves and what it does not.
238
+ - Replay and path fixes (Codex round W7): a receipt and audit are bound to the checkout and
239
+ the `rx gates` attempt they were made for. Both carry an attested `subject` (the real path
240
+ of the root and of the git common directory), and every `rx gates` attempt, failed or
241
+ stopped on its arguments included, first rotates a per-root generation kept outside the
242
+ repository under `$XDG_CONFIG_HOME/raycast-harness/generations/`. The receipt carries it
243
+ and the audit records the receipt's generation and MAC. The guard blocks a receipt copied
244
+ from another checkout, one restored after a later gates attempt, and an audit recorded
245
+ against a superseded receipt. The Bash state rule collapses `/./` and repeated `/`, and
246
+ checks every path-like word with the same protected-path test the Write rule uses (which
247
+ catches a worktree's state path and the whole rx config directory). Protected paths resolve
248
+ `..` in filesystem order, so a symlink followed by `..` is caught. `rx audit record` checks
249
+ the receipt's attestation, binding and clean results before using it, and `rx audit show`
250
+ reports provenance failures. A key directory that already exists with group or other access
251
+ is `ERROR attest-key` with the `chmod 700` fix. `docs/guide.md` ships in the package.
252
+ - `rx gates` and `rx audit record` say on stderr when they removed a previous receipt or
253
+ audit, including when the arguments did not parse, so a mistyped command no longer
254
+ deletes valid state silently.
255
+ - Simplify pass over Wave 7: the guard caches `git rev-parse` per directory within one
256
+ decision and loads its publish-only modules lazily, and a named command loads only its own
257
+ module (about 15–30 ms less per guard call); shared helpers for private temp files, atomic
258
+ JSON writes and XDG base directories. No message or check changed.
259
+ - Replay fixes (Codex round W7r2): `rx gates` rotates the generation right after the root
260
+ resolves, before any git call, so a gates attempt whose git lookup fails still supersedes a
261
+ saved receipt and audit. A failed rotation unlinks the stored generation, and every reader
262
+ rejects a generation whose directory is open to group or other, naming the `chmod 700` fix.
263
+ The Bash state rule splits words the way a POSIX shell does before removing quotes, so a
264
+ protected path with a quoted or escaped space is caught. The guide no longer claims that
265
+ `publication.json` is bound to a checkout.
266
+ - Walkthrough fixes: `agents-md-paths` checks only paths with no extension or one an
267
+ extension repository holds, and `<!-- rx-ignore agents-md -->` on a line (or alone on the
268
+ line above) exempts it from the paths, scripts and symbols checks, never from the home-path
269
+ check. Without `--published`, the comparison checks say "no published copy given" instead of
270
+ "not published". `audit-verification` says "recorded" and counts `n-a` apart from `pass`.
271
+ `rx audit record` says a blocking audit will stop the guard. Judge fixture sources cite
272
+ `raycast-extensions-skills:<path>:<lines>` instead of a path on one machine, and a test keeps
273
+ home-directory paths out of every shipped file. `api-currency` mentions a major-version
274
+ migration only across majors. `rx png` names every difference it found.
package/LICENSE ADDED
@@ -0,0 +1,201 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the purposes
44
+ of this License, Derivative Works shall not include works that remain
45
+ separable from, or merely link (or bind by name) to the interfaces of,
46
+ the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to Licensor for inclusion in the Work by the copyright owner
52
+ or by an individual or Legal Entity authorized to submit on behalf of
53
+ the copyright owner. For the purposes of this definition, "submitted"
54
+ means any form of electronic, verbal, or written communication sent
55
+ to the Licensor or its representatives, including but not limited to
56
+ communication on electronic mailing lists, source code control systems,
57
+ and issue tracking systems that are managed by, or on behalf of, the
58
+ Licensor for the purpose of discussing and improving the Work, but
59
+ excluding communication that is conspicuously marked or otherwise
60
+ designated in writing by the copyright owner as "Not a Contribution."
61
+
62
+ "Contributor" shall mean Licensor and any individual or Legal Entity
63
+ on behalf of whom a Contribution has been received by Licensor and
64
+ subsequently incorporated within the Work.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute the
71
+ Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have made,
77
+ use, offer to sell, sell, import, and otherwise transfer the Work,
78
+ where such license applies only to those patent claims licensable
79
+ by such Contributor that are necessarily infringed by their
80
+ Contribution(s) alone or by combination of their Contribution(s)
81
+ with the Work to which such Contribution(s) was submitted. If You
82
+ institute patent litigation against any entity (including a
83
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
84
+ or a Contribution incorporated within the Work constitutes direct
85
+ or contributory patent infringement, then any patent licenses
86
+ granted to You under this License for that Work shall terminate
87
+ as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute must
108
+ include a readable copy of the attribution notices contained
109
+ within such NOTICE file, excluding those notices that do not
110
+ pertain to any part of the Derivative Works, in at least one
111
+ of the following places: within a NOTICE text file distributed
112
+ as part of the Derivative Works; within the Source form or
113
+ documentation, if provided along with the Derivative Works; or,
114
+ within a display generated by the Derivative Works, if and
115
+ wherever such third-party notices normally appear. The contents
116
+ of the NOTICE file are for informational purposes only and
117
+ do not modify the License. You may add Your own attribution
118
+ notices within Derivative Works that You distribute, alongside
119
+ or as an addendum to the NOTICE text from the Work, provided
120
+ that such additional attribution notices cannot be construed
121
+ as modifying the License.
122
+
123
+ You may add Your own copyright statement to Your modifications and
124
+ may provide additional or different license terms and conditions
125
+ for use, reproduction, or distribution of Your modifications, or
126
+ for any such Derivative Works as a whole, provided Your use,
127
+ reproduction, and distribution of the Work otherwise complies with
128
+ the conditions stated in this License.
129
+
130
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
131
+ any Contribution intentionally submitted for inclusion in the Work
132
+ by You to the Licensor shall be under the terms and conditions of
133
+ this License, without any additional terms or conditions.
134
+ Notwithstanding the above, nothing herein shall supersede or modify
135
+ the terms of any separate license agreement you may have executed
136
+ with Licensor regarding such Contributions.
137
+
138
+ 6. Trademarks. This License does not grant permission to use the trade
139
+ names, trademarks, service marks, or product names of the Licensor,
140
+ except as required for reasonable and customary use in describing the
141
+ origin of the Work and reproducing the content of the NOTICE file.
142
+
143
+ 7. Disclaimer of Warranty. Unless required by applicable law or
144
+ agreed to in writing, Licensor provides the Work (and each
145
+ Contributor provides its Contributions) on an "AS IS" BASIS,
146
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147
+ implied, including, without limitation, any warranties or conditions
148
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149
+ PARTICULAR PURPOSE. You are solely responsible for determining the
150
+ appropriateness of using or redistributing the Work and assume any
151
+ risks associated with Your exercise of permissions under this License.
152
+
153
+ 8. Limitation of Liability. In no event and under no legal theory,
154
+ whether in tort (including negligence), contract, or otherwise,
155
+ unless required by applicable law (such as deliberate and grossly
156
+ negligent acts) or agreed to in writing, shall any Contributor be
157
+ liable to You for damages, including any direct, indirect, special,
158
+ incidental, or consequential damages of any character arising as a
159
+ result of this License or out of the use or inability to use the
160
+ Work (including but not limited to damages for loss of goodwill,
161
+ work stoppage, computer failure or malfunction, or any and all
162
+ other commercial damages or losses), even if such Contributor
163
+ has been advised of the possibility of such damages.
164
+
165
+ 9. Accepting Warranty or Additional Liability. While redistributing
166
+ the Work or Derivative Works thereof, You may choose to offer,
167
+ and charge a fee for, acceptance of support, warranty, indemnity,
168
+ or other liability obligations and/or rights consistent with this
169
+ License. However, in accepting such obligations, You may act only
170
+ on Your own behalf and on Your sole responsibility, not on behalf
171
+ of any other Contributor, and only if You agree to indemnify,
172
+ defend, and hold each Contributor harmless for any liability
173
+ incurred by, or claims asserted against, such Contributor by reason
174
+ of your accepting any such warranty or additional liability.
175
+
176
+ END OF TERMS AND CONDITIONS
177
+
178
+ APPENDIX: How to apply the Apache License to your work.
179
+
180
+ To apply the Apache License to your work, attach the following
181
+ boilerplate notice, with the fields enclosed by brackets "[]"
182
+ replaced with your own identifying information. (Don't include
183
+ the brackets!) The text should be enclosed in the appropriate
184
+ comment syntax for the file format. We also recommend that a
185
+ file or class name and description of purpose be included on the
186
+ same "printed page" as the copyright notice for easier
187
+ identification within third-party archives.
188
+
189
+ Copyright [yyyy] [name of copyright owner]
190
+
191
+ Licensed under the Apache License, Version 2.0 (the "License");
192
+ you may not use this file except in compliance with the License.
193
+ You may obtain a copy of the License at
194
+
195
+ http://www.apache.org/licenses/LICENSE-2.0
196
+
197
+ Unless required by applicable law or agreed to in writing, software
198
+ distributed under the License is distributed on an "AS IS" BASIS,
199
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
+ See the License for the specific language governing permissions and
201
+ limitations under the License.
package/NOTICE ADDED
@@ -0,0 +1,24 @@
1
+ raycast-harness
2
+ Copyright 2026 Chris Messina
3
+
4
+ Licensed under the Apache License, Version 2.0. See LICENSE.
5
+
6
+ Third-party material vendored in this repository
7
+ ------------------------------------------------
8
+
9
+ src/rules/greptile/ (config.json, files.json, rules.md, SOURCE.json)
10
+ A snapshot of the `.greptile/` review configuration from the raycast/extensions
11
+ repository (https://github.com/raycast/extensions), copyright Raycast
12
+ Technologies Ltd., licensed under the MIT License. SOURCE.json records the
13
+ exact repository, pull request or branch, commit SHA and fetch date the
14
+ snapshot was taken from. `rx greptile drift` compares it with the live copy.
15
+
16
+ Material relicensed by its author
17
+ ---------------------------------
18
+
19
+ The following code was first published by Chris Messina under the MIT License in
20
+ https://github.com/chrismessina/raycast-extensions-skills and is relicensed by
21
+ him here under Apache-2.0: the preflight checks (src/commands/preflight.mjs and
22
+ its tests), the Greptile drift comparison (src/commands/greptile.mjs), the PR
23
+ body editor (src/commands/pr.mjs, a port of pr-body.py) and the ESLint rule
24
+ no-multiline-emptyview-description (eslint-plugin/).
package/README.md CHANGED
@@ -1,3 +1,85 @@
1
- # Temporary Holding Version
1
+ # raycast-harness (`rx`)
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Tested, explicit-verdict checks for building and shipping [Raycast](https://www.raycast.com) extensions.
4
+
5
+ New to rx? Read the [user guide](docs/guide.md) for what it is, how to run it and the common recipes.
6
+
7
+ Most of the procedure around a Store submission is deterministic: is the published copy older than mine, does every README image resolve, does the CHANGELOG carry exactly one `{PR_MERGE_DATE}`, is this screenshot pixel-identical to the published one, did a contributor actually change code or only the CHANGELOG, may I reply to this review finding yet. Agents and people used to re-type those procedures as shell, and most defects came from the re-typing: a `grep -P` erroring into a false pass, a shell not word-splitting a variable, `ls` hiding a dotfile. `rx` moves each procedure into a Node command with one verdict per check.
8
+
9
+ ## Install and run
10
+
11
+ ```sh
12
+ npx raycast-harness commands # list commands
13
+ npx raycast-harness preflight # from an extension root
14
+ npx raycast-harness doctor
15
+ ```
16
+
17
+ Requires Node 22.12 or newer. The executable is available as both `rx` and `raycast-harness`.
18
+
19
+ ## Verdict protocol
20
+
21
+ Every command prints one line per check and exits by the worst verdict:
22
+
23
+ ```
24
+ PASS schema package.json $schema is the Raycast extension schema
25
+ FAIL readme-links 1 relative link does not resolve
26
+ README.md:12 media/missing.png
27
+ N/A changelog-updated no published copy given; pass --published <dir> (rx stale prints it)
28
+ ```
29
+
30
+ | Verdict | Means | Exit |
31
+ |---|---|---|
32
+ | `PASS` | the check ran and found nothing wrong | 0 |
33
+ | `WARN` | report, does not block | 0 |
34
+ | `N/A` | nothing to inspect, and the message says why | 0 |
35
+ | `FAIL` | the check ran and found a problem | 1 |
36
+ | `ERROR` | the check could not run (bad argument, unreadable input, missing tool, network); outranks FAIL | 2 |
37
+
38
+ Silence is never a pass. Unknown arguments are an `ERROR`. `--json` (an alias of `--format json`) prints one envelope `{ command, version, fingerprint, data, results, exit }`, and `--format md` prints the same verdicts as a Markdown report; every format exits with the same code. The full contract for every command, including its root rule, network boundary and state location, is in [`docs/commands.md`](docs/commands.md).
39
+
40
+ ## Commands
41
+
42
+ | Command | Does |
43
+ |---|---|
44
+ | `rx preflight` | Store-readiness checks on package.json, CHANGELOG, README, screenshots, dependencies, shipped files |
45
+ | `rx stale` | compares the local tree with the published copy in `raycast/extensions` and classifies every path |
46
+ | `rx png` | pixel and color-metadata comparison of screenshots and icons with the published copies (read-only) |
47
+ | `rx scan` | finds forbidden example values in files, file names, commit messages and PR text |
48
+ | `rx changelog` | placeholder, history and bullet checks; rebuilds the CHANGELOG during a merge |
49
+ | `rx contributions` | during a pull-contributions merge: which conflicted files carry a real contribution |
50
+ | `rx api-floor` | `@raycast/api` floor and currency, policy from the preset |
51
+ | `rx api-diff` | what changed between two published `@raycast/api` versions: files, `types/index.d.ts` diff, CLI commands and flags |
52
+ | `rx gates` | runs the gates in order and writes a fingerprinted receipt |
53
+ | `rx guard` | the publish hook: allows `ray publish` only on a fresh receipt and a complete audit |
54
+ | `rx audit` | records the judgment evidence the receipt cannot hold |
55
+ | `rx pr` | verifies a Store PR's author, branch, base and files; edits its body without clobbering hand edits |
56
+ | `rx holdout` | moves untracked local-only files out of the payload and verifies their return |
57
+ | `rx publication` | `record`: writes the plain record of which PR and remote head a publish produced, for `rx greptile can-reply --claims-fix` |
58
+ | `rx greptile` | fetches review rounds, waits for the next one, authorizes a reply, and keeps Greptile's review rules current (`outdated`, `update`) |
59
+ | `rx shortcuts` | `runtime`: the installed app's `Keyboard.Shortcut.Common` table into the cache; `check`: panels and toast actions against it |
60
+ | `rx preset` | validates a preset and regenerates the rule matrix it describes |
61
+ | `rx judge` | `ask`: an advisory answer to one named judgment call, or the structured question in agent mode; `eval`: per-fixture output and accuracy (never blocks) |
62
+ | `rx doctor` | Node, `ray`, `gh` auth, git signing, Raycast app version |
63
+ | `rx commands` | every command's contract as JSON |
64
+
65
+ **Judge providers.** `rx judge` uses Jev (TypeSafe's decision model, implemented against its public API reference at `https://docs.typesafe.ai/api`, fetched 2026-11-04) when `TYPESAFE_API_KEY` is set. Otherwise it uses Claude Haiku (`claude-haiku-5-5`) when `ANTHROPIC_API_KEY` is set, and otherwise agent mode, which prints the question, its answers and the inputs for the agent to decide. `--provider` overrides the order. Jev's probabilities are what its API returns; Haiku's are what the model writes into a forced tool call. Neither is calibrated, and `rx judge` never presents them as such. A provider answer counts only at a top probability of 0.7 or more, and a provider error falls back to agent mode. No `judge` result is part of the gates, the audit or the publish guard.
66
+
67
+ The ESLint rules ship with the package and are importable at `raycast-harness/eslint-plugin` (flat config; `recommended` included).
68
+
69
+ ## Core versus preset
70
+
71
+ Core encodes only objective, ecosystem-wide facts: Raycast's Store requirements, its Greptile review rules (a versioned snapshot in `src/rules/greptile/`), and what `ray publish` copies. Everything specific to one developer, such as house style, dependency floors or which files they choose to ship, lives in a **preset**: a JSON file validated against `schema/preset.schema.json` and passed with `--preset <file>`. Without a preset, preset-class checks report `N/A (no preset)`; they never silently pass. `docs/check-classes.md` records which class each check belongs to.
72
+
73
+ ## Development
74
+
75
+ ```sh
76
+ npm ci
77
+ npm run check # tsc --checkJs, eslint, node --test
78
+ node scripts/install-hooks.mjs # commit-msg hook: refuses Claude Code session URLs
79
+ ```
80
+
81
+ See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the rules every change follows (contract before code, witnessed red, fixtures, no shelling out to `ls`/`grep`/`find`/`sed`).
82
+
83
+ ## License
84
+
85
+ Apache License 2.0; see [`LICENSE`](LICENSE). Third-party material and relicensed code are listed in [`NOTICE`](NOTICE).
package/bin/rx.mjs ADDED
@@ -0,0 +1,4 @@
1
+ #!/usr/bin/env node
2
+ import { runCli } from "../src/cli.mjs";
3
+
4
+ process.exitCode = await runCli(process.argv.slice(2));
@@ -0,0 +1,35 @@
1
+ # Applicability expressions
2
+
3
+ A preset rule's `applies` field says when the rule holds for an extension. The grammar is **closed**: `schema/preset.schema.json` rejects any condition not listed here, and `rx preset check` (`preset-schema`) fails on it. `rx preflight` evaluates `applies` before running a bound check; the agent evaluates it for judgment-bound rules and records the result in the audit (plan §4.9).
4
+
5
+ ## Grammar
6
+
7
+ ```
8
+ expr := true | condition | { "all": [expr, ...] } | { "any": [expr, ...] } | { "not": expr }
9
+ condition := an object with exactly one of the keys below
10
+ ```
11
+
12
+ Evaluation is three-valued: `true`, `false`, or `unknown` (a context value `rx` cannot learn in this run). `all` is `false` if any operand is `false`, else `unknown` if any is `unknown`, else `true`. `any` is `true` if any operand is `true`, else `unknown` if any is `unknown`, else `false`. `not unknown` is `unknown`. A rule whose expression is `unknown` makes its bound checks `N/A` naming the missing value; `false` makes them `N/A (rule <id> does not apply: <rendered condition>)`.
13
+
14
+ ## Conditions and where each context value comes from
15
+
16
+ | Condition | Value | Source |
17
+ |---|---|---|
18
+ | `{ "selfAuthored": true }` | `package.json` `author` (a string, or an object's `name`) equals the preset's `owner`, compared case-insensitively. A missing `author` is `false`. | `package.json` in the root |
19
+ | `{ "platform": "macOS" \| "Windows" }` | `package.json` `platforms` contains the value. An absent `platforms` means `["macOS"]`. | `package.json` |
20
+ | `{ "published": true }` | `true` when `--published <dir>` was given, or when `repo/stale/baseline.json` (written by `rx stale`) has `published: true`; `false` when that file has `published: false`; otherwise `unknown` (the message says to run `rx stale`). | `--published`, `rx stale` state |
21
+ | `{ "webRequests": true }` | Any file under `src/` (comments stripped) matches the house-style `logger` audit pattern: `/\bfetch\s*\(\|axios\|node-fetch\|useFetch\|@chrismessina\/raycast-downloader\|from "(node:)?https?"\|from "(undici\|got\|ky)"/`. | source scan |
22
+ | `{ "declaresPreference": "<name>" }` | A preference with that `name` exists at extension level or on any command. | `package.json` |
23
+ | `{ "dependency": { "name": "<pkg>", "minVersion": "<semver>" } }` | The lockfile-resolved version of `<pkg>` (`package-lock.json` `packages["node_modules/<pkg>"].version`, or v1 `dependencies[<pkg>].version`) exists and is ≥ `minVersion` (`minVersion` optional: then presence suffices). No lockfile or not resolved → `false`. The manifest range is never consulted: a caret range admits a version without installing it. | `package-lock.json` |
24
+ | `{ "hasViewCommand": true }` | Any command has `mode: "view"`. | `package.json` |
25
+ | `{ "commandMode": "view" \| "no-view" \| "menu-bar" }` | Any command has that `mode`. | `package.json` |
26
+ | `{ "declaresInterval": true }` | Any command has an `interval` field. | `package.json` |
27
+ | `{ "writesFiles": true }` | Any file under `src/` (comments stripped) matches `/\b(writeFile\|writeFileSync\|appendFile\|appendFileSync\|createWriteStream\|copyFile\|copyFileSync\|mkdir\|mkdirSync\|rename\|renameSync)\s*\(/`. | source scan |
28
+ | `{ "callsAI": true }` | Any file under `src/` (comments stripped) matches `/\bAI\.ask\s*\(\|\buseAI\s*\(\|canAccess\s*\(\s*AI\b\|\bAI\.Model\b/`. | source scan |
29
+ | `{ "manual": "<text>" }` | Always `unknown` to `rx`: a condition only the agent can evaluate ("already being changed", "exports CSV"). The text is what the generated matrix prints in its Applies column. | the agent, recorded in the audit |
30
+
31
+ Nothing is inferred from an unstated convention: a condition not in this table is a schema error, and a context value not in this table does not exist.
32
+
33
+ ## Rendering
34
+
35
+ `rx preset table` prints an expression in the Applies column as: `true` → `all`; a condition → its phrase (`selfAuthored` → "self-authored", `webRequests` → "makes web requests", `declaresPreference: x` → "declares `x`", `dependency` → "installed `<pkg>` ≥ <minVersion>", `commandMode: no-view` → "a `no-view` command", `manual: t` → `t`); `all` → operands joined with ", "; `any` → joined with " or "; `not` → "not " + operand.