Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@

- The READMEs call sessionpad beta software rather than alpha.
- The Timeline tab's summary offer says how to turn summary lines on (set `summaryModel` to `haiku`) and has a **Got it** button, instead of a **Turn on summaries** button that changed the setting: the plugin directory accepts no settings call from a mod that keeps its engine for later, as every button and timer in this one does. A change in `/config` reloads the mod with the new value.
- The modules in `sessionpad/src` no longer take Claude Code's `$`. The hooks module builds one object from it, `ioOf($)`, with every call the mod makes written out there, and hands them that: the plugin directory reads a mod's calls from its hooks module alone and refuses `$` passed to another file. What the mod does is unchanged.
- `just dollar_check` applies the plugin directory's rule for `$` and `on` (`scripts/dollar_check.ts`) and lists every place that breaks it, and `just check` runs the script's tests (`just script_test`).

### Added

Expand Down
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ Status: beta. Version 0.4.0, not released yet; 0.3.0 was released 2026-10-29, wi

## Requirements

Claude Code 2.1.299 or later, in the Desktop app's Code tab or a terminal. Mods themselves run from 2.1.286 (Desktop) and 2.1.287 (terminal), but releases before 2.1.299 refuse this mod's hooks module, which passes `$` to functions in its other files. Mods don't run in regular claude.ai chats, in Cowork or in Desktop WSL sessions. In `claude -p` and the Agent SDK the commands and tools work but nothing is drawn. The tests run on 2.1.299 (CI) and on the newest release when developing; the releases between aren't tested.
Claude Code 2.1.299 or later, in the Desktop app's Code tab or a terminal. Mods themselves run from 2.1.286 (Desktop) and 2.1.287 (terminal), but releases before 2.1.299 refused this mod's hooks module while it passed `$` to functions in its other files, and the mod hasn't been tried on them since it stopped. Mods don't run in regular claude.ai chats, in Cowork or in Desktop WSL sessions. In `claude -p` and the Agent SDK the commands and tools work but nothing is drawn. The tests run on 2.1.299 (CI) and on the newest release when developing; the releases between aren't tested.

## Install

Expand Down Expand Up @@ -151,7 +151,7 @@ env reads: CLAUDE_CONFIG_DIR, HOME, USERPROFILE
env writes: nothing
```

There is no `$.http`: the only thing that leaves your machine is the summary line's model call, described above. `$.process.run` runs `git` (read-only commands), `du -sk` and `rm` on the mod's own files. The mod changes no settings: the plugin directory accepts no settings call from a mod that, as this one does in its buttons and timers, keeps the engine for later, so the Timeline tab says how to turn summary lines on instead of doing it. The hooks on `prompt.submit`, `turn.start` and the `tool.call` for Edit, Write, NotebookEdit and Bash only watch: each passes the event on and hands back what came back, untouched. Run `claude plugin validate sessionpad` in a clone to see the full report.
There is no `$.http`: the only thing that leaves your machine is the summary line's model call, described above. `$.process.run` runs `git` (read-only commands), `du -sk` and `rm` on the mod's own files. The mod changes no settings: the plugin directory accepts no settings call from a mod that, as this one does in its buttons and timers, keeps the engine for later, so the Timeline tab says how to turn summary lines on instead of doing it. The hooks on `prompt.submit`, `turn.start` and the `tool.call` for Edit, Write, NotebookEdit and Bash only watch: each passes the event on and hands back what came back, untouched. Run `claude plugin validate sessionpad` in a clone to see the full report. Every one of these calls is written in `sessionpad/hooks/register.ts`, most of them in `ioOf`, which builds the one object the rest of the code reaches Claude Code through.

## Development

Expand All @@ -171,7 +171,7 @@ Decisions made while building, and places where this build of Claude Code (2.1.3

- **Name and label.** The name is `sessionpad`, which installs and updates go by, so it won't change. The label the plugin lists show is its `displayName`, `Session Pad`.
- **The mod is in a subfolder, not the repository root.** `claude plugin validate` warns that a `CLAUDE.md` at a plugin root isn't loaded, and `--strict` turns that into an error; the subfolder also keeps the repository's tooling out of what users install. The marketplace file sits at the repository root, `.claude-plugin/marketplace.json`, with `"source": "./sessionpad"` rather than `"./"`.
- **The hooks module imports sibling files**, with three rules the validator enforces: a hook is written inline or as a function declared at the top of its file; a function in another file that receives `$` is a `function` declaration, not an arrow; and every read and write of a `$.state` value happens in the file that declares it, which is why all of it goes through `src/state.ts`.
- **The hooks module imports sibling files, but hands them no `$`.** The plugin directory lists a mod's calls from its hooks module alone, and refuses `$` passed to a function in another file, even from a hook's body; a hook is written inline or as a function declared at the top of its file. So `hooks/register.ts` builds one object from a hook's `$`, `ioOf($)`, each member of which makes one plain call on `$`, with the program or variable it uses written out (`git`, `du`, `rm`, `HOME`), and the modules in `src` take that object instead (`src/io.ts` is its type). A `$.state` call names its value with the plugin and key written out in the hooks module, so `stateOf` there spells out each of the pad's nine values, and `read` and `update` in `src/state.ts` reach them through it. `just dollar_check` applies the directory's rule locally, and lists every place that breaks it where the developer portal shows ten at a time.
- **Drawing is in `src/ui.tsx`**, not `src/ui.ts`, because it uses JSX.
- **Session ids.** `/clear` ends the session (`session.end` with reason `clear`) and continues under a new id with no `session.start`; the mod sees it as `classic.SessionStart` with source `clear`. `/resume` reports source `resume`. `/branch` reports source `fork` there (and `resume` at `session.end`). The mod tracks the id it loaded and carries the pad from that id. A pad the new id already has is never overwritten. This comes from the docs and the types; a manual check in a live session is still to do.
- **Pane width.** `bodyColumns` already leaves out the pane's close mark, which sits on the frame, so the first row is not drawn two cells shorter.
Expand Down
18 changes: 14 additions & 4 deletions justfile
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,18 @@ clean:

# Run every check: formatting, types, tests. CI runs this recipe on pull
# requests into main, and you run it before pushing.
check: format_check validate type_check dollar_check test
check: format_check validate type_check dollar_check script_test test

# Fail when a call on $ is split across lines or a property of $ is read:
# the plugin directory reads $ only as whole $.noun.method(...) calls. It
# reads each line with its comments taken off; it doesn't see a $ taken
# apart by destructuring, a call split between noun and method, or anything
# after a "//" inside a string on the same line.
# Then scripts/dollar_check.ts applies the directory's rule for $ and on, the
# way it reads the source: in the hooks module, $ goes only to a function
# declared at the top of that file, each registration is on("event", hook) on
# a line of its own, and no module in src holds $ at all. It lists every
# place at once, where the developer portal shows ten a round.
dollar_check:
#!/usr/bin/env bash
set -uo pipefail
Expand All @@ -23,14 +28,19 @@ dollar_check:
if [ "$status" -gt 1 ]; then echo "dollar_check: grep failed"; exit "$status"; fi
found=$(printf '%s\n' "$lines" | sed -E 's#//.*$##; s#/\*.*\*/##g' | grep -vE '^[^:]+:[0-9]+:[[:space:]]*\*' | grep -E '\$\.[a-z]+(\.[a-zA-Z]+)?[[:space:]]*$|\$\.[a-z]+\.[a-zA-Z]+[^a-zA-Z(<]|\$\.[a-z]+[^a-zA-Z.]' || true)
if [ -n "$found" ]; then echo "$found"; echo "Write each call on \$ whole, on one line: \$.noun.method(...)"; exit 1; fi
bun scripts/dollar_check.ts

# Check formatting of the mod, the marketplace file and the docs
# Run the tests of the repository's own scripts (scripts/*.test.ts)
script_test:
bun test ./scripts

# Check formatting of the mod, the scripts, the marketplace file and the docs
format_check:
bunx prettier --check sessionpad .claude-plugin README.md CHANGELOG.md package.json
bunx prettier --check sessionpad scripts .claude-plugin README.md CHANGELOG.md package.json

# Rewrite files into Prettier's format
format:
bunx prettier --write sessionpad .claude-plugin README.md CHANGELOG.md package.json
bunx prettier --write sessionpad scripts .claude-plugin README.md CHANGELOG.md package.json

# Read the mod, then the marketplace file that lists it, the way Claude Code
# will, treating warnings as errors
Expand Down
242 changes: 242 additions & 0 deletions scripts/dollar_check.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,242 @@
import { describe, expect, test } from "bun:test";

import {
blankOut,
hooksProblems,
moduleProblems,
topLevelFunctions,
} from "./dollar_check";

/** The lines of a hooks module the check reports, given its body. */
const hookLines = (source: string): number[] =>
hooksProblems(source, "register.ts").map((one) => one.line);

describe("blankOut", () => {
test("blanks comments and string text, keeping offsets", () => {
const source = 'a($) // $.x\nb("$") /* $ */ c';
const code = blankOut(source);
expect(code.length).toBe(source.length);
expect(code).toBe('a($) \nb(" ") c');
});

test("keeps the code inside a template's ${...}", () => {
const code = blankOut("`t $ ${f($)} u ${`in ${g($)}`}`");
expect(code).toContain("f($)");
expect(code).toContain("g($)");
expect(code.replace(/[fg]\(\$\)/g, "")).not.toContain("$");
});

test("blanks a regular expression but not a division", () => {
expect(blankOut("x.replace(/\\.$/, '')")).not.toContain("$");
expect(blankOut("const y = (a) / $b / 2;")).toContain("$b");
});
});

describe("hooksProblems", () => {
test("allows plain calls, parameters and $ handed to this file's functions", () => {
const source = [
'import { other } from "../src/other";',
"function helper($: EngineInterface) {",
" return $.store.get(`k`);",
"}",
"export const register: Register = (on, options) => {",
' on("session.start", async ($, e, next) => {',
" await helper($);",
' $.ui.log(`a ${String(e)}`, { to: "debug" });',
" return next(e);",
" }).catch(($, e, next) => next(e));",
' on("ui.render", ($) => other(helper($)));',
"};",
].join("\n");
expect(hookLines(source)).toEqual([]);
});

test("refuses $ handed to another file's function", () => {
const source = [
'import { loadSession } from "../src/pad";',
"export const register: Register = (on) => {",
' on("session.start", async ($, e, next) => {',
" await loadSession($, e.cwd);",
" return next(e);",
" });",
"};",
].join("\n");
expect(hookLines(source)).toEqual([4]);
});

test("refuses every other shape of $", () => {
const shapes = [
"const own = $.plugin.name;",
"($.ui).log('x');",
"$.ui?.log('x');",
"$['ui'].log('x');",
"const kept = $;",
"helper<T>($);",
"helper(!$);",
"thing.helper($);",
"$.ui.log;",
];
const source = [
"function helper($: EngineInterface) {}",
...shapes.map((line, i) => `function f${i}($: E) { ${line} }`),
].join("\n");
expect(hookLines(source)).toEqual([2, 3, 4, 5, 6, 7, 8, 9, 10]);
});

test("refuses a call split between its noun and its method", () => {
const source = [
"function f($: EngineInterface) {",
" $.ui",
" .log('x');",
"}",
].join("\n");
expect(hookLines(source)).toEqual([2]);
});

test("refuses on used other than as on(...)", () => {
const source = [
"function helper(on: On) {}",
"export const register: Register = (on) => {",
" helper(on);",
" const kept = on;",
"};",
].join("\n");
expect(hookLines(source)).toEqual([4]);
});

test("ignores $ in comments, strings and template text", () => {
const source = [
"// loadSession($)",
"/* other($) */",
"const a = 'other($)';",
"const b = `other($) costs $5`;",
"const c = jquery.$;",
].join("\n");
expect(hookLines(source)).toEqual([]);
});
});

describe("hooksProblems, after the review", () => {
test("refuses $ spread into a call or used as a default value", () => {
const source = [
"function helper(...rest: unknown[]) {}",
"function f($: E) { helper(...$); }",
"function g($: E, a = $) {}",
"const h = ($: E, a = $) => a;",
].join("\n");
expect(hookLines(source)).toEqual([2, 3, 4]);
});

test("refuses the engine held under a name other than $", () => {
const source = [
'import { loadSession } from "../src/pad";',
"function helper(engine: EngineInterface) {}",
"function named(engine, e, next) {}",
"export const register: Register = (on) => {",
' on("session.start", (engine, e, next) => loadSession(engine));',
' on("session.end", ({ ui }, e, next) => next(e));',
' on("turn.start", ($, e, next) => next(e)).catch((x, e, next) => next(e));',
' on("turn.complete", named);',
' on("ui.render", imported);',
"};",
].join("\n");
expect(hookLines(source)).toEqual([2, 5, 6, 7, 8, 9]);
});

test("refuses a registration that isn't a statement of its own line in register", () => {
const source = [
"export const register: Register = (on) => {",
' for (const name of names) on("a", ($) => 1);',
' if (isOn) on("b", ($) => 1);',
' on("c", ($) => 1); on("d", ($) => 1);',
' const kept = on("e", ($) => 1);',
" on(eventName, ($) => 1);",
' [1].forEach(() => { on("f", ($) => 1); });',
' on("g", ($) => 1).then(() => 1);',
" if (isOn)",
' on("h", ($) => 1);',
"};",
'on("i", ($) => 1);',
].join("\n");
expect(hookLines(source)).toEqual([2, 3, 4, 5, 6, 7, 8, 10, 12]);
});

test("allows a registration across lines, with its .catch", () => {
const source = [
"export const register: Register = (on, options) => {",
" on(",
' "classic.SessionStart",',
' { source: ["clear", "resume"] },',
" async ($, e, next) => {",
" return next(e);",
" }",
" ).catch(($, e, next) => next(e)); // replays the result",
' on("session.end", ($, e, next) => next(e));',
"};",
].join("\n");
expect(hookLines(source)).toEqual([]);
});

test("reads a generic function's $ as its parameter", () => {
const source = [
"function helper<T>($: EngineInterface): T {",
" return $.store.get('k') as T;",
"}",
"function caller($: EngineInterface) { helper<string>($); }",
].join("\n");
// Passing $ with a type argument is refused, as the directory says.
expect(hookLines(source)).toEqual([4]);
});
});

describe("blankOut and JSX", () => {
test("a closing tag and a self-closing element aren't read as regexes", () => {
const code = blankOut(
'<Text>a</Text>; f($);\n<Box key="a" />; g($);\n<Box x={1} />; h($);'
);
expect(code).toContain("f($)");
expect(code).toContain("g($)");
expect(code).toContain("h($)");
});
});

describe("topLevelFunctions", () => {
test("names the functions declared at the top, not inner ones or consts", () => {
const code = [
"function a() {}",
"export async function b() {",
" function inner() {}",
"}",
"const c = () => {};",
].join("\n");
expect([...topLevelFunctions(code)]).toEqual(["a", "b"]);
});
});

describe("moduleProblems", () => {
test("refuses $ held in a module, but not ${ or a regular expression", () => {
const source = [
"export async function f(io: Io) {",
" const t = `${io.x}`.replace(/\\.$/, '');",
" return io.store.get(t);",
"}",
"export function g($: EngineInterface) {",
" return $.store.get('k');",
"}",
].join("\n");
// Line 5 twice: $ taken as a parameter, and the engine's type named.
expect(moduleProblems(source, "m.ts").map((one) => one.line)).toEqual([
5, 5, 6,
]);
});

test("lets src/io.ts name the engine's type, which Io is made from", () => {
const source = 'import type { EngineInterface } from "claude-code";';
expect(moduleProblems(source, "sessionpad/src/io.ts")).toEqual([]);
expect(moduleProblems(source, "sessionpad/src/pad.ts")).toHaveLength(1);
});

test("refuses $ spread into a call", () => {
expect(moduleProblems("f(...$);", "m.ts")).toHaveLength(1);
});
});
Loading
Loading