Skip to content

Reach the engine through one object the hooks module builds - #8

Merged
j127 merged 2 commits into
mainfrom
claude/sessionpad-mod-865578
Oct 30, 2026
Merged

j127 merged 2 commits into
mainfrom
claude/sessionpad-mod-865578

Conversation

@j127

@j127 j127 commented Oct 29, 2026 •

Copy link
Copy Markdown
Owner

The plugin directory's rule for $ still blocked the submission. The finding's own text gives the rule: in the hooks module, $ may only be passed, whole, to a function declared at the top of that same file. Every hook that handed $ to a module in src broke it. That was 24 lines on e658483, and the developer portal shows ten a round, so fixing them as they showed up would have taken three more rounds.

What changes

  • hooks/register.ts builds ioOf($), one object whose members each make one plain call on $. The variable or program each one uses is written out: HOME, USERPROFILE, the config-folder variable, git, du -sk --, rm -f --. Hooks pass ioOf($) (or a local io built from it) where they passed $. Timers and buttons keep it, as they kept $ before.
  • src/io.ts is that object's type: the engine's own methods under the same nouns, cut down to the arguments the mod passes.
  • The modules in src take io instead of $. It's a rename in the code, with comments left as they were, plus the six env reads and three program runs moved to their named members. Nothing the mod does changes.
  • stateOf writes out each of the pad's nine $.state values with its key. The validator requires a $.state call's plugin and key to be written out in the hooks module, or held in a const there, so read and update in src/state.ts reach the values through it. A value that isn't the pad's is refused before $ is asked.
  • scripts/dollar_check.ts checks the directory's rule locally: in the hooks module, each $ must be a parameter, a plain $.noun.method(...) call, or a whole argument to a function declared at the top of that file; each on must be register's parameter or the callee of on(...); and no module in src holds $. just dollar_check runs it after the old grep check, and just check runs its tests (just script_test). scripts joins the format check.
  • README and CHANGELOG: the design note on the hooks module and the note on older releases now describe how it works, and the 0.4.0 entry lists both changes.

How it was checked

  • The new check on e658483's hooks file finds 24 lines, starting with 326, 332 and 336, the three the portal showed, in the same order. On this branch it finds none.
  • The validator passes in strict mode. It lists the same calls, env reads and state keys as before, now traced to ioOf, stateOf and the other functions of the hooks file.
  • 366 mod tests pass, 6 of them new (tests/io.test.ts: each member's call, the refusals, and optional arguments left out rather than passed as undefined). 19 tests of the check script pass.
  • Breaking the check four ways in a scratch copy fails its tests each time.

Review

A reviewer subagent with fresh context read b478296. It found nothing critical and no change in behavior: every argument, .catch and await is as it was, and timers and buttons keep the io of the hook that set them up, as they kept its $. What it found, and what changed in 659bf18:

  • Important: the hooks module now holds calls the portal has never read, so another round under this rule or another is possible.
    • Changed: the owner's validation in the portal stays a gate before merging. The nine casts in stateOf's $.state.set(...) calls are gone, since the rule's text names casts; the value is typed never instead.
    • Kept: the spread in $.process.run(["git", ...args], init) is inside an argument, not around a part of the call. The same shape was already in a module the validator traced.
  • Minor: nothing tied stateOf to the state contract. A tenth value would have compiled and then failed when read. The switch now runs on the contract's keys, so a key left out fails to type-check, and the test's key list is held to the contract the same way. Removing a case, or a key from the test list, fails the type check.
  • Minor: the check missed some shapes.
    • Changed: it now refuses $ spread into a call or used as a default value, the engine under another name (a hook's or .catch handler's first parameter, a parameter typed EngineInterface, the engine's type named in src outside io.ts), and a registration that isn't on("event", ...) as a statement of its own line in register's body (in a loop or an if, two on a line, assigned, or with a non-string event).
    • Docs: the CHANGELOG and justfile now say "the rule for $ and on" instead of "whole rule".
  • Minor: a false positive. function helper<T>($: E) reported its own parameter. Type parameters are now skipped.
  • Minor: four stale comments (src/state.ts, src/git.ts, src/prune.ts, the hooks module's header) described $ in src. Each is corrected in place, and none is removed.
  • Nits:
    • Changed:
      • The check fails when hooks.json names no module, where it used to pass silently.
      • It doesn't read a JSX closing tag or self-closing element as a regex.
      • A redundant condition is gone.
    • Kept, with the reason:
      • state.set sends {} when it's given no options. That's a well-formed options object, not undefined, and only update calls it, always with ifVersion.
      • scripts/ isn't type-checked, because that needs Bun's types as a new dev dependency.
      • JSX text with a quote in it still reads as a string to the end of its line. The script's header comment now says so.

Each new rule in the check has a test that fails when the rule is taken out (7 rules tried). The script's tests went from 11 to 19.

Before merging

  • A reviewer with fresh context reads the diff (above), and its findings are fixed.
  • The owner validates this branch in the developer portal, and it no longer reports the rule.
  • CI green.
  • The owner's OK to merge into main.

j127 added 2 commits October 29, 2026 16:25
The plugin directory reads a mod's calls from its hooks module alone and
refuses $ handed to a function in another file, even from a hook's body.
The developer portal flagged 24 such lines in hooks/register.ts, ten a
round.

hooks/register.ts now builds ioOf($), each member of which makes one plain
call on $, with the variable or program it uses written out (HOME, git,
du, rm), and the modules in src take that object (src/io.ts) instead of $.
A $.state call takes its plugin and key written out in the hooks module,
so stateOf spells out the pad's nine values; read and update in
src/state.ts reach them through it. What the mod does is unchanged.

scripts/dollar_check.ts applies the directory's rule locally and lists
every place that breaks it at once: on e658483 it finds the same 24 lines
as the portal, in the same order. just dollar_check runs it, and
just check runs its tests.
The check now also refuses $ spread into a call or used as a default
value, the engine held under a name other than $ (a hook's or .catch
handler's first parameter, or anything typed EngineInterface, and the
engine's type named in src outside io.ts), and a registration that isn't
on("event", ...) as a statement of its own line in register's body. It
reads a generic function's $ as its parameter, doesn't read a JSX closing
tag as a regex, and fails when hooks.json names no hooks module. Each new
rule has a test that fails without it.

stateOf passes each value to $.state.set without a cast, and switches on
the contract's keys, so a value added to the contract and not to the
switch fails to type-check; the test's list of keys is held to the
contract the same way.

Four comments that described $ in src are corrected, and the CHANGELOG
and the justfile say the check applies the rule for $ and on rather than
the "whole rule".
@j127
j127 marked this pull request as ready for review October 30, 2026 00:35
@j127
j127 merged commit 42d8d8b into main Oct 30, 2026
2 checks passed
@j127
j127 deleted the claude/sessionpad-mod-865578 branch October 30, 2026 00:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant