letmeknow-cli 0.4.10 → 0.5.0

package/README.md

@@ -1,46 +1,38 @@
 # LetMeKnow
 
-LetMeKnow gives an agent-managed folder a public, live static preview and receives browser form submissions. The CLI serves files directly and makes only an outbound WebSocket connection to the relay; it does not listen on a network port.
+LetMeKnow gives an agent a temporary public preview of a dedicated folder and receives structured input from a human. The CLI serves the folder over an outbound connection to the LetMeKnow relay; it does not listen on a network port.
 
-## Start
+## Start a session
 
-Node.js 22.12 or newer is required.
+Node.js 22.12 or newer is required. Pass the preview directory explicitly:
 
 ```bash
-npx letmeknow-cli ./workspace
+npx letmeknow-cli ./preview
 ```
 
-The CLI prints JSON lines to stdout. The first line contains the public preview URL:
+The CLI prints JSON lines to stdout. The first line contains the public URL:
 
 ```json
 {"type":"ready","url":"https://0123456789abcdef0123.letmeknow.dev/"}
 ```
 
-Open that URL in one browser. The directory defaults to the current working directory. Set `LETMEKNOW_URL` to use another compatible relay:
+Open the URL in one or more browsers. The URL is a bearer capability: anyone who has it can view the preview and submit its forms. Sessions are hosted at `letmeknow.dev` and are temporary. A graceful CLI stop closes the session; an unexpected disconnect can reconnect for up to ten minutes. `--skill` prints instructions for an agent without starting a session. Diagnostics go to stderr.
 
-```bash
-LETMEKNOW_URL=https://letmeknow.dev npx letmeknow-cli ./workspace
-```
+The preview directory is public. Keep secrets and unrelated project files elsewhere. Use a dedicated directory containing only the files intended for the human.
 
-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.
+## Live workspace
 
-## File workflow
+Create an ordinary static site in the directory, usually with `index.html`, plus its CSS, JavaScript, images, and other assets. The relay injects the small browser runtime into HTML pages. The CLI serves the workspace files unchanged.
 
-The CLI does not receive file commands. The agent reads and writes the directory directly. Keep an `index.html` at the root, plus ordinary JavaScript, CSS, images, and other static assets.
+Every file in the preview directory is part of the live artifact. A burst of changes is coalesced into one workspace revision. Each connected browser then performs a full-page reload.
 
-The preview serves exact files and `index.html` for directory paths. It supports GET and HEAD, redirects directory paths to a trailing slash, and has no application-shell fallback. HTML responses include the live-preview client inline. Use relative asset URLs so previews also work on path-based session URLs.
+The runtime preserves scroll position and the values of controls with stable, unique `id` attributes, including checked and selected state. Other browser state is not part of the preview contract. Use relative asset URLs and normal links between pages.
 
-The client continuously saves form values, checked controls, selections, focus, text selection, scroll position, and open `<details>` elements for each page in the tab's session storage. It restores them after file-triggered and user-triggered reloads. CSS changes cache-bust matching stylesheets without navigating, while changes to the current HTML route or another asset reload the page. Changes to a different HTML route do not disturb the current page. Arbitrary JavaScript heap state cannot be preserved.
+If a requested page does not exist, the live 404 page remains connected and recovers when the page is created. Connection status pages likewise reconnect and recover when the producer becomes available again.
 
-An optional element can display submission status:
+## Forms
 
-```html
-<p data-letmeknow-status aria-live="polite"></p>
-```
-
-## Form submissions
-
-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.
+Use native HTML GET and POST forms with same-origin or relative actions:
 
 ```html
 <form id="decision" action="/decide" method="post">
@@ -50,29 +42,32 @@ Forms are submitted without navigation. GET and POST forms are sent through the
 </form>
 ```
 
-Submitting `Approve` prints an event like:
+The runtime sends the submission to the CLI, which prints one `submit` event to stdout:
 
 ```json
 {"type":"submit","id":"…","method":"POST","action":"/decide","form_id":"decision","trigger":{"id":null,"name":"decision","value":"approve"},"values":{"comment":"Looks good","decision":"approve"}}
 ```
 
-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.
+Repeated field names become arrays, and native browser validation runs before delivery. POST forms may include file inputs; the total submission is limited to 1 MiB. Uploaded files are stored in a private temporary inbox and the event includes an `attachments` array with each field name, original filename, media type, size, and local path. Attachment paths remain available until the CLI stops and are never published unless the agent deliberately copies them into the preview directory.
+
+The event ID identifies the submission; it is not a response handle. Read the event, treat values and attachments as untrusted input, update the workspace, and let the next revision show the result.
 
-The event ID identifies the submission. It is not a request/response handle: update the files and let the live preview show the result.
+Submission feedback is automatic: **Sending…** or **Uploading…**, then **Sent. Waiting for an update…**, or **Couldn’t send. Try again.** Add `[data-letmeknow-status]` where a form or page needs a particular status location. Forms are accepted for asynchronous processing, so the transport response is `202 Accepted`.
 
 ## Security
 
-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.
+The preview URL grants access to the session. The relay receives served files and submitted values. The preview folder is trusted code from the browser's perspective, so do not include secrets or credentials unless that is intentional. The CLI makes outbound relay connections only and accepts no inbound browser connections.
 
