Skip to content

Let the toolkit command read a site's debug log and caught mail - #771

Merged
adamsilverstein merged 2 commits into
try/764-cli-for-ai-toolsfrom
add/764-toolkit-log-and-mail
Nov 13, 2026
Merged

adamsilverstein merged 2 commits into
try/764-cli-for-ai-toolsfrom
add/764-toolkit-log-and-mail

Conversation

@adamsilverstein

Copy link
Copy Markdown
Member

The second step for #764, stacked on #766: the two reads an agent needs when it is testing a ticket. Still nothing here that changes a site.

Written up by Claude Code, which also wrote the code:

Why

An agent testing a ticket needs to see what the site logged and what mail it sent, and today both are only in the window. This is step 2 of the plan on #764 (#764 (comment)): the remaining reads, which need no answer yet to whether a tool may change a site.

What changes

  • toolkit log [site] [--lines N] prints the end of a site's WordPress debug.log, the file the Logs panel tails: the last 100 lines unless told otherwise, 1000 at most, from one bounded read of the last 256 KB.
  • toolkit mail [site] prints the mail the app caught for a site, newest first, text only: the newest 50, with the total.
  • A site is named by its path, by a folder inside it, or by its name in the app. Left out, it is the site the current folder is in, so a tool working in the checkout passes nothing.
  • What a tool sends is never opened. resolveSite turns it into a path out of the registry, and the log is found from that.
  • An action can now refuse with a code of its own (unknown-site, ambiguous-site), so a tool can tell "no such site" from an action that broke.

Not in this PR: anything that changes a site, the opt-in setting, and the Settings row that shows where the command is. Those are steps 3 and 4.

How to test this

Platforms: either. The journey tests/e2e/journeys/toolkit-command.spec.js walks this from source (npm run test:e2e:hidden, from the repository root): it runs log from inside the checkout with no site named, log from a folder that is no site's, and mail by name. What it cannot reach is real caught mail and a real log, since a journey starts no server, so that is the part worth a pass by hand, on the Buildkite artifact for the current head.

Starting state: the app open with a site whose dev server is running, and the path of the toolkit command from Help → Open App Log (the line answering at …; the command is …).

  1. In the site's wp-admin, trigger a mail (Users → send a password reset) and a log line (any PHP notice will do).
  2. In a terminal, cd into the site's folder, any depth, and run the command path in quotes followed by log. Expected: the last lines of what the Logs panel shows.
  3. Run it with log --lines 1. Expected: only the newest line.
  4. Run it with mail. Expected: the password reset, with its subject, sender, recipient and text, matching the Mail panel.
  5. From a folder that is not in any site, run it with log. Expected: "The WordPress Contributor Toolkit has no site at or named …" and a non-zero exit status.
  6. From that same folder, run it with mail "<the site's name in the sidebar>". Expected: the same mail as step 4.

What must not have happened:

  • The Mail panel still lists every mail and the Logs panel is unchanged: reading clears nothing.
  • No debug.log was created for a site that had none.

Risks and limitations

  • Only run on macOS, from source. Same as Add a toolkit command so scripts and AI tools can drive the app #766, which this is stacked on.
  • A site name that starts with - cannot be passed as a name; use its path.
  • A mail's HTML part is left out, and only the newest 50 mails are answered.
  • A symlinked debug.log is followed, as the Logs panel follows it.
  • Review: 3 [fix here] · 3 [follow-up], all three fixed and two of the follow-ups with them. Details below.

Related

Part of #764. Stacked on #766.


Design decisions and alternatives considered
  • The current folder as the default site. The tool this is for is usually already working in the checkout, and asking it to look up and pass a path it is standing in is a step it can get wrong.
  • Realpath only on a miss. A folder the OS names differently from the registry (/private/var for /var on macOS, or the far side of a symlink) is matched by comparing real paths, and only when nothing matched as written, so the common case costs no file system call.
  • The Logs panel's own read ceiling, planInitialRead in src/log-tail.js, instead of a second number.
Review outcome (required — see AGENTS.md)

3 [fix here] · 3 [follow-up]. No escape from the registry was found for .., prefix, case or label inputs.

  • Fixed: the long-log test passed whether or not the read was bounded. Its lines are now long enough that the half line at the start of the read is in the answer if it is not dropped.

  • Fixed: site.mail had no ceiling. Newest 50, with total.

  • Fixed: toolkit log . was refused. A site written starting with . is resolved against the current folder.

  • Follow-up, done here: .. in a path is resolved before it is compared.

  • Follow-up, done here: a log whose last 256 KB are one line answered as empty.

  • Follow-up, reworded: the fallback calls realpath on the path sent. It opens nothing; the note in AGENTS.md now says "opened".

  • Review: completed — Claude Code, fresh-context agent; reviewed head f251346 / base 2c28fdf; lint, npm test and the journey green on macOS; outcome above

  • Since review: f251346 → 32a48da — the fixes above only; lint, npm test and the journey re-run green on macOS; not re-reviewed by a fresh agent

  • CodeRabbit: not requested yet

Implementation notes
  • src/control-sites.cjs: resolveSite, logLineCount, lastLines, describeEmail.
  • src/control-channel.cjs: ControlRefusal.
  • src/main.js: site.log and site.mail in controlActions, and controlSite.
  • Nothing on screen changed, so there are no screenshots.

AI Use

Claude Code did the typing here, code and description, and I did the asking. I will review and test.

🤖 Generated with Claude Code

https://claude.ai/code/session_018vwYjUEX6a9RXfZ6jHr6FN

An agent testing a ticket needs what the site logged and mailed, and
both are reads, so they need no answer yet to whether a tool may
change a site (#764). A site is named by path, by a folder inside it
or by its name, and the answer is always a path out of the registry.

Claude-Session: https://claude.ai/code/session_018vwYjUEX6a9RXfZ6jHr6FN
…og bound

The mail list had no ceiling and the store keeps every mail. A site
written as . or ./src was sent unresolved and refused. The long-log
test passed whether or not the read was bounded.

Claude-Session: https://claude.ai/code/session_018vwYjUEX6a9RXfZ6jHr6FN
@coderabbitai

coderabbitai Bot commented Nov 13, 2026

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@adamsilverstein
adamsilverstein merged commit 32a48da into try/764-cli-for-ai-tools Nov 13, 2026
12 of 13 checks passed
@adamsilverstein
adamsilverstein deleted the add/764-toolkit-log-and-mail branch November 13, 2026 17:50
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