raycast-harness 0.0.0-stage → 0.1.1

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 +279 -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 +64 -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,279 @@
1
+ # Changelog
2
+
3
+ ## 0.1.1
4
+
5
+ The first published version. 0.1.0 was staged on npm and rejected before release, and npm does
6
+ not reuse a version number, so it was never published.
7
+
8
+ - The package is macOS-only (`"os": ["darwin"]`): rx reads Raycast.app with `plutil`. CI runs on
9
+ `macos-latest` with `actions/checkout@v5` and `actions/setup-node@v5`.
10
+ - Preflight reads every `.gitignore` the extension ships, nested ones included, each relative to
11
+ its own directory, as the fork-side `git add` does. A nested `!greptile.json` can no longer let
12
+ a review config pass `nested-review-config`, and a file a nested `.gitignore` drops is no longer
13
+ reported as shipping. `readme-links` now requires each target to ship, so a link into `.github/`
14
+ or an ignored file FAILs and names the reason.
15
+ - A Greptile rule that preflight covers mechanically keeps that exemption only while its text and
16
+ scope match the digest the mapping was reviewed against (`GREPTILE_MECHANICAL_RULES`). After
17
+ `rx greptile update` changes such a rule, the audit requires a judgment entry for it again.
18
+ - `rx holdout out` stops with ERROR `holdout-tracked`, before writing an inventory or moving a
19
+ file, when git cannot read the index; before, a corrupt index made every path look untracked.
20
+ `rx holdout out`, `rx pr files --preset` and `rx stale --preset` validate the whole preset
21
+ against its schema, so a mistyped key is ERROR `input` instead of a silent default.
22
+ - The guard treats `gh pr --repo o/r ready 42`, `-R o/r` and any other flag between `pr` and
23
+ `ready` as marking a PR ready, and blocks it.
24
+ - `rx pr files` reports ERROR `github` for a files row with no `filename` string, or with a
25
+ rename source that is malformed or missing on a `renamed` row, instead of skipping the row and
26
+ passing.
27
+ - Chris's 2026-11-03 file ruling (`AGENTS.md`, `CONCEPTS.md`, `CLAUDE.md` and `HANDOFF.md`
28
+ never ship) works through a guarded publish. The plugin preset holds them out with
29
+ `rx holdout`, and `holdout-tracked` names its fix, bound to the root. The fix runs
30
+ `git -C <root> rm --cached -- <path>`, lists the path in that checkout's `.gitignore`, and runs
31
+ `rx holdout in --root <root>` before `rx holdout out` again with the same arguments. The restore
32
+ is needed because the untracked entries still move when the check FAILs. A cross-device holdout
33
+ move that fails partway removes its partial copy, so the copy no longer blocks every later `out`
34
+ unless that removal fails too. A copy whose source could not be removed stays in the inventory
35
+ without counting as moved. `rx stale --preset` (and `rx gates`, which now passes its preset to
36
+ stale) classifies a published file the preset's `holdout.localOnly` lists and the local tree
37
+ lacks as `REMOVE` (`stale-remove`, WARN) instead of the `ONLY-PUB` FAIL. `rx audit record`
38
+ accepts the disposition `remove-published` (`{ path, localHash: "absent", baseline }`) for those
39
+ rows only, and `rx guard` recomputes the same rule. `rx pr files` reports each file's GitHub
40
+ status (`data.files: [{ path, status, previous }]`, the path list kept as `data.paths`), and
41
+ with `--preset` its `pr-local-only` check FAILs when a local-only file is added, modified or
42
+ renamed in rather than removed.
43
+ - Synced with the live skills plugin: the published-copy comparison has a test for a file changed
44
+ inside an already-published directory with an unchanged file list (ported from the live
45
+ `preflight.test.mjs`), and `docs/check-classes.md` no longer lists `AGENTS.md` as a file an
46
+ owner ships on purpose (Chris's 2026-11-03 ruling: `AGENTS.md` and `CONCEPTS.md` stay in the
47
+ mirror, listed in the extension's `.gitignore`).
48
+ - Published-copy access is one scoped operation (`src/published-copy.mjs` `withPublishedCopy`):
49
+ the service owns cache detection, the upstream lock for the whole read and exact-baseline
50
+ validation, and `stale`, `preflight`, `png`, `changelog`, `contributions`, `gates` and
51
+ `audit record` read through it. `repo/stale/baseline.json` is `{ name, published, baseline, at }`
52
+ with no cache path (an older file with one still reads). An external `--published` is neither
53
+ locked nor refreshed, `changelog --published` inside the cache is read under the lock, and
54
+ `gates` reports `ERROR github` when the cache moved between `stale` and `preflight`.
55
+ - One completion kernel (`src/command-execution.mjs`) is shared by the dispatcher and by the
56
+ in-process steps of `rx gates` and `rx audit record`: results recorded before a throw, silence
57
+ as `ERROR protocol` and the conversion of thrown errors are defined once. Two existing
58
+ differences stay explicit options (only the dispatcher logs an unexpected error's stack and
59
+ contains a failure to record an ERROR). No output, verdict or exit code changes.
60
+ - `rx gates` stamps the receipt with exactly the Greptile rules snapshot its `greptile-rules`
61
+ step reported. A final check, `gates-rules-changed`, runs immediately before the receipt is
62
+ written and FAILs with no receipt when another `rx greptile update` installed a copy while gates
63
+ ran. The step has a 30-second deadline: when it expires gates WARNs, installs nothing, kills the
64
+ pending `gh` child (the 1Password `op plugin run` fallback included) and continues on the copy in
65
+ 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
66
+ receipt's rules are not the rules in use, `rx guard` and `rx audit show` prescribe "run rx gates,
67
+ then rx audit record".
68
+ - `rx gates` keeps the Greptile rules current as its first step, `greptile-rules`, with the same
69
+ check-and-update as `rx greptile update`; offline, or when the live rules fail validation, it
70
+ WARNs and continues on the copy in use. The receipt records the rules it ran under
71
+ (`greptileRules`), and a receipt written before this field is not current. `rx audit record`
72
+ refuses a receipt written under other Greptile rules, and `rx guard` and `rx audit show`
73
+ require the receipt, the audit and the rules in use to agree, naming the one that differs.
74
+ - `rx audit record` judges against one snapshot of the Greptile rules taken at the start, and
75
+ writes nothing (`ERROR audit-greptile-rules`) if an `rx greptile update` lands mid-recording.
76
+ `update --dest` restores every file it attempted, including one whose write failed after
77
+ truncating it, verifies each restored file byte for byte, and accepts an older checkout whose
78
+ `SOURCE.json` has no `committed`. In preflight, a package that `src/` appears to import at runtime
79
+ but that is listed only in `devDependencies` is a heuristic WARN, and a published menu-bar-only
80
+ extension without screenshots is a WARN unless its published copy had screenshots and this
81
+ change removes them all.
82
+ - An audit is bound to the Greptile rules it judged: `rx audit record` stores
83
+ `greptileRules { repo, sha, digest }`, and `rx guard` and `rx audit show` block when the rules
84
+ in use differ, so a rule whose text changed cannot reuse an old judgment. Rule copies are
85
+ ordered by upstream commit date (`SOURCE.json` `committed`), must name `raycast/extensions`
86
+ and pass a full schema check; `rx greptile update` WARNs when its copy is not the one in use,
87
+ and `update --dest` writes all or nothing. Preflight `screenshots` covers menu-bar commands,
88
+ `unused-dependencies` FAILs a runtime import of a package listed only in `devDependencies`, and
89
+ `nested-review-config` checks every depth of the payload. Rules that preflight covers only in part
90
+ are judgment rules too: the audit requires 55 Greptile judgment entries.
91
+ - Greptile rules stay current. `rx greptile outdated` (formerly `drift`) says whether the rules
92
+ in use match the last commit on `raycast/extensions` main that touched `.greptile/`, usually in
93
+ one request. `rx greptile update` fetches the live rules, validates them and writes them
94
+ atomically to `~/.cache/raycast-harness/greptile/rules/`; every reader uses the newest valid
95
+ copy that is not older than the one shipped with rx. `update --dest <checkout>` refreshes a
96
+ maintainer checkout's shipped copy. `rx doctor` adds a report-only `greptile-rules` check: PASS
97
+ current, WARN out of date, or WARN could not check.
98
+ - The shipped Greptile rules are refreshed to `raycast/extensions` main `b6bdcb1` (58 rules: 6
99
+ new, 19 changed). New core preflight check `nested-review-config` (Greptile
100
+ `no-nested-review-config`, high), split out of the preset-class `agent-scaffolding`, which now
101
+ only WARNs. `platforms` FAILs a missing field (`platforms-field`), or WARNs when the published
102
+ copy lacks it too. Four new audit judgment rules (40 in total). Every shipped rule is bound to a
103
+ preflight check or listed as judgment (a test enforces it), and a rule in the rules in use that
104
+ this release has not classified is a required, blocking audit entry.
105
+ - `--format md` escapes block syntax and GitHub-flavored autolinks as well as inline syntax, so
106
+ a detail such as `+ added.d.ts`, `- removed.d.ts`, `# note`, `1. item`, `&copy;`, a bare URL,
107
+ a `www.` address or an email address renders as literal text. `rx publication record` needs no
108
+ extension: it records into the git repository containing `--root` or the working directory,
109
+ including a multi-extension checkout root, and a missing git is reported as such. The plugin
110
+ runner records a publication without loading the registry or reaching the network; when rx's
111
+ bytes are not on the machine it exits 2 and says the record was not written.
112
+ - Every command takes `--format text|json|md`. `--json` stays as an exact alias of
113
+ `--format json`, and pairing it with `--format text|md` is `ERROR args`. `md` prints a
114
+ Markdown report of the results (a verdict table, then the details with `file:line` as inline
115
+ code, then the exit code) and does not render `data`. Text and JSON output are byte-identical
116
+ to before. `rx guard` keeps its hook transport when no format is given.
117
+ - `rx publication record <repo> <pr> <sha> [--root <dir>]` writes the plain publication record
118
+ `repo/publication.json` (`{repo, pr, remoteSha, at}`; no attestation, no network). Its writer
119
+ and `rx greptile can-reply --claims-fix` share one validator, and a malformed record is now
120
+ `ERROR input` rather than evidence. The plugin runner records a publication through it.
121
+ - Initial scaffold: verdict protocol, argument parser, root resolution,
122
+ `rx commands --json`, `rx doctor`, commit-message hook.
123
+ - `rx preflight`: the skills plugin's `scripts/preflight.mjs` ported with every one of its
124
+ 27 checks emitted on every run as PASS/FAIL/WARN/N/A; Markdown-aware README embed
125
+ extraction (reference definitions, angle-bracket destinations, HTML attribute whitespace,
126
+ query strings; fenced and inline code excluded); new checks `screenshot-count`,
127
+ `screenshot-format`, `screenshot-size`, `icon-size`, `readme-links`,
128
+ `changelog-placeholder`; preset-bound `pref-description-length`, `pref-label-length`,
129
+ `logger`, `logger-verbose-copy`, `logger-strict-redaction`, `agents-md-paths`,
130
+ `agents-md-scripts`, `agents-md-no-home-paths`, `agents-md-symbols`.
131
+ - Core vs preset: `docs/check-classes.md` classifies every check; preset-class checks take
132
+ values, applicability and severity from `--preset` and are `N/A` without one.
133
+ `schema/preset.schema.json` (`"schema": 1`) and the closed applicability grammar in
134
+ `docs/applicability.md`.
135
+ - `rx preset check <file>`: schema, duplicate ids, anchors, bindings against the rx, ESLint
136
+ and judgment registries, severity downgrades. `rx preset table <file> --into <reference.md>
137
+ [--check]`: regenerates the audit matrix between `<!-- rx:matrix:start -->` and
138
+ `<!-- rx:matrix:end -->`.
139
+ - `rx api-floor --preset <file>`: `@raycast/api` lockfile and manifest-range floors from the
140
+ preset's `dependencies.api` (existing 1.x, 2.x, new extensions), publication from
141
+ `rx stale`'s baseline, npm currency as an advisory that reports `N/A npm unreachable`.
142
+ - `scripts/compare-preflight.mjs` and `test/port-exceptions.json`: legacy-vs-rx equivalence
143
+ over every local `raycast-*` checkout and the fixtures.
144
+ - `rx stale`: sparse fetch of `raycast/extensions` into the shared cache, per-path classifier
145
+ (MINE / CHECK / NEW? / UPSTREAM / ONLY-PUB / UNHANDLED) with blob-history provenance,
146
+ symlink and mode checks; writes `stale/baseline.json`; CHECK and NEW? carry the
147
+ audit-disposition key `{ path, localHash, baseline }`.
148
+ - `rx contributions`: per-file incoming-vs-published decision during a `pull-contributions`
149
+ merge, monorepo-safe, both-direction tree comparison, CHANGELOG containment limited to
150
+ `CHANGELOG.md`, leftover `ext/<name>` bot-stamp detection.
151
+ - `rx changelog`: placeholder count and position, dated history against the published copy
152
+ with recorded privacy redactions (`--redactions`), bullet length, and `--merge` rebuild by
153
+ heading structure that treats a stamped and a placeholder heading as the same entry and
154
+ refuses an ambiguous boundary.
155
+ - `src/upstream.mjs`: one partial clone shared by `stale`, `gates`, `preflight --published`,
156
+ `png` and `contributions`. `src/payload.mjs`: the publisher copy set (ray's fixed skip
157
+ list at any depth) as a shared library.
158
+ - `rx png`: read-only screenshot and icon triage against the published copy with a
159
+ bounds-checked PNG chunk reader and pngjs RGBA decode; outcomes SAME-PIXELS (PASS),
160
+ UNDECIDED (FAIL: 16-bit or differing gAMA/iCCP/sRGB/cHRM), LOCAL-ONLY (N/A keep local),
161
+ OLDER-SHOT (WARN with path, local hash and baseline SHA), NOT-YOURS (FAIL). No `sips`.
162
+ - `rx scan`: gate −2. Literal scan of the payload `ray publish` copies (contents and names,
163
+ ignored and untracked included), the commit messages in ray's
164
+ `HEAD...__raycast_latest_publish_<name>__` range (all history without the tag) and
165
+ `--pr-text` files; binary files WARN; an empty forbidden list is N/A everywhere, never
166
+ PASS; `data.forbiddenHash`.
167
+ - `rx holdout out|in`: moves only untracked preset-classified local-only entries to the repo
168
+ state directory, never tracked files or `ship.keep`, with a hashed inventory; `in` refuses a
169
+ changed destination and verifies every restore.
170
+ - `rx pr verify|files|body`: port of ship's `pr-body.py` with every safeguard (initial only
171
+ onto an unedited body, whole-line anchors exactly once and non-overlapping, re-read before
172
+ the single PATCH, never retried, edit-history gap check, CRLF preserved); `--initial` also
173
+ refuses a body lacking Raycast's PR template checklist verbatim (fetched at run time);
174
+ every live body read is backed up to the cross-repo cache; `--prospective <file>` writes the
175
+ whole composed body on a dry run for `rx scan --pr-text`, and binds `--apply` to that scanned
176
+ file (a recomposition that differs FAILs and writes nothing).
177
+ - `rx greptile fetch|wait|can-reply|drift`: rounds keyed by the summary's `updated_at` with
178
+ `original_commit_id` per finding; single-shot ETag wait where a failed check is ERROR,
179
+ never "no change"; `can-reply` authorizes exact reply bytes per finding, round and head
180
+ with evidence, a forbidden-list scan and a publication record for fix claims (a decline no
181
+ longer needs a new head); the Greptile rule snapshot moves into core at
182
+ `src/rules/greptile/` and `drift --update` writes only into an explicit `--dest` checkout.
183
+ - `rx shortcuts runtime`: extract the installed Raycast app's `Keyboard.Shortcut.Common`
184
+ table (17 constants at 2.10.1.0), app version and shim fingerprint into the cross-repo
185
+ cache; `rx shortcuts check`: compare an extension's resolved ActionPanels and toast actions
186
+ with that table (`shortcut-runtime-table`, `shortcut-ambiguous`, `shortcut-reserved`).
187
+ Missing runtime evidence is an ERROR, never an N/A.
188
+ - `eslint-plugin-raycast-harness` at `raycast-harness/eslint-plugin`:
189
+ `no-multiline-emptyview-description` (moved from the skills plugin),
190
+ `no-ambiguous-shortcut` (toast `primaryAction` included; explicit `table` option),
191
+ `copy-error-pairing` (helper forms accepted), `no-toast-hide-in-cleanup`, with a
192
+ `recommended` flat config.
193
+ - `rx gates`: runs stale → scan → preflight (`--published` only when published) → api-floor →
194
+ `npm run build` → `npx --no-install tsc --noEmit` → `npm run lint`, in-process or through
195
+ execFile, invalidates the previous receipt first and writes `repo/receipt.json` only when no
196
+ step FAILed or ERRORed; missing local tooling is `ERROR tooling`, never an install.
197
+ - `src/fingerprint.mjs`: the receipt fingerprint over the publisher copy set (ignored and
198
+ untracked files included, symlink targets read through), HEAD, publish range, preset and
199
+ forbidden bytes, rx version and the published baseline (`unpublished` for a new
200
+ extension); no git writes.
201
+ - `rx audit record|show`: the agent audit beside the receipt: one entry per applicable
202
+ preset rule and Greptile judgment rule with severity from the preset, embedded
203
+ `shortcuts check` and `png` evidence, dispositions for stale CHECK/NEW? and png
204
+ OLDER-SHOT keyed on path, content hash and baseline, destination/runtime verifications
205
+ for detected external effects; tied to the receipt's fingerprint.
206
+ - `rx guard`: the plugin's PreToolUse hook: allows a publish only as the whole command
207
+ `npm run publish` or `ray publish` (one `cd <dir> &&` and plain output redirections
208
+ admitted; an exact-shape allowlist, no shell parser) and only behind a current receipt
209
+ (matching fingerprints, every step, no FAIL/ERROR) and a current audit with no blocking
210
+ reason; any other command that mentions the word `publish` blocks with the plain-command
211
+ instruction; any mention of marking a PR ready blocks; silent on allow, one JSON deny
212
+ document on block. The dispatcher honors a command's `transport` for this.
213
+ - `rx judge ask|eval`: four decisions (`changelog-user-visible`, `review-finding-triage`,
214
+ `needs-code`, `png-provenance`) with fixtures traced to receipts in the skills plugin's
215
+ learnings; inputs validated against each decision's schema; Jev and Claude Haiku adapters
216
+ behind an injectable transport, D6 provider order, 0.7 threshold with `defer-to-agent`,
217
+ provider errors falling back to agent mode, and eval accuracy. Advisory only.
218
+ - `rx api-diff <from> <to> [--out <dir>]`: packs both `@raycast/api` versions from npm and
219
+ reports the publish-order window, the added, removed and changed files, the
220
+ `types/index.d.ts` unified diff, `dist/types/` and the `oclif.manifest.json` commands, flags
221
+ and changed leaves (with `kind` added/removed/changed); file modes are inventoried; `N/A`
222
+ only when every change is a version field under the two narrow versionOnly rules (JSON
223
+ top-level `version`, or one whole quoted literal in a text file); a pack, extraction or read
224
+ failure, a symlink or special file in a package, or a publish-time tie on an endpoint is
225
+ `ERROR`; `--out` reserves `<dir>/<version>` atomically before npm, never overwrites, and an
226
+ ERROR removes only what the run reserved; temp dirs are removed on every exit path.
227
+ - `rx guard` (plan §9 item 3): a `cd` target that exists but is not a directory
228
+ (`cd ./package.json && npm run publish`) now blocks with "the cd target … is not a
229
+ directory" before any root or receipt is looked up, and an extension found one level down
230
+ through a symlinked child is reported and checked at its physical root in `data.roots` and
231
+ in every sentence.
232
+ - Receipt and audit provenance (plan §9 item 4): `rx gates` and `rx audit record` attest
233
+ `receipt.json` and `audit.json` with an HMAC-SHA256 under a per-machine key at
234
+ `$XDG_CONFIG_HOME/raycast-harness/attest.key` (created on first need at 0600 in a 0700
235
+ directory, race-safe, never replaced; an unusable key is `ERROR attest-key`). `rx guard`
236
+ verifies both attestations before any other check, so a missing key, a missing
237
+ attestation, a different key and a changed file each block with their own sentence; a
238
+ receipt written before this change blocks until `rx gates` runs again. The guard now also
239
+ handles `Write`, `Edit`, `MultiEdit` and `NotebookEdit`, blocking any target inside a
240
+ repository's rx state directory or on the key, and blocks a Bash command that mentions
241
+ `.git/rx` or the key's path. `rx doctor` reports `attest-key`. The contract's limitation (2)
242
+ now says what the attestation proves and what it does not.
243
+ - Replay and path fixes (Codex round W7): a receipt and audit are bound to the checkout and
244
+ the `rx gates` attempt they were made for. Both carry an attested `subject` (the real path
245
+ of the root and of the git common directory), and every `rx gates` attempt, failed or
246
+ stopped on its arguments included, first rotates a per-root generation kept outside the
247
+ repository under `$XDG_CONFIG_HOME/raycast-harness/generations/`. The receipt carries it
248
+ and the audit records the receipt's generation and MAC. The guard blocks a receipt copied
249
+ from another checkout, one restored after a later gates attempt, and an audit recorded
250
+ against a superseded receipt. The Bash state rule collapses `/./` and repeated `/`, and
251
+ checks every path-like word with the same protected-path test the Write rule uses (which
252
+ catches a worktree's state path and the whole rx config directory). Protected paths resolve
253
+ `..` in filesystem order, so a symlink followed by `..` is caught. `rx audit record` checks
254
+ the receipt's attestation, binding and clean results before using it, and `rx audit show`
255
+ reports provenance failures. A key directory that already exists with group or other access
256
+ is `ERROR attest-key` with the `chmod 700` fix. `docs/guide.md` ships in the package.
257
+ - `rx gates` and `rx audit record` say on stderr when they removed a previous receipt or
258
+ audit, including when the arguments did not parse, so a mistyped command no longer
259
+ deletes valid state silently.
260
+ - Simplify pass over Wave 7: the guard caches `git rev-parse` per directory within one
261
+ decision and loads its publish-only modules lazily, and a named command loads only its own
262
+ module (about 15–30 ms less per guard call); shared helpers for private temp files, atomic
263
+ JSON writes and XDG base directories. No message or check changed.
264
+ - Replay fixes (Codex round W7r2): `rx gates` rotates the generation right after the root
265
+ resolves, before any git call, so a gates attempt whose git lookup fails still supersedes a
266
+ saved receipt and audit. A failed rotation unlinks the stored generation, and every reader
267
+ rejects a generation whose directory is open to group or other, naming the `chmod 700` fix.
268
+ The Bash state rule splits words the way a POSIX shell does before removing quotes, so a
269
+ protected path with a quoted or escaped space is caught. The guide no longer claims that
270
+ `publication.json` is bound to a checkout.
271
+ - Walkthrough fixes: `agents-md-paths` checks only paths with no extension or one an
272
+ extension repository holds, and `<!-- rx-ignore agents-md -->` on a line (or alone on the
273
+ line above) exempts it from the paths, scripts and symbols checks, never from the home-path
274
+ check. Without `--published`, the comparison checks say "no published copy given" instead of
275
+ "not published". `audit-verification` says "recorded" and counts `n-a` apart from `pass`.
276
+ `rx audit record` says a blocking audit will stop the guard. Judge fixture sources cite
277
+ `raycast-extensions-skills:<path>:<lines>` instead of a path on one machine, and a test keeps
278
+ home-directory paths out of every shipped file. `api-currency` mentions a major-version
279
+ 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 macOS and Node 22.12 or newer. The package declares `"os": ["darwin"]`, because rx reads Raycast.app and its `Info.plist` with `plutil`, which only macOS has. 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));