letmeknow-cli 0.4.1 → 0.4.3

package/README.md

@@ -1,175 +1,84 @@
 # LetMeKnow
 
-LetMeKnow gives one agent and one human browser a temporary HTML and CSS workspace. The agent renders a page, receives normalized form and button actions, and responds with HTML fragments. A private browser WebSocket carries renders and actions; assets use ordinary HTTP.
+LetMeKnow gives an agent-managed folder a public, live Vite preview. The CLI runs Vite in middleware mode and makes only an outbound WebSocket connection to the relay; it does not listen on a network port.
 
-It is not a localhost proxy or a programmable frontend. Agents provide presentation and semantic actions, not JavaScript or HTTP handlers.
+## Start
 
-## CLI
-
-Node 22 or newer is required.
-
-```bash
-npx letmeknow-cli
-```
-
-The deployed service is used by default. Set `LETMEKNOW_URL` for local development:
+Node.js 22.12 or newer is required.
 
 ```bash
-LETMEKNOW_URL=http://localhost:8787 npx letmeknow-cli
-```
-
-stdin contains one compact JSON command per line. stdout contains one JSON event per line. Diagnostics go to stderr.
-
-```bash
-npx letmeknow-cli --skill
-```
-
-prints the agent instructions without connecting.
-
-## Example
-
-Open a session:
-
-```json
-{"type":"open","id":"open-1"}
+npx letmeknow-cli ./workspace
 ```
 
-The CLI emits its temporary URL:
+The CLI prints JSON lines to stdout. The first line contains the public preview URL:
 
 ```json
-{"type":"session","id":"open-1","url":"https://0123456789abcdef0123.letmeknow.dev/","expires_after_disconnect":600}
+{"type":"ready","url":"https://0123456789abcdef0123.letmeknow.dev/"}
 ```
 
-The URL serves a trusted shell immediately. Send HTML and optional CSS with `render`:
+Open that URL in one browser. The directory defaults to the current working directory. Set `LETMEKNOW_URL` to use another compatible relay:
 
-```json
-{"type":"render","id":"render-1","body":"<h1>Search invoices</h1><form id=\"search\" action=\"search\" method=\"post\" data-lmk-target=\"results\"><label>Customer<input name=\"customer\" required></label><button>Search</button></form><section id=\"results\"><p>Enter a customer.</p></section>","css":"#results { margin-top: 2rem; }"}
-```
-
-A connected browser receives the render immediately. The acknowledgement contains its revision:
-
-```json
-{"type":"ack","id":"render-1","render_id":"b87438c2-4f1c-44bd-9875-6cc64370b8aa"}
-```
-
-Submitting the form produces one normalized action:
-
-```json
-{"type":"action","id":"2ee81a6b-1035-40a7-a90d-c1e02f426baa","render_id":"b87438c2-4f1c-44bd-9875-6cc64370b8aa","action_id":"search","form_id":"search","target_id":"results","trigger":{"id":null,"name":null,"value":null},"values":{"customer":"Acme Ltd"}}
+```bash
+LETMEKNOW_URL=https://letmeknow.dev npx letmeknow-cli ./workspace
 ```
 
-Respond to that ID with HTML for the target's contents:
+There are no `--host` or `--port` options because the CLI intentionally has no listening network socket. Diagnostics go to stderr. `--skill` prints the agent instructions without starting a session.
 
-```json
-{"type":"response","id":"response-1","request_id":"2ee81a6b-1035-40a7-a90d-c1e02f426baa","body":"<table><tr><th>Invoice</th><th>Amount</th></tr><tr><td>INV-42</td><td>$800</td></tr></table>"}
-```
-
-The browser inserts the fragment into `#results`. Without `data-lmk-target`, the response replaces the whole workspace.
+## File workflow
 
-## HTML actions
+The CLI does not receive file commands. The agent reads and writes the directory directly. Keep a normal Vite entry point such as `index.html`; JavaScript, CSS, images, and other Vite-supported files can be requested through the relay.
 
-### Forms
+When a watched file changes, the browser receives an update. HTML changes replace the current document body without a page reload and preserve form values, focus, selection, and scroll position. CSS links are refreshed without navigating. Changes to a different HTML route do not disturb the current page.
 
-Interactive forms use standard HTML:
+An optional element can display submission status:
 
 ```html
-<form id="decision" action="decide" method="post">
-  <label>Comment<textarea name="comment"></textarea></label>
-  <button name="decision" value="approve" formaction="approve">Approve</button>
-  <button name="decision" value="reject" formaction="reject">Reject</button>
-</form>
+<p data-letmeknow-status aria-live="polite"></p>
 ```
 
-Forms require `method="post"`, a stable `id`, a relative action identifier, and meaningful control names. A submit button's `formaction` overrides the form's `action`. Native validation runs locally. `FormData(form, submitter)` is captured before controls are disabled, so selected controls and the clicked button are included. Repeated names become string arrays. File inputs are rejected.
+## Form submissions
 
-### Standalone actions
-
-A button can invoke an action without a form:
+Forms are submitted without navigation. GET and POST forms are sent through the relay to the CLI, which prints each submission as one JSON line on stdout. The agent can read that line and edit the folder in response.
 
 ```html
-<button type="button" data-lmk-action="refresh-status" data-lmk-target="status">Refresh</button>
+<form id="decision" action="/decide" method="post">
+  <label>Comment <textarea name="comment"></textarea></label>
+  <button name="decision" value="approve">Approve</button>
+  <button name="decision" value="reject">Reject</button>
+</form>
 ```
 
-Its event has `form_id: null`, empty `values`, and its optional `id`, `name`, and `value` in `trigger`.
-
-### Targeted updates
-
-`data-lmk-target` accepts one bare element ID. All updates use `innerHTML`. There are no alternate swap modes or selector targets. The default target is `lmk-view`, the whole workspace.
-
-Typing, focusing, expanding `<details>`, validation, scrolling, and other local browser behavior produce no agent events.
-
-## CSS
-
-`render` accepts page CSS in its `css` field. A `response` may include `css` to replace it; omitting `css` preserves it.
-
-Modern CSS is supported, including grid, flexbox, media queries, variables, transitions, and print styles. External stylesheets, `@import`, scripts, inline handlers, and inline `style` attributes are blocked. Local assets work in HTML and CSS.
-
-## One browser client
-
-At most one browser is active for a session. The first browser receives a private credential stored in that tab's `sessionStorage`.
-
-- Reloads and reconnects reuse the credential.
-- A competing browser triggers at most one liveness probe every five seconds.
-- If the active browser answers, the claimant sees “This session is open elsewhere.”
-- After a disconnect, the previous credential has a five-second exclusive reconnect period.
-- After five seconds, either the old browser or a new claimant may connect; first connection wins.
-- Laptop sleep does not invalidate the credential.
-
-The server sends a connecting browser one canonical snapshot of the current HTML, CSS, render ID, and pending actions. It does not replay user actions. The browser restores same-tab drafts from `sessionStorage`; drafts do not transfer to another browser.
-
-The server keeps committed page state and assets for the producer session. A full `render` replaces the page and clears old pending actions. A targeted response updates the canonical page. Browser disconnect alone does not delete state.
-
-## Assets
-
-`put` stores or replaces passive resources only under `/assets/`:
+Submitting `Approve` prints an event like:
 
 ```json
-{"type":"put","id":"logo","path":"/assets/logo.png","content_type":"image/png","encoding":"base64","body":"iVBORw0KGgo..."}
+{"type":"submit","id":"…","method":"POST","action":"/decide","form_id":"decision","trigger":{"id":null,"name":"decision","value":"approve"},"values":{"comment":"Looks good","decision":"approve"}}
 ```
 
-Reference them relatively:
-
-```html
-<img src="assets/logo.png" alt="Company logo">
-```
-
-Assets answer only `GET` and `HEAD`. Each body is limited to 1 MiB. A session accepts 100 assets and 10 MiB decoded asset data. There is no `delete`; assets disappear with the session.
-
-## Protocol
-
-Commands:
+Repeated field names become arrays. Native browser validation still runs before a submission is sent. File inputs and cross-origin form actions are not supported. Forms can use a submitter's standard `formaction`, `formmethod`, and `name`/`value` attributes.
 
-- `open`: create the session; it must be first.
-- `render`: replace the committed HTML and CSS and push it to the browser.
-- `put`: store an asset under `/assets/`.
-- `response`: resolve one pending action with HTML and optional CSS.
-- `close`: destroy the session immediately.
+The event ID identifies the submission. It is not a request/response handle: update the files and let the live preview show the result.
 
-Events:
+## Security
 
-- `session`: public URL and producer disconnect grace.
-- `action`: normalized form or standalone-button action.
-- `ack`: command completion.
-- `error`: invalid command or protocol state.
-- `closing`: explicit session destruction.
+The preview URL is a bearer capability. The relay receives the served files and submitted values. Do not put secrets in the preview folder or submit credentials unless that is intentional. The folder is trusted executable code from the browser's perspective.
 
-Actions remain pending until `response`, a superseding full `render`, or session close. One form or overlapping target can be pending at a time; independent regions may proceed concurrently. Match responses by action ID.
+The CLI's Vite configuration is disabled and its filesystem access is limited to the selected folder. The CLI itself still requires an outbound network connection to the relay. It does not accept inbound browser connections.
 
-HTML, CSS, asset, and action bodies are each limited to 1 MiB. Up to 32 actions may be pending.
+## Hosted compatibility
 
-## Security and lifecycle
+Existing clients using the older command protocol can still connect explicitly without a folder:
 
-HTML fragments are sanitized. Scripts, style elements, inline handlers, HTMX attributes, frames, active metadata, external form actions, and invalid LetMeKnow attributes are removed. CSP blocks arbitrary browser connections and external resources.
-
-The URL is a bearer secret. Share it only with the intended human. Browser and producer reconnect credentials remain private and never appear in protocol output.
-
-If the producer disconnects, the current page remains visible, drafts are preserved, and actions are disabled. The CLI can reconnect for ten minutes. Browser traffic does not extend that grace. `close` or producer-grace expiry deletes page state, credentials, pending actions, and assets.
+```bash
+LETMEKNOW_URL=https://letmeknow.dev npx letmeknow-cli
+```
 
 ## Development
 
 ```bash
 npm install
-npm run dev
 npm test
+npm run dev
 npm run deploy
 ```
+
+`npm run dev` and `npm run deploy` operate the Cloudflare relay.

package/SKILL.md

@@ -1,164 +1,100 @@
 ---
 name: letmeknow
-description: Show one human a temporary HTML and CSS workspace and handle normalized form or button actions through the LetMeKnow NDJSON CLI.
+description: Give a human a live public preview of an agent-managed folder and receive browser form submissions as JSON lines.
 ---
 
 # LetMeKnow
 
-Use LetMeKnow when one human needs a temporary rich document, dashboard, report, preview, form, approval, quiz, table, or status view. The agent supplies semantic HTML and CSS. The browser sends only declared actions; typing and local UI state do not create events.
+Use LetMeKnow when one human needs to inspect or interact with a temporary page, report, dashboard, approval form, quiz, table, or status view. The agent owns the files in a folder. The CLI runs Vite in middleware mode, connects to the public relay over an outbound WebSocket, and reports browser submissions on stdout.
 
-LetMeKnow is not a localhost proxy, persistent application, or arbitrary JavaScript environment.
+The CLI does **not** listen on a local network port.
 
 ## Start
 
-Node.js 22 or newer is required.
+Run the CLI as a long-lived child process with the folder you will edit:
 
 ```bash
-npx letmeknow-cli
+npx letmeknow-cli ./workspace
 ```
 
-Run it as a long-lived child process. Write one compact JSON object per line to stdin, keep stdin open, and read one JSON event per line from stdout. Read stderr separately.
+Node.js 22.12 or newer is required. Read stdout and stderr separately. Stdout is JSONL; the first event is:
 
 ```json
-{"type":"open","id":"open-1"}
+{"type":"ready","url":"https://0123456789abcdef0123.letmeknow.dev/"}
 ```
 
-Wait for the session URL:
+Open the public URL for the human. The directory defaults to the current working directory. Set `LETMEKNOW_URL` to use another compatible relay. There are no host or port options: the CLI intentionally has no listening socket.
 
-```json
-{"type":"session","id":"open-1","url":"https://0123456789abcdef0123.letmeknow.dev/","expires_after_disconnect":600}
-```
-
-The URL immediately serves a shell with a waiting message. One browser may use it at a time.
-
-## Render HTML and CSS
-
-```json
-{"type":"render","id":"render-1","body":"<h1>Search invoices</h1><form id=\"search\" action=\"search\" method=\"post\" data-lmk-target=\"results\"><label>Customer<input name=\"customer\" required></label><button>Search</button></form><section id=\"results\"><p>Enter a customer.</p></section>","css":"#results { margin-top: 2rem; }"}
-```
-
-A connected browser receives the render immediately. Wait for its acknowledgement and retain the `render_id`:
-
-```json
-{"type":"ack","id":"render-1","render_id":"b87438c2-4f1c-44bd-9875-6cc64370b8aa"}
-```
+Do not send file commands to stdin. Read and write the folder directly. Keep the process running while the human uses the page.
 
-Use semantic HTML: headings, sections, paragraphs, lists, tables, `dl`, forms, labels, controls, buttons, `details`, progress, and images. Do not include `<html>`, `<head>`, `<body>`, `<main id="lmk-view">`, scripts, style elements, inline handlers, inline `style`, iframes, or HTMX attributes.
+## Build the page
 
-The optional `css` field supports modern CSS, including grid, flexbox, media queries, variables, transitions, and print styles. External stylesheets, `@import`, and remote resources do not work. Use relative session assets.
+Create an ordinary Vite page in the folder, usually `index.html`, plus any CSS, JavaScript, images, or other assets it needs. Use semantic HTML and accessible labels, headings, sections, tables, and controls.
 
-A full `render` intentionally replaces the current page, resets drafts, and cancels actions from the previous render. Use `response` rather than `render` after a user action.
+The relay is live:
 
-## Forms
+- HTML changes update the current document body without a full page reload.
+- Existing form values, focus, text selection, and scroll position are restored after an HTML update.
+- CSS links are refreshed without navigating.
+- Changes to another HTML route do not replace the current route.
 
-Interactive forms use standard HTML:
+An optional status element gives the human feedback after a form submission:
 
 ```html
-<form id="decision" action="decide" method="post">
-  <label>Reason<textarea name="reason" required></textarea></label>
-  <button name="decision" value="approve" formaction="approve">Approve</button>
-  <button name="decision" value="reject" formaction="reject">Reject</button>
-</form>
+<p data-letmeknow-status aria-live="polite"></p>
 ```
 
-Rules:
-
-- Use `method="post"`.
-- Give each form a stable, unique `id`.
-- Give controls meaningful `name` values.
-- Use an action identifier containing letters, digits, `.`, `_`, `:`, or `-`.
-- A submit button's standard `formaction` may override the form action.
-- Native `required`, input types, ranges, and patterns validate locally.
+## Receive form submissions
 
-The runtime captures `FormData(form, submitter)` before disabling controls. Selected radios, checked boxes, ordinary controls, and the clicked submit button are included. Repeated names become string arrays. File inputs are rejected.
-
-## Standalone actions
+GET and POST forms are intercepted before navigation and sent through the relay to the CLI. Read stdout for a `submit` event:
 
 ```html
-<button type="button" data-lmk-action="refresh-status" data-lmk-target="status">
-  Refresh
-</button>
-```
-
-Use standalone actions for refresh, retry, cancel, generate, inspect, load-more, and export. Their events have `form_id: null`, empty `values`, and the button's optional `id`, `name`, and `value` in `trigger`.
-
-## Whole and partial updates
-
-Responses replace the whole workspace by default. To update a region, put `data-lmk-target="element-id"` on the form or action button:
-
-```html
-<form id="search" action="search" method="post" data-lmk-target="results">
-  <input name="query">
-  <button>Search</button>
+<form id="search" action="/search" method="post">
+  <label>Query <input name="query" required></label>
+  <button name="scope" value="all">Search all</button>
 </form>
-<section id="results"></section>
 ```
 
-The target is one bare element ID without `#`. Every update uses `innerHTML`. A submit button may override its form's target.
-
-## Handle actions
+The event is:
 
 ```json
-{"type":"action","id":"2ee81a6b-1035-40a7-a90d-c1e02f426baa","render_id":"b87438c2-4f1c-44bd-9875-6cc64370b8aa","action_id":"search","form_id":"search","target_id":"results","trigger":{"id":null,"name":null,"value":null},"values":{"query":"quarterly report"}}
+{"type":"submit","id":"…","method":"POST","action":"/search","form_id":"search","trigger":{"id":null,"name":"scope","value":"all"},"values":{"query":"quarterly report","scope":"all"}}
 ```
 
-Use:
-
-- `id` to respond to this exact action.
-- `render_id` to identify the page revision that produced it.
-- `action_id` for user intent.
-- `form_id` and `target_id` for context.
-- `trigger` for the clicked button.
-- `values` for the submitted form snapshot.
-
-Validate actions and values. Treat values as untrusted and HTML-escape reflected text.
-
-Respond with HTML for the target contents:
-
-```json
-{"type":"response","id":"response-1","request_id":"2ee81a6b-1035-40a7-a90d-c1e02f426baa","body":"<table><tr><th>Invoice</th><th>Amount</th></tr><tr><td>INV-42</td><td>$800</td></tr></table>"}
-```
-
-A response may include `css` to replace the page CSS. Omitting it preserves the existing CSS:
-
-```json
-{"type":"response","id":"response-2","request_id":"event-2","body":"<h1 class=\"success\">Approved</h1>","css":".success { color: green; }"}
-```
+Rules:
 
-Wait for the acknowledgement and its new `render_id`. An action remains pending until `response`, a superseding full `render`, or session close. Independent regions may be pending concurrently, so always match by action ID.
+- Give interactive forms a stable, meaningful `id`.
+- Give controls meaningful `name` values.
+- Use normal relative or same-origin actions.
+- Use `formaction` and `formmethod` on submitters when different buttons have different intents.
+- Native `required`, input types, ranges, and patterns validate in the browser before the event is sent.
+- Repeated names become string arrays.
+- File inputs and cross-origin actions are not supported.
 
-## One-browser behavior
+The event ID identifies the submission. There is no response packet. Validate its values, edit the files, and let the live preview show the result. Do not write JSON commands to stdin.
 
-The first browser claims the session with a private credential. Reload and laptop wake reconnect automatically. A second browser cannot connect while the first is active.
+## Example response workflow
 
-Liveness is checked only when another browser tries to claim, at most once every five seconds. After a browser disconnect, its credential has five seconds of exclusive reconnect priority. After that, the first old or new browser to connect wins.
+1. Render the initial state in `index.html`.
+2. Wait for a `submit` event on stdout.
+3. Validate its `values` and `action`.
+4. Rewrite the relevant HTML or data file in the workspace.
+5. The browser updates in place through the relay.
 
-A reconnect receives one canonical snapshot of committed HTML, CSS, render ID, and pending actions. It does not replay old user actions. Same-tab drafts are restored from `sessionStorage`; drafts do not transfer during takeover.
+Escape untrusted values before placing them in HTML. Treat browser input as untrusted even though the folder is local to the agent.
 
-## Assets
+## Security
 
-```json
-{"type":"put","id":"logo","path":"/assets/logo.png","content_type":"image/png","encoding":"base64","body":"iVBORw0KGgo..."}
-```
+The public URL is a bearer capability. The relay receives the served files and submitted values. Do not put secrets in the preview folder or submit credentials unless that is intentional. The folder is trusted executable code from the browser's perspective.
 
-Store resources only under `/assets/` and reference them relatively:
+The CLI disables Vite config discovery and limits filesystem access to the selected folder. It makes outbound relay connections only; it does not accept inbound browser connections.
 
-```html
-<img src="assets/logo.png" alt="Company logo">
-```
+## Stop
 
-`encoding` is `utf8` by default or `base64` for binary data. Assets answer only `GET` and `HEAD`. There is no `delete`; another `put` replaces an asset.
+Send `SIGINT` or `SIGTERM` to stop the CLI. The relay session expires after producer disconnect. `--skill` prints these instructions without starting a session.
 
-## Close and lifecycle
+Existing clients using the older hosted command protocol can still connect explicitly without a folder:
 
-```json
-{"type":"close","id":"close-1"}
+```bash
+LETMEKNOW_URL=https://letmeknow.dev npx letmeknow-cli
 ```
-
-Wait for `ack` and `closing`. Closing stdin only disconnects the producer.
-
-If the producer disconnects, the page remains visible, drafts remain, and actions are disabled. The CLI has ten minutes to reconnect. Browser traffic does not extend that period. Explicit close or expiry deletes HTML, CSS, credentials, actions, and assets.
-
-Limits: 1 MiB per HTML, CSS, asset, or action body; 100 assets; 10 MiB decoded asset storage; and 32 pending actions.
-
-Treat the URL as a bearer secret. Never expose either private reconnect credential.