-The selected folder is resolved with real paths. Requests that would leave that folder through a symlink are denied. `.env` files, `.git`, private-key files, database files, and their descendants are denied. The CLI itself still requires an outbound network connection to the relay. It does not accept inbound browser connections.
+The CLI resolves requested paths and denies symlinks whose targets leave the selected directory. Sensitive names such as `.env`, `.git`, private keys, and database files are excluded. Processes with write access to the preview directory are trusted publishers and can make data public through it.
 
 ## Development
 
 ```bash
 npm install
 npm test
+npm run test:browser
 npm run dev
 npm run deploy
 ```
 
-`npm run dev` and `npm run deploy` operate the Cloudflare relay.
+`npm run test:browser` requires Firefox and geckodriver. `npm run dev` and `npm run deploy` operate the Cloudflare relay. The stdout contract is JSONL (`ready` and `submit` events); diagnostics belong on stderr.

package/SKILL.md

@@ -1,56 +1,39 @@
 ---
 name: letmeknow
-description: Give a human a live public preview of an agent-managed folder and receive browser form submissions as JSON lines.
+description: Give a human a temporary live preview of an agent-managed folder and receive browser form submissions as JSON lines.
 ---
 
 # LetMeKnow
 
-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 serves that folder directly, connects to the public relay over an outbound WebSocket, and reports browser submissions on stdout.
-
-The CLI does **not** listen on a local network port.
+Use LetMeKnow when a human needs to inspect or interact with a temporary page, report, dashboard, approval form, quiz, table, or status view. You own the files in a dedicated preview folder. The CLI serves that folder through the hosted LetMeKnow relay and reports browser submissions on stdout. It does not listen on a local network port.
 
 ## Start
 
-Run the CLI as a long-lived child process with the folder you will edit:
+Pass only the files intended for public viewing in an explicit directory:
 
 ```bash
-npx letmeknow-cli ./workspace
+npx letmeknow-cli ./preview
 ```
 
-Node.js 22.12 or newer is required. Read stdout and stderr separately. Stdout is JSONL; the first event is:
+Node.js 22.12 or newer is required. Keep the process running while the human uses the page. Read stdout and stderr separately. Stdout is JSONL; the first event is:
 
 ```json
 {"type":"ready","url":"https://0123456789abcdef0123.letmeknow.dev/"}
 ```
 
-Open that 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.
-
-Do not send file commands to stdin. Read and write the folder directly. Keep the process running while the human uses the page.
-
-## Build the page
+Give the human the URL. It is a bearer capability, so anyone with it can view the preview and submit forms. Multiple browsers may view the session. `--skill` prints these instructions without starting a session.
 
-Create an ordinary static page in the folder, usually `index.html`, plus any CSS, JavaScript, images, or other assets it needs. Use relative asset URLs so path-based preview URLs work. Use semantic HTML and accessible labels, headings, sections, tables, and controls.
+## Build the preview
 
-The relay serves exact files and directory `index.html` files. It supports GET and HEAD, redirects directory paths to a trailing slash, and does not provide an application-shell fallback. HTML responses include the live-preview client inline.
+Create an ordinary static site in the folder, usually `index.html`, with its CSS, JavaScript, images, and other assets. Use semantic HTML, accessible labels, and relative asset URLs. Use normal links for navigation.
 
-The preview continuously saves each page's form values, checked controls, selections, focus, text selection, scroll position, and open `<details>` elements in the tab's session storage. It restores them after file-triggered and user-triggered reloads.
+The relay injects the browser runtime into HTML. All files in the folder form one live workspace. Changes made in a short burst become one revision, and connected browsers perform a full-page reload. The runtime preserves scroll position and values, checked state, and selected state for controls with stable, unique `id` attributes.
 
-The preview is live:
-
-- A change to the current HTML route reloads the page with its saved state.
-- CSS changes cache-bust matching linked stylesheets without navigating.
-- Changes to a different HTML route do not disturb the current page.
-- Changes to other assets reload the page. Arbitrary JavaScript heap state cannot be preserved.
-
-An optional status element gives the human feedback after a form submission:
-
-```html
-<p data-letmeknow-status aria-live="polite"></p>
-```
+A missing page displays a live 404 page that can recover when you create the page. Connection status pages reconnect and recover when the producer is available again.
 
 ## Receive form submissions
 
-GET and POST forms are intercepted before navigation and sent through the relay to the CLI. Read stdout for a `submit` event:
+Use native GET and POST forms with relative or same-origin actions:
 
 ```html
 <form id="search" action="/search" method="post">
@@ -59,40 +42,32 @@ GET and POST forms are intercepted before navigation and sent through the relay
 </form>
 ```
 
-The event is:
+The runtime provides automatic transport feedback: **Sending…** or **Uploading…**, **Sent. Waiting for an update…**, or **Couldn’t send. Try again.** Add `[data-letmeknow-status]` for a custom status location. The transport accepts submissions asynchronously with `202 Accepted`.
+
+Read stdout for a `submit` event:
 
 ```json
 {"type":"submit","id":"…","method":"POST","action":"/search","form_id":"search","trigger":{"id":null,"name":"scope","value":"all"},"values":{"query":"quarterly report","scope":"all"}}
 ```
 
-Rules:
+Give forms stable IDs and controls meaningful `name` values. Native browser validation runs before delivery, and repeated names become arrays. POST forms may include file inputs within the 1 MiB total submission limit. Attachment metadata includes a local temporary path that remains readable until the CLI stops; treat the filename, media type, and contents as untrusted. Attachments are private unless you deliberately copy them into the preview folder.
 
-- 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.
+The event ID identifies the submission, not a response channel: validate the values and attachments, update the files, and let the next workspace revision show the result. Do not write commands to stdin.
 
-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.
+## Example workflow
 
-## Example response workflow
-
-1. Render the initial state in `index.html`.
+1. Build the initial page 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 agent updates the live preview.
+3. Validate its values and action.
+4. Rewrite the relevant HTML or data file in the preview folder.
+5. Let the workspace revision reload the human's page.
 
-Escape untrusted values before placing them in HTML. Treat browser input as untrusted even though the folder is local to the agent.
+Escape untrusted values before placing them in HTML.
 
 ## Security
 
-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.
-
-The selected folder is resolved with real paths, and requests cannot escape it through symlinks. `.env` files, `.git`, private-key files, and database files are denied. The CLI makes outbound relay connections only; it does not accept inbound browser connections.
+The preview folder is public and is trusted code from the browser's perspective. Keep secrets and unrelated project files elsewhere. The CLI restricts requests to the selected directory and excludes `.env`, `.git`, private-key, and database files. Treat every process with write access to the preview folder as a trusted publisher. The CLI makes outbound relay connections only and accepts no inbound browser connections.
 
 ## Stop
 
-Send `SIGINT` or `SIGTERM` to stop the CLI. The relay session expires after producer disconnect. `--skill` prints these instructions without starting a session.
+Send `SIGINT` or `SIGTERM` to close the session. After an unexpected disconnect, the CLI can reconnect to the session for up to ten minutes. Diagnostics go to stderr; stdout remains JSONL.

package/bin/letmeknow.js

@@ -1,124 +1,31 @@
 #!/usr/bin/env node
 
-import { existsSync, readFileSync, statSync, watch, writeSync } from "node:fs";
-import { readFile, realpath, stat } from "node:fs/promises";
-import { dirname, extname, relative, resolve, sep } from "node:path";
+import { constants, existsSync, readFileSync, statSync, writeSync } from "node:fs";
+import { mkdtemp, open, realpath, rm, stat, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { tmpdir } from "node:os";
+import { dirname, extname, join, relative, resolve, sep } from "node:path";
+import { parseArgs } from "node:util";
+import chokidar from "chokidar";
+import { lookup } from "mrmime";
 
 const MAX_BODY_BYTES = 1024 * 1024;
 const GRACE_SECONDS = 10 * 60;
 const CONNECTION_TIMEOUT = 10_000;
 const MAX_RETRY_DELAY = 5_000;
+const REVISION_QUIET_MS = 200;
+const CONTROL_URL = "https://letmeknow.dev";
 const credentialPattern = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
-const mimeTypes = {
-  ".avif": "image/avif",
-  ".css": "text/css; charset=utf-8",
-  ".csv": "text/csv; charset=utf-8",
-  ".gif": "image/gif",
-  ".html": "text/html; charset=utf-8",
-  ".ico": "image/x-icon",
-  ".jpeg": "image/jpeg",
-  ".jpg": "image/jpeg",
-  ".js": "text/javascript; charset=utf-8",
-  ".json": "application/json; charset=utf-8",
-  ".map": "application/json; charset=utf-8",
-  ".mjs": "text/javascript; charset=utf-8",
-  ".pdf": "application/pdf",
-  ".png": "image/png",
-  ".svg": "image/svg+xml",
-  ".txt": "text/plain; charset=utf-8",
-  ".wasm": "application/wasm",
-  ".webmanifest": "application/manifest+json; charset=utf-8",
-  ".webp": "image/webp",
-  ".woff": "font/woff",
-  ".woff2": "font/woff2",
-  ".xml": "application/xml; charset=utf-8"
-};
-const client = String.raw`
-const sessionMatch=location.pathname.match(/^\/s\/[a-f0-9]{20}(?:\/|$)/);
-const sessionBase=sessionMatch?(sessionMatch[0].endsWith("/")?sessionMatch[0]:sessionMatch[0]+"/"):"/";
-const credentialKey="letmeknow-credential:"+location.origin+sessionBase;
-const snapshotKey=()=>credentialKey+":state:"+pageIdentity();
-let credential;
-try{credential=sessionStorage.getItem(credentialKey)}catch{}
-let socket;
-let retryTimer;
-let updateTimer;
-let reloadTimer;
-let terminal=false;
-const controls=()=>[...document.querySelectorAll("button,input,select,textarea")];
-const details=()=>[...document.querySelectorAll("details")];
-const uniqueId=(element,all)=>element.id&&all.filter(candidate=>candidate.id===element.id).length===1?element.id:null;
-const formIdentity=form=>form?.id||form?.getAttribute("name")||form?.getAttribute("action")||"document";
-const controlKey=(control,index,all=controls())=>{const id=uniqueId(control,all);if(id)return"id:"+id;const form=control.form;const identity=formIdentity(form)+":"+(control.type||control.localName)+":"+(control.name||"");const occurrence=all.slice(0,index).filter(candidate=>!uniqueId(candidate,all)&&formIdentity(candidate.form)+":"+(candidate.type||candidate.localName)+":"+(candidate.name||"")===identity).length;return"control:"+identity+":"+occurrence};
-const detailKey=(element,index,all=details())=>{const id=uniqueId(element,all);return id?"id:"+id:"detail:"+index};
-const pageIdentity=()=>location.pathname+location.search+location.hash;
-const snapshot=()=>{const all=controls();return{version:1,page:pageIdentity(),controls:all.map((control,index)=>({key:controlKey(control,index,all),value:control.value,checked:control.checked,indeterminate:control.indeterminate,selected:control instanceof HTMLSelectElement?[...control.options].map((option,optionIndex)=>option.selected?optionIndex:null).filter(optionIndex=>optionIndex!==null):undefined,start:typeof control.selectionStart==="number"?control.selectionStart:undefined,end:typeof control.selectionEnd==="number"?control.selectionEnd:undefined,direction:control.selectionDirection||undefined})),active:document.activeElement instanceof Element?controlKey(document.activeElement,all.indexOf(document.activeElement),all):undefined,details:details().map((element,index)=>({key:detailKey(element,index),open:element.open})),x:scrollX,y:scrollY}};
-const status=message=>{const element=document.querySelector("[data-letmeknow-status]");if(element)element.textContent=message};
-const stripSessionPath=path=>{if(sessionBase==="/")return path;if(path===sessionBase.slice(0,-1))return "/";return path.startsWith(sessionBase)?"/"+path.slice(sessionBase.length):path};
-const routePath=()=>{let path=stripSessionPath(location.pathname);return path.endsWith("/")?path+"index.html":path};
-const pagePath=path=>{path=path.split("?",1)[0];return stripSessionPath(path)||"/"};
-const save=()=>{try{sessionStorage.setItem(snapshotKey(),JSON.stringify(snapshot()))}catch{}};
-const restore=()=>{let raw;try{raw=sessionStorage.getItem(snapshotKey())}catch{return}if(!raw)return;let saved;try{saved=JSON.parse(raw)}catch{return}if(saved.version!==1||saved.page!==pageIdentity())return;const all=controls();const savedControls=new Map((Array.isArray(saved.controls)?saved.controls:[]).map(state=>[state.key,state]));let active;for(const [index,control] of all.entries()){const state=savedControls.get(controlKey(control,index,all));if(!state)continue;if(control instanceof HTMLSelectElement&&Array.isArray(state.selected))for(const [optionIndex,option] of [...control.options].entries())option.selected=state.selected.includes(optionIndex);else if(control.type==="checkbox"||control.type==="radio"){control.checked=state.checked;control.indeterminate=state.indeterminate}else{control.value=state.value;if(typeof state.start==="number"&&typeof control.setSelectionRange==="function")control.setSelectionRange(state.start,state.end,state.direction||"none")}if(controlKey(control,index,all)===saved.active)active=control}const savedDetails=new Map((Array.isArray(saved.details)?saved.details:[]).map(state=>[state.key,state]));for(const [index,element] of details().entries()){const state=savedDetails.get(detailKey(element,index));if(state)element.open=state.open}active?.focus({preventScroll:true});scrollTo(saved.x||0,saved.y||0)};
-const reload=()=>{if(reloadTimer)return;reloadTimer=setTimeout(()=>{save();location.reload()},75)};
-const linkedStylesheet=path=>{for(const link of document.querySelectorAll('link[rel~="stylesheet"]')){let url;try{url=new URL(link.href,location.href)}catch{continue}if(url.origin!==location.origin)continue;if(sessionBase!=="/"&&!url.pathname.startsWith(sessionBase))continue;if(pagePath(url.pathname)===path)return link}return null};
-const refreshStylesheet=link=>{const url=new URL(link.href,location.href);url.searchParams.set("_letmeknow",crypto.randomUUID());link.href=url.href};
-const flushUpdates=()=>{updateTimer=undefined;const paths=[...pendingUpdates];pendingUpdates.clear();let shouldReload=false;const styles=[];for(const path of paths){if(/\.html?$/i.test(path)){if(path===routePath())shouldReload=true}else if(/\.css$/i.test(path)){const link=linkedStylesheet(path);if(link)styles.push([path,link]);else shouldReload=true}else shouldReload=true}if(shouldReload){reload();return}for(const [,link] of styles)refreshStylesheet(link)};
-const pendingUpdates=new Set();
-const update=path=>{if(typeof path!=="string")return;path=pagePath(path);pendingUpdates.add(path);if(!updateTimer)updateTimer=setTimeout(flushUpdates,75)};
-let saveTimer;
-const scheduleSave=()=>{if(!saveTimer)saveTimer=setTimeout(()=>{saveTimer=undefined;save()},100)};
-addEventListener("input",scheduleSave,true);
-addEventListener("change",scheduleSave,true);
-addEventListener("toggle",scheduleSave,true);
-addEventListener("focusin",scheduleSave,true);
-addEventListener("selectionchange",scheduleSave,true);
-addEventListener("scroll",scheduleSave,{passive:true});
-addEventListener("pagehide",save);
-addEventListener("load",()=>requestAnimationFrame(restore),{once:true});
-document.addEventListener("reset",()=>setTimeout(save));
-const connect=()=>{
-  clearTimeout(retryTimer);retryTimer=undefined;
-  const url=new URL(sessionBase+"_letmeknow/client",location.href);url.protocol=url.protocol==="https:"?"wss:":"ws:";
-  const current=credential?new WebSocket(url,credential):new WebSocket(url);
-  socket=current;
-  current.onmessage=event=>{
-    if(socket!==current||typeof event.data!=="string")return;
-    let message;try{message=JSON.parse(event.data)}catch{return}
-    if(message.type==="credential"){credential=message.credential;try{sessionStorage.setItem(credentialKey,credential)}catch{}return}
-    if(message.type==="challenge"){if(current.readyState===WebSocket.OPEN)try{current.send(JSON.stringify({type:"alive",nonce:message.nonce}))}catch{}return}
-    if(message.type==="busy"){status("This session is open elsewhere");retryTimer=setTimeout(connect,message.retry_after*1000);return}
-    if(message.type==="file_update"){update(message.path);return}
-    if(message.type==="closed"){terminal=true;try{sessionStorage.removeItem(credentialKey)}catch{}status(message.message)}
-  };
-  current.onclose=()=>{if(socket!==current||terminal)return;if(!retryTimer){status("Reconnecting…");retryTimer=setTimeout(connect,1000)}};
-  current.onerror=()=>{};
-};
-document.addEventListener("submit",async event=>{
-  const form=event.target;
-  if(!(form instanceof HTMLFormElement))return;
-  event.preventDefault();
-  const submitter=event.submitter;
-  const method=(submitter?.getAttribute("formmethod")??form.getAttribute("method")??"get").toLowerCase();
-  if(method!=="get"&&method!=="post"){status("Only GET and POST forms are supported");return}
-  if(!form.checkValidity()){form.reportValidity();return}
-  let target;
-  try{const action=submitter?.getAttribute("formaction")??form.getAttribute("action")??location.href;const base=sessionBase!=="/"&&location.pathname===sessionBase.slice(0,-1)?new URL(sessionBase,location.href):location.href;target=new URL(action,base)}catch{status("Invalid form action");return}
-  if(target.origin!==location.origin){status("Form actions must stay on this site");return}
-  if(sessionBase!=="/"){
-    const sessionPath=sessionBase.slice(0,-1);
-    if(target.pathname===sessionPath)target.pathname=sessionBase;
-    else if(!target.pathname.startsWith(sessionBase))target.pathname=sessionBase+target.pathname.replace(/^\//,"");
-  }
-  const values=new URLSearchParams();
-  for(const [name,value] of new FormData(form,submitter)){if(typeof value!=="string"){status("File inputs are not supported");return}values.append(name,value)}
-  const actionPath=sessionBase!=="/"?target.pathname.slice(sessionBase.length-1)||"/":target.pathname;
-  const metadata={id:crypto.randomUUID(),form_id:form.id||null,action:actionPath+target.search,trigger:{id:submitter?.id||null,name:submitter?.getAttribute("name"),value:submitter?.getAttribute("value")}};
-  const headers={"X-LetMeKnow-Submission":"1","X-LetMeKnow-ID":encodeURIComponent(metadata.id),"X-LetMeKnow-Form-ID":encodeURIComponent(metadata.form_id??""),"X-LetMeKnow-Action":encodeURIComponent(metadata.action),"X-LetMeKnow-Trigger-ID":encodeURIComponent(metadata.trigger.id??""),"X-LetMeKnow-Trigger-Name":encodeURIComponent(metadata.trigger.name??""),"X-LetMeKnow-Trigger-Value":encodeURIComponent(metadata.trigger.value??"")};
-  if(method==="get")for(const [name,value] of values)target.searchParams.append(name,value);
-  try{const response=await fetch(target,{method:method.toUpperCase(),headers,...(method==="post"?{body:values}:{})});if(!response.ok)throw new Error();status("Submitted")}catch{status("The submission failed")}
-});
-connect();
-`;
+const privateNames = new Set([".env", ".git", ".ssh", "id_rsa", "id_ed25519", "id_ecdsa", "id_dsa"]);
+const privateFilePattern = /^\.env\.|\.(?:key|pem|p12|ppk|p8|sqlite|sqlite3|db|db3)$|-(?:wal|shm|journal)$/i;
+
+function getMimeType(filename) {
+  const type = lookup(filename);
+  if (!type) return "application/octet-stream";
+  return type.startsWith("text/") || type === "application/json" || type === "application/xml" || type === "application/manifest+json"
+    ? `${type}; charset=utf-8`
+    : type;
+}
 
 function header(packet, name) {
   const entry = Object.entries(packet.headers || {}).find(([key]) => key.toLowerCase() === name);
@@ -149,7 +56,7 @@ function errorResponse(packet, status, message) {
 }
 
 function deniedPath(pathname) {
-  return pathname.split("/").some(part => part === ".env" || part.startsWith(".env.") || part === ".git" || /\.(?:key|pem|p12|sqlite|db)$/i.test(part));
+  return pathname.split("/").filter(Boolean).some(part => privateNames.has(part) || privateFilePattern.test(part));
 }
 
 function inside(root, target) {
@@ -184,13 +91,6 @@ function requestUrl(packet) {
   return { pathname, encodedPathname: url.pathname, search: url.search };
 }
 
-function htmlWithClient(body) {
-  const text = body.toString("utf8");
-  const script = `<script type="module" data-letmeknow-client>${client}</script>`;
-  const closingBody = text.search(/<\/body\s*>/i);
-  return Buffer.from(closingBody < 0 ? text + script : text.slice(0, closingBody) + script + text.slice(closingBody), "utf8");
-}
-
 async function staticResponse(root, packet) {
   const method = typeof packet.method === "string" ? packet.method.toUpperCase() : "";
   if (method !== "GET" && method !== "HEAD") return errorResponse(packet, 405, "method not allowed");
@@ -211,8 +111,8 @@ async function staticResponse(root, packet) {
     return errorResponse(packet, 500, "preview request failed");
   }
   if (info.isDirectory()) {
-    if (!request.pathname.endsWith("/")) {
-      const location = request.encodedPathname + "/" + request.search;
+    if (!request.encodedPathname.endsWith("/")) {
+      const location = request.encodedPathname.slice(request.encodedPathname.lastIndexOf("/") + 1) + "/" + request.search;
       return response(packet, 301, Buffer.from(`Redirecting to ${location}`), { Location: location, "Content-Type": "text/plain; charset=utf-8" });
     }
     const index = resolve(target, "index.html");
@@ -222,31 +122,73 @@ async function staticResponse(root, packet) {
     }
     if (!inside(root, target)) return errorResponse(packet, 403, "forbidden");
     if (deniedPath("/" + relative(root, target).split(sep).join("/"))) return errorResponse(packet, 403, "forbidden");
+    try { info = await stat(target); } catch (cause) {
+      if (cause?.code === "ENOENT" || cause?.code === "ENOTDIR") return errorResponse(packet, 404, "not found");
+      if (cause?.code === "EACCES" || cause?.code === "EPERM") return errorResponse(packet, 403, "forbidden");
+      return errorResponse(packet, 500, "preview request failed");
+    }
   } else if (request.pathname.endsWith("/")) return errorResponse(packet, 404, "not found");
-  let body;
-  try { body = await readFile(target); } catch (cause) {
+  let file;
+  try { file = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW); } catch (cause) {
     if (cause?.code === "ENOENT" || cause?.code === "ENOTDIR") return errorResponse(packet, 404, "not found");
-    if (cause?.code === "EACCES" || cause?.code === "EPERM") return errorResponse(packet, 403, "forbidden");
+    if (cause?.code === "EACCES" || cause?.code === "EPERM" || cause?.code === "ELOOP") return errorResponse(packet, 403, "forbidden");
     return errorResponse(packet, 500, "preview request failed");
   }
-  if (body.byteLength > MAX_BODY_BYTES) return errorResponse(packet, 413, "response body is too large");
-  if (extname(target).toLowerCase() === ".html") body = htmlWithClient(body);
-  if (body.byteLength > MAX_BODY_BYTES) return errorResponse(packet, 413, "response body is too large");
-  return response(packet, 200, body, { "Content-Type": mimeTypes[extname(target).toLowerCase()] || "application/octet-stream" });
+  try {
+    info = await file.stat();
+    if (!info.isFile()) return errorResponse(packet, 404, "not found");
+    if (info.size > MAX_BODY_BYTES) return errorResponse(packet, 413, "response body is too large");
+    const body = await file.readFile();
+    if (body.byteLength > MAX_BODY_BYTES) return errorResponse(packet, 413, "response body is too large");
+    return response(packet, 200, body, { "Content-Type": getMimeType(target) });
+  } catch {
+    return errorResponse(packet, 500, "preview request failed");
+  } finally {
+    await file.close();
+  }
 }
 
-async function submission(packet) {
+async function multipartSubmission(body, contentType, getAttachmentInbox) {
+  const formData = await new Request("http://letmeknow.local", {
+    method: "POST",
+    headers: { "Content-Type": contentType },
+    body
+  }).formData();
+  const values = Object.create(null);
+  const attachments = [];
+  for (const [name, value] of formData) {
+    if (typeof value === "string") {
+      addValue(values, name, value);
+      continue;
+    }
+    if (value.name === "") continue;
+    const bytes = Buffer.from(await value.arrayBuffer());
+    const path = join(await getAttachmentInbox(), randomUUID());
+    await writeFile(path, bytes, { mode: 0o600, flag: "wx" });
+    attachments.push({ field: name, name: value.name, type: value.type, size: bytes.byteLength, path });
+  }
+  return { values, attachments };
+}
+
+async function submission(packet, getAttachmentInbox) {
   const url = requestUrl(packet);
   const method = typeof packet.method === "string" ? packet.method.toUpperCase() : "";
   const values = Object.create(null);
+  let attachments;
   if (method === "GET") {
     for (const [name, value] of new URLSearchParams(url.search)) addValue(values, name, value);
   } else if (method === "POST") {
     const body = Buffer.from(typeof packet.body === "string" ? packet.body : "", "base64");
     if (body.byteLength > MAX_BODY_BYTES) throw new Error("submission is too large");
-    const contentType = header(packet, "content-type")?.split(";", 1)[0].trim().toLowerCase();
-    if (contentType !== "application/x-www-form-urlencoded") throw new Error("unsupported submission encoding");
-    for (const [name, value] of new URLSearchParams(body.toString("utf8"))) addValue(values, name, value);
+    const contentTypeHeader = header(packet, "content-type");
+    const contentType = contentTypeHeader?.split(";", 1)[0].trim().toLowerCase();
+    if (contentType === "application/x-www-form-urlencoded") {
+      for (const [name, value] of new URLSearchParams(body.toString("utf8"))) addValue(values, name, value);
+    } else if (contentType === "multipart/form-data" && contentTypeHeader) {
+      const parsed = await multipartSubmission(body, contentTypeHeader, getAttachmentInbox);
+      Object.assign(values, parsed.values);
+      attachments = parsed.attachments;
+    } else throw new Error("unsupported submission encoding");
   } else throw new Error("unsupported submission method");
   const event = {
     type: "submit",
@@ -257,41 +199,33 @@ async function submission(packet) {
     trigger: { id: encodedHeader(packet, "x-letmeknow-trigger-id"), name: encodedHeader(packet, "x-letmeknow-trigger-name"), value: encodedHeader(packet, "x-letmeknow-trigger-value") },
     values
   };
+  if (attachments?.length) event.attachments = attachments;
   process.stdout.write(`${JSON.stringify(event)}\n`);
-  return response(packet, 204);
+  return response(packet, 202);
 }
 
-async function handleRequest(root, packet) {
+async function handleRequest(root, packet, getAttachmentInbox) {
   if (header(packet, "x-letmeknow-submission") === "1") {
-    try { return await submission(packet); } catch (cause) { return errorResponse(packet, cause?.message === "submission is too large" ? 413 : 400, cause instanceof Error ? cause.message : "invalid submission"); }
+    try { return await submission(packet, getAttachmentInbox); } catch (cause) { return errorResponse(packet, cause?.message === "submission is too large" ? 413 : 400, cause instanceof Error ? cause.message : "invalid submission"); }
   }
   return staticResponse(root, packet);
 }
 
-function options(args) {
-  let root;
-  for (const argument of args) {
-    if (argument.startsWith("-")) throw new Error(`unknown option: ${argument}`);
-    if (root !== undefined) throw new Error("only one directory may be provided");
-    root = resolve(argument);
-  }
-  root = root || process.cwd();
+function options(directory) {
+  const root = resolve(directory);
   if (!existsSync(root) || !statSync(root).isDirectory()) throw new Error(`directory does not exist: ${root}`);
   return realpath(root).then(root => ({ root }));
 }
 
-function endpoint(control, credential, sessionUrl) {
-  const url = new URL(control);
-  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
-  url.pathname = "/v1/connect";
-  url.search = "";
-  url.hash = "";
+function endpoint(credential, sessionUrl) {
+  const url = new URL(CONTROL_URL);
+  url.protocol = "wss:";
+  url.pathname = "/v2/connect";
   if (credential && sessionUrl) {
     const publicUrl = new URL(sessionUrl);
-    const hostCode = publicUrl.hostname.match(/^([a-f0-9]{20})\.letmeknow\.dev$/);
-    const pathCode = publicUrl.pathname.match(/^\/s\/([a-f0-9]{20})(?:\/|$)/);
-    const code = hostCode?.[1] || pathCode?.[1];
-    if (code) url.searchParams.set("code", code);
+    const code = publicUrl.hostname.match(/^([a-f0-9]{20})\.letmeknow\.dev$/)?.[1];
+    if (!code) throw new Error("invalid session URL");
+    url.searchParams.set("code", code);
   }
   return url;
 }
@@ -300,21 +234,37 @@ function validSessionUrl(value) {
   if (typeof value !== "string") return false;
   let url;
   try { url = new URL(value); } catch { return false; }
-  if (url.protocol !== "http:" && url.protocol !== "https:") return false;
-  if (/^[a-f0-9]{20}\.letmeknow\.dev$/.test(url.hostname)) return true;
-  return /^\/s\/[a-f0-9]{20}(?:\/|$)/.test(url.pathname);
+  return url.protocol === "https:" && /^[a-f0-9]{20}\.letmeknow\.dev$/.test(url.hostname) && url.pathname === "/" && !url.search && !url.hash;
 }
 
-async function start(args) {
-  const { root } = await options(args);
-  const control = process.env.LETMEKNOW_URL || "https://letmeknow.dev";
+async function start(directory) {
+  const { root } = await options(directory);
+  let attachmentInboxPromise;
+  const getAttachmentInbox = () => {
+    attachmentInboxPromise ??= mkdtemp(join(tmpdir(), "letmeknow-attachments-"));
+    return attachmentInboxPromise;
+  };
   let send = () => false;
-  const watcher = watch(root, { recursive: true, encoding: "utf8" }, (_event, filename) => {
-    if (!filename) { send({ type: "file_update", path: "/" }); return; }
+  let revisionTimer;
+  const watchedPath = filename => {
     const file = resolve(root, String(filename));
     const path = relative(root, file).split(sep).join("/");
-    if (!path || path.startsWith("../") || path === ".." || deniedPath("/" + path)) return;
-    send({ type: "file_update", path: "/" + path.split("/").map(encodeURIComponent).join("/") });
+    return path && path !== ".." && !path.startsWith("../") && !deniedPath("/" + path);
+  };
+  const watcher = chokidar.watch(root, {
+    ignoreInitial: true,
+    ignored: filename => {
+      const path = relative(root, resolve(root, String(filename))).split(sep).join("/");
+      return path !== "" && (path === ".." || path.startsWith("../") || deniedPath("/" + path));
+    }
+  });
+  const scheduleRevision = () => {
+    clearTimeout(revisionTimer);
+    revisionTimer = setTimeout(() => { revisionTimer = undefined; send({ type: "revision" }); }, REVISION_QUIET_MS);
+  };
+  watcher.on("all", (_event, filename) => {
+    if (filename && !watchedPath(filename)) return;
+    scheduleRevision();
   });
   let socket;
   let credential;
@@ -330,8 +280,13 @@ async function start(args) {
     stopped = true;
     clearTimeout(retryTimer);
     clearTimeout(connectionTimer);
+    clearTimeout(revisionTimer);
+    send({ type: "close" });
     try { socket?.close(); } catch {}
-    watcher.close();
+    await watcher.close();
+    if (attachmentInboxPromise) {
+      try { await rm(await attachmentInboxPromise, { recursive: true, force: true }); } catch {}
+    }
     process.exit(code);
   };
   process.once("SIGINT", () => void stop(0));
@@ -346,11 +301,11 @@ async function start(args) {
   const connect = () => {
     if (stopped) return;
     const reconnecting = Boolean(credential && sessionUrl);
-    const current = socket = reconnecting ? new WebSocket(endpoint(control, credential, sessionUrl), credential) : new WebSocket(endpoint(control));
+    const current = socket = reconnecting ? new WebSocket(endpoint(credential, sessionUrl), credential) : new WebSocket(endpoint());
     connectionTimer = setTimeout(() => {
       if (socket !== current || current.readyState === WebSocket.OPEN || stopped) return;
       try { current.close(); } catch {}
-      if (reconnecting) retry(); else void stop(1);
+      if (!reconnecting) void stop(1);
     }, CONNECTION_TIMEOUT);
     current.addEventListener("open", () => {
       if (socket !== current || stopped) return;
@@ -375,7 +330,7 @@ async function start(args) {
         sessionUrl = packet.url;
         if (!ready) { ready = true; process.stdout.write(`${JSON.stringify({ type: "ready", url: sessionUrl })}\n`); }
       } else if (packet.type === "http_request") {
-        void handleRequest(root, packet).then(result => send(result)).catch(() => send(errorResponse(packet, 500, "preview request failed")));
+        void handleRequest(root, packet, getAttachmentInbox).then(result => send(result)).catch(() => send(errorResponse(packet, 500, "preview request failed")));
       } else if (packet.type === "closed") {
         void stop(0);
       } else if (packet.type === "error") {
@@ -398,11 +353,29 @@ async function start(args) {
   await new Promise(() => {});
 }
 
-if (process.argv[2] === "--skill") {
-  if (process.argv.length !== 3) { process.stderr.write("Usage: npx letmeknow-cli --skill\n"); process.exit(1); }
+let parsed;
+try {
+  parsed = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+      skill: { type: "boolean" },
+      help: { type: "boolean", short: "h" }
+    },
+    allowPositionals: true
+  });
+} catch (cause) {
+  process.stderr.write(`letmeknow: ${cause instanceof Error ? cause.message : "invalid arguments"}\n`);
+  process.exit(1);
+}
+
+if (parsed.values.skill) {
+  if (parsed.positionals.length > 0) { process.stderr.write("Usage: npx letmeknow-cli --skill\n"); process.exit(1); }
   writeSync(1, readFileSync(new URL("../SKILL.md", import.meta.url)));
-} else if (process.argv.slice(2).includes("--help") || process.argv.slice(2).includes("-h")) {
-  process.stdout.write("Usage: npx letmeknow-cli [directory]\n\nServe a folder through the hosted LetMeKnow relay. The CLI does not listen on a network port. Form submissions are JSON lines on stdout.\n");
+} else if (parsed.values.help) {
+  process.stdout.write("Usage: npx letmeknow-cli <directory>\n\nServe a folder through the hosted LetMeKnow relay. The CLI does not listen on a network port. Form submissions are JSON lines on stdout.\n");
+} else if (parsed.positionals.length !== 1) {
+  process.stderr.write("letmeknow: exactly one directory must be provided\n");
+  process.exit(1);
 } else {
-  try { await start(process.argv.slice(2)); } catch (cause) { process.stderr.write(`letmeknow: ${cause instanceof Error ? cause.message : "server failed"}\n`); process.exitCode = 1; }
+  try { await start(parsed.positionals[0]); } catch (cause) { process.stderr.write(`letmeknow: ${cause instanceof Error ? cause.message : "server failed"}\n`); process.exitCode = 1; }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "letmeknow-cli",
-  "version": "0.4.10",
+  "version": "0.5.0",
   "description": "A live static preview with agent-readable form submissions.",
   "files": [
     "bin",
@@ -17,7 +17,8 @@
     "dev": "wrangler dev",
     "deploy": "wrangler deploy",
     "check": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit",
-    "test": "npm run check && vitest run && node --test tests/cli.test.js tests/integration.test.js"
+    "test": "npm run check && vitest run && node --test tests/cli.test.js",
+    "test:browser": "node --test tests/browser.test.js"
   },
   "devDependencies": {
     "@cloudflare/vitest-plugin": "^1.1.0",
@@ -27,5 +28,9 @@
     "vitest": "^4.1.11",
     "wrangler": "^4.126.0",
     "ws": "^8.21.3"
+  },
+  "dependencies": {
+    "chokidar": "^5.0.0",
+    "mrmime": "^2.0.1"
   }
 }