mirror of
https://github.com/pbakaus/impeccable.git
synced 2026-09-12 06:06:37 +03:00
Sync generated provider output
This commit is contained in:
github-actions[bot]
@@ -0,0 +1,102 @@
|
||||
One-time live-mode project setup. Loaded from [live.md](live.md) only when `live.mjs` reports `config_missing` / `config_invalid`, when `configDrift` needs handling, or when the config lacks `cspChecked`. Not part of the per-session hot path.
|
||||
|
||||
## Write the config
|
||||
|
||||
Create the file at the `path` the boot reported (default `.impeccable/live/config.json`):
|
||||
|
||||
```json
|
||||
{
|
||||
"files": ["<path-or-glob>", "<path-or-glob>", ...],
|
||||
"exclude": ["<optional-glob>", ...],
|
||||
"insertBefore": "</body>",
|
||||
"commentSyntax": "html",
|
||||
"cspChecked": true
|
||||
}
|
||||
```
|
||||
|
||||
`files` is the inject target: **the HTML files the browser actually loads**, not necessarily source (tracked vs generated does not matter here; wrap has its own generated-file guard). Entries are literal paths or globs. `exclude` (optional) skips files a `files` glob would otherwise include (email templates, demo fixtures). `cspChecked` records that the CSP step below has run; absent on first setup.
|
||||
|
||||
**Hard-excluded paths (cannot be overridden):** `**/node_modules/**` and `**/.git/**`; injecting there would instrument third-party code.
|
||||
|
||||
**Glob syntax:** `**` matches any number of segments (including zero), `*` matches within a segment, `?` matches one character. Paths are project-root-relative with forward slashes.
|
||||
|
||||
| Framework | `files` | `insertBefore` | `commentSyntax` |
|
||||
|-----------|---------|----------------|-----------------|
|
||||
| SPA with single shell (Vite / React / Plain HTML) | `["index.html"]` | `</body>` | `html` |
|
||||
| Next.js (App Router) | `["app/layout.tsx"]` | `</body>` | `jsx` |
|
||||
| Next.js (Pages) | `["pages/_document.tsx"]` | `</body>` | `jsx` |
|
||||
| Nuxt | `["app.vue"]` | `</body>` | `html` |
|
||||
| Svelte / SvelteKit | `["src/app.html"]` | `</body>` | `html` |
|
||||
| TanStack Router (SPA, Vite) | `["index.html"]` | `</body>` | `html` |
|
||||
| TanStack Start (SSR) | `["src/routes/__root.tsx"]` | `<Scripts` | `jsx` |
|
||||
| Astro | `[" <root layout .astro>"]` | `</body>` | `html` |
|
||||
| Multi-page (separate HTML per route) | `["public/**/*.html"]` glob over the served dir | `</body>` | `html` |
|
||||
|
||||
Pick an anchor that exists in every file (`</body>` almost always works); `insertAfter` matches after a line instead. For multi-page sites prefer a glob so new pages are picked up automatically. For sites whose pages are rebuilt by a generator, the inject survives only until the next regeneration: re-run `live.mjs` after each build (accept is unaffected; it writes true source via the fallback flow).
|
||||
|
||||
**Framework adapters (auto-detected at inject time).** Every inject records what it wrote in `.impeccable/live/inject-journal.json`; the next inject or remove heals artifacts a crash or wrong-directory stop left behind. SvelteKit, Nuxt, and TanStack Start server-render their document shell, so a raw `<script>` in the entry template will not execute reliably; `live-inject.mjs` detects them and routes to a dedicated adapter (SvelteKit: dev-only root component from `+layout.svelte`; Nuxt: dev-only `.client.ts` plugin; TanStack Start: a generated dev-only `ImpeccableLiveRoot` component in `__root`). The `files` value stays a valid detection/CSP hint but is not the literal insertion site. A plain TanStack Router SPA takes the baseline Vite path.
|
||||
|
||||
## Config drift
|
||||
|
||||
On every boot the project is scanned for HTML files under common page roots (`public/`, `src/`, `app/`, `pages/`) that the resolved `files` list does not cover; they surface as `configDrift.orphans` with a hint. Tell the user once per session which files are uncovered and offer to add them or switch `files` to a glob. Never auto-update the config; the user decides. `configDrift` is `null` when there is no drift.
|
||||
|
||||
## CSP detection (first-time only)
|
||||
|
||||
If `config.cspChecked === true`, skip this whole section; the user was already asked once.
|
||||
|
||||
```bash
|
||||
node .agents/skills/impeccable/scripts/detect-csp.mjs
|
||||
```
|
||||
|
||||
Output `{ shape, signals }`; the shape names the *patch mechanism*, so one template covers many frameworks:
|
||||
|
||||
- **`null`**: no CSP; write the config with `cspChecked: true` and stop here.
|
||||
- **`append-arrays`**: CSP as structured directive arrays; auto-patchable (monorepo helpers with `additionalScriptSrc`/`additionalConnectSrc`, SvelteKit `kit.csp.directives`, Nuxt `nuxt-security`).
|
||||
- **`append-string`**: CSP as a literal value string; auto-patchable (inline `next.config.*` `headers()`, Nuxt `routeRules`).
|
||||
- **`middleware`** / **`meta-tag`**: detected but not auto-patched. Show the user the detected files, ask them to add `http://localhost:8400` to `script-src` and `connect-src` manually, then mark `cspChecked: true` and proceed.
|
||||
|
||||
### Consent prompt (use this phrasing)
|
||||
|
||||
> **CSP patch needed.** I detected a Content Security Policy in your project that blocks `http://localhost:8400`: the live picker won't load without an allowance. Here's the change I'd make:
|
||||
>
|
||||
> ```diff
|
||||
> [file: <patchTarget>]
|
||||
> [exact diff, 2-5 lines]
|
||||
> ```
|
||||
>
|
||||
> It's guarded by `NODE_ENV === "development"` so the extra entry only appears in dev and never reaches production. You can remove it any time by reverting this file. Apply? [y/n]
|
||||
|
||||
On "no": skip the patch, note that live will not work until the allowance is added manually, and still write `cspChecked: true` (the question has been asked). On "yes": apply the shape's patch below, then write `cspChecked: true`.
|
||||
|
||||
### append-arrays
|
||||
|
||||
Declare near the top of the file that holds the CSP arrays, then append `...__impeccableLiveDev` to the script-src and connect-src arrays:
|
||||
|
||||
```ts
|
||||
// Dev-only allowance so impeccable live mode can load. Guarded by NODE_ENV.
|
||||
const __impeccableLiveDev =
|
||||
process.env.NODE_ENV === "development" ? ["http://localhost:8400"] : [];
|
||||
```
|
||||
|
||||
Per-framework: Next.js + monorepo helper: edit the *app's* `next.config.*` (not the shared helper), appending to `additionalScriptSrc` / `additionalConnectSrc`. SvelteKit: `svelte.config.js`, `kit.csp.directives['script-src']` and `['connect-src']`. Nuxt + nuxt-security: `nuxt.config.*`, `security.headers.contentSecurityPolicy['script-src']` and `['connect-src']`. Reference outputs: `tests/framework-fixtures/nextjs-turborepo/expected-after-patch.ts`, `tests/framework-fixtures/sveltekit-csp/expected-after-patch.js`. Idempotency: if `__impeccableLiveDev` already exists in the file, the patch is applied; just mark `cspChecked: true`.
|
||||
|
||||
### append-string
|
||||
|
||||
Two-point patch: declare a dev-only string, interpolate it into the CSP value at both directives (leading space so it concatenates cleanly; convert literals to template strings as part of the edit):
|
||||
|
||||
```ts
|
||||
// Dev-only allowance so impeccable live mode can load.
|
||||
const __impeccableLiveDev =
|
||||
process.env.NODE_ENV === "development" ? " http://localhost:8400" : "";
|
||||
```
|
||||
|
||||
- `script-src 'self' 'unsafe-inline'` becomes `` `script-src 'self' 'unsafe-inline'${__impeccableLiveDev}` ``
|
||||
- `connect-src 'self'` becomes `` `connect-src 'self'${__impeccableLiveDev}` ``
|
||||
|
||||
Per-framework: Next.js inline `headers()` in `next.config.*`; Nuxt `routeRules['/**'].headers['Content-Security-Policy']` in `nuxt.config.*`. Reference outputs: `tests/framework-fixtures/nextjs-inline-csp/expected-after-patch.js`, `tests/framework-fixtures/nuxt-csp/expected-after-patch.ts`.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the user said "no" to the CSP patch and later reports live not working: their dev CSP blocks `http://localhost:8400`. Delete `cspChecked` from `.impeccable/live/config.json` and re-run `live.mjs`; setup asks again.
|
||||
|
||||
After setup, re-run `live.mjs`.
|
||||
@@ -2,52 +2,35 @@ Interactive live variant mode: select elements in the browser, pick a design act
|
||||
|
||||
## Prerequisites
|
||||
|
||||
A running dev server with hot module replacement (Vite, Next.js, Bun, etc.), OR a static HTML file open in the browser.
|
||||
A running dev server with HMR (Vite, Next.js, Bun, etc.), OR a static HTML file open in the browser. If the dev server's default port is busy, the app is very likely ALREADY running; probe the default URL before spawning a second server.
|
||||
|
||||
Codex: run live helper commands, the app dev server, and any dependency-installing setup with `sandbox_permissions: "require_escalated"` from the start; live mode depends on localhost and package-manager network access that the sandbox blocks.
|
||||
|
||||
## The contract (read once)
|
||||
|
||||
Execute in order. No step skipped, no step reordered.
|
||||
Execute in order. No step skipped, no step reordered. Every tool output in live mode may carry an `_instructions` field: it is the authoritative next step for that exact situation, with real ids and paths substituted; when it conflicts with your recollection of this document, `_instructions` wins.
|
||||
|
||||
1. `live.mjs`: boot. If the request names or implies a file, route, or app inside a monorepo, infer the concrete path and run `node .agents/skills/impeccable/scripts/live.mjs --target <path>` instead; then run the rest of this live session from the returned `projectRoot`.
|
||||
1. `live.mjs`: boot. If the request names or implies a file, route, or app inside a monorepo, infer the concrete path and run `node .agents/skills/impeccable/scripts/live.mjs --target <path>` instead; then run the rest of this live session from the returned `projectRoot`. The boot resolves the app root from dev-server config files and persists it in `.impeccable/live/roots.json`; every helper re-anchors to that manifest at startup (a wrong cwd cannot fork session state), PRODUCT.md / DESIGN.md are discovered upward to the git root, and relative helper args like `--file` resolve against the app root.
|
||||
2. Open the app URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). Never use `serverPort`; it's the helper, not the app. **Cursor:** `browser_navigate` to that URL before polling; do not skip. **Other harnesses:** use the available browser tool; if the URL is uncertain, ask the user once.
|
||||
3. Poll loop with the default long timeout (600000 ms). Run `live-poll.mjs` again immediately after every event or `--reply`; Codex runs this one-shot poll in the foreground. Never pass a short `--timeout=`.
|
||||
|
||||
The global bar **Impeccable mark** dims and shows a pulsing amber dot when no agent is long-polling `/poll`. Hover the mark for the hint; restart `live-poll.mjs` to reconnect.
|
||||
4. On `generate`: reuse `event.scaffold` when present; read the screenshot if present; load the action's reference; deliver variants using the delivery policy below; `--reply done`; poll again. Generate in this thread. You already hold the project's tokens, conventions, and file layout; that context is the job, not overhead. During a live cycle the overlay's preview IS the verification channel: the user sees every variant rendered in their real page and picks. Do not screenshot, re-render, or QA variants between generate and accept; apply craft-floor's contrast, spacing, and type floors by construction as you write, not as a post-write inspection pass. Full verification, computed contrast, breakpoints, real-copy overflow, runs once at accept on the chosen variant during carbonize cleanup.
|
||||
5. On `steer`: read the message and `pageUrl`; do the work (page edits, navigation help, or a short reply in the `--reply` message); `--reply steer_done`; poll again. No pickup ack. The Steer bar unlocks when `steer_done` arrives over SSE.
|
||||
6. On `accept` / `discard`: the poll script runs `live-accept.mjs`, acknowledges the delivered event, and prints `_completionAck`. Plain accepts/discards are terminal immediately. Carbonize accepts remain recoverable until the foreground task runs `live-complete.mjs --id EVENT_ID`; finish that cleanup before polling again.
|
||||
7. If interrupted, run `live-status.mjs` or `live-resume.mjs` before guessing. The durable journal replays unacknowledged work after helper restart. A dropped SSE connection or a closed tab does not end the session: the journal under `.impeccable/live/sessions/` is canonical, the injected `live.js` re-attaches when the page reopens, and `live-resume.mjs` replays the active snapshot. Tell the user to reopen the app URL (or restart `live-poll.mjs`) and continue; fall back to the direct-edit loop only when `live-resume.mjs` reports no active session, never because disconnects felt frequent.
|
||||
3. Poll loop with the default long timeout (600000 ms). Run `live-poll.mjs` again immediately after every event or `--reply`; Codex runs this one-shot poll in the foreground. Never pass a short `--timeout=`. The global bar's **Impeccable mark** dims with a pulsing amber dot when nothing is polling `/poll`; restart `live-poll.mjs` to reconnect.
|
||||
4. On `generate`: reuse `event.scaffold` when present; read the screenshot if present; load the action's reference; deliver variants; `--reply done`; poll again. Generate in this thread: you already hold the project's tokens and layout. The overlay preview IS the verification channel; do not screenshot, re-render, or QA variants between generate and accept. Apply craft-floor's contrast, spacing, and type floors by construction as you write; full verification runs once at accept on the chosen variant.
|
||||
5. On `steer`: read the message and `pageUrl`; do the work; `--reply steer_done`; poll again. No pickup ack.
|
||||
6. On `accept` / `discard`: the poll script runs `live-accept.mjs`, acknowledges delivery, and prints `_completionAck`. Plain accepts/discards are terminal immediately; carbonize accepts stay recoverable until `live-complete.mjs --id EVENT_ID` runs. Finish that cleanup before polling again.
|
||||
7. If interrupted, run `live-status.mjs` or `live-resume.mjs` before guessing. The journal under `.impeccable/live/sessions/` is canonical and replays unacknowledged work after a helper restart; the injected `live.js` re-attaches when the page reopens. Fall back to the direct-edit loop only when `live-resume.mjs` reports no active session, never because disconnects felt frequent.
|
||||
8. On `exit`: run the cleanup at the bottom.
|
||||
|
||||
Harness policy:
|
||||
- **Claude Code**: run the poll as a **background task** (no short timeout). The harness notifies you when it completes, so the main conversation stays free while you generate and publish in it. Do not block the shell.
|
||||
- **Cursor**: run **one-shot** poll in a **background terminal** with notify on `"type":"(steer|generate|accept|discard|exit)"`. After each event the poll exits; handle it, `--reply`, then start `live-poll.mjs` again. Do **not** use `--stream` on Cursor: incremental stdout notify is slower in practice than exit-based notify (~5s vs sub-second in testing).
|
||||
- **Codex**: run the default one-shot poll in a **yielded foreground exec session**. Do not suffix it with `&`, use `--stream`, or leave Live without an active foreground poll. Handle every event in the main task; after each handler/reply, restart the foreground poll.
|
||||
- **Other harnesses**: one-shot foreground unless you know stdout reliably returns to this session when a shell exits.
|
||||
- **Claude Code**: run the poll as a **background task** (no short timeout); the harness notifies you on completion. Do not block the shell.
|
||||
- **Cursor**: **one-shot** poll in a **background terminal** with notify on `"type":"(steer|generate|accept|discard|manual_edit_apply|variant_mount_failed|prefetch|exit)"`; handle, `--reply`, restart the poll. Do **not** use `--stream` on Cursor (measured ~5s pickup vs sub-second one-shot).
|
||||
- **Codex**: default one-shot poll in a **yielded foreground exec session**. No `&`, no `--stream`, never leave Live without an active foreground poll. Starting the poll is not enough: SERVICE it (keep reading the exec session until it returns an event). Never announce "waiting for the user" and idle; a yielded poll nobody reads is a dead session, and the user's Go sits unanswered.
|
||||
- **Other harnesses**: one-shot foreground unless you know stdout reliably returns when a shell exits.
|
||||
|
||||
Generation delivery policy:
|
||||
- **Default (Cursor and other harnesses):** keep the established atomic single-edit delivery. Do not switch a harness to progressive until its poll loop is known not to block on the extra publish calls. This avoids trading model latency for extra tool-call latency on harnesses with different streaming behavior.
|
||||
Delivery policy: atomic single-edit delivery everywhere; do not switch a harness to progressive publishing unless its poll loop is known not to block on the extra calls.
|
||||
|
||||
Chat is overhead. No recap, no tutorial output, no pasting PRODUCT / DESIGN bodies. Spend tokens on tools and edits; on failure, one or two short sentences.
|
||||
|
||||
## Start
|
||||
|
||||
```bash
|
||||
node .agents/skills/impeccable/scripts/live.mjs
|
||||
```
|
||||
|
||||
Output JSON: `{ ok, serverPort, serverToken, pageFiles, hasProduct, product, productPath, hasDesign, design, designPath }`. `pageFiles` is the list of HTML entries the live script was injected into. Keep PRODUCT.md, DESIGN.md, and any surface brief already loaded by Setup in mind for variant generation: **DESIGN.md wins on visual decisions; PRODUCT.md wins on durable product and voice decisions; the surface brief wins on this surface's strategy.** When DESIGN.md is missing, identity is **not** absent; extract it from CSS variables, computed styles, and sibling components on the page (see Step 4 Phase A). Identity preservation is the default; departure requires the user's explicit redesign/replacement intent.
|
||||
|
||||
`serverPort` and `serverToken` belong to the small **Impeccable live helper** HTTP server (serves `/live.js`, SSE, and `/poll`). That port is **not** your dev server and is usually not the URL you open to view the app. The browser page is whatever origin serves one of the `pageFiles` entries (Vite / Next / Bun / tunnel / LAN hostname).
|
||||
|
||||
If output is `{ ok: false, error: "config_missing" | "config_invalid", path }`, this project hasn't been configured for live mode (or its config is stale). See **First-time setup** at the bottom.
|
||||
|
||||
## Poll loop
|
||||
|
||||
**Default (portable, all harnesses):**
|
||||
|
||||
```
|
||||
LOOP:
|
||||
node .agents/skills/impeccable/scripts/live-poll.mjs # default long timeout; no --timeout=
|
||||
@@ -59,253 +42,143 @@ LOOP:
|
||||
"discard" → Handle Discard; LOOP
|
||||
"prefetch" → Handle Prefetch; LOOP
|
||||
"manual_edit_apply" → Handle Manual Edit Apply; reply done|partial|error; LOOP
|
||||
"variant_mount_failed" → Fix the variant files; reply done --file <path>; LOOP
|
||||
"timeout" → LOOP
|
||||
"exit" → break → Cleanup
|
||||
```
|
||||
|
||||
**Stream mode (experimental, not for Cursor):**
|
||||
`variant_mount_failed` means the browser could not render what you published (`variant`, module `url`, `error`). The user sees a persistent error card, not variants. Fix the variant files, then `--reply EVENT_ID done --file <manifest or source path>`; the browser retries on its own.
|
||||
|
||||
```
|
||||
node .agents/skills/impeccable/scripts/live-poll.mjs --stream # stays running; one JSON line per event
|
||||
Handle event; run --reply in a separate command
|
||||
Repeat until "exit" line → Cleanup
|
||||
**Stream mode** (`--stream`, experimental, never on Cursor): one long-lived process, one JSON line per event, `--reply` from a separate command. Only for harnesses that read incremental stdout reliably.
|
||||
|
||||
## Start
|
||||
|
||||
```bash
|
||||
node .agents/skills/impeccable/scripts/live.mjs
|
||||
```
|
||||
|
||||
Stream keeps one process alive and waits for `--reply` ack before polling again. Useful only when the harness reads incremental stdout reliably and quickly. **Cursor is not one of those:** background pattern notify on a long-running shell was ~5s to pick up events vs sub-second for one-shot exit notify. Default to one-shot everywhere unless you have measured otherwise.
|
||||
Output JSON: `{ ok, serverPort, serverToken, pageFiles, roots, hasProduct, product, productPath, hasDesign, design, designPath, hasSurfaceBrief, surfaceBrief }`. `roots` is the resolved root manifest; `projectRoot` mirrors `roots.appRoot`. The surface brief rides along; do not shell out to `surface-brief.mjs` separately. Precedence for generation: **DESIGN.md wins on visual decisions; PRODUCT.md wins on durable product and voice decisions; the surface brief wins on this surface's strategy.** When DESIGN.md is missing, identity is **not** absent; extract it from CSS variables, computed styles, and sibling components (Step 4 Phase A). Identity preservation is the default; departure requires the user's explicit redesign intent.
|
||||
|
||||
`serverPort`/`serverToken` belong to the small helper HTTP server (`/live.js`, SSE, `/poll`), not your dev server; the page URL is whatever origin serves a `pageFiles` entry.
|
||||
|
||||
If output is `{ ok: false, error: "config_missing" | "config_invalid", path }`, this project needs one-time configuration: read [live-setup.md](live-setup.md) and follow it. If the output carries a non-null `configDrift`, tell the user once which HTML files are uncovered and suggest adding them or switching `files` to a glob; never auto-edit the config.
|
||||
|
||||
## Recovery commands
|
||||
|
||||
The live helper persists an append-only journal under `.impeccable/live/sessions/`. Browser checkpoints are advisory but durable; the journal is canonical. This is local durable recovery state, not project source.
|
||||
|
||||
Use these commands when the chat was interrupted, polling was missed, the helper restarted, or the browser reloaded:
|
||||
The append-only journal under `.impeccable/live/sessions/` is canonical durable state (not project source). When the chat was interrupted, polling was missed, the helper restarted, or the browser reloaded:
|
||||
|
||||
```bash
|
||||
node .agents/skills/impeccable/scripts/live-status.mjs
|
||||
node .agents/skills/impeccable/scripts/live-resume.mjs --id SESSION_ID
|
||||
node .agents/skills/impeccable/scripts/live-complete.mjs --id SESSION_ID
|
||||
node .agents/skills/impeccable/scripts/live-status.mjs # helper state, active sessions, queued events; works with the helper down
|
||||
node .agents/skills/impeccable/scripts/live-resume.mjs --id SESSION_ID # active snapshot, pending event, next safe action
|
||||
node .agents/skills/impeccable/scripts/live-complete.mjs --id SESSION_ID # canonical manual final acknowledgement after verified cleanup
|
||||
```
|
||||
|
||||
- `live-status.mjs` prints connected helper state, active durable sessions, and queued pending events. It works even when the helper is down by reading the journal directly.
|
||||
- `live-resume.mjs` prints the active snapshot, pending event, checkpoint phase, visible variant, parameter values, and the next safe agent action.
|
||||
- `live-complete.mjs` is the canonical manual final acknowledgement. Use it after carbonize/manual cleanup is verified and no further poll acknowledgement will happen automatically.
|
||||
|
||||
Server restart rule: start `live-server.mjs` again, then poll. Startup requeues unacknowledged pending events from the journal, so do not ask the user to click Go again unless `live-resume.mjs` says no active session exists.
|
||||
Server restart rule: start `live-server.mjs` again, then poll; startup requeues unacknowledged events, so never ask the user to click Go again unless `live-resume.mjs` says no active session exists.
|
||||
|
||||
## Handle `generate`
|
||||
|
||||
**Replace mode** (default): `{id, action, freeformPrompt?, count, pageUrl, element, screenshotPath?, comments?, strokes?}`.
|
||||
|
||||
**Insert mode** (`event.mode === "insert"`): `{id, mode: "insert", count, pageUrl, insert: { position, anchor }, placeholder: { width, height }, freeformPrompt?, screenshotPath?, comments?, strokes?}`. No `action`. Requires a non-empty `freeformPrompt` **or** annotations. Screenshot is sent only when annotations exist (same rule as replace). Use `placeholder` dimensions as a soft size hint for net-new content.
|
||||
**Insert mode** (`event.mode === "insert"`): `{id, mode: "insert", count, pageUrl, insert: { position, anchor }, placeholder: { width, height }, freeformPrompt?, screenshotPath?, comments?, strokes?}`. No `action`; requires a non-empty `freeformPrompt` **or** annotations. `placeholder` is a soft size hint.
|
||||
|
||||
Speed matters; the user is watching the selected element. Reuse server preflight metadata when available, minimize discovery calls, and follow the harness-specific delivery policy above.
|
||||
Speed matters; the user is watching the selected element. Reuse preflight metadata, minimize discovery calls.
|
||||
|
||||
### Insert mode branch
|
||||
|
||||
When `event.mode === "insert"`:
|
||||
|
||||
1. Read the screenshot if `event.screenshotPath` is present (annotations only).
|
||||
2. If `event.scaffold` is present, use it as the insert-helper result and do **not** run the helper again. Otherwise run the insert helper instead of wrap:
|
||||
1. Read the screenshot if present (annotations only).
|
||||
2. If `event.scaffold` is present, use it and do **not** run the helper again. Otherwise:
|
||||
|
||||
```bash
|
||||
node .agents/skills/impeccable/scripts/live-insert.mjs --id EVENT_ID --count EVENT_COUNT --position after \
|
||||
--element-id "ANCHOR_ID" --classes "class1,class2" --tag "section" --text "ANCHOR_TEXT"
|
||||
```
|
||||
|
||||
- `--position` ← `event.insert.position` (`before` | `after`)
|
||||
- Anchor flags ← `event.insert.anchor` (same mapping as wrap: id, classes, tag, text)
|
||||
|
||||
The scaffold has **no** `data-impeccable-variant="original"`. Variants are net-new HTML+CSS inserted at `insertLine`. On source-preview targets the scaffold carries `sourceWritten: false` with `wrapperBlock`, `replaceStartLine`, and `replaceEndLine` (here `replaceEndLine < replaceStartLine`, an insertion): splice your variants into `wrapperBlock` at the marker and insert the result at `replaceStartLine` in one edit, exactly as the wrap section describes, so the framework reloads once. Decide the visitor mode from the surface and load [craft-floor.md](craft-floor.md) before writing net-new markup (freeform only, no action sub-command). Deliver using the harness policy, then `--reply done`.
|
||||
|
||||
For Svelte/SvelteKit targets, `live-insert.mjs` returns `previewMode: "svelte-component"` with `mode: "insert"`, `file` pointing at a temporary `node_modules/.impeccable-live/<id>/manifest.json`, `componentDir` pointing at the variant component files, and `sourceFile` pointing at the real `.svelte` route. Write each inserted variant as a real Svelte component (`v1.svelte`, `v2.svelte`, …) under `componentDir`. Insert variants must be non-empty net-new content with a single top-level root, no `data-impeccable-*` attributes, and CSS in each component's `<style>` block. Do **not** edit the route source during generation; the browser mounts the temporary component before/after the live anchor while the user cycles variants. On Accept, `live-accept.mjs` inserts the selected component markup into `sourceFile` immediately and deletes the temp session after the source write succeeds.
|
||||
|
||||
For non-Svelte targets, on accept/discard, `live-accept.mjs` removes the wrapper block; the anchor element is untouched.
|
||||
`--position` ← `event.insert.position`; anchor flags map exactly like wrap's. The scaffold has **no** `data-impeccable-variant="original"`; variants are net-new HTML+CSS at `insertLine`. On source-preview targets the scaffold carries `sourceWritten: false` with `wrapperBlock` and `replaceEndLine < replaceStartLine` (an insertion): splice variants into `wrapperBlock` at the marker and insert at `replaceStartLine` in ONE edit, exactly as the wrap section describes. Decide the visitor mode from the surface and load [craft-floor.md](craft-floor.md) before writing net-new markup. Svelte targets follow the same component flow as wrap below (`mode: "insert"` in the manifest): each variant is a real single-root component under `componentDir` with no `data-impeccable-*` attributes; never edit the route during generation; accept splices the chosen markup into `sourceFile` mechanically. For non-Svelte targets, accept/discard removes the wrapper; the anchor is untouched.
|
||||
|
||||
### Replace mode (default)
|
||||
|
||||
### 1. Read the screenshot (if present)
|
||||
|
||||
`event.screenshotPath` is **only sent when the user placed at least one comment or stroke before Go.** When present, it's an absolute path to a PNG of the element as rendered with the annotations baked in. **Read it before planning**: annotations encode user intent not recoverable from `element.outerHTML` alone.
|
||||
`event.screenshotPath` is sent **only when the user annotated before Go**; it is a PNG of the element with annotations baked in. Read it before planning. When absent, do not ask for one or screenshot the page yourself: without annotations a screenshot anchors you on the existing design and fights the three-distinct-directions brief; work from `element.outerHTML`, the computed styles, and the prompt.
|
||||
|
||||
When `screenshotPath` is absent, don't ask for one and don't go looking for the current rendering. The omission is deliberate: without annotations, a screenshot would anchor the model on the existing design and fight the three-distinct-directions brief. Work from `element.outerHTML`, the computed styles in `event.element`, and the freeform prompt if present.
|
||||
|
||||
`event.comments` and `event.strokes` carry structured metadata alongside the visual. Treat the screenshot as primary; use the structured data for specifics worth quoting (e.g. the exact text of a comment).
|
||||
|
||||
Reading annotations precisely:
|
||||
|
||||
- **Comment position carries meaning.** Its `{x, y}` is element-local CSS px (same coord space as `element.boundingRect`). Find the child under that point and apply the comment text LOCALLY to that sub-element. A comment near the title is about the title, not a global description.
|
||||
- **Comments and strokes are independent annotations** unless clearly paired by overlap or tight proximity. Don't let the visual weight of a prominent stroke override the precise location of a textually-specific comment elsewhere.
|
||||
- **Strokes are gestures; read them by shape.** Closed loop = "this thing" (emphasis / focus); arrow = direction (move / point to); cross or slash = delete; free scribble = emphasis or delete depending on context. A loop around region X means "pay attention to X," not "only change pixels inside X."
|
||||
- **When a stroke's intent is ambiguous** (circle or arrow? emphasis or move?), state your reading in one sentence of rationale rather than silently guessing. If the uncertainty materially changes the brief, ask one short clarifying question before generating.
|
||||
Annotation semantics: a comment's `{x, y}` is element-local and binds the text to the child under that point (a comment near the title is about the title). Comments and strokes are independent unless clearly paired. Strokes read by shape: closed loop = "this thing" (emphasis, not a clipping region); arrow = direction or movement; cross/slash = delete; scribble = emphasis or delete by context. If a stroke's intent is genuinely ambiguous and it changes the brief, ask one short question before generating; otherwise state your reading in one sentence.
|
||||
|
||||
### 2. Wrap the element
|
||||
|
||||
When `event.scaffold` is present, the local helper already found the source and computed the wrapper before the poll returned. Treat `event.scaffold` as the successful helper output and skip this command entirely. `event.scaffoldAttempted` with `scaffoldError` means local preflight could not finish; use the command/fallback path below. This optimization removes a deterministic tool round trip without changing the generated design.
|
||||
When `event.scaffold` is present, the helper already found the source and computed the wrapper; treat it as the successful output and skip the command. `event.scaffoldAttempted` with `scaffoldError` means preflight could not finish; use the command below.
|
||||
|
||||
**On source-preview targets `event.scaffold` carries `sourceWritten: false`.** The helper did NOT write the wrapper into source; it hands you the wrapper as `scaffold.wrapperBlock` plus the picked element's source range (`scaffold.replaceStartLine`, `scaffold.replaceEndLine`, 1-indexed). Write the wrapper **and** all variants in ONE edit: splice your variants into `wrapperBlock` at the "Variants: insert below this line" marker, then replace source lines `[replaceStartLine, replaceEndLine]` with the result. A separate scaffold write reloads the framework before your variant write lands, and a browser caught mid-reload misses the `done` and sits at 0/N; the single edit avoids it. (`replaceEndLine < replaceStartLine` means insert mode: insert `wrapperBlock`, remove nothing.) The `svelte-component` path never sets `sourceWritten`; it follows the component-preview flow below unchanged.
|
||||
**On source-preview targets `event.scaffold` carries `sourceWritten: false`.** The helper did NOT write the wrapper; it hands you `scaffold.wrapperBlock` plus the picked element's source range (`replaceStartLine`, `replaceEndLine`, 1-indexed). Write the wrapper **and** all variants in ONE edit: splice your variants into `wrapperBlock` at the "Variants: insert below this line" marker, then replace lines `[replaceStartLine, replaceEndLine]` with the result. A separate scaffold write reloads the framework before your variant write lands and strands the browser at 0/N. (`replaceEndLine < replaceStartLine` means insert mode: insert, remove nothing.) The `svelte-component` path never sets `sourceWritten`.
|
||||
|
||||
```bash
|
||||
node .agents/skills/impeccable/scripts/live-wrap.mjs --id EVENT_ID --count EVENT_COUNT --element-id "ELEMENT_ID" --classes "class1,class2" --tag "div" --text "TEXT_SNIPPET"
|
||||
```
|
||||
|
||||
Flag mapping. Keep them separate, don't collapse into `--query`:
|
||||
Flag mapping (keep separate, never collapse into `--query`): `--element-id` ← `event.element.id`; `--classes` ← classes joined with commas; `--tag` ← tagName; `--text` ← first ~80 chars of textContent, **every call**: it disambiguates repeated sibling components, without it wrap lands on the first match. If `event.pageUrl` implies the file, pass `--file PATH`. If `--text` still matches several candidates, wrap exits `{ error: "element_ambiguous", candidates, fallback: "agent-driven" }`: pick the right range from page context and write the wrapper manually per the fallback flow.
|
||||
|
||||
- `--element-id` ← `event.element.id`
|
||||
- `--classes` ← `event.element.classes` joined with commas
|
||||
- `--tag` ← `event.element.tagName`
|
||||
- `--text` ← first ~80 chars of `event.element.textContent` (trim, single-line). **Pass this every call.** When the picked element shares classes + tag with sibling components (a list of `<Card>`s, repeating sections), this is what disambiguates which branch in source to wrap. Without it, wrap silently lands on the first match and may rewrite the wrong element.
|
||||
Success output: `{ file, insertLine, commentSyntax, styleMode, styleTag, cssSelectorPrefixExamples, cssAuthoring }` (plus the `sourceWritten: false` fields above on source-preview targets). Run directly with no preflight scaffold, it writes the wrapper itself and you splice variants at `insertLine`. `styleMode` controls how preview CSS must be authored. Treat it as a detected capability mode, not a framework guess: `scoped` means `@scope ([data-impeccable-variant="N"])` rules; `astro-global-prefixed` means explicit `[data-impeccable-variant="N"]` prefixes with the exact returned `styleTag`. Use `cssAuthoring` as the source of truth for the current file (styleTag, selector strategy, requirements, forbidden patterns); apply no framework-specific exception unless it says to.
|
||||
|
||||
The helper searches ID first, then classes, then tag + class combo. If `event.pageUrl` implies the file (e.g. `/` is usually `index.html`), pass `--file PATH` to skip the search. `--query` is a fallback for raw text search only; do not use it for normal element lookups.
|
||||
For Svelte/SvelteKit targets, `live-wrap.mjs` returns `previewMode: "svelte-component"` with `file` pointing at a temporary `node_modules/.impeccable-live/<id>/manifest.json`, `componentDir` holding the variant components, and `sourceFile` the real route. The scaffold is AST-based: control-flow blocks (`{#each}`, `{#if}`) survive intact and a free each-collection crosses the contract as ONE structured prop (kind `collection`). The payload includes `componentStubMarkup` (the prop-substituted markup already written into every stub), so do not read the manifest or stubs back. EDIT `v1.svelte`, `v2.svelte`, ... in place; never delete and recreate them; keep the stub's control flow and `propContract` prop names; never flatten a loop into literal items. The stub `<style>` arrives seeded with the source rules that currently style the selection; restyle or delete them freely. On accept, any seeded rule your variant does not re-declare is REMOVED from the source (the preview never applied it, so the user approved a design without it). Use semantic class selectors, no `@scope`, no `data-impeccable-*`. Reply with `--file` set to the manifest path; the browser mounts the compiled components so Svelte HMR does not reset page state. Accept merges the chosen component back mechanically (markup restored to route expressions, CSS reconciled, params baked, indentation preserved); you have no post-accept cleanup on this path. When the selection contains constructs a detached preview cannot support (component tags, `bind:`/`use:`, await blocks, inline scripts, spread attributes), wrap returns the normal source-preview wrapper with `previewFallback: { from: "svelte-component", reason }`; just follow the returned shape.
|
||||
|
||||
If `--text` matches multiple candidates equally well, wrap exits with `{ error: "element_ambiguous", candidates: [...] }` and `fallback: "agent-driven"`: read the candidate line ranges, decide which one matches the picked element from page context, and write the wrapper manually per the fallback flow.
|
||||
|
||||
Output on success: `{ file, insertLine, commentSyntax, styleMode, styleTag, cssSelectorPrefixExamples, cssAuthoring }`. On source-preview targets it also returns `sourceWritten: false`, `wrapperBlock`, `replaceStartLine`, and `replaceEndLine` (write it yourself per the `event.scaffold` note above). When you run this command directly (no preflight scaffold), it writes the wrapper into source itself, so there is no `wrapperBlock` and you splice variants at `insertLine`.
|
||||
|
||||
For Svelte/SvelteKit targets, `live-wrap.mjs` returns `previewMode: "svelte-component"` with `file` pointing at a temporary `node_modules/.impeccable-live/<id>/manifest.json`, `componentDir` pointing at the variant component files, and `sourceFile` pointing at the real `.svelte` route. Write each variant as a real Svelte component (`v1.svelte`, `v2.svelte`, …) under `componentDir`; use the `propContract` prop names for dynamic text (`{propName}`), not literal snapshot strings. Put variant CSS in each component's `<style>` block with semantic class selectors (no `@scope`, no `data-impeccable-*`). Reply with `--file` set to the manifest path; the browser dynamically imports and mounts the compiled components so Svelte HMR does not reset page state while the user cycles variants. On Accept, `live-accept.mjs` inlines the accepted component back into `sourceFile` immediately after source promotion succeeds.
|
||||
|
||||
**Params on component-preview paths go in a sidecar, never as an attribute.** Svelte parses `{` inside an attribute value as the start of an expression, and both Svelte/Vue previews mount without an HTML variant wrapper. Declare params in `componentDir/params.json`, keyed by variant number, using the exact param schema from section 7:
|
||||
**Params on component-preview paths go in a sidecar, never as an attribute** (Svelte parses `{` in attribute values as an expression). Declare them in `componentDir/params.json` keyed by variant number, using the schema from section 7:
|
||||
|
||||
```json
|
||||
{
|
||||
"1": [
|
||||
{"id":"density","kind":"steps","default":"snug","label":"Density","options":[
|
||||
{"value":"airy","label":"Airy"},{"value":"snug","label":"Snug"},{"value":"packed","label":"Packed"}
|
||||
]}
|
||||
],
|
||||
"2": [
|
||||
{"id":"accent","kind":"range","min":0,"max":1,"step":0.05,"default":0.5,"label":"Accent"}
|
||||
]
|
||||
}
|
||||
{ "1": [ {"id":"density","kind":"steps","default":"snug","label":"Density","options":[
|
||||
{"value":"airy","label":"Airy"},{"value":"snug","label":"Snug"} ]} ] }
|
||||
```
|
||||
|
||||
Author the component `<style>` against `var(--p-<id>, default)` for `range`/`toggle` and `[data-p-<id>="…"]` for `steps`; wrap those selectors in `:global(...)` so the knob values the runtime sets on the mounted root reach your rules. The browser reads `params.json`, docks the panel, and drives `--p-*` / `data-p-*` on the mounted component exactly as it does for the HTML/JSX path.
|
||||
Author the component `<style>` against `var(--p-<id>, default)` for `range`/`toggle` and `[data-p-<id>="…"]` for `steps`, wrapped in `:global(...)` so runtime knob values on the mounted root reach your rules.
|
||||
|
||||
`styleMode` controls how preview CSS must be authored. Treat it as a detected capability mode, not a framework guess:
|
||||
|
||||
- `scoped`: use `@scope ([data-impeccable-variant="N"])` rules.
|
||||
- `astro-global-prefixed`: use explicit `[data-impeccable-variant="N"]` selector prefixes and the exact `styleTag` returned by the tool.
|
||||
|
||||
Use `cssAuthoring` as the source of truth for the current file. It includes the exact `styleTag`, selector strategy, selector examples, requirements, and forbidden patterns. Do not apply a framework-specific exception unless the returned `styleMode` / `cssAuthoring.mode` says to.
|
||||
|
||||
**Fallback errors.** Wrap only writes into files it judges to be source (tracked by git, not marked GENERATED, not listed in config's `generatedFiles`). If it can't land on a source file, it errors without writing; accepting a variant into a generated file is silent data loss. Three shapes:
|
||||
|
||||
- `{ error: "file_is_generated", file, hint }`: user-supplied `--file` points at a generated file.
|
||||
- `{ error: "element_not_in_source", generatedMatch, hint }`: element exists only in a generated file (the next build would wipe any edits).
|
||||
- `{ error: "element_not_found", hint }`: element isn't in any project file; likely runtime-injected (JS component, dynamic render from data).
|
||||
|
||||
All three carry `fallback: "agent-driven"`. Follow **Handle fallback** below.
|
||||
**Fallback errors.** Wrap refuses to write into non-source files (generated, untracked): accepting into one is silent data loss. Three shapes, all with `fallback: "agent-driven"` (see **Handle fallback**): `file_is_generated` (your `--file` points at a generated file), `element_not_in_source` with `generatedMatch` (element only exists generated), `element_not_found` (likely runtime-injected).
|
||||
|
||||
### 3. Load the action's reference
|
||||
|
||||
If `event.action` is `impeccable` (the default freeform action), work from SKILL.md's design rules plus [craft-floor.md](craft-floor.md), and decide the visitor mode from the selected surface. Do not load a sub-command reference. **Freeform is not a pass to skip parameters:** you still follow the composition budget and the freeform bias in **§7 Parameters** below. Sub-command files list MUST-have signature knobs; freeform has no such file, so sizing knobs from surface weight and primary axes is entirely on you.
|
||||
|
||||
Any other `event.action` (`bolder`, `quieter`, `distill`, `polish`, `typeset`, `colorize`, `layout`, `adapt`, `animate`, `delight`, `overdrive`): Read `reference/<action>.md` before planning. Each sub-command encodes a specific discipline; skipping its reference produces generic output. Those files may require specific params; layer them on top of the §7 budget, not instead of it.
|
||||
`event.action` is `impeccable` (freeform): work from SKILL.md's design rules plus [craft-floor.md](craft-floor.md); decide the visitor mode from the surface; do not load a sub-command reference. Freeform is not a pass to skip parameters: follow the budget and freeform bias in section 7. Any other action (`bolder`, `quieter`, `distill`, `polish`, `typeset`, `colorize`, `layout`, `adapt`, `animate`, `delight`, `overdrive`): read `reference/<action>.md` before planning; its MUST params layer on top of the section 7 budget.
|
||||
|
||||
### 4. Plan three variants: identity first, then mode, then axes
|
||||
|
||||
The wrong frame for live mode is "show three different design directions." Live runs on an existing surface; the brand has already been chosen. The job is variation **within identity**, not selection between identities. Failure mode: three editorial-typographic variants on a brief that wasn't editorial. Bigger failure mode: three off-brand variants the user can't accept because they don't look like their product.
|
||||
|
||||
Four phases. Do them in order.
|
||||
Live runs on an existing surface; the brand is already chosen. The job is variation **within identity**, not selection between identities. The worst failure is three off-brand variants the user cannot accept. Four phases, in order.
|
||||
|
||||
#### Phase A: Extract the identity (non-skippable)
|
||||
|
||||
The existing surface has an identity already. Read it before planning anything. Sources, in priority order:
|
||||
|
||||
1. **DESIGN.md** if loaded: read the visual system fields (palette, type pairing, motion, components). This is the authoritative answer.
|
||||
2. **CSS custom properties** in the page's stylesheets (`:root { --color-...; --font-...; ... }`): these are de-facto tokens.
|
||||
3. **Computed styles** on the picked element and its parent: colors, fonts, spacing scales, corner radii.
|
||||
4. **Sibling components on the page**: what visual rhetoric do existing components use? (Asymmetric or centered? Dense or airy? Bold or quiet?)
|
||||
|
||||
Write down what you see in **one sentence**. The sentence describes the surface that's actually on screen; it is not aspirational, not opinionated, not edited toward what the brand "should" be. Capture, in roughly this order:
|
||||
|
||||
- The dominant surface color and accent color, by hex or token name (use the actual values, not categories like "warm" or "neutral").
|
||||
- The type pairing: the actual font names loaded, primary first.
|
||||
- The layout topology: how the dominant elements are arranged (stacked / side-by-side / grid / asymmetric / overlay).
|
||||
- The surface treatment: corners, borders, shadows, density of decoration.
|
||||
- The voice tone you read off the copy itself, not off the aesthetic feel.
|
||||
|
||||
Be specific. "Modern" is not a color, "elegant" is not a type pairing, "clean" is not a layout. If you can't extract a real value for an axis, skip it rather than fabricate. The point is to record what is, not to describe what you wish it were.
|
||||
|
||||
Do not name an aesthetic family in this sentence; that is a conclusion, not observed identity data. Letting conclusions into Phase A collapses the identity lock into a self-fulfilling prophecy.
|
||||
|
||||
This sentence is the **identity lock**. Every variant must be readable as the same brand if rendered side by side. Skipping this phase is the primary cause of off-brand variants. Absence of DESIGN.md is never an excuse; extract from CSS and computed styles instead.
|
||||
Sources in priority order: DESIGN.md's visual system fields; CSS custom properties (de-facto tokens); computed styles on the picked element and parent; sibling components' visual rhetoric. Write ONE sentence recording what is actually on screen: dominant surface and accent color (real values, not "warm"), the loaded font pairing, layout topology (stacked / side-by-side / grid / asymmetric / overlay), surface treatment (corners, borders, shadows, decoration density), and the voice tone read off the copy. Be specific; skip an axis rather than fabricate; do not name an aesthetic family (a conclusion, not data). This sentence is the **identity lock**: every variant must read as the same brand side by side. Absence of DESIGN.md is never an excuse.
|
||||
|
||||
#### Phase B: Pick mode (default vs departure)
|
||||
|
||||
**Default mode**: the existing identity is preserved. Variants vary expression axes within it. *This is the right mode for ~90% of live sessions.* The user picked an element on a real product they're shipping; they expect variants of *their* hero, not three different brands' heroes.
|
||||
|
||||
**Departure mode**: the existing identity is rejected. Variants propose alternatives consistent with durable product and brand truth. Trigger only when the user explicitly asks for departure in the current request or freeform prompt ("redesign this", "rebuild this from scratch", "what if it weren't editorial at all", "show me something completely different"). A stale page critique or an old task note is not replacement authorization.
|
||||
|
||||
If you're unsure, you're in default mode. The cost of being wrong about default is "three on-brand variants with similar feel": recoverable, the user picks none. The cost of being wrong about departure is "three off-brand variants": unrecoverable, the user is annoyed.
|
||||
**Default** preserves the identity and varies expression within it; right for ~90% of sessions. **Departure** rejects the identity; trigger ONLY on the user's explicit ask in the current request or prompt ("redesign this", "rebuild from scratch", "something completely different"); a stale critique or old note is not authorization. Unsure means default: wrong-default costs "three on-brand variants with similar feel" (recoverable), wrong-departure costs three off-brand variants (unrecoverable).
|
||||
|
||||
#### Phase C: Plan three variants
|
||||
|
||||
**Default mode.** Each variant commits to a different **primary axis** of difference, while preserving the identity sentence. The six axes:
|
||||
**Default mode.** Each variant commits to a different **primary axis**, preserving the identity sentence. The six axes: 1 **Hierarchy** (which element commands the eye), 2 **Layout topology** (stacked / side-by-side / grid / asymmetric / overlay), 3 **Typographic system** (pairing logic, scale ratio, case/weight, *within the available faces*), 4 **Color strategy** (which existing palette role carries the surface: Restrained / Committed / Full palette / Drenched; existing tokens only), 5 **Density** (minimal / comfortable / dense), 6 **Structural decomposition** (merge, split, progressive disclosure). Three variants, three DIFFERENT axes: the same brand at three angles. New fonts, new hues, or new aesthetic-family signals belong to departure mode only.
|
||||
|
||||
1. **Hierarchy**: which element commands the eye?
|
||||
2. **Layout topology**: stacked / side-by-side / grid / asymmetric / overlay
|
||||
3. **Typographic system**: pairing logic, scale ratio, case/weight strategy *within the available faces*
|
||||
4. **Color strategy**: which existing palette role carries the surface (Restrained / Committed / Full palette / Drenched). Use the brand's existing palette tokens, not new colors.
|
||||
5. **Density**: minimal / comfortable / dense
|
||||
6. **Structural decomposition**: merge, split, progressive disclosure
|
||||
**Departure mode.** Each variant anchors to a different aesthetic direction derived from the brand, never a fixed catalog: read PRODUCT.md's Brand Personality words; derive physical, spatial, or material experiences that embody them; from those, derive three directions genuinely different from each other AND from the current surface; reject reflex choices whose rationale would fit a neighboring product. Each direction must be one concrete sentence naming a real-world referent ("a museum exhibition label system", not "clean and minimal").
|
||||
|
||||
Three variants → three DIFFERENT axes. The trio reads as *the same brand at three angles*. Do not introduce new fonts, new palette hues, or new aesthetic-family signals; those belong to departure mode.
|
||||
|
||||
**While planning each variant, also name its 2–3 parameter knobs** (per the §7 budget table). Parameters are part of the design, not a decoration added afterward. If the variant explores density, expose a density knob. If it explores color commitment, expose a color-amount range. Deciding "what's tunable" during planning produces better knobs than retrofitting them onto finished HTML.
|
||||
|
||||
**Departure mode.** Each variant anchors to a different **aesthetic direction**, derived from PRODUCT.md's audience world and voice plus the current DESIGN.md. Do not pick from a fixed catalog; derive directions from this product.
|
||||
|
||||
Instead, work from the brand:
|
||||
|
||||
1. Read PRODUCT.md's Brand Personality words. Derive physical, spatial, or material experiences that embody them without starting from a design style.
|
||||
2. From those physical experiences, derive three visual directions that are genuinely different from each other AND from the current surface you're departing.
|
||||
3. Reject any direction chosen by reflex rather than derived from the brand. Start over from the personality words when the rationale could fit a neighboring product.
|
||||
4. Each direction must be expressible in one concrete sentence that names a real-world referent ("a museum exhibition label system for a contemporary art gallery" not "clean and minimal"). If your sentence contains only adjectives, it's not concrete enough.
|
||||
5. **While planning each direction, also name its 2–3 parameter knobs** (per the §7 budget table). The same principle as default mode: decide "what's tunable" during planning, not after writing the HTML. A departure-mode hero with 0 parameters is not "bold creative vision," it's a missed opportunity for the user to fine-tune the direction they pick.
|
||||
**In both modes, name each variant's 2 or 3 parameter knobs while planning** (section 7 budget). Parameters are part of the design; deciding "what's tunable" during planning beats retrofitting.
|
||||
|
||||
#### Phase D: Squint test
|
||||
|
||||
**Default mode squint.** Read each variant's identity sentence and compare to the locked identity from Phase A. If any variant has drifted to a different palette, type voice, or visual rhetoric, it has crossed into departure mode by accident; rework. Then check that each variant commits to a different primary axis. Three "tighter density" variants is failure.
|
||||
**Default:** compare each variant against the Phase A lock; palette, type voice, or rhetoric drift means it crossed into departure by accident: rework. Then confirm three different primary axes; three "tighter density" variants is failure. **Departure:** two passes, family before sentence. Family pass (non-negotiable): label each variant with a concrete family of your own choosing; shared or interchangeable labels mean rework. Sentence pass: three one-line descriptions side by side; two that rhyme mean rework. When the primary axis is color or theme, the trio must not share theme + dominant hue: three color worlds, not three shades.
|
||||
|
||||
**Departure mode squint.** Two passes, family before sentence:
|
||||
**Action-specific invocations** must vary along the action's dimension:
|
||||
|
||||
1. **Family pass.** Give each variant a concrete family label of your own choosing. If two variants share a label, or a label fits another variant equally well, rework. Do not use a fixed vocabulary. *This pass is non-negotiable in departure mode and catches monoculture the sentence pass misses.*
|
||||
2. **Sentence pass.** Write three one-sentence descriptions side by side. If two of them rhyme ("both feature big type" / "both are stacks of sections" / "both center the CTA"), rework the offender.
|
||||
|
||||
**When the primary axis is color or theme, forbid the trio from sharing theme + dominant hue.** Two dark-plus-one-dark is not distinct. Aim for three color worlds, not three shades of the same.
|
||||
|
||||
**For action-specific invocations**, each variant must vary along the dimension the action names:
|
||||
|
||||
- `bolder`: amplify a different dimension per variant (scale / saturation / structural change). Not three "slightly bigger" variants.
|
||||
- `bolder`: amplify a different dimension per variant (scale / saturation / structural change).
|
||||
- `quieter`: pull back a different dimension (color / ornament / spacing).
|
||||
- `distill`: remove a different class of excess (visual noise / redundant content / nested structure).
|
||||
- `polish`: target a different refinement axis (rhythm / hierarchy / micro-details like corner radii, focus states, optical kerning).
|
||||
- `typeset`: different type pairing AND different scale ratio each. Not three riffs on one pairing.
|
||||
- `colorize`: different hue family each (not shades of one hue). Vary chroma and contrast strategy.
|
||||
- `layout`: different structural arrangement (stacked / side-by-side / grid / asymmetric). Not spacing tweaks.
|
||||
- `adapt`: different target context per variant (mobile-first / tablet / desktop / print or low-data). Don't make three mobile layouts.
|
||||
- `animate`: different motion vocabulary (cascade stagger / clip wipe / scale-and-focus / morph / parallax). Not three staggered fades.
|
||||
- `delight`: different flavor of personality (unexpected micro-interaction / typographic surprise / illustrated accent / sonic-or-haptic moment / easter-egg interaction).
|
||||
- `overdrive`: different convention broken (scale / structure / motion / input model / state transitions). Skip `overdrive.md`'s "propose and ask" step; live mode is non-interactive.
|
||||
- `polish`: a different refinement axis (rhythm / hierarchy / micro-details).
|
||||
- `typeset`: different pairing AND different scale ratio each.
|
||||
- `colorize`: different hue family each; vary chroma and contrast strategy.
|
||||
- `layout`: different structural arrangement, not spacing tweaks.
|
||||
- `adapt`: different target context per variant (mobile-first / tablet / desktop / print or low-data).
|
||||
- `animate`: different motion vocabulary (cascade stagger / clip wipe / scale-and-focus / morph / parallax).
|
||||
- `delight`: different flavor of personality (micro-interaction / typographic surprise / illustrated accent / sonic-or-haptic / easter egg).
|
||||
- `overdrive`: different convention broken (scale / structure / motion / input model / state transitions); skip its "propose and ask" step, live is non-interactive.
|
||||
|
||||
### 5. Apply the freeform prompt (if present)
|
||||
|
||||
`event.freeformPrompt` is the user's ceiling on direction (all variants must honor it), but still explore meaningfully different *interpretations*. The interpretations stay within whichever mode you picked in Phase B.
|
||||
|
||||
In **default mode**, the prompt narrows the axes you choose, not the identity. *"Make it feel more confident"* → variant 1 amplifies hierarchy (one element commands the eye), variant 2 commits the existing accent color (Committed strategy on the brand's hue), variant 3 tightens density and removes decorative slack. Three different axes, same brand.
|
||||
|
||||
In **departure mode**, the prompt narrows the lanes you draw from, not the families. *"Make it feel like a newspaper front page"* would itself be a departure-mode prompt; honor it but pick three meaningfully different newspaper-adjacent lanes (broadsheet vs. tabloid vs. trade journal), and run the family pass to confirm they don't collapse into one.
|
||||
|
||||
When the prompt conflicts with a confirmed binding brand commitment or DESIGN.md invariant, preserve the invariant unless the user explicitly revokes or replaces it. Task-local strategy from the matching surface brief may change when the user changes that surface's goal.
|
||||
`event.freeformPrompt` is the user's ceiling on direction: all variants honor it while exploring different interpretations within the Phase B mode. Default mode: the prompt narrows the axes, not the identity ("more confident" → one variant amplifies hierarchy, one commits the accent color, one tightens density). Departure mode: the prompt narrows the lanes, not the families ("newspaper front page" → broadsheet vs tabloid vs trade journal, then run the family pass). When the prompt conflicts with a binding brand commitment or DESIGN.md invariant, preserve the invariant unless the user explicitly revokes it.
|
||||
|
||||
### 6. Deliver variants
|
||||
|
||||
Complete HTML replacement of the original element for each variant, not a CSS-only patch. Consider the element's context (computed styles, parent structure, CSS variables from `event.element`).
|
||||
|
||||
Colocate preview CSS as a `<style>` tag inside the variant wrapper; `<style>` works anywhere in modern browsers and keeps each delivered state internally complete (no FOUC).
|
||||
|
||||
**Atomic default:** write CSS + all variants + parameter manifests in one edit at `insertLine`, preserving the established behavior.
|
||||
|
||||
Use the `cssAuthoring` object returned by `live-wrap.mjs` to author the temporary preview CSS. The style opening tag shown below is the common case; replace it with `cssAuthoring.styleTag` when the tool returns a different one. The variant markup shape is otherwise stable:
|
||||
Complete HTML replacement of the original element per variant, not a CSS-only patch. Colocate preview CSS as a `<style>` tag inside the wrapper. **Atomic default:** CSS + all variants + parameter manifests in one edit at `insertLine`.
|
||||
|
||||
```html
|
||||
<!-- Variants: insert below this line -->
|
||||
@@ -316,92 +189,55 @@ Use the `cssAuthoring` object returned by `live-wrap.mjs` to author the temporar
|
||||
<!-- variant 1: full element replacement (single top-level element) -->
|
||||
</div>
|
||||
<div data-impeccable-variant="2" style="display: none">
|
||||
<!-- variant 2: full element replacement -->
|
||||
<!-- variant 2 -->
|
||||
</div>
|
||||
<div data-impeccable-variant="3" style="display: none">
|
||||
<!-- variant 3: full element replacement -->
|
||||
<!-- variant 3 -->
|
||||
</div>
|
||||
```
|
||||
|
||||
**Each variant div contains exactly one top-level element: the full replacement for the original.** Use the same tag as the original (e.g. `<section>` if the user picked a `<section>`). Loose siblings (heading + paragraph + div as direct children of the variant div) break the outline tracking and the accept flow, which both assume one child.
|
||||
Replace the style opening tag with `cssAuthoring.styleTag` when the tool returns a different one. **Each variant div contains exactly one top-level element**, same tag as the original; loose siblings break outline tracking and accept. First variant visible, all others `display: none`. The browser's MutationObserver accepts atomic or progressive arrival; accepting an arrived variant fences the worker, so later publications are rejected.
|
||||
|
||||
The first variant has no `display: none` (visible by default). All others do. If variants use only inline styles and no preview CSS, omit the `<style>` tag entirely.
|
||||
For `styleMode: "scoped"`, author every `:scope` rule with a descendant combinator: the `@scope` boundary is the variant wrapper div, not your element, so a bare `:scope { ... }` styles a `display: contents` shell. Always step in (`:scope > .card`, `:scope .hero-title`). The fake test agent's CSS in `tests/live-e2e/agent.mjs` is a faithful template.
|
||||
|
||||
The browser's MutationObserver accepts either delivery shape. On the transactional progressive path it shows arrived variants and pending dots immediately; Accept and Discard are available as soon as one variant exists. Accepting an arrived variant fences the worker before the browser releases the picker, so later publications are rejected.
|
||||
|
||||
For `styleMode: "scoped"`, author every `:scope` rule with a descendant combinator. The `@scope` boundary is the **variant wrapper `<div data-impeccable-variant="N">`**, not the element you're designing. A bare `:scope { background: cream; }` styles the wrapper, not the inner replacement, so the cream lands on a `display: contents` shell while the actual element keeps page defaults. Always step in: `:scope > .card`, `:scope > section`, `:scope .hero-title`, etc. The fake test agent's CSS in `tests/live-e2e/agent.mjs` is a faithful template; every scoped rule starts `:scope > ...`.
|
||||
|
||||
**JSX / TSX target files.** Wrap `<style>` content in a template literal so the CSS `{` / `}` aren't parsed as JSX expressions, and use `className=` / `style={{…}}` on every variant element. Keep `data-impeccable-*` attributes as-is; they're plain strings:
|
||||
**JSX / TSX targets:** wrap `<style>` content in a template literal (CSS braces would parse as JSX), use `className=` / `style={{…}}`, keep `data-impeccable-*` attributes as plain strings:
|
||||
|
||||
```tsx
|
||||
<style data-impeccable-css="SESSION_ID">{`
|
||||
@scope ([data-impeccable-variant="1"]) { ... }
|
||||
@scope ([data-impeccable-variant="2"]) { ... }
|
||||
`}</style>
|
||||
<div data-impeccable-variant="1">
|
||||
{/* variant 1 */}
|
||||
</div>
|
||||
<div data-impeccable-variant="2" style={{ display: 'none' }}>
|
||||
{/* variant 2 */}
|
||||
</div>
|
||||
```
|
||||
|
||||
The wrap script already gives you a single-rooted JSX wrapper: a `<div data-impeccable-variants="…">` outer element with the marker comments tucked inside. Drop the variants block above into the "Variants: insert below this line" comment and the source stays valid TSX.
|
||||
The wrap script provides a single-rooted JSX wrapper with the marker comments inside; drop the block at the marker and the source stays valid TSX.
|
||||
|
||||
### 7. Parameters (composition-sized, 0–4 per variant)
|
||||
### 7. Parameters (composition-sized, 0-4 per variant)
|
||||
|
||||
Each variant can expose **coarse** knobs alongside the full HTML/CSS replacement. The browser docks a small panel to the right of the outline with one control per parameter. The user drags/clicks and sees instant feedback: there is zero regeneration cost because the knob toggles a CSS variable or data attribute that the variant's scoped CSS is already authored against.
|
||||
Each variant can expose **coarse** knobs; the browser docks one control per parameter with zero regeneration cost (knobs drive a CSS variable or data attribute your scoped CSS is authored against). Wire an axis as soon as the user could plausibly mutter "a bit tighter" or "a touch more accent" without wanting a regeneration; micro-margins and one-off nudges are not parameters. Freeform bias: you chose the axes, so expose them; a hero with 0 params is almost always a mistake, and 1 is underweight unless the design is a genuine fixed point.
|
||||
|
||||
**What “optional” does not mean.** Parameters are not nice-to-have decoration on large work. The word meant “omit controls that are redundant or cosmetic,” not “default to zero because three variants were enough work.”
|
||||
Budget scales with the element's VISUAL weight (count visual children, not DOM depth):
|
||||
|
||||
**When to add.** As soon as the variant’s scoped CSS has a meaningful continuous or stepped axis: density, color amount, type scale, motion intensity, column weight, and so on. If you can imagine the user muttering “a bit tighter” or “a touch more accent” **without** wanting a full regeneration, wire that axis. **Not** micro-margins or one-off nudges; those are not parameters.
|
||||
- **Leaf / tiny** (button, icon, bare heading): **0 params.**
|
||||
- **Small composition** (simple card, labeled input, ≤ ~5 visual children): **0-1**.
|
||||
- **Medium composition** (section, nav cluster, 6-15 children): **target 2**; 1 if simple.
|
||||
- **Large composition** (hero, full region, 16+ children or sub-sections): **target 2-3, up to 4** when independent axes are all authored in CSS.
|
||||
|
||||
**Freeform (`action` is `impeccable`) bias.** You did not load a sub-command reference, so you must **choose** signature axes yourself. Match the budget table: for a hero or large composition, that means **2–3 axes per variant**, not 1. Prefer knobs that sit on the dimensions where your three variants actually differ (if density varies, expose it as a `steps` knob; if color commitment varies, expose it as a `range`). A hero that ships with **0** params is almost always a mistake, not a judgment call. A hero with exactly **1** param is underweight unless the design is genuinely a fixed-point comparison. Start from the budget table, not from zero.
|
||||
**Hard cap: four** per variant. For named sub-commands, the action reference's MUST params are non-negotiable when expressible; respect the cap, no duplicate knobs.
|
||||
|
||||
**Budget scales with the element's visual weight, not token budget.** Knobs need real estate to read as tunable; three sliders on a single control are noise.
|
||||
|
||||
- **Leaf / tiny**: a single button, icon, input, bare heading, solitary paragraph: **0 params.**
|
||||
- **Small composition**: labeled input, simple card, short callout (≤ ~5 visual children): **0–1** params when one dominant axis is obvious; otherwise **0.**
|
||||
- **Medium composition**: section component, nav cluster, dense card, short feature block (6–15 visual children): **target 2**; **1** is acceptable if the block is simple; **0** only when variants are truly fixed points.
|
||||
- **Large composition**: hero section, full page region, spread layout, strong internal structure (16+ visual children or multiple sub-sections): **target 2–3**; **up to 4** when several independent axes (e.g. structure `steps` + `density` + one accent) are all authored in scoped CSS.
|
||||
|
||||
**When in doubt, ask whether a dial exists before defaulting to zero.** The user can always request more variants, but the point of live mode is instant tuning without another Go. Crowding the panel is bad; **under-shipping** knobs on a dense composition is the more common failure for freeform. Count by **visual** children, not DOM depth; a shallow-but-wide hero is still large.
|
||||
|
||||
**Hard cap per variant**: at most **four** parameters so the panel stays legible; rare fifth only if the reference explicitly allows it.
|
||||
|
||||
**How to declare.** Put a JSON manifest on the variant wrapper (HTML/JSX path). **On the `svelte-component` path, do not use this attribute.** Declare params in `componentDir/params.json` keyed by variant number instead (see the component-preview paragraphs in the wrap section). The param schema below is identical for every path.
|
||||
**Declare** on the HTML/JSX path as a wrapper attribute (component-preview paths use `componentDir/params.json` instead, same schema, keyed by variant number; see the wrap section):
|
||||
|
||||
```html
|
||||
<div data-impeccable-variant="1" data-impeccable-params='[
|
||||
{"id":"color-amount","kind":"range","min":0,"max":1,"step":0.05,"default":0.5,"label":"Color amount"},
|
||||
{"id":"density","kind":"steps","default":"snug","label":"Density","options":[
|
||||
{"value":"airy","label":"Airy"},
|
||||
{"value":"snug","label":"Snug"},
|
||||
{"value":"packed","label":"Packed"}
|
||||
]},
|
||||
{"id":"serif","kind":"toggle","default":false,"label":"Serif display"}
|
||||
]'>
|
||||
...variant content...
|
||||
</div>
|
||||
```
|
||||
|
||||
**Three kinds:**
|
||||
Three kinds: `range` (slider; drives `--p-<id>`; author `var(--p-color-amount, 0.5)`; fields min/max/step/default/label), `steps` (segmented radio; drives `data-p-<id>`; author `:scope[data-p-density="airy"] .grid { ... }`; fields options/default/label), `toggle` (drives both `--p-<id>: 0|1` and attribute presence; fields default/label). Reset on variant switch is a known limitation: each variant starts at its declared defaults.
|
||||
|
||||
- `range`: smooth slider. Drives a CSS custom property `--p-<id>` on the variant wrapper. Author CSS with `var(--p-color-amount, 0.5)`. Fields: `min`, `max`, `step`, `default` (number), `label`.
|
||||
- `steps`: segmented radio. Drives a data attribute `data-p-<id>` on the variant wrapper. Author CSS with `:scope[data-p-density="airy"] .grid { ... }`. Fields: `options` (array of `{value, label}`), `default` (string), `label`.
|
||||
- `toggle`: on/off switch. Drives BOTH a CSS var (`--p-<id>: 0|1`) and a data attribute (present when on, absent when off). Use whichever is more convenient. Fields: `default` (boolean), `label`.
|
||||
|
||||
**Signature params per action.** For named sub-commands, read that action’s `reference/<action>.md` for one or two **MUST** params (e.g. `layout` → `density`). Those are non-negotiable when the design can express them. **Freeform has no file-level MUST**; the **Freeform (`impeccable`) bias** in this section is the stand-in. If the user’s action is both stylized and sub-command (e.g. `colorize`), the sub-command’s MUST list takes precedence for its axes; still respect the **Hard cap** and add no redundant duplicate knobs.
|
||||
|
||||
**Reset on variant switch.** User dials density on v1, flips to v2, v2 starts at v2's declared defaults. Known limitation; preservation across variants may land later.
|
||||
|
||||
**On accept**, the browser sends the user's current values in the accept event. `live-accept.mjs` writes them as a sibling comment:
|
||||
|
||||
```html
|
||||
<!-- impeccable-param-values SESSION_ID: {"color-amount":0.7,"density":"packed"} -->
|
||||
```
|
||||
|
||||
The carbonize cleanup step (see below) reads that comment and bakes the chosen values into the final CSS. For `steps`/`toggle` attribute selectors: keep only the branch matching the chosen value, drop the others, collapse `:scope[data-p-density="packed"] .grid` to a semantic class rule. For `range` vars: either substitute the literal or keep the var with the chosen value as its new default.
|
||||
**On accept**, the browser sends current values and `live-accept.mjs` writes them as a sibling comment: `<!-- impeccable-param-values SESSION_ID: {"color-amount":0.7} -->`. Carbonize cleanup bakes them: keep only the matching `steps`/`toggle` branch, drop the others, collapse `:scope[data-p-…]` to semantic rules; substitute `range` literals or update the var's default.
|
||||
|
||||
### 8. Signal done
|
||||
|
||||
@@ -409,127 +245,56 @@ The carbonize cleanup step (see below) reads that comment and bakes the chosen v
|
||||
node .agents/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID done --file RELATIVE_PATH
|
||||
```
|
||||
|
||||
`RELATIVE_PATH` is relative to project root (`public/index.html`, `src/App.tsx`, etc.); the browser fetches source directly if the dev server lacks HMR.
|
||||
|
||||
Then run `live-poll.mjs` again immediately.
|
||||
`RELATIVE_PATH` is relative to project root; the browser fetches source directly if the dev server lacks HMR. Then poll again immediately.
|
||||
|
||||
### Aborting an in-flight session
|
||||
|
||||
If wrap or generation fails after the browser has flipped to GENERATING (e.g. wrap landed on the wrong source branch and you've already reverted it, or generation hit an unrecoverable error), tell the **browser** so its bar resets to PICKING:
|
||||
|
||||
```bash
|
||||
node .agents/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID error "Short reason"
|
||||
```
|
||||
|
||||
Don't run `live-accept --discard` for this; that's a pure file mutator, the browser doesn't see it, and the bar gets stuck on the GENERATING dots forever (the user has to refresh). `--discard` is only correct when the **browser** initiated the discard (user clicked ✕ during CYCLING) and the agent is just running source-side cleanup the browser already triggered.
|
||||
If wrap or generation fails after the browser flipped to GENERATING, tell the **browser** so its bar resets: `node .agents/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID error "Short reason"`. Never use `live-accept --discard` for this (pure file mutator, browser never sees it, bar sticks on dots); `--discard` is only source-side cleanup for a discard the browser itself initiated.
|
||||
|
||||
## Handle fallback
|
||||
|
||||
When wrap returns `fallback: "agent-driven"`, the deterministic flow doesn't apply. Pick up here.
|
||||
When wrap returns `fallback: "agent-driven"`, you pick the source file yourself; the goal is unchanged: three preview variants now, and the accepted one persisted where the next build cannot wipe it.
|
||||
|
||||
The goal is the same: give the user three variants to choose from AND persist the accepted one in a place the next build won't wipe. The difference is that you have to pick the right source file yourself.
|
||||
|
||||
### Step 1: Identify where the element actually lives
|
||||
|
||||
Use the error payload:
|
||||
|
||||
- `element_not_in_source` with `generatedMatch: "public/docs/foo.html"`: the served HTML is generated. Find the generator (grep for writers of that path, e.g. `scripts/build-sub-pages.js`, an Astro/Next template) and locate the template or partial that emits this element.
|
||||
- `element_not_found`: the element is runtime-injected. Look for the component that renders it (React/Vue/Svelte), the JS that assembles it, or the data source that feeds it.
|
||||
- `file_is_generated` with `file: "..."`: user pointed at a generated file explicitly. Same resolution as `element_not_in_source`.
|
||||
|
||||
Read the candidate source until you're confident where a change to the element would belong. If the change is purely visual, that source might be a shared stylesheet, not the template.
|
||||
|
||||
### Step 2: Show three variants in the DOM for preview
|
||||
|
||||
The browser bar is waiting for variants. Even without a wrapper in source, you still need to show something:
|
||||
|
||||
1. Manually write the wrapper scaffold into the **served** file (the one the browser actually loaded). Use the same structure `live-wrap.mjs` produces; `<!-- impeccable-variants-start ID --><div data-impeccable-variants="ID" data-impeccable-variant-count="3" style="display: contents">…</div><!-- end -->`.
|
||||
2. Insert your three variant divs inside it, same shape as the deterministic path.
|
||||
3. Signal done with `--reply EVENT_ID done --file <served file>`. The browser's no-HMR fallback will fetch and inject.
|
||||
|
||||
This served-file edit is **temporary**: next regen wipes it, and that's fine. The real work happens on accept.
|
||||
|
||||
### Step 3: On accept, write to true source
|
||||
|
||||
When the accept event arrives (`_acceptResult.handled` will usually be `false` here because accept also refuses to persist into generated files; see Handle accept for the carbonize branch), extract the accepted variant's content and write it into the source you identified in Step 1:
|
||||
|
||||
- Structural change → edit the template / component source.
|
||||
- Visual-only change → add or update rules in the appropriate stylesheet; remove the inline `<style>` scope.
|
||||
- Dynamic from data → update the data source or the render logic.
|
||||
|
||||
Then remove the temporary wrapper from the served file if it's still there.
|
||||
|
||||
### Step 4: On discard, clean up the served file
|
||||
|
||||
Remove the wrapper you inserted in Step 2. Nothing else to do.
|
||||
1. **Find where the element really lives** from the error payload: `element_not_in_source` + `generatedMatch` means the served HTML is generated, so find the generator's template or partial; `element_not_found` means runtime-injected, so find the rendering component or data source; `file_is_generated` resolves the same way. A purely visual change may belong in a shared stylesheet rather than a template.
|
||||
2. **Preview in the served file**: manually write the same wrapper scaffold `live-wrap.mjs` produces (`<!-- impeccable-variants-start ID --><div data-impeccable-variants="ID" data-impeccable-variant-count="3" style="display: contents">…</div><!-- end -->`) into the file the browser actually loaded, insert your variant divs, `--reply EVENT_ID done --file <served file>`. This edit is temporary; a regen wiping it is fine.
|
||||
3. **On accept, write to true source** (accept refuses generated files, so `_acceptResult.handled` is usually `false` here): structural change → template/component source; visual-only → the right stylesheet; content rendered from data → the data source or render logic. Then remove the temporary wrapper from the served file.
|
||||
4. **On discard**, just remove the temporary wrapper.
|
||||
|
||||
## Handle `accept`
|
||||
|
||||
Event: `{id, variantId, _acceptResult, _completionAck}`. The poll script already ran `live-accept.mjs` to handle the file operation deterministically, then acknowledged event delivery to the helper. The browser DOM is already updated.
|
||||
Event: `{id, variantId, _acceptResult, _completionAck}`. The poll script already ran `live-accept.mjs` deterministically and acknowledged delivery; the browser DOM is already updated.
|
||||
|
||||
- The accept event includes `pageUrl`; the poll script must forward it to `live-accept.mjs --page-url PAGE_URL` so accept-time cleanup only scrubs staged copy edits for the current page.
|
||||
- `_completionAck.ok !== true`: do not poll yet. Run `live-status.mjs` / `live-resume.mjs`, complete the cleanup manually if needed, then run `live-complete.mjs --id EVENT_ID`.
|
||||
- `_acceptResult.handled: true` and `carbonize: false`: nothing to do. Poll again.
|
||||
- `_acceptResult.handled: true` and `carbonize: true`: post-accept cleanup is required, but it must not stall Codex's control lane. See "Required after accept (carbonize)" below. The `event._acceptResult.todo` field, `_completionAck.requiresComplete`, and stderr banner all point at this required follow-up; none are decorative.
|
||||
- `_acceptResult.handled: false, mode: "fallback"`: the session lived in a generated file and the script refused to persist there. You've already written the accepted variant into true source during Handle fallback Step 3; just clean up the temporary wrapper in the served file if any, and poll again.
|
||||
- `_acceptResult.handled: false, mode: "error"`: the operation genuinely failed. **Do not hand-edit the file**; the source was not touched and editing it yourself would either double-apply or race whoever holds it.
|
||||
- `error: "source_locked"`: a generation publish holds the file. Run the same `live-accept.mjs` command again; it is idempotent and will succeed once the publisher releases. Do not poll past it.
|
||||
- `error: "accept_receipt_conflict"`: this session already resolved as `priorOperation` (on `priorVariantId` for an accept), so the request contradicts durable truth. Do not edit. Run `live-status.mjs` and tell the user what the session actually resolved to.
|
||||
- anything else: report the error briefly and run `live-status.mjs` before continuing.
|
||||
- `_acceptResult.handled: false` without `mode`: manual cleanup: read file, find markers, edit.
|
||||
- `_completionAck.ok !== true`: do not poll yet. Run `live-status.mjs` / `live-resume.mjs`, finish cleanup manually if needed, then `live-complete.mjs --id EVENT_ID`.
|
||||
- `handled: true, carbonize: false`: nothing to do; poll again.
|
||||
- `handled: true, carbonize: true`: required cleanup below; `_acceptResult.todo`, `_completionAck.requiresComplete`, and the stderr banner all point at it.
|
||||
- `handled: false, mode: "fallback"`: the session lived in a generated file; you already wrote true source in fallback Step 3; clean the temporary wrapper and poll.
|
||||
- `handled: false, mode: "error"`: **do not hand-edit the file.** `source_locked`: rerun the same `live-accept.mjs` command (idempotent) until the publisher releases. `accept_receipt_conflict`: the session already resolved as `priorOperation`; run `live-status.mjs` and tell the user. Anything else: report briefly, run `live-status.mjs` first.
|
||||
- `handled: false` without `mode`: manual cleanup: read file, find markers, edit.
|
||||
|
||||
### Required after accept (carbonize)
|
||||
|
||||
When `_acceptResult.carbonize === true`, the accepted variant was stitched into source with helper markers and inline CSS so the browser can render it immediately with no visual gap. That stitch-in is **temporary**. The agent must rewrite it into permanent form before doing anything else. Skipping this leaves dead `@scope` rules for unaccepted variants, a pointless `data-impeccable-variant` wrapper, and `impeccable-carbonize-start/end` comment noise in the source file; all of which accumulate across sessions.
|
||||
`carbonize: true` means the accepted variant is stitched into source with helper markers and inline CSS (so the browser renders with no gap). That stitch-in is temporary; rewrite it into permanent form before anything else, or dead `@scope` rules, wrapper divs, and marker comments accumulate across sessions. Five steps, synchronously, before the next poll:
|
||||
|
||||
Do these five steps synchronously before the next poll. The source lock, generation epoch, and expected-source hash remain the final safety gates against a generator finishing concurrently with Accept.
|
||||
1. **Locate the carbonize block** in `_acceptResult.file`: bracketed by `<!-- impeccable-carbonize-start/end SESSION_ID -->` with a `<style data-impeccable-css>` element; read the `<!-- impeccable-param-values -->` comment first when present, it drives steps 3 and 4.
|
||||
2. **Move the CSS rules** into the project's real stylesheet (whichever already owns styling for the surrounding element).
|
||||
3. **Bake param values while rewriting selectors**: retarget `@scope ([data-impeccable-variant="N"])` to real semantic classes; keep only the `:scope[data-p-<id>="VALUE"]` branch matching the chosen value; substitute `var(--p-<id>)` literals or update the var's default.
|
||||
4. **Unwrap the accepted content**: delete the inner variant div (and on JSX the outer `data-impeccable-carbonize` div); drop `data-impeccable-params` and all `data-p-*` attributes.
|
||||
5. **Delete** the inline `<style>` block, the param-values comment, both carbonize markers, and any `@scope` rules for non-accepted variants.
|
||||
|
||||
1. **Locate the carbonize block** in the source file (`_acceptResult.file`). It's bracketed by `<!-- impeccable-carbonize-start SESSION_ID -->` and `<!-- impeccable-carbonize-end SESSION_ID -->` and contains a `<style data-impeccable-css="SESSION_ID">` element. If the variant declared parameters, an `<!-- impeccable-param-values SESSION_ID: {...} -->` comment sits alongside the style tag with the user's chosen values; read it first; it drives steps 3 and 4 below.
|
||||
2. **Move the CSS rules** into the project's real stylesheet. Which stylesheet depends on the project (e.g. `site/styles/workflow.css` for an Astro project, or the component's co-located CSS file for a Vite/Next project; pick whichever already owns styling for the surrounding element).
|
||||
3. **Bake in parameter values while rewriting selectors.** For `@scope ([data-impeccable-variant="N"])` wrappers: retarget to real, semantic classes on the accepted HTML (`.why-visual--v2 .v2-label { … }`). For `:scope[data-p-<id>="VALUE"]` selectors: keep only the branch matching the chosen value from the param-values comment; drop the others (they're dead after accept). For `var(--p-<id>, DEFAULT)` in the CSS: either substitute the literal value, or if the param is still useful as a knob going forward, leave the var and update its initial declaration to the chosen value.
|
||||
4. **Unwrap the accepted content.** Delete the inner `<div data-impeccable-variant="N" style="display: contents">` that wraps it. On JSX/TSX, also delete the outer `<div data-impeccable-carbonize="SESSION_ID" style={{ display: 'contents' }}>` wrapper if present (accept adds it so ternary/`return` slots keep a single root). Drop `data-impeccable-params` and any `data-p-*` attributes; those are live-mode plumbing, not source.
|
||||
5. **Delete the inline `<style>` block, the `<!-- impeccable-param-values -->` comment if present, and both `<!-- impeccable-carbonize-start/end -->` markers.** Also drop any `@scope` rules for variants other than the accepted one; those are dead code now.
|
||||
|
||||
After the file is clean, the cleanup owner runs `live-complete.mjs --id SESSION_ID` and verifies `phase: "completed"`. Poll again only after that verification.
|
||||
Then run `live-complete.mjs --id SESSION_ID` and verify `phase: "completed"` before polling again. The command is a gate, not a formality: it refuses with `error: "source_dirty"` plus findings while any live-mode leftover remains; fix and rerun (`--force` only for false positives).
|
||||
|
||||
## Handle `discard`
|
||||
|
||||
Event: `{id, _acceptResult, _completionAck}`. The poll script already restored the original, removed all variant markers, and acknowledged `discarded` durable completion. Nothing to do unless `_completionAck.ok !== true`; in that case run `live-complete.mjs --id EVENT_ID --discarded`, then poll again.
|
||||
Event: `{id, _acceptResult, _completionAck}`. The poll script already restored the original and acknowledged `discarded`. Nothing to do unless `_completionAck.ok !== true`; then `live-complete.mjs --id EVENT_ID --discarded` and poll again.
|
||||
|
||||
## Handle `steer`
|
||||
|
||||
Event: `{id, message, pageUrl}`. The user typed or spoke into the global bar **Steer** control: page-level direction without picking an element or launching variant generation.
|
||||
|
||||
The mic button uses the browser **Web Speech API** (MVP): click to start, speak, stop automatically when the utterance ends, then the transcript submits as a steer event. Click again while listening to cancel without submitting.
|
||||
|
||||
This is lighter than `generate`: no screenshot, no element context, no variant cycling. Read `message` and inspect the live page or project files as needed, then either make edits or answer in prose.
|
||||
|
||||
When finished:
|
||||
|
||||
```bash
|
||||
node .agents/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID steer_done ["Optional short note for a browser toast"]
|
||||
```
|
||||
|
||||
On failure:
|
||||
|
||||
```bash
|
||||
node .agents/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID error "Short reason"
|
||||
```
|
||||
|
||||
Then poll again immediately. Do not send a separate "picked up" reply. The Steer bar stays locked until `steer_done` or `error` arrives over SSE.
|
||||
Event: `{id, message, pageUrl}`: page-level direction from the global bar's Steer control (typed or spoken), no element context, no variant cycling. Read `message`, inspect the page or files as needed, make edits or answer in prose. Reply `node .agents/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID steer_done ["Optional short toast"]`, or on failure `--reply EVENT_ID error "Short reason"`, then poll immediately. No separate pickup reply; the Steer bar unlocks on `steer_done` or `error`.
|
||||
|
||||
## Handle `prefetch`
|
||||
|
||||
Event: `{pageUrl}`. The browser fires this the first time the user selects an element on a given route, as a latency shortcut; it signals the user is likely about to Go on a page you haven't read yet.
|
||||
|
||||
Resolve `pageUrl` to the underlying file:
|
||||
|
||||
- Root `/` → the `pageFile` returned by `live.mjs` (usually `public/index.html` or equivalent).
|
||||
- Sub-routes (e.g. `/docs`, `/docs/live`) → the generated or source file for that route. Use your knowledge of the project layout (multi-page static sites often resolve `/foo` → `public/foo/index.html`; SPAs may map all routes to a single entry).
|
||||
|
||||
Read the file into context, then poll again. No `--reply`: this is speculative pre-work; Go will come later. If you can't confidently resolve the route to a file, skip and poll again.
|
||||
|
||||
Dedupe is the browser's job (one prefetch per unique pathname per session); trust it. If the same file shows up twice from different routes mapping to the same file, the second Read is cached anyway.
|
||||
Event: `{pageUrl}`: fired once per route on first selection; the user is likely about to Go on a page you have not read. Resolve the route to its file (root `/` is usually the boot's `pageFile`; multi-page sites often map `/foo` to `public/foo/index.html`; SPAs map everything to one entry), read it, poll again. No `--reply`. If you cannot resolve it confidently, skip and poll.
|
||||
|
||||
## Handle `manual_edit_apply`
|
||||
|
||||
@@ -545,12 +310,7 @@ After source edits finish, reply exactly once with `node .agents/skills/impeccab
|
||||
|
||||
## Exit
|
||||
|
||||
The user can stop live mode by:
|
||||
- Saying "stop live mode" / "exit live" in chat
|
||||
- Closing the browser tab (SSE drops, poll returns `exit` after 8s)
|
||||
- The browser's exit button
|
||||
|
||||
When the poll returns `exit`, proceed to cleanup. If the poll is still running as a background task, kill it first.
|
||||
The user stops live mode by saying so in chat, closing the tab (SSE drops; poll returns `exit` after 8s), or the browser's exit button. On `exit`, kill any still-running background poll, then clean up.
|
||||
|
||||
## Cleanup
|
||||
|
||||
@@ -558,175 +318,8 @@ When the poll returns `exit`, proceed to cleanup. If the poll is still running a
|
||||
node .agents/skills/impeccable/scripts/live-server.mjs stop
|
||||
```
|
||||
|
||||
Stops the HTTP server and runs `live-inject.mjs --remove` to strip `localhost:…/live.js` from the HTML entry. To stop the server but keep the inject tag (for a quick restart), use `stop --keep-inject`. `.impeccable/live/config.json` persists as project config for future sessions.
|
||||
Stops the helper and runs `live-inject.mjs --remove` to strip the injected script (use `stop --keep-inject` to keep it for a quick restart; `.impeccable/live/config.json` persists as project config). Then search for and remove any leftover `impeccable-variants-start` wrappers and `impeccable-carbonize-start` blocks.
|
||||
|
||||
Then:
|
||||
- Remove any leftover variant wrappers (search for `impeccable-variants-start` markers).
|
||||
- Remove any leftover carbonize blocks (search for `impeccable-carbonize-start` markers).
|
||||
## First-time setup
|
||||
|
||||
## First-time setup (config missing or invalid)
|
||||
|
||||
If `live.mjs` outputs `{ ok: false, error: "config_missing" | "config_invalid", path }`, write the live config at the reported path. By default this is `.impeccable/live/config.json`.
|
||||
|
||||
Schema:
|
||||
|
||||
```json
|
||||
{
|
||||
"files": ["<path-or-glob>", "<path-or-glob>", ...],
|
||||
"exclude": ["<optional-glob>", ...],
|
||||
"insertBefore": "</body>",
|
||||
"commentSyntax": "html",
|
||||
"cspChecked": true
|
||||
}
|
||||
```
|
||||
|
||||
`files` is the inject target; **the HTML files the browser actually loads**, not necessarily source. Each entry is either a literal path (`"public/index.html"`) or a glob pattern (`"public/**/*.html"`). Tracked or generated doesn't matter here; wrap has its own generated-file guard and routes accepts through the fallback flow.
|
||||
|
||||
`exclude` (optional) is a list of glob patterns matching files to skip, even if a `files` glob would have included them. Use for email templates, demo fixtures, or any HTML that isn't a live page.
|
||||
|
||||
`cspChecked` tracks whether the CSP detection step below has already run. Absent on first setup; set to `true` after CSP is checked (whether patched, declined, or not needed).
|
||||
|
||||
**Hard-excluded paths (cannot be overridden).** `**/node_modules/**` and `**/.git/**` are never matched regardless of what the user writes. These are vendor/metadata directories and injecting into them would silently instrument third-party code.
|
||||
|
||||
**Glob syntax.** `**` matches any number of path segments (including zero), `*` matches any characters except `/`, `?` matches a single character except `/`. Paths are always relative to the project root with forward slashes.
|
||||
|
||||
| Framework | `files` | `insertBefore` | `commentSyntax` |
|
||||
|-----------|---------|----------------|-----------------|
|
||||
| SPA with single shell (Vite / React / Plain HTML) | `["index.html"]` | `</body>` | `html` |
|
||||
| Next.js (App Router) | `["app/layout.tsx"]` | `</body>` | `jsx` |
|
||||
| Next.js (Pages) | `["pages/_document.tsx"]` | `</body>` | `jsx` |
|
||||
| Nuxt | `["app.vue"]` | `</body>` | `html` |
|
||||
| Svelte / SvelteKit | `["src/app.html"]` | `</body>` | `html` |
|
||||
| TanStack Router (SPA, Vite) | `["index.html"]` | `</body>` | `html` |
|
||||
| TanStack Start (SSR) | `["src/routes/__root.tsx"]` | `<Scripts` | `jsx` |
|
||||
| Astro | `[" <root layout .astro>"]` | `</body>` | `html` |
|
||||
| Multi-page (separate HTML per route) | `["public/**/*.html"]`: a glob covering the served directory | `</body>` | `html` |
|
||||
|
||||
Pick an anchor that exists in every file (`</body>` almost always works). Use `insertAfter` if the anchor should match **after** a specific line.
|
||||
|
||||
**Framework adapters (auto-detected at inject time).** SvelteKit, Nuxt, and TanStack Start server-render their document shell, so a raw `<script>` in the entry template will not execute reliably. `live-inject.mjs` detects these from the project and routes to a dedicated adapter instead of the literal `files` patch: SvelteKit mounts a dev-only root component from `+layout.svelte`; Nuxt writes a dev-only `.client.ts` plugin; TanStack Start (detected by `@tanstack/react-start` plus `src/routes/__root.tsx`) patches the `__root` document to render a generated dev-only `src/impeccable/ImpeccableLiveRoot` component that appends the bundle on mount. The `files` value stays a valid detection/CSP hint but is not the literal insertion site. A plain TanStack Router SPA (no `@tanstack/react-start`) has a static `index.html` and takes the baseline Vite path with no adapter.
|
||||
|
||||
For multi-page sites, **prefer a glob over a literal file list**. New pages added later are picked up automatically on the next `live-inject.mjs` run; no config maintenance needed.
|
||||
|
||||
For multi-page sites whose pages are *rebuilt* by a generator (Astro, static-site generators, custom scripts like `build-sub-pages.js`), the inject survives only until the next regeneration. Re-run `live.mjs` after each build. Accept is unaffected; it writes to true source via the fallback flow.
|
||||
|
||||
### Drift-heal warning
|
||||
|
||||
On every `live.mjs` boot, after inject, the project is scanned for HTML files under common page-source roots (`public/`, `src/`, `app/`, `pages/`). If any exist that aren't covered by the resolved `files` list, the output includes a `configDrift` field:
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"serverPort": 8400,
|
||||
"pageFiles": [ "..." ],
|
||||
"configDrift": {
|
||||
"orphans": ["public/new-section/index.html", "public/docs/new-command.html"],
|
||||
"orphanCount": 2,
|
||||
"hint": "2 HTML file(s) exist but aren't in config.files. Consider adding them, or use a glob pattern like \"public/**/*.html\"."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
When `configDrift` is present, surface it to the user once per session before entering the poll loop:
|
||||
|
||||
> Noticed N HTML file(s) in the project that aren't in `config.files`:
|
||||
>
|
||||
> - `public/new-section/index.html`
|
||||
> - `public/docs/new-command.html`
|
||||
>
|
||||
> Add them, or switch `files` to a glob like `["public/**/*.html"]` and let it track new pages automatically?
|
||||
|
||||
Don't auto-update the config; let the user decide. `configDrift` is `null` when there's no drift.
|
||||
|
||||
### CSP detection (first-time only)
|
||||
|
||||
If `config.cspChecked === true`, skip this entire section. You already asked this user once; the answer sticks.
|
||||
|
||||
Otherwise, run the detection helper:
|
||||
|
||||
```bash
|
||||
node .agents/skills/impeccable/scripts/detect-csp.mjs
|
||||
```
|
||||
|
||||
Output: `{ shape, signals }` where `shape` is one of `append-arrays`, `append-string`, `middleware`, `meta-tag`, or `null`. The shape is named by *patch mechanism*, so one template covers many frameworks.
|
||||
|
||||
- **`null`**: no CSP; skip to writing `.impeccable/live/config.json` with `cspChecked: true`.
|
||||
- **`append-arrays`**: CSP defined as structured directive arrays. Auto-patchable. See *append-arrays* below. Covers:
|
||||
- Monorepo helpers with `additionalScriptSrc` / `additionalConnectSrc` options (Next.js + shared config package)
|
||||
- SvelteKit `kit.csp.directives`
|
||||
- Nuxt `nuxt-security` module's `contentSecurityPolicy`
|
||||
- **`append-string`**: CSP written as a literal value string. Auto-patchable. See *append-string* below. Covers:
|
||||
- Inline `next.config.*` `headers()` with a CSP literal
|
||||
- Nuxt `routeRules` / `nitro.routeRules` headers
|
||||
- **`middleware`** or **`meta-tag`**: rarer. Detected but not auto-patched in v1. Show the user the detected files and ask them to add `http://localhost:8400` to `script-src` and `connect-src` manually, then mark `cspChecked: true` and proceed.
|
||||
|
||||
#### Consent prompt template
|
||||
|
||||
Use this phrasing so the experience is consistent across agents:
|
||||
|
||||
> **CSP patch needed.** I detected a Content Security Policy in your project that blocks `http://localhost:8400`: the live picker won't load without an allowance. Here's the change I'd make:
|
||||
>
|
||||
> ```diff
|
||||
> [file: <patchTarget>]
|
||||
> [exact diff, 2–5 lines]
|
||||
> ```
|
||||
>
|
||||
> It's guarded by `NODE_ENV === "development"` so the extra entry only appears in dev and never reaches production. You can remove it any time by reverting this file. Apply? [y/n]
|
||||
|
||||
On "no": skip the patch, mention live won't work until the user adds the allowance manually, still write `cspChecked: true` (the question's been asked).
|
||||
|
||||
On "yes": apply the Shape-specific patch below, then write `cspChecked: true`.
|
||||
|
||||
#### append-arrays
|
||||
|
||||
CSP expressed as structured directive arrays. Patch mechanism: declare a dev-only array, spread it into the script-src and connect-src arrays.
|
||||
|
||||
**Declare near the top of the file that holds the CSP arrays:**
|
||||
|
||||
```ts
|
||||
// Dev-only allowance so impeccable live mode can load. Guarded by NODE_ENV.
|
||||
const __impeccableLiveDev =
|
||||
process.env.NODE_ENV === "development" ? ["http://localhost:8400"] : [];
|
||||
```
|
||||
|
||||
**Append `...__impeccableLiveDev` to the script-src and connect-src directive arrays.** Per-framework specifics:
|
||||
|
||||
- **Next.js + monorepo helper**: edit the *app's* `next.config.*` (not the shared helper), appending to `additionalScriptSrc` and `additionalConnectSrc` passed into `createBaseNextConfig` (or equivalent). Keeps the shared package clean.
|
||||
- **SvelteKit**: edit `svelte.config.js`, appending to `kit.csp.directives['script-src']` and `kit.csp.directives['connect-src']`.
|
||||
- **Nuxt + nuxt-security**: edit `nuxt.config.*`, appending to `security.headers.contentSecurityPolicy['script-src']` and `['connect-src']`.
|
||||
|
||||
Reference outputs:
|
||||
- `tests/framework-fixtures/nextjs-turborepo/expected-after-patch.ts` (Next.js)
|
||||
- `tests/framework-fixtures/sveltekit-csp/expected-after-patch.js` (SvelteKit)
|
||||
|
||||
Idempotency: if `__impeccableLiveDev` already exists in the file, the patch is already applied; skip asking and just mark `cspChecked: true`.
|
||||
|
||||
#### append-string
|
||||
|
||||
CSP built as a literal value string. Two-point patch: declare a dev-only string near the top, interpolate it into the CSP at the `script-src` and `connect-src` directives.
|
||||
|
||||
```ts
|
||||
// Dev-only allowance so impeccable live mode can load.
|
||||
const __impeccableLiveDev =
|
||||
process.env.NODE_ENV === "development" ? " http://localhost:8400" : "";
|
||||
```
|
||||
|
||||
Then in the CSP value string:
|
||||
- `script-src 'self' 'unsafe-inline'` → `` `script-src 'self' 'unsafe-inline'${__impeccableLiveDev}` ``
|
||||
- `connect-src 'self'` → `` `connect-src 'self'${__impeccableLiveDev}` ``
|
||||
|
||||
(Leading space on the dev string so it concatenates cleanly into the existing value. Convert the literal CSP directives into template strings as part of the edit if they aren't already.)
|
||||
|
||||
Per-framework specifics:
|
||||
- **Next.js inline `headers()`**: edit `next.config.*`, splicing the variable into the CSP value.
|
||||
- **Nuxt `routeRules`**: edit `nuxt.config.*`, splicing into the CSP in `routeRules['/**'].headers['Content-Security-Policy']`.
|
||||
|
||||
Reference outputs:
|
||||
- `tests/framework-fixtures/nextjs-inline-csp/expected-after-patch.js` (Next.js)
|
||||
- `tests/framework-fixtures/nuxt-csp/expected-after-patch.ts` (Nuxt)
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
If a user says "no" to the CSP patch at setup time and later complains that live doesn't work: their dev CSP blocks `http://localhost:8400`. Fix: delete `cspChecked` from `.impeccable/live/config.json` and re-run `live.mjs`: setup will ask again.
|
||||
|
||||
Then re-run `live.mjs`.
|
||||
Only when `live.mjs` reports `config_missing` / `config_invalid`, or `configDrift` needs explaining, or the config lacks `cspChecked`: read [live-setup.md](live-setup.md). It owns the config schema, the per-framework `files` table, injection adapters, drift healing, and the CSP detection and consent flow.
|
||||
|
||||
@@ -27,6 +27,7 @@ import {
|
||||
inlineSvelteComponentAccept,
|
||||
removeSvelteComponentSession,
|
||||
} from './live/svelte-component.mjs';
|
||||
import { enterLiveRoot } from './live/roots.mjs';
|
||||
|
||||
const ACCEPT_LOCK_WAIT_MS = 1_000;
|
||||
// Mirrors VARIANT_ID_PATTERN in live/event-validation.mjs, which gates the same
|
||||
@@ -946,6 +947,7 @@ function argVal(args, flag) {
|
||||
// Auto-execute when run directly
|
||||
const _running = process.argv[1];
|
||||
if (_running?.endsWith('live-accept.mjs') || _running?.endsWith('live-accept.mjs/')) {
|
||||
enterLiveRoot();
|
||||
acceptCli();
|
||||
}
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -3,8 +3,12 @@
|
||||
* Canonical durable completion acknowledgement for Impeccable live sessions.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { createLiveSessionStore } from './live/session-store.mjs';
|
||||
import { readLiveServerInfo } from './lib/impeccable-paths.mjs';
|
||||
import { enterLiveRoot } from './live/roots.mjs';
|
||||
import { verifyAcceptedFile } from './live/accept-verify.mjs';
|
||||
|
||||
function parseArgs(argv) {
|
||||
const out = { status: 'complete' };
|
||||
@@ -15,6 +19,7 @@ function parseArgs(argv) {
|
||||
else if (arg === '--discarded' || arg === '--discard') out.status = 'discarded';
|
||||
else if (arg === '--error') { out.status = 'agent_error'; out.message = argv[++i] || 'unknown error'; }
|
||||
else if (arg.startsWith('--error=')) { out.status = 'agent_error'; out.message = arg.slice('--error='.length); }
|
||||
else if (arg === '--force') out.force = true;
|
||||
else if (arg === '--help' || arg === '-h') out.help = true;
|
||||
}
|
||||
return out;
|
||||
@@ -23,10 +28,36 @@ function parseArgs(argv) {
|
||||
export async function completeCli() {
|
||||
const args = parseArgs(process.argv.slice(2));
|
||||
if (args.help || !args.id) {
|
||||
console.log(`Usage: node live-complete.mjs --id SESSION_ID [--discarded|--error MESSAGE]\n\nAppend the final durable session acknowledgement. Use after accept/discard cleanup is verified.`);
|
||||
console.log(`Usage: node live-complete.mjs --id SESSION_ID [--discarded|--error MESSAGE] [--force]\n\nAppend the final durable session acknowledgement. Use after accept/discard cleanup is verified.\nCompletion is refused while the session's source file still carries live-mode leftovers\n(markers, data-p-* attributes, unbaked --p-* vars); fix the file or pass --force.`);
|
||||
process.exit(args.help ? 0 : 1);
|
||||
}
|
||||
|
||||
// The carbonize contract used to be prose; this makes it mechanical. A
|
||||
// "complete" while the source still carries live plumbing is how markers
|
||||
// and dead param branches accumulated across sessions.
|
||||
if (args.status === 'complete' && !args.force) {
|
||||
const store = createLiveSessionStore({ cwd: process.cwd(), sessionId: args.id });
|
||||
const snapshot = store.getSnapshot(args.id, { includeCompleted: true });
|
||||
const sourceFile = snapshot?.sourceFile;
|
||||
const absSource = sourceFile ? path.resolve(process.cwd(), sourceFile) : null;
|
||||
const relSource = absSource ? path.relative(process.cwd(), absSource) : null;
|
||||
const insideProject = relSource !== null && relSource !== '' && !relSource.startsWith('..') && !path.isAbsolute(relSource);
|
||||
if (insideProject && !relSource.startsWith('node_modules' + path.sep) && !relSource.startsWith('node_modules/')) {
|
||||
const verify = verifyAcceptedFile(fs, absSource);
|
||||
if (!verify.clean) {
|
||||
console.log(JSON.stringify({
|
||||
ok: false,
|
||||
error: 'source_dirty',
|
||||
id: args.id,
|
||||
file: sourceFile,
|
||||
findings: verify.findings,
|
||||
hint: 'The accepted source still carries live-mode leftovers. Finish the carbonize cleanup (bake params, remove markers and data-p-* attributes), then run live-complete again. Use --force only if a finding is a false positive.',
|
||||
}, null, 2));
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const serverInfo = readServerInfo();
|
||||
const serverResult = serverInfo ? await completeThroughServer(serverInfo, args) : null;
|
||||
if (serverResult?.ok) {
|
||||
@@ -71,5 +102,6 @@ async function completeThroughServer(info, args) {
|
||||
|
||||
const _running = process.argv[1];
|
||||
if (_running?.endsWith('live-complete.mjs') || _running?.endsWith('live-complete.mjs/')) {
|
||||
enterLiveRoot();
|
||||
completeCli();
|
||||
}
|
||||
|
||||
@@ -7,6 +7,11 @@
|
||||
* every subsequent run, this script handles insert/remove deterministically
|
||||
* with zero LLM involvement.
|
||||
*
|
||||
* Framework knowledge lives in `live/frameworks/` — detection order, adapters,
|
||||
* the generic tag strategy, and the per-extension authoring traits live-wrap
|
||||
* reads. This file is the CLI around it: resolve config, resolve the
|
||||
* framework, heal orphaned artifacts, apply or remove, record the journal.
|
||||
*
|
||||
* Usage:
|
||||
* node live-inject.mjs --port PORT [--token TOKEN] # Insert the live script tag
|
||||
* node live-inject.mjs --remove # Remove the live script tag
|
||||
@@ -23,22 +28,36 @@ import path from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { resolveLiveConfigPath } from './lib/impeccable-paths.mjs';
|
||||
import {
|
||||
applySvelteKitLiveAdapter,
|
||||
detectSvelteKitProject,
|
||||
removeSvelteKitLiveAdapter,
|
||||
} from './live/sveltekit-adapter.mjs';
|
||||
describeInjectArtifacts,
|
||||
frameworkIgnorePatterns,
|
||||
resolveFramework,
|
||||
resolveSourceTraits,
|
||||
} from './live/frameworks/index.mjs';
|
||||
import {
|
||||
applyTanStackLiveAdapter,
|
||||
detectTanStackStartProject,
|
||||
removeTanStackLiveAdapter,
|
||||
} from './live/tanstack-adapter.mjs';
|
||||
clearInjectJournal,
|
||||
healInjectJournal,
|
||||
recordInjection,
|
||||
} from './live/frameworks/journal.mjs';
|
||||
import {
|
||||
buildTagBlock,
|
||||
insertTag,
|
||||
patchCspMeta,
|
||||
removeTag,
|
||||
revertCspMeta,
|
||||
} from './live/frameworks/tag-strategy.mjs';
|
||||
import { buildLiveScriptSrc } from './live/frameworks/script-src.mjs';
|
||||
import { enterLiveRoot } from './live/roots.mjs';
|
||||
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
||||
const CONFIG_PATH = resolveLiveConfigPath({ cwd: process.cwd(), scriptsDir: __dirname });
|
||||
const MARKER_OPEN_TEXT = 'impeccable-live-start';
|
||||
const MARKER_CLOSE_TEXT = 'impeccable-live-end';
|
||||
const NUXT_PLUGIN_MARKER = 'impeccable-live-nuxt-plugin';
|
||||
const NUXT_PLUGIN_NAME = 'impeccable-live.client.ts';
|
||||
// Resolved lazily so the enterLiveRoot() chdir in the CLI guard below takes
|
||||
// effect first; module scope runs before the guard.
|
||||
let CONFIG_PATH_CACHED = null;
|
||||
function CONFIG_PATH_GET() {
|
||||
if (!CONFIG_PATH_CACHED) {
|
||||
CONFIG_PATH_CACHED = resolveLiveConfigPath({ cwd: process.cwd(), scriptsDir: __dirname });
|
||||
}
|
||||
return CONFIG_PATH_CACHED;
|
||||
}
|
||||
const IGNORE_MARKER_OPEN = '# impeccable-live-ignore-start';
|
||||
const IGNORE_MARKER_CLOSE = '# impeccable-live-ignore-end';
|
||||
|
||||
@@ -47,6 +66,9 @@ export const LIVE_IGNORE_PATTERNS = Object.freeze([
|
||||
'.impeccable/hook.pending.json',
|
||||
'.impeccable/config.local.json',
|
||||
'.impeccable/live/server.json',
|
||||
'.impeccable/live/roots.json',
|
||||
'.impeccable/live/app-root.json',
|
||||
'.impeccable/live/inject-journal.json',
|
||||
'.impeccable/live/sessions/',
|
||||
'.impeccable/live/previews/',
|
||||
'.impeccable/live/annotations/',
|
||||
@@ -102,60 +124,61 @@ Output (JSON):
|
||||
}
|
||||
|
||||
if (args.includes('--check')) {
|
||||
if (!fs.existsSync(CONFIG_PATH)) {
|
||||
console.log(JSON.stringify({ ok: false, error: 'config_missing', path: CONFIG_PATH }));
|
||||
// Deliberately read-only: --check runs from status paths and must never
|
||||
// mutate the tree. Journal reconciliation happens on the inject run.
|
||||
if (!fs.existsSync(CONFIG_PATH_GET())) {
|
||||
console.log(JSON.stringify({ ok: false, error: 'config_missing', path: CONFIG_PATH_GET() }));
|
||||
process.exit(0);
|
||||
}
|
||||
let cfg;
|
||||
try {
|
||||
cfg = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
|
||||
cfg = JSON.parse(fs.readFileSync(CONFIG_PATH_GET(), 'utf-8'));
|
||||
} catch (err) {
|
||||
console.log(JSON.stringify({ ok: false, error: 'config_invalid', message: err.message, path: CONFIG_PATH }));
|
||||
console.log(JSON.stringify({ ok: false, error: 'config_invalid', message: err.message, path: CONFIG_PATH_GET() }));
|
||||
return;
|
||||
}
|
||||
try {
|
||||
validateConfig(cfg);
|
||||
} catch (err) {
|
||||
console.log(JSON.stringify({ ok: false, error: 'config_invalid', message: err.message, path: CONFIG_PATH }));
|
||||
console.log(JSON.stringify({ ok: false, error: 'config_invalid', message: err.message, path: CONFIG_PATH_GET() }));
|
||||
return;
|
||||
}
|
||||
console.log(JSON.stringify({ ok: true, config: cfg, path: CONFIG_PATH }));
|
||||
console.log(JSON.stringify({ ok: true, config: cfg, path: CONFIG_PATH_GET() }));
|
||||
return;
|
||||
}
|
||||
|
||||
// Load config
|
||||
if (!fs.existsSync(CONFIG_PATH)) {
|
||||
console.error(JSON.stringify({ ok: false, error: 'config_missing', path: CONFIG_PATH }));
|
||||
if (!fs.existsSync(CONFIG_PATH_GET())) {
|
||||
console.error(JSON.stringify({ ok: false, error: 'config_missing', path: CONFIG_PATH_GET() }));
|
||||
process.exit(1);
|
||||
}
|
||||
const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
|
||||
const config = JSON.parse(fs.readFileSync(CONFIG_PATH_GET(), 'utf-8'));
|
||||
validateConfig(config);
|
||||
|
||||
const resolvedFiles = resolveFiles(process.cwd(), config);
|
||||
const svelteKit = detectSvelteKitProject(process.cwd(), config);
|
||||
const nuxt = detectNuxtProject(process.cwd());
|
||||
const tanstack = svelteKit || nuxt ? null : detectTanStackStartProject(process.cwd());
|
||||
const cwd = process.cwd();
|
||||
const resolvedFiles = resolveFiles(cwd, config);
|
||||
const resolved = resolveFramework(cwd, config);
|
||||
const isAdapter = resolved?.framework.inject.kind === 'adapter';
|
||||
|
||||
if (args.includes('--remove')) {
|
||||
if (svelteKit) {
|
||||
const adapterResult = removeSvelteKitLiveAdapter({ cwd: process.cwd(), config });
|
||||
console.log(JSON.stringify({ ok: true, adapter: 'sveltekit', results: [adapterResult] }));
|
||||
return;
|
||||
}
|
||||
if (tanstack) {
|
||||
const adapterResult = removeTanStackLiveAdapter({ cwd: process.cwd(), project: tanstack });
|
||||
console.log(JSON.stringify({ ok: !adapterResult.error, adapter: 'tanstack-start', results: [adapterResult] }));
|
||||
if (adapterResult.error) process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
if (nuxt) {
|
||||
const adapterResult = removeNuxtLiveAdapter({ cwd: process.cwd(), project: nuxt });
|
||||
console.log(JSON.stringify({ ok: !adapterResult.error, adapter: 'nuxt', results: [adapterResult] }));
|
||||
if (adapterResult.error) process.exitCode = 1;
|
||||
if (isAdapter) {
|
||||
const adapterResult = resolved.framework.inject.remove({ cwd, config, project: resolved.project });
|
||||
const ok = !(adapterResult && adapterResult.error);
|
||||
// Anything the adapter could not reach (its detection may have shifted
|
||||
// since the session started) is still on the journal.
|
||||
const { healed } = healInjectJournal(cwd);
|
||||
clearInjectJournal(cwd);
|
||||
console.log(JSON.stringify({
|
||||
ok,
|
||||
adapter: resolved.framework.name,
|
||||
results: [adapterResult],
|
||||
healed: healed.length ? healed : undefined,
|
||||
}));
|
||||
if (!ok) process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
const results = resolvedFiles.map((relFile) => {
|
||||
const absFile = path.resolve(process.cwd(), relFile);
|
||||
const absFile = path.resolve(cwd, relFile);
|
||||
if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
|
||||
const content = fs.readFileSync(absFile, 'utf-8');
|
||||
const detagged = removeTag(content, config.commentSyntax);
|
||||
@@ -168,7 +191,9 @@ Output (JSON):
|
||||
cspReverted: updated !== detagged,
|
||||
};
|
||||
});
|
||||
console.log(JSON.stringify({ ok: true, results }));
|
||||
const { healed } = healInjectJournal(cwd);
|
||||
clearInjectJournal(cwd);
|
||||
console.log(JSON.stringify({ ok: true, results, healed: healed.length ? healed : undefined }));
|
||||
return;
|
||||
}
|
||||
|
||||
@@ -180,50 +205,68 @@ Output (JSON):
|
||||
process.exit(1);
|
||||
}
|
||||
// Optional server token: appended to the /live.js src so the token-gated
|
||||
// /live.js handler authorizes the browser fetch. `live.mjs` always passes it.
|
||||
// /live.js handler authorizes the browser fetch. `live.mjs` always passes
|
||||
// it; a manual `--port`-only invocation reads the running helper's token
|
||||
// from server.json instead of writing an unauthenticated URL that 401s.
|
||||
const tokenIdx = args.indexOf('--token');
|
||||
const token = tokenIdx !== -1 ? args[tokenIdx + 1] : undefined;
|
||||
const gitIgnore = ensureLiveGitIgnores(
|
||||
process.cwd(),
|
||||
nuxt ? [nuxt.pluginFile] : tanstack ? [tanstack.componentFile] : [],
|
||||
);
|
||||
let token = tokenIdx !== -1 ? args[tokenIdx + 1] : undefined;
|
||||
if (!token) {
|
||||
try {
|
||||
const info = JSON.parse(fs.readFileSync(path.join(cwd, '.impeccable', 'live', 'server.json'), 'utf-8'));
|
||||
// A record for a DIFFERENT port is a stale or foreign helper; its token
|
||||
// would 401 just the same, so only adopt a matching one.
|
||||
if (info?.token && Number(info.port) === port) token = info.token;
|
||||
} catch { /* no running helper recorded; keep legacy tokenless behavior */ }
|
||||
}
|
||||
|
||||
if (svelteKit) {
|
||||
const adapterResult = applySvelteKitLiveAdapter({ cwd: process.cwd(), port, token, config });
|
||||
console.log(JSON.stringify({ ok: true, port, adapter: 'sveltekit', gitIgnore, results: [adapterResult] }));
|
||||
return;
|
||||
}
|
||||
if (tanstack) {
|
||||
const adapterResult = applyTanStackLiveAdapter({ cwd: process.cwd(), port, token, project: tanstack });
|
||||
console.log(JSON.stringify({
|
||||
ok: !adapterResult.error,
|
||||
// Reconcile before writing anything. Artifacts this run is about to own are
|
||||
// kept (so a repeat inject stays byte-idempotent); artifacts left behind by
|
||||
// a session that never got to stop are healed.
|
||||
const plannedArtifacts = describeInjectArtifacts(resolved, { cwd, files: resolvedFiles });
|
||||
const { healed } = healInjectJournal(cwd, { keep: plannedArtifacts.map((a) => a.path) });
|
||||
|
||||
const gitIgnore = ensureLiveGitIgnores(cwd, frameworkIgnorePatterns(resolved));
|
||||
// In a nested-app repo the roots pointer lives at the REPO root, outside the
|
||||
// reach of the appRoot-relative ignore block above; give that directory its
|
||||
// own local excludes so the pointer (absolute host paths) never gets staged.
|
||||
try {
|
||||
const rootsManifest = JSON.parse(fs.readFileSync(path.join(cwd, '.impeccable', 'live', 'roots.json'), 'utf-8'));
|
||||
if (rootsManifest?.repoRoot && path.resolve(rootsManifest.repoRoot) !== path.resolve(cwd)) {
|
||||
ensureLiveGitIgnores(rootsManifest.repoRoot);
|
||||
}
|
||||
} catch { /* no manifest: single-root project */ }
|
||||
|
||||
if (isAdapter) {
|
||||
const adapterResult = resolved.framework.inject.apply({
|
||||
cwd,
|
||||
port,
|
||||
adapter: 'tanstack-start',
|
||||
token,
|
||||
config,
|
||||
project: resolved.project,
|
||||
});
|
||||
const ok = !(adapterResult && adapterResult.error);
|
||||
if (ok) recordInjection(cwd, { framework: resolved.framework.name, port, artifacts: plannedArtifacts });
|
||||
console.log(JSON.stringify({
|
||||
ok,
|
||||
port,
|
||||
adapter: resolved.framework.name,
|
||||
gitIgnore,
|
||||
results: [adapterResult],
|
||||
healed: healed.length ? healed : undefined,
|
||||
}));
|
||||
if (adapterResult.error) process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
if (nuxt) {
|
||||
const adapterResult = applyNuxtLiveAdapter({ cwd: process.cwd(), port, token, project: nuxt });
|
||||
console.log(JSON.stringify({
|
||||
ok: !adapterResult.error,
|
||||
port,
|
||||
adapter: 'nuxt',
|
||||
gitIgnore,
|
||||
results: [adapterResult],
|
||||
}));
|
||||
if (adapterResult.error) process.exitCode = 1;
|
||||
if (!ok) process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
|
||||
const results = resolvedFiles.map((relFile) => {
|
||||
const absFile = path.resolve(process.cwd(), relFile);
|
||||
const absFile = path.resolve(cwd, relFile);
|
||||
if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
|
||||
const content = fs.readFileSync(absFile, 'utf-8');
|
||||
const withoutOld = revertCspMeta(removeTag(content, config.commentSyntax));
|
||||
const withTag = insertTag(withoutOld, config, port, relFile, token);
|
||||
// Per-file, not per-project: a Vite app can hold an .astro partial, and a
|
||||
// framework project's entry template is often plain HTML.
|
||||
const scriptAttrs = resolveSourceTraits(relFile).injectScriptAttrs;
|
||||
const withTag = insertTag(withoutOld, config, port, token, scriptAttrs);
|
||||
if (withTag === withoutOld) {
|
||||
return { file: relFile, error: 'insertion_point_not_found', anchor: config.insertBefore || config.insertAfter };
|
||||
}
|
||||
@@ -236,7 +279,19 @@ Output (JSON):
|
||||
};
|
||||
});
|
||||
const anyInserted = results.some((r) => r.inserted);
|
||||
console.log(JSON.stringify({ ok: anyInserted, port, gitIgnore, results }));
|
||||
const writtenFiles = new Set(results.filter((r) => r.inserted).map((r) => r.file));
|
||||
recordInjection(cwd, {
|
||||
framework: resolved?.framework.name,
|
||||
port,
|
||||
artifacts: plannedArtifacts.filter((a) => writtenFiles.has(a.path)),
|
||||
});
|
||||
console.log(JSON.stringify({
|
||||
ok: anyInserted,
|
||||
port,
|
||||
gitIgnore,
|
||||
results,
|
||||
healed: healed.length ? healed : undefined,
|
||||
}));
|
||||
if (!anyInserted) process.exit(1);
|
||||
}
|
||||
|
||||
@@ -271,115 +326,6 @@ export function ensureLiveGitIgnores(cwd = process.cwd(), extraPatterns = []) {
|
||||
};
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Nuxt adapter
|
||||
//
|
||||
// A script element placed in app.vue is compiled as Vue-rendered DOM and is
|
||||
// not executed. Nuxt instead auto-discovers client plugins. Keep the adapter
|
||||
// generated, dev-only, and outside user-authored source: Live creates one
|
||||
// marked .client.ts plugin on start and removes it on stop.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export function detectNuxtProject(cwd = process.cwd()) {
|
||||
const configFile = fs.readdirSync(cwd, { withFileTypes: true })
|
||||
.find((entry) => entry.isFile() && /^nuxt\.config\.(?:js|mjs|cjs|ts|mts|cts)$/.test(entry.name))
|
||||
?.name;
|
||||
if (!configFile) return null;
|
||||
|
||||
const config = fs.readFileSync(path.join(cwd, configFile), 'utf-8');
|
||||
const literalSrcDir = config.match(/\bsrcDir\s*:\s*(['"])([^'"]+)\1/);
|
||||
let appDir = '';
|
||||
if (literalSrcDir) {
|
||||
const candidate = literalSrcDir[2]
|
||||
.replace(/\\/g, '/')
|
||||
.replace(/^\.\//, '')
|
||||
.replace(/\/+$/, '');
|
||||
const normalized = path.posix.normalize(candidate);
|
||||
if (normalized !== '..' && !normalized.startsWith('../') && !path.isAbsolute(normalized)) {
|
||||
appDir = normalized === '.' ? '' : normalized;
|
||||
}
|
||||
} else if (
|
||||
fs.existsSync(path.join(cwd, 'app', 'app.vue'))
|
||||
|| fs.existsSync(path.join(cwd, 'app', 'pages'))
|
||||
) {
|
||||
appDir = 'app';
|
||||
}
|
||||
|
||||
const pluginFile = [appDir, 'plugins', NUXT_PLUGIN_NAME].filter(Boolean).join('/');
|
||||
return { configFile, appDir, pluginFile };
|
||||
}
|
||||
|
||||
export function buildNuxtPlugin(port, token) {
|
||||
return `/* ${NUXT_PLUGIN_MARKER} */
|
||||
const liveSrc = '${buildLiveScriptSrc(port, token)}';
|
||||
const liveSelector = 'script[data-impeccable-live-nuxt]';
|
||||
|
||||
export default defineNuxtPlugin(() => {
|
||||
if (!import.meta.dev || typeof document === 'undefined') return;
|
||||
|
||||
const expectedSrc = new URL(liveSrc, window.location.href).href;
|
||||
let script = document.querySelector(liveSelector);
|
||||
if (script?.src === expectedSrc) return;
|
||||
script?.remove();
|
||||
|
||||
script = document.createElement('script');
|
||||
script.src = liveSrc;
|
||||
script.async = true;
|
||||
script.dataset.impeccableLiveNuxt = '';
|
||||
document.head.appendChild(script);
|
||||
|
||||
import.meta.hot?.dispose(() => {
|
||||
if (script?.isConnected) script.remove();
|
||||
});
|
||||
});
|
||||
/* /${NUXT_PLUGIN_MARKER} */
|
||||
`;
|
||||
}
|
||||
|
||||
export function applyNuxtLiveAdapter({ cwd = process.cwd(), port, token, project = detectNuxtProject(cwd) }) {
|
||||
if (!project) return { error: 'nuxt_not_detected' };
|
||||
const absFile = path.join(cwd, project.pluginFile);
|
||||
const existing = fs.existsSync(absFile) ? fs.readFileSync(absFile, 'utf-8') : null;
|
||||
if (existing !== null && !existing.includes(NUXT_PLUGIN_MARKER)) {
|
||||
return {
|
||||
file: project.pluginFile,
|
||||
error: 'nuxt_plugin_conflict',
|
||||
hint: `${project.pluginFile} already exists and is not managed by Impeccable Live`,
|
||||
};
|
||||
}
|
||||
|
||||
const content = buildNuxtPlugin(port, token);
|
||||
fs.mkdirSync(path.dirname(absFile), { recursive: true });
|
||||
if (content !== existing) fs.writeFileSync(absFile, content, 'utf-8');
|
||||
return {
|
||||
file: project.pluginFile,
|
||||
inserted: true,
|
||||
changed: content !== existing,
|
||||
devOnly: true,
|
||||
};
|
||||
}
|
||||
|
||||
export function removeNuxtLiveAdapter({ cwd = process.cwd(), project = detectNuxtProject(cwd) }) {
|
||||
if (!project) return { error: 'nuxt_not_detected' };
|
||||
const absFile = path.join(cwd, project.pluginFile);
|
||||
if (!fs.existsSync(absFile)) {
|
||||
return { file: project.pluginFile, removed: false, note: 'no adapter present' };
|
||||
}
|
||||
const content = fs.readFileSync(absFile, 'utf-8');
|
||||
if (!content.includes(NUXT_PLUGIN_MARKER)) {
|
||||
return {
|
||||
file: project.pluginFile,
|
||||
removed: false,
|
||||
error: 'nuxt_plugin_conflict',
|
||||
hint: `${project.pluginFile} is not managed by Impeccable Live`,
|
||||
};
|
||||
}
|
||||
fs.unlinkSync(absFile);
|
||||
const pluginDir = path.dirname(absFile);
|
||||
if (fs.readdirSync(pluginDir).length === 0) fs.rmdirSync(pluginDir);
|
||||
return { file: project.pluginFile, removed: true };
|
||||
}
|
||||
|
||||
function resolveIgnoreTarget(cwd) {
|
||||
const gitExcludePath = resolveGitInfoExcludePath(cwd);
|
||||
if (gitExcludePath) {
|
||||
@@ -527,242 +473,31 @@ function validateConfig(cfg) {
|
||||
}
|
||||
}
|
||||
|
||||
function commentOpen(syntax) { return syntax === 'jsx' ? '{/*' : '<!--'; }
|
||||
function commentClose(syntax) { return syntax === 'jsx' ? '*/}' : '-->'; }
|
||||
|
||||
/**
|
||||
* Build the /live.js src the browser loads. When a token is supplied it rides
|
||||
* as a `?token=...` query param so the server's token-gated /live.js handler
|
||||
* authorizes the fetch. Shared by every injection path (HTML/JSX script tag,
|
||||
* the Nuxt plugin, the SvelteKit root component) so they stay in sync.
|
||||
*/
|
||||
export function buildLiveScriptSrc(port, token) {
|
||||
const base = 'http://localhost:' + port + '/live.js';
|
||||
return token ? base + '?token=' + encodeURIComponent(token) : base;
|
||||
}
|
||||
|
||||
function buildTagBlock(syntax, port, filePath, token) {
|
||||
const open = commentOpen(syntax);
|
||||
const close = commentClose(syntax);
|
||||
// Astro processes <script> tags by default and rewrites src to its own
|
||||
// bundled URL. is:inline opts out so the literal external src survives.
|
||||
const isAstro = typeof filePath === 'string' && filePath.endsWith('.astro');
|
||||
const scriptAttrs = isAstro ? 'is:inline ' : '';
|
||||
return (
|
||||
open + ' ' + MARKER_OPEN_TEXT + ' ' + close + '\n' +
|
||||
'<script ' + scriptAttrs + 'src="' + buildLiveScriptSrc(port, token) + '"></script>\n' +
|
||||
open + ' ' + MARKER_CLOSE_TEXT + ' ' + close + '\n'
|
||||
);
|
||||
}
|
||||
|
||||
function detectLineEnding(content) {
|
||||
if (content.includes('\r\n')) return '\r\n';
|
||||
if (content.includes('\r')) return '\r';
|
||||
return '\n';
|
||||
}
|
||||
|
||||
function normalizeLineEndings(content, lineEnding) {
|
||||
return lineEnding === '\n' ? content : content.replace(/\n/g, lineEnding);
|
||||
}
|
||||
|
||||
function readLineEndingAt(content, index) {
|
||||
if (content[index] === '\r' && content[index + 1] === '\n') return '\r\n';
|
||||
if (content[index] === '\n') return '\n';
|
||||
if (content[index] === '\r') return '\r';
|
||||
return '';
|
||||
}
|
||||
|
||||
function insertTag(content, config, port, filePath, token) {
|
||||
const lineEnding = detectLineEnding(content);
|
||||
const block = normalizeLineEndings(buildTagBlock(config.commentSyntax, port, filePath, token), lineEnding);
|
||||
// insertBefore: match the LAST occurrence. Anchors like `</body>` naturally
|
||||
// belong at the end, and the same literal can appear earlier in code blocks
|
||||
// within rendered documentation pages.
|
||||
if (config.insertBefore) {
|
||||
const idx = content.lastIndexOf(config.insertBefore);
|
||||
if (idx === -1) return content;
|
||||
return content.slice(0, idx) + block + content.slice(idx);
|
||||
}
|
||||
// insertAfter: match the FIRST occurrence — typical anchors like `<head>` or
|
||||
// `<body>` open near the top of the document.
|
||||
const idx = content.indexOf(config.insertAfter);
|
||||
if (idx === -1) return content;
|
||||
const after = idx + config.insertAfter.length;
|
||||
// Preserve an existing trailing newline if the anchor already has one.
|
||||
// Slice the remainder from the original anchor offset, not prefix.length:
|
||||
// in the no-newline case prefix is one char longer than the anchor (the
|
||||
// appended '\n'), so slicing by prefix.length would drop the first real
|
||||
// character after the anchor (#227).
|
||||
const existingNewline = readLineEndingAt(content, after);
|
||||
const prefix = content.slice(0, after) + (existingNewline || lineEnding);
|
||||
const rest = content.slice(after + existingNewline.length);
|
||||
return prefix + block + rest;
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove the live script block. Matches either HTML or JSX comment markers
|
||||
* regardless of config (so stale tags from a wrong config can still be cleaned).
|
||||
*
|
||||
* Indent-preserving: captures any whitespace immediately preceding the opener
|
||||
* marker and re-emits it in place of the removed block. `insertTag` inserted
|
||||
* the block *after* the original line's indent and *before* the anchor (e.g.
|
||||
* `</body>`), which moved the indent onto the opener line and left the anchor
|
||||
* unindented. Replacing the whole block (plus its trailing newline) with just
|
||||
* the captured indent hands the indent back to the anchor that follows.
|
||||
*/
|
||||
function removeTag(content, _syntax) {
|
||||
const patterns = [
|
||||
/([ \t]*)<!--\s*impeccable-live-start\s*-->[\s\S]*?<!--\s*impeccable-live-end\s*-->([ \t]*(?:\r\n|\n|\r|$)?)/,
|
||||
/([ \t]*)\{\/\*\s*impeccable-live-start\s*\*\/\}[\s\S]*?\{\/\*\s*impeccable-live-end\s*\*\/\}([ \t]*(?:\r\n|\n|\r|$)?)/,
|
||||
];
|
||||
for (const pat of patterns) {
|
||||
let changed = false;
|
||||
let next = content;
|
||||
do {
|
||||
content = next;
|
||||
next = content.replace(pat, (_match, leadingIndent, trailing = '') => {
|
||||
if (/[\r\n]/.test(trailing)) return leadingIndent;
|
||||
return leadingIndent || trailing || '';
|
||||
});
|
||||
if (next !== content) changed = true;
|
||||
} while (next !== content);
|
||||
if (changed) return next;
|
||||
}
|
||||
return content;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Content-Security-Policy meta-tag patcher
|
||||
//
|
||||
// When the user's HTML carries `<meta http-equiv="Content-Security-Policy">`,
|
||||
// the cross-origin load of /live.js (and the SSE/POST connection back to
|
||||
// localhost:PORT) is blocked unless the CSP explicitly allows that origin.
|
||||
//
|
||||
// On insert: append `http://localhost:PORT` to `script-src` and `connect-src`,
|
||||
// and stash the original `content` value in a `data-impeccable-csp-original`
|
||||
// attribute (base64) so revert is exact.
|
||||
//
|
||||
// On remove: detect the marker attribute, decode it, restore the original
|
||||
// content value verbatim, drop the marker.
|
||||
//
|
||||
// Header-based CSP (Next.js headers, Nuxt routeRules, SvelteKit kit.csp,
|
||||
// shared helpers) is NOT patched here — those need framework-specific config
|
||||
// edits and are handled via the existing detect-csp.mjs reference output.
|
||||
// Only the in-source meta-tag form gets the auto-patch.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const CSP_MARKER_ATTR = 'data-impeccable-csp-original';
|
||||
|
||||
function findCspMetaTags(content) {
|
||||
const out = [];
|
||||
const tagRe = /<meta\s+([^>]*?)\/?>/gis;
|
||||
let m;
|
||||
while ((m = tagRe.exec(content)) !== null) {
|
||||
const attrs = m[1];
|
||||
if (!/(http-equiv|httpEquiv)\s*=\s*(['"])Content-Security-Policy\2/i.test(attrs)) continue;
|
||||
out.push({ start: m.index, end: m.index + m[0].length, full: m[0], attrs });
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function getAttr(attrs, name) {
|
||||
const re = new RegExp(`\\b${name}\\s*=\\s*(['"])([\\s\\S]*?)\\1`, 'i');
|
||||
const m = attrs.match(re);
|
||||
return m ? { quote: m[1], value: m[2], full: m[0] } : null;
|
||||
}
|
||||
|
||||
function appendOriginToDirective(csp, directive, origin) {
|
||||
const re = new RegExp(`(^|;)(\\s*)(${directive})\\s+([^;]*)`, 'i');
|
||||
const m = csp.match(re);
|
||||
if (m) {
|
||||
const tokens = m[4].trim().split(/\s+/);
|
||||
if (tokens.includes(origin)) return csp;
|
||||
return csp.replace(re, `${m[1]}${m[2]}${m[3]} ${[...tokens, origin].join(' ')}`);
|
||||
}
|
||||
// Directive missing — add it. Use 'self' + origin so we don't inadvertently
|
||||
// narrow the policy compared to the default-src fallback (most users with
|
||||
// an explicit CSP have 'self' there).
|
||||
return csp.trim().replace(/;?\s*$/, '') + `; ${directive} 'self' ${origin}`;
|
||||
}
|
||||
|
||||
export function patchCspMeta(content, port) {
|
||||
const tags = findCspMetaTags(content);
|
||||
if (tags.length === 0) return content;
|
||||
const origin = `http://localhost:${port}`;
|
||||
|
||||
// Walk last-to-first so prior splices don't invalidate later indices.
|
||||
let result = content;
|
||||
for (let i = tags.length - 1; i >= 0; i--) {
|
||||
const tag = tags[i];
|
||||
const attrs = tag.attrs;
|
||||
if (getAttr(attrs, CSP_MARKER_ATTR)) continue; // already patched
|
||||
const contentAttr = getAttr(attrs, 'content');
|
||||
if (!contentAttr) continue;
|
||||
|
||||
const original = contentAttr.value;
|
||||
let patched = original;
|
||||
patched = appendOriginToDirective(patched, 'script-src', origin);
|
||||
patched = appendOriginToDirective(patched, 'connect-src', origin);
|
||||
// The shader overlay during 'generating' creates a screenshot via
|
||||
// URL.createObjectURL, producing a `blob:` URL — img-src 'self' rejects
|
||||
// those. Add `blob:` so the overlay doesn't throw a CSP violation.
|
||||
patched = appendOriginToDirective(patched, 'img-src', 'blob:');
|
||||
if (patched === original) continue;
|
||||
|
||||
const newContentAttr = `content=${contentAttr.quote}${patched}${contentAttr.quote}`;
|
||||
const marker = `${CSP_MARKER_ATTR}="${Buffer.from(original, 'utf-8').toString('base64')}"`;
|
||||
// The tagRe captures any whitespace between the last attribute and the
|
||||
// closing `/>` as part of `attrs`. Naively appending ` ${marker}` after
|
||||
// a replace would land it BEFORE that trailing space, leaving a double
|
||||
// space inside attrs and clobbering the space before `/>`. Split off
|
||||
// the trailing whitespace, splice the marker into the attribute body,
|
||||
// and re-append the original trailing whitespace so a self-closing
|
||||
// `<meta … />` round-trips byte-for-byte.
|
||||
const trailingWs = (attrs.match(/[ \t]*$/) || [''])[0];
|
||||
const attrsBody = attrs.slice(0, attrs.length - trailingWs.length);
|
||||
const newAttrs = attrsBody.replace(contentAttr.full, newContentAttr) + ' ' + marker + trailingWs;
|
||||
const newTag = tag.full.replace(attrs, newAttrs);
|
||||
|
||||
result = result.slice(0, tag.start) + newTag + result.slice(tag.end);
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
export function revertCspMeta(content) {
|
||||
const tags = findCspMetaTags(content);
|
||||
if (tags.length === 0) return content;
|
||||
|
||||
let result = content;
|
||||
for (let i = tags.length - 1; i >= 0; i--) {
|
||||
const tag = tags[i];
|
||||
const origAttr = getAttr(tag.attrs, CSP_MARKER_ATTR);
|
||||
if (!origAttr) continue;
|
||||
const contentAttr = getAttr(tag.attrs, 'content');
|
||||
if (!contentAttr) continue;
|
||||
|
||||
let originalValue;
|
||||
try { originalValue = Buffer.from(origAttr.value, 'base64').toString('utf-8'); }
|
||||
catch { continue; }
|
||||
|
||||
const newContentAttr = `content=${contentAttr.quote}${originalValue}${contentAttr.quote}`;
|
||||
let newAttrs = tag.attrs.replace(contentAttr.full, newContentAttr);
|
||||
// Drop the marker attribute and any single space immediately preceding it.
|
||||
newAttrs = newAttrs.replace(new RegExp(`\\s*${origAttr.full}`), '');
|
||||
const newTag = tag.full.replace(tag.attrs, newAttrs);
|
||||
|
||||
result = result.slice(0, tag.start) + newTag + result.slice(tag.end);
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Auto-execute
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const _running = process.argv[1];
|
||||
if (_running?.endsWith('live-inject.mjs') || _running?.endsWith('live-inject.mjs/')) {
|
||||
enterLiveRoot();
|
||||
injectCli();
|
||||
}
|
||||
|
||||
export { insertTag, removeTag, validateConfig, buildTagBlock };
|
||||
// patchCspMeta + revertCspMeta are exported above where they're defined.
|
||||
// Re-exported so long-standing importers (live.mjs, the adapter modules, the
|
||||
// test suites) keep their entry points while the implementations live in
|
||||
// live/frameworks/.
|
||||
export {
|
||||
buildLiveScriptSrc,
|
||||
buildTagBlock,
|
||||
insertTag,
|
||||
patchCspMeta,
|
||||
removeTag,
|
||||
revertCspMeta,
|
||||
validateConfig,
|
||||
};
|
||||
export {
|
||||
applyNuxtLiveAdapter,
|
||||
buildNuxtPlugin,
|
||||
detectNuxtProject,
|
||||
removeNuxtLiveAdapter,
|
||||
} from './live/frameworks/nuxt.mjs';
|
||||
|
||||
@@ -26,6 +26,7 @@ import {
|
||||
scaffoldSvelteComponentInsertSession,
|
||||
shouldUseSvelteComponentInjection,
|
||||
} from './live/svelte-component.mjs';
|
||||
import { enterLiveRoot } from './live/roots.mjs';
|
||||
|
||||
const INSERT_POSITIONS = new Set(['before', 'after']);
|
||||
|
||||
@@ -286,5 +287,6 @@ Output (JSON):
|
||||
|
||||
const _running = process.argv[1];
|
||||
if (_running?.endsWith('live-insert.mjs') || _running?.endsWith('live-insert.mjs/')) {
|
||||
enterLiveRoot();
|
||||
insertCli();
|
||||
}
|
||||
|
||||
@@ -14,6 +14,8 @@ import path from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { completionAckForAcceptResult, completionTypeForAcceptResult } from './live/completion.mjs';
|
||||
import { readLiveServerInfo } from './lib/impeccable-paths.mjs';
|
||||
import { enterLiveRoot } from './live/roots.mjs';
|
||||
import { instructionsForEvent } from './live/instructions.mjs';
|
||||
|
||||
// Absolute path to a sibling script in this skill's scripts dir, so runtime
|
||||
// error hints print a directly-runnable command instead of a placeholder.
|
||||
@@ -27,7 +29,7 @@ const scriptCmd = (name) => `node "${path.join(SELF_DIR, name)}"`;
|
||||
export const PER_REQUEST_TIMEOUT_MS = 270_000;
|
||||
export const DEFAULT_EVENT_LEASE_MS = 600_000;
|
||||
|
||||
const EVENT_TYPES_NEEDING_AGENT_REPLY = new Set(['generate', 'steer', 'manual_edit_apply', 'carbonize_cleanup']);
|
||||
const EVENT_TYPES_NEEDING_AGENT_REPLY = new Set(['generate', 'steer', 'manual_edit_apply', 'carbonize_cleanup', 'variant_mount_failed']);
|
||||
|
||||
function readServerInfo() {
|
||||
const record = readLiveServerInfo(process.cwd());
|
||||
@@ -117,8 +119,11 @@ export async function postReply(base, token, reply) {
|
||||
});
|
||||
if (!res.ok) {
|
||||
const body = await res.json().catch(() => ({}));
|
||||
const parts = [body.error || res.statusText, body.reason, body.hint].filter(Boolean);
|
||||
throw new Error(parts.join(': '));
|
||||
const failureLines = Array.isArray(body.failures)
|
||||
? body.failures.map((f) => ` ${f.file}${f.line != null ? `:${f.line}` : ''} ${f.message}`).join('\n')
|
||||
: null;
|
||||
const parts = [body.error || res.statusText, body.reason, body.hint, failureLines, body._instructions].filter(Boolean);
|
||||
throw new Error(parts.join('\n'));
|
||||
}
|
||||
}
|
||||
|
||||
@@ -261,6 +266,13 @@ export function writeCarbonizeBanner(event) {
|
||||
}
|
||||
|
||||
export function printPollEvent(event) {
|
||||
// Situational plumbing rides with the event itself: `_instructions` is the
|
||||
// authoritative next step, with real ids and paths substituted, so the
|
||||
// reference doc can stay lean and can never drift from script behavior.
|
||||
if (event && typeof event === 'object' && !event._instructions) {
|
||||
const instructions = instructionsForEvent(event, { scriptsPath: SELF_DIR });
|
||||
if (instructions) event._instructions = instructions;
|
||||
}
|
||||
console.log(JSON.stringify(event));
|
||||
}
|
||||
|
||||
@@ -412,5 +424,6 @@ export function normalizePollTypes(value) {
|
||||
// Auto-execute when run directly
|
||||
const _running = process.argv[1];
|
||||
if (_running?.endsWith('live-poll.mjs') || _running?.endsWith('live-poll.mjs/')) {
|
||||
enterLiveRoot();
|
||||
pollCli();
|
||||
}
|
||||
|
||||
@@ -4,6 +4,7 @@
|
||||
*/
|
||||
|
||||
import { createLiveSessionStore } from './live/session-store.mjs';
|
||||
import { enterLiveRoot } from './live/roots.mjs';
|
||||
|
||||
function manualApplyReplyCommand(eventOrId = 'EVENT_ID') {
|
||||
const id = typeof eventOrId === 'string' ? eventOrId : eventOrId?.id || 'EVENT_ID';
|
||||
@@ -49,6 +50,28 @@ function collectManualApplyFiles(batch) {
|
||||
return [...new Set(files.filter((file) => typeof file === 'string' && file.length > 0))].sort();
|
||||
}
|
||||
|
||||
/**
|
||||
* The browser's render truth, folded into a small block the agent reads before
|
||||
* it decides what to do. `arrivedVariants` only says the agent published;
|
||||
* `renderState` says whether any of it reached a screen.
|
||||
*/
|
||||
export function renderSummary(snapshot = {}) {
|
||||
return {
|
||||
renderState: snapshot.renderState ?? null,
|
||||
mountedVariants: Array.isArray(snapshot.mountedVariants) ? snapshot.mountedVariants : [],
|
||||
mountFailures: Array.isArray(snapshot.mountFailures) ? snapshot.mountFailures : [],
|
||||
};
|
||||
}
|
||||
|
||||
export function mountFailureAction(snapshot = {}) {
|
||||
const failures = Array.isArray(snapshot.mountFailures) ? snapshot.mountFailures : [];
|
||||
const latest = failures[failures.length - 1];
|
||||
if (!latest) return null;
|
||||
const where = latest.url ? ` from ${latest.url}` : '';
|
||||
const why = latest.error ? ` (${latest.error})` : '';
|
||||
return `The browser failed to mount variant ${latest.variant}${where}${why}; nothing is on screen. Fix the variant files, then reply with live-poll.mjs --reply ${snapshot?.pendingEvent?.id || snapshot?.id || 'SESSION_ID'} done --file <manifest or source path> for the queued variant_mount_failed event (or republish) so the browser retries.`;
|
||||
}
|
||||
|
||||
function parseArgs(argv) {
|
||||
const out = { id: null };
|
||||
for (let i = 0; i < argv.length; i++) {
|
||||
@@ -75,20 +98,26 @@ export async function resumeCli() {
|
||||
}
|
||||
|
||||
const pending = snapshot.pendingEvent || null;
|
||||
const nextAction = pending
|
||||
? pending.type === 'manual_edit_apply'
|
||||
? manualApplyResumeHint(pending)
|
||||
: `Run live-poll.mjs, handle ${pending.type} ${pending.id}, then acknowledge with live-poll.mjs --reply ${pending.id} done.`
|
||||
: snapshot.phase === 'carbonize_required'
|
||||
? `Finish carbonize cleanup${snapshot.sourceFile ? ` in ${snapshot.sourceFile}` : ''}, then run live-complete.mjs --id ${snapshot.id}.`
|
||||
: snapshot.phase === 'accept_requested'
|
||||
? `Run live-complete.mjs --id ${snapshot.id} after verifying the accepted variant is written.`
|
||||
: `Inspect ${snapshot.id}; no pending agent event is currently queued.`;
|
||||
const render = renderSummary(snapshot);
|
||||
// A failed render outranks the generic pending-event hint: the agent needs to
|
||||
// know the user is staring at an error card, not at variants. A leased manual
|
||||
// Apply still outranks both, because abandoning that lease loses user edits.
|
||||
const mountAction = render.renderState === 'failed' ? mountFailureAction(snapshot) : null;
|
||||
const nextAction = pending?.type === 'manual_edit_apply'
|
||||
? manualApplyResumeHint(pending)
|
||||
: mountAction || (pending
|
||||
? `Run live-poll.mjs, handle ${pending.type} ${pending.id}, then acknowledge with live-poll.mjs --reply ${pending.id} done.`
|
||||
: snapshot.phase === 'carbonize_required'
|
||||
? `Finish carbonize cleanup${snapshot.sourceFile ? ` in ${snapshot.sourceFile}` : ''}, then run live-complete.mjs --id ${snapshot.id}.`
|
||||
: snapshot.phase === 'accept_requested'
|
||||
? `Run live-complete.mjs --id ${snapshot.id} after verifying the accepted variant is written.`
|
||||
: `Inspect ${snapshot.id}; no pending agent event is currently queued.`);
|
||||
|
||||
console.log(JSON.stringify({ active: true, snapshot, pendingEvent: pending, nextAction }, null, 2));
|
||||
console.log(JSON.stringify({ active: true, snapshot, pendingEvent: pending, render, nextAction }, null, 2));
|
||||
}
|
||||
|
||||
const _running = process.argv[1];
|
||||
if (_running?.endsWith('live-resume.mjs') || _running?.endsWith('live-resume.mjs/')) {
|
||||
enterLiveRoot();
|
||||
resumeCli();
|
||||
}
|
||||
|
||||
@@ -33,7 +33,10 @@ import { runGenerationPreflight } from './live/generation-preflight.mjs';
|
||||
import { validateEvent } from './live/event-validation.mjs';
|
||||
import { selectAvailablePendingEvent } from './live/poll-lanes.mjs';
|
||||
import { createManualEditRoutes } from './live/manual-edit-routes.mjs';
|
||||
import { LIVE_COMMANDS } from './live/vocabulary.mjs';
|
||||
import {
|
||||
LIVE_COMMANDS,
|
||||
VARIANT_PROGRESS_CHECKPOINT_REASONS as VARIANT_PROGRESS_CHECKPOINT_REASON_LIST,
|
||||
} from './live/vocabulary.mjs';
|
||||
import {
|
||||
getDesignSidecarPath,
|
||||
getLiveDir,
|
||||
@@ -51,24 +54,53 @@ import {
|
||||
} from './live/manual-apply.mjs';
|
||||
import {
|
||||
applyDeferredSvelteComponentAccepts,
|
||||
bumpSvelteComponentPreviewRevision,
|
||||
compileCheckVariants,
|
||||
removeAllSvelteComponentSessions,
|
||||
sweepInactiveSvelteComponentSessions,
|
||||
} from './live/svelte-component.mjs';
|
||||
import { enterLiveRoot } from './live/roots.mjs';
|
||||
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
||||
// PRODUCT.md / DESIGN.md live wherever context.mjs resolves. The generated
|
||||
// DESIGN sidecar is project-local at .impeccable/design.json, with legacy
|
||||
// DESIGN.json fallback for existing projects.
|
||||
const PROJECT_CONTEXT = loadContext(process.cwd());
|
||||
const CONTEXT_DIR = PROJECT_CONTEXT.contextDir;
|
||||
const DESIGN_MD_PATH = PROJECT_CONTEXT.designPath
|
||||
? path.resolve(process.cwd(), PROJECT_CONTEXT.designPath)
|
||||
: null;
|
||||
// Anchor the whole process on the live roots manifest before anything derives
|
||||
// a path from cwd. A server started from the wrong directory re-roots itself
|
||||
// onto the appRoot the boot decided on instead of minting a second project.
|
||||
const LIVE_ROOTS = enterLiveRoot(process.cwd());
|
||||
|
||||
// PRODUCT.md / DESIGN.md context, resolved lazily and per request so a server
|
||||
// that outlives an `impeccable document` run (or a context file created after
|
||||
// boot) reports current truth instead of a boot-time snapshot. The roots
|
||||
// manifest wins when the ambient resolution misses (nested app inheriting
|
||||
// repo-level context files).
|
||||
function resolveProjectContext() {
|
||||
const ctx = loadContext(process.cwd());
|
||||
const designPath = ctx.designPath
|
||||
? path.resolve(process.cwd(), ctx.designPath)
|
||||
: (LIVE_ROOTS?.designPath && fs.existsSync(LIVE_ROOTS.designPath) ? LIVE_ROOTS.designPath : null);
|
||||
const hasProduct = ctx.hasProduct
|
||||
|| !!(LIVE_ROOTS?.productPath && fs.existsSync(LIVE_ROOTS.productPath));
|
||||
return {
|
||||
...ctx,
|
||||
hasProduct,
|
||||
hasDesign: !!designPath,
|
||||
resolvedDesignPath: designPath,
|
||||
contextDir: ctx.contextDir || LIVE_ROOTS?.contextRoot || process.cwd(),
|
||||
designContextDir: ctx.designContextDir
|
||||
|| (designPath ? path.dirname(designPath) : null),
|
||||
};
|
||||
}
|
||||
const DEFAULT_POLL_TIMEOUT = 600_000; // 10 min — agent re-polls on timeout anyway
|
||||
const SSE_HEARTBEAT_INTERVAL = 30_000; // keepalive ping every 30s
|
||||
|
||||
// The browser events allowed to mint a NEW session journal. `generate` starts
|
||||
// a variant session at Go; `steer` mints its own request id. Every other
|
||||
// id-carrying event must land on an existing session (see the unknown_session
|
||||
// gate in the /events handler).
|
||||
const SESSION_CREATING_EVENT_TYPES = new Set(['generate', 'steer']);
|
||||
// The browser checkpoints for several unrelated reasons (see checkpointPayload
|
||||
// in live-browser.js). Only these two report that variant availability changed,
|
||||
// and only they may drive variant_progress / the *_reviewable phases.
|
||||
const VARIANT_PROGRESS_CHECKPOINT_REASONS = new Set(['variants_progress', 'variants_ready']);
|
||||
const VARIANT_PROGRESS_CHECKPOINT_REASONS = new Set(VARIANT_PROGRESS_CHECKPOINT_REASON_LIST);
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Port detection
|
||||
@@ -150,7 +182,16 @@ function chatAgentLikelyActive() {
|
||||
const MAX_ANNOTATION_BYTES = 10 * 1024 * 1024;
|
||||
|
||||
function enqueueEvent(event) {
|
||||
if (!event || (event.id && state.pendingEvents.some((entry) => entry.event?.id === event.id && entry.event?.type === event.type))) return;
|
||||
if (!event) return;
|
||||
// Dedupe by (session, type), except mount failures, which are per-variant:
|
||||
// variant 2 failing must not be swallowed because variant 1's failure is
|
||||
// still queued.
|
||||
const duplicate = event.id && state.pendingEvents.some((entry) => (
|
||||
entry.event?.id === event.id
|
||||
&& entry.event?.type === event.type
|
||||
&& (event.type !== 'variant_mount_failed' || entry.event?.variant === event.variant)
|
||||
));
|
||||
if (duplicate) return;
|
||||
state.pendingEvents.push({ event, leaseUntil: 0, seq: state.nextEventSeq++ });
|
||||
flushPendingPolls();
|
||||
}
|
||||
@@ -445,6 +486,11 @@ function summarizeActiveSessionForClient(snapshot = {}) {
|
||||
generationCompletedAt: snapshot.generationCompletedAt ?? null,
|
||||
generationCanceled: snapshot.generationCanceled === true,
|
||||
cancelReason: snapshot.cancelReason ?? null,
|
||||
// Render truth, so a browser with no localStorage can rehydrate to the
|
||||
// same comparison the server already knows about.
|
||||
mountedVariants: Array.isArray(snapshot.mountedVariants) ? snapshot.mountedVariants : [],
|
||||
mountFailures: Array.isArray(snapshot.mountFailures) ? snapshot.mountFailures : [],
|
||||
renderState: snapshot.renderState ?? null,
|
||||
};
|
||||
}
|
||||
|
||||
@@ -618,7 +664,7 @@ function hasProjectContext() {
|
||||
// PRODUCT.md carries brand voice / anti-references — that's what determines
|
||||
// whether variants are brand-aware. DESIGN.md (visual tokens) is a separate
|
||||
// concern, surfaced by the design panel's own empty state.
|
||||
return !!PROJECT_CONTEXT.hasProduct;
|
||||
return !!resolveProjectContext().hasProduct;
|
||||
}
|
||||
|
||||
function statOrNull(filePath) {
|
||||
@@ -690,6 +736,7 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
|
||||
port: state.port,
|
||||
vocabulary: LIVE_COMMANDS,
|
||||
commandPrefix: IMPECCABLE_COMMAND_PREFIX,
|
||||
appRoot: process.cwd(),
|
||||
parts,
|
||||
});
|
||||
res.writeHead(200, {
|
||||
@@ -827,8 +874,9 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
|
||||
const token = url.searchParams.get('token');
|
||||
if (token !== state.token) { res.writeHead(401); res.end('Unauthorized'); return; }
|
||||
|
||||
const mdPath = DESIGN_MD_PATH;
|
||||
const jsonPath = resolveDesignSidecarPath(process.cwd(), PROJECT_CONTEXT.designContextDir || CONTEXT_DIR) || getDesignSidecarPath(process.cwd());
|
||||
const projectContext = resolveProjectContext();
|
||||
const mdPath = projectContext.resolvedDesignPath;
|
||||
const jsonPath = resolveDesignSidecarPath(process.cwd(), projectContext.designContextDir || projectContext.contextDir) || getDesignSidecarPath(process.cwd());
|
||||
const mdStat = statOrNull(mdPath);
|
||||
const jsonStat = statOrNull(jsonPath);
|
||||
|
||||
@@ -979,6 +1027,20 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
|
||||
res.end(JSON.stringify({ ok: true }));
|
||||
return;
|
||||
}
|
||||
// Only the events that START a session may create its journal.
|
||||
// Everything else (checkpoints, mount acks, accept/discard) must
|
||||
// reference a session THIS store already knows: appendEvent creates a
|
||||
// journal for any id it is handed, so without this gate a browser
|
||||
// resuming another project's session from per-origin storage (two
|
||||
// apps sharing a localhost port) materializes a ghost session here
|
||||
// that keeps reattaching after every discard.
|
||||
if (msg.id && state.sessionStore
|
||||
&& !SESSION_CREATING_EVENT_TYPES.has(msg.type)
|
||||
&& !state.sessionStore.has(msg.id)) {
|
||||
res.writeHead(404, { 'Content-Type': 'application/json' });
|
||||
res.end(JSON.stringify({ error: 'unknown_session', id: msg.id }));
|
||||
return;
|
||||
}
|
||||
const missedCompletion = detectMissedGenerationCompletion(msg);
|
||||
if (state.sessionStore && msg.id) {
|
||||
try {
|
||||
@@ -997,7 +1059,25 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
|
||||
if (msg.type === 'exit') {
|
||||
cleanupSvelteComponentSessionsBeforeExit();
|
||||
}
|
||||
if (msg.type !== 'checkpoint') {
|
||||
// An ORPHANED discard is the browser reporting that the session's
|
||||
// wrapper no longer exists in source (edited or regenerated away).
|
||||
// There is no cleanup for an agent to perform, and asking one to run
|
||||
// the normal discard flow would just fail against the missing
|
||||
// scaffolding, so the server terminalizes the session itself and the
|
||||
// event stays out of the poll queue.
|
||||
const orphanedDiscard = msg.type === 'discard' && msg.orphaned === true;
|
||||
if (orphanedDiscard && state.sessionStore && msg.id) {
|
||||
try {
|
||||
state.sessionStore.appendEvent({ type: 'discarded', id: msg.id, orphaned: true });
|
||||
} catch { /* the discard_requested phase already left the resumable set */ }
|
||||
}
|
||||
// `variant_mounted` is the happy path: it is journaled above so the
|
||||
// snapshot carries render truth, but there is nothing for the agent to
|
||||
// do about it, so it stays out of the poll queue and off the SSE bus.
|
||||
// `variant_mount_failed` is the opposite: the agent published something
|
||||
// the browser could not render, and only the agent can fix it, so it
|
||||
// goes to the queue as a first-class event.
|
||||
if (msg.type !== 'checkpoint' && msg.type !== 'variant_mounted' && !orphanedDiscard) {
|
||||
enqueueEvent(msg);
|
||||
}
|
||||
res.writeHead(200, { 'Content-Type': 'application/json' });
|
||||
@@ -1099,7 +1179,8 @@ function sessionFileMetadataFromPollReply(file) {
|
||||
const base = { file: normalized };
|
||||
const metadataFile = normalized;
|
||||
if (!metadataFile.endsWith('/manifest.json') && metadataFile !== 'manifest.json') return base;
|
||||
if (!metadataFile.includes('node_modules/.impeccable-live/')
|
||||
if (!metadataFile.includes('.impeccable/live/previews/')
|
||||
&& !metadataFile.includes('node_modules/.impeccable-live/')
|
||||
&& !metadataFile.includes('src/lib/impeccable/')
|
||||
&& !metadataFile.includes('/.impeccable-live/')) return base;
|
||||
|
||||
@@ -1139,7 +1220,14 @@ function inferSourceEventType(msg = {}, pendingEvents = state.pendingEvents) {
|
||||
// `agent_done` can be the automatic acknowledgement for a carbonize Accept.
|
||||
// New pollers send sourceEventType explicitly; default to generate only for
|
||||
// older callers so a late worker cannot acknowledge a queued Accept.
|
||||
if (msg.type === 'agent_done' || msg.type === 'done') return 'generate';
|
||||
if (msg.type === 'agent_done' || msg.type === 'done') {
|
||||
// A `done` reply to a mount failure is the republish that unblocks the
|
||||
// browser. Without this the ack would look for a `generate` that was
|
||||
// already retired, the mount-failure event would stay queued, and the next
|
||||
// poll would hand the same failure back to the agent forever.
|
||||
if (!pendingTypes.has('generate') && pendingTypes.has('variant_mount_failed')) return 'variant_mount_failed';
|
||||
return 'generate';
|
||||
}
|
||||
// `error` is reference/live.md's documented failure reply, and parseReplyArgs
|
||||
// never sets sourceEventType on it (the poller is a fresh process that cannot
|
||||
// know what it leased). Returning undefined here makes acknowledgePendingEvent
|
||||
@@ -1264,6 +1352,30 @@ function handlePollPost(req, res) {
|
||||
return;
|
||||
}
|
||||
const replyFileMeta = sessionFileMetadataFromPollReply(msg.file);
|
||||
// A publish (done reply carrying a component manifest) snapshots the
|
||||
// variant files into a fresh revision dir before the browser is told:
|
||||
// the import path changes every publish, so no transform cache can pin a
|
||||
// stale compile of a republished module (node_modules is unwatched).
|
||||
// Broken variants are bounced HERE, before the browser imports anything:
|
||||
// a compile error that reaches the page is a red overlay in the user's
|
||||
// face; bounced at publish it is a private fix with file and line.
|
||||
if (replyFileMeta.previewMode === 'svelte-component'
|
||||
&& msg.id
|
||||
&& (msg.type === 'done' || !msg.type)) {
|
||||
let compileCheck = { ok: true, failures: [] };
|
||||
try { compileCheck = compileCheckVariants(msg.id, process.cwd()); } catch { /* best-effort */ }
|
||||
if (!compileCheck.ok) {
|
||||
res.writeHead(422, { 'Content-Type': 'application/json' });
|
||||
res.end(JSON.stringify({
|
||||
error: 'variant_compile_failed',
|
||||
id: msg.id,
|
||||
failures: compileCheck.failures,
|
||||
_instructions: 'The publish was NOT delivered: the listed variant file(s) do not compile, so the browser never saw them. Fix each failure at the given file and line (the most common cause is a second top-level <style> element; Svelte allows exactly one, so merge all rules into the existing block), then send the same --reply done again.',
|
||||
}));
|
||||
return;
|
||||
}
|
||||
try { bumpSvelteComponentPreviewRevision(msg.id, process.cwd()); } catch { /* best-effort */ }
|
||||
}
|
||||
if (state.sessionStore && msg.id && !skipJournalReply) {
|
||||
try {
|
||||
const eventType = msg.type === 'steer_done'
|
||||
@@ -1335,6 +1447,51 @@ function cleanupSvelteComponentSessionsBeforeExit() {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* A previous run that died without its shutdown hook leaves preview component
|
||||
* dirs behind. Drop the ones whose session the store no longer considers
|
||||
* active; anything still active is mid-generation and must survive a restart.
|
||||
*/
|
||||
function sweepOrphanSvelteComponentSessionsOnStartup() {
|
||||
try {
|
||||
const activeIds = (state.sessionStore?.listActiveSessions() || [])
|
||||
.map((snapshot) => snapshot?.id)
|
||||
.filter(Boolean);
|
||||
const result = sweepInactiveSvelteComponentSessions(activeIds, process.cwd());
|
||||
if (result.removed.length > 0 || result.removedRoot) {
|
||||
console.log('[impeccable] swept orphaned Svelte component sessions:', JSON.stringify(result));
|
||||
}
|
||||
} catch (err) {
|
||||
console.warn('[impeccable] Svelte component session sweep failed:', err.message);
|
||||
}
|
||||
}
|
||||
|
||||
// Accept receipts are a short-lived idempotency record for a single accept.
|
||||
// Nothing reads one after the session that wrote it is gone, so they only need
|
||||
// to outlive a crash-and-retry window.
|
||||
const ACCEPT_RECEIPT_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000;
|
||||
|
||||
function sweepStaleAcceptReceiptsOnStartup() {
|
||||
try {
|
||||
const dir = path.join(getLiveDir(process.cwd()), 'accept-receipts');
|
||||
if (!fs.existsSync(dir)) return;
|
||||
const cutoff = Date.now() - ACCEPT_RECEIPT_MAX_AGE_MS;
|
||||
let removed = 0;
|
||||
for (const name of fs.readdirSync(dir)) {
|
||||
if (!name.endsWith('.json') && !name.endsWith('.tmp')) continue;
|
||||
const file = path.join(dir, name);
|
||||
try {
|
||||
if (fs.statSync(file).mtimeMs >= cutoff) continue;
|
||||
fs.rmSync(file, { force: true });
|
||||
removed++;
|
||||
} catch { /* non-fatal */ }
|
||||
}
|
||||
if (removed > 0) console.log(`[impeccable] removed ${removed} accept receipt(s) older than 14 days`);
|
||||
} catch (err) {
|
||||
console.warn('[impeccable] accept receipt retention sweep failed:', err.message);
|
||||
}
|
||||
}
|
||||
|
||||
function applyLegacyDeferredAcceptsOnStartup() {
|
||||
try {
|
||||
const result = applyDeferredSvelteComponentAccepts(process.cwd());
|
||||
@@ -1474,6 +1631,8 @@ manualApply.rollbackTransaction({
|
||||
reason: 'manual_edit_server_start_recovered_abandoned_transaction',
|
||||
});
|
||||
applyLegacyDeferredAcceptsOnStartup();
|
||||
sweepOrphanSvelteComponentSessionsOnStartup();
|
||||
sweepStaleAcceptReceiptsOnStartup();
|
||||
restorePendingEventsFromStore();
|
||||
manualApply.pruneStaleEvidence();
|
||||
const portArg = args.find(a => a.startsWith('--port='));
|
||||
|
||||
@@ -5,7 +5,8 @@
|
||||
|
||||
import { createLiveSessionStore } from './live/session-store.mjs';
|
||||
import { readLiveServerInfo } from './lib/impeccable-paths.mjs';
|
||||
import { manualApplyResumeHint } from './live-resume.mjs';
|
||||
import { manualApplyResumeHint, mountFailureAction, renderSummary } from './live-resume.mjs';
|
||||
import { enterLiveRoot } from './live/roots.mjs';
|
||||
|
||||
function readServerInfo() {
|
||||
return readLiveServerInfo(process.cwd())?.info || null;
|
||||
@@ -28,6 +29,8 @@ export async function statusCli() {
|
||||
const store = createLiveSessionStore({ cwd: process.cwd() });
|
||||
const activeSessions = store.listActiveSessions();
|
||||
const manualApply = findPendingManualApply(server, activeSessions);
|
||||
const sessions = server?.activeSessions || activeSessions;
|
||||
const renderFailure = sessions.find((session) => session?.renderState === 'failed') || null;
|
||||
const payload = {
|
||||
liveServer: server ? {
|
||||
status: server.status,
|
||||
@@ -36,14 +39,16 @@ export async function statusCli() {
|
||||
agentPolling: server.agentPolling,
|
||||
pendingEvents: server.pendingEvents,
|
||||
} : null,
|
||||
activeSessions: server?.activeSessions || activeSessions,
|
||||
recoveryHint: recoveryHint({ server, manualApply }),
|
||||
activeSessions: sessions,
|
||||
render: sessions.map((session) => ({ id: session?.id ?? null, ...renderSummary(session) })),
|
||||
recoveryHint: recoveryHint({ server, manualApply, renderFailure }),
|
||||
};
|
||||
console.log(JSON.stringify(payload, null, 2));
|
||||
}
|
||||
|
||||
function recoveryHint({ server, manualApply }) {
|
||||
function recoveryHint({ server, manualApply, renderFailure }) {
|
||||
if (manualApply) return manualApplyResumeHint(manualApply);
|
||||
if (renderFailure) return mountFailureAction(renderFailure);
|
||||
if (server) {
|
||||
return 'Run live-poll.mjs to continue pending work, or live-complete.mjs --id <session> after manual cleanup.';
|
||||
}
|
||||
@@ -61,5 +66,6 @@ function findPendingManualApply(server, activeSessions) {
|
||||
|
||||
const _running = process.argv[1];
|
||||
if (_running?.endsWith('live-status.mjs') || _running?.endsWith('live-status.mjs/')) {
|
||||
enterLiveRoot();
|
||||
statusCli();
|
||||
}
|
||||
|
||||
@@ -17,11 +17,13 @@ import { isGeneratedFile } from './lib/is-generated.mjs';
|
||||
import { resolveLiveTemplateExtensions } from './lib/template-extensions.mjs';
|
||||
import { readBuffer as readManualEditsBuffer } from './live/manual-edits-buffer.mjs';
|
||||
import { findSourceFile } from './live/source-search.mjs';
|
||||
import { resolveSourceTraits } from './live/frameworks/index.mjs';
|
||||
import {
|
||||
buildSvelteComponentCssAuthoring,
|
||||
scaffoldSvelteComponentSession,
|
||||
shouldUseSvelteComponentInjection,
|
||||
} from './live/svelte-component.mjs';
|
||||
import { enterLiveRoot } from './live/roots.mjs';
|
||||
|
||||
export async function wrapCli() {
|
||||
const args = process.argv.slice(2);
|
||||
@@ -293,8 +295,10 @@ The agent should insert variant HTML at insertLine.`);
|
||||
.join('\n');
|
||||
const originalIndented = reindentOriginal(' ');
|
||||
const relTargetFile = path.relative(process.cwd(), targetFile).split(path.sep).join('/');
|
||||
const useSvelteComponent = shouldUseSvelteComponentInjection(targetFile);
|
||||
const useFrameworkComponent = useSvelteComponent;
|
||||
// The registry says which files get component preview; the svelte-component
|
||||
// module keeps the env escape hatch that turns it off.
|
||||
const useSvelteComponent = resolveSourceTraits(targetFile).preview === 'component'
|
||||
&& shouldUseSvelteComponentInjection(targetFile);
|
||||
|
||||
// Wrapper attributes differ by syntax. HTML allows plain string attrs;
|
||||
// JSX requires object-literal style and parses string attrs as HTML (which
|
||||
@@ -343,12 +347,18 @@ The agent should insert variant HTML at insertLine.`);
|
||||
let svelteSession = null;
|
||||
let deferredWrapper = null;
|
||||
|
||||
let sveltePreviewFallback = null;
|
||||
if (useSvelteComponent) {
|
||||
// Svelte/SvelteKit resets component-local state on markup HMR updates.
|
||||
// Keep generation source-neutral: agents write real variant components
|
||||
// under the generated componentDir, the browser mounts them into the live
|
||||
// DOM, and live-accept.mjs inlines the accepted variant back into the route.
|
||||
svelteSession = scaffoldSvelteComponentSession({
|
||||
//
|
||||
// The scaffold is AST-based and refuses markup a detached preview cannot
|
||||
// support (component tags, bind:/use:, await blocks, bound nested each).
|
||||
// Refusal falls back to the plain source-preview wrapper below: an
|
||||
// HMR-resetting but CORRECT preview beats a detached wrong one.
|
||||
const scaffolded = scaffoldSvelteComponentSession({
|
||||
id,
|
||||
count,
|
||||
sourceFile: relTargetFile,
|
||||
@@ -357,10 +367,18 @@ The agent should insert variant HTML at insertLine.`);
|
||||
originalLines,
|
||||
cwd: process.cwd(),
|
||||
});
|
||||
outputFile = path.resolve(process.cwd(), svelteSession.manifestFile);
|
||||
outputStartLine = 1;
|
||||
outputEndLine = 1;
|
||||
insertLine = 1;
|
||||
if (scaffolded && scaffolded.fallback === 'source-preview') {
|
||||
sveltePreviewFallback = scaffolded.reason || 'unsupported markup';
|
||||
} else {
|
||||
svelteSession = scaffolded;
|
||||
outputFile = path.resolve(process.cwd(), svelteSession.manifestFile);
|
||||
outputStartLine = 1;
|
||||
outputEndLine = 1;
|
||||
insertLine = 1;
|
||||
}
|
||||
}
|
||||
if (svelteSession) {
|
||||
// component preview: outputs already set above
|
||||
} else if (deferSourceWrite) {
|
||||
// Deferred source write: compute the scaffold text but leave source
|
||||
// untouched. The agent replaces the picked element's source range with
|
||||
@@ -396,15 +414,19 @@ The agent should insert variant HTML at insertLine.`);
|
||||
|
||||
const outputRelFile = path.relative(process.cwd(), outputFile).split(path.sep).join('/');
|
||||
|
||||
const svelteComponentAuthoring = useSvelteComponent ? buildSvelteComponentCssAuthoring(count) : null;
|
||||
const componentPreviewActive = !!svelteSession;
|
||||
const svelteComponentAuthoring = componentPreviewActive ? buildSvelteComponentCssAuthoring(count) : null;
|
||||
const componentSession = svelteSession;
|
||||
const componentPreviewMode = useSvelteComponent ? 'svelte-component' : undefined;
|
||||
const componentPreviewMode = componentPreviewActive ? 'svelte-component' : undefined;
|
||||
const previewMode = componentPreviewMode;
|
||||
|
||||
console.log(JSON.stringify({
|
||||
file: outputRelFile,
|
||||
sourceFile: useFrameworkComponent ? relTargetFile : undefined,
|
||||
sourceFile: componentPreviewActive ? relTargetFile : undefined,
|
||||
previewMode,
|
||||
previewFallback: sveltePreviewFallback
|
||||
? { from: 'svelte-component', reason: sveltePreviewFallback }
|
||||
: undefined,
|
||||
// Deferred source write: the wrapper is NOT yet in source. The agent
|
||||
// replaces [replaceStartLine, replaceEndLine] with `wrapperBlock` (variants
|
||||
// spliced at the "insert below this line" marker) in one atomic edit.
|
||||
@@ -414,8 +436,9 @@ The agent should insert variant HTML at insertLine.`);
|
||||
replaceEndLine: deferredWrapper ? deferredWrapper.replaceEndLine : undefined,
|
||||
componentDir: componentSession?.componentDir,
|
||||
propContract: componentSession?.propContract,
|
||||
sourceStartLine: useFrameworkComponent ? startLine + 1 : undefined,
|
||||
sourceEndLine: useFrameworkComponent ? endLine + 1 : undefined,
|
||||
componentStubMarkup: componentSession?.stubMarkup,
|
||||
sourceStartLine: componentPreviewActive ? startLine + 1 : undefined,
|
||||
sourceEndLine: componentPreviewActive ? endLine + 1 : undefined,
|
||||
startLine: outputStartLine, // 1-indexed for the agent
|
||||
// wrapperLines is an array but one element (the original-content slot)
|
||||
// is a `\n`-joined multi-line string, so the actual file-row count is
|
||||
@@ -426,8 +449,8 @@ The agent should insert variant HTML at insertLine.`);
|
||||
insertLine, // 1-indexed: where variants go
|
||||
commentSyntax: commentSyntax,
|
||||
styleMode: componentPreviewMode || styleMode.mode,
|
||||
styleTag: useFrameworkComponent ? null : styleMode.styleTag,
|
||||
cssSelectorPrefixExamples: useFrameworkComponent ? [] : buildCssSelectorPrefixExamples(styleMode.mode, count),
|
||||
styleTag: componentPreviewActive ? null : styleMode.styleTag,
|
||||
cssSelectorPrefixExamples: componentPreviewActive ? [] : buildCssSelectorPrefixExamples(styleMode.mode, count),
|
||||
cssAuthoring: svelteComponentAuthoring || buildCssAuthoring(styleMode, count),
|
||||
originalLineCount: originalLines.length,
|
||||
}));
|
||||
@@ -630,27 +653,22 @@ function attrEscapeDouble(str) {
|
||||
.replace(/>/g, '>');
|
||||
}
|
||||
|
||||
/**
|
||||
* Comment syntax, style mode, and preview strategy all come from the framework
|
||||
* registry, keyed on the target file's extension: `.jsx`/`.tsx` author JSX
|
||||
* comments, `.astro` needs global-prefixed preview CSS because Astro scopes
|
||||
* component styles away from the generated wrappers, `.svelte` gets component
|
||||
* preview. See live/frameworks/index.mjs for why extension and not project.
|
||||
*/
|
||||
function detectCommentSyntax(filePath) {
|
||||
const ext = path.extname(filePath).toLowerCase();
|
||||
if (ext === '.jsx' || ext === '.tsx') {
|
||||
return { open: '{/*', close: '*/}' };
|
||||
}
|
||||
// HTML, Vue, Svelte, Astro all use HTML comments
|
||||
return { open: '<!--', close: '-->' };
|
||||
return resolveSourceTraits(filePath).commentSyntax === 'jsx'
|
||||
? { open: '{/*', close: '*/}' }
|
||||
: { open: '<!--', close: '-->' };
|
||||
}
|
||||
|
||||
function detectStyleMode(filePath) {
|
||||
const ext = path.extname(filePath).toLowerCase();
|
||||
if (ext === '.astro') {
|
||||
return {
|
||||
mode: 'astro-global-prefixed',
|
||||
styleTag: '<style is:inline data-impeccable-css="SESSION_ID">',
|
||||
};
|
||||
}
|
||||
return {
|
||||
mode: 'scoped',
|
||||
styleTag: '<style data-impeccable-css="SESSION_ID">',
|
||||
};
|
||||
const traits = resolveSourceTraits(filePath);
|
||||
return { mode: traits.styleMode, styleTag: traits.styleTag };
|
||||
}
|
||||
|
||||
function buildCssSelectorPrefixExamples(styleMode, count) {
|
||||
@@ -890,6 +908,7 @@ function findClosingLine(lines, start) {
|
||||
// Auto-execute when run directly (node live-wrap.mjs ...)
|
||||
const _running = process.argv[1];
|
||||
if (_running?.endsWith('live-wrap.mjs') || _running?.endsWith('live-wrap.mjs/')) {
|
||||
enterLiveRoot();
|
||||
wrapCli();
|
||||
}
|
||||
|
||||
|
||||
@@ -21,10 +21,13 @@ import { execSync } from 'node:child_process';
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { loadContext, resolveTargetSelection } from './context.mjs';
|
||||
import { resolveTargetSelection } from './context.mjs';
|
||||
import { resolveFiles } from './live-inject.mjs';
|
||||
import { readLiveServerInfo } from './lib/impeccable-paths.mjs';
|
||||
import { resolveSurfaceBrief } from './lib/surface-briefs.mjs';
|
||||
import { resolveLiveTarget } from './live-target.mjs';
|
||||
import { bootInstructions } from './live/instructions.mjs';
|
||||
import { resolveRoots, writeRootsManifest } from './live/roots.mjs';
|
||||
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
||||
|
||||
@@ -60,6 +63,8 @@ The agent should then:
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
// Legacy workspace-monorepo selection first: it carries richer candidate
|
||||
// metadata (context inheritance status) than the roots scan.
|
||||
const targetSelection = resolveTargetSelection(liveTarget.originalCwd, liveTarget.targetOptions);
|
||||
if (targetSelection) {
|
||||
console.log(JSON.stringify({
|
||||
@@ -71,11 +76,31 @@ The agent should then:
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
const ctx = loadContext(liveTarget.originalCwd, liveTarget.targetOptions);
|
||||
const activeCwd = ctx.projectRoot;
|
||||
const rootsResult = resolveRoots({
|
||||
cwd: liveTarget.originalCwd,
|
||||
targetPath: liveTarget.absoluteTargetPath,
|
||||
});
|
||||
if (rootsResult.selection) {
|
||||
console.log(JSON.stringify({
|
||||
ok: false,
|
||||
error: 'target_selection_required',
|
||||
targetCandidates: rootsResult.selection.candidates,
|
||||
hint: 'Several apps with a dev-server config exist. Ask the user which one to use, then rerun with --target <path into that app>.',
|
||||
}, null, 2));
|
||||
process.exit(0);
|
||||
}
|
||||
const roots = rootsResult.manifest;
|
||||
const activeCwd = roots.appRoot;
|
||||
const outputTargetPath = liveTarget.targetPath || null;
|
||||
|
||||
const missingContext = missingLiveContext(ctx);
|
||||
// Gate on readable CONTENT, not path existence, so an empty or unreadable
|
||||
// PRODUCT.md routes to init instead of passing the gate and then reporting
|
||||
// hasProduct: false in the same payload.
|
||||
const product = safeRead(roots.productPath);
|
||||
const design = safeRead(roots.designPath);
|
||||
const missingContext = [];
|
||||
if (!product) missingContext.push('PRODUCT.md');
|
||||
if (!design) missingContext.push('DESIGN.md');
|
||||
if (missingContext.length > 0) {
|
||||
console.log(JSON.stringify({
|
||||
ok: false,
|
||||
@@ -83,14 +108,18 @@ The agent should then:
|
||||
missing: missingContext,
|
||||
nextCommand: missingContext.includes('PRODUCT.md') ? 'init' : 'document',
|
||||
targetPath: outputTargetPath,
|
||||
projectRoot: ctx.projectRoot,
|
||||
repoRoot: ctx.repoRoot,
|
||||
productPath: ctx.productPath,
|
||||
designPath: ctx.designPath,
|
||||
projectRoot: roots.appRoot,
|
||||
repoRoot: roots.repoRoot,
|
||||
productPath: relOrNull(liveTarget.originalCwd, roots.productPath),
|
||||
designPath: relOrNull(liveTarget.originalCwd, roots.designPath),
|
||||
}, null, 2));
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
// Persist the decision before anything else spawns, so every helper the
|
||||
// agent runs later (from any cwd inside the repo) lands on the same roots.
|
||||
writeRootsManifest(roots);
|
||||
|
||||
// 1. Check config (fail fast if missing — no point starting anything else)
|
||||
const checkOut = runScript('live-inject.mjs', ['--check'], { cwd: activeCwd });
|
||||
const checkResult = safeParse(checkOut);
|
||||
@@ -98,8 +127,8 @@ The agent should then:
|
||||
console.log(JSON.stringify({
|
||||
...(checkResult || { ok: false, error: 'check_failed', raw: checkOut }),
|
||||
targetPath: outputTargetPath,
|
||||
projectRoot: ctx.projectRoot,
|
||||
repoRoot: ctx.repoRoot,
|
||||
projectRoot: roots.appRoot,
|
||||
repoRoot: roots.repoRoot,
|
||||
}));
|
||||
process.exit(0);
|
||||
}
|
||||
@@ -134,7 +163,28 @@ The agent should then:
|
||||
const resolvedFiles = resolveFiles(activeCwd, checkResult.config);
|
||||
const drift = scanForDrift(activeCwd, resolvedFiles, checkResult.config);
|
||||
|
||||
// 5. Emit everything the agent needs
|
||||
// 5. Emit everything the agent needs. The surface brief rides along so the
|
||||
// agent does not spend three more tool calls (and a --help miss) on
|
||||
// surface-brief.mjs before the first poll.
|
||||
let surfaceBrief = null;
|
||||
let surfaceBriefPath = null;
|
||||
try {
|
||||
// Briefs live under .impeccable/surfaces, which in a nested-app repo sits
|
||||
// at the CONTEXT or repo root, not the app root; context.mjs already finds
|
||||
// them there, and live must not report "no brief" for the same project.
|
||||
const briefRoots = [roots.appRoot, roots.contextRoot, roots.repoRoot]
|
||||
.filter(Boolean)
|
||||
.filter((dir, i, arr) => arr.findIndex((other) => path.resolve(other) === path.resolve(dir)) === i);
|
||||
for (const briefRoot of briefRoots) {
|
||||
const resolvedBrief = resolveSurfaceBrief(briefRoot, liveTarget.absoluteTargetPath || null);
|
||||
if (!resolvedBrief?.brief) continue;
|
||||
surfaceBrief = resolvedBrief.brief.text ?? safeRead(resolvedBrief.brief.path);
|
||||
surfaceBriefPath = resolvedBrief.brief.path
|
||||
? path.relative(liveTarget.originalCwd, resolvedBrief.brief.path)
|
||||
: null;
|
||||
break;
|
||||
}
|
||||
} catch { /* briefs are optional context */ }
|
||||
console.log(JSON.stringify({
|
||||
ok: true,
|
||||
serverPort: serverInfo.port,
|
||||
@@ -143,22 +193,29 @@ The agent should then:
|
||||
liveConfigPath: checkResult.path,
|
||||
configDrift: drift,
|
||||
targetPath: outputTargetPath,
|
||||
projectRoot: ctx.projectRoot,
|
||||
repoRoot: ctx.repoRoot,
|
||||
hasProduct: ctx.hasProduct,
|
||||
product: ctx.product,
|
||||
productPath: ctx.productPath,
|
||||
hasDesign: ctx.hasDesign,
|
||||
design: ctx.design,
|
||||
designPath: ctx.designPath,
|
||||
projectRoot: roots.appRoot,
|
||||
repoRoot: roots.repoRoot,
|
||||
roots,
|
||||
hasProduct: !!product,
|
||||
product,
|
||||
productPath: relOrNull(liveTarget.originalCwd, roots.productPath),
|
||||
hasDesign: !!design,
|
||||
design,
|
||||
designPath: relOrNull(liveTarget.originalCwd, roots.designPath),
|
||||
hasSurfaceBrief: !!surfaceBrief,
|
||||
surfaceBrief,
|
||||
surfaceBriefPath,
|
||||
_instructions: bootInstructions({ scriptsPath: __dirname }),
|
||||
}, null, 2));
|
||||
}
|
||||
|
||||
function missingLiveContext(ctx) {
|
||||
const missing = [];
|
||||
if (!ctx.hasProduct) missing.push('PRODUCT.md');
|
||||
if (!ctx.hasDesign) missing.push('DESIGN.md');
|
||||
return missing;
|
||||
function safeRead(p) {
|
||||
if (!p) return null;
|
||||
try { return fs.readFileSync(p, 'utf-8'); } catch { return null; }
|
||||
}
|
||||
|
||||
function relOrNull(base, p) {
|
||||
return p ? path.relative(base, p) : null;
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
@@ -0,0 +1,617 @@
|
||||
/**
|
||||
* Accept-time CSS reconciliation for live mode.
|
||||
*
|
||||
* The old accept path appended the chosen variant's whole <style> body in
|
||||
* front of the component's existing rules, which preserved every superseded
|
||||
* declaration (the "old divider borders survive the accept" bug) and left
|
||||
* dead parameter branches in source. This module makes acceptance a merge:
|
||||
*
|
||||
* reconcileCss replace rules whose selectors match, append new ones
|
||||
* bakeParamValues collapse --p-* vars and [data-p-*] branches to the
|
||||
* user's chosen values, driven by the declared param
|
||||
* kinds from params.json (not regex sniffing)
|
||||
* pruneUnusedSelectors use the framework compiler's own unused-selector
|
||||
* warnings to delete rules the accepted markup no longer
|
||||
* references
|
||||
*
|
||||
* The parser is hand-rolled on purpose: skill scripts run standalone inside
|
||||
* user projects and cannot rely on this repo's node_modules. It is a small
|
||||
* recursive block parser (comment- and string-aware), not a spec-complete
|
||||
* CSS parser; everything it emits round-trips byte-for-byte through raw
|
||||
* slices except the rules deliberately changed.
|
||||
*/
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Parsing
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Parse a stylesheet into a flat tree.
|
||||
* Node shapes:
|
||||
* { type: 'rule', prelude, body, start, end, preludeStart }
|
||||
* { type: 'at', name, prelude, children|body, start, end } (children when
|
||||
* the block contains rules: media/supports/layer/container/scope)
|
||||
* { type: 'comment', text, start, end }
|
||||
*/
|
||||
export function parseStylesheet(css, offset = 0) {
|
||||
const text = String(css || '');
|
||||
const nodes = [];
|
||||
let i = 0;
|
||||
|
||||
const skipWs = () => { while (i < text.length && /\s/.test(text[i])) i++; };
|
||||
|
||||
while (i < text.length) {
|
||||
skipWs();
|
||||
if (i >= text.length) break;
|
||||
|
||||
if (text[i] === '/' && text[i + 1] === '*') {
|
||||
const start = i;
|
||||
const close = text.indexOf('*/', i + 2);
|
||||
i = close === -1 ? text.length : close + 2;
|
||||
nodes.push({ type: 'comment', text: text.slice(start, i), start: offset + start, end: offset + i });
|
||||
continue;
|
||||
}
|
||||
|
||||
const preludeStart = i;
|
||||
const boundary = scanToBlockOrStatementEnd(text, i);
|
||||
if (boundary.kind === 'none') break; // trailing garbage / declarations at top level
|
||||
if (boundary.kind === 'statement') {
|
||||
// Block-less at-statement (@import, @charset, @layer names;). Emitted
|
||||
// as its own node so the FOLLOWING rule still indexes for
|
||||
// reconciliation instead of being folded into this prelude.
|
||||
const raw = text.slice(preludeStart, boundary.index + 1).trim();
|
||||
if (raw) {
|
||||
nodes.push({
|
||||
type: 'at',
|
||||
name: (raw.match(/^@([A-Za-z-]+)/) || [])[1] || '',
|
||||
prelude: raw.replace(/;$/, ''),
|
||||
statement: true,
|
||||
start: offset + preludeStart,
|
||||
end: offset + boundary.index + 1,
|
||||
});
|
||||
}
|
||||
i = boundary.index + 1;
|
||||
continue;
|
||||
}
|
||||
const braceIdx = boundary.index;
|
||||
const prelude = text.slice(preludeStart, braceIdx).trim();
|
||||
const bodyStart = braceIdx + 1;
|
||||
const bodyEnd = scanBlockEnd(text, bodyStart);
|
||||
const body = text.slice(bodyStart, bodyEnd);
|
||||
const nodeEnd = Math.min(text.length, bodyEnd + 1);
|
||||
|
||||
if (prelude.startsWith('@')) {
|
||||
const name = (prelude.match(/^@([A-Za-z-]+)/) || [])[1] || '';
|
||||
if (['media', 'supports', 'layer', 'container', 'scope'].includes(name)) {
|
||||
nodes.push({
|
||||
type: 'at',
|
||||
name,
|
||||
prelude,
|
||||
children: parseStylesheet(body, offset + bodyStart),
|
||||
start: offset + preludeStart,
|
||||
end: offset + nodeEnd,
|
||||
});
|
||||
} else {
|
||||
nodes.push({
|
||||
type: 'at',
|
||||
name,
|
||||
prelude,
|
||||
body,
|
||||
start: offset + preludeStart,
|
||||
end: offset + nodeEnd,
|
||||
});
|
||||
}
|
||||
} else if (prelude) {
|
||||
nodes.push({
|
||||
type: 'rule',
|
||||
prelude,
|
||||
body,
|
||||
start: offset + preludeStart,
|
||||
end: offset + nodeEnd,
|
||||
preludeStart: offset + preludeStart,
|
||||
});
|
||||
}
|
||||
i = nodeEnd;
|
||||
}
|
||||
return nodes;
|
||||
}
|
||||
|
||||
/**
|
||||
* Scan for the next structural boundary: the `{` opening a block, or the `;`
|
||||
* ending a block-less at-statement, whichever comes first (string- and
|
||||
* comment-aware). Returns { kind: 'block' | 'statement' | 'none', index }.
|
||||
*/
|
||||
function scanToBlockOrStatementEnd(text, from) {
|
||||
let i = from;
|
||||
let quote = null;
|
||||
while (i < text.length) {
|
||||
const ch = text[i];
|
||||
if (quote) {
|
||||
if (ch === '\\') i++;
|
||||
else if (ch === quote) quote = null;
|
||||
} else if (ch === '"' || ch === "'") {
|
||||
quote = ch;
|
||||
} else if (ch === '/' && text[i + 1] === '*') {
|
||||
const close = text.indexOf('*/', i + 2);
|
||||
i = close === -1 ? text.length : close + 1;
|
||||
} else if (ch === '{') {
|
||||
return { kind: 'block', index: i };
|
||||
} else if (ch === ';') {
|
||||
return { kind: 'statement', index: i };
|
||||
}
|
||||
i++;
|
||||
}
|
||||
return { kind: 'none', index: -1 };
|
||||
}
|
||||
|
||||
function scanBlockEnd(text, from) {
|
||||
let i = from;
|
||||
let depth = 1;
|
||||
let quote = null;
|
||||
while (i < text.length) {
|
||||
const ch = text[i];
|
||||
if (quote) {
|
||||
if (ch === '\\') i++;
|
||||
else if (ch === quote) quote = null;
|
||||
} else if (ch === '"' || ch === "'") {
|
||||
quote = ch;
|
||||
} else if (ch === '/' && text[i + 1] === '*') {
|
||||
const close = text.indexOf('*/', i + 2);
|
||||
i = close === -1 ? text.length : close + 1;
|
||||
} else if (ch === '{') {
|
||||
depth++;
|
||||
} else if (ch === '}') {
|
||||
depth--;
|
||||
if (depth === 0) return i;
|
||||
}
|
||||
i++;
|
||||
}
|
||||
return text.length;
|
||||
}
|
||||
|
||||
export function serializeNodes(nodes, indent = '') {
|
||||
const out = [];
|
||||
for (const node of nodes) {
|
||||
if (node.type === 'comment') {
|
||||
out.push(indent + node.text);
|
||||
} else if (node.type === 'rule') {
|
||||
out.push(`${indent}${node.prelude} {${formatBody(node.body, indent)}}`);
|
||||
} else if (node.type === 'at' && node.children) {
|
||||
out.push(`${indent}${node.prelude} {`);
|
||||
out.push(serializeNodes(node.children, indent + ' '));
|
||||
out.push(`${indent}}`);
|
||||
} else if (node.type === 'at' && node.statement) {
|
||||
out.push(`${indent}${node.prelude};`);
|
||||
} else if (node.type === 'at') {
|
||||
out.push(`${indent}${node.prelude} {${formatBody(node.body, indent)}}`);
|
||||
}
|
||||
}
|
||||
return out.join('\n');
|
||||
}
|
||||
|
||||
function formatBody(body, indent) {
|
||||
const trimmed = String(body || '').trim();
|
||||
if (!trimmed) return ' ';
|
||||
const lines = trimmed.split('\n').map((l) => l.trim()).filter(Boolean);
|
||||
if (lines.length === 1 && lines[0].length < 60) return ` ${lines[0]} `;
|
||||
return '\n' + lines.map((l) => `${indent} ${l}`).join('\n') + `\n${indent}`;
|
||||
}
|
||||
|
||||
export function normalizeSelector(prelude) {
|
||||
return String(prelude || '')
|
||||
.replace(/\s+/g, ' ')
|
||||
.replace(/\s*([>+~,])\s*/g, '$1')
|
||||
.trim();
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Reconciliation
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Merge variant CSS into existing CSS. Rules whose (at-context, normalized
|
||||
* selector) match an existing rule REPLACE that rule's body in place; new
|
||||
* rules append at the end under their at-context. Returns { css, replaced,
|
||||
* appended }.
|
||||
*/
|
||||
export function reconcileCss(existingCss, variantCss) {
|
||||
const existing = parseStylesheet(existingCss);
|
||||
const incoming = parseStylesheet(variantCss);
|
||||
let replaced = 0;
|
||||
let appended = 0;
|
||||
|
||||
const mergeLevel = (existingNodes, incomingNodes) => {
|
||||
const index = new Map();
|
||||
for (const node of existingNodes) {
|
||||
if (node.type === 'rule') index.set(normalizeSelector(node.prelude), node);
|
||||
}
|
||||
const atIndex = new Map();
|
||||
for (const node of existingNodes) {
|
||||
if (node.type === 'at' && node.children) atIndex.set(normalizeSelector(node.prelude), node);
|
||||
}
|
||||
// Baking can leave several incoming rules with the same selector (e.g. a
|
||||
// base rule plus a stripped param branch). The first one REPLACES the
|
||||
// existing body; later same-selector rules extend it, never clobber it.
|
||||
const touched = new Set();
|
||||
for (const node of incomingNodes) {
|
||||
if (node.type === 'comment') continue;
|
||||
if (node.type === 'rule') {
|
||||
const key = normalizeSelector(node.prelude);
|
||||
const match = index.get(key);
|
||||
if (match) {
|
||||
if (touched.has(key)) {
|
||||
match.body = `${match.body.trim()}\n${node.body.trim()}`;
|
||||
} else if (match.body.trim() !== node.body.trim()) {
|
||||
match.body = node.body;
|
||||
replaced++;
|
||||
}
|
||||
touched.add(key);
|
||||
} else {
|
||||
// New base rules go BEFORE the existing top-level media blocks:
|
||||
// appended after them, an equal-specificity base rule wins the
|
||||
// cascade over the stylesheet's earlier responsive overrides and
|
||||
// silently weakens the mobile styles for any still-shared class.
|
||||
const appendedNode = { ...node };
|
||||
const firstAt = existingNodes.findIndex((n) => n.type === 'at' && n.children);
|
||||
if (firstAt === -1) existingNodes.push(appendedNode);
|
||||
else existingNodes.splice(firstAt, 0, appendedNode);
|
||||
index.set(key, appendedNode);
|
||||
touched.add(key);
|
||||
appended++;
|
||||
}
|
||||
} else if (node.type === 'at' && node.children) {
|
||||
const key = normalizeSelector(node.prelude);
|
||||
const match = atIndex.get(key);
|
||||
if (match) {
|
||||
mergeLevel(match.children, node.children);
|
||||
} else {
|
||||
existingNodes.push({ ...node });
|
||||
atIndex.set(key, existingNodes[existingNodes.length - 1]);
|
||||
appended++;
|
||||
}
|
||||
} else {
|
||||
existingNodes.push({ ...node });
|
||||
appended++;
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
mergeLevel(existing, incoming);
|
||||
return { css: serializeNodes(existing), replaced, appended };
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Parameter baking
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Replace every `var(--p-<id>, fallback)` / `var(--p-<id>)` occurrence with a
|
||||
* literal value. Paren-aware: fallbacks containing calc()/nested vars are
|
||||
* handled, unlike the old `[^)]+` regex.
|
||||
*/
|
||||
export function substituteParamVar(css, id, value) {
|
||||
const text = String(css || '');
|
||||
const needle = `var(--p-${id}`;
|
||||
let out = '';
|
||||
let i = 0;
|
||||
while (i < text.length) {
|
||||
const idx = text.indexOf(needle, i);
|
||||
if (idx === -1) { out += text.slice(i); break; }
|
||||
const after = idx + needle.length;
|
||||
// Must be end of the var name: `)` or `,`.
|
||||
if (after < text.length && text[after] !== ')' && text[after] !== ',') {
|
||||
out += text.slice(i, after);
|
||||
i = after;
|
||||
continue;
|
||||
}
|
||||
let j = after;
|
||||
let depth = 1; // we are inside var(
|
||||
while (j < text.length && depth > 0) {
|
||||
if (text[j] === '(') depth++;
|
||||
else if (text[j] === ')') depth--;
|
||||
j++;
|
||||
}
|
||||
out += text.slice(i, idx) + String(value);
|
||||
i = j;
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function normalizeToggleForVar(value) {
|
||||
return value === true || value === 'true' || value === 1 || value === '1' || value === 'on' ? '1' : '0';
|
||||
}
|
||||
|
||||
function isToggleOn(value) {
|
||||
return normalizeToggleForVar(value) === '1';
|
||||
}
|
||||
|
||||
/**
|
||||
* Strip `[data-p-<id>="value"]` / `[data-p-<id>]` attribute selectors from a
|
||||
* selector, deciding survival by the chosen value:
|
||||
* returns null when the selector targets a non-chosen branch (drop it),
|
||||
* otherwise the selector with the attribute test removed and any emptied
|
||||
* :global() wrappers cleaned up.
|
||||
*/
|
||||
export function stripParamSelector(selector, id, kind, chosenValue) {
|
||||
const attrRe = new RegExp(`\\[data-p-${escapeRegExp(id)}(?:=(["'])(.*?)\\1)?\\]`, 'g');
|
||||
let drop = false;
|
||||
let out = String(selector).replace(attrRe, (_m, _q, expected) => {
|
||||
if (kind === 'steps') {
|
||||
if (expected == null || String(expected) === String(chosenValue)) return '';
|
||||
drop = true;
|
||||
return '';
|
||||
}
|
||||
// toggle: the runtime sets data-p-<id>="on" when on and removes the
|
||||
// attribute when off. A branch survives baking only if it actually
|
||||
// matched at preview time with the chosen state: the presence form and
|
||||
// the literal "on" form match while on; every other valued form
|
||||
// (["false"], ["0"], ...) never matched and is dead regardless of state.
|
||||
if (expected != null && expected !== 'on') {
|
||||
drop = true;
|
||||
return '';
|
||||
}
|
||||
if (!isToggleOn(chosenValue)) {
|
||||
drop = true;
|
||||
return '';
|
||||
}
|
||||
return '';
|
||||
});
|
||||
if (drop) return null;
|
||||
out = out
|
||||
.replace(/:global\(\s*\)/g, '')
|
||||
.replace(/\s+/g, ' ')
|
||||
.replace(/^\s*[>+~]\s*/, '')
|
||||
.trim();
|
||||
return out || null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Bake chosen parameter values into CSS. `params` is the declared parameter
|
||||
* list for the accepted variant (from params.json); `values` maps id ->
|
||||
* chosen value (falling back to each param's declared default).
|
||||
*/
|
||||
export function bakeParamValues(css, params = [], values = {}) {
|
||||
let nodes = parseStylesheet(css);
|
||||
|
||||
const chosen = new Map();
|
||||
for (const param of params || []) {
|
||||
if (!param || !param.id) continue;
|
||||
const has = values && Object.prototype.hasOwnProperty.call(values, param.id);
|
||||
chosen.set(param.id, { kind: param.kind, value: has ? values[param.id] : param.default });
|
||||
}
|
||||
// Values sent for params that were never declared still bake as ranges,
|
||||
// so an out-of-sync manifest degrades to the old behavior, not to silence.
|
||||
for (const [id, value] of Object.entries(values || {})) {
|
||||
if (!chosen.has(id)) chosen.set(id, { kind: 'range', value });
|
||||
}
|
||||
|
||||
const bakeBody = (body) => {
|
||||
let out = String(body || '');
|
||||
for (const [id, { kind, value }] of chosen) {
|
||||
const literal = kind === 'toggle' ? normalizeToggleForVar(value) : String(value);
|
||||
out = substituteParamVar(out, id, literal);
|
||||
}
|
||||
// Strip the readiness sentinel as a DECLARATION, not a line: a one-line
|
||||
// rule carrying the sentinel plus real declarations must keep the rest.
|
||||
return out
|
||||
.replace(/(^|;)\s*--impeccable-variant-ready\s*:[^;{}]*/g, '$1')
|
||||
.replace(/;\s*;/g, ';')
|
||||
.replace(/^\s*;\s*/, '');
|
||||
};
|
||||
|
||||
const transform = (list) => {
|
||||
const result = [];
|
||||
for (const node of list) {
|
||||
if (node.type === 'at' && node.children) {
|
||||
const children = transform(node.children);
|
||||
if (children.length > 0) result.push({ ...node, children });
|
||||
continue;
|
||||
}
|
||||
if (node.type !== 'rule') {
|
||||
if (node.type === 'at') result.push({ ...node, body: bakeBody(node.body) });
|
||||
else result.push(node);
|
||||
continue;
|
||||
}
|
||||
const selectors = splitSelectorList(node.prelude);
|
||||
const kept = [];
|
||||
for (let selector of selectors) {
|
||||
let alive = true;
|
||||
for (const [id, { kind, value }] of chosen) {
|
||||
if (kind !== 'steps' && kind !== 'toggle') continue;
|
||||
if (!selector.includes(`data-p-${id}`)) continue;
|
||||
const next = stripParamSelector(selector, id, kind, value);
|
||||
if (next == null) { alive = false; break; }
|
||||
selector = next;
|
||||
}
|
||||
if (alive && selector.trim()) kept.push(selector.trim());
|
||||
}
|
||||
if (kept.length === 0) continue;
|
||||
const body = bakeBody(node.body);
|
||||
if (!body.trim()) continue;
|
||||
result.push({ ...node, prelude: kept.join(', '), body });
|
||||
}
|
||||
return result;
|
||||
};
|
||||
|
||||
nodes = transform(nodes);
|
||||
return serializeNodes(nodes);
|
||||
}
|
||||
|
||||
export function splitSelectorList(prelude) {
|
||||
const selectors = [];
|
||||
let start = 0;
|
||||
let bracket = 0;
|
||||
let paren = 0;
|
||||
let quote = null;
|
||||
const text = String(prelude || '');
|
||||
for (let i = 0; i < text.length; i++) {
|
||||
const ch = text[i];
|
||||
if (quote) {
|
||||
if (ch === '\\') i++;
|
||||
else if (ch === quote) quote = null;
|
||||
continue;
|
||||
}
|
||||
if (ch === '"' || ch === "'") quote = ch;
|
||||
else if (ch === '[') bracket++;
|
||||
else if (ch === ']') bracket = Math.max(0, bracket - 1);
|
||||
else if (ch === '(') paren++;
|
||||
else if (ch === ')') paren = Math.max(0, paren - 1);
|
||||
else if (ch === ',' && bracket === 0 && paren === 0) {
|
||||
selectors.push(text.slice(start, i));
|
||||
start = i + 1;
|
||||
}
|
||||
}
|
||||
selectors.push(text.slice(start));
|
||||
return selectors.map((s) => s.trim()).filter(Boolean);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Compiler-driven pruning
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Remove selectors the framework compiler reports as unused from a full
|
||||
* component source. `compileFn` is the app's svelte compile; warnings with
|
||||
* code `css_unused_selector` carry character offsets into the source.
|
||||
* `skipSelectors` protects selectors that were already unused before the
|
||||
* accept: pre-existing dead rules are the user's code, not live-mode debris.
|
||||
* Returns { source, removed } where removed lists the pruned selector texts.
|
||||
*/
|
||||
export function collectUnusedSelectors(componentSource, compileFn) {
|
||||
try {
|
||||
const { warnings } = compileFn(String(componentSource || ''), { generate: false });
|
||||
return new Set((warnings || [])
|
||||
.filter((w) => w.code === 'css_unused_selector'
|
||||
&& Number.isInteger(w.start?.character)
|
||||
&& Number.isInteger(w.end?.character))
|
||||
.map((w) => String(componentSource).slice(w.start.character, w.end.character).trim()));
|
||||
} catch {
|
||||
return new Set();
|
||||
}
|
||||
}
|
||||
|
||||
export function pruneUnusedSelectors(componentSource, compileFn, { skipSelectors } = {}) {
|
||||
let source = String(componentSource || '');
|
||||
const removed = [];
|
||||
const skip = skipSelectors instanceof Set ? skipSelectors : new Set(skipSelectors || []);
|
||||
for (let pass = 0; pass < 3; pass++) {
|
||||
let warnings;
|
||||
try {
|
||||
({ warnings } = compileFn(source, { generate: false }));
|
||||
} catch {
|
||||
return { source, removed }; // never let pruning break an accept
|
||||
}
|
||||
const unused = (warnings || [])
|
||||
.filter((w) => w.code === 'css_unused_selector'
|
||||
&& Number.isInteger(w.start?.character)
|
||||
&& Number.isInteger(w.end?.character))
|
||||
.filter((w) => !skip.has(source.slice(w.start.character, w.end.character).trim()))
|
||||
.sort((a, b) => b.start.character - a.start.character);
|
||||
if (unused.length === 0) break;
|
||||
|
||||
let next = source;
|
||||
for (const warning of unused) {
|
||||
const result = removeSelectorAt(next, warning.start.character, warning.end.character);
|
||||
if (result.changed) {
|
||||
removed.push(result.selector);
|
||||
next = result.source;
|
||||
}
|
||||
}
|
||||
if (next === source) break;
|
||||
source = next;
|
||||
}
|
||||
return { source, removed };
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove the selector at [start, end) from its rule. When it is the rule's
|
||||
* only selector, remove the whole rule (prelude through closing brace).
|
||||
*/
|
||||
function removeSelectorAt(source, start, end) {
|
||||
const selector = source.slice(start, end);
|
||||
|
||||
// Find the rule boundaries around the selector.
|
||||
const braceIdx = source.indexOf('{', end);
|
||||
if (braceIdx === -1) return { changed: false, selector, source };
|
||||
const bodyEnd = scanBlockEnd(source, braceIdx + 1);
|
||||
|
||||
// Prelude spans backward from the brace to the previous } ; { or the end
|
||||
// of the <style> open tag. A bare `>` is NOT a boundary: it is the child
|
||||
// combinator, and cutting there truncates a selector list like
|
||||
// `.a > .b, .c` mid-prelude. Only a `>` that closes a `<style ...>` tag
|
||||
// bounds the walk.
|
||||
let preludeStart = start;
|
||||
for (let i = start - 1; i >= 0; i--) {
|
||||
const ch = source[i];
|
||||
if (ch === '}' || ch === '{' || ch === ';') { preludeStart = i + 1; break; }
|
||||
if (ch === '>') {
|
||||
const styleOpen = source.lastIndexOf('<style', i);
|
||||
if (styleOpen !== -1 && source.indexOf('>', styleOpen) === i) { preludeStart = i + 1; break; }
|
||||
continue; // child combinator inside the prelude
|
||||
}
|
||||
if (i === 0) preludeStart = 0;
|
||||
}
|
||||
const prelude = source.slice(preludeStart, braceIdx);
|
||||
const selectors = splitSelectorList(prelude);
|
||||
const target = selector.trim();
|
||||
const kept = selectors.filter((s) => s !== target);
|
||||
|
||||
if (kept.length === selectors.length) {
|
||||
// Offsets did not line up with a full selector in the list; be safe.
|
||||
return { changed: false, selector, source };
|
||||
}
|
||||
|
||||
if (kept.length === 0) {
|
||||
// Remove the entire rule including trailing newline.
|
||||
let ruleEnd = Math.min(source.length, bodyEnd + 1);
|
||||
while (ruleEnd < source.length && source[ruleEnd] === '\n') ruleEnd++;
|
||||
let ruleStart = preludeStart;
|
||||
while (ruleStart > 0 && (source[ruleStart - 1] === ' ' || source[ruleStart - 1] === '\t')) ruleStart--;
|
||||
return { changed: true, selector: target, source: source.slice(0, ruleStart) + source.slice(ruleEnd) };
|
||||
}
|
||||
|
||||
const indent = (prelude.match(/^\s*/) || [''])[0];
|
||||
return {
|
||||
changed: true,
|
||||
selector: target,
|
||||
source: source.slice(0, preludeStart) + indent + kept.join(', ') + ' ' + source.slice(braceIdx, source.length),
|
||||
};
|
||||
}
|
||||
|
||||
function escapeRegExp(value) {
|
||||
return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
||||
}
|
||||
|
||||
/**
|
||||
* Collect every normalized selector in a CSS text, including inside nested
|
||||
* at-blocks. Used by the accept postcondition: a selector present before the
|
||||
* accept may only disappear if the compiler reported it unused; anything
|
||||
* else means the parser or reconciler damaged the user's file, and the write
|
||||
* must be refused rather than silently committed.
|
||||
*/
|
||||
export function collectAllSelectors(css, out = new Set()) {
|
||||
for (const node of parseStylesheet(css)) {
|
||||
if (node.type === 'rule') {
|
||||
for (const selector of splitSelectorList(node.prelude)) out.add(normalizeSelector(selector));
|
||||
} else if (node.type === 'at' && node.children) {
|
||||
for (const child of node.children) {
|
||||
if (child.type === 'rule') {
|
||||
for (const selector of splitSelectorList(child.prelude)) out.add(normalizeSelector(selector));
|
||||
} else if (child.type === 'at' && child.children) {
|
||||
collectSelectorsFromNodes(child.children, out);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function collectSelectorsFromNodes(nodes, out) {
|
||||
for (const node of nodes) {
|
||||
if (node.type === 'rule') {
|
||||
for (const selector of splitSelectorList(node.prelude)) out.add(normalizeSelector(selector));
|
||||
} else if (node.type === 'at' && node.children) {
|
||||
collectSelectorsFromNodes(node.children, out);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,60 @@
|
||||
/**
|
||||
* Postcondition scanner for accepted/carbonized source. The carbonize
|
||||
* contract used to exist only as prose in reference/live.md; nothing checked
|
||||
* that an accept actually left the file clean, so dead param branches,
|
||||
* preview attributes, and marker comments accumulated across sessions. This
|
||||
* scanner is the mechanical form of that contract. live-complete refuses to
|
||||
* mark a carbonize session complete while the file is dirty, and the
|
||||
* mechanical Svelte accept runs it on its own output as a self-check.
|
||||
*/
|
||||
|
||||
// Param patterns are anchored to the exact shapes live mode writes
|
||||
// (attribute-with-value / selector forms, var() references), not bare
|
||||
// substrings, so user tokens that merely share the prefix cannot trip the
|
||||
// completion gate.
|
||||
const FORBIDDEN = [
|
||||
{ marker: 'impeccable-variants-start', why: 'variant wrapper comment left in source' },
|
||||
{ marker: 'impeccable-variants-end', why: 'variant wrapper comment left in source' },
|
||||
{ marker: 'impeccable-carbonize-start', why: 'carbonize block not rewritten into permanent form' },
|
||||
{ marker: 'impeccable-carbonize-end', why: 'carbonize block not rewritten into permanent form' },
|
||||
{ marker: 'impeccable-param-values', why: 'param-values comment not baked and removed' },
|
||||
{ marker: 'data-impeccable-', why: 'live-mode plumbing attribute left on markup' },
|
||||
{ marker: /\bdata-p-[A-Za-z0-9_-]+\s*(?:=|\])/, label: 'data-p-*', why: 'preview parameter attribute left on markup' },
|
||||
{ marker: /var\(\s*--p-[A-Za-z0-9_-]+\s*[,)]/, label: 'var(--p-*)', why: 'preview parameter variable not baked to a literal' },
|
||||
{ marker: '--impeccable-variant-ready', why: 'preview readiness sentinel left in CSS' },
|
||||
];
|
||||
|
||||
/**
|
||||
* Scan file text for live-mode leftovers. Returns { clean, findings } where
|
||||
* each finding is { marker, line, excerpt, why }.
|
||||
*/
|
||||
export function verifyAcceptedSource(text) {
|
||||
const findings = [];
|
||||
const lines = String(text || '').split('\n');
|
||||
for (let i = 0; i < lines.length; i++) {
|
||||
const line = lines[i];
|
||||
for (const { marker, label, why } of FORBIDDEN) {
|
||||
const hit = marker instanceof RegExp ? marker.test(line) : line.includes(marker);
|
||||
if (hit) {
|
||||
findings.push({
|
||||
marker: label || String(marker),
|
||||
line: i + 1,
|
||||
excerpt: line.trim().slice(0, 120),
|
||||
why,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
return { clean: findings.length === 0, findings };
|
||||
}
|
||||
|
||||
/** Convenience wrapper for CLI callers: read + scan, tolerating a missing file. */
|
||||
export function verifyAcceptedFile(fs, filePath) {
|
||||
let text;
|
||||
try {
|
||||
text = fs.readFileSync(filePath, 'utf-8');
|
||||
} catch {
|
||||
return { clean: true, findings: [], missing: true };
|
||||
}
|
||||
return { ...verifyAcceptedSource(text), missing: false };
|
||||
}
|
||||
@@ -32,10 +32,15 @@ export function readLiveBrowserScriptParts(parts, readFile = (filePath) => fs.re
|
||||
}));
|
||||
}
|
||||
|
||||
export function assembleLiveBrowserScript({ token, port, vocabulary, commandPrefix = '/', parts }) {
|
||||
export function assembleLiveBrowserScript({ token, port, vocabulary, commandPrefix = '/', appRoot = null, parts }) {
|
||||
const prelude =
|
||||
`window.__IMPECCABLE_TOKEN__ = '${token}';\n` +
|
||||
`window.__IMPECCABLE_PORT__ = ${port};\n` +
|
||||
// Project identity for browser-side session storage. localStorage is
|
||||
// keyed by ORIGIN, and two projects routinely share a localhost port
|
||||
// across time; saved sessions carry this value so a resume can tell a
|
||||
// foreign project's leftovers from its own.
|
||||
`window.__IMPECCABLE_APP_ROOT__ = ${JSON.stringify(appRoot)};\n` +
|
||||
`window.__IMPECCABLE_COMMAND_PREFIX__ = ${JSON.stringify(commandPrefix)};\n` +
|
||||
// Canonical command vocabulary (values + labels + icons). live-browser.js
|
||||
// builds its action picker from this instead of an inline copy.
|
||||
|
||||
@@ -5,17 +5,26 @@
|
||||
|
||||
import { canCreateInsert } from './insert-ui.mjs';
|
||||
|
||||
// The accepted visual action values come from the canonical vocabulary so the
|
||||
// validator, the picker UI, and the marketing demo never drift. Imported (not
|
||||
// just re-exported) so it is also in scope for the validators below.
|
||||
import { VISUAL_ACTIONS } from './vocabulary.mjs';
|
||||
export { VISUAL_ACTIONS };
|
||||
// The accepted protocol values come from the canonical vocabulary so the
|
||||
// validator, the store, the server, and the picker UI never drift. Imported
|
||||
// (not just re-exported) so they are also in scope for the validators below.
|
||||
import { AGENT_PHASES, CLIENT_EVENT_TYPES, VISUAL_ACTIONS } from './vocabulary.mjs';
|
||||
export { AGENT_PHASES, CLIENT_EVENT_TYPES, VISUAL_ACTIONS };
|
||||
|
||||
const AGENT_PHASE_SET = new Set(AGENT_PHASES);
|
||||
|
||||
const ID_PATTERN = /^[0-9a-f]{8}$/;
|
||||
const VARIANT_ID_PATTERN = /^[0-9]{1,3}$/;
|
||||
const INSERT_POSITIONS = new Set(['before', 'after']);
|
||||
const FORBIDDEN_MANUAL_EDIT_TEXT_CHARS = ['<', '{', '}', '`'];
|
||||
|
||||
// Mount acknowledgements carry a module URL and a raw exception message from
|
||||
// the page. Both are attacker-adjacent (any script on the page can POST them
|
||||
// with the token it can already read), so they are length-capped before they
|
||||
// reach the journal.
|
||||
export const MOUNT_URL_MAX_LENGTH = 2000;
|
||||
export const MOUNT_ERROR_MAX_LENGTH = 1000;
|
||||
|
||||
function isValidId(v) { return typeof v === 'string' && ID_PATTERN.test(v); }
|
||||
function isValidVariantId(v) { return typeof v === 'string' && VARIANT_ID_PATTERN.test(v); }
|
||||
|
||||
@@ -92,6 +101,36 @@ function validateManualEditEvent(msg, label) {
|
||||
return null;
|
||||
}
|
||||
|
||||
function isValidMountVariant(value) {
|
||||
return Number.isInteger(value) && value >= 1 && value <= 999;
|
||||
}
|
||||
|
||||
/**
|
||||
* Mount acknowledgements are the browser's answer to "did the thing you
|
||||
* published actually render". They are validated strictly because the render
|
||||
* truth in the session snapshot is built from them: a malformed ack that slid
|
||||
* through would report a variant as mounted that never was.
|
||||
*/
|
||||
function validateMountAck(msg) {
|
||||
if (!isValidId(msg.id)) return 'variant_mounted: missing or malformed id';
|
||||
if (!isValidMountVariant(msg.variant)) return 'variant_mounted: variant must be an integer 1-999';
|
||||
if (msg.url !== undefined) {
|
||||
if (typeof msg.url !== 'string') return 'variant_mounted: url must be string';
|
||||
if (msg.url.length > MOUNT_URL_MAX_LENGTH) return 'variant_mounted: url too long';
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function validateMountFailure(msg) {
|
||||
if (!isValidId(msg.id)) return 'variant_mount_failed: missing or malformed id';
|
||||
if (!isValidMountVariant(msg.variant)) return 'variant_mount_failed: variant must be an integer 1-999';
|
||||
if (typeof msg.url !== 'string' || !msg.url.trim()) return 'variant_mount_failed: url required';
|
||||
if (msg.url.length > MOUNT_URL_MAX_LENGTH) return 'variant_mount_failed: url too long';
|
||||
if (typeof msg.error !== 'string' || !msg.error.trim()) return 'variant_mount_failed: error required';
|
||||
if (msg.error.length > MOUNT_ERROR_MAX_LENGTH) return 'variant_mount_failed: error too long';
|
||||
return null;
|
||||
}
|
||||
|
||||
export function validateEvent(msg) {
|
||||
if (!msg || typeof msg !== 'object' || !msg.type) return 'Missing or invalid message';
|
||||
switch (msg.type) {
|
||||
@@ -120,13 +159,21 @@ export function validateEvent(msg) {
|
||||
return null;
|
||||
case 'agent_phase':
|
||||
if (!isValidId(msg.id)) return 'agent_phase: missing or malformed id';
|
||||
if (typeof msg.phase !== 'string' || !/^[a-z][a-z0-9_]{1,63}$/.test(msg.phase)) {
|
||||
return 'agent_phase: missing or malformed phase';
|
||||
if (typeof msg.phase !== 'string' || !msg.phase) return 'agent_phase: missing phase';
|
||||
// The enum, not a shape pattern. A phase the browser cannot rank is a
|
||||
// phase the progress bar cannot show, so accepting an arbitrary
|
||||
// lowercase word only defers the failure to the UI.
|
||||
if (!AGENT_PHASE_SET.has(msg.phase)) {
|
||||
return 'agent_phase: unknown phase ' + msg.phase + ' (expected one of ' + AGENT_PHASES.join(', ') + ')';
|
||||
}
|
||||
if (msg.durationMs !== undefined && (!Number.isFinite(msg.durationMs) || msg.durationMs < 0)) {
|
||||
return 'agent_phase: durationMs must be a non-negative number';
|
||||
}
|
||||
return null;
|
||||
case 'variant_mounted':
|
||||
return validateMountAck(msg);
|
||||
case 'variant_mount_failed':
|
||||
return validateMountFailure(msg);
|
||||
case 'exit':
|
||||
return null;
|
||||
case 'prefetch':
|
||||
|
||||
@@ -0,0 +1,47 @@
|
||||
/**
|
||||
* Astro registry entry.
|
||||
*
|
||||
* Astro takes the generic tag strategy, with two Astro-specific values that
|
||||
* used to sit as inline `endsWith('.astro')` branches in live-inject.mjs and
|
||||
* live-wrap.mjs:
|
||||
*
|
||||
* injectScriptAttrs Astro processes <script> tags by default and rewrites
|
||||
* src to its own bundled URL; is:inline opts out.
|
||||
* styleMode Astro scopes component styles, which strips preview CSS
|
||||
* off the generated variant wrappers, so preview rules are
|
||||
* authored global and prefixed instead of @scope'd.
|
||||
*/
|
||||
|
||||
import { findConfigFile, hasAnyDependency, literalConfigFiles } from './detect-utils.mjs';
|
||||
|
||||
const ASTRO_CONFIG_RE = /^astro\.config\.(?:js|mjs|cjs|ts|mts|cts)$/;
|
||||
|
||||
export function detectAstroProject(cwd = process.cwd(), config = null) {
|
||||
const configFile = findConfigFile(cwd, ASTRO_CONFIG_RE);
|
||||
if (configFile) return { configFile, via: 'config' };
|
||||
if (hasAnyDependency(cwd, ['astro'])) return { configFile: null, via: 'package' };
|
||||
// A tree of .astro entry templates with no astro.config still belongs to
|
||||
// Astro; the configured injection target names it.
|
||||
const entry = literalConfigFiles(cwd, config).find((rel) => rel.endsWith('.astro'));
|
||||
if (entry) return { configFile: null, via: 'config-files', entry };
|
||||
return null;
|
||||
}
|
||||
|
||||
export const astro = {
|
||||
name: 'astro',
|
||||
|
||||
detect(cwd, config) {
|
||||
return detectAstroProject(cwd, config);
|
||||
},
|
||||
|
||||
inject: { kind: 'tag' },
|
||||
|
||||
source: {
|
||||
extensions: ['.astro'],
|
||||
preview: 'source',
|
||||
styleMode: 'astro-global-prefixed',
|
||||
styleTag: '<style is:inline data-impeccable-css="SESSION_ID">',
|
||||
commentSyntax: 'html',
|
||||
injectScriptAttrs: 'is:inline ',
|
||||
},
|
||||
};
|
||||
@@ -0,0 +1,73 @@
|
||||
/**
|
||||
* Small read-only probes the framework entries share.
|
||||
*
|
||||
* Every helper here is cheap and failure-tolerant: detection runs on every
|
||||
* inject, against project trees that may be half-installed, so a missing or
|
||||
* malformed file means "not this framework", never a throw.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
/** Merged dependency names from package.json, or an empty object. */
|
||||
export function readPackageDeps(cwd) {
|
||||
const file = path.join(cwd, 'package.json');
|
||||
try {
|
||||
const pkg = JSON.parse(fs.readFileSync(file, 'utf-8'));
|
||||
return {
|
||||
...(pkg.dependencies || {}),
|
||||
...(pkg.devDependencies || {}),
|
||||
...(pkg.peerDependencies || {}),
|
||||
};
|
||||
} catch {
|
||||
return {};
|
||||
}
|
||||
}
|
||||
|
||||
export function hasAnyDependency(cwd, names) {
|
||||
const deps = readPackageDeps(cwd);
|
||||
return names.some((name) => Boolean(deps[name]));
|
||||
}
|
||||
|
||||
/** First top-level file name matching `re`, or null. */
|
||||
export function findConfigFile(cwd, re) {
|
||||
try {
|
||||
return fs.readdirSync(cwd, { withFileTypes: true })
|
||||
.find((entry) => entry.isFile() && re.test(entry.name))
|
||||
?.name ?? null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
export function fileExists(cwd, rel) {
|
||||
try {
|
||||
return fs.existsSync(path.join(cwd, rel));
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
export function firstExistingFile(cwd, candidates) {
|
||||
for (const rel of candidates) {
|
||||
if (fileExists(cwd, rel)) return rel;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Literal (non-glob) entries of `config.files` that exist on disk. Several
|
||||
* detectors read the configured injection target as a signal, which is how the
|
||||
* bare fixtures — a tree of `.astro` files with no astro.config — still resolve
|
||||
* to the framework that authored them.
|
||||
*/
|
||||
export function literalConfigFiles(cwd, config) {
|
||||
const files = Array.isArray(config?.files) ? config.files : [];
|
||||
const out = [];
|
||||
for (const rel of files) {
|
||||
if (typeof rel !== 'string' || rel.includes('*') || rel.includes('?')) continue;
|
||||
const normalized = rel.split(path.sep).join('/');
|
||||
if (fileExists(cwd, normalized)) out.push(normalized);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
@@ -0,0 +1,143 @@
|
||||
/**
|
||||
* The live-mode framework registry.
|
||||
*
|
||||
* Before this existed, framework knowledge was smeared across live-inject.mjs
|
||||
* (detection order, the Nuxt adapter, the Astro `is:inline` branch), the two
|
||||
* adapter modules, and live-wrap.mjs (which extension gets component preview,
|
||||
* which gets Astro's global-prefixed CSS, which gets JSX comments). Adding or
|
||||
* fixing a framework meant reading all of them.
|
||||
*
|
||||
* One entry per framework now declares everything the live scripts need:
|
||||
*
|
||||
* name stable identifier; also the `adapter` value in inject JSON.
|
||||
* detect (cwd, config) → falsy when this is not the project, otherwise
|
||||
* a truthy project descriptor that apply/remove/artifacts read.
|
||||
* Order in FRAMEWORKS is priority order; first truthy wins.
|
||||
* inject { kind: 'adapter', apply, remove, ignorePatterns, artifacts,
|
||||
* unpatch } for frameworks that server-render their document
|
||||
* shell, or { kind: 'tag' } for the generic marker-wrapped
|
||||
* <script src> block.
|
||||
* source how live-wrap treats files this framework authors:
|
||||
* extensions, preview ('source' | 'component'), styleMode,
|
||||
* styleTag, commentSyntax, injectScriptAttrs. Anything omitted
|
||||
* falls back to SOURCE_TRAIT_DEFAULTS.
|
||||
*
|
||||
* Two rules hold the thing together:
|
||||
*
|
||||
* 1. **Detection order is injection priority.** SvelteKit → Nuxt → TanStack
|
||||
* Start → Astro → Next → Vite → static HTML, exactly the order
|
||||
* live-inject.mjs used to hard-code. static-html always matches, so
|
||||
* resolveFramework never returns null.
|
||||
* 2. **Source traits resolve by file extension, not by project.** A SvelteKit
|
||||
* project's injection target is `src/app.html`; a Vite app can contain
|
||||
* `.astro` partials. live-wrap has always keyed these off the target file,
|
||||
* and resolveSourceTraits keeps it that way. Several entries may claim the
|
||||
* same extension (`.tsx` belongs to three); when they do, the values must
|
||||
* agree, which tests/live-frameworks.test.mjs asserts.
|
||||
*/
|
||||
|
||||
import path from 'node:path';
|
||||
|
||||
import { sveltekit } from './sveltekit.mjs';
|
||||
import { nuxt } from './nuxt.mjs';
|
||||
import { tanstackStart } from './tanstack-start.mjs';
|
||||
import { astro } from './astro.mjs';
|
||||
import { nextjs } from './nextjs.mjs';
|
||||
import { viteGeneric } from './vite-generic.mjs';
|
||||
import { staticHtml } from './static-html.mjs';
|
||||
import { TAG_PATCH_MARKERS, unpatchTagFile } from './tag-strategy.mjs';
|
||||
|
||||
/** Priority order. Do not reorder without re-reading rule 1 above. */
|
||||
export const FRAMEWORKS = Object.freeze([
|
||||
sveltekit,
|
||||
nuxt,
|
||||
tanstackStart,
|
||||
astro,
|
||||
nextjs,
|
||||
viteGeneric,
|
||||
staticHtml,
|
||||
]);
|
||||
|
||||
export const PREVIEW_MODES = Object.freeze(['source', 'component']);
|
||||
export const STYLE_MODES = Object.freeze(['scoped', 'astro-global-prefixed']);
|
||||
export const COMMENT_SYNTAXES = Object.freeze(['html', 'jsx']);
|
||||
export const INJECT_KINDS = Object.freeze(['adapter', 'tag']);
|
||||
|
||||
export const SOURCE_TRAIT_DEFAULTS = Object.freeze({
|
||||
preview: 'source',
|
||||
styleMode: 'scoped',
|
||||
styleTag: '<style data-impeccable-css="SESSION_ID">',
|
||||
commentSyntax: 'html',
|
||||
injectScriptAttrs: '',
|
||||
});
|
||||
|
||||
/** The patch kind the generic tag strategy records in the journal. */
|
||||
export const TAG_PATCH_KIND = 'live-tag';
|
||||
|
||||
/**
|
||||
* Undo functions keyed by the `patch` value an artifact carries. Built from
|
||||
* the entries so a new adapter registers its own undo alongside its apply.
|
||||
*/
|
||||
export const PATCH_UNDOERS = Object.freeze(Object.assign(
|
||||
{ [TAG_PATCH_KIND]: unpatchTagFile },
|
||||
...FRAMEWORKS.map((framework) => framework.inject.unpatch || {}),
|
||||
));
|
||||
|
||||
/**
|
||||
* First entry whose detect() matches. Returns { framework, project } where
|
||||
* project is the detector's descriptor (adapters read it; tag frameworks
|
||||
* mostly ignore it).
|
||||
*/
|
||||
export function resolveFramework(cwd = process.cwd(), config = null) {
|
||||
for (const framework of FRAMEWORKS) {
|
||||
const project = framework.detect(cwd, config);
|
||||
if (project) return { framework, project };
|
||||
}
|
||||
// Unreachable while static-html stays terminal, but a caller that reorders
|
||||
// the array should get a diagnosable null rather than a silent tag inject.
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Source-authoring traits for one file, merged over SOURCE_TRAIT_DEFAULTS.
|
||||
* `framework` names the entry that claimed the extension, or null.
|
||||
*/
|
||||
export function resolveSourceTraits(filePath) {
|
||||
const ext = path.extname(String(filePath || '')).toLowerCase();
|
||||
for (const framework of FRAMEWORKS) {
|
||||
const source = framework.source;
|
||||
if (!source || !source.extensions.includes(ext)) continue;
|
||||
const { extensions, ...traits } = source;
|
||||
return { framework: framework.name, ...SOURCE_TRAIT_DEFAULTS, ...traits };
|
||||
}
|
||||
return { framework: null, ...SOURCE_TRAIT_DEFAULTS };
|
||||
}
|
||||
|
||||
/**
|
||||
* Extra gitignore patterns the resolved framework needs beyond the static
|
||||
* LIVE_IGNORE_PATTERNS list (paths that depend on a detected srcDir or file
|
||||
* extension and so cannot be written down ahead of time).
|
||||
*/
|
||||
export function frameworkIgnorePatterns(resolved) {
|
||||
const fn = resolved?.framework?.inject?.ignorePatterns;
|
||||
return typeof fn === 'function' ? (fn(resolved.project) || []) : [];
|
||||
}
|
||||
|
||||
/**
|
||||
* The files this injection will create or patch, in journal-artifact form.
|
||||
* Adapters declare their own; the tag strategy patches exactly the resolved
|
||||
* config files.
|
||||
*/
|
||||
export function describeInjectArtifacts(resolved, { cwd = process.cwd(), files = [] } = {}) {
|
||||
if (!resolved) return [];
|
||||
const { framework, project } = resolved;
|
||||
if (framework.inject.kind === 'adapter') {
|
||||
return (framework.inject.artifacts?.({ cwd, project }) || []).filter((a) => a && a.path);
|
||||
}
|
||||
return files.map((file) => ({
|
||||
kind: 'patched',
|
||||
path: file,
|
||||
patch: TAG_PATCH_KIND,
|
||||
markers: [...TAG_PATCH_MARKERS],
|
||||
}));
|
||||
}
|
||||
@@ -0,0 +1,197 @@
|
||||
/**
|
||||
* Crash-safe injection journal.
|
||||
*
|
||||
* Injection writes into the user's source tree: generated components, a Nuxt
|
||||
* client plugin, marker blocks inside a layout, a patched CSP meta tag. The
|
||||
* clean path removes all of it on stop. The unclean paths do not:
|
||||
*
|
||||
* - the dev server is SIGKILLed, so `--remove` never runs;
|
||||
* - the project changes shape between start and stop (a nuxt.config appears,
|
||||
* a package.json is edited), so detection resolves a different framework
|
||||
* and the old framework's artifacts are nobody's business;
|
||||
* - stop runs from a different directory than start did.
|
||||
*
|
||||
* So every inject records what it wrote to `.impeccable/live/inject-journal.json`
|
||||
* before the next one runs, and both inject and `--remove` reconcile that
|
||||
* record against the tree.
|
||||
*
|
||||
* **The journal is a claim of ownership, not a to-do list.** Healing an
|
||||
* artifact only ever removes what still carries our marker; a generated file
|
||||
* the user has since replaced, or a layout they have since un-patched by hand,
|
||||
* is dropped from the journal untouched.
|
||||
*
|
||||
* **Path resolution is appRoot-relative.** Live entry scripts chdir onto the
|
||||
* roots manifest (`enterLiveRoot`) before doing anything, so a journal written
|
||||
* by a session started in the app root is found by a stop issued from any
|
||||
* directory inside the repo.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { PATCH_UNDOERS } from './index.mjs';
|
||||
|
||||
export const INJECT_JOURNAL_VERSION = 1;
|
||||
export const INJECT_JOURNAL_RELPATH = '.impeccable/live/inject-journal.json';
|
||||
|
||||
export function injectJournalPath(cwd = process.cwd()) {
|
||||
return path.join(cwd, ...INJECT_JOURNAL_RELPATH.split('/'));
|
||||
}
|
||||
|
||||
export function readInjectJournal(cwd = process.cwd()) {
|
||||
const file = injectJournalPath(cwd);
|
||||
let raw;
|
||||
try {
|
||||
raw = JSON.parse(fs.readFileSync(file, 'utf-8'));
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
if (!raw || typeof raw !== 'object' || !Array.isArray(raw.artifacts)) return null;
|
||||
return raw;
|
||||
}
|
||||
|
||||
export function clearInjectJournal(cwd = process.cwd()) {
|
||||
try { fs.unlinkSync(injectJournalPath(cwd)); } catch { /* already gone */ }
|
||||
}
|
||||
|
||||
function writeInjectJournal(cwd, journal) {
|
||||
const file = injectJournalPath(cwd);
|
||||
fs.mkdirSync(path.dirname(file), { recursive: true });
|
||||
fs.writeFileSync(file, JSON.stringify(journal, null, 2) + '\n', 'utf-8');
|
||||
return file;
|
||||
}
|
||||
|
||||
/**
|
||||
* Record the artifacts an injection just wrote. Replaces any previous record:
|
||||
* callers heal first (see healInjectJournal), so nothing survivable is lost.
|
||||
*/
|
||||
export function recordInjection(cwd = process.cwd(), { framework, port, artifacts = [] } = {}) {
|
||||
if (!artifacts.length) {
|
||||
clearInjectJournal(cwd);
|
||||
return null;
|
||||
}
|
||||
return writeInjectJournal(cwd, {
|
||||
version: INJECT_JOURNAL_VERSION,
|
||||
appRoot: path.resolve(cwd),
|
||||
framework: framework || null,
|
||||
port: Number.isFinite(Number(port)) ? Number(port) : null,
|
||||
pid: process.pid,
|
||||
recordedAt: new Date().toISOString(),
|
||||
artifacts,
|
||||
});
|
||||
}
|
||||
|
||||
function normalizeRel(cwd, rel) {
|
||||
return path.resolve(cwd, String(rel || '')).split(path.sep).join('/');
|
||||
}
|
||||
|
||||
function readIfPresent(abs) {
|
||||
try {
|
||||
return fs.readFileSync(abs, 'utf-8');
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function pruneEmptyDirs(dir, stopDir) {
|
||||
let current = path.resolve(dir);
|
||||
const stop = path.resolve(stopDir);
|
||||
while (current !== stop && current.startsWith(stop + path.sep)) {
|
||||
try {
|
||||
if (fs.readdirSync(current).length > 0) return;
|
||||
fs.rmdirSync(current);
|
||||
} catch {
|
||||
return;
|
||||
}
|
||||
current = path.dirname(current);
|
||||
}
|
||||
}
|
||||
|
||||
function insideProject(cwd, abs) {
|
||||
const rel = path.relative(path.resolve(cwd), path.resolve(abs));
|
||||
return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
|
||||
}
|
||||
|
||||
function healArtifact(cwd, artifact, undoers) {
|
||||
const abs = path.resolve(cwd, artifact.path);
|
||||
// The journal is a project-local file, i.e. attacker-writable input in a
|
||||
// cloned repo. Never touch anything outside the project tree, whatever the
|
||||
// journal claims to own.
|
||||
if (!insideProject(cwd, abs)) return { path: artifact.path, action: 'refused_outside_project' };
|
||||
const content = readIfPresent(abs);
|
||||
if (content === null) return { path: artifact.path, action: 'absent' };
|
||||
|
||||
if (artifact.kind === 'created') {
|
||||
// Only reclaim a generated file that still carries our marker; a created
|
||||
// artifact with no marker at all is unverifiable and stays untouched.
|
||||
if (!artifact.marker || !content.includes(artifact.marker)) {
|
||||
return { path: artifact.path, action: 'disowned' };
|
||||
}
|
||||
try { fs.rmSync(abs, { force: true }); } catch { return null; }
|
||||
if (artifact.pruneTo !== undefined) {
|
||||
const pruneRoot = path.resolve(cwd, artifact.pruneTo || '.');
|
||||
if (insideProject(cwd, pruneRoot) || pruneRoot === path.resolve(cwd)) {
|
||||
pruneEmptyDirs(path.dirname(abs), pruneRoot);
|
||||
}
|
||||
}
|
||||
return { path: artifact.path, action: 'removed' };
|
||||
}
|
||||
|
||||
if (artifact.kind === 'patched') {
|
||||
const markers = Array.isArray(artifact.markers) ? artifact.markers : [];
|
||||
// No marker left means the patch is already gone; never run an undo over
|
||||
// a file we no longer recognize (the undoers normalize whitespace).
|
||||
if (markers.length && !markers.some((marker) => content.includes(marker))) {
|
||||
return { path: artifact.path, action: 'disowned' };
|
||||
}
|
||||
const undo = undoers[artifact.patch];
|
||||
if (typeof undo !== 'function') return null;
|
||||
const next = undo(content);
|
||||
if (next === content) return { path: artifact.path, action: 'disowned' };
|
||||
try { fs.writeFileSync(abs, next, 'utf-8'); } catch { return null; }
|
||||
return { path: artifact.path, action: 'unpatched' };
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Reconcile the journal against the tree.
|
||||
*
|
||||
* `keep` is the set of paths the current operation legitimately owns — the
|
||||
* artifacts an inject is about to (re)write. Everything else in the journal is
|
||||
* an orphan of a session that is gone, and gets healed. This keeps a repeat
|
||||
* inject byte-idempotent: the artifacts it is about to rewrite are kept, not
|
||||
* torn down and rebuilt.
|
||||
*
|
||||
* Returns `{ healed, kept }`. `healed` lists only artifacts whose file was
|
||||
* actually changed or removed, so callers can stay silent when nothing was
|
||||
* orphaned. Idempotent: a second call finds an empty journal.
|
||||
*/
|
||||
export function healInjectJournal(cwd = process.cwd(), { keep = [], undoers = PATCH_UNDOERS } = {}) {
|
||||
const journal = readInjectJournal(cwd);
|
||||
if (!journal) return { healed: [], kept: [] };
|
||||
|
||||
const keepSet = new Set(keep.map((rel) => normalizeRel(cwd, rel)));
|
||||
const healed = [];
|
||||
const kept = [];
|
||||
|
||||
for (const artifact of journal.artifacts) {
|
||||
if (!artifact || typeof artifact.path !== 'string') continue;
|
||||
if (keepSet.has(normalizeRel(cwd, artifact.path))) {
|
||||
kept.push(artifact);
|
||||
continue;
|
||||
}
|
||||
const outcome = healArtifact(cwd, artifact, undoers);
|
||||
if (outcome && (outcome.action === 'removed' || outcome.action === 'unpatched')) {
|
||||
healed.push(outcome);
|
||||
}
|
||||
}
|
||||
|
||||
if (kept.length) {
|
||||
writeInjectJournal(cwd, { ...journal, artifacts: kept });
|
||||
} else {
|
||||
clearInjectJournal(cwd);
|
||||
}
|
||||
|
||||
return { healed, kept };
|
||||
}
|
||||
@@ -0,0 +1,49 @@
|
||||
/**
|
||||
* Next.js registry entry.
|
||||
*
|
||||
* Next takes the generic tag strategy: the App Router's root layout renders
|
||||
* `<html>…<body>` in JSX, so the marker-wrapped script block goes in there
|
||||
* verbatim. Nothing about injection differs from a plain Vite app, which is
|
||||
* why live-inject.mjs never had a Next branch. The entry exists so the
|
||||
* registry can name what it is looking at.
|
||||
*/
|
||||
|
||||
import { fileExists, findConfigFile, hasAnyDependency } from './detect-utils.mjs';
|
||||
|
||||
const NEXT_CONFIG_RE = /^next\.config\.(?:js|mjs|cjs|ts|mts|cts)$/;
|
||||
|
||||
const ROUTER_ENTRY_CANDIDATES = [
|
||||
'app/layout.tsx', 'app/layout.jsx', 'app/layout.ts', 'app/layout.js',
|
||||
'src/app/layout.tsx', 'src/app/layout.jsx', 'src/app/layout.ts', 'src/app/layout.js',
|
||||
'pages/_app.tsx', 'pages/_app.jsx', 'pages/_app.ts', 'pages/_app.js',
|
||||
'pages/_document.tsx', 'pages/_document.jsx',
|
||||
'src/pages/_app.tsx', 'src/pages/_app.jsx',
|
||||
];
|
||||
|
||||
export function detectNextProject(cwd = process.cwd()) {
|
||||
const configFile = findConfigFile(cwd, NEXT_CONFIG_RE);
|
||||
if (configFile) return { configFile, via: 'config' };
|
||||
if (hasAnyDependency(cwd, ['next'])) return { configFile: null, via: 'package' };
|
||||
// Next's file conventions are distinctive enough to stand alone: a root
|
||||
// `app/layout.*` or `pages/_app.*` is not a shape other bundlers produce.
|
||||
const entry = ROUTER_ENTRY_CANDIDATES.find((rel) => fileExists(cwd, rel));
|
||||
if (entry) return { configFile: null, via: 'router-entry', entry };
|
||||
return null;
|
||||
}
|
||||
|
||||
export const nextjs = {
|
||||
name: 'nextjs',
|
||||
|
||||
detect(cwd) {
|
||||
return detectNextProject(cwd);
|
||||
},
|
||||
|
||||
inject: { kind: 'tag' },
|
||||
|
||||
source: {
|
||||
extensions: ['.tsx', '.jsx'],
|
||||
preview: 'source',
|
||||
styleMode: 'scoped',
|
||||
commentSyntax: 'jsx',
|
||||
},
|
||||
};
|
||||
@@ -0,0 +1,161 @@
|
||||
/**
|
||||
* Nuxt registry entry, and the Nuxt adapter itself.
|
||||
*
|
||||
* A script element placed in app.vue is compiled as Vue-rendered DOM and is
|
||||
* not executed. Nuxt instead auto-discovers client plugins. Keep the adapter
|
||||
* generated, dev-only, and outside user-authored source: Live creates one
|
||||
* marked .client.ts plugin on start and removes it on stop.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { buildLiveScriptSrc } from './script-src.mjs';
|
||||
import { findConfigFile } from './detect-utils.mjs';
|
||||
|
||||
export const NUXT_PLUGIN_MARKER = 'impeccable-live-nuxt-plugin';
|
||||
export const NUXT_PLUGIN_NAME = 'impeccable-live.client.ts';
|
||||
|
||||
const NUXT_CONFIG_RE = /^nuxt\.config\.(?:js|mjs|cjs|ts|mts|cts)$/;
|
||||
|
||||
export function detectNuxtProject(cwd = process.cwd()) {
|
||||
const configFile = findConfigFile(cwd, NUXT_CONFIG_RE);
|
||||
if (!configFile) return null;
|
||||
|
||||
const config = fs.readFileSync(path.join(cwd, configFile), 'utf-8');
|
||||
const literalSrcDir = config.match(/\bsrcDir\s*:\s*(['"])([^'"]+)\1/);
|
||||
let appDir = '';
|
||||
if (literalSrcDir) {
|
||||
const candidate = literalSrcDir[2]
|
||||
.replace(/\\/g, '/')
|
||||
.replace(/^\.\//, '')
|
||||
.replace(/\/+$/, '');
|
||||
const normalized = path.posix.normalize(candidate);
|
||||
if (normalized !== '..' && !normalized.startsWith('../') && !path.isAbsolute(normalized)) {
|
||||
appDir = normalized === '.' ? '' : normalized;
|
||||
}
|
||||
} else if (
|
||||
fs.existsSync(path.join(cwd, 'app', 'app.vue'))
|
||||
|| fs.existsSync(path.join(cwd, 'app', 'pages'))
|
||||
) {
|
||||
appDir = 'app';
|
||||
}
|
||||
|
||||
const pluginFile = [appDir, 'plugins', NUXT_PLUGIN_NAME].filter(Boolean).join('/');
|
||||
return { configFile, appDir, pluginFile };
|
||||
}
|
||||
|
||||
export function buildNuxtPlugin(port, token) {
|
||||
return `/* ${NUXT_PLUGIN_MARKER} */
|
||||
const liveSrc = '${buildLiveScriptSrc(port, token)}';
|
||||
const liveSelector = 'script[data-impeccable-live-nuxt]';
|
||||
|
||||
export default defineNuxtPlugin(() => {
|
||||
if (!import.meta.dev || typeof document === 'undefined') return;
|
||||
|
||||
const expectedSrc = new URL(liveSrc, window.location.href).href;
|
||||
let script = document.querySelector(liveSelector);
|
||||
if (script?.src === expectedSrc) return;
|
||||
script?.remove();
|
||||
|
||||
script = document.createElement('script');
|
||||
script.src = liveSrc;
|
||||
script.async = true;
|
||||
script.dataset.impeccableLiveNuxt = '';
|
||||
document.head.appendChild(script);
|
||||
|
||||
import.meta.hot?.dispose(() => {
|
||||
if (script?.isConnected) script.remove();
|
||||
});
|
||||
});
|
||||
/* /${NUXT_PLUGIN_MARKER} */
|
||||
`;
|
||||
}
|
||||
|
||||
export function applyNuxtLiveAdapter({ cwd = process.cwd(), port, token, project = detectNuxtProject(cwd) }) {
|
||||
if (!project) return { error: 'nuxt_not_detected' };
|
||||
const absFile = path.join(cwd, project.pluginFile);
|
||||
const existing = fs.existsSync(absFile) ? fs.readFileSync(absFile, 'utf-8') : null;
|
||||
if (existing !== null && !existing.includes(NUXT_PLUGIN_MARKER)) {
|
||||
return {
|
||||
file: project.pluginFile,
|
||||
error: 'nuxt_plugin_conflict',
|
||||
hint: `${project.pluginFile} already exists and is not managed by Impeccable Live`,
|
||||
};
|
||||
}
|
||||
|
||||
const content = buildNuxtPlugin(port, token);
|
||||
fs.mkdirSync(path.dirname(absFile), { recursive: true });
|
||||
if (content !== existing) fs.writeFileSync(absFile, content, 'utf-8');
|
||||
return {
|
||||
file: project.pluginFile,
|
||||
inserted: true,
|
||||
changed: content !== existing,
|
||||
devOnly: true,
|
||||
};
|
||||
}
|
||||
|
||||
export function removeNuxtLiveAdapter({ cwd = process.cwd(), project = detectNuxtProject(cwd) }) {
|
||||
if (!project) return { error: 'nuxt_not_detected' };
|
||||
const absFile = path.join(cwd, project.pluginFile);
|
||||
if (!fs.existsSync(absFile)) {
|
||||
return { file: project.pluginFile, removed: false, note: 'no adapter present' };
|
||||
}
|
||||
const content = fs.readFileSync(absFile, 'utf-8');
|
||||
if (!content.includes(NUXT_PLUGIN_MARKER)) {
|
||||
return {
|
||||
file: project.pluginFile,
|
||||
removed: false,
|
||||
error: 'nuxt_plugin_conflict',
|
||||
hint: `${project.pluginFile} is not managed by Impeccable Live`,
|
||||
};
|
||||
}
|
||||
fs.unlinkSync(absFile);
|
||||
const pluginDir = path.dirname(absFile);
|
||||
if (fs.readdirSync(pluginDir).length === 0) fs.rmdirSync(pluginDir);
|
||||
return { file: project.pluginFile, removed: true };
|
||||
}
|
||||
|
||||
export const nuxt = {
|
||||
name: 'nuxt',
|
||||
|
||||
detect(cwd) {
|
||||
return detectNuxtProject(cwd);
|
||||
},
|
||||
|
||||
inject: {
|
||||
kind: 'adapter',
|
||||
|
||||
apply({ cwd, port, token, project }) {
|
||||
return applyNuxtLiveAdapter({ cwd, port, token, project });
|
||||
},
|
||||
|
||||
remove({ cwd, project }) {
|
||||
return removeNuxtLiveAdapter({ cwd, project });
|
||||
},
|
||||
|
||||
// The plugin path depends on the resolved srcDir, so it cannot live in the
|
||||
// static ignore list the way the SvelteKit paths do.
|
||||
ignorePatterns(project) {
|
||||
return project?.pluginFile ? [project.pluginFile] : [];
|
||||
},
|
||||
|
||||
artifacts({ project }) {
|
||||
if (!project?.pluginFile) return [];
|
||||
return [{
|
||||
kind: 'created',
|
||||
path: project.pluginFile,
|
||||
marker: NUXT_PLUGIN_MARKER,
|
||||
// Mirrors removeNuxtLiveAdapter: the generated `plugins/` directory
|
||||
// goes when it empties, its parent stays.
|
||||
pruneTo: path.posix.dirname(path.posix.dirname(project.pluginFile)),
|
||||
}];
|
||||
},
|
||||
},
|
||||
|
||||
source: {
|
||||
extensions: ['.vue'],
|
||||
preview: 'source',
|
||||
styleMode: 'scoped',
|
||||
commentSyntax: 'html',
|
||||
},
|
||||
};
|
||||
@@ -0,0 +1,17 @@
|
||||
/**
|
||||
* The one place that builds the `/live.js` URL the browser loads.
|
||||
*
|
||||
* Every injection path needs it (the generic script tag, the Nuxt client
|
||||
* plugin, the SvelteKit root component, the TanStack mount component), and a
|
||||
* separate module keeps that shared leaf free of import cycles: the framework
|
||||
* entries import it, and nothing here imports a framework entry.
|
||||
*/
|
||||
|
||||
/**
|
||||
* When a token is supplied it rides as a `?token=...` query param so the
|
||||
* server's token-gated /live.js handler authorizes the fetch.
|
||||
*/
|
||||
export function buildLiveScriptSrc(port, token) {
|
||||
const base = 'http://localhost:' + port + '/live.js';
|
||||
return token ? base + '?token=' + encodeURIComponent(token) : base;
|
||||
}
|
||||
@@ -0,0 +1,26 @@
|
||||
/**
|
||||
* Static HTML registry entry: the terminal fallback.
|
||||
*
|
||||
* Hand-written pages, a multi-page site emitted by a generator, anything with
|
||||
* no bundler config at the app root. `detect` always matches, so this entry
|
||||
* must stay last in FRAMEWORKS. Its behavior is the plain tag strategy, which
|
||||
* is what live-inject.mjs did for every unrecognized project before the
|
||||
* registry existed.
|
||||
*/
|
||||
|
||||
export const staticHtml = {
|
||||
name: 'static-html',
|
||||
|
||||
detect() {
|
||||
return { via: 'fallback' };
|
||||
},
|
||||
|
||||
inject: { kind: 'tag' },
|
||||
|
||||
source: {
|
||||
extensions: ['.html', '.htm'],
|
||||
preview: 'source',
|
||||
styleMode: 'scoped',
|
||||
commentSyntax: 'html',
|
||||
},
|
||||
};
|
||||
@@ -0,0 +1,71 @@
|
||||
/**
|
||||
* SvelteKit registry entry.
|
||||
*
|
||||
* Detection and the apply/remove pair are the existing adapter's
|
||||
* (`../sveltekit-adapter.mjs`); this file only declares them to the registry
|
||||
* and names the artifacts the journal has to be able to heal.
|
||||
*/
|
||||
|
||||
import {
|
||||
SVELTE_LAYOUT_MARKER_OPEN,
|
||||
SVELTE_LIVE_ROOT_COMPONENT,
|
||||
applySvelteKitLiveAdapter,
|
||||
detectSvelteKitProject,
|
||||
removeSvelteKitLiveAdapter,
|
||||
unpatchSvelteLayout,
|
||||
} from '../sveltekit-adapter.mjs';
|
||||
|
||||
export const sveltekit = {
|
||||
name: 'sveltekit',
|
||||
|
||||
detect(cwd, config) {
|
||||
return detectSvelteKitProject(cwd, config);
|
||||
},
|
||||
|
||||
inject: {
|
||||
kind: 'adapter',
|
||||
|
||||
apply({ cwd, port, token, config }) {
|
||||
return applySvelteKitLiveAdapter({ cwd, port, token, config });
|
||||
},
|
||||
|
||||
remove({ cwd, config }) {
|
||||
return removeSvelteKitLiveAdapter({ cwd, config });
|
||||
},
|
||||
|
||||
// The generated root component and the `src/lib/impeccable/` runtime paths
|
||||
// are already in the static LIVE_IGNORE_PATTERNS list, so nothing extra.
|
||||
ignorePatterns() {
|
||||
return [];
|
||||
},
|
||||
|
||||
artifacts({ project }) {
|
||||
return [
|
||||
{
|
||||
kind: 'created',
|
||||
path: SVELTE_LIVE_ROOT_COMPONENT,
|
||||
marker: 'impeccable-live-root',
|
||||
pruneTo: 'src',
|
||||
},
|
||||
{
|
||||
kind: 'patched',
|
||||
path: project?.layoutFile || 'src/routes/+layout.svelte',
|
||||
patch: 'sveltekit-layout',
|
||||
markers: [SVELTE_LAYOUT_MARKER_OPEN],
|
||||
},
|
||||
];
|
||||
},
|
||||
|
||||
unpatch: {
|
||||
'sveltekit-layout': unpatchSvelteLayout,
|
||||
},
|
||||
},
|
||||
|
||||
source: {
|
||||
extensions: ['.svelte'],
|
||||
// Svelte resets component-local state on markup HMR updates, so variants
|
||||
// are mounted from generated components rather than written into the route.
|
||||
preview: 'component',
|
||||
commentSyntax: 'html',
|
||||
},
|
||||
};
|
||||
@@ -0,0 +1,247 @@
|
||||
/**
|
||||
* The generic `tag` injection strategy.
|
||||
*
|
||||
* Frameworks without a dedicated adapter get a literal marker-wrapped
|
||||
* `<script src>` block written into the entry template named by
|
||||
* `.impeccable/live/config.json`. This module owns that block: building it,
|
||||
* inserting it at the configured anchor, removing it again, and the
|
||||
* Content-Security-Policy meta patch that keeps the cross-origin load allowed.
|
||||
*
|
||||
* It is deliberately framework-agnostic. Per-framework knowledge (Astro's
|
||||
* `is:inline`, for instance) arrives as the `scriptAttrs` argument, resolved
|
||||
* from the registry by the caller, so nothing here has to branch on a file
|
||||
* extension or a project shape.
|
||||
*/
|
||||
|
||||
import { buildLiveScriptSrc } from './script-src.mjs';
|
||||
|
||||
export const MARKER_OPEN_TEXT = 'impeccable-live-start';
|
||||
export const MARKER_CLOSE_TEXT = 'impeccable-live-end';
|
||||
|
||||
/** Markers that identify a file as still carrying our tag-strategy patch. */
|
||||
export const TAG_PATCH_MARKERS = Object.freeze([MARKER_OPEN_TEXT, 'data-impeccable-csp-original']);
|
||||
|
||||
function commentOpen(syntax) { return syntax === 'jsx' ? '{/*' : '<!--'; }
|
||||
function commentClose(syntax) { return syntax === 'jsx' ? '*/}' : '-->'; }
|
||||
|
||||
/**
|
||||
* `scriptAttrs` is a pre-rendered attribute string (trailing space included)
|
||||
* that the registry supplies for the target file. Astro is the only framework
|
||||
* that uses it today: Astro processes `<script>` tags by default and rewrites
|
||||
* src to its own bundled URL, so `is:inline ` opts out and the literal external
|
||||
* src survives.
|
||||
*/
|
||||
export function buildTagBlock(syntax, port, token, scriptAttrs = '') {
|
||||
const open = commentOpen(syntax);
|
||||
const close = commentClose(syntax);
|
||||
return (
|
||||
open + ' ' + MARKER_OPEN_TEXT + ' ' + close + '\n' +
|
||||
'<script ' + scriptAttrs + 'src="' + buildLiveScriptSrc(port, token) + '"></script>\n' +
|
||||
open + ' ' + MARKER_CLOSE_TEXT + ' ' + close + '\n'
|
||||
);
|
||||
}
|
||||
|
||||
function detectLineEnding(content) {
|
||||
if (content.includes('\r\n')) return '\r\n';
|
||||
if (content.includes('\r')) return '\r';
|
||||
return '\n';
|
||||
}
|
||||
|
||||
function normalizeLineEndings(content, lineEnding) {
|
||||
return lineEnding === '\n' ? content : content.replace(/\n/g, lineEnding);
|
||||
}
|
||||
|
||||
function readLineEndingAt(content, index) {
|
||||
if (content[index] === '\r' && content[index + 1] === '\n') return '\r\n';
|
||||
if (content[index] === '\n') return '\n';
|
||||
if (content[index] === '\r') return '\r';
|
||||
return '';
|
||||
}
|
||||
|
||||
export function insertTag(content, config, port, token, scriptAttrs = '') {
|
||||
const lineEnding = detectLineEnding(content);
|
||||
const block = normalizeLineEndings(buildTagBlock(config.commentSyntax, port, token, scriptAttrs), lineEnding);
|
||||
// insertBefore: match the LAST occurrence. Anchors like `</body>` naturally
|
||||
// belong at the end, and the same literal can appear earlier in code blocks
|
||||
// within rendered documentation pages.
|
||||
if (config.insertBefore) {
|
||||
const idx = content.lastIndexOf(config.insertBefore);
|
||||
if (idx === -1) return content;
|
||||
return content.slice(0, idx) + block + content.slice(idx);
|
||||
}
|
||||
// insertAfter: match the FIRST occurrence — typical anchors like `<head>` or
|
||||
// `<body>` open near the top of the document.
|
||||
const idx = content.indexOf(config.insertAfter);
|
||||
if (idx === -1) return content;
|
||||
const after = idx + config.insertAfter.length;
|
||||
// Preserve an existing trailing newline if the anchor already has one.
|
||||
// Slice the remainder from the original anchor offset, not prefix.length:
|
||||
// in the no-newline case prefix is one char longer than the anchor (the
|
||||
// appended '\n'), so slicing by prefix.length would drop the first real
|
||||
// character after the anchor (#227).
|
||||
const existingNewline = readLineEndingAt(content, after);
|
||||
const prefix = content.slice(0, after) + (existingNewline || lineEnding);
|
||||
const rest = content.slice(after + existingNewline.length);
|
||||
return prefix + block + rest;
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove the live script block. Matches either HTML or JSX comment markers
|
||||
* regardless of config (so stale tags from a wrong config can still be cleaned).
|
||||
*
|
||||
* Indent-preserving: captures any whitespace immediately preceding the opener
|
||||
* marker and re-emits it in place of the removed block. `insertTag` inserted
|
||||
* the block *after* the original line's indent and *before* the anchor (e.g.
|
||||
* `</body>`), which moved the indent onto the opener line and left the anchor
|
||||
* unindented. Replacing the whole block (plus its trailing newline) with just
|
||||
* the captured indent hands the indent back to the anchor that follows.
|
||||
*/
|
||||
export function removeTag(content, _syntax) {
|
||||
const patterns = [
|
||||
/([ \t]*)<!--\s*impeccable-live-start\s*-->[\s\S]*?<!--\s*impeccable-live-end\s*-->([ \t]*(?:\r\n|\n|\r|$)?)/,
|
||||
/([ \t]*)\{\/\*\s*impeccable-live-start\s*\*\/\}[\s\S]*?\{\/\*\s*impeccable-live-end\s*\*\/\}([ \t]*(?:\r\n|\n|\r|$)?)/,
|
||||
];
|
||||
for (const pat of patterns) {
|
||||
let changed = false;
|
||||
let next = content;
|
||||
do {
|
||||
content = next;
|
||||
next = content.replace(pat, (_match, leadingIndent, trailing = '') => {
|
||||
if (/[\r\n]/.test(trailing)) return leadingIndent;
|
||||
return leadingIndent || trailing || '';
|
||||
});
|
||||
if (next !== content) changed = true;
|
||||
} while (next !== content);
|
||||
if (changed) return next;
|
||||
}
|
||||
return content;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Content-Security-Policy meta-tag patcher
|
||||
//
|
||||
// When the user's HTML carries `<meta http-equiv="Content-Security-Policy">`,
|
||||
// the cross-origin load of /live.js (and the SSE/POST connection back to
|
||||
// localhost:PORT) is blocked unless the CSP explicitly allows that origin.
|
||||
//
|
||||
// On insert: append `http://localhost:PORT` to `script-src` and `connect-src`,
|
||||
// and stash the original `content` value in a `data-impeccable-csp-original`
|
||||
// attribute (base64) so revert is exact.
|
||||
//
|
||||
// On remove: detect the marker attribute, decode it, restore the original
|
||||
// content value verbatim, drop the marker.
|
||||
//
|
||||
// Header-based CSP (Next.js headers, Nuxt routeRules, SvelteKit kit.csp,
|
||||
// shared helpers) is NOT patched here — those need framework-specific config
|
||||
// edits and are handled via the existing detect-csp.mjs reference output.
|
||||
// Only the in-source meta-tag form gets the auto-patch.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const CSP_MARKER_ATTR = 'data-impeccable-csp-original';
|
||||
|
||||
function findCspMetaTags(content) {
|
||||
const out = [];
|
||||
const tagRe = /<meta\s+([^>]*?)\/?>/gis;
|
||||
let m;
|
||||
while ((m = tagRe.exec(content)) !== null) {
|
||||
const attrs = m[1];
|
||||
if (!/(http-equiv|httpEquiv)\s*=\s*(['"])Content-Security-Policy\2/i.test(attrs)) continue;
|
||||
out.push({ start: m.index, end: m.index + m[0].length, full: m[0], attrs });
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function getAttr(attrs, name) {
|
||||
const re = new RegExp(`\\b${name}\\s*=\\s*(['"])([\\s\\S]*?)\\1`, 'i');
|
||||
const m = attrs.match(re);
|
||||
return m ? { quote: m[1], value: m[2], full: m[0] } : null;
|
||||
}
|
||||
|
||||
function appendOriginToDirective(csp, directive, origin) {
|
||||
const re = new RegExp(`(^|;)(\\s*)(${directive})\\s+([^;]*)`, 'i');
|
||||
const m = csp.match(re);
|
||||
if (m) {
|
||||
const tokens = m[4].trim().split(/\s+/);
|
||||
if (tokens.includes(origin)) return csp;
|
||||
return csp.replace(re, `${m[1]}${m[2]}${m[3]} ${[...tokens, origin].join(' ')}`);
|
||||
}
|
||||
// Directive missing — add it. Use 'self' + origin so we don't inadvertently
|
||||
// narrow the policy compared to the default-src fallback (most users with
|
||||
// an explicit CSP have 'self' there).
|
||||
return csp.trim().replace(/;?\s*$/, '') + `; ${directive} 'self' ${origin}`;
|
||||
}
|
||||
|
||||
export function patchCspMeta(content, port) {
|
||||
const tags = findCspMetaTags(content);
|
||||
if (tags.length === 0) return content;
|
||||
const origin = `http://localhost:${port}`;
|
||||
|
||||
// Walk last-to-first so prior splices don't invalidate later indices.
|
||||
let result = content;
|
||||
for (let i = tags.length - 1; i >= 0; i--) {
|
||||
const tag = tags[i];
|
||||
const attrs = tag.attrs;
|
||||
if (getAttr(attrs, CSP_MARKER_ATTR)) continue; // already patched
|
||||
const contentAttr = getAttr(attrs, 'content');
|
||||
if (!contentAttr) continue;
|
||||
|
||||
const original = contentAttr.value;
|
||||
let patched = original;
|
||||
patched = appendOriginToDirective(patched, 'script-src', origin);
|
||||
patched = appendOriginToDirective(patched, 'connect-src', origin);
|
||||
// The shader overlay during 'generating' creates a screenshot via
|
||||
// URL.createObjectURL, producing a `blob:` URL — img-src 'self' rejects
|
||||
// those. Add `blob:` so the overlay doesn't throw a CSP violation.
|
||||
patched = appendOriginToDirective(patched, 'img-src', 'blob:');
|
||||
if (patched === original) continue;
|
||||
|
||||
const newContentAttr = `content=${contentAttr.quote}${patched}${contentAttr.quote}`;
|
||||
const marker = `${CSP_MARKER_ATTR}="${Buffer.from(original, 'utf-8').toString('base64')}"`;
|
||||
// The tagRe captures any whitespace between the last attribute and the
|
||||
// closing `/>` as part of `attrs`. Naively appending ` ${marker}` after
|
||||
// a replace would land it BEFORE that trailing space, leaving a double
|
||||
// space inside attrs and clobbering the space before `/>`. Split off
|
||||
// the trailing whitespace, splice the marker into the attribute body,
|
||||
// and re-append the original trailing whitespace so a self-closing
|
||||
// `<meta … />` round-trips byte-for-byte.
|
||||
const trailingWs = (attrs.match(/[ \t]*$/) || [''])[0];
|
||||
const attrsBody = attrs.slice(0, attrs.length - trailingWs.length);
|
||||
const newAttrs = attrsBody.replace(contentAttr.full, newContentAttr) + ' ' + marker + trailingWs;
|
||||
const newTag = tag.full.replace(attrs, newAttrs);
|
||||
|
||||
result = result.slice(0, tag.start) + newTag + result.slice(tag.end);
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
export function revertCspMeta(content) {
|
||||
const tags = findCspMetaTags(content);
|
||||
if (tags.length === 0) return content;
|
||||
|
||||
let result = content;
|
||||
for (let i = tags.length - 1; i >= 0; i--) {
|
||||
const tag = tags[i];
|
||||
const origAttr = getAttr(tag.attrs, CSP_MARKER_ATTR);
|
||||
if (!origAttr) continue;
|
||||
const contentAttr = getAttr(tag.attrs, 'content');
|
||||
if (!contentAttr) continue;
|
||||
|
||||
let originalValue;
|
||||
try { originalValue = Buffer.from(origAttr.value, 'base64').toString('utf-8'); }
|
||||
catch { continue; }
|
||||
|
||||
const newContentAttr = `content=${contentAttr.quote}${originalValue}${contentAttr.quote}`;
|
||||
let newAttrs = tag.attrs.replace(contentAttr.full, newContentAttr);
|
||||
// Drop the marker attribute and any single space immediately preceding it.
|
||||
newAttrs = newAttrs.replace(new RegExp(`\\s*${origAttr.full}`), '');
|
||||
const newTag = tag.full.replace(tag.attrs, newAttrs);
|
||||
|
||||
result = result.slice(0, tag.start) + newTag + result.slice(tag.end);
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
/** The journal's undo for a tag-strategy patch: drop the block, restore CSP. */
|
||||
export function unpatchTagFile(content) {
|
||||
return revertCspMeta(removeTag(content));
|
||||
}
|
||||
@@ -0,0 +1,70 @@
|
||||
/**
|
||||
* TanStack Start registry entry.
|
||||
*
|
||||
* Detection and the apply/remove pair are the existing adapter's
|
||||
* (`../tanstack-adapter.mjs`); this file only declares them to the registry
|
||||
* and names the artifacts the journal has to be able to heal.
|
||||
*/
|
||||
|
||||
import {
|
||||
TANSTACK_MARKER_OPEN,
|
||||
applyTanStackLiveAdapter,
|
||||
detectTanStackStartProject,
|
||||
removeTanStackLiveAdapter,
|
||||
unpatchTanStackRoot,
|
||||
} from '../tanstack-adapter.mjs';
|
||||
|
||||
export const tanstackStart = {
|
||||
name: 'tanstack-start',
|
||||
|
||||
detect(cwd) {
|
||||
return detectTanStackStartProject(cwd);
|
||||
},
|
||||
|
||||
inject: {
|
||||
kind: 'adapter',
|
||||
|
||||
apply({ cwd, port, token, project }) {
|
||||
return applyTanStackLiveAdapter({ cwd, port, token, project });
|
||||
},
|
||||
|
||||
remove({ cwd, project }) {
|
||||
return removeTanStackLiveAdapter({ cwd, project });
|
||||
},
|
||||
|
||||
// The mount component's extension follows the root route's, so the path
|
||||
// cannot live in the static ignore list.
|
||||
ignorePatterns(project) {
|
||||
return project?.componentFile ? [project.componentFile] : [];
|
||||
},
|
||||
|
||||
artifacts({ project }) {
|
||||
if (!project) return [];
|
||||
return [
|
||||
{
|
||||
kind: 'created',
|
||||
path: project.componentFile,
|
||||
marker: 'impeccable-live-tanstack',
|
||||
pruneTo: 'src',
|
||||
},
|
||||
{
|
||||
kind: 'patched',
|
||||
path: project.rootRoute,
|
||||
patch: 'tanstack-root',
|
||||
markers: [TANSTACK_MARKER_OPEN],
|
||||
},
|
||||
];
|
||||
},
|
||||
|
||||
unpatch: {
|
||||
'tanstack-root': unpatchTanStackRoot,
|
||||
},
|
||||
},
|
||||
|
||||
source: {
|
||||
extensions: ['.tsx', '.jsx'],
|
||||
preview: 'source',
|
||||
styleMode: 'scoped',
|
||||
commentSyntax: 'jsx',
|
||||
},
|
||||
};
|
||||
@@ -0,0 +1,42 @@
|
||||
/**
|
||||
* Generic Vite registry entry: a bundled app with a real `index.html` entry
|
||||
* and no framework-specific document ownership. React, Vue, Solid, Preact and
|
||||
* a plain TanStack Router SPA all land here — the marker-wrapped script block
|
||||
* goes straight into the HTML entry.
|
||||
*
|
||||
* This is the entry that catches everything with a bundler config; only
|
||||
* static-html sits below it.
|
||||
*/
|
||||
|
||||
import { fileExists, findConfigFile, hasAnyDependency } from './detect-utils.mjs';
|
||||
|
||||
const VITE_CONFIG_RE = /^vite\.config\.(?:js|mjs|cjs|ts|mts|cts)$/;
|
||||
|
||||
export function detectViteProject(cwd = process.cwd()) {
|
||||
const configFile = findConfigFile(cwd, VITE_CONFIG_RE);
|
||||
if (configFile) return { configFile, via: 'config' };
|
||||
if (hasAnyDependency(cwd, ['vite'])) return { configFile: null, via: 'package' };
|
||||
// A zero-config Vite app is index.html + package.json, the same pair
|
||||
// roots.mjs treats as an app root.
|
||||
if (fileExists(cwd, 'index.html') && fileExists(cwd, 'package.json')) {
|
||||
return { configFile: null, via: 'zero-config' };
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
export const viteGeneric = {
|
||||
name: 'vite-generic',
|
||||
|
||||
detect(cwd) {
|
||||
return detectViteProject(cwd);
|
||||
},
|
||||
|
||||
inject: { kind: 'tag' },
|
||||
|
||||
source: {
|
||||
extensions: ['.tsx', '.jsx'],
|
||||
preview: 'source',
|
||||
styleMode: 'scoped',
|
||||
commentSyntax: 'jsx',
|
||||
},
|
||||
};
|
||||
@@ -0,0 +1,142 @@
|
||||
/**
|
||||
* Just-in-time agent instructions for live mode.
|
||||
*
|
||||
* The live scripts, not the reference doc, own situational plumbing: every
|
||||
* event printed by live-poll carries an `_instructions` string describing
|
||||
* exactly what to do NEXT, with real ids, paths, and line numbers already
|
||||
* substituted and only the active path's rules included (a svelte-component
|
||||
* session never sees JSX guidance, and vice versa). live.md stays lean: the
|
||||
* session contract, harness policy, and design-quality guidance that is not
|
||||
* situational (identity lock, variation axes, parameter budgets).
|
||||
*
|
||||
* Keep these strings imperative, concrete, and short. They are read by an
|
||||
* agent mid-session; every sentence must earn its tokens. Instructions are
|
||||
* versioned with the scripts, so they cannot drift from behavior the way a
|
||||
* hand-maintained doc can.
|
||||
*/
|
||||
|
||||
const PLAN_POINTER = 'Plan per live.md section 4: extract the identity lock, pick default vs departure mode, commit each variant to a DIFFERENT primary axis, squint-test the trio. Size parameter knobs per section 7 budgets.';
|
||||
|
||||
function pollCmd(scriptsPath) {
|
||||
return `node ${scriptsPath}/live-poll.mjs`;
|
||||
}
|
||||
|
||||
function replyCmd(scriptsPath, id, rest) {
|
||||
return `${pollCmd(scriptsPath)} --reply ${id} ${rest}`;
|
||||
}
|
||||
|
||||
export function instructionsForEvent(event, { scriptsPath = '{{scripts_path}}' } = {}) {
|
||||
if (!event || typeof event !== 'object') return undefined;
|
||||
switch (event.type) {
|
||||
case 'generate':
|
||||
return generateInstructions(event, scriptsPath);
|
||||
case 'steer':
|
||||
return `Do what the message asks (page edits, navigation help, or a short answer). Then reply exactly once: ${replyCmd(scriptsPath, event.id, 'steer_done ["optional short toast"]')} (on failure: --reply ${event.id} error "Short reason"). No pickup ack; poll again immediately after.`;
|
||||
case 'prefetch':
|
||||
return `Speculative pre-read, no reply owed: resolve ${JSON.stringify(event.pageUrl || '/')} to its source file (root "/" is usually the boot's pageFile; multi-page sites map /foo to public/foo/index.html; SPAs map all routes to one entry), read it into context, then poll again. Skip if you cannot resolve it confidently.`;
|
||||
case 'variant_mount_failed':
|
||||
return `The browser could NOT render variant ${event.variant}${event.url ? ` (module: ${event.url})` : ''}${event.error ? `: ${String(event.error).slice(0, 200)}` : ''}. The user sees a persistent error card, not variants. Fix the variant source files, then reply ${replyCmd(scriptsPath, event.id, 'done --file <manifest or source path>')}; the browser retries on its own. Poll again after the reply.`;
|
||||
case 'accept':
|
||||
return acceptInstructions(event, scriptsPath);
|
||||
case 'discard':
|
||||
return event?._completionAck?.ok === true
|
||||
? 'Original restored and durable completion acknowledged; nothing to do. Poll again.'
|
||||
: `Completion was not acknowledged: run node ${scriptsPath}/live-complete.mjs --id ${event.id} --discarded, then poll again.`;
|
||||
case 'manual_edit_apply':
|
||||
return `The user already clicked Apply; never ask, discard, or redirect. Delegate the source edits to the impeccable_manual_edit_applier subagent when available (pass cwd, scripts path, event id, page URL, chunk/deadline, batch, evidencePath); it must not poll or reply. ${event.repair ? 'A `repair` payload is present: the previous Apply changed source but validation failed; fix the CURRENT source, never roll back yourself. ' : ''}Reply exactly once: ${replyCmd(scriptsPath, event.id, `done --data '{"status":"done","appliedEntryIds":[...],"failed":[],"files":[...],"notes":[]}'`)} (status "partial"/"error" with failed[] when not every entry applied). Then poll again.`;
|
||||
case 'timeout':
|
||||
return 'No event arrived; poll again immediately.';
|
||||
case 'exit':
|
||||
return `Session over: kill any background poll, then node ${scriptsPath}/live-server.mjs stop (removes the injected script tag). Sweep leftover impeccable-variants-start / impeccable-carbonize-start markers from source.`;
|
||||
default:
|
||||
return undefined;
|
||||
}
|
||||
}
|
||||
|
||||
function generateInstructions(event, scriptsPath) {
|
||||
const id = event.id;
|
||||
const scaffold = event.scaffold;
|
||||
const steps = [];
|
||||
|
||||
if (event.screenshotPath) {
|
||||
steps.push(`Read the annotated screenshot first: ${event.screenshotPath}. Comment {x,y} positions bind text to the child under that point; strokes read by shape (loop = emphasis on this thing, arrow = direction, cross = delete).`);
|
||||
} else {
|
||||
steps.push('No screenshot was sent (the user did not annotate); do not ask for one and do not screenshot the page. Work from element.outerHTML, the computed styles, and the prompt.');
|
||||
}
|
||||
|
||||
if (event.mode === 'insert') {
|
||||
steps.push(insertScaffoldInstructions(event, scriptsPath));
|
||||
} else if (scaffold?.previewMode === 'svelte-component') {
|
||||
steps.push(svelteComponentInstructions(event, scaffold, scriptsPath));
|
||||
} else if (scaffold && scaffold.sourceWritten === false) {
|
||||
steps.push(deferredWrapperInstructions(event, scaffold, scriptsPath));
|
||||
} else if (scaffold) {
|
||||
steps.push(`The wrapper is already written into ${scaffold.file}. Splice preview CSS plus all ${event.count} variants at line ${scaffold.insertLine} in ONE edit, following the returned cssAuthoring contract (styleTag, selector strategy, forbidden patterns). Each variant div holds exactly ONE top-level element (same tag as the original); first visible, others display: none.`);
|
||||
} else {
|
||||
steps.push(`Preflight could not scaffold${event.scaffoldError ? ` (${event.scaffoldError})` : ''}. Run node ${scriptsPath}/live-wrap.mjs --id ${id} --count ${event.count} --element-id "${event.element?.id || ''}" --classes "${(event.element?.classes || []).join(',')}" --tag "${event.element?.tagName || ''}" --text "<first ~80 chars of the picked element's textContent>". Keep the flags separate; --text disambiguates repeated siblings. On a fallback error, follow live.md's Handle fallback.`);
|
||||
}
|
||||
|
||||
steps.push(event.action && event.action !== 'impeccable'
|
||||
? `Action is "${event.action}": read reference/${event.action}.md before planning; its MUST params are non-negotiable. ${PLAN_POINTER}`
|
||||
: `Freeform action: work from SKILL.md rules plus craft-floor.md; no sub-command file. ${PLAN_POINTER}`);
|
||||
|
||||
steps.push(`When all ${event.count} variants are delivered: ${replyCmd(scriptsPath, id, 'done --file <project-root-relative path you wrote>')}. Then poll again. If generation fails after the browser flipped to GENERATING, reply --reply ${id} error "Short reason" so the bar resets (never live-accept --discard for this).`);
|
||||
|
||||
return steps.map((s, i) => `${i + 1}. ${s}`).join('\n');
|
||||
}
|
||||
|
||||
function svelteComponentInstructions(event, scaffold, scriptsPath) {
|
||||
const dir = scaffold.componentDir;
|
||||
const count = event.count;
|
||||
return `Svelte component preview. EDIT the existing stubs ${dir}/v1.svelte ... v${count}.svelte in place; never delete or recreate them; do not read them back (the prop-substituted markup is in scaffold.componentStubMarkup). Keep the stub's control flow ({#each}, {#if}) and propContract prop names exactly; never flatten a loop into literal items. The stub <style> is seeded with the source rules that style the selection; restyle or delete freely, and know that any seeded rule you do not re-declare is REMOVED from source on accept (the preview never applied it). ALL your CSS goes inside that ONE existing <style> block: Svelte forbids a second top-level style element, and a publish with a non-compiling variant is bounced back to you with file and line. Semantic class selectors only: no @scope, no data-impeccable-* attributes. Params go in ${dir}/params.json keyed by variant number (never an attribute); author knob CSS against var(--p-<id>, default) and :global([data-p-<id>="..."]). Reply with --file ${scaffold.file}. Accept later merges everything into ${scaffold.sourceFile} mechanically; you have no post-accept cleanup.`;
|
||||
}
|
||||
|
||||
function deferredWrapperInstructions(event, scaffold, scriptsPath) {
|
||||
const insertNote = Number(scaffold.replaceEndLine) < Number(scaffold.replaceStartLine)
|
||||
? ` (replaceEndLine < replaceStartLine: this is an INSERTION at line ${scaffold.replaceStartLine}; remove nothing)`
|
||||
: '';
|
||||
return `The wrapper is NOT in source yet. In ONE edit to ${scaffold.file}: splice preview CSS plus all ${event.count} variants into scaffold.wrapperBlock at the "Variants: insert below this line" marker, then replace lines ${scaffold.replaceStartLine}-${scaffold.replaceEndLine}${insertNote} with the result. Two separate writes reload the framework mid-publish and strand the browser at 0/N. Author CSS per the returned cssAuthoring contract; each variant div holds exactly ONE top-level element (same tag as the original); first visible, others display: none. On JSX/TSX wrap the <style> content in a template literal and use className / style={{...}}.`;
|
||||
}
|
||||
|
||||
function insertScaffoldInstructions(event, scriptsPath) {
|
||||
const scaffold = event.scaffold;
|
||||
const base = `Insert mode: net-new content sized around ${event.placeholder?.width || '?'}x${event.placeholder?.height || '?'} at the chosen anchor; load craft-floor.md before writing net-new markup.`;
|
||||
if (scaffold?.previewMode === 'svelte-component') {
|
||||
return `${base} Write each inserted variant as a single-root Svelte component under ${scaffold.componentDir} (no data-impeccable-* attributes, CSS in each component's <style>). Never edit the route during generation; reply with --file ${scaffold.file}.`;
|
||||
}
|
||||
if (scaffold && scaffold.sourceWritten === false) {
|
||||
return `${base} Splice your variants into scaffold.wrapperBlock at the marker and insert the result at line ${scaffold.replaceStartLine} of ${scaffold.file} in ONE edit.`;
|
||||
}
|
||||
return `${base} If no scaffold payload is present, run node ${scriptsPath}/live-insert.mjs --id ${event.id} --count ${event.count} --position ${event.insert?.position || 'after'} with the anchor flags from event.insert.anchor, then splice variants at the returned insertLine.`;
|
||||
}
|
||||
|
||||
function acceptInstructions(event, scriptsPath) {
|
||||
const result = event._acceptResult || {};
|
||||
const ackOk = event._completionAck?.ok === true;
|
||||
const prefix = ackOk ? '' : `Completion was NOT acknowledged: run node ${scriptsPath}/live-status.mjs, finish any cleanup, then node ${scriptsPath}/live-complete.mjs --id ${event.id}. `;
|
||||
|
||||
if (result.handled === true && result.carbonize === true) {
|
||||
return `${prefix}Carbonize cleanup is REQUIRED now, before the next poll, in ${result.file}: (1) locate the impeccable-carbonize-start/end block and read the impeccable-param-values comment; (2) move the CSS rules into the stylesheet that owns this area; (3) bake params while rewriting selectors (@scope wrappers to semantic classes, keep only the chosen data-p branch, substitute range literals); (4) unwrap the accepted content and drop every data-impeccable-* / data-p-* attribute; (5) delete the inline <style>, the param-values comment, and both markers plus dead @scope rules. Then run node ${scriptsPath}/live-complete.mjs --id ${event.id} and verify phase "completed"; it refuses with source_dirty while leftovers remain. Poll again only after that.`;
|
||||
}
|
||||
if (result.handled === true) {
|
||||
return `${prefix}Accept was merged into source mechanically; nothing to clean up. Poll again.`;
|
||||
}
|
||||
if (result.mode === 'fallback') {
|
||||
return `${prefix}The session lived in a generated file, so accept refused to persist there. Write the accepted variant into the true source you identified during Handle fallback, remove the temporary wrapper from the served file, then poll again.`;
|
||||
}
|
||||
if (result.mode === 'error') {
|
||||
if (result.error === 'source_locked') {
|
||||
return `${prefix}The source file is briefly locked by a publisher. Re-run the exact same live-accept.mjs command (idempotent); do NOT hand-edit the file, and do not poll past this.`;
|
||||
}
|
||||
if (result.error === 'accept_receipt_conflict') {
|
||||
return `${prefix}This session already resolved as ${result.priorOperation || 'a prior operation'}; do not edit anything. Run node ${scriptsPath}/live-status.mjs and tell the user what the session resolved to.`;
|
||||
}
|
||||
return `${prefix}Accept failed: ${result.error || 'unknown error'}. Source was not touched; do not hand-edit. Run node ${scriptsPath}/live-status.mjs before continuing.`;
|
||||
}
|
||||
return `${prefix}No mechanical accept result; read ${result.file || 'the session source file'}, find the impeccable markers, and finish the merge by hand. Poll again after.`;
|
||||
}
|
||||
|
||||
/** Boot instructions attached to live.mjs's success payload. */
|
||||
export function bootInstructions({ scriptsPath = '{{scripts_path}}' } = {}) {
|
||||
return `Open the app URL that serves a pageFiles entry (never serverPort; that is the helper). Then start the poll loop per your harness policy in live.md and re-run ${pollCmd(scriptsPath)} immediately after every event or reply. Every event carries _instructions: follow them; they are the authoritative next step with real ids and paths filled in. A poll that is running is a poll you are SERVICING: never announce you are waiting and idle your turn; stay on the exec session until it returns an event, and never end a turn while a poll is outstanding.`;
|
||||
}
|
||||
@@ -0,0 +1,508 @@
|
||||
/**
|
||||
* Live root resolution: the single place that decides which directories a live
|
||||
* session operates on. Every live entry script resolves this once at startup
|
||||
* (see enterLiveRoot) instead of trusting its ambient cwd, which is how a
|
||||
* `cd` used to silently fork the whole system into a second, empty project.
|
||||
*
|
||||
* Four distinct roots travel together as one manifest:
|
||||
*
|
||||
* appRoot what the dev server serves; where live session state,
|
||||
* injected adapters, and preview modules live.
|
||||
* repoRoot the git boundary (falls back to appRoot outside git).
|
||||
* contextRoot the nearest directory from appRoot up to repoRoot carrying
|
||||
* PRODUCT.md / DESIGN.md (canonical spot or a fallback dir).
|
||||
* sessionRoot <appRoot>/.impeccable/live — durable live state.
|
||||
*
|
||||
* appRoot detection keys on dev-server config presence (vite/svelte/next/
|
||||
* astro/nuxt/... config files), not on monorepo brand markers. A nested
|
||||
* website/ with vite.config.js wins over a repo root that merely has a
|
||||
* package.json. Workspace declarations are one input, not the gatekeeper.
|
||||
*
|
||||
* The resolved manifest is persisted at <appRoot>/.impeccable/live/roots.json
|
||||
* plus a pointer at <repoRoot>/.impeccable/live/app-root.json when the two
|
||||
* differ, so a helper invoked from anywhere inside the repo finds the same
|
||||
* roots the boot decided on. When several apps in one repo run live, the
|
||||
* pointer follows the most recent boot; per-app roots.json files stay put.
|
||||
*/
|
||||
import fs from 'node:fs';
|
||||
import os from 'node:os';
|
||||
import path from 'node:path';
|
||||
import { execFileSync } from 'node:child_process';
|
||||
import { resolveProjectRoot } from '../context.mjs';
|
||||
|
||||
const ROOTS_MANIFEST_VERSION = 1;
|
||||
const ROOTS_FILE = 'roots.json';
|
||||
const POINTER_FILE = 'app-root.json';
|
||||
|
||||
const PRODUCT_NAMES = ['PRODUCT.md', 'Product.md', 'product.md'];
|
||||
const DESIGN_NAMES = ['DESIGN.md', 'Design.md', 'design.md'];
|
||||
const CONTEXT_FALLBACK_DIRS = ['.agents/context', 'docs'];
|
||||
|
||||
// Presence of any of these marks a directory as a dev-served app root.
|
||||
const DEV_CONFIG_MARKERS = [
|
||||
'vite.config.js', 'vite.config.ts', 'vite.config.mjs', 'vite.config.mts', 'vite.config.cjs',
|
||||
'svelte.config.js', 'svelte.config.mjs', 'svelte.config.ts',
|
||||
'next.config.js', 'next.config.mjs', 'next.config.ts',
|
||||
'astro.config.mjs', 'astro.config.js', 'astro.config.ts', 'astro.config.cjs',
|
||||
'nuxt.config.ts', 'nuxt.config.js', 'nuxt.config.mjs',
|
||||
'remix.config.js', 'react-router.config.ts',
|
||||
'angular.json',
|
||||
'webpack.config.js', 'webpack.config.ts',
|
||||
];
|
||||
|
||||
const CANDIDATE_SCAN_IGNORED = new Set([
|
||||
'node_modules', '.git', 'dist', 'build', 'coverage', 'vendor', 'vendors',
|
||||
'.next', '.nuxt', '.svelte-kit', '.astro', '.turbo', '.cache', '.vercel',
|
||||
]);
|
||||
const CANDIDATE_SCAN_DEPTH = 2;
|
||||
|
||||
function exists(p) {
|
||||
try { fs.statSync(p); return true; } catch { return false; }
|
||||
}
|
||||
|
||||
function isDir(p) {
|
||||
try { return fs.statSync(p).isDirectory(); } catch { return false; }
|
||||
}
|
||||
|
||||
function firstExisting(dir, names) {
|
||||
for (const name of names) {
|
||||
const abs = path.join(dir, name);
|
||||
if (exists(abs)) return abs;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function hasDevConfig(dir) {
|
||||
if (DEV_CONFIG_MARKERS.some((name) => exists(path.join(dir, name)))) return true;
|
||||
// A plain Vite app can run with zero config: index.html + package.json.
|
||||
return exists(path.join(dir, 'index.html')) && exists(path.join(dir, 'package.json'));
|
||||
}
|
||||
|
||||
function isAppRoot(dir) {
|
||||
// A directory already configured for live IS an app root, dev config or not
|
||||
// (plain static multi-page projects have no bundler config).
|
||||
return hasDevConfig(dir) || exists(path.join(dir, '.impeccable', 'live', 'config.json'));
|
||||
}
|
||||
|
||||
function findContextFile(dir, names) {
|
||||
const direct = firstExisting(dir, names);
|
||||
if (direct) return direct;
|
||||
for (const rel of CONTEXT_FALLBACK_DIRS) {
|
||||
const nested = firstExisting(path.join(dir, rel), names);
|
||||
if (nested) return nested;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
export function findGitRoot(startDir) {
|
||||
let dir = path.resolve(startDir);
|
||||
const home = path.resolve(os.homedir());
|
||||
while (true) {
|
||||
if (dir === home) return null;
|
||||
if (exists(path.join(dir, '.git'))) return dir;
|
||||
const parent = path.dirname(dir);
|
||||
if (parent === dir) return null;
|
||||
dir = parent;
|
||||
}
|
||||
}
|
||||
|
||||
function walkUp(startDir, upperBound, visit) {
|
||||
let dir = path.resolve(startDir);
|
||||
const stop = path.resolve(upperBound);
|
||||
const home = path.resolve(os.homedir());
|
||||
while (true) {
|
||||
if (dir === home) return null;
|
||||
const hit = visit(dir);
|
||||
if (hit) return hit;
|
||||
if (dir === stop) return null;
|
||||
const parent = path.dirname(dir);
|
||||
if (parent === dir) return null;
|
||||
dir = parent;
|
||||
}
|
||||
}
|
||||
|
||||
function insideOrEqual(candidate, root) {
|
||||
const rel = path.relative(path.resolve(root), path.resolve(candidate));
|
||||
return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
|
||||
}
|
||||
|
||||
/**
|
||||
* Scan downward (bounded depth) for directories carrying a dev-server config.
|
||||
* Used when live boots from a directory that is not itself an app root and no
|
||||
* --target narrows the choice: one candidate is auto-picked, several become a
|
||||
* selection prompt.
|
||||
*/
|
||||
export function discoverAppCandidates(rootDir, depth = CANDIDATE_SCAN_DEPTH) {
|
||||
const found = [];
|
||||
const scan = (dir, remaining) => {
|
||||
let entries;
|
||||
try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
|
||||
for (const entry of entries) {
|
||||
if (!entry.isDirectory()) continue;
|
||||
if (entry.name.startsWith('.') || CANDIDATE_SCAN_IGNORED.has(entry.name)) continue;
|
||||
const abs = path.join(dir, entry.name);
|
||||
// Same criterion as the upward walk (isAppRoot): a live-configured
|
||||
// plain-static site with no bundler markers is still an app, and
|
||||
// missing it here would silently fall back to the wrong root.
|
||||
if (isAppRoot(abs)) {
|
||||
found.push(abs);
|
||||
continue; // nested apps below an app root are that app's business
|
||||
}
|
||||
if (remaining > 1) scan(abs, remaining - 1);
|
||||
}
|
||||
};
|
||||
scan(path.resolve(rootDir), depth);
|
||||
return found.sort();
|
||||
}
|
||||
|
||||
/**
|
||||
* Fresh root resolution. Never reads a persisted manifest.
|
||||
*
|
||||
* Returns { manifest } on success or { selection } when several candidate
|
||||
* apps exist and nothing disambiguates.
|
||||
*/
|
||||
export function resolveRoots({ cwd = process.cwd(), targetPath = null } = {}) {
|
||||
const absCwd = path.resolve(cwd);
|
||||
const absTarget = targetPath
|
||||
? (path.isAbsolute(targetPath) ? targetPath : path.resolve(absCwd, targetPath))
|
||||
: null;
|
||||
const targetDir = absTarget
|
||||
? (isDir(absTarget) ? absTarget : path.dirname(absTarget))
|
||||
: absCwd;
|
||||
|
||||
// The walk bound must be an ancestor of the target: a git root found from
|
||||
// the CWD is only usable when the target actually lives inside it,
|
||||
// otherwise the walk would climb out of both trees.
|
||||
const targetGitRoot = findGitRoot(targetDir);
|
||||
const cwdGitRoot = targetGitRoot ? null : findGitRoot(absCwd);
|
||||
const repoRoot = targetGitRoot
|
||||
|| (cwdGitRoot && insideOrEqual(targetDir, cwdGitRoot) ? cwdGitRoot : null);
|
||||
// Without a git boundary, never ascend above the starting directory: the
|
||||
// filesystem above an unversioned project is not ours to interpret.
|
||||
const upperBound = repoRoot || targetDir;
|
||||
|
||||
// The workspace-aware legacy resolution (context.mjs) still decides two
|
||||
// things: the fallback when no app marker exists, and how far the marker
|
||||
// walk may ascend when an explicit target selected a workspace child. A
|
||||
// root-level live config must never shadow a child the target picked.
|
||||
const legacyRoot = resolveProjectRoot(absCwd, absTarget ? { targetPath: absTarget } : {});
|
||||
const markerBound = absTarget && insideOrEqual(targetDir, legacyRoot) && insideOrEqual(legacyRoot, upperBound)
|
||||
? legacyRoot
|
||||
: upperBound;
|
||||
|
||||
let appRoot = walkUp(targetDir, markerBound, (dir) => (isAppRoot(dir) ? dir : null));
|
||||
let resolvedFrom = appRoot
|
||||
? (absTarget ? `target:${path.relative(absCwd, absTarget) || '.'}` : 'cwd')
|
||||
: null;
|
||||
|
||||
if (!appRoot && !absTarget) {
|
||||
const candidates = discoverAppCandidates(absCwd);
|
||||
if (candidates.length === 1) {
|
||||
appRoot = candidates[0];
|
||||
resolvedFrom = `candidate:${path.relative(absCwd, appRoot)}`;
|
||||
} else if (candidates.length > 1) {
|
||||
return {
|
||||
selection: {
|
||||
candidates: candidates.map((abs) => ({
|
||||
name: path.basename(abs),
|
||||
path: path.relative(absCwd, abs).split(path.sep).join('/'),
|
||||
})),
|
||||
},
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
if (!appRoot) {
|
||||
// No app marker anywhere: defer to the workspace-aware legacy resolution
|
||||
// (workspace child for a targeted monorepo path, cwd otherwise). Never
|
||||
// adopt an arbitrary ancestor just because it has a package.json, and
|
||||
// never adopt a root that does not even contain the target.
|
||||
appRoot = insideOrEqual(targetDir, legacyRoot) ? legacyRoot : targetDir;
|
||||
resolvedFrom = 'fallback';
|
||||
}
|
||||
|
||||
const effectiveRepoRoot = repoRoot && insideOrEqual(appRoot, repoRoot) ? repoRoot : appRoot;
|
||||
|
||||
// Each context file resolves independently: a child app may carry its own
|
||||
// PRODUCT.md while inheriting DESIGN.md from the repo root (or vice versa).
|
||||
const productPath = walkUp(appRoot, effectiveRepoRoot, (dir) => findContextFile(dir, PRODUCT_NAMES));
|
||||
const designPath = walkUp(appRoot, effectiveRepoRoot, (dir) => findContextFile(dir, DESIGN_NAMES));
|
||||
const contextRoot = productPath
|
||||
? path.dirname(productPath)
|
||||
: designPath
|
||||
? path.dirname(designPath)
|
||||
: null;
|
||||
|
||||
return {
|
||||
manifest: {
|
||||
version: ROOTS_MANIFEST_VERSION,
|
||||
appRoot,
|
||||
repoRoot: effectiveRepoRoot,
|
||||
contextRoot,
|
||||
sessionRoot: path.join(appRoot, '.impeccable', 'live'),
|
||||
productPath,
|
||||
designPath,
|
||||
resolvedFrom,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function rootsFilePath(appRoot) {
|
||||
return path.join(appRoot, '.impeccable', 'live', ROOTS_FILE);
|
||||
}
|
||||
|
||||
function pointerFilePath(repoRoot) {
|
||||
return path.join(repoRoot, '.impeccable', 'live', POINTER_FILE);
|
||||
}
|
||||
|
||||
export function writeRootsManifest(manifest) {
|
||||
const file = rootsFilePath(manifest.appRoot);
|
||||
fs.mkdirSync(path.dirname(file), { recursive: true });
|
||||
fs.writeFileSync(file, JSON.stringify(manifest, null, 2));
|
||||
if (path.resolve(manifest.repoRoot) !== path.resolve(manifest.appRoot)) {
|
||||
const pointer = pointerFilePath(manifest.repoRoot);
|
||||
fs.mkdirSync(path.dirname(pointer), { recursive: true });
|
||||
// The pointer records EVERY app that has booted live in this repo, most
|
||||
// recent first. A single last-boot-wins value made a helper run from the
|
||||
// repo root silently target whichever app booted last, even while an
|
||||
// earlier app's session was the one still live.
|
||||
const entries = readPointerEntries(manifest.repoRoot)
|
||||
.filter((entry) => path.resolve(entry.appRoot) !== path.resolve(manifest.appRoot));
|
||||
entries.unshift({ appRoot: manifest.appRoot, bootedAt: new Date().toISOString() });
|
||||
fs.writeFileSync(pointer, JSON.stringify({ version: 2, appRoots: entries }));
|
||||
}
|
||||
return file;
|
||||
}
|
||||
|
||||
function readPointerEntries(repoRoot) {
|
||||
try {
|
||||
const raw = JSON.parse(fs.readFileSync(pointerFilePath(repoRoot), 'utf-8'));
|
||||
if (Array.isArray(raw?.appRoots)) {
|
||||
return raw.appRoots.filter((entry) => entry && typeof entry.appRoot === 'string');
|
||||
}
|
||||
// v1 shape: a single { appRoot } value.
|
||||
if (raw && typeof raw.appRoot === 'string') return [{ appRoot: raw.appRoot }];
|
||||
return [];
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* True when the app's live helper server is recorded and its pid is alive.
|
||||
* A liveness signal alone misclassifies a REUSED pid (helper died without
|
||||
* removing server.json, the OS handed the pid to something else), so the
|
||||
* process's command line must also look like a node process; that removes
|
||||
* reuse by arbitrary processes. A pid reused by another node process remains
|
||||
* a residual false positive, which the multi-app warning and --target
|
||||
* escape hatch cover.
|
||||
*/
|
||||
function hasLiveServer(appRoot) {
|
||||
let pid;
|
||||
let port;
|
||||
let token;
|
||||
try {
|
||||
const info = JSON.parse(fs.readFileSync(path.join(appRoot, '.impeccable', 'live', 'server.json'), 'utf-8'));
|
||||
if (!info || typeof info.pid !== 'number') return false;
|
||||
pid = info.pid;
|
||||
port = Number(info.port);
|
||||
token = typeof info.token === 'string' ? info.token : null;
|
||||
process.kill(pid, 0);
|
||||
} catch (err) {
|
||||
// EPERM: the process exists but is not signalable by this user.
|
||||
if (err?.code !== 'EPERM') return false;
|
||||
}
|
||||
// Liveness alone misclassifies a REUSED pid, and a bare TCP connect
|
||||
// misclassifies a coincidental listener on a reused port. The decisive
|
||||
// signal is IDENTITY: the helper answers its authenticated /status
|
||||
// endpoint with the token server.json records; nothing else on that port
|
||||
// can. The probe is a spawned node one-liner so it works identically on
|
||||
// every platform.
|
||||
if (Number.isInteger(port) && port > 0 && token) {
|
||||
try {
|
||||
execFileSync(process.execPath, ['-e', [
|
||||
"const req = require('node:http').get({ host: '127.0.0.1', port: Number(process.argv[1]), path: '/status?token=' + encodeURIComponent(process.argv[2]), timeout: 1200 }, (res) => { res.resume(); process.exit(res.statusCode === 200 ? 0 : 1); });",
|
||||
"req.on('timeout', () => { req.destroy(); process.exit(1); });",
|
||||
"req.on('error', () => process.exit(1));",
|
||||
].join(''), String(port), token], { timeout: 4000, stdio: 'ignore' });
|
||||
return true;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
// Every server.json this codebase has ever written records port + token
|
||||
// (see writeLiveServerInfo). A record without them is malformed or foreign
|
||||
// and cannot be authenticated, so it does not count as a live helper;
|
||||
// resolution falls to the durable-session tier, which is the correct
|
||||
// recovery path for a stopped or crashed helper anyway.
|
||||
return false;
|
||||
}
|
||||
|
||||
const TERMINAL_SESSION_PHASES = new Set(['completed', 'discarded']);
|
||||
|
||||
/**
|
||||
* True when the app's durable session store holds a session that is not
|
||||
* terminal. With every helper server stopped, this is what distinguishes
|
||||
* "the app whose interrupted session the user is trying to recover" from an
|
||||
* app that merely booted more recently.
|
||||
*/
|
||||
function hasActiveDurableSession(appRoot) {
|
||||
const dir = path.join(appRoot, '.impeccable', 'live', 'sessions');
|
||||
let entries;
|
||||
try {
|
||||
entries = fs.readdirSync(dir);
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
for (const name of entries) {
|
||||
if (!name.endsWith('.snapshot.json')) continue;
|
||||
try {
|
||||
const snapshot = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf-8'));
|
||||
if (snapshot?.phase && !TERMINAL_SESSION_PHASES.has(snapshot.phase)) return true;
|
||||
} catch { /* skip unreadable snapshots */ }
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
function readManifestAt(appRoot) {
|
||||
try {
|
||||
const raw = JSON.parse(fs.readFileSync(rootsFilePath(appRoot), 'utf-8'));
|
||||
if (!raw || typeof raw.appRoot !== 'string') return null;
|
||||
// A manifest is only trusted where it claims to live; anything else is a
|
||||
// copied or stale file.
|
||||
if (path.resolve(raw.appRoot) !== path.resolve(appRoot)) return null;
|
||||
return raw;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve the roots for the live session governing `cwd`, preferring a
|
||||
* persisted manifest (written by the boot) over fresh detection:
|
||||
*
|
||||
* 1. Walk up from cwd looking for .impeccable/live/roots.json.
|
||||
* 2. At the git root, follow .impeccable/live/app-root.json to the app.
|
||||
* 3. Fresh resolveRoots().
|
||||
*
|
||||
* Fresh results are NOT persisted here; only the boot (live.mjs / server
|
||||
* startup) writes manifests, so ad-hoc helper invocations cannot mint
|
||||
* conflicting truth.
|
||||
*/
|
||||
export function resolveLiveRoots(cwd = process.cwd(), { targetPath = null } = {}) {
|
||||
const absCwd = path.resolve(cwd);
|
||||
|
||||
if (!targetPath) {
|
||||
const persisted = walkUp(absCwd, findGitRoot(absCwd) || absCwd, (dir) => readManifestAt(dir));
|
||||
if (persisted) return { manifest: persisted, source: 'persisted' };
|
||||
|
||||
const gitRoot = findGitRoot(absCwd);
|
||||
if (gitRoot) {
|
||||
// Several apps in one repo may have booted live. Preference order:
|
||||
// a running helper server, then an app whose durable store still holds
|
||||
// a non-terminal session (the stopped session the user is recovering),
|
||||
// then the most recent boot. A stale pointer entry must never redirect
|
||||
// status/poll/accept onto the wrong app's session store.
|
||||
const candidates = readPointerEntries(gitRoot)
|
||||
.map((entry) => readManifestAt(entry.appRoot))
|
||||
.filter(Boolean);
|
||||
if (candidates.length > 0) {
|
||||
const liveApps = candidates.filter((manifest) => hasLiveServer(manifest.appRoot));
|
||||
const recoveringApps = liveApps.length > 0
|
||||
? liveApps
|
||||
: candidates.filter((manifest) => hasActiveDurableSession(manifest.appRoot));
|
||||
const tier = recoveringApps.length > 0 ? recoveringApps : candidates;
|
||||
// Multiple apps qualifying at the same tier is inherent ambiguity:
|
||||
// intent is unknowable from the repo root. The choice stays
|
||||
// deterministic (most recent boot first), but it must be LOUD, not
|
||||
// silent, so the agent can re-anchor when it meant the other app.
|
||||
if (tier.length > 1) {
|
||||
const chosen = tier[0].appRoot;
|
||||
const others = tier.slice(1).map((manifest) => manifest.appRoot).join(', ');
|
||||
process.stderr.write(
|
||||
`[impeccable live] Multiple apps in this repo have live state; using ${chosen}. `
|
||||
+ `Other candidate(s): ${others}. Run from the app directory (or pass --target) to address a specific app.\n`,
|
||||
);
|
||||
}
|
||||
return { manifest: tier[0], source: 'pointer' };
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const fresh = resolveRoots({ cwd: absCwd, targetPath });
|
||||
if (fresh.selection) return { selection: fresh.selection, source: 'fresh' };
|
||||
return { manifest: fresh.manifest, source: 'fresh' };
|
||||
}
|
||||
|
||||
/**
|
||||
* Consume a `--target <path>` / `--target=<path>` pair from an argv array,
|
||||
* returning the value and removing the tokens so downstream flag parsers
|
||||
* (which do not know the option) never see them.
|
||||
*/
|
||||
export function consumeTargetArg(argv = process.argv) {
|
||||
for (let i = 0; i < argv.length; i++) {
|
||||
const arg = argv[i];
|
||||
if (arg === '--target') {
|
||||
const value = argv[i + 1];
|
||||
// A --target with no usable value must not degrade into implicit root
|
||||
// selection: these helpers mutate session state, and "the most recent
|
||||
// app" is exactly what the caller was trying NOT to get.
|
||||
if (typeof value !== 'string' || value === '' || value.startsWith('--')) {
|
||||
throw new Error('--target requires a path value (use --target <path> or --target=<path>)');
|
||||
}
|
||||
argv.splice(i, 2);
|
||||
return value;
|
||||
}
|
||||
if (typeof arg === 'string' && arg.startsWith('--target=')) {
|
||||
const value = arg.slice('--target='.length);
|
||||
if (value === '') {
|
||||
throw new Error('--target requires a path value (use --target <path> or --target=<path>)');
|
||||
}
|
||||
argv.splice(i, 1);
|
||||
return value;
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Entry-point guard for live CLI scripts: resolve the governing roots and
|
||||
* make appRoot the process cwd so every downstream path derivation agrees
|
||||
* with the boot. An explicit `--target <path>` on the helper's command line
|
||||
* overrides pointer resolution, which is what disambiguates a repo with
|
||||
* several live apps (the multi-app warning names this escape hatch, so it
|
||||
* has to actually work on every helper). Returns the manifest. On selection
|
||||
* ambiguity it stays in the current directory (the boot flow handles
|
||||
* prompting); a malformed --target exits with an error instead of silently
|
||||
* falling back to implicit selection, which could mutate the wrong app.
|
||||
*/
|
||||
export function enterLiveRoot(cwd = process.cwd()) {
|
||||
let targetPath;
|
||||
try {
|
||||
targetPath = consumeTargetArg(process.argv);
|
||||
} catch (err) {
|
||||
console.error(`[impeccable live] ${err.message}`);
|
||||
process.exit(1);
|
||||
}
|
||||
const resolved = resolveLiveRoots(cwd, targetPath ? { targetPath } : {});
|
||||
if (!resolved.manifest) return null;
|
||||
const appRoot = resolved.manifest.appRoot;
|
||||
if (path.resolve(cwd) !== path.resolve(appRoot)) {
|
||||
// Failing to land on the resolved appRoot must be fatal: a helper that
|
||||
// silently keeps its ambient cwd derives server, session, and source
|
||||
// paths from a different project and mutates the wrong state. A manifest
|
||||
// pointing at a deleted directory is stale ambient truth, not a reason
|
||||
// to guess.
|
||||
if (!isDir(appRoot)) {
|
||||
console.error(`[impeccable live] resolved app root does not exist: ${appRoot} (stale roots manifest? re-run the live boot, or pass --target <path>)`);
|
||||
process.exit(1);
|
||||
}
|
||||
try {
|
||||
process.chdir(appRoot);
|
||||
} catch (err) {
|
||||
console.error(`[impeccable live] could not enter app root ${appRoot}: ${err.message}`);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
return resolved.manifest;
|
||||
}
|
||||
@@ -1,26 +1,40 @@
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { getLegacyLiveSessionsDir, getLiveSessionsDir, safeSessionId } from '../lib/impeccable-paths.mjs';
|
||||
import { COMPLETED_SESSION_PHASES, GENERATION_FENCED_SESSION_PHASES } from './vocabulary.mjs';
|
||||
|
||||
const COMPLETED_PHASES = new Set(['completed', 'discarded']);
|
||||
export const GENERATION_FENCED_PHASES = new Set([
|
||||
'accept_requested',
|
||||
'discard_requested',
|
||||
'carbonize_required',
|
||||
'completed',
|
||||
'discarded',
|
||||
]);
|
||||
const COMPLETED_PHASES = new Set(COMPLETED_SESSION_PHASES);
|
||||
export const GENERATION_FENCED_PHASES = new Set(GENERATION_FENCED_SESSION_PHASES);
|
||||
|
||||
// The snapshot file carries two bookkeeping fields the snapshot itself does not
|
||||
// own: how large the journal was when the snapshot was written, and the next
|
||||
// sequence number. Both are stripped before a snapshot is handed to a caller.
|
||||
// The byte count is what makes a cached snapshot verifiable — the journal is
|
||||
// append-only, so a matching size means no event has landed since.
|
||||
const META_JOURNAL_BYTES = '__journalBytes';
|
||||
const META_NEXT_SEQ = '__nextSeq';
|
||||
|
||||
// TODO(revision-unification): `checkpointRevision`, `browserCheckpointRevision`,
|
||||
// and `publicationCheckpointRevision` are three counters for two domains.
|
||||
// `checkpointRevision` is a compatibility mirror of the browser counter kept for
|
||||
// older readers. Collapsing them means changing what a resumed browser compares
|
||||
// its local revision against, so it belongs in a pass that owns resume ordering,
|
||||
// not in a caching change.
|
||||
|
||||
export function createLiveSessionStore({ cwd = process.cwd(), sessionId } = {}) {
|
||||
const rootDir = getLiveSessionsDir(cwd);
|
||||
const legacyRootDir = getLegacyLiveSessionsDir(cwd);
|
||||
fs.mkdirSync(rootDir, { recursive: true });
|
||||
|
||||
// No snapshot cache on purpose: appendEvent and getSnapshot both rebuild from
|
||||
// the journal so sequence numbers and phase fences never come from a stale
|
||||
// in-memory copy when the publisher/complete helpers append from another
|
||||
// process. A cache written but never read would grow per session for the
|
||||
// lifetime of the server without ever saving a rebuild.
|
||||
// Derived state per session, keyed by what the journal looked like when it was
|
||||
// derived. Publisher/complete helpers append from other processes, so the key
|
||||
// is the journal's own (path, size, mtime) rather than a trusted local write
|
||||
// count: an append this process did not make invalidates the entry and the
|
||||
// next read replays. Without the cache every append and every read replayed
|
||||
// the whole journal, which made a long session quadratic in its own length.
|
||||
/** @type {Map<string, { snapshot: object, nextSeq: number, journalPath: string, size: number, mtimeMs: number }>} */
|
||||
const derived = new Map();
|
||||
|
||||
function getReadableJournalPath(id) {
|
||||
const primary = getJournalPath(rootDir, id);
|
||||
if (fs.existsSync(primary)) return primary;
|
||||
@@ -29,42 +43,116 @@ export function createLiveSessionStore({ cwd = process.cwd(), sessionId } = {})
|
||||
return primary;
|
||||
}
|
||||
|
||||
/**
|
||||
* The current derived state for a session, from the in-memory cache when the
|
||||
* journal has not moved, from the snapshot file when that file is provably
|
||||
* current, and from a full replay otherwise.
|
||||
*/
|
||||
function readState(id, { allowSnapshotFile = true } = {}) {
|
||||
const journalPath = getReadableJournalPath(id);
|
||||
const stat = statOrNull(journalPath);
|
||||
const size = stat ? stat.size : -1;
|
||||
const mtimeMs = stat ? stat.mtimeMs : -1;
|
||||
|
||||
const cached = derived.get(id);
|
||||
if (cached && cached.journalPath === journalPath && cached.size === size && cached.mtimeMs === mtimeMs) {
|
||||
return cached;
|
||||
}
|
||||
|
||||
if (allowSnapshotFile && stat) {
|
||||
const hydrated = readSnapshotFile(getSnapshotPath(rootDir, id), id, size);
|
||||
if (hydrated) {
|
||||
const entry = { ...hydrated, journalPath, size, mtimeMs };
|
||||
derived.set(id, entry);
|
||||
return entry;
|
||||
}
|
||||
}
|
||||
|
||||
const rebuilt = rebuildSnapshotFromJournal(journalPath, id);
|
||||
const entry = { snapshot: rebuilt.snapshot, nextSeq: rebuilt.nextSeq, journalPath, size, mtimeMs };
|
||||
derived.set(id, entry);
|
||||
return entry;
|
||||
}
|
||||
|
||||
function persist(id, snapshot, nextSeq) {
|
||||
const snapshotPath = getSnapshotPath(rootDir, id);
|
||||
const journalPath = getReadableJournalPath(id);
|
||||
const stat = statOrNull(journalPath);
|
||||
writeSnapshot(snapshotPath, snapshot, { journalBytes: stat ? stat.size : -1, nextSeq });
|
||||
derived.set(id, {
|
||||
snapshot,
|
||||
nextSeq,
|
||||
journalPath,
|
||||
size: stat ? stat.size : -1,
|
||||
mtimeMs: stat ? stat.mtimeMs : -1,
|
||||
});
|
||||
}
|
||||
|
||||
return {
|
||||
rootDir,
|
||||
legacyRootDir,
|
||||
appendEvent(event) {
|
||||
const normalized = normalizeEvent(event, sessionId);
|
||||
const journalPath = getJournalPath(rootDir, normalized.id);
|
||||
const snapshotPath = getSnapshotPath(rootDir, normalized.id);
|
||||
const legacyJournalPath = getJournalPath(legacyRootDir, normalized.id);
|
||||
if (!fs.existsSync(journalPath) && fs.existsSync(legacyJournalPath)) {
|
||||
fs.copyFileSync(legacyJournalPath, journalPath);
|
||||
// The readable path just moved from legacy to primary; anything derived
|
||||
// against the old path describes a file this session no longer reads.
|
||||
derived.delete(normalized.id);
|
||||
}
|
||||
// Publisher/complete helpers can append from a separate process while
|
||||
// the server is alive. Rebuild here so sequence numbers and phase
|
||||
// fences never come from a stale in-memory cache.
|
||||
const prior = rebuildSnapshotFromJournal(getReadableJournalPath(normalized.id), normalized.id);
|
||||
const seq = prior.nextSeq;
|
||||
// Reuse the derived state when the journal has not changed under us, and
|
||||
// apply the new event on top of it. Correctness still comes from the
|
||||
// journal: any append from another process invalidates the entry above
|
||||
// and this replays before writing, so sequence numbers and phase fences
|
||||
// are never taken from a stale copy.
|
||||
const prior = readState(normalized.id);
|
||||
const entry = {
|
||||
seq,
|
||||
seq: prior.nextSeq,
|
||||
id: normalized.id,
|
||||
type: normalized.type,
|
||||
ts: new Date().toISOString(),
|
||||
event: normalized,
|
||||
};
|
||||
fs.appendFileSync(journalPath, JSON.stringify(entry) + '\n');
|
||||
const next = applyEvent(prior.snapshot, entry, prior.diagnostics);
|
||||
writeSnapshot(snapshotPath, next);
|
||||
const next = applyEvent(prior.snapshot, entry);
|
||||
persist(normalized.id, next, prior.nextSeq + 1);
|
||||
return next;
|
||||
},
|
||||
/**
|
||||
* True when a journal exists for the id in either root. appendEvent
|
||||
* CREATES a journal for any id it is handed, so callers that should only
|
||||
* ever touch existing sessions (browser checkpoints, mount acks) check
|
||||
* here first — otherwise a stale id from another project's browser
|
||||
* storage materializes a ghost session in this store.
|
||||
*/
|
||||
has(id) {
|
||||
if (!id || typeof id !== 'string') return false;
|
||||
return fs.existsSync(getJournalPath(rootDir, id))
|
||||
|| fs.existsSync(getJournalPath(legacyRootDir, id));
|
||||
},
|
||||
/**
|
||||
* Read-only. `live-status` and `live-resume` call this against a session a
|
||||
* running server owns; writing the snapshot file here made every read a
|
||||
* write and let a reader's replay of a half-written journal land on disk.
|
||||
* Snapshot files are written by appendEvent and by flush().
|
||||
*/
|
||||
getSnapshot(id = sessionId, opts = {}) {
|
||||
if (!id) throw new Error('session id required');
|
||||
const journalPath = getReadableJournalPath(id);
|
||||
const snapshotPath = getSnapshotPath(rootDir, id);
|
||||
const rebuilt = rebuildSnapshotFromJournal(journalPath, id);
|
||||
writeSnapshot(snapshotPath, rebuilt.snapshot);
|
||||
if (!opts.includeCompleted && COMPLETED_PHASES.has(rebuilt.snapshot.phase)) return null;
|
||||
return rebuilt.snapshot;
|
||||
const { snapshot } = readState(id);
|
||||
if (!opts.includeCompleted && COMPLETED_PHASES.has(snapshot.phase)) return null;
|
||||
return snapshot;
|
||||
},
|
||||
/**
|
||||
* Write the snapshot file for a session without appending an event. The
|
||||
* durable truth is the journal, so this only refreshes the read cache other
|
||||
* processes use; callers that need the state itself should use getSnapshot.
|
||||
*/
|
||||
flush(id = sessionId) {
|
||||
if (!id) throw new Error('session id required');
|
||||
const state = readState(id, { allowSnapshotFile: false });
|
||||
persist(id, state.snapshot, state.nextSeq);
|
||||
return state.snapshot;
|
||||
},
|
||||
listActiveSessions() {
|
||||
const ids = new Set();
|
||||
@@ -74,6 +162,9 @@ export function createLiveSessionStore({ cwd = process.cwd(), sessionId } = {})
|
||||
if (name.endsWith('.jsonl')) ids.add(name.slice(0, -'.jsonl'.length));
|
||||
}
|
||||
}
|
||||
// Each id goes through readState, so a session whose journal has not moved
|
||||
// since it was last derived costs a stat and nothing more. The server calls
|
||||
// this on every /status and on every SSE connect.
|
||||
return [...ids]
|
||||
.sort()
|
||||
.map((id) => this.getSnapshot(id))
|
||||
@@ -82,6 +173,39 @@ export function createLiveSessionStore({ cwd = process.cwd(), sessionId } = {})
|
||||
};
|
||||
}
|
||||
|
||||
function statOrNull(filePath) {
|
||||
try {
|
||||
return fs.statSync(filePath);
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Hydrate derived state from a snapshot file, but only when it provably
|
||||
* describes the journal as it stands right now. Anything short of an exact byte
|
||||
* match on an append-only file means events landed after the snapshot was
|
||||
* written, and the caller replays instead.
|
||||
*/
|
||||
function readSnapshotFile(snapshotPath, id, journalBytes) {
|
||||
let parsed;
|
||||
try {
|
||||
parsed = JSON.parse(fs.readFileSync(snapshotPath, 'utf-8'));
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
if (!parsed || typeof parsed !== 'object') return null;
|
||||
if (parsed[META_JOURNAL_BYTES] !== journalBytes) return null;
|
||||
if (!Number.isInteger(parsed[META_NEXT_SEQ])) return null;
|
||||
const nextSeq = parsed[META_NEXT_SEQ];
|
||||
delete parsed[META_JOURNAL_BYTES];
|
||||
delete parsed[META_NEXT_SEQ];
|
||||
// The journal owns identity; a snapshot file copied between session ids is
|
||||
// not a reason to answer with the wrong id.
|
||||
if (parsed.id !== id) return null;
|
||||
return { snapshot: { ...baseSnapshot(id), ...parsed }, nextSeq };
|
||||
}
|
||||
|
||||
function normalizeEvent(event, fallbackId) {
|
||||
if (!event || typeof event !== 'object') throw new Error('event object required');
|
||||
const id = event.id || fallbackId;
|
||||
@@ -127,11 +251,37 @@ function baseSnapshot(id) {
|
||||
generationCanceledAt: null,
|
||||
cancelReason: null,
|
||||
annotationArtifacts: [],
|
||||
// Render truth. `arrivedVariants` says what the agent published; these say
|
||||
// what the browser actually got on screen. They are kept alongside the
|
||||
// published counters rather than replacing them so older readers keep
|
||||
// working, but they are the only fields that answer "did the user ever see
|
||||
// a variant".
|
||||
mountedVariants: [],
|
||||
mountFailures: [],
|
||||
renderState: null,
|
||||
diagnostics: [],
|
||||
updatedAt: null,
|
||||
};
|
||||
}
|
||||
|
||||
// How many mount failures a session keeps. The card in the browser shows the
|
||||
// newest one; the agent needs enough history to spot a variant that fails
|
||||
// every republish, not the whole retry storm.
|
||||
const MOUNT_FAILURE_HISTORY = 5;
|
||||
|
||||
/**
|
||||
* `pending` = the agent published and nothing has acked yet, `mounted` = at
|
||||
* least one variant reached the DOM, `failed` = the browser reported failures
|
||||
* and nothing ever mounted. A single success outranks any number of failures:
|
||||
* the user is looking at something.
|
||||
*/
|
||||
function deriveRenderState(snapshot) {
|
||||
if (snapshot.mountedVariants.length > 0) return 'mounted';
|
||||
if (snapshot.mountFailures.length > 0) return 'failed';
|
||||
if (snapshot.generationCompletedAt) return 'pending';
|
||||
return null;
|
||||
}
|
||||
|
||||
function rebuildSnapshotFromJournal(journalPath, id) {
|
||||
let snapshot = baseSnapshot(id);
|
||||
const diagnostics = [];
|
||||
@@ -159,7 +309,7 @@ function rebuildSnapshotFromJournal(journalPath, id) {
|
||||
return { snapshot, diagnostics, nextSeq };
|
||||
}
|
||||
|
||||
function applyEvent(snapshot, entry, inheritedDiagnostics = []) {
|
||||
function applyEvent(snapshot, entry) {
|
||||
const event = entry.event || entry;
|
||||
const next = {
|
||||
...snapshot,
|
||||
@@ -168,14 +318,13 @@ function applyEvent(snapshot, entry, inheritedDiagnostics = []) {
|
||||
generationTimings: { ...(snapshot.generationTimings || {}) },
|
||||
variantPlan: snapshot.variantPlan || null,
|
||||
annotationArtifacts: [...(snapshot.annotationArtifacts || [])],
|
||||
mountedVariants: [...(snapshot.mountedVariants || [])],
|
||||
mountFailures: [...(snapshot.mountFailures || [])],
|
||||
renderState: snapshot.renderState ?? null,
|
||||
diagnostics: [...(snapshot.diagnostics || [])],
|
||||
updatedAt: entry.ts || new Date().toISOString(),
|
||||
};
|
||||
|
||||
if (inheritedDiagnostics.length && next.diagnostics.length === 0) {
|
||||
next.diagnostics = [...inheritedDiagnostics];
|
||||
}
|
||||
|
||||
switch (event.type) {
|
||||
case 'generate':
|
||||
next.phase = 'generate_requested';
|
||||
@@ -184,6 +333,11 @@ function applyEvent(snapshot, entry, inheritedDiagnostics = []) {
|
||||
next.pendingEventSeq = entry.seq ?? next.pendingEventSeq;
|
||||
next.pendingEvent = toPendingEvent(event);
|
||||
next.variantPlan = null;
|
||||
// A new cycle publishes new files: everything the browser told us about
|
||||
// the previous batch is now about modules that no longer exist.
|
||||
next.mountedVariants = [];
|
||||
next.mountFailures = [];
|
||||
next.renderState = null;
|
||||
if (event.screenshotPath) upsertArtifact(next.annotationArtifacts, { type: 'screenshot', path: event.screenshotPath });
|
||||
break;
|
||||
case 'variant_plan':
|
||||
@@ -238,7 +392,45 @@ function applyEvent(snapshot, entry, inheritedDiagnostics = []) {
|
||||
message: 'Accepted variant still has carbonize markers that must be folded into source CSS.',
|
||||
});
|
||||
}
|
||||
next.renderState = deriveRenderState(next);
|
||||
break;
|
||||
case 'variant_mounted': {
|
||||
const variant = Number(event.variant);
|
||||
if (!Number.isInteger(variant) || variant < 1) {
|
||||
next.diagnostics.push({ error: 'malformed_mount_ack', type: event.type, variant: event.variant ?? null });
|
||||
break;
|
||||
}
|
||||
if (!next.mountedVariants.includes(variant)) {
|
||||
next.mountedVariants = [...next.mountedVariants, variant].sort((a, b) => a - b);
|
||||
}
|
||||
next.renderState = deriveRenderState(next);
|
||||
break;
|
||||
}
|
||||
case 'variant_mount_failed': {
|
||||
const variant = Number(event.variant);
|
||||
if (!Number.isInteger(variant) || variant < 1) {
|
||||
next.diagnostics.push({ error: 'malformed_mount_ack', type: event.type, variant: event.variant ?? null });
|
||||
break;
|
||||
}
|
||||
next.mountFailures = [
|
||||
...next.mountFailures,
|
||||
{
|
||||
variant,
|
||||
url: typeof event.url === 'string' ? event.url : null,
|
||||
error: typeof event.error === 'string' ? event.error : null,
|
||||
at: event.at ?? (Date.parse(entry.ts || '') || Date.now()),
|
||||
},
|
||||
].slice(-MOUNT_FAILURE_HISTORY);
|
||||
next.renderState = deriveRenderState(next);
|
||||
// The failure needs an agent reply, so it must survive a helper
|
||||
// restart the same way a generate does. Never clobber a still-pending
|
||||
// generate: a progressive publish can fail an early mount while the
|
||||
// generate event itself is still leased.
|
||||
if (!next.pendingEvent) {
|
||||
next.pendingEvent = toPendingEvent(event);
|
||||
}
|
||||
break;
|
||||
}
|
||||
case 'checkpoint':
|
||||
if (next.generationCanceled || GENERATION_FENCED_PHASES.has(next.phase)) {
|
||||
next.diagnostics.push({ error: 'checkpoint_after_terminal_ignored', phase: event.phase ?? null, revision: event.revision ?? null });
|
||||
@@ -361,6 +553,11 @@ function upsertArtifact(artifacts, artifact) {
|
||||
}
|
||||
}
|
||||
|
||||
function writeSnapshot(snapshotPath, snapshot) {
|
||||
fs.writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2) + '\n');
|
||||
function writeSnapshot(snapshotPath, snapshot, meta) {
|
||||
const payload = {
|
||||
...snapshot,
|
||||
[META_JOURNAL_BYTES]: meta?.journalBytes ?? -1,
|
||||
[META_NEXT_SEQ]: meta?.nextSeq ?? 1,
|
||||
};
|
||||
fs.writeFileSync(snapshotPath, JSON.stringify(payload, null, 2) + '\n');
|
||||
}
|
||||
|
||||
@@ -0,0 +1,961 @@
|
||||
/**
|
||||
* AST-based Svelte scaffolding for live component previews.
|
||||
*
|
||||
* The scaffolder turns the selected block of a route's markup into a detached
|
||||
* preview component whose dynamic values arrive as props. The old
|
||||
* implementation matched `{...}` with a regex, which flattened control-flow
|
||||
* blocks ({#each}, {#if}) into scalar text props and shipped structurally
|
||||
* wrong previews. This module uses the app's own svelte compiler
|
||||
* (parse with modern: true) and replaces only expressions that are FREE,
|
||||
* i.e. reference identifiers not bound by an enclosing template scope:
|
||||
*
|
||||
* {#each stages as stage, i} stages -> collection prop (array)
|
||||
* <span>{stage.label}</span> bound -> left verbatim
|
||||
* {/each}
|
||||
* <p>{footerNote}</p> free -> text prop (string)
|
||||
*
|
||||
* Constructs that cannot work in a detached component (component tags whose
|
||||
* imports live in the route file, bind:/use: directives, await blocks,
|
||||
* render tags) mark the analysis unsupported; the caller falls back to
|
||||
* source-preview mode, which keeps the markup inside the route file where
|
||||
* those references still resolve. A wrong preview is worse than a plain one.
|
||||
*
|
||||
* The compiler is resolved from the APP's node_modules, never bundled: the
|
||||
* preview must be parsed by the same svelte version that will compile it.
|
||||
*/
|
||||
|
||||
import { createRequire } from 'node:module';
|
||||
import path from 'node:path';
|
||||
|
||||
const HANDLER_ATTR_RE = /^on[a-z]/;
|
||||
|
||||
/**
|
||||
* Resolve the app's svelte compiler synchronously (svelte 5 ships a CJS
|
||||
* compiler build, so createRequire works and the accept/scaffold pipeline
|
||||
* stays synchronous). Returns { parse, compile, VERSION } or null.
|
||||
*/
|
||||
export function loadSvelteCompiler(appRoot) {
|
||||
try {
|
||||
const req = createRequire(path.join(appRoot, 'package.json'));
|
||||
const mod = req('svelte/compiler');
|
||||
if (typeof mod.parse !== 'function') return null;
|
||||
const major = parseInt(String(mod.VERSION || '0'), 10);
|
||||
if (major < 5) return null; // detached mount() previews are svelte 5 only
|
||||
return { parse: mod.parse, compile: mod.compile, VERSION: mod.VERSION };
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// ESTree helpers
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Collect the root identifiers an ESTree expression reads. Walks generically;
|
||||
* skips non-computed member properties and non-computed/non-shorthand object
|
||||
* keys, which are names, not references.
|
||||
*/
|
||||
export function collectRootIdentifiers(node, out = new Set()) {
|
||||
if (!node || typeof node !== 'object') return out;
|
||||
if (Array.isArray(node)) {
|
||||
for (const item of node) collectRootIdentifiers(item, out);
|
||||
return out;
|
||||
}
|
||||
switch (node.type) {
|
||||
case 'Identifier':
|
||||
out.add(node.name);
|
||||
return out;
|
||||
case 'MemberExpression':
|
||||
collectRootIdentifiers(node.object, out);
|
||||
if (node.computed) collectRootIdentifiers(node.property, out);
|
||||
return out;
|
||||
case 'Property':
|
||||
if (node.computed) collectRootIdentifiers(node.key, out);
|
||||
collectRootIdentifiers(node.value, out);
|
||||
return out;
|
||||
case 'ArrowFunctionExpression':
|
||||
case 'FunctionExpression': {
|
||||
// Params shadow outer names inside the body.
|
||||
const bound = new Set();
|
||||
for (const param of node.params || []) collectPatternNames(param, bound);
|
||||
const inner = collectRootIdentifiers(node.body, new Set());
|
||||
for (const name of inner) if (!bound.has(name)) out.add(name);
|
||||
return out;
|
||||
}
|
||||
default: {
|
||||
for (const key of Object.keys(node)) {
|
||||
if (key === 'type' || key === 'start' || key === 'end' || key === 'loc' || key === 'range' || key === 'parent') continue;
|
||||
collectRootIdentifiers(node[key], out);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/** Collect names bound by a destructuring pattern (each contexts, const tags). */
|
||||
export function collectPatternNames(pattern, out = new Set()) {
|
||||
if (!pattern || typeof pattern !== 'object') return out;
|
||||
switch (pattern.type) {
|
||||
case 'Identifier':
|
||||
out.add(pattern.name);
|
||||
return out;
|
||||
case 'ObjectPattern':
|
||||
for (const prop of pattern.properties || []) {
|
||||
if (prop.type === 'RestElement') collectPatternNames(prop.argument, out);
|
||||
else collectPatternNames(prop.value, out);
|
||||
}
|
||||
return out;
|
||||
case 'ArrayPattern':
|
||||
for (const el of pattern.elements || []) if (el) collectPatternNames(el, out);
|
||||
return out;
|
||||
case 'AssignmentPattern':
|
||||
collectPatternNames(pattern.left, out);
|
||||
return out;
|
||||
case 'RestElement':
|
||||
collectPatternNames(pattern.argument, out);
|
||||
return out;
|
||||
default:
|
||||
return out;
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Template analysis
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
class Analysis {
|
||||
constructor(source) {
|
||||
this.source = source;
|
||||
this.replacements = []; // { start, end, prop } source ranges to swap
|
||||
this.contract = []; // [{ prop, expr, kind, ... }]
|
||||
this.byExpr = new Map(); // expr text -> contract entry
|
||||
this.usedNames = new Set();
|
||||
this.unsupported = null;
|
||||
}
|
||||
|
||||
fail(reason) {
|
||||
if (!this.unsupported) this.unsupported = reason;
|
||||
}
|
||||
|
||||
propFor(exprText, kind, extra = {}) {
|
||||
const existing = this.byExpr.get(exprText);
|
||||
if (existing) return existing;
|
||||
const base = derivePropName(exprText);
|
||||
let name = base;
|
||||
let n = 2;
|
||||
while (this.usedNames.has(name)) name = `${base}${n++}`;
|
||||
this.usedNames.add(name);
|
||||
const entry = { prop: name, expr: exprText, kind, ...extra };
|
||||
this.byExpr.set(exprText, entry);
|
||||
this.contract.push(entry);
|
||||
return entry;
|
||||
}
|
||||
}
|
||||
|
||||
// A derived prop name lands in `let { <name> } = $props()`; a reserved word
|
||||
// there is a syntax error the session only hits at import time.
|
||||
const RESERVED_PROP_NAMES = new Set([
|
||||
'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger',
|
||||
'default', 'delete', 'do', 'else', 'enum', 'export', 'extends', 'false',
|
||||
'finally', 'for', 'function', 'if', 'implements', 'import', 'in',
|
||||
'instanceof', 'interface', 'let', 'new', 'null', 'package', 'private',
|
||||
'protected', 'public', 'return', 'static', 'super', 'switch', 'this',
|
||||
'throw', 'true', 'try', 'typeof', 'undefined', 'var', 'void', 'while',
|
||||
'with', 'yield',
|
||||
]);
|
||||
|
||||
export function derivePropName(expr) {
|
||||
const tail = String(expr).match(/(?:\.|\[["']?)([A-Za-z_$][\w$]*)["']?\]?\s*$/);
|
||||
const candidate = (tail && tail[1])
|
||||
|| (String(expr).match(/^([A-Za-z_$][\w$]*)$/) || [])[1]
|
||||
|| 'value';
|
||||
return RESERVED_PROP_NAMES.has(candidate) ? `${candidate}Value` : candidate;
|
||||
}
|
||||
|
||||
function exprText(source, node) {
|
||||
return source.slice(node.start, node.end);
|
||||
}
|
||||
|
||||
// Identifiers that resolve in ANY module scope. They are neither hydratable
|
||||
// props nor evidence of route coupling, so they count as neither free nor
|
||||
// bound: `{Math.round(x)}` must not mint a prop named `round`, and
|
||||
// `{fmt(stage.label)}` must not pass as global-only.
|
||||
const GLOBAL_IDENTIFIERS = new Set([
|
||||
'Math', 'JSON', 'Date', 'Intl', 'Number', 'String', 'Boolean', 'Array',
|
||||
'Object', 'Map', 'Set', 'Promise', 'RegExp', 'NaN', 'Infinity', 'undefined',
|
||||
'isNaN', 'isFinite', 'parseInt', 'parseFloat', 'encodeURIComponent',
|
||||
'decodeURIComponent', 'console', 'window', 'document', 'navigator',
|
||||
'location', 'structuredClone', 'crypto',
|
||||
]);
|
||||
|
||||
function classifyRoots(node, scopes) {
|
||||
const roots = collectRootIdentifiers(node);
|
||||
let bound = 0;
|
||||
let free = 0;
|
||||
for (const name of roots) {
|
||||
if (GLOBAL_IDENTIFIERS.has(name)) continue;
|
||||
if (scopes.some((scope) => scope.has(name))) bound++;
|
||||
else free++;
|
||||
}
|
||||
return { bound, free };
|
||||
}
|
||||
|
||||
function isFree(node, scopes) {
|
||||
const { bound, free } = classifyRoots(node, scopes);
|
||||
return free > 0 && bound === 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* An expression mixing loop-bound and outer free identifiers (e.g.
|
||||
* `{fmt(stage.label)}` where `fmt` lives in the route script) can neither
|
||||
* become a prop (the bound part varies per item) nor survive detachment
|
||||
* verbatim (the free name is undeclared in the preview and throws at mount,
|
||||
* past the compile gate, because globals make it legal to the compiler).
|
||||
* Source-preview mode is the only correct home for it.
|
||||
*/
|
||||
function failOnMixedExpression(node, scopes, analysis, source) {
|
||||
const { bound, free } = classifyRoots(node, scopes);
|
||||
if (bound > 0 && free > 0) {
|
||||
analysis.fail(`expression mixing loop and outer identifiers ({${exprText(source, node).slice(0, 60)}}) requires source-preview mode`);
|
||||
return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Analyze a parsed template fragment. `scopes` is a stack of Sets of bound
|
||||
* names; the outermost call passes an empty stack.
|
||||
*/
|
||||
function analyzeFragment(fragment, analysis, scopes) {
|
||||
if (!fragment || !Array.isArray(fragment.nodes)) return;
|
||||
// ConstTag declarations bind for the whole fragment.
|
||||
const fragmentScope = new Set();
|
||||
const nextScopes = [...scopes, fragmentScope];
|
||||
for (const node of fragment.nodes) {
|
||||
if (node.type === 'ConstTag' && node.declaration) {
|
||||
for (const decl of node.declaration.declarations || []) {
|
||||
collectPatternNames(decl.id, fragmentScope);
|
||||
}
|
||||
}
|
||||
}
|
||||
for (const node of fragment.nodes) analyzeNode(node, analysis, nextScopes);
|
||||
}
|
||||
|
||||
function analyzeNode(node, analysis, scopes) {
|
||||
if (!node || analysis.unsupported) return;
|
||||
switch (node.type) {
|
||||
case 'Text':
|
||||
case 'Comment':
|
||||
return;
|
||||
case 'ExpressionTag': {
|
||||
if (failOnMixedExpression(node.expression, scopes, analysis, analysis.source)) return;
|
||||
if (isFree(node.expression, scopes)) {
|
||||
const text = exprText(analysis.source, node.expression);
|
||||
const entry = analysis.propFor(text, 'text');
|
||||
// node.start/end include the braces; keep them, swap the inside.
|
||||
analysis.replacements.push({ start: node.expression.start, end: node.expression.end, prop: entry.prop });
|
||||
}
|
||||
return;
|
||||
}
|
||||
case 'HtmlTag': {
|
||||
if (failOnMixedExpression(node.expression, scopes, analysis, analysis.source)) return;
|
||||
if (isFree(node.expression, scopes)) {
|
||||
const text = exprText(analysis.source, node.expression);
|
||||
const entry = analysis.propFor(text, 'raw');
|
||||
analysis.replacements.push({ start: node.expression.start, end: node.expression.end, prop: entry.prop });
|
||||
}
|
||||
return;
|
||||
}
|
||||
case 'ConstTag': {
|
||||
// Its expression may read free names; leave them: the declaration
|
||||
// travels with the markup and stays valid only if its inputs do.
|
||||
if (node.declaration) {
|
||||
for (const decl of node.declaration.declarations || []) {
|
||||
if (decl.init && failOnMixedExpression(decl.init, scopes, analysis, analysis.source)) return;
|
||||
if (decl.init && isFree(decl.init, scopes)) {
|
||||
const text = exprText(analysis.source, decl.init);
|
||||
const entry = analysis.propFor(text, 'text');
|
||||
analysis.replacements.push({ start: decl.init.start, end: decl.init.end, prop: entry.prop });
|
||||
}
|
||||
}
|
||||
}
|
||||
return;
|
||||
}
|
||||
case 'EachBlock': {
|
||||
if (failOnMixedExpression(node.expression, scopes, analysis, analysis.source)) return;
|
||||
if (isFree(node.expression, scopes)) {
|
||||
const text = exprText(analysis.source, node.expression);
|
||||
const item = describeEachItem(node, analysis.source);
|
||||
// Keyed each: the key must evaluate to a distinct value per hydrated
|
||||
// item or Svelte throws each_key_duplicate at mount. A key that is a
|
||||
// plain member of the item (the common `(item.id)` shape) gets a
|
||||
// synthetic per-index value injected by the browser (keyField).
|
||||
// Anything else cannot be hydrated safely; source-preview mode keeps
|
||||
// it correct.
|
||||
if (node.key) {
|
||||
const keyInfo = classifyEachKey(node);
|
||||
if (keyInfo.unsupported) {
|
||||
analysis.fail(keyInfo.unsupported);
|
||||
return;
|
||||
}
|
||||
if (keyInfo.keyField) {
|
||||
if (item.textSlots.some((slot) => slot.key === keyInfo.keyField)) {
|
||||
// The key doubles as a displayed slot; a synthetic value would
|
||||
// change visible text, and the displayed text may not be
|
||||
// unique. Not previewable in a detached component.
|
||||
analysis.fail('each key that is also a displayed field requires source-preview mode');
|
||||
return;
|
||||
}
|
||||
item.keyField = keyInfo.keyField;
|
||||
}
|
||||
}
|
||||
const entry = analysis.propFor(text, 'collection', { item });
|
||||
analysis.replacements.push({ start: node.expression.start, end: node.expression.end, prop: entry.prop });
|
||||
}
|
||||
const bound = new Set();
|
||||
if (node.context) collectPatternNames(node.context, bound);
|
||||
if (node.index) bound.add(node.index);
|
||||
analyzeFragment(node.body, analysis, [...scopes, bound]);
|
||||
if (node.fallback) analyzeFragment(node.fallback, analysis, scopes);
|
||||
return;
|
||||
}
|
||||
case 'IfBlock': {
|
||||
if (failOnMixedExpression(node.test, scopes, analysis, analysis.source)) return;
|
||||
if (isFree(node.test, scopes)) {
|
||||
const text = exprText(analysis.source, node.test);
|
||||
// The browser hydrates a free condition from what the live page
|
||||
// currently shows: when the consequent's root element is present
|
||||
// under the picked element, the condition is on.
|
||||
const entry = analysis.propFor(text, 'condition', {
|
||||
probe: describeElementProbe(node.consequent),
|
||||
});
|
||||
analysis.replacements.push({ start: node.test.start, end: node.test.end, prop: entry.prop });
|
||||
}
|
||||
analyzeFragment(node.consequent, analysis, scopes);
|
||||
if (node.alternate) analyzeFragment(node.alternate, analysis, scopes);
|
||||
return;
|
||||
}
|
||||
case 'KeyBlock': {
|
||||
if (failOnMixedExpression(node.expression, scopes, analysis, analysis.source)) return;
|
||||
if (isFree(node.expression, scopes)) {
|
||||
const text = exprText(analysis.source, node.expression);
|
||||
const entry = analysis.propFor(text, 'text');
|
||||
analysis.replacements.push({ start: node.expression.start, end: node.expression.end, prop: entry.prop });
|
||||
}
|
||||
analyzeFragment(node.fragment, analysis, scopes);
|
||||
return;
|
||||
}
|
||||
case 'SnippetBlock': {
|
||||
const bound = new Set();
|
||||
for (const param of node.parameters || []) collectPatternNames(param, bound);
|
||||
// The snippet's own name becomes available to render tags in this file.
|
||||
analyzeFragment(node.body, analysis, [...scopes, bound]);
|
||||
return;
|
||||
}
|
||||
case 'RegularElement':
|
||||
case 'SlotElement':
|
||||
case 'TitleElement': {
|
||||
if (node.name === 'script') {
|
||||
// An inline script inside the selected block carries route-scoped
|
||||
// code; running it a second time from a detached preview is wrong.
|
||||
analysis.fail('inline script element requires source-preview mode');
|
||||
return;
|
||||
}
|
||||
analyzeAttributes(node, analysis, scopes);
|
||||
if (!analysis.unsupported) analyzeFragment(node.fragment, analysis, scopes);
|
||||
return;
|
||||
}
|
||||
case 'SvelteElement':
|
||||
case 'SvelteFragment':
|
||||
case 'SvelteBoundary': {
|
||||
analyzeAttributes(node, analysis, scopes);
|
||||
if (!analysis.unsupported) analyzeFragment(node.fragment, analysis, scopes);
|
||||
return;
|
||||
}
|
||||
case 'Component':
|
||||
case 'SvelteComponent':
|
||||
case 'SvelteSelf':
|
||||
// The component's import lives in the route file; a detached preview
|
||||
// cannot resolve it. Source-preview mode keeps it working.
|
||||
analysis.fail(`component tag <${node.name || 'Component'}> requires source-preview mode`);
|
||||
return;
|
||||
case 'RenderTag':
|
||||
analysis.fail('render tag requires source-preview mode');
|
||||
return;
|
||||
case 'AwaitBlock':
|
||||
analysis.fail('await block requires source-preview mode');
|
||||
return;
|
||||
case 'SvelteHead':
|
||||
case 'SvelteWindow':
|
||||
case 'SvelteDocument':
|
||||
case 'SvelteBody':
|
||||
analysis.fail(`${node.type} requires source-preview mode`);
|
||||
return;
|
||||
default: {
|
||||
if (node.fragment) analyzeFragment(node.fragment, analysis, scopes);
|
||||
return;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
function analyzeAttributes(node, analysis, scopes) {
|
||||
for (const attr of node.attributes || []) {
|
||||
switch (attr.type) {
|
||||
case 'Attribute': {
|
||||
if (attr.value === true) break;
|
||||
const parts = Array.isArray(attr.value) ? attr.value : [attr.value];
|
||||
for (const part of parts) {
|
||||
if (!part || part.type !== 'ExpressionTag') continue;
|
||||
if (failOnMixedExpression(part.expression, scopes, analysis, analysis.source)) return;
|
||||
if (!isFree(part.expression, scopes)) continue;
|
||||
const text = exprText(analysis.source, part.expression);
|
||||
const kind = HANDLER_ATTR_RE.test(attr.name) ? 'handler' : 'text';
|
||||
const entry = analysis.propFor(text, kind);
|
||||
analysis.replacements.push({ start: part.expression.start, end: part.expression.end, prop: entry.prop });
|
||||
}
|
||||
break;
|
||||
}
|
||||
case 'ClassDirective': {
|
||||
const expr = attr.expression;
|
||||
if (expr && failOnMixedExpression(expr, scopes, analysis, analysis.source)) return;
|
||||
if (expr && isFree(expr, scopes)) {
|
||||
const text = exprText(analysis.source, expr);
|
||||
// The directive's class name is literal, so the live DOM answers
|
||||
// the condition directly: the class is either present or not.
|
||||
const entry = analysis.propFor(text, 'condition', {
|
||||
probe: { className: attr.name },
|
||||
});
|
||||
analysis.replacements.push({ start: expr.start, end: expr.end, prop: entry.prop });
|
||||
}
|
||||
break;
|
||||
}
|
||||
case 'StyleDirective': {
|
||||
// Unlike ClassDirective, a style directive stores its value in
|
||||
// attribute shape: `true` for the shorthand, else an array of parts.
|
||||
const parts = attr.value === true ? [] : (Array.isArray(attr.value) ? attr.value : [attr.value]);
|
||||
for (const part of parts) {
|
||||
if (part?.type === 'ExpressionTag'
|
||||
&& failOnMixedExpression(part.expression, scopes, analysis, analysis.source)) {
|
||||
return;
|
||||
}
|
||||
}
|
||||
const dynamic = parts.some((part) => part?.type === 'ExpressionTag' && isFree(part.expression, scopes));
|
||||
const shorthandFree = attr.value === true && isFree({ type: 'Identifier', name: attr.name }, scopes);
|
||||
if (dynamic || shorthandFree) {
|
||||
// style:opacity={x} carries a css VALUE, not a boolean, and the
|
||||
// computed value on the live element is not reliably recoverable in
|
||||
// the shape the expression produced. A falsified style is worse
|
||||
// than an HMR-resetting preview.
|
||||
analysis.fail(`style:${attr.name} with a dynamic value requires source-preview mode`);
|
||||
}
|
||||
break;
|
||||
}
|
||||
case 'BindDirective':
|
||||
analysis.fail(`bind:${attr.name} requires source-preview mode`);
|
||||
return;
|
||||
case 'UseDirective':
|
||||
analysis.fail(`use:${attr.name} requires source-preview mode`);
|
||||
return;
|
||||
case 'AnimateDirective':
|
||||
case 'TransitionDirective':
|
||||
// Motion directives reference route-scoped or svelte/transition
|
||||
// imports; a detached preview cannot resolve them.
|
||||
analysis.fail(`${attr.type} requires source-preview mode`);
|
||||
return;
|
||||
case 'OnDirective': {
|
||||
// Legacy on:click syntax; treat like handler attributes.
|
||||
const expr = attr.expression;
|
||||
if (expr && failOnMixedExpression(expr, scopes, analysis, analysis.source)) return;
|
||||
if (expr && isFree(expr, scopes)) {
|
||||
const text = exprText(analysis.source, expr);
|
||||
const entry = analysis.propFor(text, 'handler');
|
||||
analysis.replacements.push({ start: expr.start, end: expr.end, prop: entry.prop });
|
||||
}
|
||||
break;
|
||||
}
|
||||
case 'SpreadAttribute':
|
||||
analysis.fail('spread attribute requires source-preview mode');
|
||||
return;
|
||||
default:
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Describe the repeating item of an each block for browser-side hydration:
|
||||
* the item's root element (tag + static classes, used to count live
|
||||
* iterations) and the ordered text slots that reference loop bindings.
|
||||
*/
|
||||
function describeEachItem(node, source) {
|
||||
const body = node.body;
|
||||
const rootEl = (body?.nodes || []).find((n) => n.type === 'RegularElement');
|
||||
|
||||
const textSlots = [];
|
||||
const staticTexts = [];
|
||||
let nestedUnsupported = false;
|
||||
const collectStatics = (fragment) => {
|
||||
for (const child of fragment?.nodes || []) {
|
||||
if (child.type === 'Text') {
|
||||
const trimmed = String(child.data || '').trim();
|
||||
if (trimmed) staticTexts.push(trimmed);
|
||||
} else if (child.type === 'IfBlock') {
|
||||
collectStatics(child.consequent);
|
||||
if (child.alternate) collectStatics(child.alternate);
|
||||
} else if (child.type === 'EachBlock') {
|
||||
collectStatics(child.body);
|
||||
} else if (child.fragment) {
|
||||
collectStatics(child.fragment);
|
||||
}
|
||||
}
|
||||
};
|
||||
collectStatics(body);
|
||||
const attrSlots = [];
|
||||
// The hydration item is a SHALLOW object whose string fields are the exact
|
||||
// property names the markup accesses, filled from the rendered page. That
|
||||
// model supports one item access per slot, optionally wrapped in a global
|
||||
// transform ({Math.round(r.score)} hydrates `score`). Shapes it cannot
|
||||
// represent split two ways: CRASHY ones would throw at mount time against a
|
||||
// shallow item (deep paths like r.meta.label, method calls like r.format())
|
||||
// and force the source-preview fallback; LOSSY ones render wrong but safe
|
||||
// (bare {r}, multi-access expressions that would double their text) and
|
||||
// also fall back in text position, where the damage is visible.
|
||||
const boundAs = (name, scopeInfos) => {
|
||||
for (let i = scopeInfos.length - 1; i >= 0; i--) {
|
||||
const info = scopeInfos[i];
|
||||
if (info.indexName === name) return 'index';
|
||||
if (info.itemName === name) return 'item';
|
||||
if (info.names.has(name)) return 'field';
|
||||
}
|
||||
return null;
|
||||
};
|
||||
const slotKeysOf = (expression, scopeInfos) => {
|
||||
const keys = new Set();
|
||||
let crashy = false;
|
||||
let lossy = false;
|
||||
let touches = false;
|
||||
const visit = (node, ctx) => {
|
||||
if (!node || typeof node !== 'object' || crashy) return;
|
||||
if (Array.isArray(node)) {
|
||||
for (const item of node) visit(item, {});
|
||||
return;
|
||||
}
|
||||
switch (node.type) {
|
||||
case 'Identifier': {
|
||||
const kind = boundAs(node.name, scopeInfos);
|
||||
if (!kind) return;
|
||||
touches = true;
|
||||
if (kind === 'index') return; // the runtime each provides it
|
||||
if (kind === 'item') { lossy = true; return; } // bare item reference
|
||||
if (ctx.callee) { crashy = true; return; } // field() on a hydrated string
|
||||
keys.add(node.name); // destructured context field
|
||||
return;
|
||||
}
|
||||
case 'MemberExpression': {
|
||||
if (
|
||||
!node.computed
|
||||
&& node.object?.type === 'Identifier'
|
||||
&& boundAs(node.object.name, scopeInfos) === 'item'
|
||||
&& node.property?.type === 'Identifier'
|
||||
) {
|
||||
touches = true;
|
||||
// item.a.b or item.method(): a shallow string field throws here.
|
||||
if (ctx.memberObject || ctx.callee) { crashy = true; return; }
|
||||
keys.add(node.property.name);
|
||||
return;
|
||||
}
|
||||
visit(node.object, { memberObject: true });
|
||||
if (node.computed) visit(node.property, {});
|
||||
return;
|
||||
}
|
||||
case 'CallExpression':
|
||||
visit(node.callee, { callee: true });
|
||||
for (const arg of node.arguments || []) visit(arg, {});
|
||||
return;
|
||||
case 'ArrowFunctionExpression':
|
||||
case 'FunctionExpression': {
|
||||
// Closures cannot hydrate; only lossy when they capture the item.
|
||||
const roots = collectRootIdentifiers(node);
|
||||
if ([...roots].some((name) => boundAs(name, scopeInfos))) { touches = true; lossy = true; }
|
||||
return;
|
||||
}
|
||||
case 'Property':
|
||||
if (node.computed) visit(node.key, {});
|
||||
visit(node.value, {});
|
||||
return;
|
||||
default: {
|
||||
for (const key of Object.keys(node)) {
|
||||
if (key === 'type' || key === 'start' || key === 'end' || key === 'loc' || key === 'range' || key === 'parent') continue;
|
||||
visit(node[key], {});
|
||||
}
|
||||
}
|
||||
}
|
||||
};
|
||||
visit(expression, {});
|
||||
if (crashy) return { crashy: true };
|
||||
if (lossy || keys.size > 1) return { lossy: true };
|
||||
if (!touches || keys.size === 0) return { skip: true };
|
||||
return { key: [...keys][0] };
|
||||
};
|
||||
const staticClassesOf = (el) => {
|
||||
const classes = [];
|
||||
for (const attr of el?.attributes || []) {
|
||||
if (attr.type === 'Attribute' && attr.name === 'class' && Array.isArray(attr.value)) {
|
||||
for (const part of attr.value) {
|
||||
if (part.type === 'Text') classes.push(...part.data.split(/\s+/).filter(Boolean));
|
||||
}
|
||||
}
|
||||
}
|
||||
return classes;
|
||||
};
|
||||
const scopeInfoOf = (eachNode) => {
|
||||
const names = new Set();
|
||||
if (eachNode.context) collectPatternNames(eachNode.context, names);
|
||||
return {
|
||||
names,
|
||||
itemName: eachNode.context?.type === 'Identifier' ? eachNode.context.name : null,
|
||||
indexName: eachNode.index || null,
|
||||
};
|
||||
};
|
||||
const walkForSlots = (fragment, scopeInfos) => {
|
||||
for (const child of fragment?.nodes || []) {
|
||||
if (child.type === 'ExpressionTag') {
|
||||
const slot = slotKeysOf(child.expression, scopeInfos);
|
||||
if (slot.crashy || slot.lossy) { nestedUnsupported = true; continue; }
|
||||
if (slot.skip) continue;
|
||||
textSlots.push({ key: slot.key, expr: exprText(source, child.expression) });
|
||||
} else if (child.type === 'RegularElement' || child.type === 'SvelteElement') {
|
||||
// Bound values in ATTRIBUTES (href={link.href}, src={item.img}) are
|
||||
// part of the item too: the browser reads the rendered attribute off
|
||||
// the live element, so the preview does not mount with empty links.
|
||||
// Only a single-expression attribute hydrates exactly; a mixed value
|
||||
// ("card {r.status}") stays unhydrated because the rendered attribute
|
||||
// is not separable into its parts, which was the prior behavior.
|
||||
for (const attr of child.attributes || []) {
|
||||
if (attr.type !== 'Attribute' || attr.value === true) continue;
|
||||
if (HANDLER_ATTR_RE.test(attr.name)) continue; // functions cannot hydrate
|
||||
const parts = Array.isArray(attr.value) ? attr.value : [attr.value];
|
||||
const exprParts = parts.filter((part) => part?.type === 'ExpressionTag');
|
||||
for (const part of exprParts) {
|
||||
const slot = slotKeysOf(part.expression, scopeInfos);
|
||||
if (slot.crashy) { nestedUnsupported = true; continue; }
|
||||
if (slot.skip || slot.lossy) continue;
|
||||
if (parts.length !== 1) continue; // mixed static+dynamic value
|
||||
attrSlots.push({
|
||||
key: slot.key,
|
||||
expr: exprText(source, part.expression),
|
||||
attr: attr.name,
|
||||
tag: child.name || null,
|
||||
classes: staticClassesOf(child),
|
||||
});
|
||||
}
|
||||
}
|
||||
walkForSlots(child.fragment, scopeInfos);
|
||||
continue;
|
||||
} else if (child.type === 'EachBlock') {
|
||||
const roots = collectRootIdentifiers(child.expression);
|
||||
const boundNested = [...roots].some((name) => boundAs(name, scopeInfos));
|
||||
if (boundNested) nestedUnsupported = true; // nested per-item arrays: no hydration plan yet
|
||||
walkForSlots(child.body, [...scopeInfos, scopeInfoOf(child)]);
|
||||
} else if (child.type === 'IfBlock') {
|
||||
walkForSlots(child.consequent, scopeInfos);
|
||||
if (child.alternate) walkForSlots(child.alternate, scopeInfos);
|
||||
} else if (child.fragment) {
|
||||
walkForSlots(child.fragment, scopeInfos);
|
||||
}
|
||||
}
|
||||
};
|
||||
walkForSlots(body, [scopeInfoOf(node)]);
|
||||
|
||||
const staticClasses = [];
|
||||
for (const attr of rootEl?.attributes || []) {
|
||||
if (attr.type === 'Attribute' && attr.name === 'class' && Array.isArray(attr.value)) {
|
||||
for (const part of attr.value) {
|
||||
if (part.type === 'Text') staticClasses.push(...part.data.split(/\s+/).filter(Boolean));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
rootTag: rootEl?.name || null,
|
||||
rootClasses: staticClasses,
|
||||
textSlots,
|
||||
attrSlots,
|
||||
staticTexts,
|
||||
nestedUnsupported,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Classify a keyed each block's key expression:
|
||||
* { keyField } member of the loop item (e.g. `(expense.id)` when the
|
||||
* context binds `expense`): browser injects a unique
|
||||
* per-index value under that field.
|
||||
* {} key is the whole loop item or the index: already
|
||||
* distinct per iteration, nothing to inject.
|
||||
* { unsupported } free or complex keys: cannot hydrate distinct values.
|
||||
*/
|
||||
function classifyEachKey(node) {
|
||||
const bound = new Set();
|
||||
if (node.context) collectPatternNames(node.context, bound);
|
||||
if (node.index) bound.add(node.index);
|
||||
const key = node.key;
|
||||
const roots = collectRootIdentifiers(key);
|
||||
const usesLoopBinding = [...roots].some((name) => bound.has(name));
|
||||
if (!usesLoopBinding) {
|
||||
// A key that ignores the loop item is constant across iterations:
|
||||
// guaranteed duplicate keys at mount.
|
||||
return { unsupported: 'each key not derived from the loop item requires source-preview mode' };
|
||||
}
|
||||
if (key.type === 'Identifier' && bound.has(key.name)) return {};
|
||||
if (
|
||||
key.type === 'MemberExpression'
|
||||
&& !key.computed
|
||||
&& key.object?.type === 'Identifier'
|
||||
&& bound.has(key.object.name)
|
||||
&& key.property?.type === 'Identifier'
|
||||
) {
|
||||
return { keyField: key.property.name };
|
||||
}
|
||||
return { unsupported: 'complex each key requires source-preview mode' };
|
||||
}
|
||||
|
||||
/**
|
||||
* Describe a fragment's root element for browser presence probing:
|
||||
* { tag, classes } of the first RegularElement, or null for text-only
|
||||
* fragments (which cannot be probed reliably).
|
||||
*/
|
||||
function describeElementProbe(fragment) {
|
||||
const rootEl = (fragment?.nodes || []).find((n) => n.type === 'RegularElement');
|
||||
if (!rootEl) return null;
|
||||
const classes = [];
|
||||
for (const attr of rootEl.attributes || []) {
|
||||
if (attr.type === 'Attribute' && attr.name === 'class' && Array.isArray(attr.value)) {
|
||||
for (const part of attr.value) {
|
||||
if (part.type === 'Text') classes.push(...part.data.split(/\s+/).filter(Boolean));
|
||||
}
|
||||
}
|
||||
}
|
||||
return { tag: rootEl.name, classes };
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public API
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Analyze a markup block and produce the prop-substituted scaffold markup and
|
||||
* the v2 prop contract. Returns { ok: false, reason } when the block needs
|
||||
* source-preview mode (parse failure or unsupported construct).
|
||||
*/
|
||||
export function analyzeSvelteMarkup(markup, parse) {
|
||||
const source = String(markup || '');
|
||||
let ast;
|
||||
try {
|
||||
ast = parse(source, { modern: true });
|
||||
} catch (err) {
|
||||
return { ok: false, reason: `svelte parse failed: ${err.message}` };
|
||||
}
|
||||
if (ast.instance || ast.module) {
|
||||
return { ok: false, reason: 'selected block contains a script tag' };
|
||||
}
|
||||
const analysis = new Analysis(source);
|
||||
analyzeFragment(ast.fragment, analysis, []);
|
||||
if (analysis.unsupported) {
|
||||
return { ok: false, reason: analysis.unsupported };
|
||||
}
|
||||
for (const entry of analysis.contract) {
|
||||
if (entry.kind === 'collection' && entry.item?.nestedUnsupported) {
|
||||
return { ok: false, reason: 'per-item content (nested blocks or expressions) this preview cannot hydrate requires source-preview mode' };
|
||||
}
|
||||
}
|
||||
|
||||
const markupWithProps = applyReplacements(source, analysis.replacements);
|
||||
return {
|
||||
ok: true,
|
||||
markupWithProps,
|
||||
contract: analysis.contract.map((entry) => ({
|
||||
prop: entry.prop,
|
||||
expr: entry.expr,
|
||||
kind: entry.kind,
|
||||
// Kept for backward compatibility with v1 consumers (fake e2e agent,
|
||||
// text-only restore paths).
|
||||
placeholder: `{${entry.expr}}`,
|
||||
...(entry.item ? { item: entry.item } : {}),
|
||||
...(entry.probe ? { probe: entry.probe } : {}),
|
||||
})),
|
||||
};
|
||||
}
|
||||
|
||||
function applyReplacements(source, replacements) {
|
||||
const sorted = [...replacements].sort((a, b) => b.start - a.start);
|
||||
let out = source;
|
||||
for (const { start, end, prop } of sorted) {
|
||||
out = out.slice(0, start) + prop + out.slice(end);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
/**
|
||||
* Restore a variant's markup back to route-source form: every free
|
||||
* identifier that matches a contract prop is replaced by its original
|
||||
* expression. AST-based so `{#each stages as stage}` restores to
|
||||
* `{#each data.stages as stage}` even though the prop appears without braces.
|
||||
*/
|
||||
export function restoreSvelteMarkup(markup, contract, parse) {
|
||||
const source = String(markup || '');
|
||||
const byProp = new Map();
|
||||
for (const entry of contract || []) byProp.set(entry.prop, entry.expr);
|
||||
if (byProp.size === 0) return { ok: true, markup: source };
|
||||
|
||||
let ast;
|
||||
try {
|
||||
ast = parse(source, { modern: true });
|
||||
} catch (err) {
|
||||
return { ok: false, reason: `variant parse failed: ${err.message}` };
|
||||
}
|
||||
|
||||
const replacements = [];
|
||||
const visitExpr = (expression, scopes) => {
|
||||
if (!expression) return;
|
||||
collectFreeIdentifierRanges(expression, scopes, (name, start, end) => {
|
||||
const original = byProp.get(name);
|
||||
if (original != null && original !== name) replacements.push({ start, end, prop: original });
|
||||
});
|
||||
};
|
||||
|
||||
const walk = (fragment, scopes) => {
|
||||
const fragmentScope = new Set();
|
||||
const nextScopes = [...scopes, fragmentScope];
|
||||
for (const node of fragment?.nodes || []) {
|
||||
if (node.type === 'ConstTag' && node.declaration) {
|
||||
for (const decl of node.declaration.declarations || []) collectPatternNames(decl.id, fragmentScope);
|
||||
}
|
||||
}
|
||||
for (const node of fragment?.nodes || []) {
|
||||
switch (node?.type) {
|
||||
case 'ExpressionTag':
|
||||
case 'HtmlTag':
|
||||
visitExpr(node.expression, nextScopes);
|
||||
break;
|
||||
case 'ConstTag':
|
||||
for (const decl of node.declaration?.declarations || []) visitExpr(decl.init, nextScopes);
|
||||
break;
|
||||
case 'EachBlock': {
|
||||
visitExpr(node.expression, nextScopes);
|
||||
const bound = new Set();
|
||||
if (node.context) collectPatternNames(node.context, bound);
|
||||
if (node.index) bound.add(node.index);
|
||||
// The key evaluates per item, so the loop context and index are in
|
||||
// scope there. Visiting it with outer scopes only let a contract
|
||||
// prop that shares a loop binding's name rewrite the key.
|
||||
if (node.key) visitExpr(node.key, [...nextScopes, bound]);
|
||||
walk(node.body, [...nextScopes, bound]);
|
||||
if (node.fallback) walk(node.fallback, nextScopes);
|
||||
break;
|
||||
}
|
||||
case 'IfBlock':
|
||||
visitExpr(node.test, nextScopes);
|
||||
walk(node.consequent, nextScopes);
|
||||
if (node.alternate) walk(node.alternate, nextScopes);
|
||||
break;
|
||||
case 'KeyBlock':
|
||||
visitExpr(node.expression, nextScopes);
|
||||
walk(node.fragment, nextScopes);
|
||||
break;
|
||||
case 'SnippetBlock': {
|
||||
const bound = new Set();
|
||||
for (const param of node.parameters || []) collectPatternNames(param, bound);
|
||||
walk(node.body, [...nextScopes, bound]);
|
||||
break;
|
||||
}
|
||||
default: {
|
||||
for (const attr of node?.attributes || []) {
|
||||
if (attr.type === 'Attribute' && Array.isArray(attr.value)) {
|
||||
for (const part of attr.value) {
|
||||
if (part?.type === 'ExpressionTag') visitExpr(part.expression, nextScopes);
|
||||
}
|
||||
} else if (attr.expression) {
|
||||
visitExpr(attr.expression, nextScopes);
|
||||
}
|
||||
}
|
||||
if (node?.fragment) walk(node.fragment, nextScopes);
|
||||
}
|
||||
}
|
||||
}
|
||||
};
|
||||
walk(ast.fragment, []);
|
||||
|
||||
return { ok: true, markup: applyReplacements(source, replacements) };
|
||||
}
|
||||
|
||||
/**
|
||||
* Report [name, start, end] for every free root identifier READ in an
|
||||
* expression (skips member properties, object keys, shadowed names).
|
||||
*/
|
||||
function collectFreeIdentifierRanges(node, scopes, emit) {
|
||||
const visit = (n, localBound) => {
|
||||
if (!n || typeof n !== 'object') return;
|
||||
if (Array.isArray(n)) { for (const item of n) visit(item, localBound); return; }
|
||||
switch (n.type) {
|
||||
case 'Identifier': {
|
||||
const bound = localBound.has(n.name) || scopes.some((s) => s.has(n.name));
|
||||
if (!bound) emit(n.name, n.start, n.end);
|
||||
return;
|
||||
}
|
||||
case 'MemberExpression':
|
||||
visit(n.object, localBound);
|
||||
if (n.computed) visit(n.property, localBound);
|
||||
return;
|
||||
case 'Property':
|
||||
if (n.computed) visit(n.key, localBound);
|
||||
visit(n.value, localBound);
|
||||
return;
|
||||
case 'ArrowFunctionExpression':
|
||||
case 'FunctionExpression': {
|
||||
const inner = new Set(localBound);
|
||||
for (const param of n.params || []) collectPatternNames(param, inner);
|
||||
visit(n.body, inner);
|
||||
return;
|
||||
}
|
||||
default:
|
||||
for (const key of Object.keys(n)) {
|
||||
if (key === 'type' || key === 'start' || key === 'end' || key === 'loc' || key === 'range' || key === 'parent') continue;
|
||||
visit(n[key], localBound);
|
||||
}
|
||||
}
|
||||
};
|
||||
visit(node, new Set());
|
||||
}
|
||||
|
||||
/**
|
||||
* Build the preview component's script block from a v2 contract, with
|
||||
* defaults that keep an unhydrated mount rendering instead of crashing.
|
||||
*/
|
||||
export function buildPropsScriptV2(contract) {
|
||||
if (!contract || contract.length === 0) {
|
||||
return '<script>\n /** @type {Record<string, never>} */\n let {} = $props();\n</script>\n';
|
||||
}
|
||||
const defaults = {
|
||||
text: "''",
|
||||
raw: "''",
|
||||
condition: 'false',
|
||||
collection: '[]',
|
||||
handler: '() => {}',
|
||||
};
|
||||
const types = {
|
||||
text: 'string',
|
||||
raw: 'string',
|
||||
condition: 'boolean',
|
||||
collection: 'Array<Record<string, unknown>>',
|
||||
handler: '() => void',
|
||||
};
|
||||
const names = contract
|
||||
.map((c) => `${c.prop} = ${defaults[c.kind] ?? "''"}`)
|
||||
.join(', ');
|
||||
const typeFields = contract
|
||||
.map((c) => ` ${c.prop}?: ${types[c.kind] ?? 'string'};`)
|
||||
.join('\n');
|
||||
return `<script>\n /** @type {{\n${typeFields}\n }} */\n let { ${names} } = $props();\n</script>\n`;
|
||||
}
|
||||
@@ -10,9 +10,38 @@ import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import os from 'node:os';
|
||||
import { createHash } from 'node:crypto';
|
||||
import {
|
||||
analyzeSvelteMarkup,
|
||||
buildPropsScriptV2,
|
||||
loadSvelteCompiler,
|
||||
restoreSvelteMarkup,
|
||||
} from './svelte-ast.mjs';
|
||||
import {
|
||||
bakeParamValues,
|
||||
collectAllSelectors,
|
||||
collectUnusedSelectors,
|
||||
normalizeSelector,
|
||||
parseStylesheet,
|
||||
pruneUnusedSelectors,
|
||||
reconcileCss,
|
||||
serializeNodes,
|
||||
splitSelectorList,
|
||||
} from './accept-css.mjs';
|
||||
import { verifyAcceptedSource } from './accept-verify.mjs';
|
||||
|
||||
// Preview modules stay under node_modules on purpose: SvelteKit restricts
|
||||
// vite's server.fs.allow to src/lib, src/routes, .svelte-kit, and
|
||||
// node_modules, so an .impeccable/ tree under the app root 403s (verified
|
||||
// against a real SvelteKit dev server). Staleness from node_modules being
|
||||
// unwatched is solved by REVISIONED module paths instead: every publish
|
||||
// snapshots the variant files into a fresh r<N>/ directory and the browser
|
||||
// imports from there, so a republished fix can never be pinned by a
|
||||
// transform cache keyed on the old path.
|
||||
export const SVELTE_COMPONENT_ROOT = 'node_modules/.impeccable-live';
|
||||
// A short-lived interim location; swept so no project keeps a stray tree.
|
||||
export const LEGACY_SVELTE_COMPONENT_ROOT = '.impeccable/live/previews';
|
||||
export const SVELTE_RUNTIME_FILE = `${SVELTE_COMPONENT_ROOT}/__runtime.js`;
|
||||
export const SVELTE_PROBE_FILE = `${SVELTE_COMPONENT_ROOT}/__probe.js`;
|
||||
export const DEFERRED_ACCEPTS_FILE = '.impeccable/live/deferred-svelte-component-accepts.json';
|
||||
|
||||
const MUSTACHE_RE = /\{([^{}]+)\}/g;
|
||||
@@ -32,9 +61,18 @@ export function manifestPathForSession(id, cwd = process.cwd()) {
|
||||
|
||||
export function ensureRuntimeHelper(cwd = process.cwd()) {
|
||||
const file = path.join(cwd, SVELTE_RUNTIME_FILE);
|
||||
if (fs.existsSync(file)) return file;
|
||||
fs.mkdirSync(path.dirname(file), { recursive: true });
|
||||
fs.writeFileSync(file, `export { mount, unmount } from 'svelte';\n`, 'utf-8');
|
||||
if (!fs.existsSync(file)) {
|
||||
fs.writeFileSync(file, `export { mount, unmount } from 'svelte';\n`, 'utf-8');
|
||||
}
|
||||
// Attach-time probe: the browser imports this through the dev server before
|
||||
// the first mount. A 404 here means the resolved app root and the dev
|
||||
// server's root disagree, and the session fails with a named error instead
|
||||
// of a silent fall-back to the picker at first variant.
|
||||
const probe = path.join(cwd, SVELTE_PROBE_FILE);
|
||||
if (!fs.existsSync(probe)) {
|
||||
fs.writeFileSync(probe, `export const impeccableLivePreviewProbe = true;\n`, 'utf-8');
|
||||
}
|
||||
return file;
|
||||
}
|
||||
|
||||
@@ -136,6 +174,14 @@ function buildInsertVariantStub(variantNum) {
|
||||
return `${buildPropsScript([])}<div class="impeccable-insert-preview">Insert variant ${variantNum}</div>\n\n<style>\n .impeccable-insert-preview { display: block; }\n</style>\n`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Scaffold a component-preview session. The scaffold is AST-based: the app's
|
||||
* own svelte compiler parses the selected markup, control-flow blocks are
|
||||
* preserved (an each collection crosses the prop contract as ONE structured
|
||||
* prop, its loop body verbatim), and constructs a detached preview cannot
|
||||
* support return `{ fallback: 'source-preview', reason }` so the caller keeps
|
||||
* the markup inside the route file instead of shipping a wrong preview.
|
||||
*/
|
||||
export function scaffoldSvelteComponentSession({
|
||||
id,
|
||||
count,
|
||||
@@ -145,25 +191,55 @@ export function scaffoldSvelteComponentSession({
|
||||
originalLines,
|
||||
cwd = process.cwd(),
|
||||
}) {
|
||||
const originalMarkup = originalLines.join('\n');
|
||||
|
||||
const compiler = loadSvelteCompiler(cwd);
|
||||
if (!compiler) {
|
||||
return { fallback: 'source-preview', reason: 'svelte 5 compiler not resolvable from the app root' };
|
||||
}
|
||||
const analysis = analyzeSvelteMarkup(originalMarkup, compiler.parse);
|
||||
if (!analysis.ok) {
|
||||
return { fallback: 'source-preview', reason: analysis.reason };
|
||||
}
|
||||
|
||||
ensureRuntimeHelper(cwd);
|
||||
const dir = componentSessionDir(id, cwd);
|
||||
fs.mkdirSync(dir, { recursive: true });
|
||||
|
||||
const originalMarkup = originalLines.join('\n');
|
||||
const contract = buildPropContract(extractMustacheExpressions(originalMarkup));
|
||||
const originalWithProps = substituteExprsWithProps(originalMarkup, contract);
|
||||
const contract = analysis.contract;
|
||||
const seeded = extractMatchingSourceCss(
|
||||
safeReadSource(path.resolve(cwd, sourceFile)),
|
||||
originalMarkup,
|
||||
);
|
||||
const seededCss = seeded.css;
|
||||
// The preview compiles in isolation, so NONE of these source rules applied
|
||||
// to what the user approved. Accept enforces that preview truth: any of
|
||||
// them the variant does not re-declare is superseded and removed, instead
|
||||
// of re-attaching to the accepted markup through kept class names (the
|
||||
// ".decisions grid grabs the new board" failure). Only the CLASS-matched
|
||||
// selectors are candidates; tag rules style shared route elements.
|
||||
const seededSelectors = [...seeded.supersedable];
|
||||
|
||||
const manifest = {
|
||||
id,
|
||||
previewMode: 'svelte-component',
|
||||
contractVersion: 2,
|
||||
sourceFile: sourceFile.split(path.sep).join('/'),
|
||||
sourceStartLine,
|
||||
sourceEndLine,
|
||||
count,
|
||||
propContract: contract,
|
||||
originalMarkup,
|
||||
seededSelectors,
|
||||
componentDir: path.relative(cwd, dir).split(path.sep).join('/'),
|
||||
// Absolute paths let the browser fall back to /@fs/ imports when the dev
|
||||
// server's base or root makes root-relative URLs miss, and probe whether
|
||||
// the preview tree is reachable at all before blaming a variant.
|
||||
componentDirAbs: dir.split(path.sep).join('/'),
|
||||
runtimeModule: `/${SVELTE_RUNTIME_FILE}`,
|
||||
runtimeModuleAbs: path.join(cwd, SVELTE_RUNTIME_FILE).split(path.sep).join('/'),
|
||||
probeModule: `/${SVELTE_PROBE_FILE}`,
|
||||
probeModuleAbs: path.join(cwd, SVELTE_PROBE_FILE).split(path.sep).join('/'),
|
||||
};
|
||||
|
||||
fs.writeFileSync(path.join(dir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
|
||||
@@ -171,7 +247,7 @@ export function scaffoldSvelteComponentSession({
|
||||
for (let n = 1; n <= count; n++) {
|
||||
const variantFile = path.join(dir, `v${n}.svelte`);
|
||||
if (!fs.existsSync(variantFile)) {
|
||||
fs.writeFileSync(variantFile, buildVariantStub(n, originalWithProps, contract), 'utf-8');
|
||||
fs.writeFileSync(variantFile, buildVariantStubV2(n, analysis.markupWithProps, contract, seededCss), 'utf-8');
|
||||
}
|
||||
}
|
||||
|
||||
@@ -180,9 +256,100 @@ export function scaffoldSvelteComponentSession({
|
||||
manifestFile: path.relative(cwd, path.join(dir, 'manifest.json')).split(path.sep).join('/'),
|
||||
componentDir: manifest.componentDir,
|
||||
propContract: contract,
|
||||
// Inlined so the generate event's scaffold payload carries the stub
|
||||
// shape; the agent edits vN.svelte in place instead of spending reads on
|
||||
// the manifest and stub files (or deleting and recreating them).
|
||||
stubMarkup: analysis.markupWithProps,
|
||||
seededCss,
|
||||
};
|
||||
}
|
||||
|
||||
function safeReadSource(filePath) {
|
||||
try { return fs.readFileSync(filePath, 'utf-8'); } catch { return ''; }
|
||||
}
|
||||
|
||||
function escapeSelectorToken(token) {
|
||||
return String(token).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
||||
}
|
||||
|
||||
/**
|
||||
* Seed variant stubs with the source component's rules that already style the
|
||||
* selected markup, so variants start from the real cascade (a detached
|
||||
* preview inherits none of the route's compile-scoped CSS) instead of
|
||||
* reimplementing it blind.
|
||||
*
|
||||
* Returns { css, supersedable }. `css` is every matching rule (class OR tag
|
||||
* matched). `supersedable` holds only the CLASS-matched selectors: those are
|
||||
* the accept-time removal candidates. Tag selectors (h1, a, p) style shared
|
||||
* elements across the whole route, so they seed the preview but are never
|
||||
* candidates for removal.
|
||||
*/
|
||||
export function extractMatchingSourceCss(routeSource, originalMarkup) {
|
||||
const empty = { css: '', supersedable: new Set() };
|
||||
const styleMatch = String(routeSource || '').match(/<style\b[^>]*>([\s\S]*?)<\/style\s*>/i);
|
||||
if (!styleMatch) return empty;
|
||||
const classNames = new Set();
|
||||
const classRe = /class\s*=\s*(["'])(.*?)\1/g;
|
||||
let m;
|
||||
while ((m = classRe.exec(originalMarkup))) {
|
||||
for (const cls of m[2].split(/\s+/)) if (cls && !cls.includes('{')) classNames.add(cls);
|
||||
}
|
||||
const tagRe = /<([a-z][a-z0-9-]*)/gi;
|
||||
const tags = new Set();
|
||||
while ((m = tagRe.exec(originalMarkup))) tags.add(m[1].toLowerCase());
|
||||
if (classNames.size === 0 && tags.size === 0) return empty;
|
||||
|
||||
// Token-boundary matching, never substring: `.btn` must not match
|
||||
// `.btn-primary`, and `.stage` must not match `.stages`. A substring hit
|
||||
// seeds a rule that never styled the pick, and a falsely seeded selector
|
||||
// becomes an accept-time DELETION of a hand-written rule.
|
||||
const classRes = [...classNames].map((cls) => new RegExp('\\.' + escapeSelectorToken(cls) + '(?![A-Za-z0-9_-])'));
|
||||
const tagRes = [...tags].map((tag) => new RegExp('(^|[\\s>+~,(])' + escapeSelectorToken(tag) + '(?![A-Za-z0-9_-])', 'i'));
|
||||
const classMatches = (selector) => classRes.some((re) => re.test(selector));
|
||||
const tagMatches = (selector) => tagRes.some((re) => re.test(selector));
|
||||
|
||||
const supersedable = new Set();
|
||||
const ruleMatches = (prelude) => {
|
||||
let matched = false;
|
||||
for (const selector of splitSelectorList(prelude)) {
|
||||
if (classMatches(selector)) {
|
||||
matched = true;
|
||||
supersedable.add(normalizeSelector(selector));
|
||||
} else if (tagMatches(selector)) {
|
||||
matched = true;
|
||||
}
|
||||
}
|
||||
return matched;
|
||||
};
|
||||
|
||||
const pick = (nodes) => {
|
||||
const kept = [];
|
||||
for (const node of nodes) {
|
||||
if (node.type === 'rule' && ruleMatches(node.prelude)) kept.push(node);
|
||||
else if (node.type === 'at' && node.children) {
|
||||
const children = pick(node.children);
|
||||
if (children.length) kept.push({ ...node, children });
|
||||
}
|
||||
}
|
||||
return kept;
|
||||
};
|
||||
return { css: serializeNodes(pick(parseStylesheet(styleMatch[1]))), supersedable };
|
||||
}
|
||||
|
||||
function buildVariantStubV2(variantNum, markupWithProps, contract, seededCss) {
|
||||
const propsComment = contract.length > 0
|
||||
? `\n<!-- Props: ${contract.map((c) => `${c.prop} (${c.kind}) <- {${c.expr}}`).join(', ')} -->\n`
|
||||
: '';
|
||||
// The guard comments must never contain the literal "<style" character
|
||||
// sequence: agents (and the fake test agent) locate the style block with
|
||||
// string searches, and a mention inside a comment truncates their surgery
|
||||
// mid-comment.
|
||||
const css = seededCss
|
||||
? `\n<style>\n /* Variant ${variantNum}: seeded from the route's current rules; restyle or delete freely.\n ALL rules go inside THIS block. Svelte allows exactly one top-level style\n element per component; appending a second one is a compile error. */\n${seededCss.split('\n').map((l) => (l.trim() ? ' ' + l : '')).join('\n')}\n</style>\n`
|
||||
: `\n<style>\n /* Variant ${variantNum}: add all CSS inside THIS block. Svelte allows exactly\n one top-level style element; a second one is a compile error. */\n</style>\n`;
|
||||
return `${buildPropsScriptV2(contract)}${propsComment}${markupWithProps.trim()}\n${css}`;
|
||||
}
|
||||
|
||||
export function scaffoldSvelteComponentInsertSession({
|
||||
id,
|
||||
count,
|
||||
@@ -213,7 +380,11 @@ export function scaffoldSvelteComponentInsertSession({
|
||||
count,
|
||||
propContract: [],
|
||||
componentDir: path.relative(cwd, dir).split(path.sep).join('/'),
|
||||
componentDirAbs: dir.split(path.sep).join('/'),
|
||||
runtimeModule: `/${SVELTE_RUNTIME_FILE}`,
|
||||
runtimeModuleAbs: path.join(cwd, SVELTE_RUNTIME_FILE).split(path.sep).join('/'),
|
||||
probeModule: `/${SVELTE_PROBE_FILE}`,
|
||||
probeModuleAbs: path.join(cwd, SVELTE_PROBE_FILE).split(path.sep).join('/'),
|
||||
};
|
||||
|
||||
fs.writeFileSync(path.join(dir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
|
||||
@@ -238,16 +409,24 @@ export function findSvelteComponentManifest(id, cwd = process.cwd()) {
|
||||
if (fs.existsSync(direct)) {
|
||||
return readManifest(direct);
|
||||
}
|
||||
const root = path.join(cwd, SVELTE_COMPONENT_ROOT);
|
||||
if (!fs.existsSync(root)) return null;
|
||||
for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
|
||||
if (!entry.isDirectory()) continue;
|
||||
const candidate = path.join(root, entry.name, 'manifest.json');
|
||||
if (!fs.existsSync(candidate)) continue;
|
||||
try {
|
||||
const manifest = readManifest(candidate);
|
||||
if (manifest?.id === id) return { ...manifest, manifestPath: candidate };
|
||||
} catch { /* skip */ }
|
||||
// Legacy location: a session scaffolded by an older version can still be
|
||||
// accepted after an upgrade.
|
||||
const legacyDirect = path.join(cwd, LEGACY_SVELTE_COMPONENT_ROOT, id, 'manifest.json');
|
||||
if (fs.existsSync(legacyDirect)) {
|
||||
return readManifest(legacyDirect);
|
||||
}
|
||||
for (const rootRel of [SVELTE_COMPONENT_ROOT, LEGACY_SVELTE_COMPONENT_ROOT]) {
|
||||
const root = path.join(cwd, rootRel);
|
||||
if (!fs.existsSync(root)) continue;
|
||||
for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
|
||||
if (!entry.isDirectory()) continue;
|
||||
const candidate = path.join(root, entry.name, 'manifest.json');
|
||||
if (!fs.existsSync(candidate)) continue;
|
||||
try {
|
||||
const manifest = readManifest(candidate);
|
||||
if (manifest?.id === id) return { ...manifest, manifestPath: candidate };
|
||||
} catch { /* skip */ }
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
@@ -451,35 +630,6 @@ function rewriteParamSelectors(selector, paramValues) {
|
||||
return { keep, selector: next };
|
||||
}
|
||||
|
||||
function splitSelectorList(prelude) {
|
||||
const selectors = [];
|
||||
let start = 0;
|
||||
let bracket = 0;
|
||||
let paren = 0;
|
||||
let quote = null;
|
||||
for (let i = 0; i < prelude.length; i++) {
|
||||
const ch = prelude[i];
|
||||
if (quote) {
|
||||
if (ch === '\\') i++;
|
||||
else if (ch === quote) quote = null;
|
||||
continue;
|
||||
}
|
||||
if (ch === '"' || ch === "'") {
|
||||
quote = ch;
|
||||
continue;
|
||||
}
|
||||
if (ch === '[') bracket++;
|
||||
else if (ch === ']') bracket = Math.max(0, bracket - 1);
|
||||
else if (ch === '(') paren++;
|
||||
else if (ch === ')') paren = Math.max(0, paren - 1);
|
||||
else if (ch === ',' && bracket === 0 && paren === 0) {
|
||||
selectors.push(prelude.slice(start, i));
|
||||
start = i + 1;
|
||||
}
|
||||
}
|
||||
selectors.push(prelude.slice(start));
|
||||
return selectors;
|
||||
}
|
||||
|
||||
function selectorHasVariant(selector, variantNum) {
|
||||
return variantSelectorRegex(variantNum).test(selector);
|
||||
@@ -527,10 +677,24 @@ export function inlineSvelteComponentAccept(manifest, variantNum, paramValues =
|
||||
|
||||
const rootTag = matchOpeningTag(markup)?.tag || 'div';
|
||||
const contract = manifest.propContract || [];
|
||||
const compiler = loadSvelteCompiler(cwd);
|
||||
const mergedMarkup = mergeOriginalTopLevelAttrs(markup, manifest.originalMarkup || '');
|
||||
const restoredMarkup = substitutePropsWithExprs(mergedMarkup, contract)
|
||||
.split('\n')
|
||||
.map((line) => line.trimEnd());
|
||||
|
||||
// Restore props back to route expressions. Contract v2 restores through the
|
||||
// AST so a prop used without braces (each headers, attribute positions)
|
||||
// still maps back to its original expression; v1 falls back to the textual
|
||||
// placeholder swap.
|
||||
let restoredText;
|
||||
if (Number(manifest.contractVersion) === 2 && compiler) {
|
||||
const restored = restoreSvelteMarkup(mergedMarkup, contract, compiler.parse);
|
||||
if (!restored.ok) {
|
||||
return { handled: false, error: 'Accepted variant does not parse: ' + restored.reason, ...resultBase };
|
||||
}
|
||||
restoredText = restored.markup;
|
||||
} else {
|
||||
restoredText = substitutePropsWithExprs(mergedMarkup, contract);
|
||||
}
|
||||
const restoredMarkup = restoredText.split('\n').map((line) => line.trimEnd());
|
||||
|
||||
const sourceContent = fs.readFileSync(sourceFile, 'utf-8');
|
||||
const sourceLines = sourceContent.split('\n');
|
||||
@@ -541,10 +705,7 @@ export function inlineSvelteComponentAccept(manifest, variantNum, paramValues =
|
||||
}
|
||||
|
||||
const indent = sourceLines[start].match(/^(\s*)/)?.[1] || '';
|
||||
const indentedMarkup = restoredMarkup.map((line) => {
|
||||
if (line.trim() === '') return '';
|
||||
return indent + line.trimStart();
|
||||
});
|
||||
const indentedMarkup = reindentPreservingStructure(restoredMarkup, indent);
|
||||
|
||||
let newLines = [
|
||||
...sourceLines.slice(0, start),
|
||||
@@ -552,25 +713,235 @@ export function inlineSvelteComponentAccept(manifest, variantNum, paramValues =
|
||||
...sourceLines.slice(end + 1),
|
||||
];
|
||||
|
||||
const sanitizedCss = sanitizeAcceptedSvelteCss(cssLines, variantNum, paramValues, rootTag);
|
||||
const bakedCss = bakeParamValuesInCss(sanitizedCss, paramValues);
|
||||
if (bakedCss.length > 0) {
|
||||
newLines = appendCssToSvelteStyle(newLines, bakedCss);
|
||||
// Selectors that were already unused before this accept are the user's
|
||||
// pre-existing code; the pruning pass must not touch them.
|
||||
const preUnused = compiler ? collectUnusedSelectors(sourceContent, compiler.compile) : new Set();
|
||||
|
||||
// Bake params (declared kinds from params.json drive branch pruning), then
|
||||
// MERGE into the component's existing style block: matching selectors are
|
||||
// replaced, new ones appended. Appending alone is how superseded rules used
|
||||
// to survive their own replacement.
|
||||
const declaredParams = readDeclaredParams(manifest, variantNum, cwd);
|
||||
let variantCss = cssLines.join('\n');
|
||||
if (/data-impeccable-variant|impeccable-variant-ready/.test(variantCss)) {
|
||||
// Defensive: strip preview-wrapper selectors that authoring rules forbid
|
||||
// on this path but an off-spec agent may still emit.
|
||||
variantCss = sanitizeAcceptedSvelteCss(cssLines, variantNum, paramValues, rootTag).join('\n');
|
||||
}
|
||||
const bakedCss = bakeParamValues(variantCss, declaredParams, paramValues || {});
|
||||
const cssStats = { replaced: 0, appended: 0, pruned: [], superseded: [] };
|
||||
if (bakedCss.trim()) {
|
||||
const merged = mergeCssIntoSvelteSource(newLines.join('\n'), bakedCss);
|
||||
newLines = merged.text.split('\n');
|
||||
cssStats.replaced = merged.replaced;
|
||||
cssStats.appended = merged.appended;
|
||||
}
|
||||
|
||||
let finalText = newLines.join('\n');
|
||||
|
||||
// Preview truth: the detached preview never applied the source rules that
|
||||
// styled the replaced selection, so the user approved a design without
|
||||
// them. Any seeded selector the variant did not re-declare is superseded;
|
||||
// left in place it re-attaches through kept class names (the accepted root
|
||||
// keeps its original classes) and re-layouts markup it no longer owns.
|
||||
//
|
||||
// Removal is bounded by ownership: a selector whose classes are still used
|
||||
// by route markup OUTSIDE the replaced region does not belong to the pick
|
||||
// alone, and removing it would strip styling from markup this accept never
|
||||
// touched. Keeping it risks a visible re-attachment quirk on the accepted
|
||||
// region; deleting it breaks the rest of the route. Keep it.
|
||||
const outsideMarkup = [...sourceLines.slice(0, start), ...sourceLines.slice(end + 1)]
|
||||
.join('\n')
|
||||
.replace(/<style\b[^>]*>[\s\S]*?<\/style\s*>/gi, '');
|
||||
const outsideClasses = new Set();
|
||||
{
|
||||
const attrRe = /class\s*=\s*(["'])(.*?)\1/g;
|
||||
let cm;
|
||||
while ((cm = attrRe.exec(outsideMarkup))) {
|
||||
for (const cls of cm[2].split(/\s+/)) if (cls && !cls.includes('{')) outsideClasses.add(cls);
|
||||
}
|
||||
const directiveRe = /class:([A-Za-z0-9_-]+)/g;
|
||||
while ((cm = directiveRe.exec(outsideMarkup))) outsideClasses.add(cm[1]);
|
||||
}
|
||||
const usedOutsideReplacedRegion = (selector) => {
|
||||
const classTokenRe = /\.([A-Za-z0-9_-]+)/g;
|
||||
let tm;
|
||||
while ((tm = classTokenRe.exec(selector))) {
|
||||
if (outsideClasses.has(tm[1])) return true;
|
||||
}
|
||||
return false;
|
||||
};
|
||||
const incomingSelectors = collectAllSelectors(bakedCss);
|
||||
const superseded = (manifest.seededSelectors || [])
|
||||
.map((selector) => normalizeSelector(selector))
|
||||
.filter((selector) => selector && !incomingSelectors.has(selector) && !usedOutsideReplacedRegion(selector));
|
||||
if (superseded.length > 0) {
|
||||
const scrubbed = removeSelectorsFromSvelteSource(finalText, new Set(superseded));
|
||||
finalText = scrubbed.text;
|
||||
cssStats.superseded = scrubbed.removed;
|
||||
}
|
||||
|
||||
if (compiler) {
|
||||
const pruned = pruneUnusedSelectors(finalText, compiler.compile, { skipSelectors: preUnused });
|
||||
finalText = pruned.source;
|
||||
cssStats.pruned = pruned.removed;
|
||||
}
|
||||
|
||||
// Postcondition: no selector from the user's pre-accept CSS may vanish
|
||||
// unless the compiler-driven prune or the preview-truth supersession
|
||||
// deliberately removed it. This turns any parser or reconciler defect into
|
||||
// a loud refusal instead of silent damage to a hand-written style block.
|
||||
const lostSelectors = findLostSelectors(sourceContent, finalText, [
|
||||
...cssStats.pruned,
|
||||
...cssStats.superseded,
|
||||
]);
|
||||
if (lostSelectors.length > 0) {
|
||||
return {
|
||||
handled: false,
|
||||
error: 'CSS reconciliation would lose selectors from the existing style block: '
|
||||
+ lostSelectors.join(', ')
|
||||
+ '. Source not modified; accept the variant manually.',
|
||||
mode: 'error',
|
||||
...resultBase,
|
||||
};
|
||||
}
|
||||
|
||||
try {
|
||||
fs.writeFileSync(sourceFile, newLines.join('\n'), 'utf-8');
|
||||
fs.writeFileSync(sourceFile, finalText, 'utf-8');
|
||||
} catch (err) {
|
||||
return { handled: false, error: 'Failed to write Svelte source: ' + err.message, ...resultBase };
|
||||
}
|
||||
removeSvelteComponentSession(manifest.id, cwd);
|
||||
|
||||
const verify = verifyAcceptedSource(finalText);
|
||||
return {
|
||||
handled: true,
|
||||
css: cssStats,
|
||||
verify,
|
||||
...resultBase,
|
||||
};
|
||||
}
|
||||
|
||||
/** Re-indent a block onto `indent` while preserving its internal structure. */
|
||||
export function reindentPreservingStructure(lines, indent) {
|
||||
const nonEmpty = lines.filter((line) => line.trim() !== '');
|
||||
if (nonEmpty.length === 0) return lines.map(() => '');
|
||||
const minIndent = Math.min(...nonEmpty.map((line) => (line.match(/^\s*/) || [''])[0].length));
|
||||
return lines.map((line) => {
|
||||
if (line.trim() === '') return '';
|
||||
const current = (line.match(/^\s*/) || [''])[0].length;
|
||||
return indent + line.slice(Math.min(minIndent, current));
|
||||
});
|
||||
}
|
||||
|
||||
function styleBlockText(sourceText) {
|
||||
const match = String(sourceText || '').match(/<style\b[^>]*>([\s\S]*?)<\/style\s*>/i);
|
||||
return match ? match[1] : '';
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove every rule whose (normalized) selector list is fully contained in
|
||||
* `selectors` from the component's style block, at any at-rule nesting depth.
|
||||
* Rules that mix doomed and surviving selectors keep the survivors.
|
||||
*/
|
||||
export function removeSelectorsFromSvelteSource(sourceText, selectors) {
|
||||
const text = String(sourceText || '');
|
||||
const styleRe = /<style\b[^>]*>([\s\S]*?)<\/style\s*>/gi;
|
||||
let lastMatch = null;
|
||||
let m;
|
||||
while ((m = styleRe.exec(text))) lastMatch = m;
|
||||
if (!lastMatch) return { text, removed: [] };
|
||||
|
||||
const removed = [];
|
||||
const transform = (nodes) => {
|
||||
const kept = [];
|
||||
for (const node of nodes) {
|
||||
if (node.type === 'rule') {
|
||||
const survivors = [];
|
||||
for (const selector of splitSelectorList(node.prelude)) {
|
||||
if (selectors.has(normalizeSelector(selector))) removed.push(normalizeSelector(selector));
|
||||
else survivors.push(selector);
|
||||
}
|
||||
if (survivors.length > 0) kept.push({ ...node, prelude: survivors.join(', ') });
|
||||
} else if (node.type === 'at' && node.children) {
|
||||
const children = transform(node.children);
|
||||
if (children.length > 0) kept.push({ ...node, children });
|
||||
} else {
|
||||
kept.push(node);
|
||||
}
|
||||
}
|
||||
return kept;
|
||||
};
|
||||
|
||||
const nodes = transform(parseStylesheet(lastMatch[1]));
|
||||
if (removed.length === 0) return { text, removed };
|
||||
const openTag = lastMatch[0].slice(0, lastMatch[0].indexOf('>') + 1);
|
||||
const rebuilt = `${openTag}\n${serializeNodes(nodes).split('\n').map((l) => (l.trim() ? ' ' + l : '')).join('\n')}\n</style>`;
|
||||
return {
|
||||
text: text.slice(0, lastMatch.index) + rebuilt + text.slice(lastMatch.index + lastMatch[0].length),
|
||||
removed,
|
||||
};
|
||||
}
|
||||
|
||||
export function findLostSelectors(beforeSource, afterSource, prunedSelectors = []) {
|
||||
const before = collectAllSelectors(styleBlockText(beforeSource));
|
||||
const after = collectAllSelectors(styleBlockText(afterSource));
|
||||
const pruned = new Set((prunedSelectors || []).map((s) => normalizeSelector(s)));
|
||||
const lost = [];
|
||||
for (const selector of before) {
|
||||
if (!after.has(selector) && !pruned.has(selector)) lost.push(selector);
|
||||
}
|
||||
return lost;
|
||||
}
|
||||
|
||||
function readDeclaredParams(manifest, variantNum, cwd) {
|
||||
try {
|
||||
const raw = JSON.parse(fs.readFileSync(path.join(cwd, manifest.componentDir, 'params.json'), 'utf-8'));
|
||||
const list = raw?.[String(variantNum)];
|
||||
return Array.isArray(list) ? list : [];
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Merge CSS into a svelte component's top-level style block (created when
|
||||
* absent), replacing rules whose selectors match and appending the rest.
|
||||
*/
|
||||
export function mergeCssIntoSvelteSource(sourceText, incomingCss) {
|
||||
const text = String(sourceText || '');
|
||||
const styleRe = /<style\b[^>]*>([\s\S]*?)<\/style\s*>/gi;
|
||||
let lastMatch = null;
|
||||
let m;
|
||||
while ((m = styleRe.exec(text))) lastMatch = m;
|
||||
|
||||
if (!lastMatch) {
|
||||
const { css, replaced, appended } = reconcileCss('', incomingCss);
|
||||
return {
|
||||
text: `${text.replace(/\s*$/, '')}\n\n<style>\n${indentCssBlock(css)}\n</style>\n`,
|
||||
replaced,
|
||||
appended,
|
||||
};
|
||||
}
|
||||
|
||||
const inner = lastMatch[1];
|
||||
const { css, replaced, appended } = reconcileCss(inner, incomingCss);
|
||||
const openTag = lastMatch[0].slice(0, lastMatch[0].indexOf('>') + 1);
|
||||
const replacedBlock = `${openTag}\n${indentCssBlock(css)}\n</style>`;
|
||||
return {
|
||||
text: text.slice(0, lastMatch.index) + replacedBlock + text.slice(lastMatch.index + lastMatch[0].length),
|
||||
replaced,
|
||||
appended,
|
||||
};
|
||||
}
|
||||
|
||||
function indentCssBlock(css) {
|
||||
return String(css || '')
|
||||
.split('\n')
|
||||
.map((line) => (line.trim() === '' ? '' : ' ' + line))
|
||||
.join('\n');
|
||||
}
|
||||
|
||||
function inlineSvelteComponentInsertAccept({
|
||||
manifest,
|
||||
markup,
|
||||
@@ -601,10 +972,7 @@ function inlineSvelteComponentInsertAccept({
|
||||
|
||||
const nearbyLine = sourceLines[insertIndex] ?? sourceLines[insertIndex - 1] ?? '';
|
||||
const indent = nearbyLine.match(/^(\s*)/)?.[1] || '';
|
||||
const indentedMarkup = restoredMarkup.map((line) => {
|
||||
if (line.trim() === '') return '';
|
||||
return indent + line.trimStart();
|
||||
});
|
||||
const indentedMarkup = reindentPreservingStructure(restoredMarkup, indent);
|
||||
|
||||
let newLines = [
|
||||
...sourceLines.slice(0, insertIndex),
|
||||
@@ -612,10 +980,15 @@ function inlineSvelteComponentInsertAccept({
|
||||
...sourceLines.slice(insertIndex),
|
||||
];
|
||||
|
||||
const sanitizedCss = sanitizeAcceptedSvelteCss(cssLines, variantNum, paramValues, rootTag);
|
||||
const bakedCss = bakeParamValuesInCss(sanitizedCss, paramValues);
|
||||
if (bakedCss.length > 0) {
|
||||
newLines = appendCssToSvelteStyle(newLines, bakedCss);
|
||||
let variantCss = cssLines.join('\n');
|
||||
if (/data-impeccable-variant|impeccable-variant-ready/.test(variantCss)) {
|
||||
variantCss = sanitizeAcceptedSvelteCss(cssLines, variantNum, paramValues, rootTag).join('\n');
|
||||
}
|
||||
const declaredParams = readDeclaredParams(manifest, variantNum, cwd);
|
||||
const bakedCss = bakeParamValues(variantCss, declaredParams, paramValues || {});
|
||||
if (bakedCss.trim()) {
|
||||
const merged = mergeCssIntoSvelteSource(newLines.join('\n'), bakedCss);
|
||||
newLines = merged.text.split('\n');
|
||||
}
|
||||
|
||||
try {
|
||||
@@ -625,8 +998,10 @@ function inlineSvelteComponentInsertAccept({
|
||||
}
|
||||
removeSvelteComponentSession(manifest.id, cwd);
|
||||
|
||||
const verify = verifyAcceptedSource(newLines.join('\n'));
|
||||
return {
|
||||
handled: true,
|
||||
verify,
|
||||
...resultBase,
|
||||
};
|
||||
}
|
||||
@@ -729,18 +1104,159 @@ export function removeSvelteComponentSession(id, cwd = process.cwd()) {
|
||||
} catch { /* non-fatal */ }
|
||||
}
|
||||
|
||||
export function removeAllSvelteComponentSessions(cwd = process.cwd()) {
|
||||
const root = path.join(cwd, SVELTE_COMPONENT_ROOT);
|
||||
if (!fs.existsSync(root)) return;
|
||||
for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
|
||||
if (!entry.isDirectory()) continue;
|
||||
if (entry.name.startsWith('__')) continue;
|
||||
/**
|
||||
* Compile-check every variant component of a session with the app's own
|
||||
* compiler, BEFORE the browser ever imports them. A variant that does not
|
||||
* compile (the classic: a second top-level <style> appended next to the
|
||||
* seeded one) used to surface as a red Vite overlay in the user's page plus
|
||||
* a mount-failure round trip; bounced at publish time it is a private
|
||||
* agent-side fix with the exact file and line.
|
||||
*/
|
||||
export function compileCheckVariants(id, cwd = process.cwd()) {
|
||||
const manifest = findSvelteComponentManifest(id, cwd);
|
||||
if (!manifest || !manifest.manifestPath) return { ok: true, failures: [], checked: 0 };
|
||||
const compiler = loadSvelteCompiler(cwd);
|
||||
if (!compiler || typeof compiler.compile !== 'function') return { ok: true, failures: [], checked: 0 };
|
||||
const sessionDir = path.dirname(manifest.manifestPath);
|
||||
const failures = [];
|
||||
let checked = 0;
|
||||
let entries = [];
|
||||
try { entries = fs.readdirSync(sessionDir); } catch { return { ok: true, failures: [], checked: 0 }; }
|
||||
for (const name of entries) {
|
||||
if (!/^v\d+\.svelte$/.test(name)) continue;
|
||||
checked++;
|
||||
try {
|
||||
fs.rmSync(path.join(root, entry.name), { recursive: true, force: true });
|
||||
compiler.compile(fs.readFileSync(path.join(sessionDir, name), 'utf-8'), { generate: false });
|
||||
} catch (err) {
|
||||
failures.push({
|
||||
file: `${manifest.componentDir}/${name}`,
|
||||
line: err?.start?.line ?? null,
|
||||
column: err?.start?.column ?? null,
|
||||
message: String(err?.message || err).split('\n')[0].slice(0, 300),
|
||||
});
|
||||
}
|
||||
}
|
||||
return { ok: failures.length === 0, failures, checked };
|
||||
}
|
||||
|
||||
/**
|
||||
* Snapshot the agent-authored variant files into a fresh revision directory
|
||||
* and stamp the manifest. Called by the server on every publish (`done`
|
||||
* reply) for a component session; the browser imports from the revision dir,
|
||||
* so the dev server can never serve a stale compile of a republished file.
|
||||
*/
|
||||
export function bumpSvelteComponentPreviewRevision(id, cwd = process.cwd()) {
|
||||
const manifest = findSvelteComponentManifest(id, cwd);
|
||||
if (!manifest || !manifest.manifestPath) return null;
|
||||
const sessionDir = path.dirname(manifest.manifestPath);
|
||||
const revision = Number(manifest.revision || 0) + 1;
|
||||
const revDirName = `r${revision}`;
|
||||
const revDir = path.join(sessionDir, revDirName);
|
||||
try {
|
||||
fs.mkdirSync(revDir, { recursive: true });
|
||||
let entries = [];
|
||||
try { entries = fs.readdirSync(sessionDir, { withFileTypes: true }); } catch { /* empty */ }
|
||||
for (const entry of entries) {
|
||||
if (!entry.isFile()) continue;
|
||||
if (entry.name === 'manifest.json') continue;
|
||||
fs.copyFileSync(path.join(sessionDir, entry.name), path.join(revDir, entry.name));
|
||||
}
|
||||
// Previous revision dirs are dead the moment a new one exists.
|
||||
for (const entry of entries) {
|
||||
if (entry.isDirectory() && /^r\d+$/.test(entry.name) && entry.name !== revDirName) {
|
||||
try { fs.rmSync(path.join(sessionDir, entry.name), { recursive: true, force: true }); } catch { /* non-fatal */ }
|
||||
}
|
||||
}
|
||||
const relSessionDir = path.relative(cwd, sessionDir).split(path.sep).join('/');
|
||||
const updated = {
|
||||
...manifest,
|
||||
revision,
|
||||
revisionDir: `${relSessionDir}/${revDirName}`,
|
||||
revisionDirAbs: revDir.split(path.sep).join('/'),
|
||||
};
|
||||
delete updated.manifestPath;
|
||||
fs.writeFileSync(manifest.manifestPath, JSON.stringify(updated, null, 2) + '\n', 'utf-8');
|
||||
return { revision, revisionDir: updated.revisionDir };
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Stop-path sweep. The whole `node_modules/.impeccable-live` tree is
|
||||
* impeccable-owned and gitignored, so once no session should survive there is
|
||||
* nothing left worth keeping: the per-session dirs, the generated
|
||||
* `__runtime.js`, and the parent directory all go. The old per-entry loop
|
||||
* skipped `__*` entries and the parent, which left the runtime shim and an
|
||||
* empty directory in every project that ever ran live mode once.
|
||||
*/
|
||||
export function removeAllSvelteComponentSessions(cwd = process.cwd()) {
|
||||
for (const rootRel of [SVELTE_COMPONENT_ROOT, LEGACY_SVELTE_COMPONENT_ROOT]) {
|
||||
const root = path.join(cwd, rootRel);
|
||||
if (!fs.existsSync(root)) continue;
|
||||
try {
|
||||
fs.rmSync(root, { recursive: true, force: true });
|
||||
} catch { /* non-fatal */ }
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Boot-path sweep. A restart must not delete the tree wholesale: sessions
|
||||
* recorded in the session store may still be mid-generation. Remove only the
|
||||
* session dirs whose id has no active snapshot, then drop `__runtime.js` and
|
||||
* the parent directory when nothing is left to serve.
|
||||
*
|
||||
* @param {Iterable<string>} activeIds session ids that must be preserved
|
||||
* @returns {{ removed: string[], removedRoot: boolean, kept: string[] }}
|
||||
*/
|
||||
export function sweepInactiveSvelteComponentSessions(activeIds = [], cwd = process.cwd()) {
|
||||
const result = { removed: [], removedRoot: false, kept: [] };
|
||||
const active = new Set();
|
||||
for (const id of activeIds || []) {
|
||||
if (typeof id === 'string' && id) active.add(id);
|
||||
}
|
||||
|
||||
for (const rootRel of [SVELTE_COMPONENT_ROOT, LEGACY_SVELTE_COMPONENT_ROOT]) {
|
||||
const root = path.join(cwd, rootRel);
|
||||
if (!fs.existsSync(root)) continue;
|
||||
|
||||
let entries;
|
||||
try {
|
||||
entries = fs.readdirSync(root, { withFileTypes: true });
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
|
||||
let keptHere = 0;
|
||||
for (const entry of entries) {
|
||||
if (!entry.isDirectory()) continue;
|
||||
if (entry.name.startsWith('__')) continue;
|
||||
if (active.has(entry.name)) {
|
||||
result.kept.push(entry.name);
|
||||
keptHere++;
|
||||
continue;
|
||||
}
|
||||
try {
|
||||
fs.rmSync(path.join(root, entry.name), { recursive: true, force: true });
|
||||
result.removed.push(entry.name);
|
||||
} catch {
|
||||
// Could not remove it, so it still occupies the tree; treat it as kept
|
||||
// so the parent directory is not torn out from under it.
|
||||
result.kept.push(entry.name);
|
||||
keptHere++;
|
||||
}
|
||||
}
|
||||
|
||||
if (keptHere === 0) {
|
||||
try {
|
||||
fs.rmSync(root, { recursive: true, force: true });
|
||||
result.removedRoot = true;
|
||||
} catch { /* non-fatal */ }
|
||||
}
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
export function deferredAcceptsPath(cwd = process.cwd()) {
|
||||
const key = createHash('sha1').update(path.resolve(cwd)).digest('hex').slice(0, 16);
|
||||
return path.join(os.tmpdir(), 'impeccable-live', key, 'deferred-svelte-component-accepts.json');
|
||||
|
||||
@@ -7,6 +7,7 @@
|
||||
* actual live UI remains the shared plain-DOM browser chrome.
|
||||
*/
|
||||
|
||||
import crypto from 'node:crypto';
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
@@ -14,6 +15,28 @@ export const SVELTE_LIVE_ROOT_COMPONENT = 'src/lib/impeccable/ImpeccableLiveRoot
|
||||
export const SVELTE_LAYOUT_MARKER_OPEN = '<!-- impeccable-live-svelte-start -->';
|
||||
export const SVELTE_LAYOUT_MARKER_CLOSE = '<!-- impeccable-live-svelte-end -->';
|
||||
export const SVELTE_ROOT_IMPORT = "import ImpeccableLiveRoot from '$lib/impeccable/ImpeccableLiveRoot.svelte';";
|
||||
// Matches the import at ANY revision (or none). [ \t]* bounds only, never
|
||||
// \s*: a greedy \s* after the statement swallowed the next line's
|
||||
// indentation on removal, leaving a formatting scar in user layouts.
|
||||
const SVELTE_ROOT_IMPORT_LINE_RE = /^[ \t]*import ImpeccableLiveRoot from '\$lib\/impeccable\/ImpeccableLiveRoot\.svelte(?:\?[^']*)?';[ \t]*\r?\n?/gm;
|
||||
|
||||
/**
|
||||
* The import specifier carries a token-derived revision query. The adapter
|
||||
* component embeds the helper token, and Vite (client AND SSR) can keep
|
||||
* serving a stale compiled module after the file is rewritten on a helper
|
||||
* restart; the browser then requests /live.js with a rotated-out token and
|
||||
* gets a 401 with no picker. A changed specifier is a different module id,
|
||||
* which no cache survives.
|
||||
*/
|
||||
export function svelteRootImportLine(rev) {
|
||||
if (!rev) return SVELTE_ROOT_IMPORT;
|
||||
return "import ImpeccableLiveRoot from '$lib/impeccable/ImpeccableLiveRoot.svelte?impeccable-live=" + rev + "';";
|
||||
}
|
||||
|
||||
export function svelteAdapterRev(token) {
|
||||
if (!token) return null;
|
||||
return crypto.createHash('sha256').update(String(token)).digest('hex').slice(0, 8);
|
||||
}
|
||||
|
||||
export function detectSvelteKitProject(cwd = process.cwd(), config = null) {
|
||||
const appHtml = findSvelteKitAppHtml(cwd, config);
|
||||
@@ -50,7 +73,7 @@ export function applySvelteKitLiveAdapter({ cwd = process.cwd(), port, token, co
|
||||
fs.mkdirSync(path.dirname(layoutAbs), { recursive: true });
|
||||
const layoutExisted = fs.existsSync(layoutAbs);
|
||||
const before = layoutExisted ? fs.readFileSync(layoutAbs, 'utf-8') : defaultSvelteLayout();
|
||||
const after = patchSvelteLayout(before);
|
||||
const after = patchSvelteLayout(before, { rev: svelteAdapterRev(token) });
|
||||
fs.writeFileSync(layoutAbs, after, 'utf-8');
|
||||
|
||||
return {
|
||||
@@ -94,15 +117,27 @@ export function removeSvelteKitLiveAdapter({ cwd = process.cwd(), config = null
|
||||
};
|
||||
}
|
||||
|
||||
export function patchSvelteLayout(content) {
|
||||
export function patchSvelteLayout(content, { rev = null } = {}) {
|
||||
let out = String(content || '');
|
||||
if (!out.includes(SVELTE_ROOT_IMPORT)) {
|
||||
const scriptMatch = out.match(/<script(?:\s[^>]*)?>/i);
|
||||
if (scriptMatch) {
|
||||
const insertAt = scriptMatch.index + scriptMatch[0].length;
|
||||
out = out.slice(0, insertAt) + '\n ' + SVELTE_ROOT_IMPORT + out.slice(insertAt);
|
||||
} else {
|
||||
out = `<script>\n ${SVELTE_ROOT_IMPORT}\n</script>\n\n` + out;
|
||||
const importLine = svelteRootImportLine(rev);
|
||||
if (!out.includes(importLine)) {
|
||||
// An import at an older revision is replaced in place, keeping its
|
||||
// indentation; only a layout with no impeccable import gets an insert.
|
||||
let replaced = false;
|
||||
out = out.replace(SVELTE_ROOT_IMPORT_LINE_RE, (line) => {
|
||||
if (replaced) return '';
|
||||
replaced = true;
|
||||
const indent = (line.match(/^[ \t]*/) || [''])[0];
|
||||
return indent + importLine + '\n';
|
||||
});
|
||||
if (!replaced) {
|
||||
const scriptMatch = out.match(/<script(?:\s[^>]*)?>/i);
|
||||
if (scriptMatch) {
|
||||
const insertAt = scriptMatch.index + scriptMatch[0].length;
|
||||
out = out.slice(0, insertAt) + '\n ' + importLine + out.slice(insertAt);
|
||||
} else {
|
||||
out = `<script>\n ${importLine}\n</script>\n\n` + out;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -131,8 +166,8 @@ export function unpatchSvelteLayout(content) {
|
||||
'g',
|
||||
);
|
||||
out = out.replace(blockRe, '$1');
|
||||
out = out.replace(new RegExp('^\\s*' + escapeRegExp(SVELTE_ROOT_IMPORT) + '\\s*\\n?', 'gm'), '');
|
||||
out = out.replace(/<script>\s*<\/script>\s*\n?/g, '');
|
||||
out = out.replace(SVELTE_ROOT_IMPORT_LINE_RE, '');
|
||||
out = out.replace(/<script>\s*<\/script>[ \t]*\r?\n?/g, '');
|
||||
return out.replace(/\n{3,}/g, '\n\n');
|
||||
}
|
||||
|
||||
@@ -193,6 +228,11 @@ export function buildSvelteLiveRootComponent(port, token) {
|
||||
script.src = LIVE_URL;
|
||||
script.async = true;
|
||||
script.dataset.impeccableLiveScript = 'true';
|
||||
script.onerror = () => console.error(
|
||||
'[impeccable] live.js failed to load from ' + LIVE_URL
|
||||
+ ' (helper down, or the token rotated while a stale adapter module was cached).'
|
||||
+ ' Re-run the live boot, then reload this page.'
|
||||
);
|
||||
document.head.appendChild(script);
|
||||
|
||||
return () => {
|
||||
|
||||
@@ -19,7 +19,7 @@
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { buildLiveScriptSrc } from '../live-inject.mjs';
|
||||
import { buildLiveScriptSrc } from './frameworks/script-src.mjs';
|
||||
|
||||
export const TANSTACK_MARKER_OPEN = '{/* impeccable-live-tanstack-start */}';
|
||||
export const TANSTACK_MARKER_CLOSE = '{/* impeccable-live-tanstack-end */}';
|
||||
|
||||
@@ -34,3 +34,138 @@ export const LIVE_COMMANDS = [
|
||||
|
||||
// Action values accepted by the live event protocol, in palette order.
|
||||
export const VISUAL_ACTIONS = LIVE_COMMANDS.map((c) => c.value);
|
||||
|
||||
/*
|
||||
* ---------------------------------------------------------------------------
|
||||
* Protocol vocabulary
|
||||
* ---------------------------------------------------------------------------
|
||||
* The enums below are the wire contract between the browser overlay, the live
|
||||
* helper server, and the durable session journal. They live here rather than in
|
||||
* the modules that use them so a value cannot be added to the validator without
|
||||
* the store and the server seeing it too.
|
||||
*
|
||||
* live-browser.js still cannot import this file (it is served raw and injected
|
||||
* as an IIFE), so its local phase table repeats the agent-phase names. Anything
|
||||
* the server can broadcast must appear in AGENT_PHASES here first.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Phases the live server broadcasts as `agent_phase`, in lifecycle order.
|
||||
* Every one of these is emitted by `recordAgentPhase()` in live-server.mjs;
|
||||
* the validator rejects anything else, so a typo in a phase name fails loudly
|
||||
* instead of quietly ranking as an unknown phase in the browser's progress bar.
|
||||
*/
|
||||
export const AGENT_PHASES = Object.freeze([
|
||||
'picked_up',
|
||||
'scaffolding',
|
||||
'source_ready',
|
||||
'scaffold_fallback',
|
||||
'generation_ready',
|
||||
'first_reviewable',
|
||||
'second_reviewable',
|
||||
'all_variants_ready',
|
||||
]);
|
||||
|
||||
/** Event types the helper server accepts from the browser over POST /events. */
|
||||
export const CLIENT_EVENT_TYPES = Object.freeze([
|
||||
'generate',
|
||||
'accept',
|
||||
'discard',
|
||||
'checkpoint',
|
||||
'agent_phase',
|
||||
'variant_mounted',
|
||||
'variant_mount_failed',
|
||||
'exit',
|
||||
'prefetch',
|
||||
'manual_edits',
|
||||
'steer',
|
||||
'carbonize_cleanup',
|
||||
]);
|
||||
|
||||
/**
|
||||
* Event types the durable journal applies. A superset of CLIENT_EVENT_TYPES:
|
||||
* the agent-side helpers (live-poll, live-complete) and the server itself
|
||||
* append the rest. An event type missing here lands as `unknown_event_type`
|
||||
* in the snapshot diagnostics.
|
||||
*/
|
||||
export const JOURNAL_EVENT_TYPES = Object.freeze([
|
||||
'generate',
|
||||
'variant_plan',
|
||||
'detector_waivers',
|
||||
'agent_phase',
|
||||
'variants_ready',
|
||||
'agent_done',
|
||||
'variant_mounted',
|
||||
'variant_mount_failed',
|
||||
'checkpoint',
|
||||
'accept',
|
||||
'accept_intent',
|
||||
'manual_edit_apply',
|
||||
'steer',
|
||||
'steer_done',
|
||||
'carbonize_cleanup',
|
||||
'discard',
|
||||
'discarded',
|
||||
'complete',
|
||||
'agent_error',
|
||||
]);
|
||||
|
||||
/** Phases the session store assigns to a snapshot. */
|
||||
export const SESSION_PHASES = Object.freeze([
|
||||
'new',
|
||||
'generate_requested',
|
||||
'variants_ready',
|
||||
'carbonize_required',
|
||||
'carbonize_cleanup_requested',
|
||||
'manual_edit_apply_requested',
|
||||
'steer_requested',
|
||||
'steer_done',
|
||||
'accept_requested',
|
||||
'discard_requested',
|
||||
'discarded',
|
||||
'completed',
|
||||
'agent_error',
|
||||
]);
|
||||
|
||||
/** Phases that retire a session from the active list. */
|
||||
export const COMPLETED_SESSION_PHASES = Object.freeze(['completed', 'discarded']);
|
||||
|
||||
/**
|
||||
* Phases after which a late generation write is a ghost from a canceled cycle.
|
||||
* The store journals such an event as a diagnostic instead of applying it.
|
||||
*/
|
||||
export const GENERATION_FENCED_SESSION_PHASES = Object.freeze([
|
||||
'accept_requested',
|
||||
'discard_requested',
|
||||
'carbonize_required',
|
||||
'completed',
|
||||
'discarded',
|
||||
]);
|
||||
|
||||
/**
|
||||
* `reason` values carried on checkpoint events. Not validated (an unknown
|
||||
* reason is journaled, never rejected) because the reason is diagnostic
|
||||
* breadcrumb, not control flow. Two exceptions drive behavior and are split
|
||||
* out below.
|
||||
*/
|
||||
export const CHECKPOINT_REASONS = Object.freeze([
|
||||
'generate_started',
|
||||
'variants_progress',
|
||||
'variants_ready',
|
||||
'browser_resumed',
|
||||
'browser_resumed_svelte_component',
|
||||
'param_changed',
|
||||
'variant_anchor_missing',
|
||||
'component_preview_anchor_missing',
|
||||
'steer_input_focused',
|
||||
'steer_submitted',
|
||||
'steer_send_failed',
|
||||
'steer_done',
|
||||
'steer_error',
|
||||
]);
|
||||
|
||||
/** Checkpoint reasons the server reads as variant-publication progress. */
|
||||
export const VARIANT_PROGRESS_CHECKPOINT_REASONS = Object.freeze([
|
||||
'variants_progress',
|
||||
'variants_ready',
|
||||
]);
|
||||
|
||||
@@ -0,0 +1,102 @@
|
||||
One-time live-mode project setup. Loaded from [live.md](live.md) only when `live.mjs` reports `config_missing` / `config_invalid`, when `configDrift` needs handling, or when the config lacks `cspChecked`. Not part of the per-session hot path.
|
||||
|
||||
## Write the config
|
||||
|
||||
Create the file at the `path` the boot reported (default `.impeccable/live/config.json`):
|
||||
|
||||
```json
|
||||
{
|
||||
"files": ["<path-or-glob>", "<path-or-glob>", ...],
|
||||
"exclude": ["<optional-glob>", ...],
|
||||
"insertBefore": "</body>",
|
||||
"commentSyntax": "html",
|
||||
"cspChecked": true
|
||||
}
|
||||
```
|
||||
|
||||
`files` is the inject target: **the HTML files the browser actually loads**, not necessarily source (tracked vs generated does not matter here; wrap has its own generated-file guard). Entries are literal paths or globs. `exclude` (optional) skips files a `files` glob would otherwise include (email templates, demo fixtures). `cspChecked` records that the CSP step below has run; absent on first setup.
|
||||
|
||||
**Hard-excluded paths (cannot be overridden):** `**/node_modules/**` and `**/.git/**`; injecting there would instrument third-party code.
|
||||
|
||||
**Glob syntax:** `**` matches any number of segments (including zero), `*` matches within a segment, `?` matches one character. Paths are project-root-relative with forward slashes.
|
||||
|
||||
| Framework | `files` | `insertBefore` | `commentSyntax` |
|
||||
|-----------|---------|----------------|-----------------|
|
||||
| SPA with single shell (Vite / React / Plain HTML) | `["index.html"]` | `</body>` | `html` |
|
||||
| Next.js (App Router) | `["app/layout.tsx"]` | `</body>` | `jsx` |
|
||||
| Next.js (Pages) | `["pages/_document.tsx"]` | `</body>` | `jsx` |
|
||||
| Nuxt | `["app.vue"]` | `</body>` | `html` |
|
||||
| Svelte / SvelteKit | `["src/app.html"]` | `</body>` | `html` |
|
||||
| TanStack Router (SPA, Vite) | `["index.html"]` | `</body>` | `html` |
|
||||
| TanStack Start (SSR) | `["src/routes/__root.tsx"]` | `<Scripts` | `jsx` |
|
||||
| Astro | `[" <root layout .astro>"]` | `</body>` | `html` |
|
||||
| Multi-page (separate HTML per route) | `["public/**/*.html"]` glob over the served dir | `</body>` | `html` |
|
||||
|
||||
Pick an anchor that exists in every file (`</body>` almost always works); `insertAfter` matches after a line instead. For multi-page sites prefer a glob so new pages are picked up automatically. For sites whose pages are rebuilt by a generator, the inject survives only until the next regeneration: re-run `live.mjs` after each build (accept is unaffected; it writes true source via the fallback flow).
|
||||
|
||||
**Framework adapters (auto-detected at inject time).** Every inject records what it wrote in `.impeccable/live/inject-journal.json`; the next inject or remove heals artifacts a crash or wrong-directory stop left behind. SvelteKit, Nuxt, and TanStack Start server-render their document shell, so a raw `<script>` in the entry template will not execute reliably; `live-inject.mjs` detects them and routes to a dedicated adapter (SvelteKit: dev-only root component from `+layout.svelte`; Nuxt: dev-only `.client.ts` plugin; TanStack Start: a generated dev-only `ImpeccableLiveRoot` component in `__root`). The `files` value stays a valid detection/CSP hint but is not the literal insertion site. A plain TanStack Router SPA takes the baseline Vite path.
|
||||
|
||||
## Config drift
|
||||
|
||||
On every boot the project is scanned for HTML files under common page roots (`public/`, `src/`, `app/`, `pages/`) that the resolved `files` list does not cover; they surface as `configDrift.orphans` with a hint. Tell the user once per session which files are uncovered and offer to add them or switch `files` to a glob. Never auto-update the config; the user decides. `configDrift` is `null` when there is no drift.
|
||||
|
||||
## CSP detection (first-time only)
|
||||
|
||||
If `config.cspChecked === true`, skip this whole section; the user was already asked once.
|
||||
|
||||
```bash
|
||||
node .claude/skills/impeccable/scripts/detect-csp.mjs
|
||||
```
|
||||
|
||||
Output `{ shape, signals }`; the shape names the *patch mechanism*, so one template covers many frameworks:
|
||||
|
||||
- **`null`**: no CSP; write the config with `cspChecked: true` and stop here.
|
||||
- **`append-arrays`**: CSP as structured directive arrays; auto-patchable (monorepo helpers with `additionalScriptSrc`/`additionalConnectSrc`, SvelteKit `kit.csp.directives`, Nuxt `nuxt-security`).
|
||||
- **`append-string`**: CSP as a literal value string; auto-patchable (inline `next.config.*` `headers()`, Nuxt `routeRules`).
|
||||
- **`middleware`** / **`meta-tag`**: detected but not auto-patched. Show the user the detected files, ask them to add `http://localhost:8400` to `script-src` and `connect-src` manually, then mark `cspChecked: true` and proceed.
|
||||
|
||||
### Consent prompt (use this phrasing)
|
||||
|
||||
> **CSP patch needed.** I detected a Content Security Policy in your project that blocks `http://localhost:8400`: the live picker won't load without an allowance. Here's the change I'd make:
|
||||
>
|
||||
> ```diff
|
||||
> [file: <patchTarget>]
|
||||
> [exact diff, 2-5 lines]
|
||||
> ```
|
||||
>
|
||||
> It's guarded by `NODE_ENV === "development"` so the extra entry only appears in dev and never reaches production. You can remove it any time by reverting this file. Apply? [y/n]
|
||||
|
||||
On "no": skip the patch, note that live will not work until the allowance is added manually, and still write `cspChecked: true` (the question has been asked). On "yes": apply the shape's patch below, then write `cspChecked: true`.
|
||||
|
||||
### append-arrays
|
||||
|
||||
Declare near the top of the file that holds the CSP arrays, then append `...__impeccableLiveDev` to the script-src and connect-src arrays:
|
||||
|
||||
```ts
|
||||
// Dev-only allowance so impeccable live mode can load. Guarded by NODE_ENV.
|
||||
const __impeccableLiveDev =
|
||||
process.env.NODE_ENV === "development" ? ["http://localhost:8400"] : [];
|
||||
```
|
||||
|
||||
Per-framework: Next.js + monorepo helper: edit the *app's* `next.config.*` (not the shared helper), appending to `additionalScriptSrc` / `additionalConnectSrc`. SvelteKit: `svelte.config.js`, `kit.csp.directives['script-src']` and `['connect-src']`. Nuxt + nuxt-security: `nuxt.config.*`, `security.headers.contentSecurityPolicy['script-src']` and `['connect-src']`. Reference outputs: `tests/framework-fixtures/nextjs-turborepo/expected-after-patch.ts`, `tests/framework-fixtures/sveltekit-csp/expected-after-patch.js`. Idempotency: if `__impeccableLiveDev` already exists in the file, the patch is applied; just mark `cspChecked: true`.
|
||||
|
||||
### append-string
|
||||
|
||||
Two-point patch: declare a dev-only string, interpolate it into the CSP value at both directives (leading space so it concatenates cleanly; convert literals to template strings as part of the edit):
|
||||
|
||||
```ts
|
||||
// Dev-only allowance so impeccable live mode can load.
|
||||
const __impeccableLiveDev =
|
||||
process.env.NODE_ENV === "development" ? " http://localhost:8400" : "";
|
||||
```
|
||||
|
||||
- `script-src 'self' 'unsafe-inline'` becomes `` `script-src 'self' 'unsafe-inline'${__impeccableLiveDev}` ``
|
||||
- `connect-src 'self'` becomes `` `connect-src 'self'${__impeccableLiveDev}` ``
|
||||
|
||||
Per-framework: Next.js inline `headers()` in `next.config.*`; Nuxt `routeRules['/**'].headers['Content-Security-Policy']` in `nuxt.config.*`. Reference outputs: `tests/framework-fixtures/nextjs-inline-csp/expected-after-patch.js`, `tests/framework-fixtures/nuxt-csp/expected-after-patch.ts`.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the user said "no" to the CSP patch and later reports live not working: their dev CSP blocks `http://localhost:8400`. Delete `cspChecked` from `.impeccable/live/config.json` and re-run `live.mjs`; setup asks again.
|
||||
|
||||
After setup, re-run `live.mjs`.
|
||||
@@ -2,50 +2,33 @@ Interactive live variant mode: select elements in the browser, pick a design act
|
||||
|
||||
## Prerequisites
|
||||
|
||||
A running dev server with hot module replacement (Vite, Next.js, Bun, etc.), OR a static HTML file open in the browser.
|
||||
A running dev server with HMR (Vite, Next.js, Bun, etc.), OR a static HTML file open in the browser. If the dev server's default port is busy, the app is very likely ALREADY running; probe the default URL before spawning a second server.
|
||||
|
||||
## The contract (read once)
|
||||
|
||||
Execute in order. No step skipped, no step reordered.
|
||||
Execute in order. No step skipped, no step reordered. Every tool output in live mode may carry an `_instructions` field: it is the authoritative next step for that exact situation, with real ids and paths substituted; when it conflicts with your recollection of this document, `_instructions` wins.
|
||||
|
||||
1. `live.mjs`: boot. If the request names or implies a file, route, or app inside a monorepo, infer the concrete path and run `node .claude/skills/impeccable/scripts/live.mjs --target <path>` instead; then run the rest of this live session from the returned `projectRoot`.
|
||||
1. `live.mjs`: boot. If the request names or implies a file, route, or app inside a monorepo, infer the concrete path and run `node .claude/skills/impeccable/scripts/live.mjs --target <path>` instead; then run the rest of this live session from the returned `projectRoot`. The boot resolves the app root from dev-server config files and persists it in `.impeccable/live/roots.json`; every helper re-anchors to that manifest at startup (a wrong cwd cannot fork session state), PRODUCT.md / DESIGN.md are discovered upward to the git root, and relative helper args like `--file` resolve against the app root.
|
||||
2. Open the app URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). Never use `serverPort`; it's the helper, not the app. **Cursor:** `browser_navigate` to that URL before polling; do not skip. **Other harnesses:** use the available browser tool; if the URL is uncertain, ask the user once.
|
||||
3. Poll loop with the default long timeout (600000 ms). Run `live-poll.mjs` again immediately after every event or `--reply`; Codex runs this one-shot poll in the foreground. Never pass a short `--timeout=`.
|
||||
|
||||
The global bar **Impeccable mark** dims and shows a pulsing amber dot when no agent is long-polling `/poll`. Hover the mark for the hint; restart `live-poll.mjs` to reconnect.
|
||||
4. On `generate`: reuse `event.scaffold` when present; read the screenshot if present; load the action's reference; deliver variants using the delivery policy below; `--reply done`; poll again. Generate in this thread. You already hold the project's tokens, conventions, and file layout; that context is the job, not overhead. During a live cycle the overlay's preview IS the verification channel: the user sees every variant rendered in their real page and picks. Do not screenshot, re-render, or QA variants between generate and accept; apply craft-floor's contrast, spacing, and type floors by construction as you write, not as a post-write inspection pass. Full verification, computed contrast, breakpoints, real-copy overflow, runs once at accept on the chosen variant during carbonize cleanup.
|
||||
5. On `steer`: read the message and `pageUrl`; do the work (page edits, navigation help, or a short reply in the `--reply` message); `--reply steer_done`; poll again. No pickup ack. The Steer bar unlocks when `steer_done` arrives over SSE.
|
||||
6. On `accept` / `discard`: the poll script runs `live-accept.mjs`, acknowledges the delivered event, and prints `_completionAck`. Plain accepts/discards are terminal immediately. Carbonize accepts remain recoverable until the foreground task runs `live-complete.mjs --id EVENT_ID`; finish that cleanup before polling again.
|
||||
7. If interrupted, run `live-status.mjs` or `live-resume.mjs` before guessing. The durable journal replays unacknowledged work after helper restart. A dropped SSE connection or a closed tab does not end the session: the journal under `.impeccable/live/sessions/` is canonical, the injected `live.js` re-attaches when the page reopens, and `live-resume.mjs` replays the active snapshot. Tell the user to reopen the app URL (or restart `live-poll.mjs`) and continue; fall back to the direct-edit loop only when `live-resume.mjs` reports no active session, never because disconnects felt frequent.
|
||||
3. Poll loop with the default long timeout (600000 ms). Run `live-poll.mjs` again immediately after every event or `--reply`; Codex runs this one-shot poll in the foreground. Never pass a short `--timeout=`. The global bar's **Impeccable mark** dims with a pulsing amber dot when nothing is polling `/poll`; restart `live-poll.mjs` to reconnect.
|
||||
4. On `generate`: reuse `event.scaffold` when present; read the screenshot if present; load the action's reference; deliver variants; `--reply done`; poll again. Generate in this thread: you already hold the project's tokens and layout. The overlay preview IS the verification channel; do not screenshot, re-render, or QA variants between generate and accept. Apply craft-floor's contrast, spacing, and type floors by construction as you write; full verification runs once at accept on the chosen variant.
|
||||
5. On `steer`: read the message and `pageUrl`; do the work; `--reply steer_done`; poll again. No pickup ack.
|
||||
6. On `accept` / `discard`: the poll script runs `live-accept.mjs`, acknowledges delivery, and prints `_completionAck`. Plain accepts/discards are terminal immediately; carbonize accepts stay recoverable until `live-complete.mjs --id EVENT_ID` runs. Finish that cleanup before polling again.
|
||||
7. If interrupted, run `live-status.mjs` or `live-resume.mjs` before guessing. The journal under `.impeccable/live/sessions/` is canonical and replays unacknowledged work after a helper restart; the injected `live.js` re-attaches when the page reopens. Fall back to the direct-edit loop only when `live-resume.mjs` reports no active session, never because disconnects felt frequent.
|
||||
8. On `exit`: run the cleanup at the bottom.
|
||||
|
||||
Harness policy:
|
||||
- **Claude Code**: run the poll as a **background task** (no short timeout). The harness notifies you when it completes, so the main conversation stays free while you generate and publish in it. Do not block the shell.
|
||||
- **Cursor**: run **one-shot** poll in a **background terminal** with notify on `"type":"(steer|generate|accept|discard|exit)"`. After each event the poll exits; handle it, `--reply`, then start `live-poll.mjs` again. Do **not** use `--stream` on Cursor: incremental stdout notify is slower in practice than exit-based notify (~5s vs sub-second in testing).
|
||||
- **Codex**: run the default one-shot poll in a **yielded foreground exec session**. Do not suffix it with `&`, use `--stream`, or leave Live without an active foreground poll. Handle every event in the main task; after each handler/reply, restart the foreground poll.
|
||||
- **Other harnesses**: one-shot foreground unless you know stdout reliably returns to this session when a shell exits.
|
||||
- **Claude Code**: run the poll as a **background task** (no short timeout); the harness notifies you on completion. Do not block the shell.
|
||||
- **Cursor**: **one-shot** poll in a **background terminal** with notify on `"type":"(steer|generate|accept|discard|manual_edit_apply|variant_mount_failed|prefetch|exit)"`; handle, `--reply`, restart the poll. Do **not** use `--stream` on Cursor (measured ~5s pickup vs sub-second one-shot).
|
||||
- **Codex**: default one-shot poll in a **yielded foreground exec session**. No `&`, no `--stream`, never leave Live without an active foreground poll. Starting the poll is not enough: SERVICE it (keep reading the exec session until it returns an event). Never announce "waiting for the user" and idle; a yielded poll nobody reads is a dead session, and the user's Go sits unanswered.
|
||||
- **Other harnesses**: one-shot foreground unless you know stdout reliably returns when a shell exits.
|
||||
|
||||
Generation delivery policy:
|
||||
- **Default (Cursor and other harnesses):** keep the established atomic single-edit delivery. Do not switch a harness to progressive until its poll loop is known not to block on the extra publish calls. This avoids trading model latency for extra tool-call latency on harnesses with different streaming behavior.
|
||||
Delivery policy: atomic single-edit delivery everywhere; do not switch a harness to progressive publishing unless its poll loop is known not to block on the extra calls.
|
||||
|
||||
Chat is overhead. No recap, no tutorial output, no pasting PRODUCT / DESIGN bodies. Spend tokens on tools and edits; on failure, one or two short sentences.
|
||||
|
||||
## Start
|
||||
|
||||
```bash
|
||||
node .claude/skills/impeccable/scripts/live.mjs
|
||||
```
|
||||
|
||||
Output JSON: `{ ok, serverPort, serverToken, pageFiles, hasProduct, product, productPath, hasDesign, design, designPath }`. `pageFiles` is the list of HTML entries the live script was injected into. Keep PRODUCT.md, DESIGN.md, and any surface brief already loaded by Setup in mind for variant generation: **DESIGN.md wins on visual decisions; PRODUCT.md wins on durable product and voice decisions; the surface brief wins on this surface's strategy.** When DESIGN.md is missing, identity is **not** absent; extract it from CSS variables, computed styles, and sibling components on the page (see Step 4 Phase A). Identity preservation is the default; departure requires the user's explicit redesign/replacement intent.
|
||||
|
||||
`serverPort` and `serverToken` belong to the small **Impeccable live helper** HTTP server (serves `/live.js`, SSE, and `/poll`). That port is **not** your dev server and is usually not the URL you open to view the app. The browser page is whatever origin serves one of the `pageFiles` entries (Vite / Next / Bun / tunnel / LAN hostname).
|
||||
|
||||
If output is `{ ok: false, error: "config_missing" | "config_invalid", path }`, this project hasn't been configured for live mode (or its config is stale). See **First-time setup** at the bottom.
|
||||
|
||||
## Poll loop
|
||||
|
||||
**Default (portable, all harnesses):**
|
||||
|
||||
```
|
||||
LOOP:
|
||||
node .claude/skills/impeccable/scripts/live-poll.mjs # default long timeout; no --timeout=
|
||||
@@ -57,253 +40,143 @@ LOOP:
|
||||
"discard" → Handle Discard; LOOP
|
||||
"prefetch" → Handle Prefetch; LOOP
|
||||
"manual_edit_apply" → Handle Manual Edit Apply; reply done|partial|error; LOOP
|
||||
"variant_mount_failed" → Fix the variant files; reply done --file <path>; LOOP
|
||||
"timeout" → LOOP
|
||||
"exit" → break → Cleanup
|
||||
```
|
||||
|
||||
**Stream mode (experimental, not for Cursor):**
|
||||
`variant_mount_failed` means the browser could not render what you published (`variant`, module `url`, `error`). The user sees a persistent error card, not variants. Fix the variant files, then `--reply EVENT_ID done --file <manifest or source path>`; the browser retries on its own.
|
||||
|
||||
```
|
||||
node .claude/skills/impeccable/scripts/live-poll.mjs --stream # stays running; one JSON line per event
|
||||
Handle event; run --reply in a separate command
|
||||
Repeat until "exit" line → Cleanup
|
||||
**Stream mode** (`--stream`, experimental, never on Cursor): one long-lived process, one JSON line per event, `--reply` from a separate command. Only for harnesses that read incremental stdout reliably.
|
||||
|
||||
## Start
|
||||
|
||||
```bash
|
||||
node .claude/skills/impeccable/scripts/live.mjs
|
||||
```
|
||||
|
||||
Stream keeps one process alive and waits for `--reply` ack before polling again. Useful only when the harness reads incremental stdout reliably and quickly. **Cursor is not one of those:** background pattern notify on a long-running shell was ~5s to pick up events vs sub-second for one-shot exit notify. Default to one-shot everywhere unless you have measured otherwise.
|
||||
Output JSON: `{ ok, serverPort, serverToken, pageFiles, roots, hasProduct, product, productPath, hasDesign, design, designPath, hasSurfaceBrief, surfaceBrief }`. `roots` is the resolved root manifest; `projectRoot` mirrors `roots.appRoot`. The surface brief rides along; do not shell out to `surface-brief.mjs` separately. Precedence for generation: **DESIGN.md wins on visual decisions; PRODUCT.md wins on durable product and voice decisions; the surface brief wins on this surface's strategy.** When DESIGN.md is missing, identity is **not** absent; extract it from CSS variables, computed styles, and sibling components (Step 4 Phase A). Identity preservation is the default; departure requires the user's explicit redesign intent.
|
||||
|
||||
`serverPort`/`serverToken` belong to the small helper HTTP server (`/live.js`, SSE, `/poll`), not your dev server; the page URL is whatever origin serves a `pageFiles` entry.
|
||||
|
||||
If output is `{ ok: false, error: "config_missing" | "config_invalid", path }`, this project needs one-time configuration: read [live-setup.md](live-setup.md) and follow it. If the output carries a non-null `configDrift`, tell the user once which HTML files are uncovered and suggest adding them or switching `files` to a glob; never auto-edit the config.
|
||||
|
||||
## Recovery commands
|
||||
|
||||
The live helper persists an append-only journal under `.impeccable/live/sessions/`. Browser checkpoints are advisory but durable; the journal is canonical. This is local durable recovery state, not project source.
|
||||
|
||||
Use these commands when the chat was interrupted, polling was missed, the helper restarted, or the browser reloaded:
|
||||
The append-only journal under `.impeccable/live/sessions/` is canonical durable state (not project source). When the chat was interrupted, polling was missed, the helper restarted, or the browser reloaded:
|
||||
|
||||
```bash
|
||||
node .claude/skills/impeccable/scripts/live-status.mjs
|
||||
node .claude/skills/impeccable/scripts/live-resume.mjs --id SESSION_ID
|
||||
node .claude/skills/impeccable/scripts/live-complete.mjs --id SESSION_ID
|
||||
node .claude/skills/impeccable/scripts/live-status.mjs # helper state, active sessions, queued events; works with the helper down
|
||||
node .claude/skills/impeccable/scripts/live-resume.mjs --id SESSION_ID # active snapshot, pending event, next safe action
|
||||
node .claude/skills/impeccable/scripts/live-complete.mjs --id SESSION_ID # canonical manual final acknowledgement after verified cleanup
|
||||
```
|
||||
|
||||
- `live-status.mjs` prints connected helper state, active durable sessions, and queued pending events. It works even when the helper is down by reading the journal directly.
|
||||
- `live-resume.mjs` prints the active snapshot, pending event, checkpoint phase, visible variant, parameter values, and the next safe agent action.
|
||||
- `live-complete.mjs` is the canonical manual final acknowledgement. Use it after carbonize/manual cleanup is verified and no further poll acknowledgement will happen automatically.
|
||||
|
||||
Server restart rule: start `live-server.mjs` again, then poll. Startup requeues unacknowledged pending events from the journal, so do not ask the user to click Go again unless `live-resume.mjs` says no active session exists.
|
||||
Server restart rule: start `live-server.mjs` again, then poll; startup requeues unacknowledged events, so never ask the user to click Go again unless `live-resume.mjs` says no active session exists.
|
||||
|
||||
## Handle `generate`
|
||||
|
||||
**Replace mode** (default): `{id, action, freeformPrompt?, count, pageUrl, element, screenshotPath?, comments?, strokes?}`.
|
||||
|
||||
**Insert mode** (`event.mode === "insert"`): `{id, mode: "insert", count, pageUrl, insert: { position, anchor }, placeholder: { width, height }, freeformPrompt?, screenshotPath?, comments?, strokes?}`. No `action`. Requires a non-empty `freeformPrompt` **or** annotations. Screenshot is sent only when annotations exist (same rule as replace). Use `placeholder` dimensions as a soft size hint for net-new content.
|
||||
**Insert mode** (`event.mode === "insert"`): `{id, mode: "insert", count, pageUrl, insert: { position, anchor }, placeholder: { width, height }, freeformPrompt?, screenshotPath?, comments?, strokes?}`. No `action`; requires a non-empty `freeformPrompt` **or** annotations. `placeholder` is a soft size hint.
|
||||
|
||||
Speed matters; the user is watching the selected element. Reuse server preflight metadata when available, minimize discovery calls, and follow the harness-specific delivery policy above.
|
||||
Speed matters; the user is watching the selected element. Reuse preflight metadata, minimize discovery calls.
|
||||
|
||||
### Insert mode branch
|
||||
|
||||
When `event.mode === "insert"`:
|
||||
|
||||
1. Read the screenshot if `event.screenshotPath` is present (annotations only).
|
||||
2. If `event.scaffold` is present, use it as the insert-helper result and do **not** run the helper again. Otherwise run the insert helper instead of wrap:
|
||||
1. Read the screenshot if present (annotations only).
|
||||
2. If `event.scaffold` is present, use it and do **not** run the helper again. Otherwise:
|
||||
|
||||
```bash
|
||||
node .claude/skills/impeccable/scripts/live-insert.mjs --id EVENT_ID --count EVENT_COUNT --position after \
|
||||
--element-id "ANCHOR_ID" --classes "class1,class2" --tag "section" --text "ANCHOR_TEXT"
|
||||
```
|
||||
|
||||
- `--position` ← `event.insert.position` (`before` | `after`)
|
||||
- Anchor flags ← `event.insert.anchor` (same mapping as wrap: id, classes, tag, text)
|
||||
|
||||
The scaffold has **no** `data-impeccable-variant="original"`. Variants are net-new HTML+CSS inserted at `insertLine`. On source-preview targets the scaffold carries `sourceWritten: false` with `wrapperBlock`, `replaceStartLine`, and `replaceEndLine` (here `replaceEndLine < replaceStartLine`, an insertion): splice your variants into `wrapperBlock` at the marker and insert the result at `replaceStartLine` in one edit, exactly as the wrap section describes, so the framework reloads once. Decide the visitor mode from the surface and load [craft-floor.md](craft-floor.md) before writing net-new markup (freeform only, no action sub-command). Deliver using the harness policy, then `--reply done`.
|
||||
|
||||
For Svelte/SvelteKit targets, `live-insert.mjs` returns `previewMode: "svelte-component"` with `mode: "insert"`, `file` pointing at a temporary `node_modules/.impeccable-live/<id>/manifest.json`, `componentDir` pointing at the variant component files, and `sourceFile` pointing at the real `.svelte` route. Write each inserted variant as a real Svelte component (`v1.svelte`, `v2.svelte`, …) under `componentDir`. Insert variants must be non-empty net-new content with a single top-level root, no `data-impeccable-*` attributes, and CSS in each component's `<style>` block. Do **not** edit the route source during generation; the browser mounts the temporary component before/after the live anchor while the user cycles variants. On Accept, `live-accept.mjs` inserts the selected component markup into `sourceFile` immediately and deletes the temp session after the source write succeeds.
|
||||
|
||||
For non-Svelte targets, on accept/discard, `live-accept.mjs` removes the wrapper block; the anchor element is untouched.
|
||||
`--position` ← `event.insert.position`; anchor flags map exactly like wrap's. The scaffold has **no** `data-impeccable-variant="original"`; variants are net-new HTML+CSS at `insertLine`. On source-preview targets the scaffold carries `sourceWritten: false` with `wrapperBlock` and `replaceEndLine < replaceStartLine` (an insertion): splice variants into `wrapperBlock` at the marker and insert at `replaceStartLine` in ONE edit, exactly as the wrap section describes. Decide the visitor mode from the surface and load [craft-floor.md](craft-floor.md) before writing net-new markup. Svelte targets follow the same component flow as wrap below (`mode: "insert"` in the manifest): each variant is a real single-root component under `componentDir` with no `data-impeccable-*` attributes; never edit the route during generation; accept splices the chosen markup into `sourceFile` mechanically. For non-Svelte targets, accept/discard removes the wrapper; the anchor is untouched.
|
||||
|
||||
### Replace mode (default)
|
||||
|
||||
### 1. Read the screenshot (if present)
|
||||
|
||||
`event.screenshotPath` is **only sent when the user placed at least one comment or stroke before Go.** When present, it's an absolute path to a PNG of the element as rendered with the annotations baked in. **Read it before planning**: annotations encode user intent not recoverable from `element.outerHTML` alone.
|
||||
`event.screenshotPath` is sent **only when the user annotated before Go**; it is a PNG of the element with annotations baked in. Read it before planning. When absent, do not ask for one or screenshot the page yourself: without annotations a screenshot anchors you on the existing design and fights the three-distinct-directions brief; work from `element.outerHTML`, the computed styles, and the prompt.
|
||||
|
||||
When `screenshotPath` is absent, don't ask for one and don't go looking for the current rendering. The omission is deliberate: without annotations, a screenshot would anchor the model on the existing design and fight the three-distinct-directions brief. Work from `element.outerHTML`, the computed styles in `event.element`, and the freeform prompt if present.
|
||||
|
||||
`event.comments` and `event.strokes` carry structured metadata alongside the visual. Treat the screenshot as primary; use the structured data for specifics worth quoting (e.g. the exact text of a comment).
|
||||
|
||||
Reading annotations precisely:
|
||||
|
||||
- **Comment position carries meaning.** Its `{x, y}` is element-local CSS px (same coord space as `element.boundingRect`). Find the child under that point and apply the comment text LOCALLY to that sub-element. A comment near the title is about the title, not a global description.
|
||||
- **Comments and strokes are independent annotations** unless clearly paired by overlap or tight proximity. Don't let the visual weight of a prominent stroke override the precise location of a textually-specific comment elsewhere.
|
||||
- **Strokes are gestures; read them by shape.** Closed loop = "this thing" (emphasis / focus); arrow = direction (move / point to); cross or slash = delete; free scribble = emphasis or delete depending on context. A loop around region X means "pay attention to X," not "only change pixels inside X."
|
||||
- **When a stroke's intent is ambiguous** (circle or arrow? emphasis or move?), state your reading in one sentence of rationale rather than silently guessing. If the uncertainty materially changes the brief, ask one short clarifying question before generating.
|
||||
Annotation semantics: a comment's `{x, y}` is element-local and binds the text to the child under that point (a comment near the title is about the title). Comments and strokes are independent unless clearly paired. Strokes read by shape: closed loop = "this thing" (emphasis, not a clipping region); arrow = direction or movement; cross/slash = delete; scribble = emphasis or delete by context. If a stroke's intent is genuinely ambiguous and it changes the brief, ask one short question before generating; otherwise state your reading in one sentence.
|
||||
|
||||
### 2. Wrap the element
|
||||
|
||||
When `event.scaffold` is present, the local helper already found the source and computed the wrapper before the poll returned. Treat `event.scaffold` as the successful helper output and skip this command entirely. `event.scaffoldAttempted` with `scaffoldError` means local preflight could not finish; use the command/fallback path below. This optimization removes a deterministic tool round trip without changing the generated design.
|
||||
When `event.scaffold` is present, the helper already found the source and computed the wrapper; treat it as the successful output and skip the command. `event.scaffoldAttempted` with `scaffoldError` means preflight could not finish; use the command below.
|
||||
|
||||
**On source-preview targets `event.scaffold` carries `sourceWritten: false`.** The helper did NOT write the wrapper into source; it hands you the wrapper as `scaffold.wrapperBlock` plus the picked element's source range (`scaffold.replaceStartLine`, `scaffold.replaceEndLine`, 1-indexed). Write the wrapper **and** all variants in ONE edit: splice your variants into `wrapperBlock` at the "Variants: insert below this line" marker, then replace source lines `[replaceStartLine, replaceEndLine]` with the result. A separate scaffold write reloads the framework before your variant write lands, and a browser caught mid-reload misses the `done` and sits at 0/N; the single edit avoids it. (`replaceEndLine < replaceStartLine` means insert mode: insert `wrapperBlock`, remove nothing.) The `svelte-component` path never sets `sourceWritten`; it follows the component-preview flow below unchanged.
|
||||
**On source-preview targets `event.scaffold` carries `sourceWritten: false`.** The helper did NOT write the wrapper; it hands you `scaffold.wrapperBlock` plus the picked element's source range (`replaceStartLine`, `replaceEndLine`, 1-indexed). Write the wrapper **and** all variants in ONE edit: splice your variants into `wrapperBlock` at the "Variants: insert below this line" marker, then replace lines `[replaceStartLine, replaceEndLine]` with the result. A separate scaffold write reloads the framework before your variant write lands and strands the browser at 0/N. (`replaceEndLine < replaceStartLine` means insert mode: insert, remove nothing.) The `svelte-component` path never sets `sourceWritten`.
|
||||
|
||||
```bash
|
||||
node .claude/skills/impeccable/scripts/live-wrap.mjs --id EVENT_ID --count EVENT_COUNT --element-id "ELEMENT_ID" --classes "class1,class2" --tag "div" --text "TEXT_SNIPPET"
|
||||
```
|
||||
|
||||
Flag mapping. Keep them separate, don't collapse into `--query`:
|
||||
Flag mapping (keep separate, never collapse into `--query`): `--element-id` ← `event.element.id`; `--classes` ← classes joined with commas; `--tag` ← tagName; `--text` ← first ~80 chars of textContent, **every call**: it disambiguates repeated sibling components, without it wrap lands on the first match. If `event.pageUrl` implies the file, pass `--file PATH`. If `--text` still matches several candidates, wrap exits `{ error: "element_ambiguous", candidates, fallback: "agent-driven" }`: pick the right range from page context and write the wrapper manually per the fallback flow.
|
||||
|
||||
- `--element-id` ← `event.element.id`
|
||||
- `--classes` ← `event.element.classes` joined with commas
|
||||
- `--tag` ← `event.element.tagName`
|
||||
- `--text` ← first ~80 chars of `event.element.textContent` (trim, single-line). **Pass this every call.** When the picked element shares classes + tag with sibling components (a list of `<Card>`s, repeating sections), this is what disambiguates which branch in source to wrap. Without it, wrap silently lands on the first match and may rewrite the wrong element.
|
||||
Success output: `{ file, insertLine, commentSyntax, styleMode, styleTag, cssSelectorPrefixExamples, cssAuthoring }` (plus the `sourceWritten: false` fields above on source-preview targets). Run directly with no preflight scaffold, it writes the wrapper itself and you splice variants at `insertLine`. `styleMode` controls how preview CSS must be authored. Treat it as a detected capability mode, not a framework guess: `scoped` means `@scope ([data-impeccable-variant="N"])` rules; `astro-global-prefixed` means explicit `[data-impeccable-variant="N"]` prefixes with the exact returned `styleTag`. Use `cssAuthoring` as the source of truth for the current file (styleTag, selector strategy, requirements, forbidden patterns); apply no framework-specific exception unless it says to.
|
||||
|
||||
The helper searches ID first, then classes, then tag + class combo. If `event.pageUrl` implies the file (e.g. `/` is usually `index.html`), pass `--file PATH` to skip the search. `--query` is a fallback for raw text search only; do not use it for normal element lookups.
|
||||
For Svelte/SvelteKit targets, `live-wrap.mjs` returns `previewMode: "svelte-component"` with `file` pointing at a temporary `node_modules/.impeccable-live/<id>/manifest.json`, `componentDir` holding the variant components, and `sourceFile` the real route. The scaffold is AST-based: control-flow blocks (`{#each}`, `{#if}`) survive intact and a free each-collection crosses the contract as ONE structured prop (kind `collection`). The payload includes `componentStubMarkup` (the prop-substituted markup already written into every stub), so do not read the manifest or stubs back. EDIT `v1.svelte`, `v2.svelte`, ... in place; never delete and recreate them; keep the stub's control flow and `propContract` prop names; never flatten a loop into literal items. The stub `<style>` arrives seeded with the source rules that currently style the selection; restyle or delete them freely. On accept, any seeded rule your variant does not re-declare is REMOVED from the source (the preview never applied it, so the user approved a design without it). Use semantic class selectors, no `@scope`, no `data-impeccable-*`. Reply with `--file` set to the manifest path; the browser mounts the compiled components so Svelte HMR does not reset page state. Accept merges the chosen component back mechanically (markup restored to route expressions, CSS reconciled, params baked, indentation preserved); you have no post-accept cleanup on this path. When the selection contains constructs a detached preview cannot support (component tags, `bind:`/`use:`, await blocks, inline scripts, spread attributes), wrap returns the normal source-preview wrapper with `previewFallback: { from: "svelte-component", reason }`; just follow the returned shape.
|
||||
|
||||
If `--text` matches multiple candidates equally well, wrap exits with `{ error: "element_ambiguous", candidates: [...] }` and `fallback: "agent-driven"`: read the candidate line ranges, decide which one matches the picked element from page context, and write the wrapper manually per the fallback flow.
|
||||
|
||||
Output on success: `{ file, insertLine, commentSyntax, styleMode, styleTag, cssSelectorPrefixExamples, cssAuthoring }`. On source-preview targets it also returns `sourceWritten: false`, `wrapperBlock`, `replaceStartLine`, and `replaceEndLine` (write it yourself per the `event.scaffold` note above). When you run this command directly (no preflight scaffold), it writes the wrapper into source itself, so there is no `wrapperBlock` and you splice variants at `insertLine`.
|
||||
|
||||
For Svelte/SvelteKit targets, `live-wrap.mjs` returns `previewMode: "svelte-component"` with `file` pointing at a temporary `node_modules/.impeccable-live/<id>/manifest.json`, `componentDir` pointing at the variant component files, and `sourceFile` pointing at the real `.svelte` route. Write each variant as a real Svelte component (`v1.svelte`, `v2.svelte`, …) under `componentDir`; use the `propContract` prop names for dynamic text (`{propName}`), not literal snapshot strings. Put variant CSS in each component's `<style>` block with semantic class selectors (no `@scope`, no `data-impeccable-*`). Reply with `--file` set to the manifest path; the browser dynamically imports and mounts the compiled components so Svelte HMR does not reset page state while the user cycles variants. On Accept, `live-accept.mjs` inlines the accepted component back into `sourceFile` immediately after source promotion succeeds.
|
||||
|
||||
**Params on component-preview paths go in a sidecar, never as an attribute.** Svelte parses `{` inside an attribute value as the start of an expression, and both Svelte/Vue previews mount without an HTML variant wrapper. Declare params in `componentDir/params.json`, keyed by variant number, using the exact param schema from section 7:
|
||||
**Params on component-preview paths go in a sidecar, never as an attribute** (Svelte parses `{` in attribute values as an expression). Declare them in `componentDir/params.json` keyed by variant number, using the schema from section 7:
|
||||
|
||||
```json
|
||||
{
|
||||
"1": [
|
||||
{"id":"density","kind":"steps","default":"snug","label":"Density","options":[
|
||||
{"value":"airy","label":"Airy"},{"value":"snug","label":"Snug"},{"value":"packed","label":"Packed"}
|
||||
]}
|
||||
],
|
||||
"2": [
|
||||
{"id":"accent","kind":"range","min":0,"max":1,"step":0.05,"default":0.5,"label":"Accent"}
|
||||
]
|
||||
}
|
||||
{ "1": [ {"id":"density","kind":"steps","default":"snug","label":"Density","options":[
|
||||
{"value":"airy","label":"Airy"},{"value":"snug","label":"Snug"} ]} ] }
|
||||
```
|
||||
|
||||
Author the component `<style>` against `var(--p-<id>, default)` for `range`/`toggle` and `[data-p-<id>="…"]` for `steps`; wrap those selectors in `:global(...)` so the knob values the runtime sets on the mounted root reach your rules. The browser reads `params.json`, docks the panel, and drives `--p-*` / `data-p-*` on the mounted component exactly as it does for the HTML/JSX path.
|
||||
Author the component `<style>` against `var(--p-<id>, default)` for `range`/`toggle` and `[data-p-<id>="…"]` for `steps`, wrapped in `:global(...)` so runtime knob values on the mounted root reach your rules.
|
||||
|
||||
`styleMode` controls how preview CSS must be authored. Treat it as a detected capability mode, not a framework guess:
|
||||
|
||||
- `scoped`: use `@scope ([data-impeccable-variant="N"])` rules.
|
||||
- `astro-global-prefixed`: use explicit `[data-impeccable-variant="N"]` selector prefixes and the exact `styleTag` returned by the tool.
|
||||
|
||||
Use `cssAuthoring` as the source of truth for the current file. It includes the exact `styleTag`, selector strategy, selector examples, requirements, and forbidden patterns. Do not apply a framework-specific exception unless the returned `styleMode` / `cssAuthoring.mode` says to.
|
||||
|
||||
**Fallback errors.** Wrap only writes into files it judges to be source (tracked by git, not marked GENERATED, not listed in config's `generatedFiles`). If it can't land on a source file, it errors without writing; accepting a variant into a generated file is silent data loss. Three shapes:
|
||||
|
||||
- `{ error: "file_is_generated", file, hint }`: user-supplied `--file` points at a generated file.
|
||||
- `{ error: "element_not_in_source", generatedMatch, hint }`: element exists only in a generated file (the next build would wipe any edits).
|
||||
- `{ error: "element_not_found", hint }`: element isn't in any project file; likely runtime-injected (JS component, dynamic render from data).
|
||||
|
||||
All three carry `fallback: "agent-driven"`. Follow **Handle fallback** below.
|
||||
**Fallback errors.** Wrap refuses to write into non-source files (generated, untracked): accepting into one is silent data loss. Three shapes, all with `fallback: "agent-driven"` (see **Handle fallback**): `file_is_generated` (your `--file` points at a generated file), `element_not_in_source` with `generatedMatch` (element only exists generated), `element_not_found` (likely runtime-injected).
|
||||
|
||||
### 3. Load the action's reference
|
||||
|
||||
If `event.action` is `impeccable` (the default freeform action), work from SKILL.md's design rules plus [craft-floor.md](craft-floor.md), and decide the visitor mode from the selected surface. Do not load a sub-command reference. **Freeform is not a pass to skip parameters:** you still follow the composition budget and the freeform bias in **§7 Parameters** below. Sub-command files list MUST-have signature knobs; freeform has no such file, so sizing knobs from surface weight and primary axes is entirely on you.
|
||||
|
||||
Any other `event.action` (`bolder`, `quieter`, `distill`, `polish`, `typeset`, `colorize`, `layout`, `adapt`, `animate`, `delight`, `overdrive`): Read `reference/<action>.md` before planning. Each sub-command encodes a specific discipline; skipping its reference produces generic output. Those files may require specific params; layer them on top of the §7 budget, not instead of it.
|
||||
`event.action` is `impeccable` (freeform): work from SKILL.md's design rules plus [craft-floor.md](craft-floor.md); decide the visitor mode from the surface; do not load a sub-command reference. Freeform is not a pass to skip parameters: follow the budget and freeform bias in section 7. Any other action (`bolder`, `quieter`, `distill`, `polish`, `typeset`, `colorize`, `layout`, `adapt`, `animate`, `delight`, `overdrive`): read `reference/<action>.md` before planning; its MUST params layer on top of the section 7 budget.
|
||||
|
||||
### 4. Plan three variants: identity first, then mode, then axes
|
||||
|
||||
The wrong frame for live mode is "show three different design directions." Live runs on an existing surface; the brand has already been chosen. The job is variation **within identity**, not selection between identities. Failure mode: three editorial-typographic variants on a brief that wasn't editorial. Bigger failure mode: three off-brand variants the user can't accept because they don't look like their product.
|
||||
|
||||
Four phases. Do them in order.
|
||||
Live runs on an existing surface; the brand is already chosen. The job is variation **within identity**, not selection between identities. The worst failure is three off-brand variants the user cannot accept. Four phases, in order.
|
||||
|
||||
#### Phase A: Extract the identity (non-skippable)
|
||||
|
||||
The existing surface has an identity already. Read it before planning anything. Sources, in priority order:
|
||||
|
||||
1. **DESIGN.md** if loaded: read the visual system fields (palette, type pairing, motion, components). This is the authoritative answer.
|
||||
2. **CSS custom properties** in the page's stylesheets (`:root { --color-...; --font-...; ... }`): these are de-facto tokens.
|
||||
3. **Computed styles** on the picked element and its parent: colors, fonts, spacing scales, corner radii.
|
||||
4. **Sibling components on the page**: what visual rhetoric do existing components use? (Asymmetric or centered? Dense or airy? Bold or quiet?)
|
||||
|
||||
Write down what you see in **one sentence**. The sentence describes the surface that's actually on screen; it is not aspirational, not opinionated, not edited toward what the brand "should" be. Capture, in roughly this order:
|
||||
|
||||
- The dominant surface color and accent color, by hex or token name (use the actual values, not categories like "warm" or "neutral").
|
||||
- The type pairing: the actual font names loaded, primary first.
|
||||
- The layout topology: how the dominant elements are arranged (stacked / side-by-side / grid / asymmetric / overlay).
|
||||
- The surface treatment: corners, borders, shadows, density of decoration.
|
||||
- The voice tone you read off the copy itself, not off the aesthetic feel.
|
||||
|
||||
Be specific. "Modern" is not a color, "elegant" is not a type pairing, "clean" is not a layout. If you can't extract a real value for an axis, skip it rather than fabricate. The point is to record what is, not to describe what you wish it were.
|
||||
|
||||
Do not name an aesthetic family in this sentence; that is a conclusion, not observed identity data. Letting conclusions into Phase A collapses the identity lock into a self-fulfilling prophecy.
|
||||
|
||||
This sentence is the **identity lock**. Every variant must be readable as the same brand if rendered side by side. Skipping this phase is the primary cause of off-brand variants. Absence of DESIGN.md is never an excuse; extract from CSS and computed styles instead.
|
||||
Sources in priority order: DESIGN.md's visual system fields; CSS custom properties (de-facto tokens); computed styles on the picked element and parent; sibling components' visual rhetoric. Write ONE sentence recording what is actually on screen: dominant surface and accent color (real values, not "warm"), the loaded font pairing, layout topology (stacked / side-by-side / grid / asymmetric / overlay), surface treatment (corners, borders, shadows, decoration density), and the voice tone read off the copy. Be specific; skip an axis rather than fabricate; do not name an aesthetic family (a conclusion, not data). This sentence is the **identity lock**: every variant must read as the same brand side by side. Absence of DESIGN.md is never an excuse.
|
||||
|
||||
#### Phase B: Pick mode (default vs departure)
|
||||
|
||||
**Default mode**: the existing identity is preserved. Variants vary expression axes within it. *This is the right mode for ~90% of live sessions.* The user picked an element on a real product they're shipping; they expect variants of *their* hero, not three different brands' heroes.
|
||||
|
||||
**Departure mode**: the existing identity is rejected. Variants propose alternatives consistent with durable product and brand truth. Trigger only when the user explicitly asks for departure in the current request or freeform prompt ("redesign this", "rebuild this from scratch", "what if it weren't editorial at all", "show me something completely different"). A stale page critique or an old task note is not replacement authorization.
|
||||
|
||||
If you're unsure, you're in default mode. The cost of being wrong about default is "three on-brand variants with similar feel": recoverable, the user picks none. The cost of being wrong about departure is "three off-brand variants": unrecoverable, the user is annoyed.
|
||||
**Default** preserves the identity and varies expression within it; right for ~90% of sessions. **Departure** rejects the identity; trigger ONLY on the user's explicit ask in the current request or prompt ("redesign this", "rebuild from scratch", "something completely different"); a stale critique or old note is not authorization. Unsure means default: wrong-default costs "three on-brand variants with similar feel" (recoverable), wrong-departure costs three off-brand variants (unrecoverable).
|
||||
|
||||
#### Phase C: Plan three variants
|
||||
|
||||
**Default mode.** Each variant commits to a different **primary axis** of difference, while preserving the identity sentence. The six axes:
|
||||
**Default mode.** Each variant commits to a different **primary axis**, preserving the identity sentence. The six axes: 1 **Hierarchy** (which element commands the eye), 2 **Layout topology** (stacked / side-by-side / grid / asymmetric / overlay), 3 **Typographic system** (pairing logic, scale ratio, case/weight, *within the available faces*), 4 **Color strategy** (which existing palette role carries the surface: Restrained / Committed / Full palette / Drenched; existing tokens only), 5 **Density** (minimal / comfortable / dense), 6 **Structural decomposition** (merge, split, progressive disclosure). Three variants, three DIFFERENT axes: the same brand at three angles. New fonts, new hues, or new aesthetic-family signals belong to departure mode only.
|
||||
|
||||
1. **Hierarchy**: which element commands the eye?
|
||||
2. **Layout topology**: stacked / side-by-side / grid / asymmetric / overlay
|
||||
3. **Typographic system**: pairing logic, scale ratio, case/weight strategy *within the available faces*
|
||||
4. **Color strategy**: which existing palette role carries the surface (Restrained / Committed / Full palette / Drenched). Use the brand's existing palette tokens, not new colors.
|
||||
5. **Density**: minimal / comfortable / dense
|
||||
6. **Structural decomposition**: merge, split, progressive disclosure
|
||||
**Departure mode.** Each variant anchors to a different aesthetic direction derived from the brand, never a fixed catalog: read PRODUCT.md's Brand Personality words; derive physical, spatial, or material experiences that embody them; from those, derive three directions genuinely different from each other AND from the current surface; reject reflex choices whose rationale would fit a neighboring product. Each direction must be one concrete sentence naming a real-world referent ("a museum exhibition label system", not "clean and minimal").
|
||||
|
||||
Three variants → three DIFFERENT axes. The trio reads as *the same brand at three angles*. Do not introduce new fonts, new palette hues, or new aesthetic-family signals; those belong to departure mode.
|
||||
|
||||
**While planning each variant, also name its 2–3 parameter knobs** (per the §7 budget table). Parameters are part of the design, not a decoration added afterward. If the variant explores density, expose a density knob. If it explores color commitment, expose a color-amount range. Deciding "what's tunable" during planning produces better knobs than retrofitting them onto finished HTML.
|
||||
|
||||
**Departure mode.** Each variant anchors to a different **aesthetic direction**, derived from PRODUCT.md's audience world and voice plus the current DESIGN.md. Do not pick from a fixed catalog; derive directions from this product.
|
||||
|
||||
Instead, work from the brand:
|
||||
|
||||
1. Read PRODUCT.md's Brand Personality words. Derive physical, spatial, or material experiences that embody them without starting from a design style.
|
||||
2. From those physical experiences, derive three visual directions that are genuinely different from each other AND from the current surface you're departing.
|
||||
3. Reject any direction chosen by reflex rather than derived from the brand. Start over from the personality words when the rationale could fit a neighboring product.
|
||||
4. Each direction must be expressible in one concrete sentence that names a real-world referent ("a museum exhibition label system for a contemporary art gallery" not "clean and minimal"). If your sentence contains only adjectives, it's not concrete enough.
|
||||
5. **While planning each direction, also name its 2–3 parameter knobs** (per the §7 budget table). The same principle as default mode: decide "what's tunable" during planning, not after writing the HTML. A departure-mode hero with 0 parameters is not "bold creative vision," it's a missed opportunity for the user to fine-tune the direction they pick.
|
||||
**In both modes, name each variant's 2 or 3 parameter knobs while planning** (section 7 budget). Parameters are part of the design; deciding "what's tunable" during planning beats retrofitting.
|
||||
|
||||
#### Phase D: Squint test
|
||||
|
||||
**Default mode squint.** Read each variant's identity sentence and compare to the locked identity from Phase A. If any variant has drifted to a different palette, type voice, or visual rhetoric, it has crossed into departure mode by accident; rework. Then check that each variant commits to a different primary axis. Three "tighter density" variants is failure.
|
||||
**Default:** compare each variant against the Phase A lock; palette, type voice, or rhetoric drift means it crossed into departure by accident: rework. Then confirm three different primary axes; three "tighter density" variants is failure. **Departure:** two passes, family before sentence. Family pass (non-negotiable): label each variant with a concrete family of your own choosing; shared or interchangeable labels mean rework. Sentence pass: three one-line descriptions side by side; two that rhyme mean rework. When the primary axis is color or theme, the trio must not share theme + dominant hue: three color worlds, not three shades.
|
||||
|
||||
**Departure mode squint.** Two passes, family before sentence:
|
||||
**Action-specific invocations** must vary along the action's dimension:
|
||||
|
||||
1. **Family pass.** Give each variant a concrete family label of your own choosing. If two variants share a label, or a label fits another variant equally well, rework. Do not use a fixed vocabulary. *This pass is non-negotiable in departure mode and catches monoculture the sentence pass misses.*
|
||||
2. **Sentence pass.** Write three one-sentence descriptions side by side. If two of them rhyme ("both feature big type" / "both are stacks of sections" / "both center the CTA"), rework the offender.
|
||||
|
||||
**When the primary axis is color or theme, forbid the trio from sharing theme + dominant hue.** Two dark-plus-one-dark is not distinct. Aim for three color worlds, not three shades of the same.
|
||||
|
||||
**For action-specific invocations**, each variant must vary along the dimension the action names:
|
||||
|
||||
- `bolder`: amplify a different dimension per variant (scale / saturation / structural change). Not three "slightly bigger" variants.
|
||||
- `bolder`: amplify a different dimension per variant (scale / saturation / structural change).
|
||||
- `quieter`: pull back a different dimension (color / ornament / spacing).
|
||||
- `distill`: remove a different class of excess (visual noise / redundant content / nested structure).
|
||||
- `polish`: target a different refinement axis (rhythm / hierarchy / micro-details like corner radii, focus states, optical kerning).
|
||||
- `typeset`: different type pairing AND different scale ratio each. Not three riffs on one pairing.
|
||||
- `colorize`: different hue family each (not shades of one hue). Vary chroma and contrast strategy.
|
||||
- `layout`: different structural arrangement (stacked / side-by-side / grid / asymmetric). Not spacing tweaks.
|
||||
- `adapt`: different target context per variant (mobile-first / tablet / desktop / print or low-data). Don't make three mobile layouts.
|
||||
- `animate`: different motion vocabulary (cascade stagger / clip wipe / scale-and-focus / morph / parallax). Not three staggered fades.
|
||||
- `delight`: different flavor of personality (unexpected micro-interaction / typographic surprise / illustrated accent / sonic-or-haptic moment / easter-egg interaction).
|
||||
- `overdrive`: different convention broken (scale / structure / motion / input model / state transitions). Skip `overdrive.md`'s "propose and ask" step; live mode is non-interactive.
|
||||
- `polish`: a different refinement axis (rhythm / hierarchy / micro-details).
|
||||
- `typeset`: different pairing AND different scale ratio each.
|
||||
- `colorize`: different hue family each; vary chroma and contrast strategy.
|
||||
- `layout`: different structural arrangement, not spacing tweaks.
|
||||
- `adapt`: different target context per variant (mobile-first / tablet / desktop / print or low-data).
|
||||
- `animate`: different motion vocabulary (cascade stagger / clip wipe / scale-and-focus / morph / parallax).
|
||||
- `delight`: different flavor of personality (micro-interaction / typographic surprise / illustrated accent / sonic-or-haptic / easter egg).
|
||||
- `overdrive`: different convention broken (scale / structure / motion / input model / state transitions); skip its "propose and ask" step, live is non-interactive.
|
||||
|
||||
### 5. Apply the freeform prompt (if present)
|
||||
|
||||
`event.freeformPrompt` is the user's ceiling on direction (all variants must honor it), but still explore meaningfully different *interpretations*. The interpretations stay within whichever mode you picked in Phase B.
|
||||
|
||||
In **default mode**, the prompt narrows the axes you choose, not the identity. *"Make it feel more confident"* → variant 1 amplifies hierarchy (one element commands the eye), variant 2 commits the existing accent color (Committed strategy on the brand's hue), variant 3 tightens density and removes decorative slack. Three different axes, same brand.
|
||||
|
||||
In **departure mode**, the prompt narrows the lanes you draw from, not the families. *"Make it feel like a newspaper front page"* would itself be a departure-mode prompt; honor it but pick three meaningfully different newspaper-adjacent lanes (broadsheet vs. tabloid vs. trade journal), and run the family pass to confirm they don't collapse into one.
|
||||
|
||||
When the prompt conflicts with a confirmed binding brand commitment or DESIGN.md invariant, preserve the invariant unless the user explicitly revokes or replaces it. Task-local strategy from the matching surface brief may change when the user changes that surface's goal.
|
||||
`event.freeformPrompt` is the user's ceiling on direction: all variants honor it while exploring different interpretations within the Phase B mode. Default mode: the prompt narrows the axes, not the identity ("more confident" → one variant amplifies hierarchy, one commits the accent color, one tightens density). Departure mode: the prompt narrows the lanes, not the families ("newspaper front page" → broadsheet vs tabloid vs trade journal, then run the family pass). When the prompt conflicts with a binding brand commitment or DESIGN.md invariant, preserve the invariant unless the user explicitly revokes it.
|
||||
|
||||
### 6. Deliver variants
|
||||
|
||||
Complete HTML replacement of the original element for each variant, not a CSS-only patch. Consider the element's context (computed styles, parent structure, CSS variables from `event.element`).
|
||||
|
||||
Colocate preview CSS as a `<style>` tag inside the variant wrapper; `<style>` works anywhere in modern browsers and keeps each delivered state internally complete (no FOUC).
|
||||
|
||||
**Atomic default:** write CSS + all variants + parameter manifests in one edit at `insertLine`, preserving the established behavior.
|
||||
|
||||
Use the `cssAuthoring` object returned by `live-wrap.mjs` to author the temporary preview CSS. The style opening tag shown below is the common case; replace it with `cssAuthoring.styleTag` when the tool returns a different one. The variant markup shape is otherwise stable:
|
||||
Complete HTML replacement of the original element per variant, not a CSS-only patch. Colocate preview CSS as a `<style>` tag inside the wrapper. **Atomic default:** CSS + all variants + parameter manifests in one edit at `insertLine`.
|
||||
|
||||
```html
|
||||
<!-- Variants: insert below this line -->
|
||||
@@ -314,92 +187,55 @@ Use the `cssAuthoring` object returned by `live-wrap.mjs` to author the temporar
|
||||
<!-- variant 1: full element replacement (single top-level element) -->
|
||||
</div>
|
||||
<div data-impeccable-variant="2" style="display: none">
|
||||
<!-- variant 2: full element replacement -->
|
||||
<!-- variant 2 -->
|
||||
</div>
|
||||
<div data-impeccable-variant="3" style="display: none">
|
||||
<!-- variant 3: full element replacement -->
|
||||
<!-- variant 3 -->
|
||||
</div>
|
||||
```
|
||||
|
||||
**Each variant div contains exactly one top-level element: the full replacement for the original.** Use the same tag as the original (e.g. `<section>` if the user picked a `<section>`). Loose siblings (heading + paragraph + div as direct children of the variant div) break the outline tracking and the accept flow, which both assume one child.
|
||||
Replace the style opening tag with `cssAuthoring.styleTag` when the tool returns a different one. **Each variant div contains exactly one top-level element**, same tag as the original; loose siblings break outline tracking and accept. First variant visible, all others `display: none`. The browser's MutationObserver accepts atomic or progressive arrival; accepting an arrived variant fences the worker, so later publications are rejected.
|
||||
|
||||
The first variant has no `display: none` (visible by default). All others do. If variants use only inline styles and no preview CSS, omit the `<style>` tag entirely.
|
||||
For `styleMode: "scoped"`, author every `:scope` rule with a descendant combinator: the `@scope` boundary is the variant wrapper div, not your element, so a bare `:scope { ... }` styles a `display: contents` shell. Always step in (`:scope > .card`, `:scope .hero-title`). The fake test agent's CSS in `tests/live-e2e/agent.mjs` is a faithful template.
|
||||
|
||||
The browser's MutationObserver accepts either delivery shape. On the transactional progressive path it shows arrived variants and pending dots immediately; Accept and Discard are available as soon as one variant exists. Accepting an arrived variant fences the worker before the browser releases the picker, so later publications are rejected.
|
||||
|
||||
For `styleMode: "scoped"`, author every `:scope` rule with a descendant combinator. The `@scope` boundary is the **variant wrapper `<div data-impeccable-variant="N">`**, not the element you're designing. A bare `:scope { background: cream; }` styles the wrapper, not the inner replacement, so the cream lands on a `display: contents` shell while the actual element keeps page defaults. Always step in: `:scope > .card`, `:scope > section`, `:scope .hero-title`, etc. The fake test agent's CSS in `tests/live-e2e/agent.mjs` is a faithful template; every scoped rule starts `:scope > ...`.
|
||||
|
||||
**JSX / TSX target files.** Wrap `<style>` content in a template literal so the CSS `{` / `}` aren't parsed as JSX expressions, and use `className=` / `style={{…}}` on every variant element. Keep `data-impeccable-*` attributes as-is; they're plain strings:
|
||||
**JSX / TSX targets:** wrap `<style>` content in a template literal (CSS braces would parse as JSX), use `className=` / `style={{…}}`, keep `data-impeccable-*` attributes as plain strings:
|
||||
|
||||
```tsx
|
||||
<style data-impeccable-css="SESSION_ID">{`
|
||||
@scope ([data-impeccable-variant="1"]) { ... }
|
||||
@scope ([data-impeccable-variant="2"]) { ... }
|
||||
`}</style>
|
||||
<div data-impeccable-variant="1">
|
||||
{/* variant 1 */}
|
||||
</div>
|
||||
<div data-impeccable-variant="2" style={{ display: 'none' }}>
|
||||
{/* variant 2 */}
|
||||
</div>
|
||||
```
|
||||
|
||||
The wrap script already gives you a single-rooted JSX wrapper: a `<div data-impeccable-variants="…">` outer element with the marker comments tucked inside. Drop the variants block above into the "Variants: insert below this line" comment and the source stays valid TSX.
|
||||
The wrap script provides a single-rooted JSX wrapper with the marker comments inside; drop the block at the marker and the source stays valid TSX.
|
||||
|
||||
### 7. Parameters (composition-sized, 0–4 per variant)
|
||||
### 7. Parameters (composition-sized, 0-4 per variant)
|
||||
|
||||
Each variant can expose **coarse** knobs alongside the full HTML/CSS replacement. The browser docks a small panel to the right of the outline with one control per parameter. The user drags/clicks and sees instant feedback: there is zero regeneration cost because the knob toggles a CSS variable or data attribute that the variant's scoped CSS is already authored against.
|
||||
Each variant can expose **coarse** knobs; the browser docks one control per parameter with zero regeneration cost (knobs drive a CSS variable or data attribute your scoped CSS is authored against). Wire an axis as soon as the user could plausibly mutter "a bit tighter" or "a touch more accent" without wanting a regeneration; micro-margins and one-off nudges are not parameters. Freeform bias: you chose the axes, so expose them; a hero with 0 params is almost always a mistake, and 1 is underweight unless the design is a genuine fixed point.
|
||||
|
||||
**What “optional” does not mean.** Parameters are not nice-to-have decoration on large work. The word meant “omit controls that are redundant or cosmetic,” not “default to zero because three variants were enough work.”
|
||||
Budget scales with the element's VISUAL weight (count visual children, not DOM depth):
|
||||
|
||||
**When to add.** As soon as the variant’s scoped CSS has a meaningful continuous or stepped axis: density, color amount, type scale, motion intensity, column weight, and so on. If you can imagine the user muttering “a bit tighter” or “a touch more accent” **without** wanting a full regeneration, wire that axis. **Not** micro-margins or one-off nudges; those are not parameters.
|
||||
- **Leaf / tiny** (button, icon, bare heading): **0 params.**
|
||||
- **Small composition** (simple card, labeled input, ≤ ~5 visual children): **0-1**.
|
||||
- **Medium composition** (section, nav cluster, 6-15 children): **target 2**; 1 if simple.
|
||||
- **Large composition** (hero, full region, 16+ children or sub-sections): **target 2-3, up to 4** when independent axes are all authored in CSS.
|
||||
|
||||
**Freeform (`action` is `impeccable`) bias.** You did not load a sub-command reference, so you must **choose** signature axes yourself. Match the budget table: for a hero or large composition, that means **2–3 axes per variant**, not 1. Prefer knobs that sit on the dimensions where your three variants actually differ (if density varies, expose it as a `steps` knob; if color commitment varies, expose it as a `range`). A hero that ships with **0** params is almost always a mistake, not a judgment call. A hero with exactly **1** param is underweight unless the design is genuinely a fixed-point comparison. Start from the budget table, not from zero.
|
||||
**Hard cap: four** per variant. For named sub-commands, the action reference's MUST params are non-negotiable when expressible; respect the cap, no duplicate knobs.
|
||||
|
||||
**Budget scales with the element's visual weight, not token budget.** Knobs need real estate to read as tunable; three sliders on a single control are noise.
|
||||
|
||||
- **Leaf / tiny**: a single button, icon, input, bare heading, solitary paragraph: **0 params.**
|
||||
- **Small composition**: labeled input, simple card, short callout (≤ ~5 visual children): **0–1** params when one dominant axis is obvious; otherwise **0.**
|
||||
- **Medium composition**: section component, nav cluster, dense card, short feature block (6–15 visual children): **target 2**; **1** is acceptable if the block is simple; **0** only when variants are truly fixed points.
|
||||
- **Large composition**: hero section, full page region, spread layout, strong internal structure (16+ visual children or multiple sub-sections): **target 2–3**; **up to 4** when several independent axes (e.g. structure `steps` + `density` + one accent) are all authored in scoped CSS.
|
||||
|
||||
**When in doubt, ask whether a dial exists before defaulting to zero.** The user can always request more variants, but the point of live mode is instant tuning without another Go. Crowding the panel is bad; **under-shipping** knobs on a dense composition is the more common failure for freeform. Count by **visual** children, not DOM depth; a shallow-but-wide hero is still large.
|
||||
|
||||
**Hard cap per variant**: at most **four** parameters so the panel stays legible; rare fifth only if the reference explicitly allows it.
|
||||
|
||||
**How to declare.** Put a JSON manifest on the variant wrapper (HTML/JSX path). **On the `svelte-component` path, do not use this attribute.** Declare params in `componentDir/params.json` keyed by variant number instead (see the component-preview paragraphs in the wrap section). The param schema below is identical for every path.
|
||||
**Declare** on the HTML/JSX path as a wrapper attribute (component-preview paths use `componentDir/params.json` instead, same schema, keyed by variant number; see the wrap section):
|
||||
|
||||
```html
|
||||
<div data-impeccable-variant="1" data-impeccable-params='[
|
||||
{"id":"color-amount","kind":"range","min":0,"max":1,"step":0.05,"default":0.5,"label":"Color amount"},
|
||||
{"id":"density","kind":"steps","default":"snug","label":"Density","options":[
|
||||
{"value":"airy","label":"Airy"},
|
||||
{"value":"snug","label":"Snug"},
|
||||
{"value":"packed","label":"Packed"}
|
||||
]},
|
||||
{"id":"serif","kind":"toggle","default":false,"label":"Serif display"}
|
||||
]'>
|
||||
...variant content...
|
||||
</div>
|
||||
```
|
||||
|
||||
**Three kinds:**
|
||||
Three kinds: `range` (slider; drives `--p-<id>`; author `var(--p-color-amount, 0.5)`; fields min/max/step/default/label), `steps` (segmented radio; drives `data-p-<id>`; author `:scope[data-p-density="airy"] .grid { ... }`; fields options/default/label), `toggle` (drives both `--p-<id>: 0|1` and attribute presence; fields default/label). Reset on variant switch is a known limitation: each variant starts at its declared defaults.
|
||||
|
||||
- `range`: smooth slider. Drives a CSS custom property `--p-<id>` on the variant wrapper. Author CSS with `var(--p-color-amount, 0.5)`. Fields: `min`, `max`, `step`, `default` (number), `label`.
|
||||
- `steps`: segmented radio. Drives a data attribute `data-p-<id>` on the variant wrapper. Author CSS with `:scope[data-p-density="airy"] .grid { ... }`. Fields: `options` (array of `{value, label}`), `default` (string), `label`.
|
||||
- `toggle`: on/off switch. Drives BOTH a CSS var (`--p-<id>: 0|1`) and a data attribute (present when on, absent when off). Use whichever is more convenient. Fields: `default` (boolean), `label`.
|
||||
|
||||
**Signature params per action.** For named sub-commands, read that action’s `reference/<action>.md` for one or two **MUST** params (e.g. `layout` → `density`). Those are non-negotiable when the design can express them. **Freeform has no file-level MUST**; the **Freeform (`impeccable`) bias** in this section is the stand-in. If the user’s action is both stylized and sub-command (e.g. `colorize`), the sub-command’s MUST list takes precedence for its axes; still respect the **Hard cap** and add no redundant duplicate knobs.
|
||||
|
||||
**Reset on variant switch.** User dials density on v1, flips to v2, v2 starts at v2's declared defaults. Known limitation; preservation across variants may land later.
|
||||
|
||||
**On accept**, the browser sends the user's current values in the accept event. `live-accept.mjs` writes them as a sibling comment:
|
||||
|
||||
```html
|
||||
<!-- impeccable-param-values SESSION_ID: {"color-amount":0.7,"density":"packed"} -->
|
||||
```
|
||||
|
||||
The carbonize cleanup step (see below) reads that comment and bakes the chosen values into the final CSS. For `steps`/`toggle` attribute selectors: keep only the branch matching the chosen value, drop the others, collapse `:scope[data-p-density="packed"] .grid` to a semantic class rule. For `range` vars: either substitute the literal or keep the var with the chosen value as its new default.
|
||||
**On accept**, the browser sends current values and `live-accept.mjs` writes them as a sibling comment: `<!-- impeccable-param-values SESSION_ID: {"color-amount":0.7} -->`. Carbonize cleanup bakes them: keep only the matching `steps`/`toggle` branch, drop the others, collapse `:scope[data-p-…]` to semantic rules; substitute `range` literals or update the var's default.
|
||||
|
||||
### 8. Signal done
|
||||
|
||||
@@ -407,127 +243,56 @@ The carbonize cleanup step (see below) reads that comment and bakes the chosen v
|
||||
node .claude/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID done --file RELATIVE_PATH
|
||||
```
|
||||
|
||||
`RELATIVE_PATH` is relative to project root (`public/index.html`, `src/App.tsx`, etc.); the browser fetches source directly if the dev server lacks HMR.
|
||||
|
||||
Then run `live-poll.mjs` again immediately.
|
||||
`RELATIVE_PATH` is relative to project root; the browser fetches source directly if the dev server lacks HMR. Then poll again immediately.
|
||||
|
||||
### Aborting an in-flight session
|
||||
|
||||
If wrap or generation fails after the browser has flipped to GENERATING (e.g. wrap landed on the wrong source branch and you've already reverted it, or generation hit an unrecoverable error), tell the **browser** so its bar resets to PICKING:
|
||||
|
||||
```bash
|
||||
node .claude/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID error "Short reason"
|
||||
```
|
||||
|
||||
Don't run `live-accept --discard` for this; that's a pure file mutator, the browser doesn't see it, and the bar gets stuck on the GENERATING dots forever (the user has to refresh). `--discard` is only correct when the **browser** initiated the discard (user clicked ✕ during CYCLING) and the agent is just running source-side cleanup the browser already triggered.
|
||||
If wrap or generation fails after the browser flipped to GENERATING, tell the **browser** so its bar resets: `node .claude/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID error "Short reason"`. Never use `live-accept --discard` for this (pure file mutator, browser never sees it, bar sticks on dots); `--discard` is only source-side cleanup for a discard the browser itself initiated.
|
||||
|
||||
## Handle fallback
|
||||
|
||||
When wrap returns `fallback: "agent-driven"`, the deterministic flow doesn't apply. Pick up here.
|
||||
When wrap returns `fallback: "agent-driven"`, you pick the source file yourself; the goal is unchanged: three preview variants now, and the accepted one persisted where the next build cannot wipe it.
|
||||
|
||||
The goal is the same: give the user three variants to choose from AND persist the accepted one in a place the next build won't wipe. The difference is that you have to pick the right source file yourself.
|
||||
|
||||
### Step 1: Identify where the element actually lives
|
||||
|
||||
Use the error payload:
|
||||
|
||||
- `element_not_in_source` with `generatedMatch: "public/docs/foo.html"`: the served HTML is generated. Find the generator (grep for writers of that path, e.g. `scripts/build-sub-pages.js`, an Astro/Next template) and locate the template or partial that emits this element.
|
||||
- `element_not_found`: the element is runtime-injected. Look for the component that renders it (React/Vue/Svelte), the JS that assembles it, or the data source that feeds it.
|
||||
- `file_is_generated` with `file: "..."`: user pointed at a generated file explicitly. Same resolution as `element_not_in_source`.
|
||||
|
||||
Read the candidate source until you're confident where a change to the element would belong. If the change is purely visual, that source might be a shared stylesheet, not the template.
|
||||
|
||||
### Step 2: Show three variants in the DOM for preview
|
||||
|
||||
The browser bar is waiting for variants. Even without a wrapper in source, you still need to show something:
|
||||
|
||||
1. Manually write the wrapper scaffold into the **served** file (the one the browser actually loaded). Use the same structure `live-wrap.mjs` produces; `<!-- impeccable-variants-start ID --><div data-impeccable-variants="ID" data-impeccable-variant-count="3" style="display: contents">…</div><!-- end -->`.
|
||||
2. Insert your three variant divs inside it, same shape as the deterministic path.
|
||||
3. Signal done with `--reply EVENT_ID done --file <served file>`. The browser's no-HMR fallback will fetch and inject.
|
||||
|
||||
This served-file edit is **temporary**: next regen wipes it, and that's fine. The real work happens on accept.
|
||||
|
||||
### Step 3: On accept, write to true source
|
||||
|
||||
When the accept event arrives (`_acceptResult.handled` will usually be `false` here because accept also refuses to persist into generated files; see Handle accept for the carbonize branch), extract the accepted variant's content and write it into the source you identified in Step 1:
|
||||
|
||||
- Structural change → edit the template / component source.
|
||||
- Visual-only change → add or update rules in the appropriate stylesheet; remove the inline `<style>` scope.
|
||||
- Dynamic from data → update the data source or the render logic.
|
||||
|
||||
Then remove the temporary wrapper from the served file if it's still there.
|
||||
|
||||
### Step 4: On discard, clean up the served file
|
||||
|
||||
Remove the wrapper you inserted in Step 2. Nothing else to do.
|
||||
1. **Find where the element really lives** from the error payload: `element_not_in_source` + `generatedMatch` means the served HTML is generated, so find the generator's template or partial; `element_not_found` means runtime-injected, so find the rendering component or data source; `file_is_generated` resolves the same way. A purely visual change may belong in a shared stylesheet rather than a template.
|
||||
2. **Preview in the served file**: manually write the same wrapper scaffold `live-wrap.mjs` produces (`<!-- impeccable-variants-start ID --><div data-impeccable-variants="ID" data-impeccable-variant-count="3" style="display: contents">…</div><!-- end -->`) into the file the browser actually loaded, insert your variant divs, `--reply EVENT_ID done --file <served file>`. This edit is temporary; a regen wiping it is fine.
|
||||
3. **On accept, write to true source** (accept refuses generated files, so `_acceptResult.handled` is usually `false` here): structural change → template/component source; visual-only → the right stylesheet; content rendered from data → the data source or render logic. Then remove the temporary wrapper from the served file.
|
||||
4. **On discard**, just remove the temporary wrapper.
|
||||
|
||||
## Handle `accept`
|
||||
|
||||
Event: `{id, variantId, _acceptResult, _completionAck}`. The poll script already ran `live-accept.mjs` to handle the file operation deterministically, then acknowledged event delivery to the helper. The browser DOM is already updated.
|
||||
Event: `{id, variantId, _acceptResult, _completionAck}`. The poll script already ran `live-accept.mjs` deterministically and acknowledged delivery; the browser DOM is already updated.
|
||||
|
||||
- The accept event includes `pageUrl`; the poll script must forward it to `live-accept.mjs --page-url PAGE_URL` so accept-time cleanup only scrubs staged copy edits for the current page.
|
||||
- `_completionAck.ok !== true`: do not poll yet. Run `live-status.mjs` / `live-resume.mjs`, complete the cleanup manually if needed, then run `live-complete.mjs --id EVENT_ID`.
|
||||
- `_acceptResult.handled: true` and `carbonize: false`: nothing to do. Poll again.
|
||||
- `_acceptResult.handled: true` and `carbonize: true`: post-accept cleanup is required, but it must not stall Codex's control lane. See "Required after accept (carbonize)" below. The `event._acceptResult.todo` field, `_completionAck.requiresComplete`, and stderr banner all point at this required follow-up; none are decorative.
|
||||
- `_acceptResult.handled: false, mode: "fallback"`: the session lived in a generated file and the script refused to persist there. You've already written the accepted variant into true source during Handle fallback Step 3; just clean up the temporary wrapper in the served file if any, and poll again.
|
||||
- `_acceptResult.handled: false, mode: "error"`: the operation genuinely failed. **Do not hand-edit the file**; the source was not touched and editing it yourself would either double-apply or race whoever holds it.
|
||||
- `error: "source_locked"`: a generation publish holds the file. Run the same `live-accept.mjs` command again; it is idempotent and will succeed once the publisher releases. Do not poll past it.
|
||||
- `error: "accept_receipt_conflict"`: this session already resolved as `priorOperation` (on `priorVariantId` for an accept), so the request contradicts durable truth. Do not edit. Run `live-status.mjs` and tell the user what the session actually resolved to.
|
||||
- anything else: report the error briefly and run `live-status.mjs` before continuing.
|
||||
- `_acceptResult.handled: false` without `mode`: manual cleanup: read file, find markers, edit.
|
||||
- `_completionAck.ok !== true`: do not poll yet. Run `live-status.mjs` / `live-resume.mjs`, finish cleanup manually if needed, then `live-complete.mjs --id EVENT_ID`.
|
||||
- `handled: true, carbonize: false`: nothing to do; poll again.
|
||||
- `handled: true, carbonize: true`: required cleanup below; `_acceptResult.todo`, `_completionAck.requiresComplete`, and the stderr banner all point at it.
|
||||
- `handled: false, mode: "fallback"`: the session lived in a generated file; you already wrote true source in fallback Step 3; clean the temporary wrapper and poll.
|
||||
- `handled: false, mode: "error"`: **do not hand-edit the file.** `source_locked`: rerun the same `live-accept.mjs` command (idempotent) until the publisher releases. `accept_receipt_conflict`: the session already resolved as `priorOperation`; run `live-status.mjs` and tell the user. Anything else: report briefly, run `live-status.mjs` first.
|
||||
- `handled: false` without `mode`: manual cleanup: read file, find markers, edit.
|
||||
|
||||
### Required after accept (carbonize)
|
||||
|
||||
When `_acceptResult.carbonize === true`, the accepted variant was stitched into source with helper markers and inline CSS so the browser can render it immediately with no visual gap. That stitch-in is **temporary**. The agent must rewrite it into permanent form before doing anything else. Skipping this leaves dead `@scope` rules for unaccepted variants, a pointless `data-impeccable-variant` wrapper, and `impeccable-carbonize-start/end` comment noise in the source file; all of which accumulate across sessions.
|
||||
`carbonize: true` means the accepted variant is stitched into source with helper markers and inline CSS (so the browser renders with no gap). That stitch-in is temporary; rewrite it into permanent form before anything else, or dead `@scope` rules, wrapper divs, and marker comments accumulate across sessions. Five steps, synchronously, before the next poll:
|
||||
|
||||
Do these five steps synchronously before the next poll. The source lock, generation epoch, and expected-source hash remain the final safety gates against a generator finishing concurrently with Accept.
|
||||
1. **Locate the carbonize block** in `_acceptResult.file`: bracketed by `<!-- impeccable-carbonize-start/end SESSION_ID -->` with a `<style data-impeccable-css>` element; read the `<!-- impeccable-param-values -->` comment first when present, it drives steps 3 and 4.
|
||||
2. **Move the CSS rules** into the project's real stylesheet (whichever already owns styling for the surrounding element).
|
||||
3. **Bake param values while rewriting selectors**: retarget `@scope ([data-impeccable-variant="N"])` to real semantic classes; keep only the `:scope[data-p-<id>="VALUE"]` branch matching the chosen value; substitute `var(--p-<id>)` literals or update the var's default.
|
||||
4. **Unwrap the accepted content**: delete the inner variant div (and on JSX the outer `data-impeccable-carbonize` div); drop `data-impeccable-params` and all `data-p-*` attributes.
|
||||
5. **Delete** the inline `<style>` block, the param-values comment, both carbonize markers, and any `@scope` rules for non-accepted variants.
|
||||
|
||||
1. **Locate the carbonize block** in the source file (`_acceptResult.file`). It's bracketed by `<!-- impeccable-carbonize-start SESSION_ID -->` and `<!-- impeccable-carbonize-end SESSION_ID -->` and contains a `<style data-impeccable-css="SESSION_ID">` element. If the variant declared parameters, an `<!-- impeccable-param-values SESSION_ID: {...} -->` comment sits alongside the style tag with the user's chosen values; read it first; it drives steps 3 and 4 below.
|
||||
2. **Move the CSS rules** into the project's real stylesheet. Which stylesheet depends on the project (e.g. `site/styles/workflow.css` for an Astro project, or the component's co-located CSS file for a Vite/Next project; pick whichever already owns styling for the surrounding element).
|
||||
3. **Bake in parameter values while rewriting selectors.** For `@scope ([data-impeccable-variant="N"])` wrappers: retarget to real, semantic classes on the accepted HTML (`.why-visual--v2 .v2-label { … }`). For `:scope[data-p-<id>="VALUE"]` selectors: keep only the branch matching the chosen value from the param-values comment; drop the others (they're dead after accept). For `var(--p-<id>, DEFAULT)` in the CSS: either substitute the literal value, or if the param is still useful as a knob going forward, leave the var and update its initial declaration to the chosen value.
|
||||
4. **Unwrap the accepted content.** Delete the inner `<div data-impeccable-variant="N" style="display: contents">` that wraps it. On JSX/TSX, also delete the outer `<div data-impeccable-carbonize="SESSION_ID" style={{ display: 'contents' }}>` wrapper if present (accept adds it so ternary/`return` slots keep a single root). Drop `data-impeccable-params` and any `data-p-*` attributes; those are live-mode plumbing, not source.
|
||||
5. **Delete the inline `<style>` block, the `<!-- impeccable-param-values -->` comment if present, and both `<!-- impeccable-carbonize-start/end -->` markers.** Also drop any `@scope` rules for variants other than the accepted one; those are dead code now.
|
||||
|
||||
After the file is clean, the cleanup owner runs `live-complete.mjs --id SESSION_ID` and verifies `phase: "completed"`. Poll again only after that verification.
|
||||
Then run `live-complete.mjs --id SESSION_ID` and verify `phase: "completed"` before polling again. The command is a gate, not a formality: it refuses with `error: "source_dirty"` plus findings while any live-mode leftover remains; fix and rerun (`--force` only for false positives).
|
||||
|
||||
## Handle `discard`
|
||||
|
||||
Event: `{id, _acceptResult, _completionAck}`. The poll script already restored the original, removed all variant markers, and acknowledged `discarded` durable completion. Nothing to do unless `_completionAck.ok !== true`; in that case run `live-complete.mjs --id EVENT_ID --discarded`, then poll again.
|
||||
Event: `{id, _acceptResult, _completionAck}`. The poll script already restored the original and acknowledged `discarded`. Nothing to do unless `_completionAck.ok !== true`; then `live-complete.mjs --id EVENT_ID --discarded` and poll again.
|
||||
|
||||
## Handle `steer`
|
||||
|
||||
Event: `{id, message, pageUrl}`. The user typed or spoke into the global bar **Steer** control: page-level direction without picking an element or launching variant generation.
|
||||
|
||||
The mic button uses the browser **Web Speech API** (MVP): click to start, speak, stop automatically when the utterance ends, then the transcript submits as a steer event. Click again while listening to cancel without submitting.
|
||||
|
||||
This is lighter than `generate`: no screenshot, no element context, no variant cycling. Read `message` and inspect the live page or project files as needed, then either make edits or answer in prose.
|
||||
|
||||
When finished:
|
||||
|
||||
```bash
|
||||
node .claude/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID steer_done ["Optional short note for a browser toast"]
|
||||
```
|
||||
|
||||
On failure:
|
||||
|
||||
```bash
|
||||
node .claude/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID error "Short reason"
|
||||
```
|
||||
|
||||
Then poll again immediately. Do not send a separate "picked up" reply. The Steer bar stays locked until `steer_done` or `error` arrives over SSE.
|
||||
Event: `{id, message, pageUrl}`: page-level direction from the global bar's Steer control (typed or spoken), no element context, no variant cycling. Read `message`, inspect the page or files as needed, make edits or answer in prose. Reply `node .claude/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID steer_done ["Optional short toast"]`, or on failure `--reply EVENT_ID error "Short reason"`, then poll immediately. No separate pickup reply; the Steer bar unlocks on `steer_done` or `error`.
|
||||
|
||||
## Handle `prefetch`
|
||||
|
||||
Event: `{pageUrl}`. The browser fires this the first time the user selects an element on a given route, as a latency shortcut; it signals the user is likely about to Go on a page you haven't read yet.
|
||||
|
||||
Resolve `pageUrl` to the underlying file:
|
||||
|
||||
- Root `/` → the `pageFile` returned by `live.mjs` (usually `public/index.html` or equivalent).
|
||||
- Sub-routes (e.g. `/docs`, `/docs/live`) → the generated or source file for that route. Use your knowledge of the project layout (multi-page static sites often resolve `/foo` → `public/foo/index.html`; SPAs may map all routes to a single entry).
|
||||
|
||||
Read the file into context, then poll again. No `--reply`: this is speculative pre-work; Go will come later. If you can't confidently resolve the route to a file, skip and poll again.
|
||||
|
||||
Dedupe is the browser's job (one prefetch per unique pathname per session); trust it. If the same file shows up twice from different routes mapping to the same file, the second Read is cached anyway.
|
||||
Event: `{pageUrl}`: fired once per route on first selection; the user is likely about to Go on a page you have not read. Resolve the route to its file (root `/` is usually the boot's `pageFile`; multi-page sites often map `/foo` to `public/foo/index.html`; SPAs map everything to one entry), read it, poll again. No `--reply`. If you cannot resolve it confidently, skip and poll.
|
||||
|
||||
## Handle `manual_edit_apply`
|
||||
|
||||
@@ -543,12 +308,7 @@ After source edits finish, reply exactly once with `node .claude/skills/impeccab
|
||||
|
||||
## Exit
|
||||
|
||||
The user can stop live mode by:
|
||||
- Saying "stop live mode" / "exit live" in chat
|
||||
- Closing the browser tab (SSE drops, poll returns `exit` after 8s)
|
||||
- The browser's exit button
|
||||
|
||||
When the poll returns `exit`, proceed to cleanup. If the poll is still running as a background task, kill it first.
|
||||
The user stops live mode by saying so in chat, closing the tab (SSE drops; poll returns `exit` after 8s), or the browser's exit button. On `exit`, kill any still-running background poll, then clean up.
|
||||
|
||||
## Cleanup
|
||||
|
||||
@@ -556,175 +316,8 @@ When the poll returns `exit`, proceed to cleanup. If the poll is still running a
|
||||
node .claude/skills/impeccable/scripts/live-server.mjs stop
|
||||
```
|
||||
|
||||
Stops the HTTP server and runs `live-inject.mjs --remove` to strip `localhost:…/live.js` from the HTML entry. To stop the server but keep the inject tag (for a quick restart), use `stop --keep-inject`. `.impeccable/live/config.json` persists as project config for future sessions.
|
||||
Stops the helper and runs `live-inject.mjs --remove` to strip the injected script (use `stop --keep-inject` to keep it for a quick restart; `.impeccable/live/config.json` persists as project config). Then search for and remove any leftover `impeccable-variants-start` wrappers and `impeccable-carbonize-start` blocks.
|
||||
|
||||
Then:
|
||||
- Remove any leftover variant wrappers (search for `impeccable-variants-start` markers).
|
||||
- Remove any leftover carbonize blocks (search for `impeccable-carbonize-start` markers).
|
||||
## First-time setup
|
||||
|
||||
## First-time setup (config missing or invalid)
|
||||
|
||||
If `live.mjs` outputs `{ ok: false, error: "config_missing" | "config_invalid", path }`, write the live config at the reported path. By default this is `.impeccable/live/config.json`.
|
||||
|
||||
Schema:
|
||||
|
||||
```json
|
||||
{
|
||||
"files": ["<path-or-glob>", "<path-or-glob>", ...],
|
||||
"exclude": ["<optional-glob>", ...],
|
||||
"insertBefore": "</body>",
|
||||
"commentSyntax": "html",
|
||||
"cspChecked": true
|
||||
}
|
||||
```
|
||||
|
||||
`files` is the inject target; **the HTML files the browser actually loads**, not necessarily source. Each entry is either a literal path (`"public/index.html"`) or a glob pattern (`"public/**/*.html"`). Tracked or generated doesn't matter here; wrap has its own generated-file guard and routes accepts through the fallback flow.
|
||||
|
||||
`exclude` (optional) is a list of glob patterns matching files to skip, even if a `files` glob would have included them. Use for email templates, demo fixtures, or any HTML that isn't a live page.
|
||||
|
||||
`cspChecked` tracks whether the CSP detection step below has already run. Absent on first setup; set to `true` after CSP is checked (whether patched, declined, or not needed).
|
||||
|
||||
**Hard-excluded paths (cannot be overridden).** `**/node_modules/**` and `**/.git/**` are never matched regardless of what the user writes. These are vendor/metadata directories and injecting into them would silently instrument third-party code.
|
||||
|
||||
**Glob syntax.** `**` matches any number of path segments (including zero), `*` matches any characters except `/`, `?` matches a single character except `/`. Paths are always relative to the project root with forward slashes.
|
||||
|
||||
| Framework | `files` | `insertBefore` | `commentSyntax` |
|
||||
|-----------|---------|----------------|-----------------|
|
||||
| SPA with single shell (Vite / React / Plain HTML) | `["index.html"]` | `</body>` | `html` |
|
||||
| Next.js (App Router) | `["app/layout.tsx"]` | `</body>` | `jsx` |
|
||||
| Next.js (Pages) | `["pages/_document.tsx"]` | `</body>` | `jsx` |
|
||||
| Nuxt | `["app.vue"]` | `</body>` | `html` |
|
||||
| Svelte / SvelteKit | `["src/app.html"]` | `</body>` | `html` |
|
||||
| TanStack Router (SPA, Vite) | `["index.html"]` | `</body>` | `html` |
|
||||
| TanStack Start (SSR) | `["src/routes/__root.tsx"]` | `<Scripts` | `jsx` |
|
||||
| Astro | `[" <root layout .astro>"]` | `</body>` | `html` |
|
||||
| Multi-page (separate HTML per route) | `["public/**/*.html"]`: a glob covering the served directory | `</body>` | `html` |
|
||||
|
||||
Pick an anchor that exists in every file (`</body>` almost always works). Use `insertAfter` if the anchor should match **after** a specific line.
|
||||
|
||||
**Framework adapters (auto-detected at inject time).** SvelteKit, Nuxt, and TanStack Start server-render their document shell, so a raw `<script>` in the entry template will not execute reliably. `live-inject.mjs` detects these from the project and routes to a dedicated adapter instead of the literal `files` patch: SvelteKit mounts a dev-only root component from `+layout.svelte`; Nuxt writes a dev-only `.client.ts` plugin; TanStack Start (detected by `@tanstack/react-start` plus `src/routes/__root.tsx`) patches the `__root` document to render a generated dev-only `src/impeccable/ImpeccableLiveRoot` component that appends the bundle on mount. The `files` value stays a valid detection/CSP hint but is not the literal insertion site. A plain TanStack Router SPA (no `@tanstack/react-start`) has a static `index.html` and takes the baseline Vite path with no adapter.
|
||||
|
||||
For multi-page sites, **prefer a glob over a literal file list**. New pages added later are picked up automatically on the next `live-inject.mjs` run; no config maintenance needed.
|
||||
|
||||
For multi-page sites whose pages are *rebuilt* by a generator (Astro, static-site generators, custom scripts like `build-sub-pages.js`), the inject survives only until the next regeneration. Re-run `live.mjs` after each build. Accept is unaffected; it writes to true source via the fallback flow.
|
||||
|
||||
### Drift-heal warning
|
||||
|
||||
On every `live.mjs` boot, after inject, the project is scanned for HTML files under common page-source roots (`public/`, `src/`, `app/`, `pages/`). If any exist that aren't covered by the resolved `files` list, the output includes a `configDrift` field:
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"serverPort": 8400,
|
||||
"pageFiles": [ "..." ],
|
||||
"configDrift": {
|
||||
"orphans": ["public/new-section/index.html", "public/docs/new-command.html"],
|
||||
"orphanCount": 2,
|
||||
"hint": "2 HTML file(s) exist but aren't in config.files. Consider adding them, or use a glob pattern like \"public/**/*.html\"."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
When `configDrift` is present, surface it to the user once per session before entering the poll loop:
|
||||
|
||||
> Noticed N HTML file(s) in the project that aren't in `config.files`:
|
||||
>
|
||||
> - `public/new-section/index.html`
|
||||
> - `public/docs/new-command.html`
|
||||
>
|
||||
> Add them, or switch `files` to a glob like `["public/**/*.html"]` and let it track new pages automatically?
|
||||
|
||||
Don't auto-update the config; let the user decide. `configDrift` is `null` when there's no drift.
|
||||
|
||||
### CSP detection (first-time only)
|
||||
|
||||
If `config.cspChecked === true`, skip this entire section. You already asked this user once; the answer sticks.
|
||||
|
||||
Otherwise, run the detection helper:
|
||||
|
||||
```bash
|
||||
node .claude/skills/impeccable/scripts/detect-csp.mjs
|
||||
```
|
||||
|
||||
Output: `{ shape, signals }` where `shape` is one of `append-arrays`, `append-string`, `middleware`, `meta-tag`, or `null`. The shape is named by *patch mechanism*, so one template covers many frameworks.
|
||||
|
||||
- **`null`**: no CSP; skip to writing `.impeccable/live/config.json` with `cspChecked: true`.
|
||||
- **`append-arrays`**: CSP defined as structured directive arrays. Auto-patchable. See *append-arrays* below. Covers:
|
||||
- Monorepo helpers with `additionalScriptSrc` / `additionalConnectSrc` options (Next.js + shared config package)
|
||||
- SvelteKit `kit.csp.directives`
|
||||
- Nuxt `nuxt-security` module's `contentSecurityPolicy`
|
||||
- **`append-string`**: CSP written as a literal value string. Auto-patchable. See *append-string* below. Covers:
|
||||
- Inline `next.config.*` `headers()` with a CSP literal
|
||||
- Nuxt `routeRules` / `nitro.routeRules` headers
|
||||
- **`middleware`** or **`meta-tag`**: rarer. Detected but not auto-patched in v1. Show the user the detected files and ask them to add `http://localhost:8400` to `script-src` and `connect-src` manually, then mark `cspChecked: true` and proceed.
|
||||
|
||||
#### Consent prompt template
|
||||
|
||||
Use this phrasing so the experience is consistent across agents:
|
||||
|
||||
> **CSP patch needed.** I detected a Content Security Policy in your project that blocks `http://localhost:8400`: the live picker won't load without an allowance. Here's the change I'd make:
|
||||
>
|
||||
> ```diff
|
||||
> [file: <patchTarget>]
|
||||
> [exact diff, 2–5 lines]
|
||||
> ```
|
||||
>
|
||||
> It's guarded by `NODE_ENV === "development"` so the extra entry only appears in dev and never reaches production. You can remove it any time by reverting this file. Apply? [y/n]
|
||||
|
||||
On "no": skip the patch, mention live won't work until the user adds the allowance manually, still write `cspChecked: true` (the question's been asked).
|
||||
|
||||
On "yes": apply the Shape-specific patch below, then write `cspChecked: true`.
|
||||
|
||||
#### append-arrays
|
||||
|
||||
CSP expressed as structured directive arrays. Patch mechanism: declare a dev-only array, spread it into the script-src and connect-src arrays.
|
||||
|
||||
**Declare near the top of the file that holds the CSP arrays:**
|
||||
|
||||
```ts
|
||||
// Dev-only allowance so impeccable live mode can load. Guarded by NODE_ENV.
|
||||
const __impeccableLiveDev =
|
||||
process.env.NODE_ENV === "development" ? ["http://localhost:8400"] : [];
|
||||
```
|
||||
|
||||
**Append `...__impeccableLiveDev` to the script-src and connect-src directive arrays.** Per-framework specifics:
|
||||
|
||||
- **Next.js + monorepo helper**: edit the *app's* `next.config.*` (not the shared helper), appending to `additionalScriptSrc` and `additionalConnectSrc` passed into `createBaseNextConfig` (or equivalent). Keeps the shared package clean.
|
||||
- **SvelteKit**: edit `svelte.config.js`, appending to `kit.csp.directives['script-src']` and `kit.csp.directives['connect-src']`.
|
||||
- **Nuxt + nuxt-security**: edit `nuxt.config.*`, appending to `security.headers.contentSecurityPolicy['script-src']` and `['connect-src']`.
|
||||
|
||||
Reference outputs:
|
||||
- `tests/framework-fixtures/nextjs-turborepo/expected-after-patch.ts` (Next.js)
|
||||
- `tests/framework-fixtures/sveltekit-csp/expected-after-patch.js` (SvelteKit)
|
||||
|
||||
Idempotency: if `__impeccableLiveDev` already exists in the file, the patch is already applied; skip asking and just mark `cspChecked: true`.
|
||||
|
||||
#### append-string
|
||||
|
||||
CSP built as a literal value string. Two-point patch: declare a dev-only string near the top, interpolate it into the CSP at the `script-src` and `connect-src` directives.
|
||||
|
||||
```ts
|
||||
// Dev-only allowance so impeccable live mode can load.
|
||||
const __impeccableLiveDev =
|
||||
process.env.NODE_ENV === "development" ? " http://localhost:8400" : "";
|
||||
```
|
||||
|
||||
Then in the CSP value string:
|
||||
- `script-src 'self' 'unsafe-inline'` → `` `script-src 'self' 'unsafe-inline'${__impeccableLiveDev}` ``
|
||||
- `connect-src 'self'` → `` `connect-src 'self'${__impeccableLiveDev}` ``
|
||||
|
||||
(Leading space on the dev string so it concatenates cleanly into the existing value. Convert the literal CSP directives into template strings as part of the edit if they aren't already.)
|
||||
|
||||
Per-framework specifics:
|
||||
- **Next.js inline `headers()`**: edit `next.config.*`, splicing the variable into the CSP value.
|
||||
- **Nuxt `routeRules`**: edit `nuxt.config.*`, splicing into the CSP in `routeRules['/**'].headers['Content-Security-Policy']`.
|
||||
|
||||
Reference outputs:
|
||||
- `tests/framework-fixtures/nextjs-inline-csp/expected-after-patch.js` (Next.js)
|
||||
- `tests/framework-fixtures/nuxt-csp/expected-after-patch.ts` (Nuxt)
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
If a user says "no" to the CSP patch at setup time and later complains that live doesn't work: their dev CSP blocks `http://localhost:8400`. Fix: delete `cspChecked` from `.impeccable/live/config.json` and re-run `live.mjs`: setup will ask again.
|
||||
|
||||
Then re-run `live.mjs`.
|
||||
Only when `live.mjs` reports `config_missing` / `config_invalid`, or `configDrift` needs explaining, or the config lacks `cspChecked`: read [live-setup.md](live-setup.md). It owns the config schema, the per-framework `files` table, injection adapters, drift healing, and the CSP detection and consent flow.
|
||||
|
||||
@@ -27,6 +27,7 @@ import {
|
||||
inlineSvelteComponentAccept,
|
||||
removeSvelteComponentSession,
|
||||
} from './live/svelte-component.mjs';
|
||||
import { enterLiveRoot } from './live/roots.mjs';
|
||||
|
||||
const ACCEPT_LOCK_WAIT_MS = 1_000;
|
||||
// Mirrors VARIANT_ID_PATTERN in live/event-validation.mjs, which gates the same
|
||||
@@ -946,6 +947,7 @@ function argVal(args, flag) {
|
||||
// Auto-execute when run directly
|
||||
const _running = process.argv[1];
|
||||
if (_running?.endsWith('live-accept.mjs') || _running?.endsWith('live-accept.mjs/')) {
|
||||
enterLiveRoot();
|
||||
acceptCli();
|
||||
}
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -3,8 +3,12 @@
|
||||
* Canonical durable completion acknowledgement for Impeccable live sessions.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { createLiveSessionStore } from './live/session-store.mjs';
|
||||
import { readLiveServerInfo } from './lib/impeccable-paths.mjs';
|
||||
import { enterLiveRoot } from './live/roots.mjs';
|
||||
import { verifyAcceptedFile } from './live/accept-verify.mjs';
|
||||
|
||||
function parseArgs(argv) {
|
||||
const out = { status: 'complete' };
|
||||
@@ -15,6 +19,7 @@ function parseArgs(argv) {
|
||||
else if (arg === '--discarded' || arg === '--discard') out.status = 'discarded';
|
||||
else if (arg === '--error') { out.status = 'agent_error'; out.message = argv[++i] || 'unknown error'; }
|
||||
else if (arg.startsWith('--error=')) { out.status = 'agent_error'; out.message = arg.slice('--error='.length); }
|
||||
else if (arg === '--force') out.force = true;
|
||||
else if (arg === '--help' || arg === '-h') out.help = true;
|
||||
}
|
||||
return out;
|
||||
@@ -23,10 +28,36 @@ function parseArgs(argv) {
|
||||
export async function completeCli() {
|
||||
const args = parseArgs(process.argv.slice(2));
|
||||
if (args.help || !args.id) {
|
||||
console.log(`Usage: node live-complete.mjs --id SESSION_ID [--discarded|--error MESSAGE]\n\nAppend the final durable session acknowledgement. Use after accept/discard cleanup is verified.`);
|
||||
console.log(`Usage: node live-complete.mjs --id SESSION_ID [--discarded|--error MESSAGE] [--force]\n\nAppend the final durable session acknowledgement. Use after accept/discard cleanup is verified.\nCompletion is refused while the session's source file still carries live-mode leftovers\n(markers, data-p-* attributes, unbaked --p-* vars); fix the file or pass --force.`);
|
||||
process.exit(args.help ? 0 : 1);
|
||||
}
|
||||
|
||||
// The carbonize contract used to be prose; this makes it mechanical. A
|
||||
// "complete" while the source still carries live plumbing is how markers
|
||||
// and dead param branches accumulated across sessions.
|
||||
if (args.status === 'complete' && !args.force) {
|
||||
const store = createLiveSessionStore({ cwd: process.cwd(), sessionId: args.id });
|
||||
const snapshot = store.getSnapshot(args.id, { includeCompleted: true });
|
||||
const sourceFile = snapshot?.sourceFile;
|
||||
const absSource = sourceFile ? path.resolve(process.cwd(), sourceFile) : null;
|
||||
const relSource = absSource ? path.relative(process.cwd(), absSource) : null;
|
||||
const insideProject = relSource !== null && relSource !== '' && !relSource.startsWith('..') && !path.isAbsolute(relSource);
|
||||
if (insideProject && !relSource.startsWith('node_modules' + path.sep) && !relSource.startsWith('node_modules/')) {
|
||||
const verify = verifyAcceptedFile(fs, absSource);
|
||||
if (!verify.clean) {
|
||||
console.log(JSON.stringify({
|
||||
ok: false,
|
||||
error: 'source_dirty',
|
||||
id: args.id,
|
||||
file: sourceFile,
|
||||
findings: verify.findings,
|
||||
hint: 'The accepted source still carries live-mode leftovers. Finish the carbonize cleanup (bake params, remove markers and data-p-* attributes), then run live-complete again. Use --force only if a finding is a false positive.',
|
||||
}, null, 2));
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const serverInfo = readServerInfo();
|
||||
const serverResult = serverInfo ? await completeThroughServer(serverInfo, args) : null;
|
||||
if (serverResult?.ok) {
|
||||
@@ -71,5 +102,6 @@ async function completeThroughServer(info, args) {
|
||||
|
||||
const _running = process.argv[1];
|
||||
if (_running?.endsWith('live-complete.mjs') || _running?.endsWith('live-complete.mjs/')) {
|
||||
enterLiveRoot();
|
||||
completeCli();
|
||||
}
|
||||
|
||||
@@ -7,6 +7,11 @@
|
||||
* every subsequent run, this script handles insert/remove deterministically
|
||||
* with zero LLM involvement.
|
||||
*
|
||||
* Framework knowledge lives in `live/frameworks/` — detection order, adapters,
|
||||
* the generic tag strategy, and the per-extension authoring traits live-wrap
|
||||
* reads. This file is the CLI around it: resolve config, resolve the
|
||||
* framework, heal orphaned artifacts, apply or remove, record the journal.
|
||||
*
|
||||
* Usage:
|
||||
* node live-inject.mjs --port PORT [--token TOKEN] # Insert the live script tag
|
||||
* node live-inject.mjs --remove # Remove the live script tag
|
||||
@@ -23,22 +28,36 @@ import path from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { resolveLiveConfigPath } from './lib/impeccable-paths.mjs';
|
||||
import {
|
||||
applySvelteKitLiveAdapter,
|
||||
detectSvelteKitProject,
|
||||
removeSvelteKitLiveAdapter,
|
||||
} from './live/sveltekit-adapter.mjs';
|
||||
describeInjectArtifacts,
|
||||
frameworkIgnorePatterns,
|
||||
resolveFramework,
|
||||
resolveSourceTraits,
|
||||
} from './live/frameworks/index.mjs';
|
||||
import {
|
||||
applyTanStackLiveAdapter,
|
||||
detectTanStackStartProject,
|
||||
removeTanStackLiveAdapter,
|
||||
} from './live/tanstack-adapter.mjs';
|
||||
clearInjectJournal,
|
||||
healInjectJournal,
|
||||
recordInjection,
|
||||
} from './live/frameworks/journal.mjs';
|
||||
import {
|
||||
buildTagBlock,
|
||||
insertTag,
|
||||
patchCspMeta,
|
||||
removeTag,
|
||||
revertCspMeta,
|
||||
} from './live/frameworks/tag-strategy.mjs';
|
||||
import { buildLiveScriptSrc } from './live/frameworks/script-src.mjs';
|
||||
import { enterLiveRoot } from './live/roots.mjs';
|
||||
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
||||
const CONFIG_PATH = resolveLiveConfigPath({ cwd: process.cwd(), scriptsDir: __dirname });
|
||||
const MARKER_OPEN_TEXT = 'impeccable-live-start';
|
||||
const MARKER_CLOSE_TEXT = 'impeccable-live-end';
|
||||
const NUXT_PLUGIN_MARKER = 'impeccable-live-nuxt-plugin';
|
||||
const NUXT_PLUGIN_NAME = 'impeccable-live.client.ts';
|
||||
// Resolved lazily so the enterLiveRoot() chdir in the CLI guard below takes
|
||||
// effect first; module scope runs before the guard.
|
||||
let CONFIG_PATH_CACHED = null;
|
||||
function CONFIG_PATH_GET() {
|
||||
if (!CONFIG_PATH_CACHED) {
|
||||
CONFIG_PATH_CACHED = resolveLiveConfigPath({ cwd: process.cwd(), scriptsDir: __dirname });
|
||||
}
|
||||
return CONFIG_PATH_CACHED;
|
||||
}
|
||||
const IGNORE_MARKER_OPEN = '# impeccable-live-ignore-start';
|
||||
const IGNORE_MARKER_CLOSE = '# impeccable-live-ignore-end';
|
||||
|
||||
@@ -47,6 +66,9 @@ export const LIVE_IGNORE_PATTERNS = Object.freeze([
|
||||
'.impeccable/hook.pending.json',
|
||||
'.impeccable/config.local.json',
|
||||
'.impeccable/live/server.json',
|
||||
'.impeccable/live/roots.json',
|
||||
'.impeccable/live/app-root.json',
|
||||
'.impeccable/live/inject-journal.json',
|
||||
'.impeccable/live/sessions/',
|
||||
'.impeccable/live/previews/',
|
||||
'.impeccable/live/annotations/',
|
||||
@@ -102,60 +124,61 @@ Output (JSON):
|
||||
}
|
||||
|
||||
if (args.includes('--check')) {
|
||||
if (!fs.existsSync(CONFIG_PATH)) {
|
||||
console.log(JSON.stringify({ ok: false, error: 'config_missing', path: CONFIG_PATH }));
|
||||
// Deliberately read-only: --check runs from status paths and must never
|
||||
// mutate the tree. Journal reconciliation happens on the inject run.
|
||||
if (!fs.existsSync(CONFIG_PATH_GET())) {
|
||||
console.log(JSON.stringify({ ok: false, error: 'config_missing', path: CONFIG_PATH_GET() }));
|
||||
process.exit(0);
|
||||
}
|
||||
let cfg;
|
||||
try {
|
||||
cfg = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
|
||||
cfg = JSON.parse(fs.readFileSync(CONFIG_PATH_GET(), 'utf-8'));
|
||||
} catch (err) {
|
||||
console.log(JSON.stringify({ ok: false, error: 'config_invalid', message: err.message, path: CONFIG_PATH }));
|
||||
console.log(JSON.stringify({ ok: false, error: 'config_invalid', message: err.message, path: CONFIG_PATH_GET() }));
|
||||
return;
|
||||
}
|
||||
try {
|
||||
validateConfig(cfg);
|
||||
} catch (err) {
|
||||
console.log(JSON.stringify({ ok: false, error: 'config_invalid', message: err.message, path: CONFIG_PATH }));
|
||||
console.log(JSON.stringify({ ok: false, error: 'config_invalid', message: err.message, path: CONFIG_PATH_GET() }));
|
||||
return;
|
||||
}
|
||||
console.log(JSON.stringify({ ok: true, config: cfg, path: CONFIG_PATH }));
|
||||
console.log(JSON.stringify({ ok: true, config: cfg, path: CONFIG_PATH_GET() }));
|
||||
return;
|
||||
}
|
||||
|
||||
// Load config
|
||||
if (!fs.existsSync(CONFIG_PATH)) {
|
||||
console.error(JSON.stringify({ ok: false, error: 'config_missing', path: CONFIG_PATH }));
|
||||
if (!fs.existsSync(CONFIG_PATH_GET())) {
|
||||
console.error(JSON.stringify({ ok: false, error: 'config_missing', path: CONFIG_PATH_GET() }));
|
||||
process.exit(1);
|
||||
}
|
||||
const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
|
||||
const config = JSON.parse(fs.readFileSync(CONFIG_PATH_GET(), 'utf-8'));
|
||||
validateConfig(config);
|
||||
|
||||
const resolvedFiles = resolveFiles(process.cwd(), config);
|
||||
const svelteKit = detectSvelteKitProject(process.cwd(), config);
|
||||
const nuxt = detectNuxtProject(process.cwd());
|
||||
const tanstack = svelteKit || nuxt ? null : detectTanStackStartProject(process.cwd());
|
||||
const cwd = process.cwd();
|
||||
const resolvedFiles = resolveFiles(cwd, config);
|
||||
const resolved = resolveFramework(cwd, config);
|
||||
const isAdapter = resolved?.framework.inject.kind === 'adapter';
|
||||
|
||||
if (args.includes('--remove')) {
|
||||
if (svelteKit) {
|
||||
const adapterResult = removeSvelteKitLiveAdapter({ cwd: process.cwd(), config });
|
||||
console.log(JSON.stringify({ ok: true, adapter: 'sveltekit', results: [adapterResult] }));
|
||||
return;
|
||||
}
|
||||
if (tanstack) {
|
||||
const adapterResult = removeTanStackLiveAdapter({ cwd: process.cwd(), project: tanstack });
|
||||
console.log(JSON.stringify({ ok: !adapterResult.error, adapter: 'tanstack-start', results: [adapterResult] }));
|
||||
if (adapterResult.error) process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
if (nuxt) {
|
||||
const adapterResult = removeNuxtLiveAdapter({ cwd: process.cwd(), project: nuxt });
|
||||
console.log(JSON.stringify({ ok: !adapterResult.error, adapter: 'nuxt', results: [adapterResult] }));
|
||||
if (adapterResult.error) process.exitCode = 1;
|
||||
if (isAdapter) {
|
||||
const adapterResult = resolved.framework.inject.remove({ cwd, config, project: resolved.project });
|
||||
const ok = !(adapterResult && adapterResult.error);
|
||||
// Anything the adapter could not reach (its detection may have shifted
|
||||
// since the session started) is still on the journal.
|
||||
const { healed } = healInjectJournal(cwd);
|
||||
clearInjectJournal(cwd);
|
||||
console.log(JSON.stringify({
|
||||
ok,
|
||||
adapter: resolved.framework.name,
|
||||
results: [adapterResult],
|
||||
healed: healed.length ? healed : undefined,
|
||||
}));
|
||||
if (!ok) process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
const results = resolvedFiles.map((relFile) => {
|
||||
const absFile = path.resolve(process.cwd(), relFile);
|
||||
const absFile = path.resolve(cwd, relFile);
|
||||
if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
|
||||
const content = fs.readFileSync(absFile, 'utf-8');
|
||||
const detagged = removeTag(content, config.commentSyntax);
|
||||
@@ -168,7 +191,9 @@ Output (JSON):
|
||||
cspReverted: updated !== detagged,
|
||||
};
|
||||
});
|
||||
console.log(JSON.stringify({ ok: true, results }));
|
||||
const { healed } = healInjectJournal(cwd);
|
||||
clearInjectJournal(cwd);
|
||||
console.log(JSON.stringify({ ok: true, results, healed: healed.length ? healed : undefined }));
|
||||
return;
|
||||
}
|
||||
|
||||
@@ -180,50 +205,68 @@ Output (JSON):
|
||||
process.exit(1);
|
||||
}
|
||||
// Optional server token: appended to the /live.js src so the token-gated
|
||||
// /live.js handler authorizes the browser fetch. `live.mjs` always passes it.
|
||||
// /live.js handler authorizes the browser fetch. `live.mjs` always passes
|
||||
// it; a manual `--port`-only invocation reads the running helper's token
|
||||
// from server.json instead of writing an unauthenticated URL that 401s.
|
||||
const tokenIdx = args.indexOf('--token');
|
||||
const token = tokenIdx !== -1 ? args[tokenIdx + 1] : undefined;
|
||||
const gitIgnore = ensureLiveGitIgnores(
|
||||
process.cwd(),
|
||||
nuxt ? [nuxt.pluginFile] : tanstack ? [tanstack.componentFile] : [],
|
||||
);
|
||||
let token = tokenIdx !== -1 ? args[tokenIdx + 1] : undefined;
|
||||
if (!token) {
|
||||
try {
|
||||
const info = JSON.parse(fs.readFileSync(path.join(cwd, '.impeccable', 'live', 'server.json'), 'utf-8'));
|
||||
// A record for a DIFFERENT port is a stale or foreign helper; its token
|
||||
// would 401 just the same, so only adopt a matching one.
|
||||
if (info?.token && Number(info.port) === port) token = info.token;
|
||||
} catch { /* no running helper recorded; keep legacy tokenless behavior */ }
|
||||
}
|
||||
|
||||
if (svelteKit) {
|
||||
const adapterResult = applySvelteKitLiveAdapter({ cwd: process.cwd(), port, token, config });
|
||||
console.log(JSON.stringify({ ok: true, port, adapter: 'sveltekit', gitIgnore, results: [adapterResult] }));
|
||||
return;
|
||||
}
|
||||
if (tanstack) {
|
||||
const adapterResult = applyTanStackLiveAdapter({ cwd: process.cwd(), port, token, project: tanstack });
|
||||
console.log(JSON.stringify({
|
||||
ok: !adapterResult.error,
|
||||
// Reconcile before writing anything. Artifacts this run is about to own are
|
||||
// kept (so a repeat inject stays byte-idempotent); artifacts left behind by
|
||||
// a session that never got to stop are healed.
|
||||
const plannedArtifacts = describeInjectArtifacts(resolved, { cwd, files: resolvedFiles });
|
||||
const { healed } = healInjectJournal(cwd, { keep: plannedArtifacts.map((a) => a.path) });
|
||||
|
||||
const gitIgnore = ensureLiveGitIgnores(cwd, frameworkIgnorePatterns(resolved));
|
||||
// In a nested-app repo the roots pointer lives at the REPO root, outside the
|
||||
// reach of the appRoot-relative ignore block above; give that directory its
|
||||
// own local excludes so the pointer (absolute host paths) never gets staged.
|
||||
try {
|
||||
const rootsManifest = JSON.parse(fs.readFileSync(path.join(cwd, '.impeccable', 'live', 'roots.json'), 'utf-8'));
|
||||
if (rootsManifest?.repoRoot && path.resolve(rootsManifest.repoRoot) !== path.resolve(cwd)) {
|
||||
ensureLiveGitIgnores(rootsManifest.repoRoot);
|
||||
}
|
||||
} catch { /* no manifest: single-root project */ }
|
||||
|
||||
if (isAdapter) {
|
||||
const adapterResult = resolved.framework.inject.apply({
|
||||
cwd,
|
||||
port,
|
||||
adapter: 'tanstack-start',
|
||||
token,
|
||||
config,
|
||||
project: resolved.project,
|
||||
});
|
||||
const ok = !(adapterResult && adapterResult.error);
|
||||
if (ok) recordInjection(cwd, { framework: resolved.framework.name, port, artifacts: plannedArtifacts });
|
||||
console.log(JSON.stringify({
|
||||
ok,
|
||||
port,
|
||||
adapter: resolved.framework.name,
|
||||
gitIgnore,
|
||||
results: [adapterResult],
|
||||
healed: healed.length ? healed : undefined,
|
||||
}));
|
||||
if (adapterResult.error) process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
if (nuxt) {
|
||||
const adapterResult = applyNuxtLiveAdapter({ cwd: process.cwd(), port, token, project: nuxt });
|
||||
console.log(JSON.stringify({
|
||||
ok: !adapterResult.error,
|
||||
port,
|
||||
adapter: 'nuxt',
|
||||
gitIgnore,
|
||||
results: [adapterResult],
|
||||
}));
|
||||
if (adapterResult.error) process.exitCode = 1;
|
||||
if (!ok) process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
|
||||
const results = resolvedFiles.map((relFile) => {
|
||||
const absFile = path.resolve(process.cwd(), relFile);
|
||||
const absFile = path.resolve(cwd, relFile);
|
||||
if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
|
||||
const content = fs.readFileSync(absFile, 'utf-8');
|
||||
const withoutOld = revertCspMeta(removeTag(content, config.commentSyntax));
|
||||
const withTag = insertTag(withoutOld, config, port, relFile, token);
|
||||
// Per-file, not per-project: a Vite app can hold an .astro partial, and a
|
||||
// framework project's entry template is often plain HTML.
|
||||
const scriptAttrs = resolveSourceTraits(relFile).injectScriptAttrs;
|
||||
const withTag = insertTag(withoutOld, config, port, token, scriptAttrs);
|
||||
if (withTag === withoutOld) {
|
||||
return { file: relFile, error: 'insertion_point_not_found', anchor: config.insertBefore || config.insertAfter };
|
||||
}
|
||||
@@ -236,7 +279,19 @@ Output (JSON):
|
||||
};
|
||||
});
|
||||
const anyInserted = results.some((r) => r.inserted);
|
||||
console.log(JSON.stringify({ ok: anyInserted, port, gitIgnore, results }));
|
||||
const writtenFiles = new Set(results.filter((r) => r.inserted).map((r) => r.file));
|
||||
recordInjection(cwd, {
|
||||
framework: resolved?.framework.name,
|
||||
port,
|
||||
artifacts: plannedArtifacts.filter((a) => writtenFiles.has(a.path)),
|
||||
});
|
||||
console.log(JSON.stringify({
|
||||
ok: anyInserted,
|
||||
port,
|
||||
gitIgnore,
|
||||
results,
|
||||
healed: healed.length ? healed : undefined,
|
||||
}));
|
||||
if (!anyInserted) process.exit(1);
|
||||
}
|
||||
|
||||
@@ -271,115 +326,6 @@ export function ensureLiveGitIgnores(cwd = process.cwd(), extraPatterns = []) {
|
||||
};
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Nuxt adapter
|
||||
//
|
||||
// A script element placed in app.vue is compiled as Vue-rendered DOM and is
|
||||
// not executed. Nuxt instead auto-discovers client plugins. Keep the adapter
|
||||
// generated, dev-only, and outside user-authored source: Live creates one
|
||||
// marked .client.ts plugin on start and removes it on stop.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export function detectNuxtProject(cwd = process.cwd()) {
|
||||
const configFile = fs.readdirSync(cwd, { withFileTypes: true })
|
||||
.find((entry) => entry.isFile() && /^nuxt\.config\.(?:js|mjs|cjs|ts|mts|cts)$/.test(entry.name))
|
||||
?.name;
|
||||
if (!configFile) return null;
|
||||
|
||||
const config = fs.readFileSync(path.join(cwd, configFile), 'utf-8');
|
||||
const literalSrcDir = config.match(/\bsrcDir\s*:\s*(['"])([^'"]+)\1/);
|
||||
let appDir = '';
|
||||
if (literalSrcDir) {
|
||||
const candidate = literalSrcDir[2]
|
||||
.replace(/\\/g, '/')
|
||||
.replace(/^\.\//, '')
|
||||
.replace(/\/+$/, '');
|
||||
const normalized = path.posix.normalize(candidate);
|
||||
if (normalized !== '..' && !normalized.startsWith('../') && !path.isAbsolute(normalized)) {
|
||||
appDir = normalized === '.' ? '' : normalized;
|
||||
}
|
||||
} else if (
|
||||
fs.existsSync(path.join(cwd, 'app', 'app.vue'))
|
||||
|| fs.existsSync(path.join(cwd, 'app', 'pages'))
|
||||
) {
|
||||
appDir = 'app';
|
||||
}
|
||||
|
||||
const pluginFile = [appDir, 'plugins', NUXT_PLUGIN_NAME].filter(Boolean).join('/');
|
||||
return { configFile, appDir, pluginFile };
|
||||
}
|
||||
|
||||
export function buildNuxtPlugin(port, token) {
|
||||
return `/* ${NUXT_PLUGIN_MARKER} */
|
||||
const liveSrc = '${buildLiveScriptSrc(port, token)}';
|
||||
const liveSelector = 'script[data-impeccable-live-nuxt]';
|
||||
|
||||
export default defineNuxtPlugin(() => {
|
||||
if (!import.meta.dev || typeof document === 'undefined') return;
|
||||
|
||||
const expectedSrc = new URL(liveSrc, window.location.href).href;
|
||||
let script = document.querySelector(liveSelector);
|
||||
if (script?.src === expectedSrc) return;
|
||||
script?.remove();
|
||||
|
||||
script = document.createElement('script');
|
||||
script.src = liveSrc;
|
||||
script.async = true;
|
||||
script.dataset.impeccableLiveNuxt = '';
|
||||
document.head.appendChild(script);
|
||||
|
||||
import.meta.hot?.dispose(() => {
|
||||
if (script?.isConnected) script.remove();
|
||||
});
|
||||
});
|
||||
/* /${NUXT_PLUGIN_MARKER} */
|
||||
`;
|
||||
}
|
||||
|
||||
export function applyNuxtLiveAdapter({ cwd = process.cwd(), port, token, project = detectNuxtProject(cwd) }) {
|
||||
if (!project) return { error: 'nuxt_not_detected' };
|
||||
const absFile = path.join(cwd, project.pluginFile);
|
||||
const existing = fs.existsSync(absFile) ? fs.readFileSync(absFile, 'utf-8') : null;
|
||||
if (existing !== null && !existing.includes(NUXT_PLUGIN_MARKER)) {
|
||||
return {
|
||||
file: project.pluginFile,
|
||||
error: 'nuxt_plugin_conflict',
|
||||
hint: `${project.pluginFile} already exists and is not managed by Impeccable Live`,
|
||||
};
|
||||
}
|
||||
|
||||
const content = buildNuxtPlugin(port, token);
|
||||
fs.mkdirSync(path.dirname(absFile), { recursive: true });
|
||||
if (content !== existing) fs.writeFileSync(absFile, content, 'utf-8');
|
||||
return {
|
||||
file: project.pluginFile,
|
||||
inserted: true,
|
||||
changed: content !== existing,
|
||||
devOnly: true,
|
||||
};
|
||||
}
|
||||
|
||||
export function removeNuxtLiveAdapter({ cwd = process.cwd(), project = detectNuxtProject(cwd) }) {
|
||||
if (!project) return { error: 'nuxt_not_detected' };
|
||||
const absFile = path.join(cwd, project.pluginFile);
|
||||
if (!fs.existsSync(absFile)) {
|
||||
return { file: project.pluginFile, removed: false, note: 'no adapter present' };
|
||||
}
|
||||
const content = fs.readFileSync(absFile, 'utf-8');
|
||||
if (!content.includes(NUXT_PLUGIN_MARKER)) {
|
||||
return {
|
||||
file: project.pluginFile,
|
||||
removed: false,
|
||||
error: 'nuxt_plugin_conflict',
|
||||
hint: `${project.pluginFile} is not managed by Impeccable Live`,
|
||||
};
|
||||
}
|
||||
fs.unlinkSync(absFile);
|
||||
const pluginDir = path.dirname(absFile);
|
||||
if (fs.readdirSync(pluginDir).length === 0) fs.rmdirSync(pluginDir);
|
||||
return { file: project.pluginFile, removed: true };
|
||||
}
|
||||
|
||||
function resolveIgnoreTarget(cwd) {
|
||||
const gitExcludePath = resolveGitInfoExcludePath(cwd);
|
||||
if (gitExcludePath) {
|
||||
@@ -527,242 +473,31 @@ function validateConfig(cfg) {
|
||||
}
|
||||
}
|
||||
|
||||
function commentOpen(syntax) { return syntax === 'jsx' ? '{/*' : '<!--'; }
|
||||
function commentClose(syntax) { return syntax === 'jsx' ? '*/}' : '-->'; }
|
||||
|
||||
/**
|
||||
* Build the /live.js src the browser loads. When a token is supplied it rides
|
||||
* as a `?token=...` query param so the server's token-gated /live.js handler
|
||||
* authorizes the fetch. Shared by every injection path (HTML/JSX script tag,
|
||||
* the Nuxt plugin, the SvelteKit root component) so they stay in sync.
|
||||
*/
|
||||
export function buildLiveScriptSrc(port, token) {
|
||||
const base = 'http://localhost:' + port + '/live.js';
|
||||
return token ? base + '?token=' + encodeURIComponent(token) : base;
|
||||
}
|
||||
|
||||
function buildTagBlock(syntax, port, filePath, token) {
|
||||
const open = commentOpen(syntax);
|
||||
const close = commentClose(syntax);
|
||||
// Astro processes <script> tags by default and rewrites src to its own
|
||||
// bundled URL. is:inline opts out so the literal external src survives.
|
||||
const isAstro = typeof filePath === 'string' && filePath.endsWith('.astro');
|
||||
const scriptAttrs = isAstro ? 'is:inline ' : '';
|
||||
return (
|
||||
open + ' ' + MARKER_OPEN_TEXT + ' ' + close + '\n' +
|
||||
'<script ' + scriptAttrs + 'src="' + buildLiveScriptSrc(port, token) + '"></script>\n' +
|
||||
open + ' ' + MARKER_CLOSE_TEXT + ' ' + close + '\n'
|
||||
);
|
||||
}
|
||||
|
||||
function detectLineEnding(content) {
|
||||
if (content.includes('\r\n')) return '\r\n';
|
||||
if (content.includes('\r')) return '\r';
|
||||
return '\n';
|
||||
}
|
||||
|
||||
function normalizeLineEndings(content, lineEnding) {
|
||||
return lineEnding === '\n' ? content : content.replace(/\n/g, lineEnding);
|
||||
}
|
||||
|
||||
function readLineEndingAt(content, index) {
|
||||
if (content[index] === '\r' && content[index + 1] === '\n') return '\r\n';
|
||||
if (content[index] === '\n') return '\n';
|
||||
if (content[index] === '\r') return '\r';
|
||||
return '';
|
||||
}
|
||||
|
||||
function insertTag(content, config, port, filePath, token) {
|
||||
const lineEnding = detectLineEnding(content);
|
||||
const block = normalizeLineEndings(buildTagBlock(config.commentSyntax, port, filePath, token), lineEnding);
|
||||
// insertBefore: match the LAST occurrence. Anchors like `</body>` naturally
|
||||
// belong at the end, and the same literal can appear earlier in code blocks
|
||||
// within rendered documentation pages.
|
||||
if (config.insertBefore) {
|
||||
const idx = content.lastIndexOf(config.insertBefore);
|
||||
if (idx === -1) return content;
|
||||
return content.slice(0, idx) + block + content.slice(idx);
|
||||
}
|
||||
// insertAfter: match the FIRST occurrence — typical anchors like `<head>` or
|
||||
// `<body>` open near the top of the document.
|
||||
const idx = content.indexOf(config.insertAfter);
|
||||
if (idx === -1) return content;
|
||||
const after = idx + config.insertAfter.length;
|
||||
// Preserve an existing trailing newline if the anchor already has one.
|
||||
// Slice the remainder from the original anchor offset, not prefix.length:
|
||||
// in the no-newline case prefix is one char longer than the anchor (the
|
||||
// appended '\n'), so slicing by prefix.length would drop the first real
|
||||
// character after the anchor (#227).
|
||||
const existingNewline = readLineEndingAt(content, after);
|
||||
const prefix = content.slice(0, after) + (existingNewline || lineEnding);
|
||||
const rest = content.slice(after + existingNewline.length);
|
||||
return prefix + block + rest;
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove the live script block. Matches either HTML or JSX comment markers
|
||||
* regardless of config (so stale tags from a wrong config can still be cleaned).
|
||||
*
|
||||
* Indent-preserving: captures any whitespace immediately preceding the opener
|
||||
* marker and re-emits it in place of the removed block. `insertTag` inserted
|
||||
* the block *after* the original line's indent and *before* the anchor (e.g.
|
||||
* `</body>`), which moved the indent onto the opener line and left the anchor
|
||||
* unindented. Replacing the whole block (plus its trailing newline) with just
|
||||
* the captured indent hands the indent back to the anchor that follows.
|
||||
*/
|
||||
function removeTag(content, _syntax) {
|
||||
const patterns = [
|
||||
/([ \t]*)<!--\s*impeccable-live-start\s*-->[\s\S]*?<!--\s*impeccable-live-end\s*-->([ \t]*(?:\r\n|\n|\r|$)?)/,
|
||||
/([ \t]*)\{\/\*\s*impeccable-live-start\s*\*\/\}[\s\S]*?\{\/\*\s*impeccable-live-end\s*\*\/\}([ \t]*(?:\r\n|\n|\r|$)?)/,
|
||||
];
|
||||
for (const pat of patterns) {
|
||||
let changed = false;
|
||||
let next = content;
|
||||
do {
|
||||
content = next;
|
||||
next = content.replace(pat, (_match, leadingIndent, trailing = '') => {
|
||||
if (/[\r\n]/.test(trailing)) return leadingIndent;
|
||||
return leadingIndent || trailing || '';
|
||||
});
|
||||
if (next !== content) changed = true;
|
||||
} while (next !== content);
|
||||
if (changed) return next;
|
||||
}
|
||||
return content;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Content-Security-Policy meta-tag patcher
|
||||
//
|
||||
// When the user's HTML carries `<meta http-equiv="Content-Security-Policy">`,
|
||||
// the cross-origin load of /live.js (and the SSE/POST connection back to
|
||||
// localhost:PORT) is blocked unless the CSP explicitly allows that origin.
|
||||
//
|
||||
// On insert: append `http://localhost:PORT` to `script-src` and `connect-src`,
|
||||
// and stash the original `content` value in a `data-impeccable-csp-original`
|
||||
// attribute (base64) so revert is exact.
|
||||
//
|
||||
// On remove: detect the marker attribute, decode it, restore the original
|
||||
// content value verbatim, drop the marker.
|
||||
//
|
||||
// Header-based CSP (Next.js headers, Nuxt routeRules, SvelteKit kit.csp,
|
||||
// shared helpers) is NOT patched here — those need framework-specific config
|
||||
// edits and are handled via the existing detect-csp.mjs reference output.
|
||||
// Only the in-source meta-tag form gets the auto-patch.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const CSP_MARKER_ATTR = 'data-impeccable-csp-original';
|
||||
|
||||
function findCspMetaTags(content) {
|
||||
const out = [];
|
||||
const tagRe = /<meta\s+([^>]*?)\/?>/gis;
|
||||
let m;
|
||||
while ((m = tagRe.exec(content)) !== null) {
|
||||
const attrs = m[1];
|
||||
if (!/(http-equiv|httpEquiv)\s*=\s*(['"])Content-Security-Policy\2/i.test(attrs)) continue;
|
||||
out.push({ start: m.index, end: m.index + m[0].length, full: m[0], attrs });
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function getAttr(attrs, name) {
|
||||
const re = new RegExp(`\\b${name}\\s*=\\s*(['"])([\\s\\S]*?)\\1`, 'i');
|
||||
const m = attrs.match(re);
|
||||
return m ? { quote: m[1], value: m[2], full: m[0] } : null;
|
||||
}
|
||||
|
||||
function appendOriginToDirective(csp, directive, origin) {
|
||||
const re = new RegExp(`(^|;)(\\s*)(${directive})\\s+([^;]*)`, 'i');
|
||||
const m = csp.match(re);
|
||||
if (m) {
|
||||
const tokens = m[4].trim().split(/\s+/);
|
||||
if (tokens.includes(origin)) return csp;
|
||||
return csp.replace(re, `${m[1]}${m[2]}${m[3]} ${[...tokens, origin].join(' ')}`);
|
||||
}
|
||||
// Directive missing — add it. Use 'self' + origin so we don't inadvertently
|
||||
// narrow the policy compared to the default-src fallback (most users with
|
||||
// an explicit CSP have 'self' there).
|
||||
return csp.trim().replace(/;?\s*$/, '') + `; ${directive} 'self' ${origin}`;
|
||||
}
|
||||
|
||||
export function patchCspMeta(content, port) {
|
||||
const tags = findCspMetaTags(content);
|
||||
if (tags.length === 0) return content;
|
||||
const origin = `http://localhost:${port}`;
|
||||
|
||||
// Walk last-to-first so prior splices don't invalidate later indices.
|
||||
let result = content;
|
||||
for (let i = tags.length - 1; i >= 0; i--) {
|
||||
const tag = tags[i];
|
||||
const attrs = tag.attrs;
|
||||
if (getAttr(attrs, CSP_MARKER_ATTR)) continue; // already patched
|
||||
const contentAttr = getAttr(attrs, 'content');
|
||||
if (!contentAttr) continue;
|
||||
|
||||
const original = contentAttr.value;
|
||||
let patched = original;
|
||||
patched = appendOriginToDirective(patched, 'script-src', origin);
|
||||
patched = appendOriginToDirective(patched, 'connect-src', origin);
|
||||
// The shader overlay during 'generating' creates a screenshot via
|
||||
// URL.createObjectURL, producing a `blob:` URL — img-src 'self' rejects
|
||||
// those. Add `blob:` so the overlay doesn't throw a CSP violation.
|
||||
patched = appendOriginToDirective(patched, 'img-src', 'blob:');
|
||||
if (patched === original) continue;
|
||||
|
||||
const newContentAttr = `content=${contentAttr.quote}${patched}${contentAttr.quote}`;
|
||||
const marker = `${CSP_MARKER_ATTR}="${Buffer.from(original, 'utf-8').toString('base64')}"`;
|
||||
// The tagRe captures any whitespace between the last attribute and the
|
||||
// closing `/>` as part of `attrs`. Naively appending ` ${marker}` after
|
||||
// a replace would land it BEFORE that trailing space, leaving a double
|
||||
// space inside attrs and clobbering the space before `/>`. Split off
|
||||
// the trailing whitespace, splice the marker into the attribute body,
|
||||
// and re-append the original trailing whitespace so a self-closing
|
||||
// `<meta … />` round-trips byte-for-byte.
|
||||
const trailingWs = (attrs.match(/[ \t]*$/) || [''])[0];
|
||||
const attrsBody = attrs.slice(0, attrs.length - trailingWs.length);
|
||||
const newAttrs = attrsBody.replace(contentAttr.full, newContentAttr) + ' ' + marker + trailingWs;
|
||||
const newTag = tag.full.replace(attrs, newAttrs);
|
||||
|
||||
result = result.slice(0, tag.start) + newTag + result.slice(tag.end);
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
export function revertCspMeta(content) {
|
||||
const tags = findCspMetaTags(content);
|
||||
if (tags.length === 0) return content;
|
||||
|
||||
let result = content;
|
||||
for (let i = tags.length - 1; i >= 0; i--) {
|
||||
const tag = tags[i];
|
||||
const origAttr = getAttr(tag.attrs, CSP_MARKER_ATTR);
|
||||
if (!origAttr) continue;
|
||||
const contentAttr = getAttr(tag.attrs, 'content');
|
||||
if (!contentAttr) continue;
|
||||
|
||||
let originalValue;
|
||||
try { originalValue = Buffer.from(origAttr.value, 'base64').toString('utf-8'); }
|
||||
catch { continue; }
|
||||
|
||||
const newContentAttr = `content=${contentAttr.quote}${originalValue}${contentAttr.quote}`;
|
||||
let newAttrs = tag.attrs.replace(contentAttr.full, newContentAttr);
|
||||
// Drop the marker attribute and any single space immediately preceding it.
|
||||
newAttrs = newAttrs.replace(new RegExp(`\\s*${origAttr.full}`), '');
|
||||
const newTag = tag.full.replace(tag.attrs, newAttrs);
|
||||
|
||||
result = result.slice(0, tag.start) + newTag + result.slice(tag.end);
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Auto-execute
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const _running = process.argv[1];
|
||||
if (_running?.endsWith('live-inject.mjs') || _running?.endsWith('live-inject.mjs/')) {
|
||||
enterLiveRoot();
|
||||
injectCli();
|
||||
}
|
||||
|
||||
export { insertTag, removeTag, validateConfig, buildTagBlock };
|
||||
// patchCspMeta + revertCspMeta are exported above where they're defined.
|
||||
// Re-exported so long-standing importers (live.mjs, the adapter modules, the
|
||||
// test suites) keep their entry points while the implementations live in
|
||||
// live/frameworks/.
|
||||
export {
|
||||
buildLiveScriptSrc,
|
||||
buildTagBlock,
|
||||
insertTag,
|
||||
patchCspMeta,
|
||||
removeTag,
|
||||
revertCspMeta,
|
||||
validateConfig,
|
||||
};
|
||||
export {
|
||||
applyNuxtLiveAdapter,
|
||||
buildNuxtPlugin,
|
||||
detectNuxtProject,
|
||||
removeNuxtLiveAdapter,
|
||||
} from './live/frameworks/nuxt.mjs';
|
||||
|
||||
@@ -26,6 +26,7 @@ import {
|
||||
scaffoldSvelteComponentInsertSession,
|
||||
shouldUseSvelteComponentInjection,
|
||||
} from './live/svelte-component.mjs';
|
||||
import { enterLiveRoot } from './live/roots.mjs';
|
||||
|
||||
const INSERT_POSITIONS = new Set(['before', 'after']);
|
||||
|
||||
@@ -286,5 +287,6 @@ Output (JSON):
|
||||
|
||||
const _running = process.argv[1];
|
||||
if (_running?.endsWith('live-insert.mjs') || _running?.endsWith('live-insert.mjs/')) {
|
||||
enterLiveRoot();
|
||||
insertCli();
|
||||
}
|
||||
|
||||
@@ -14,6 +14,8 @@ import path from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { completionAckForAcceptResult, completionTypeForAcceptResult } from './live/completion.mjs';
|
||||
import { readLiveServerInfo } from './lib/impeccable-paths.mjs';
|
||||
import { enterLiveRoot } from './live/roots.mjs';
|
||||
import { instructionsForEvent } from './live/instructions.mjs';
|
||||
|
||||
// Absolute path to a sibling script in this skill's scripts dir, so runtime
|
||||
// error hints print a directly-runnable command instead of a placeholder.
|
||||
@@ -27,7 +29,7 @@ const scriptCmd = (name) => `node "${path.join(SELF_DIR, name)}"`;
|
||||
export const PER_REQUEST_TIMEOUT_MS = 270_000;
|
||||
export const DEFAULT_EVENT_LEASE_MS = 600_000;
|
||||
|
||||
const EVENT_TYPES_NEEDING_AGENT_REPLY = new Set(['generate', 'steer', 'manual_edit_apply', 'carbonize_cleanup']);
|
||||
const EVENT_TYPES_NEEDING_AGENT_REPLY = new Set(['generate', 'steer', 'manual_edit_apply', 'carbonize_cleanup', 'variant_mount_failed']);
|
||||
|
||||
function readServerInfo() {
|
||||
const record = readLiveServerInfo(process.cwd());
|
||||
@@ -117,8 +119,11 @@ export async function postReply(base, token, reply) {
|
||||
});
|
||||
if (!res.ok) {
|
||||
const body = await res.json().catch(() => ({}));
|
||||
const parts = [body.error || res.statusText, body.reason, body.hint].filter(Boolean);
|
||||
throw new Error(parts.join(': '));
|
||||
const failureLines = Array.isArray(body.failures)
|
||||
? body.failures.map((f) => ` ${f.file}${f.line != null ? `:${f.line}` : ''} ${f.message}`).join('\n')
|
||||
: null;
|
||||
const parts = [body.error || res.statusText, body.reason, body.hint, failureLines, body._instructions].filter(Boolean);
|
||||
throw new Error(parts.join('\n'));
|
||||
}
|
||||
}
|
||||
|
||||
@@ -261,6 +266,13 @@ export function writeCarbonizeBanner(event) {
|
||||
}
|
||||
|
||||
export function printPollEvent(event) {
|
||||
// Situational plumbing rides with the event itself: `_instructions` is the
|
||||
// authoritative next step, with real ids and paths substituted, so the
|
||||
// reference doc can stay lean and can never drift from script behavior.
|
||||
if (event && typeof event === 'object' && !event._instructions) {
|
||||
const instructions = instructionsForEvent(event, { scriptsPath: SELF_DIR });
|
||||
if (instructions) event._instructions = instructions;
|
||||
}
|
||||
console.log(JSON.stringify(event));
|
||||
}
|
||||
|
||||
@@ -412,5 +424,6 @@ export function normalizePollTypes(value) {
|
||||
// Auto-execute when run directly
|
||||
const _running = process.argv[1];
|
||||
if (_running?.endsWith('live-poll.mjs') || _running?.endsWith('live-poll.mjs/')) {
|
||||
enterLiveRoot();
|
||||
pollCli();
|
||||
}
|
||||
|
||||
@@ -4,6 +4,7 @@
|
||||
*/
|
||||
|
||||
import { createLiveSessionStore } from './live/session-store.mjs';
|
||||
import { enterLiveRoot } from './live/roots.mjs';
|
||||
|
||||
function manualApplyReplyCommand(eventOrId = 'EVENT_ID') {
|
||||
const id = typeof eventOrId === 'string' ? eventOrId : eventOrId?.id || 'EVENT_ID';
|
||||
@@ -49,6 +50,28 @@ function collectManualApplyFiles(batch) {
|
||||
return [...new Set(files.filter((file) => typeof file === 'string' && file.length > 0))].sort();
|
||||
}
|
||||
|
||||
/**
|
||||
* The browser's render truth, folded into a small block the agent reads before
|
||||
* it decides what to do. `arrivedVariants` only says the agent published;
|
||||
* `renderState` says whether any of it reached a screen.
|
||||
*/
|
||||
export function renderSummary(snapshot = {}) {
|
||||
return {
|
||||
renderState: snapshot.renderState ?? null,
|
||||
mountedVariants: Array.isArray(snapshot.mountedVariants) ? snapshot.mountedVariants : [],
|
||||
mountFailures: Array.isArray(snapshot.mountFailures) ? snapshot.mountFailures : [],
|
||||
};
|
||||
}
|
||||
|
||||
export function mountFailureAction(snapshot = {}) {
|
||||
const failures = Array.isArray(snapshot.mountFailures) ? snapshot.mountFailures : [];
|
||||
const latest = failures[failures.length - 1];
|
||||
if (!latest) return null;
|
||||
const where = latest.url ? ` from ${latest.url}` : '';
|
||||
const why = latest.error ? ` (${latest.error})` : '';
|
||||
return `The browser failed to mount variant ${latest.variant}${where}${why}; nothing is on screen. Fix the variant files, then reply with live-poll.mjs --reply ${snapshot?.pendingEvent?.id || snapshot?.id || 'SESSION_ID'} done --file <manifest or source path> for the queued variant_mount_failed event (or republish) so the browser retries.`;
|
||||
}
|
||||
|
||||
function parseArgs(argv) {
|
||||
const out = { id: null };
|
||||
for (let i = 0; i < argv.length; i++) {
|
||||
@@ -75,20 +98,26 @@ export async function resumeCli() {
|
||||
}
|
||||
|
||||
const pending = snapshot.pendingEvent || null;
|
||||
const nextAction = pending
|
||||
? pending.type === 'manual_edit_apply'
|
||||
? manualApplyResumeHint(pending)
|
||||
: `Run live-poll.mjs, handle ${pending.type} ${pending.id}, then acknowledge with live-poll.mjs --reply ${pending.id} done.`
|
||||
: snapshot.phase === 'carbonize_required'
|
||||
? `Finish carbonize cleanup${snapshot.sourceFile ? ` in ${snapshot.sourceFile}` : ''}, then run live-complete.mjs --id ${snapshot.id}.`
|
||||
: snapshot.phase === 'accept_requested'
|
||||
? `Run live-complete.mjs --id ${snapshot.id} after verifying the accepted variant is written.`
|
||||
: `Inspect ${snapshot.id}; no pending agent event is currently queued.`;
|
||||
const render = renderSummary(snapshot);
|
||||
// A failed render outranks the generic pending-event hint: the agent needs to
|
||||
// know the user is staring at an error card, not at variants. A leased manual
|
||||
// Apply still outranks both, because abandoning that lease loses user edits.
|
||||
const mountAction = render.renderState === 'failed' ? mountFailureAction(snapshot) : null;
|
||||
const nextAction = pending?.type === 'manual_edit_apply'
|
||||
? manualApplyResumeHint(pending)
|
||||
: mountAction || (pending
|
||||
? `Run live-poll.mjs, handle ${pending.type} ${pending.id}, then acknowledge with live-poll.mjs --reply ${pending.id} done.`
|
||||
: snapshot.phase === 'carbonize_required'
|
||||
? `Finish carbonize cleanup${snapshot.sourceFile ? ` in ${snapshot.sourceFile}` : ''}, then run live-complete.mjs --id ${snapshot.id}.`
|
||||
: snapshot.phase === 'accept_requested'
|
||||
? `Run live-complete.mjs --id ${snapshot.id} after verifying the accepted variant is written.`
|
||||
: `Inspect ${snapshot.id}; no pending agent event is currently queued.`);
|
||||
|
||||
console.log(JSON.stringify({ active: true, snapshot, pendingEvent: pending, nextAction }, null, 2));
|
||||
console.log(JSON.stringify({ active: true, snapshot, pendingEvent: pending, render, nextAction }, null, 2));
|
||||
}
|
||||
|
||||
const _running = process.argv[1];
|
||||
if (_running?.endsWith('live-resume.mjs') || _running?.endsWith('live-resume.mjs/')) {
|
||||
enterLiveRoot();
|
||||
resumeCli();
|
||||
}
|
||||
|
||||
@@ -33,7 +33,10 @@ import { runGenerationPreflight } from './live/generation-preflight.mjs';
|
||||
import { validateEvent } from './live/event-validation.mjs';
|
||||
import { selectAvailablePendingEvent } from './live/poll-lanes.mjs';
|
||||
import { createManualEditRoutes } from './live/manual-edit-routes.mjs';
|
||||
import { LIVE_COMMANDS } from './live/vocabulary.mjs';
|
||||
import {
|
||||
LIVE_COMMANDS,
|
||||
VARIANT_PROGRESS_CHECKPOINT_REASONS as VARIANT_PROGRESS_CHECKPOINT_REASON_LIST,
|
||||
} from './live/vocabulary.mjs';
|
||||
import {
|
||||
getDesignSidecarPath,
|
||||
getLiveDir,
|
||||
@@ -51,24 +54,53 @@ import {
|
||||
} from './live/manual-apply.mjs';
|
||||
import {
|
||||
applyDeferredSvelteComponentAccepts,
|
||||
bumpSvelteComponentPreviewRevision,
|
||||
compileCheckVariants,
|
||||
removeAllSvelteComponentSessions,
|
||||
sweepInactiveSvelteComponentSessions,
|
||||
} from './live/svelte-component.mjs';
|
||||
import { enterLiveRoot } from './live/roots.mjs';
|
||||
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
||||
// PRODUCT.md / DESIGN.md live wherever context.mjs resolves. The generated
|
||||
// DESIGN sidecar is project-local at .impeccable/design.json, with legacy
|
||||
// DESIGN.json fallback for existing projects.
|
||||
const PROJECT_CONTEXT = loadContext(process.cwd());
|
||||
const CONTEXT_DIR = PROJECT_CONTEXT.contextDir;
|
||||
const DESIGN_MD_PATH = PROJECT_CONTEXT.designPath
|
||||
? path.resolve(process.cwd(), PROJECT_CONTEXT.designPath)
|
||||
: null;
|
||||
// Anchor the whole process on the live roots manifest before anything derives
|
||||
// a path from cwd. A server started from the wrong directory re-roots itself
|
||||
// onto the appRoot the boot decided on instead of minting a second project.
|
||||
const LIVE_ROOTS = enterLiveRoot(process.cwd());
|
||||
|
||||
// PRODUCT.md / DESIGN.md context, resolved lazily and per request so a server
|
||||
// that outlives an `impeccable document` run (or a context file created after
|
||||
// boot) reports current truth instead of a boot-time snapshot. The roots
|
||||
// manifest wins when the ambient resolution misses (nested app inheriting
|
||||
// repo-level context files).
|
||||
function resolveProjectContext() {
|
||||
const ctx = loadContext(process.cwd());
|
||||
const designPath = ctx.designPath
|
||||
? path.resolve(process.cwd(), ctx.designPath)
|
||||
: (LIVE_ROOTS?.designPath && fs.existsSync(LIVE_ROOTS.designPath) ? LIVE_ROOTS.designPath : null);
|
||||
const hasProduct = ctx.hasProduct
|
||||
|| !!(LIVE_ROOTS?.productPath && fs.existsSync(LIVE_ROOTS.productPath));
|
||||
return {
|
||||
...ctx,
|
||||
hasProduct,
|
||||
hasDesign: !!designPath,
|
||||
resolvedDesignPath: designPath,
|
||||
contextDir: ctx.contextDir || LIVE_ROOTS?.contextRoot || process.cwd(),
|
||||
designContextDir: ctx.designContextDir
|
||||
|| (designPath ? path.dirname(designPath) : null),
|
||||
};
|
||||
}
|
||||
const DEFAULT_POLL_TIMEOUT = 600_000; // 10 min — agent re-polls on timeout anyway
|
||||
const SSE_HEARTBEAT_INTERVAL = 30_000; // keepalive ping every 30s
|
||||
|
||||
// The browser events allowed to mint a NEW session journal. `generate` starts
|
||||
// a variant session at Go; `steer` mints its own request id. Every other
|
||||
// id-carrying event must land on an existing session (see the unknown_session
|
||||
// gate in the /events handler).
|
||||
const SESSION_CREATING_EVENT_TYPES = new Set(['generate', 'steer']);
|
||||
// The browser checkpoints for several unrelated reasons (see checkpointPayload
|
||||
// in live-browser.js). Only these two report that variant availability changed,
|
||||
// and only they may drive variant_progress / the *_reviewable phases.
|
||||
const VARIANT_PROGRESS_CHECKPOINT_REASONS = new Set(['variants_progress', 'variants_ready']);
|
||||
const VARIANT_PROGRESS_CHECKPOINT_REASONS = new Set(VARIANT_PROGRESS_CHECKPOINT_REASON_LIST);
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Port detection
|
||||
@@ -150,7 +182,16 @@ function chatAgentLikelyActive() {
|
||||
const MAX_ANNOTATION_BYTES = 10 * 1024 * 1024;
|
||||
|
||||
function enqueueEvent(event) {
|
||||
if (!event || (event.id && state.pendingEvents.some((entry) => entry.event?.id === event.id && entry.event?.type === event.type))) return;
|
||||
if (!event) return;
|
||||
// Dedupe by (session, type), except mount failures, which are per-variant:
|
||||
// variant 2 failing must not be swallowed because variant 1's failure is
|
||||
// still queued.
|
||||
const duplicate = event.id && state.pendingEvents.some((entry) => (
|
||||
entry.event?.id === event.id
|
||||
&& entry.event?.type === event.type
|
||||
&& (event.type !== 'variant_mount_failed' || entry.event?.variant === event.variant)
|
||||
));
|
||||
if (duplicate) return;
|
||||
state.pendingEvents.push({ event, leaseUntil: 0, seq: state.nextEventSeq++ });
|
||||
flushPendingPolls();
|
||||
}
|
||||
@@ -445,6 +486,11 @@ function summarizeActiveSessionForClient(snapshot = {}) {
|
||||
generationCompletedAt: snapshot.generationCompletedAt ?? null,
|
||||
generationCanceled: snapshot.generationCanceled === true,
|
||||
cancelReason: snapshot.cancelReason ?? null,
|
||||
// Render truth, so a browser with no localStorage can rehydrate to the
|
||||
// same comparison the server already knows about.
|
||||
mountedVariants: Array.isArray(snapshot.mountedVariants) ? snapshot.mountedVariants : [],
|
||||
mountFailures: Array.isArray(snapshot.mountFailures) ? snapshot.mountFailures : [],
|
||||
renderState: snapshot.renderState ?? null,
|
||||
};
|
||||
}
|
||||
|
||||
@@ -618,7 +664,7 @@ function hasProjectContext() {
|
||||
// PRODUCT.md carries brand voice / anti-references — that's what determines
|
||||
// whether variants are brand-aware. DESIGN.md (visual tokens) is a separate
|
||||
// concern, surfaced by the design panel's own empty state.
|
||||
return !!PROJECT_CONTEXT.hasProduct;
|
||||
return !!resolveProjectContext().hasProduct;
|
||||
}
|
||||
|
||||
function statOrNull(filePath) {
|
||||
@@ -690,6 +736,7 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
|
||||
port: state.port,
|
||||
vocabulary: LIVE_COMMANDS,
|
||||
commandPrefix: IMPECCABLE_COMMAND_PREFIX,
|
||||
appRoot: process.cwd(),
|
||||
parts,
|
||||
});
|
||||
res.writeHead(200, {
|
||||
@@ -827,8 +874,9 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
|
||||
const token = url.searchParams.get('token');
|
||||
if (token !== state.token) { res.writeHead(401); res.end('Unauthorized'); return; }
|
||||
|
||||
const mdPath = DESIGN_MD_PATH;
|
||||
const jsonPath = resolveDesignSidecarPath(process.cwd(), PROJECT_CONTEXT.designContextDir || CONTEXT_DIR) || getDesignSidecarPath(process.cwd());
|
||||
const projectContext = resolveProjectContext();
|
||||
const mdPath = projectContext.resolvedDesignPath;
|
||||
const jsonPath = resolveDesignSidecarPath(process.cwd(), projectContext.designContextDir || projectContext.contextDir) || getDesignSidecarPath(process.cwd());
|
||||
const mdStat = statOrNull(mdPath);
|
||||
const jsonStat = statOrNull(jsonPath);
|
||||
|
||||
@@ -979,6 +1027,20 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
|
||||
res.end(JSON.stringify({ ok: true }));
|
||||
return;
|
||||
}
|
||||
// Only the events that START a session may create its journal.
|
||||
// Everything else (checkpoints, mount acks, accept/discard) must
|
||||
// reference a session THIS store already knows: appendEvent creates a
|
||||
// journal for any id it is handed, so without this gate a browser
|
||||
// resuming another project's session from per-origin storage (two
|
||||
// apps sharing a localhost port) materializes a ghost session here
|
||||
// that keeps reattaching after every discard.
|
||||
if (msg.id && state.sessionStore
|
||||
&& !SESSION_CREATING_EVENT_TYPES.has(msg.type)
|
||||
&& !state.sessionStore.has(msg.id)) {
|
||||
res.writeHead(404, { 'Content-Type': 'application/json' });
|
||||
res.end(JSON.stringify({ error: 'unknown_session', id: msg.id }));
|
||||
return;
|
||||
}
|
||||
const missedCompletion = detectMissedGenerationCompletion(msg);
|
||||
if (state.sessionStore && msg.id) {
|
||||
try {
|
||||
@@ -997,7 +1059,25 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
|
||||
if (msg.type === 'exit') {
|
||||
cleanupSvelteComponentSessionsBeforeExit();
|
||||
}
|
||||
if (msg.type !== 'checkpoint') {
|
||||
// An ORPHANED discard is the browser reporting that the session's
|
||||
// wrapper no longer exists in source (edited or regenerated away).
|
||||
// There is no cleanup for an agent to perform, and asking one to run
|
||||
// the normal discard flow would just fail against the missing
|
||||
// scaffolding, so the server terminalizes the session itself and the
|
||||
// event stays out of the poll queue.
|
||||
const orphanedDiscard = msg.type === 'discard' && msg.orphaned === true;
|
||||
if (orphanedDiscard && state.sessionStore && msg.id) {
|
||||
try {
|
||||
state.sessionStore.appendEvent({ type: 'discarded', id: msg.id, orphaned: true });
|
||||
} catch { /* the discard_requested phase already left the resumable set */ }
|
||||
}
|
||||
// `variant_mounted` is the happy path: it is journaled above so the
|
||||
// snapshot carries render truth, but there is nothing for the agent to
|
||||
// do about it, so it stays out of the poll queue and off the SSE bus.
|
||||
// `variant_mount_failed` is the opposite: the agent published something
|
||||
// the browser could not render, and only the agent can fix it, so it
|
||||
// goes to the queue as a first-class event.
|
||||
if (msg.type !== 'checkpoint' && msg.type !== 'variant_mounted' && !orphanedDiscard) {
|
||||
enqueueEvent(msg);
|
||||
}
|
||||
res.writeHead(200, { 'Content-Type': 'application/json' });
|
||||
@@ -1099,7 +1179,8 @@ function sessionFileMetadataFromPollReply(file) {
|
||||
const base = { file: normalized };
|
||||
const metadataFile = normalized;
|
||||
if (!metadataFile.endsWith('/manifest.json') && metadataFile !== 'manifest.json') return base;
|
||||
if (!metadataFile.includes('node_modules/.impeccable-live/')
|
||||
if (!metadataFile.includes('.impeccable/live/previews/')
|
||||
&& !metadataFile.includes('node_modules/.impeccable-live/')
|
||||
&& !metadataFile.includes('src/lib/impeccable/')
|
||||
&& !metadataFile.includes('/.impeccable-live/')) return base;
|
||||
|
||||
@@ -1139,7 +1220,14 @@ function inferSourceEventType(msg = {}, pendingEvents = state.pendingEvents) {
|
||||
// `agent_done` can be the automatic acknowledgement for a carbonize Accept.
|
||||
// New pollers send sourceEventType explicitly; default to generate only for
|
||||
// older callers so a late worker cannot acknowledge a queued Accept.
|
||||
if (msg.type === 'agent_done' || msg.type === 'done') return 'generate';
|
||||
if (msg.type === 'agent_done' || msg.type === 'done') {
|
||||
// A `done` reply to a mount failure is the republish that unblocks the
|
||||
// browser. Without this the ack would look for a `generate` that was
|
||||
// already retired, the mount-failure event would stay queued, and the next
|
||||
// poll would hand the same failure back to the agent forever.
|
||||
if (!pendingTypes.has('generate') && pendingTypes.has('variant_mount_failed')) return 'variant_mount_failed';
|
||||
return 'generate';
|
||||
}
|
||||
// `error` is reference/live.md's documented failure reply, and parseReplyArgs
|
||||
// never sets sourceEventType on it (the poller is a fresh process that cannot
|
||||
// know what it leased). Returning undefined here makes acknowledgePendingEvent
|
||||
@@ -1264,6 +1352,30 @@ function handlePollPost(req, res) {
|
||||
return;
|
||||
}
|
||||
const replyFileMeta = sessionFileMetadataFromPollReply(msg.file);
|
||||
// A publish (done reply carrying a component manifest) snapshots the
|
||||
// variant files into a fresh revision dir before the browser is told:
|
||||
// the import path changes every publish, so no transform cache can pin a
|
||||
// stale compile of a republished module (node_modules is unwatched).
|
||||
// Broken variants are bounced HERE, before the browser imports anything:
|
||||
// a compile error that reaches the page is a red overlay in the user's
|
||||
// face; bounced at publish it is a private fix with file and line.
|
||||
if (replyFileMeta.previewMode === 'svelte-component'
|
||||
&& msg.id
|
||||
&& (msg.type === 'done' || !msg.type)) {
|
||||
let compileCheck = { ok: true, failures: [] };
|
||||
try { compileCheck = compileCheckVariants(msg.id, process.cwd()); } catch { /* best-effort */ }
|
||||
if (!compileCheck.ok) {
|
||||
res.writeHead(422, { 'Content-Type': 'application/json' });
|
||||
res.end(JSON.stringify({
|
||||
error: 'variant_compile_failed',
|
||||
id: msg.id,
|
||||
failures: compileCheck.failures,
|
||||
_instructions: 'The publish was NOT delivered: the listed variant file(s) do not compile, so the browser never saw them. Fix each failure at the given file and line (the most common cause is a second top-level <style> element; Svelte allows exactly one, so merge all rules into the existing block), then send the same --reply done again.',
|
||||
}));
|
||||
return;
|
||||
}
|
||||
try { bumpSvelteComponentPreviewRevision(msg.id, process.cwd()); } catch { /* best-effort */ }
|
||||
}
|
||||
if (state.sessionStore && msg.id && !skipJournalReply) {
|
||||
try {
|
||||
const eventType = msg.type === 'steer_done'
|
||||
@@ -1335,6 +1447,51 @@ function cleanupSvelteComponentSessionsBeforeExit() {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* A previous run that died without its shutdown hook leaves preview component
|
||||
* dirs behind. Drop the ones whose session the store no longer considers
|
||||
* active; anything still active is mid-generation and must survive a restart.
|
||||
*/
|
||||
function sweepOrphanSvelteComponentSessionsOnStartup() {
|
||||
try {
|
||||
const activeIds = (state.sessionStore?.listActiveSessions() || [])
|
||||
.map((snapshot) => snapshot?.id)
|
||||
.filter(Boolean);
|
||||
const result = sweepInactiveSvelteComponentSessions(activeIds, process.cwd());
|
||||
if (result.removed.length > 0 || result.removedRoot) {
|
||||
console.log('[impeccable] swept orphaned Svelte component sessions:', JSON.stringify(result));
|
||||
}
|
||||
} catch (err) {
|
||||
console.warn('[impeccable] Svelte component session sweep failed:', err.message);
|
||||
}
|
||||
}
|
||||
|
||||
// Accept receipts are a short-lived idempotency record for a single accept.
|
||||
// Nothing reads one after the session that wrote it is gone, so they only need
|
||||
// to outlive a crash-and-retry window.
|
||||
const ACCEPT_RECEIPT_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000;
|
||||
|
||||
function sweepStaleAcceptReceiptsOnStartup() {
|
||||
try {
|
||||
const dir = path.join(getLiveDir(process.cwd()), 'accept-receipts');
|
||||
if (!fs.existsSync(dir)) return;
|
||||
const cutoff = Date.now() - ACCEPT_RECEIPT_MAX_AGE_MS;
|
||||
let removed = 0;
|
||||
for (const name of fs.readdirSync(dir)) {
|
||||
if (!name.endsWith('.json') && !name.endsWith('.tmp')) continue;
|
||||
const file = path.join(dir, name);
|
||||
try {
|
||||
if (fs.statSync(file).mtimeMs >= cutoff) continue;
|
||||
fs.rmSync(file, { force: true });
|
||||
removed++;
|
||||
} catch { /* non-fatal */ }
|
||||
}
|
||||
if (removed > 0) console.log(`[impeccable] removed ${removed} accept receipt(s) older than 14 days`);
|
||||
} catch (err) {
|
||||
console.warn('[impeccable] accept receipt retention sweep failed:', err.message);
|
||||
}
|
||||
}
|
||||
|
||||
function applyLegacyDeferredAcceptsOnStartup() {
|
||||
try {
|
||||
const result = applyDeferredSvelteComponentAccepts(process.cwd());
|
||||
@@ -1474,6 +1631,8 @@ manualApply.rollbackTransaction({
|
||||
reason: 'manual_edit_server_start_recovered_abandoned_transaction',
|
||||
});
|
||||
applyLegacyDeferredAcceptsOnStartup();
|
||||
sweepOrphanSvelteComponentSessionsOnStartup();
|
||||
sweepStaleAcceptReceiptsOnStartup();
|
||||
restorePendingEventsFromStore();
|
||||
manualApply.pruneStaleEvidence();
|
||||
const portArg = args.find(a => a.startsWith('--port='));
|
||||
|
||||
@@ -5,7 +5,8 @@
|
||||
|
||||
import { createLiveSessionStore } from './live/session-store.mjs';
|
||||
import { readLiveServerInfo } from './lib/impeccable-paths.mjs';
|
||||
import { manualApplyResumeHint } from './live-resume.mjs';
|
||||
import { manualApplyResumeHint, mountFailureAction, renderSummary } from './live-resume.mjs';
|
||||
import { enterLiveRoot } from './live/roots.mjs';
|
||||
|
||||
function readServerInfo() {
|
||||
return readLiveServerInfo(process.cwd())?.info || null;
|
||||
@@ -28,6 +29,8 @@ export async function statusCli() {
|
||||
const store = createLiveSessionStore({ cwd: process.cwd() });
|
||||
const activeSessions = store.listActiveSessions();
|
||||
const manualApply = findPendingManualApply(server, activeSessions);
|
||||
const sessions = server?.activeSessions || activeSessions;
|
||||
const renderFailure = sessions.find((session) => session?.renderState === 'failed') || null;
|
||||
const payload = {
|
||||
liveServer: server ? {
|
||||
status: server.status,
|
||||
@@ -36,14 +39,16 @@ export async function statusCli() {
|
||||
agentPolling: server.agentPolling,
|
||||
pendingEvents: server.pendingEvents,
|
||||
} : null,
|
||||
activeSessions: server?.activeSessions || activeSessions,
|
||||
recoveryHint: recoveryHint({ server, manualApply }),
|
||||
activeSessions: sessions,
|
||||
render: sessions.map((session) => ({ id: session?.id ?? null, ...renderSummary(session) })),
|
||||
recoveryHint: recoveryHint({ server, manualApply, renderFailure }),
|
||||
};
|
||||
console.log(JSON.stringify(payload, null, 2));
|
||||
}
|
||||
|
||||
function recoveryHint({ server, manualApply }) {
|
||||
function recoveryHint({ server, manualApply, renderFailure }) {
|
||||
if (manualApply) return manualApplyResumeHint(manualApply);
|
||||
if (renderFailure) return mountFailureAction(renderFailure);
|
||||
if (server) {
|
||||
return 'Run live-poll.mjs to continue pending work, or live-complete.mjs --id <session> after manual cleanup.';
|
||||
}
|
||||
@@ -61,5 +66,6 @@ function findPendingManualApply(server, activeSessions) {
|
||||
|
||||
const _running = process.argv[1];
|
||||
if (_running?.endsWith('live-status.mjs') || _running?.endsWith('live-status.mjs/')) {
|
||||
enterLiveRoot();
|
||||
statusCli();
|
||||
}
|
||||
|
||||
@@ -17,11 +17,13 @@ import { isGeneratedFile } from './lib/is-generated.mjs';
|
||||
import { resolveLiveTemplateExtensions } from './lib/template-extensions.mjs';
|
||||
import { readBuffer as readManualEditsBuffer } from './live/manual-edits-buffer.mjs';
|
||||
import { findSourceFile } from './live/source-search.mjs';
|
||||
import { resolveSourceTraits } from './live/frameworks/index.mjs';
|
||||
import {
|
||||
buildSvelteComponentCssAuthoring,
|
||||
scaffoldSvelteComponentSession,
|
||||
shouldUseSvelteComponentInjection,
|
||||
} from './live/svelte-component.mjs';
|
||||
import { enterLiveRoot } from './live/roots.mjs';
|
||||
|
||||
export async function wrapCli() {
|
||||
const args = process.argv.slice(2);
|
||||
@@ -293,8 +295,10 @@ The agent should insert variant HTML at insertLine.`);
|
||||
.join('\n');
|
||||
const originalIndented = reindentOriginal(' ');
|
||||
const relTargetFile = path.relative(process.cwd(), targetFile).split(path.sep).join('/');
|
||||
const useSvelteComponent = shouldUseSvelteComponentInjection(targetFile);
|
||||
const useFrameworkComponent = useSvelteComponent;
|
||||
// The registry says which files get component preview; the svelte-component
|
||||
// module keeps the env escape hatch that turns it off.
|
||||
const useSvelteComponent = resolveSourceTraits(targetFile).preview === 'component'
|
||||
&& shouldUseSvelteComponentInjection(targetFile);
|
||||
|
||||
// Wrapper attributes differ by syntax. HTML allows plain string attrs;
|
||||
// JSX requires object-literal style and parses string attrs as HTML (which
|
||||
@@ -343,12 +347,18 @@ The agent should insert variant HTML at insertLine.`);
|
||||
let svelteSession = null;
|
||||
let deferredWrapper = null;
|
||||
|
||||
let sveltePreviewFallback = null;
|
||||
if (useSvelteComponent) {
|
||||
// Svelte/SvelteKit resets component-local state on markup HMR updates.
|
||||
// Keep generation source-neutral: agents write real variant components
|
||||
// under the generated componentDir, the browser mounts them into the live
|
||||
// DOM, and live-accept.mjs inlines the accepted variant back into the route.
|
||||
svelteSession = scaffoldSvelteComponentSession({
|
||||
//
|
||||
// The scaffold is AST-based and refuses markup a detached preview cannot
|
||||
// support (component tags, bind:/use:, await blocks, bound nested each).
|
||||
// Refusal falls back to the plain source-preview wrapper below: an
|
||||
// HMR-resetting but CORRECT preview beats a detached wrong one.
|
||||
const scaffolded = scaffoldSvelteComponentSession({
|
||||
id,
|
||||
count,
|
||||
sourceFile: relTargetFile,
|
||||
@@ -357,10 +367,18 @@ The agent should insert variant HTML at insertLine.`);
|
||||
originalLines,
|
||||
cwd: process.cwd(),
|
||||
});
|
||||
outputFile = path.resolve(process.cwd(), svelteSession.manifestFile);
|
||||
outputStartLine = 1;
|
||||
outputEndLine = 1;
|
||||
insertLine = 1;
|
||||
if (scaffolded && scaffolded.fallback === 'source-preview') {
|
||||
sveltePreviewFallback = scaffolded.reason || 'unsupported markup';
|
||||
} else {
|
||||
svelteSession = scaffolded;
|
||||
outputFile = path.resolve(process.cwd(), svelteSession.manifestFile);
|
||||
outputStartLine = 1;
|
||||
outputEndLine = 1;
|
||||
insertLine = 1;
|
||||
}
|
||||
}
|
||||
if (svelteSession) {
|
||||
// component preview: outputs already set above
|
||||
} else if (deferSourceWrite) {
|
||||
// Deferred source write: compute the scaffold text but leave source
|
||||
// untouched. The agent replaces the picked element's source range with
|
||||
@@ -396,15 +414,19 @@ The agent should insert variant HTML at insertLine.`);
|
||||
|
||||
const outputRelFile = path.relative(process.cwd(), outputFile).split(path.sep).join('/');
|
||||
|
||||
const svelteComponentAuthoring = useSvelteComponent ? buildSvelteComponentCssAuthoring(count) : null;
|
||||
const componentPreviewActive = !!svelteSession;
|
||||
const svelteComponentAuthoring = componentPreviewActive ? buildSvelteComponentCssAuthoring(count) : null;
|
||||
const componentSession = svelteSession;
|
||||
const componentPreviewMode = useSvelteComponent ? 'svelte-component' : undefined;
|
||||
const componentPreviewMode = componentPreviewActive ? 'svelte-component' : undefined;
|
||||
const previewMode = componentPreviewMode;
|
||||
|
||||
console.log(JSON.stringify({
|
||||
file: outputRelFile,
|
||||
sourceFile: useFrameworkComponent ? relTargetFile : undefined,
|
||||
sourceFile: componentPreviewActive ? relTargetFile : undefined,
|
||||
previewMode,
|
||||
previewFallback: sveltePreviewFallback
|
||||
? { from: 'svelte-component', reason: sveltePreviewFallback }
|
||||
: undefined,
|
||||
// Deferred source write: the wrapper is NOT yet in source. The agent
|
||||
// replaces [replaceStartLine, replaceEndLine] with `wrapperBlock` (variants
|
||||
// spliced at the "insert below this line" marker) in one atomic edit.
|
||||
@@ -414,8 +436,9 @@ The agent should insert variant HTML at insertLine.`);
|
||||
replaceEndLine: deferredWrapper ? deferredWrapper.replaceEndLine : undefined,
|
||||
componentDir: componentSession?.componentDir,
|
||||
propContract: componentSession?.propContract,
|
||||
sourceStartLine: useFrameworkComponent ? startLine + 1 : undefined,
|
||||
sourceEndLine: useFrameworkComponent ? endLine + 1 : undefined,
|
||||
componentStubMarkup: componentSession?.stubMarkup,
|
||||
sourceStartLine: componentPreviewActive ? startLine + 1 : undefined,
|
||||
sourceEndLine: componentPreviewActive ? endLine + 1 : undefined,
|
||||
startLine: outputStartLine, // 1-indexed for the agent
|
||||
// wrapperLines is an array but one element (the original-content slot)
|
||||
// is a `\n`-joined multi-line string, so the actual file-row count is
|
||||
@@ -426,8 +449,8 @@ The agent should insert variant HTML at insertLine.`);
|
||||
insertLine, // 1-indexed: where variants go
|
||||
commentSyntax: commentSyntax,
|
||||
styleMode: componentPreviewMode || styleMode.mode,
|
||||
styleTag: useFrameworkComponent ? null : styleMode.styleTag,
|
||||
cssSelectorPrefixExamples: useFrameworkComponent ? [] : buildCssSelectorPrefixExamples(styleMode.mode, count),
|
||||
styleTag: componentPreviewActive ? null : styleMode.styleTag,
|
||||
cssSelectorPrefixExamples: componentPreviewActive ? [] : buildCssSelectorPrefixExamples(styleMode.mode, count),
|
||||
cssAuthoring: svelteComponentAuthoring || buildCssAuthoring(styleMode, count),
|
||||
originalLineCount: originalLines.length,
|
||||
}));
|
||||
@@ -630,27 +653,22 @@ function attrEscapeDouble(str) {
|
||||
.replace(/>/g, '>');
|
||||
}
|
||||
|
||||
/**
|
||||
* Comment syntax, style mode, and preview strategy all come from the framework
|
||||
* registry, keyed on the target file's extension: `.jsx`/`.tsx` author JSX
|
||||
* comments, `.astro` needs global-prefixed preview CSS because Astro scopes
|
||||
* component styles away from the generated wrappers, `.svelte` gets component
|
||||
* preview. See live/frameworks/index.mjs for why extension and not project.
|
||||
*/
|
||||
function detectCommentSyntax(filePath) {
|
||||
const ext = path.extname(filePath).toLowerCase();
|
||||
if (ext === '.jsx' || ext === '.tsx') {
|
||||
return { open: '{/*', close: '*/}' };
|
||||
}
|
||||
// HTML, Vue, Svelte, Astro all use HTML comments
|
||||
return { open: '<!--', close: '-->' };
|
||||
return resolveSourceTraits(filePath).commentSyntax === 'jsx'
|
||||
? { open: '{/*', close: '*/}' }
|
||||
: { open: '<!--', close: '-->' };
|
||||
}
|
||||
|
||||
function detectStyleMode(filePath) {
|
||||
const ext = path.extname(filePath).toLowerCase();
|
||||
if (ext === '.astro') {
|
||||
return {
|
||||
mode: 'astro-global-prefixed',
|
||||
styleTag: '<style is:inline data-impeccable-css="SESSION_ID">',
|
||||
};
|
||||
}
|
||||
return {
|
||||
mode: 'scoped',
|
||||
styleTag: '<style data-impeccable-css="SESSION_ID">',
|
||||
};
|
||||
const traits = resolveSourceTraits(filePath);
|
||||
return { mode: traits.styleMode, styleTag: traits.styleTag };
|
||||
}
|
||||
|
||||
function buildCssSelectorPrefixExamples(styleMode, count) {
|
||||
@@ -890,6 +908,7 @@ function findClosingLine(lines, start) {
|
||||
// Auto-execute when run directly (node live-wrap.mjs ...)
|
||||
const _running = process.argv[1];
|
||||
if (_running?.endsWith('live-wrap.mjs') || _running?.endsWith('live-wrap.mjs/')) {
|
||||
enterLiveRoot();
|
||||
wrapCli();
|
||||
}
|
||||
|
||||
|
||||
@@ -21,10 +21,13 @@ import { execSync } from 'node:child_process';
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { loadContext, resolveTargetSelection } from './context.mjs';
|
||||
import { resolveTargetSelection } from './context.mjs';
|
||||
import { resolveFiles } from './live-inject.mjs';
|
||||
import { readLiveServerInfo } from './lib/impeccable-paths.mjs';
|
||||
import { resolveSurfaceBrief } from './lib/surface-briefs.mjs';
|
||||
import { resolveLiveTarget } from './live-target.mjs';
|
||||
import { bootInstructions } from './live/instructions.mjs';
|
||||
import { resolveRoots, writeRootsManifest } from './live/roots.mjs';
|
||||
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
||||
|
||||
@@ -60,6 +63,8 @@ The agent should then:
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
// Legacy workspace-monorepo selection first: it carries richer candidate
|
||||
// metadata (context inheritance status) than the roots scan.
|
||||
const targetSelection = resolveTargetSelection(liveTarget.originalCwd, liveTarget.targetOptions);
|
||||
if (targetSelection) {
|
||||
console.log(JSON.stringify({
|
||||
@@ -71,11 +76,31 @@ The agent should then:
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
const ctx = loadContext(liveTarget.originalCwd, liveTarget.targetOptions);
|
||||
const activeCwd = ctx.projectRoot;
|
||||
const rootsResult = resolveRoots({
|
||||
cwd: liveTarget.originalCwd,
|
||||
targetPath: liveTarget.absoluteTargetPath,
|
||||
});
|
||||
if (rootsResult.selection) {
|
||||
console.log(JSON.stringify({
|
||||
ok: false,
|
||||
error: 'target_selection_required',
|
||||
targetCandidates: rootsResult.selection.candidates,
|
||||
hint: 'Several apps with a dev-server config exist. Ask the user which one to use, then rerun with --target <path into that app>.',
|
||||
}, null, 2));
|
||||
process.exit(0);
|
||||
}
|
||||
const roots = rootsResult.manifest;
|
||||
const activeCwd = roots.appRoot;
|
||||
const outputTargetPath = liveTarget.targetPath || null;
|
||||
|
||||
const missingContext = missingLiveContext(ctx);
|
||||
// Gate on readable CONTENT, not path existence, so an empty or unreadable
|
||||
// PRODUCT.md routes to init instead of passing the gate and then reporting
|
||||
// hasProduct: false in the same payload.
|
||||
const product = safeRead(roots.productPath);
|
||||
const design = safeRead(roots.designPath);
|
||||
const missingContext = [];
|
||||
if (!product) missingContext.push('PRODUCT.md');
|
||||
if (!design) missingContext.push('DESIGN.md');
|
||||
if (missingContext.length > 0) {
|
||||
console.log(JSON.stringify({
|
||||
ok: false,
|
||||
@@ -83,14 +108,18 @@ The agent should then:
|
||||
missing: missingContext,
|
||||
nextCommand: missingContext.includes('PRODUCT.md') ? 'init' : 'document',
|
||||
targetPath: outputTargetPath,
|
||||
projectRoot: ctx.projectRoot,
|
||||
repoRoot: ctx.repoRoot,
|
||||
productPath: ctx.productPath,
|
||||
designPath: ctx.designPath,
|
||||
projectRoot: roots.appRoot,
|
||||
repoRoot: roots.repoRoot,
|
||||
productPath: relOrNull(liveTarget.originalCwd, roots.productPath),
|
||||
designPath: relOrNull(liveTarget.originalCwd, roots.designPath),
|
||||
}, null, 2));
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
// Persist the decision before anything else spawns, so every helper the
|
||||
// agent runs later (from any cwd inside the repo) lands on the same roots.
|
||||
writeRootsManifest(roots);
|
||||
|
||||
// 1. Check config (fail fast if missing — no point starting anything else)
|
||||
const checkOut = runScript('live-inject.mjs', ['--check'], { cwd: activeCwd });
|
||||
const checkResult = safeParse(checkOut);
|
||||
@@ -98,8 +127,8 @@ The agent should then:
|
||||
console.log(JSON.stringify({
|
||||
...(checkResult || { ok: false, error: 'check_failed', raw: checkOut }),
|
||||
targetPath: outputTargetPath,
|
||||
projectRoot: ctx.projectRoot,
|
||||
repoRoot: ctx.repoRoot,
|
||||
projectRoot: roots.appRoot,
|
||||
repoRoot: roots.repoRoot,
|
||||
}));
|
||||
process.exit(0);
|
||||
}
|
||||
@@ -134,7 +163,28 @@ The agent should then:
|
||||
const resolvedFiles = resolveFiles(activeCwd, checkResult.config);
|
||||
const drift = scanForDrift(activeCwd, resolvedFiles, checkResult.config);
|
||||
|
||||
// 5. Emit everything the agent needs
|
||||
// 5. Emit everything the agent needs. The surface brief rides along so the
|
||||
// agent does not spend three more tool calls (and a --help miss) on
|
||||
// surface-brief.mjs before the first poll.
|
||||
let surfaceBrief = null;
|
||||
let surfaceBriefPath = null;
|
||||
try {
|
||||
// Briefs live under .impeccable/surfaces, which in a nested-app repo sits
|
||||
// at the CONTEXT or repo root, not the app root; context.mjs already finds
|
||||
// them there, and live must not report "no brief" for the same project.
|
||||
const briefRoots = [roots.appRoot, roots.contextRoot, roots.repoRoot]
|
||||
.filter(Boolean)
|
||||
.filter((dir, i, arr) => arr.findIndex((other) => path.resolve(other) === path.resolve(dir)) === i);
|
||||
for (const briefRoot of briefRoots) {
|
||||
const resolvedBrief = resolveSurfaceBrief(briefRoot, liveTarget.absoluteTargetPath || null);
|
||||
if (!resolvedBrief?.brief) continue;
|
||||
surfaceBrief = resolvedBrief.brief.text ?? safeRead(resolvedBrief.brief.path);
|
||||
surfaceBriefPath = resolvedBrief.brief.path
|
||||
? path.relative(liveTarget.originalCwd, resolvedBrief.brief.path)
|
||||
: null;
|
||||
break;
|
||||
}
|
||||
} catch { /* briefs are optional context */ }
|
||||
console.log(JSON.stringify({
|
||||
ok: true,
|
||||
serverPort: serverInfo.port,
|
||||
@@ -143,22 +193,29 @@ The agent should then:
|
||||
liveConfigPath: checkResult.path,
|
||||
configDrift: drift,
|
||||
targetPath: outputTargetPath,
|
||||
projectRoot: ctx.projectRoot,
|
||||
repoRoot: ctx.repoRoot,
|
||||
hasProduct: ctx.hasProduct,
|
||||
product: ctx.product,
|
||||
productPath: ctx.productPath,
|
||||
hasDesign: ctx.hasDesign,
|
||||
design: ctx.design,
|
||||
designPath: ctx.designPath,
|
||||
projectRoot: roots.appRoot,
|
||||
repoRoot: roots.repoRoot,
|
||||
roots,
|
||||
hasProduct: !!product,
|
||||
product,
|
||||
productPath: relOrNull(liveTarget.originalCwd, roots.productPath),
|
||||
hasDesign: !!design,
|
||||
design,
|
||||
designPath: relOrNull(liveTarget.originalCwd, roots.designPath),
|
||||
hasSurfaceBrief: !!surfaceBrief,
|
||||
surfaceBrief,
|
||||
surfaceBriefPath,
|
||||
_instructions: bootInstructions({ scriptsPath: __dirname }),
|
||||
}, null, 2));
|
||||
}
|
||||
|
||||
function missingLiveContext(ctx) {
|
||||
const missing = [];
|
||||
if (!ctx.hasProduct) missing.push('PRODUCT.md');
|
||||
if (!ctx.hasDesign) missing.push('DESIGN.md');
|
||||
return missing;
|
||||
function safeRead(p) {
|
||||
if (!p) return null;
|
||||
try { return fs.readFileSync(p, 'utf-8'); } catch { return null; }
|
||||
}
|
||||
|
||||
function relOrNull(base, p) {
|
||||
return p ? path.relative(base, p) : null;
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
@@ -0,0 +1,617 @@
|
||||
/**
|
||||
* Accept-time CSS reconciliation for live mode.
|
||||
*
|
||||
* The old accept path appended the chosen variant's whole <style> body in
|
||||
* front of the component's existing rules, which preserved every superseded
|
||||
* declaration (the "old divider borders survive the accept" bug) and left
|
||||
* dead parameter branches in source. This module makes acceptance a merge:
|
||||
*
|
||||
* reconcileCss replace rules whose selectors match, append new ones
|
||||
* bakeParamValues collapse --p-* vars and [data-p-*] branches to the
|
||||
* user's chosen values, driven by the declared param
|
||||
* kinds from params.json (not regex sniffing)
|
||||
* pruneUnusedSelectors use the framework compiler's own unused-selector
|
||||
* warnings to delete rules the accepted markup no longer
|
||||
* references
|
||||
*
|
||||
* The parser is hand-rolled on purpose: skill scripts run standalone inside
|
||||
* user projects and cannot rely on this repo's node_modules. It is a small
|
||||
* recursive block parser (comment- and string-aware), not a spec-complete
|
||||
* CSS parser; everything it emits round-trips byte-for-byte through raw
|
||||
* slices except the rules deliberately changed.
|
||||
*/
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Parsing
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Parse a stylesheet into a flat tree.
|
||||
* Node shapes:
|
||||
* { type: 'rule', prelude, body, start, end, preludeStart }
|
||||
* { type: 'at', name, prelude, children|body, start, end } (children when
|
||||
* the block contains rules: media/supports/layer/container/scope)
|
||||
* { type: 'comment', text, start, end }
|
||||
*/
|
||||
export function parseStylesheet(css, offset = 0) {
|
||||
const text = String(css || '');
|
||||
const nodes = [];
|
||||
let i = 0;
|
||||
|
||||
const skipWs = () => { while (i < text.length && /\s/.test(text[i])) i++; };
|
||||
|
||||
while (i < text.length) {
|
||||
skipWs();
|
||||
if (i >= text.length) break;
|
||||
|
||||
if (text[i] === '/' && text[i + 1] === '*') {
|
||||
const start = i;
|
||||
const close = text.indexOf('*/', i + 2);
|
||||
i = close === -1 ? text.length : close + 2;
|
||||
nodes.push({ type: 'comment', text: text.slice(start, i), start: offset + start, end: offset + i });
|
||||
continue;
|
||||
}
|
||||
|
||||
const preludeStart = i;
|
||||
const boundary = scanToBlockOrStatementEnd(text, i);
|
||||
if (boundary.kind === 'none') break; // trailing garbage / declarations at top level
|
||||
if (boundary.kind === 'statement') {
|
||||
// Block-less at-statement (@import, @charset, @layer names;). Emitted
|
||||
// as its own node so the FOLLOWING rule still indexes for
|
||||
// reconciliation instead of being folded into this prelude.
|
||||
const raw = text.slice(preludeStart, boundary.index + 1).trim();
|
||||
if (raw) {
|
||||
nodes.push({
|
||||
type: 'at',
|
||||
name: (raw.match(/^@([A-Za-z-]+)/) || [])[1] || '',
|
||||
prelude: raw.replace(/;$/, ''),
|
||||
statement: true,
|
||||
start: offset + preludeStart,
|
||||
end: offset + boundary.index + 1,
|
||||
});
|
||||
}
|
||||
i = boundary.index + 1;
|
||||
continue;
|
||||
}
|
||||
const braceIdx = boundary.index;
|
||||
const prelude = text.slice(preludeStart, braceIdx).trim();
|
||||
const bodyStart = braceIdx + 1;
|
||||
const bodyEnd = scanBlockEnd(text, bodyStart);
|
||||
const body = text.slice(bodyStart, bodyEnd);
|
||||
const nodeEnd = Math.min(text.length, bodyEnd + 1);
|
||||
|
||||
if (prelude.startsWith('@')) {
|
||||
const name = (prelude.match(/^@([A-Za-z-]+)/) || [])[1] || '';
|
||||
if (['media', 'supports', 'layer', 'container', 'scope'].includes(name)) {
|
||||
nodes.push({
|
||||
type: 'at',
|
||||
name,
|
||||
prelude,
|
||||
children: parseStylesheet(body, offset + bodyStart),
|
||||
start: offset + preludeStart,
|
||||
end: offset + nodeEnd,
|
||||
});
|
||||
} else {
|
||||
nodes.push({
|
||||
type: 'at',
|
||||
name,
|
||||
prelude,
|
||||
body,
|
||||
start: offset + preludeStart,
|
||||
end: offset + nodeEnd,
|
||||
});
|
||||
}
|
||||
} else if (prelude) {
|
||||
nodes.push({
|
||||
type: 'rule',
|
||||
prelude,
|
||||
body,
|
||||
start: offset + preludeStart,
|
||||
end: offset + nodeEnd,
|
||||
preludeStart: offset + preludeStart,
|
||||
});
|
||||
}
|
||||
i = nodeEnd;
|
||||
}
|
||||
return nodes;
|
||||
}
|
||||
|
||||
/**
|
||||
* Scan for the next structural boundary: the `{` opening a block, or the `;`
|
||||
* ending a block-less at-statement, whichever comes first (string- and
|
||||
* comment-aware). Returns { kind: 'block' | 'statement' | 'none', index }.
|
||||
*/
|
||||
function scanToBlockOrStatementEnd(text, from) {
|
||||
let i = from;
|
||||
let quote = null;
|
||||
while (i < text.length) {
|
||||
const ch = text[i];
|
||||
if (quote) {
|
||||
if (ch === '\\') i++;
|
||||
else if (ch === quote) quote = null;
|
||||
} else if (ch === '"' || ch === "'") {
|
||||
quote = ch;
|
||||
} else if (ch === '/' && text[i + 1] === '*') {
|
||||
const close = text.indexOf('*/', i + 2);
|
||||
i = close === -1 ? text.length : close + 1;
|
||||
} else if (ch === '{') {
|
||||
return { kind: 'block', index: i };
|
||||
} else if (ch === ';') {
|
||||
return { kind: 'statement', index: i };
|
||||
}
|
||||
i++;
|
||||
}
|
||||
return { kind: 'none', index: -1 };
|
||||
}
|
||||
|
||||
function scanBlockEnd(text, from) {
|
||||
let i = from;
|
||||
let depth = 1;
|
||||
let quote = null;
|
||||
while (i < text.length) {
|
||||
const ch = text[i];
|
||||
if (quote) {
|
||||
if (ch === '\\') i++;
|
||||
else if (ch === quote) quote = null;
|
||||
} else if (ch === '"' || ch === "'") {
|
||||
quote = ch;
|
||||
} else if (ch === '/' && text[i + 1] === '*') {
|
||||
const close = text.indexOf('*/', i + 2);
|
||||
i = close === -1 ? text.length : close + 1;
|
||||
} else if (ch === '{') {
|
||||
depth++;
|
||||
} else if (ch === '}') {
|
||||
depth--;
|
||||
if (depth === 0) return i;
|
||||
}
|
||||
i++;
|
||||
}
|
||||
return text.length;
|
||||
}
|
||||
|
||||
export function serializeNodes(nodes, indent = '') {
|
||||
const out = [];
|
||||
for (const node of nodes) {
|
||||
if (node.type === 'comment') {
|
||||
out.push(indent + node.text);
|
||||
} else if (node.type === 'rule') {
|
||||
out.push(`${indent}${node.prelude} {${formatBody(node.body, indent)}}`);
|
||||
} else if (node.type === 'at' && node.children) {
|
||||
out.push(`${indent}${node.prelude} {`);
|
||||
out.push(serializeNodes(node.children, indent + ' '));
|
||||
out.push(`${indent}}`);
|
||||
} else if (node.type === 'at' && node.statement) {
|
||||
out.push(`${indent}${node.prelude};`);
|
||||
} else if (node.type === 'at') {
|
||||
out.push(`${indent}${node.prelude} {${formatBody(node.body, indent)}}`);
|
||||
}
|
||||
}
|
||||
return out.join('\n');
|
||||
}
|
||||
|
||||
function formatBody(body, indent) {
|
||||
const trimmed = String(body || '').trim();
|
||||
if (!trimmed) return ' ';
|
||||
const lines = trimmed.split('\n').map((l) => l.trim()).filter(Boolean);
|
||||
if (lines.length === 1 && lines[0].length < 60) return ` ${lines[0]} `;
|
||||
return '\n' + lines.map((l) => `${indent} ${l}`).join('\n') + `\n${indent}`;
|
||||
}
|
||||
|
||||
export function normalizeSelector(prelude) {
|
||||
return String(prelude || '')
|
||||
.replace(/\s+/g, ' ')
|
||||
.replace(/\s*([>+~,])\s*/g, '$1')
|
||||
.trim();
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Reconciliation
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Merge variant CSS into existing CSS. Rules whose (at-context, normalized
|
||||
* selector) match an existing rule REPLACE that rule's body in place; new
|
||||
* rules append at the end under their at-context. Returns { css, replaced,
|
||||
* appended }.
|
||||
*/
|
||||
export function reconcileCss(existingCss, variantCss) {
|
||||
const existing = parseStylesheet(existingCss);
|
||||
const incoming = parseStylesheet(variantCss);
|
||||
let replaced = 0;
|
||||
let appended = 0;
|
||||
|
||||
const mergeLevel = (existingNodes, incomingNodes) => {
|
||||
const index = new Map();
|
||||
for (const node of existingNodes) {
|
||||
if (node.type === 'rule') index.set(normalizeSelector(node.prelude), node);
|
||||
}
|
||||
const atIndex = new Map();
|
||||
for (const node of existingNodes) {
|
||||
if (node.type === 'at' && node.children) atIndex.set(normalizeSelector(node.prelude), node);
|
||||
}
|
||||
// Baking can leave several incoming rules with the same selector (e.g. a
|
||||
// base rule plus a stripped param branch). The first one REPLACES the
|
||||
// existing body; later same-selector rules extend it, never clobber it.
|
||||
const touched = new Set();
|
||||
for (const node of incomingNodes) {
|
||||
if (node.type === 'comment') continue;
|
||||
if (node.type === 'rule') {
|
||||
const key = normalizeSelector(node.prelude);
|
||||
const match = index.get(key);
|
||||
if (match) {
|
||||
if (touched.has(key)) {
|
||||
match.body = `${match.body.trim()}\n${node.body.trim()}`;
|
||||
} else if (match.body.trim() !== node.body.trim()) {
|
||||
match.body = node.body;
|
||||
replaced++;
|
||||
}
|
||||
touched.add(key);
|
||||
} else {
|
||||
// New base rules go BEFORE the existing top-level media blocks:
|
||||
// appended after them, an equal-specificity base rule wins the
|
||||
// cascade over the stylesheet's earlier responsive overrides and
|
||||
// silently weakens the mobile styles for any still-shared class.
|
||||
const appendedNode = { ...node };
|
||||
const firstAt = existingNodes.findIndex((n) => n.type === 'at' && n.children);
|
||||
if (firstAt === -1) existingNodes.push(appendedNode);
|
||||
else existingNodes.splice(firstAt, 0, appendedNode);
|
||||
index.set(key, appendedNode);
|
||||
touched.add(key);
|
||||
appended++;
|
||||
}
|
||||
} else if (node.type === 'at' && node.children) {
|
||||
const key = normalizeSelector(node.prelude);
|
||||
const match = atIndex.get(key);
|
||||
if (match) {
|
||||
mergeLevel(match.children, node.children);
|
||||
} else {
|
||||
existingNodes.push({ ...node });
|
||||
atIndex.set(key, existingNodes[existingNodes.length - 1]);
|
||||
appended++;
|
||||
}
|
||||
} else {
|
||||
existingNodes.push({ ...node });
|
||||
appended++;
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
mergeLevel(existing, incoming);
|
||||
return { css: serializeNodes(existing), replaced, appended };
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Parameter baking
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Replace every `var(--p-<id>, fallback)` / `var(--p-<id>)` occurrence with a
|
||||
* literal value. Paren-aware: fallbacks containing calc()/nested vars are
|
||||
* handled, unlike the old `[^)]+` regex.
|
||||
*/
|
||||
export function substituteParamVar(css, id, value) {
|
||||
const text = String(css || '');
|
||||
const needle = `var(--p-${id}`;
|
||||
let out = '';
|
||||
let i = 0;
|
||||
while (i < text.length) {
|
||||
const idx = text.indexOf(needle, i);
|
||||
if (idx === -1) { out += text.slice(i); break; }
|
||||
const after = idx + needle.length;
|
||||
// Must be end of the var name: `)` or `,`.
|
||||
if (after < text.length && text[after] !== ')' && text[after] !== ',') {
|
||||
out += text.slice(i, after);
|
||||
i = after;
|
||||
continue;
|
||||
}
|
||||
let j = after;
|
||||
let depth = 1; // we are inside var(
|
||||
while (j < text.length && depth > 0) {
|
||||
if (text[j] === '(') depth++;
|
||||
else if (text[j] === ')') depth--;
|
||||
j++;
|
||||
}
|
||||
out += text.slice(i, idx) + String(value);
|
||||
i = j;
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function normalizeToggleForVar(value) {
|
||||
return value === true || value === 'true' || value === 1 || value === '1' || value === 'on' ? '1' : '0';
|
||||
}
|
||||
|
||||
function isToggleOn(value) {
|
||||
return normalizeToggleForVar(value) === '1';
|
||||
}
|
||||
|
||||
/**
|
||||
* Strip `[data-p-<id>="value"]` / `[data-p-<id>]` attribute selectors from a
|
||||
* selector, deciding survival by the chosen value:
|
||||
* returns null when the selector targets a non-chosen branch (drop it),
|
||||
* otherwise the selector with the attribute test removed and any emptied
|
||||
* :global() wrappers cleaned up.
|
||||
*/
|
||||
export function stripParamSelector(selector, id, kind, chosenValue) {
|
||||
const attrRe = new RegExp(`\\[data-p-${escapeRegExp(id)}(?:=(["'])(.*?)\\1)?\\]`, 'g');
|
||||
let drop = false;
|
||||
let out = String(selector).replace(attrRe, (_m, _q, expected) => {
|
||||
if (kind === 'steps') {
|
||||
if (expected == null || String(expected) === String(chosenValue)) return '';
|
||||
drop = true;
|
||||
return '';
|
||||
}
|
||||
// toggle: the runtime sets data-p-<id>="on" when on and removes the
|
||||
// attribute when off. A branch survives baking only if it actually
|
||||
// matched at preview time with the chosen state: the presence form and
|
||||
// the literal "on" form match while on; every other valued form
|
||||
// (["false"], ["0"], ...) never matched and is dead regardless of state.
|
||||
if (expected != null && expected !== 'on') {
|
||||
drop = true;
|
||||
return '';
|
||||
}
|
||||
if (!isToggleOn(chosenValue)) {
|
||||
drop = true;
|
||||
return '';
|
||||
}
|
||||
return '';
|
||||
});
|
||||
if (drop) return null;
|
||||
out = out
|
||||
.replace(/:global\(\s*\)/g, '')
|
||||
.replace(/\s+/g, ' ')
|
||||
.replace(/^\s*[>+~]\s*/, '')
|
||||
.trim();
|
||||
return out || null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Bake chosen parameter values into CSS. `params` is the declared parameter
|
||||
* list for the accepted variant (from params.json); `values` maps id ->
|
||||
* chosen value (falling back to each param's declared default).
|
||||
*/
|
||||
export function bakeParamValues(css, params = [], values = {}) {
|
||||
let nodes = parseStylesheet(css);
|
||||
|
||||
const chosen = new Map();
|
||||
for (const param of params || []) {
|
||||
if (!param || !param.id) continue;
|
||||
const has = values && Object.prototype.hasOwnProperty.call(values, param.id);
|
||||
chosen.set(param.id, { kind: param.kind, value: has ? values[param.id] : param.default });
|
||||
}
|
||||
// Values sent for params that were never declared still bake as ranges,
|
||||
// so an out-of-sync manifest degrades to the old behavior, not to silence.
|
||||
for (const [id, value] of Object.entries(values || {})) {
|
||||
if (!chosen.has(id)) chosen.set(id, { kind: 'range', value });
|
||||
}
|
||||
|
||||
const bakeBody = (body) => {
|
||||
let out = String(body || '');
|
||||
for (const [id, { kind, value }] of chosen) {
|
||||
const literal = kind === 'toggle' ? normalizeToggleForVar(value) : String(value);
|
||||
out = substituteParamVar(out, id, literal);
|
||||
}
|
||||
// Strip the readiness sentinel as a DECLARATION, not a line: a one-line
|
||||
// rule carrying the sentinel plus real declarations must keep the rest.
|
||||
return out
|
||||
.replace(/(^|;)\s*--impeccable-variant-ready\s*:[^;{}]*/g, '$1')
|
||||
.replace(/;\s*;/g, ';')
|
||||
.replace(/^\s*;\s*/, '');
|
||||
};
|
||||
|
||||
const transform = (list) => {
|
||||
const result = [];
|
||||
for (const node of list) {
|
||||
if (node.type === 'at' && node.children) {
|
||||
const children = transform(node.children);
|
||||
if (children.length > 0) result.push({ ...node, children });
|
||||
continue;
|
||||
}
|
||||
if (node.type !== 'rule') {
|
||||
if (node.type === 'at') result.push({ ...node, body: bakeBody(node.body) });
|
||||
else result.push(node);
|
||||
continue;
|
||||
}
|
||||
const selectors = splitSelectorList(node.prelude);
|
||||
const kept = [];
|
||||
for (let selector of selectors) {
|
||||
let alive = true;
|
||||
for (const [id, { kind, value }] of chosen) {
|
||||
if (kind !== 'steps' && kind !== 'toggle') continue;
|
||||
if (!selector.includes(`data-p-${id}`)) continue;
|
||||
const next = stripParamSelector(selector, id, kind, value);
|
||||
if (next == null) { alive = false; break; }
|
||||
selector = next;
|
||||
}
|
||||
if (alive && selector.trim()) kept.push(selector.trim());
|
||||
}
|
||||
if (kept.length === 0) continue;
|
||||
const body = bakeBody(node.body);
|
||||
if (!body.trim()) continue;
|
||||
result.push({ ...node, prelude: kept.join(', '), body });
|
||||
}
|
||||
return result;
|
||||
};
|
||||
|
||||
nodes = transform(nodes);
|
||||
return serializeNodes(nodes);
|
||||
}
|
||||
|
||||
export function splitSelectorList(prelude) {
|
||||
const selectors = [];
|
||||
let start = 0;
|
||||
let bracket = 0;
|
||||
let paren = 0;
|
||||
let quote = null;
|
||||
const text = String(prelude || '');
|
||||
for (let i = 0; i < text.length; i++) {
|
||||
const ch = text[i];
|
||||
if (quote) {
|
||||
if (ch === '\\') i++;
|
||||
else if (ch === quote) quote = null;
|
||||
continue;
|
||||
}
|
||||
if (ch === '"' || ch === "'") quote = ch;
|
||||
else if (ch === '[') bracket++;
|
||||
else if (ch === ']') bracket = Math.max(0, bracket - 1);
|
||||
else if (ch === '(') paren++;
|
||||
else if (ch === ')') paren = Math.max(0, paren - 1);
|
||||
else if (ch === ',' && bracket === 0 && paren === 0) {
|
||||
selectors.push(text.slice(start, i));
|
||||
start = i + 1;
|
||||
}
|
||||
}
|
||||
selectors.push(text.slice(start));
|
||||
return selectors.map((s) => s.trim()).filter(Boolean);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Compiler-driven pruning
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Remove selectors the framework compiler reports as unused from a full
|
||||
* component source. `compileFn` is the app's svelte compile; warnings with
|
||||
* code `css_unused_selector` carry character offsets into the source.
|
||||
* `skipSelectors` protects selectors that were already unused before the
|
||||
* accept: pre-existing dead rules are the user's code, not live-mode debris.
|
||||
* Returns { source, removed } where removed lists the pruned selector texts.
|
||||
*/
|
||||
export function collectUnusedSelectors(componentSource, compileFn) {
|
||||
try {
|
||||
const { warnings } = compileFn(String(componentSource || ''), { generate: false });
|
||||
return new Set((warnings || [])
|
||||
.filter((w) => w.code === 'css_unused_selector'
|
||||
&& Number.isInteger(w.start?.character)
|
||||
&& Number.isInteger(w.end?.character))
|
||||
.map((w) => String(componentSource).slice(w.start.character, w.end.character).trim()));
|
||||
} catch {
|
||||
return new Set();
|
||||
}
|
||||
}
|
||||
|
||||
export function pruneUnusedSelectors(componentSource, compileFn, { skipSelectors } = {}) {
|
||||
let source = String(componentSource || '');
|
||||
const removed = [];
|
||||
const skip = skipSelectors instanceof Set ? skipSelectors : new Set(skipSelectors || []);
|
||||
for (let pass = 0; pass < 3; pass++) {
|
||||
let warnings;
|
||||
try {
|
||||
({ warnings } = compileFn(source, { generate: false }));
|
||||
} catch {
|
||||
return { source, removed }; // never let pruning break an accept
|
||||
}
|
||||
const unused = (warnings || [])
|
||||
.filter((w) => w.code === 'css_unused_selector'
|
||||
&& Number.isInteger(w.start?.character)
|
||||
&& Number.isInteger(w.end?.character))
|
||||
.filter((w) => !skip.has(source.slice(w.start.character, w.end.character).trim()))
|
||||
.sort((a, b) => b.start.character - a.start.character);
|
||||
if (unused.length === 0) break;
|
||||
|
||||
let next = source;
|
||||
for (const warning of unused) {
|
||||
const result = removeSelectorAt(next, warning.start.character, warning.end.character);
|
||||
if (result.changed) {
|
||||
removed.push(result.selector);
|
||||
next = result.source;
|
||||
}
|
||||
}
|
||||
if (next === source) break;
|
||||
source = next;
|
||||
}
|
||||
return { source, removed };
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove the selector at [start, end) from its rule. When it is the rule's
|
||||
* only selector, remove the whole rule (prelude through closing brace).
|
||||
*/
|
||||
function removeSelectorAt(source, start, end) {
|
||||
const selector = source.slice(start, end);
|
||||
|
||||
// Find the rule boundaries around the selector.
|
||||
const braceIdx = source.indexOf('{', end);
|
||||
if (braceIdx === -1) return { changed: false, selector, source };
|
||||
const bodyEnd = scanBlockEnd(source, braceIdx + 1);
|
||||
|
||||
// Prelude spans backward from the brace to the previous } ; { or the end
|
||||
// of the <style> open tag. A bare `>` is NOT a boundary: it is the child
|
||||
// combinator, and cutting there truncates a selector list like
|
||||
// `.a > .b, .c` mid-prelude. Only a `>` that closes a `<style ...>` tag
|
||||
// bounds the walk.
|
||||
let preludeStart = start;
|
||||
for (let i = start - 1; i >= 0; i--) {
|
||||
const ch = source[i];
|
||||
if (ch === '}' || ch === '{' || ch === ';') { preludeStart = i + 1; break; }
|
||||
if (ch === '>') {
|
||||
const styleOpen = source.lastIndexOf('<style', i);
|
||||
if (styleOpen !== -1 && source.indexOf('>', styleOpen) === i) { preludeStart = i + 1; break; }
|
||||
continue; // child combinator inside the prelude
|
||||
}
|
||||
if (i === 0) preludeStart = 0;
|
||||
}
|
||||
const prelude = source.slice(preludeStart, braceIdx);
|
||||
const selectors = splitSelectorList(prelude);
|
||||
const target = selector.trim();
|
||||
const kept = selectors.filter((s) => s !== target);
|
||||
|
||||
if (kept.length === selectors.length) {
|
||||
// Offsets did not line up with a full selector in the list; be safe.
|
||||
return { changed: false, selector, source };
|
||||
}
|
||||
|
||||
if (kept.length === 0) {
|
||||
// Remove the entire rule including trailing newline.
|
||||
let ruleEnd = Math.min(source.length, bodyEnd + 1);
|
||||
while (ruleEnd < source.length && source[ruleEnd] === '\n') ruleEnd++;
|
||||
let ruleStart = preludeStart;
|
||||
while (ruleStart > 0 && (source[ruleStart - 1] === ' ' || source[ruleStart - 1] === '\t')) ruleStart--;
|
||||
return { changed: true, selector: target, source: source.slice(0, ruleStart) + source.slice(ruleEnd) };
|
||||
}
|
||||
|
||||
const indent = (prelude.match(/^\s*/) || [''])[0];
|
||||
return {
|
||||
changed: true,
|
||||
selector: target,
|
||||
source: source.slice(0, preludeStart) + indent + kept.join(', ') + ' ' + source.slice(braceIdx, source.length),
|
||||
};
|
||||
}
|
||||
|
||||
function escapeRegExp(value) {
|
||||
return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
||||
}
|
||||
|
||||
/**
|
||||
* Collect every normalized selector in a CSS text, including inside nested
|
||||
* at-blocks. Used by the accept postcondition: a selector present before the
|
||||
* accept may only disappear if the compiler reported it unused; anything
|
||||
* else means the parser or reconciler damaged the user's file, and the write
|
||||
* must be refused rather than silently committed.
|
||||
*/
|
||||
export function collectAllSelectors(css, out = new Set()) {
|
||||
for (const node of parseStylesheet(css)) {
|
||||
if (node.type === 'rule') {
|
||||
for (const selector of splitSelectorList(node.prelude)) out.add(normalizeSelector(selector));
|
||||
} else if (node.type === 'at' && node.children) {
|
||||
for (const child of node.children) {
|
||||
if (child.type === 'rule') {
|
||||
for (const selector of splitSelectorList(child.prelude)) out.add(normalizeSelector(selector));
|
||||
} else if (child.type === 'at' && child.children) {
|
||||
collectSelectorsFromNodes(child.children, out);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function collectSelectorsFromNodes(nodes, out) {
|
||||
for (const node of nodes) {
|
||||
if (node.type === 'rule') {
|
||||
for (const selector of splitSelectorList(node.prelude)) out.add(normalizeSelector(selector));
|
||||
} else if (node.type === 'at' && node.children) {
|
||||
collectSelectorsFromNodes(node.children, out);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,60 @@
|
||||
/**
|
||||
* Postcondition scanner for accepted/carbonized source. The carbonize
|
||||
* contract used to exist only as prose in reference/live.md; nothing checked
|
||||
* that an accept actually left the file clean, so dead param branches,
|
||||
* preview attributes, and marker comments accumulated across sessions. This
|
||||
* scanner is the mechanical form of that contract. live-complete refuses to
|
||||
* mark a carbonize session complete while the file is dirty, and the
|
||||
* mechanical Svelte accept runs it on its own output as a self-check.
|
||||
*/
|
||||
|
||||
// Param patterns are anchored to the exact shapes live mode writes
|
||||
// (attribute-with-value / selector forms, var() references), not bare
|
||||
// substrings, so user tokens that merely share the prefix cannot trip the
|
||||
// completion gate.
|
||||
const FORBIDDEN = [
|
||||
{ marker: 'impeccable-variants-start', why: 'variant wrapper comment left in source' },
|
||||
{ marker: 'impeccable-variants-end', why: 'variant wrapper comment left in source' },
|
||||
{ marker: 'impeccable-carbonize-start', why: 'carbonize block not rewritten into permanent form' },
|
||||
{ marker: 'impeccable-carbonize-end', why: 'carbonize block not rewritten into permanent form' },
|
||||
{ marker: 'impeccable-param-values', why: 'param-values comment not baked and removed' },
|
||||
{ marker: 'data-impeccable-', why: 'live-mode plumbing attribute left on markup' },
|
||||
{ marker: /\bdata-p-[A-Za-z0-9_-]+\s*(?:=|\])/, label: 'data-p-*', why: 'preview parameter attribute left on markup' },
|
||||
{ marker: /var\(\s*--p-[A-Za-z0-9_-]+\s*[,)]/, label: 'var(--p-*)', why: 'preview parameter variable not baked to a literal' },
|
||||
{ marker: '--impeccable-variant-ready', why: 'preview readiness sentinel left in CSS' },
|
||||
];
|
||||
|
||||
/**
|
||||
* Scan file text for live-mode leftovers. Returns { clean, findings } where
|
||||
* each finding is { marker, line, excerpt, why }.
|
||||
*/
|
||||
export function verifyAcceptedSource(text) {
|
||||
const findings = [];
|
||||
const lines = String(text || '').split('\n');
|
||||
for (let i = 0; i < lines.length; i++) {
|
||||
const line = lines[i];
|
||||
for (const { marker, label, why } of FORBIDDEN) {
|
||||
const hit = marker instanceof RegExp ? marker.test(line) : line.includes(marker);
|
||||
if (hit) {
|
||||
findings.push({
|
||||
marker: label || String(marker),
|
||||
line: i + 1,
|
||||
excerpt: line.trim().slice(0, 120),
|
||||
why,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
return { clean: findings.length === 0, findings };
|
||||
}
|
||||
|
||||
/** Convenience wrapper for CLI callers: read + scan, tolerating a missing file. */
|
||||
export function verifyAcceptedFile(fs, filePath) {
|
||||
let text;
|
||||
try {
|
||||
text = fs.readFileSync(filePath, 'utf-8');
|
||||
} catch {
|
||||
return { clean: true, findings: [], missing: true };
|
||||
}
|
||||
return { ...verifyAcceptedSource(text), missing: false };
|
||||
}
|
||||
@@ -32,10 +32,15 @@ export function readLiveBrowserScriptParts(parts, readFile = (filePath) => fs.re
|
||||
}));
|
||||
}
|
||||
|
||||
export function assembleLiveBrowserScript({ token, port, vocabulary, commandPrefix = '/', parts }) {
|
||||
export function assembleLiveBrowserScript({ token, port, vocabulary, commandPrefix = '/', appRoot = null, parts }) {
|
||||
const prelude =
|
||||
`window.__IMPECCABLE_TOKEN__ = '${token}';\n` +
|
||||
`window.__IMPECCABLE_PORT__ = ${port};\n` +
|
||||
// Project identity for browser-side session storage. localStorage is
|
||||
// keyed by ORIGIN, and two projects routinely share a localhost port
|
||||
// across time; saved sessions carry this value so a resume can tell a
|
||||
// foreign project's leftovers from its own.
|
||||
`window.__IMPECCABLE_APP_ROOT__ = ${JSON.stringify(appRoot)};\n` +
|
||||
`window.__IMPECCABLE_COMMAND_PREFIX__ = ${JSON.stringify(commandPrefix)};\n` +
|
||||
// Canonical command vocabulary (values + labels + icons). live-browser.js
|
||||
// builds its action picker from this instead of an inline copy.
|
||||
|
||||
@@ -5,17 +5,26 @@
|
||||
|
||||
import { canCreateInsert } from './insert-ui.mjs';
|
||||
|
||||
// The accepted visual action values come from the canonical vocabulary so the
|
||||
// validator, the picker UI, and the marketing demo never drift. Imported (not
|
||||
// just re-exported) so it is also in scope for the validators below.
|
||||
import { VISUAL_ACTIONS } from './vocabulary.mjs';
|
||||
export { VISUAL_ACTIONS };
|
||||
// The accepted protocol values come from the canonical vocabulary so the
|
||||
// validator, the store, the server, and the picker UI never drift. Imported
|
||||
// (not just re-exported) so they are also in scope for the validators below.
|
||||
import { AGENT_PHASES, CLIENT_EVENT_TYPES, VISUAL_ACTIONS } from './vocabulary.mjs';
|
||||
export { AGENT_PHASES, CLIENT_EVENT_TYPES, VISUAL_ACTIONS };
|
||||
|
||||
const AGENT_PHASE_SET = new Set(AGENT_PHASES);
|
||||
|
||||
const ID_PATTERN = /^[0-9a-f]{8}$/;
|
||||
const VARIANT_ID_PATTERN = /^[0-9]{1,3}$/;
|
||||
const INSERT_POSITIONS = new Set(['before', 'after']);
|
||||
const FORBIDDEN_MANUAL_EDIT_TEXT_CHARS = ['<', '{', '}', '`'];
|
||||
|
||||
// Mount acknowledgements carry a module URL and a raw exception message from
|
||||
// the page. Both are attacker-adjacent (any script on the page can POST them
|
||||
// with the token it can already read), so they are length-capped before they
|
||||
// reach the journal.
|
||||
export const MOUNT_URL_MAX_LENGTH = 2000;
|
||||
export const MOUNT_ERROR_MAX_LENGTH = 1000;
|
||||
|
||||
function isValidId(v) { return typeof v === 'string' && ID_PATTERN.test(v); }
|
||||
function isValidVariantId(v) { return typeof v === 'string' && VARIANT_ID_PATTERN.test(v); }
|
||||
|
||||
@@ -92,6 +101,36 @@ function validateManualEditEvent(msg, label) {
|
||||
return null;
|
||||
}
|
||||
|
||||
function isValidMountVariant(value) {
|
||||
return Number.isInteger(value) && value >= 1 && value <= 999;
|
||||
}
|
||||
|
||||
/**
|
||||
* Mount acknowledgements are the browser's answer to "did the thing you
|
||||
* published actually render". They are validated strictly because the render
|
||||
* truth in the session snapshot is built from them: a malformed ack that slid
|
||||
* through would report a variant as mounted that never was.
|
||||
*/
|
||||
function validateMountAck(msg) {
|
||||
if (!isValidId(msg.id)) return 'variant_mounted: missing or malformed id';
|
||||
if (!isValidMountVariant(msg.variant)) return 'variant_mounted: variant must be an integer 1-999';
|
||||
if (msg.url !== undefined) {
|
||||
if (typeof msg.url !== 'string') return 'variant_mounted: url must be string';
|
||||
if (msg.url.length > MOUNT_URL_MAX_LENGTH) return 'variant_mounted: url too long';
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function validateMountFailure(msg) {
|
||||
if (!isValidId(msg.id)) return 'variant_mount_failed: missing or malformed id';
|
||||
if (!isValidMountVariant(msg.variant)) return 'variant_mount_failed: variant must be an integer 1-999';
|
||||
if (typeof msg.url !== 'string' || !msg.url.trim()) return 'variant_mount_failed: url required';
|
||||
if (msg.url.length > MOUNT_URL_MAX_LENGTH) return 'variant_mount_failed: url too long';
|
||||
if (typeof msg.error !== 'string' || !msg.error.trim()) return 'variant_mount_failed: error required';
|
||||
if (msg.error.length > MOUNT_ERROR_MAX_LENGTH) return 'variant_mount_failed: error too long';
|
||||
return null;
|
||||
}
|
||||
|
||||
export function validateEvent(msg) {
|
||||
if (!msg || typeof msg !== 'object' || !msg.type) return 'Missing or invalid message';
|
||||
switch (msg.type) {
|
||||
@@ -120,13 +159,21 @@ export function validateEvent(msg) {
|
||||
return null;
|
||||
case 'agent_phase':
|
||||
if (!isValidId(msg.id)) return 'agent_phase: missing or malformed id';
|
||||
if (typeof msg.phase !== 'string' || !/^[a-z][a-z0-9_]{1,63}$/.test(msg.phase)) {
|
||||
return 'agent_phase: missing or malformed phase';
|
||||
if (typeof msg.phase !== 'string' || !msg.phase) return 'agent_phase: missing phase';
|
||||
// The enum, not a shape pattern. A phase the browser cannot rank is a
|
||||
// phase the progress bar cannot show, so accepting an arbitrary
|
||||
// lowercase word only defers the failure to the UI.
|
||||
if (!AGENT_PHASE_SET.has(msg.phase)) {
|
||||
return 'agent_phase: unknown phase ' + msg.phase + ' (expected one of ' + AGENT_PHASES.join(', ') + ')';
|
||||
}
|
||||
if (msg.durationMs !== undefined && (!Number.isFinite(msg.durationMs) || msg.durationMs < 0)) {
|
||||
return 'agent_phase: durationMs must be a non-negative number';
|
||||
}
|
||||
return null;
|
||||
case 'variant_mounted':
|
||||
return validateMountAck(msg);
|
||||
case 'variant_mount_failed':
|
||||
return validateMountFailure(msg);
|
||||
case 'exit':
|
||||
return null;
|
||||
case 'prefetch':
|
||||
|
||||
@@ -0,0 +1,47 @@
|
||||
/**
|
||||
* Astro registry entry.
|
||||
*
|
||||
* Astro takes the generic tag strategy, with two Astro-specific values that
|
||||
* used to sit as inline `endsWith('.astro')` branches in live-inject.mjs and
|
||||
* live-wrap.mjs:
|
||||
*
|
||||
* injectScriptAttrs Astro processes <script> tags by default and rewrites
|
||||
* src to its own bundled URL; is:inline opts out.
|
||||
* styleMode Astro scopes component styles, which strips preview CSS
|
||||
* off the generated variant wrappers, so preview rules are
|
||||
* authored global and prefixed instead of @scope'd.
|
||||
*/
|
||||
|
||||
import { findConfigFile, hasAnyDependency, literalConfigFiles } from './detect-utils.mjs';
|
||||
|
||||
const ASTRO_CONFIG_RE = /^astro\.config\.(?:js|mjs|cjs|ts|mts|cts)$/;
|
||||
|
||||
export function detectAstroProject(cwd = process.cwd(), config = null) {
|
||||
const configFile = findConfigFile(cwd, ASTRO_CONFIG_RE);
|
||||
if (configFile) return { configFile, via: 'config' };
|
||||
if (hasAnyDependency(cwd, ['astro'])) return { configFile: null, via: 'package' };
|
||||
// A tree of .astro entry templates with no astro.config still belongs to
|
||||
// Astro; the configured injection target names it.
|
||||
const entry = literalConfigFiles(cwd, config).find((rel) => rel.endsWith('.astro'));
|
||||
if (entry) return { configFile: null, via: 'config-files', entry };
|
||||
return null;
|
||||
}
|
||||
|
||||
export const astro = {
|
||||
name: 'astro',
|
||||
|
||||
detect(cwd, config) {
|
||||
return detectAstroProject(cwd, config);
|
||||
},
|
||||
|
||||
inject: { kind: 'tag' },
|
||||
|
||||
source: {
|
||||
extensions: ['.astro'],
|
||||
preview: 'source',
|
||||
styleMode: 'astro-global-prefixed',
|
||||
styleTag: '<style is:inline data-impeccable-css="SESSION_ID">',
|
||||
commentSyntax: 'html',
|
||||
injectScriptAttrs: 'is:inline ',
|
||||
},
|
||||
};
|
||||
@@ -0,0 +1,73 @@
|
||||
/**
|
||||
* Small read-only probes the framework entries share.
|
||||
*
|
||||
* Every helper here is cheap and failure-tolerant: detection runs on every
|
||||
* inject, against project trees that may be half-installed, so a missing or
|
||||
* malformed file means "not this framework", never a throw.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
/** Merged dependency names from package.json, or an empty object. */
|
||||
export function readPackageDeps(cwd) {
|
||||
const file = path.join(cwd, 'package.json');
|
||||
try {
|
||||
const pkg = JSON.parse(fs.readFileSync(file, 'utf-8'));
|
||||
return {
|
||||
...(pkg.dependencies || {}),
|
||||
...(pkg.devDependencies || {}),
|
||||
...(pkg.peerDependencies || {}),
|
||||
};
|
||||
} catch {
|
||||
return {};
|
||||
}
|
||||
}
|
||||
|
||||
export function hasAnyDependency(cwd, names) {
|
||||
const deps = readPackageDeps(cwd);
|
||||
return names.some((name) => Boolean(deps[name]));
|
||||
}
|
||||
|
||||
/** First top-level file name matching `re`, or null. */
|
||||
export function findConfigFile(cwd, re) {
|
||||
try {
|
||||
return fs.readdirSync(cwd, { withFileTypes: true })
|
||||
.find((entry) => entry.isFile() && re.test(entry.name))
|
||||
?.name ?? null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
export function fileExists(cwd, rel) {
|
||||
try {
|
||||
return fs.existsSync(path.join(cwd, rel));
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
export function firstExistingFile(cwd, candidates) {
|
||||
for (const rel of candidates) {
|
||||
if (fileExists(cwd, rel)) return rel;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Literal (non-glob) entries of `config.files` that exist on disk. Several
|
||||
* detectors read the configured injection target as a signal, which is how the
|
||||
* bare fixtures — a tree of `.astro` files with no astro.config — still resolve
|
||||
* to the framework that authored them.
|
||||
*/
|
||||
export function literalConfigFiles(cwd, config) {
|
||||
const files = Array.isArray(config?.files) ? config.files : [];
|
||||
const out = [];
|
||||
for (const rel of files) {
|
||||
if (typeof rel !== 'string' || rel.includes('*') || rel.includes('?')) continue;
|
||||
const normalized = rel.split(path.sep).join('/');
|
||||
if (fileExists(cwd, normalized)) out.push(normalized);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
@@ -0,0 +1,143 @@
|
||||
/**
|
||||
* The live-mode framework registry.
|
||||
*
|
||||
* Before this existed, framework knowledge was smeared across live-inject.mjs
|
||||
* (detection order, the Nuxt adapter, the Astro `is:inline` branch), the two
|
||||
* adapter modules, and live-wrap.mjs (which extension gets component preview,
|
||||
* which gets Astro's global-prefixed CSS, which gets JSX comments). Adding or
|
||||
* fixing a framework meant reading all of them.
|
||||
*
|
||||
* One entry per framework now declares everything the live scripts need:
|
||||
*
|
||||
* name stable identifier; also the `adapter` value in inject JSON.
|
||||
* detect (cwd, config) → falsy when this is not the project, otherwise
|
||||
* a truthy project descriptor that apply/remove/artifacts read.
|
||||
* Order in FRAMEWORKS is priority order; first truthy wins.
|
||||
* inject { kind: 'adapter', apply, remove, ignorePatterns, artifacts,
|
||||
* unpatch } for frameworks that server-render their document
|
||||
* shell, or { kind: 'tag' } for the generic marker-wrapped
|
||||
* <script src> block.
|
||||
* source how live-wrap treats files this framework authors:
|
||||
* extensions, preview ('source' | 'component'), styleMode,
|
||||
* styleTag, commentSyntax, injectScriptAttrs. Anything omitted
|
||||
* falls back to SOURCE_TRAIT_DEFAULTS.
|
||||
*
|
||||
* Two rules hold the thing together:
|
||||
*
|
||||
* 1. **Detection order is injection priority.** SvelteKit → Nuxt → TanStack
|
||||
* Start → Astro → Next → Vite → static HTML, exactly the order
|
||||
* live-inject.mjs used to hard-code. static-html always matches, so
|
||||
* resolveFramework never returns null.
|
||||
* 2. **Source traits resolve by file extension, not by project.** A SvelteKit
|
||||
* project's injection target is `src/app.html`; a Vite app can contain
|
||||
* `.astro` partials. live-wrap has always keyed these off the target file,
|
||||
* and resolveSourceTraits keeps it that way. Several entries may claim the
|
||||
* same extension (`.tsx` belongs to three); when they do, the values must
|
||||
* agree, which tests/live-frameworks.test.mjs asserts.
|
||||
*/
|
||||
|
||||
import path from 'node:path';
|
||||
|
||||
import { sveltekit } from './sveltekit.mjs';
|
||||
import { nuxt } from './nuxt.mjs';
|
||||
import { tanstackStart } from './tanstack-start.mjs';
|
||||
import { astro } from './astro.mjs';
|
||||
import { nextjs } from './nextjs.mjs';
|
||||
import { viteGeneric } from './vite-generic.mjs';
|
||||
import { staticHtml } from './static-html.mjs';
|
||||
import { TAG_PATCH_MARKERS, unpatchTagFile } from './tag-strategy.mjs';
|
||||
|
||||
/** Priority order. Do not reorder without re-reading rule 1 above. */
|
||||
export const FRAMEWORKS = Object.freeze([
|
||||
sveltekit,
|
||||
nuxt,
|
||||
tanstackStart,
|
||||
astro,
|
||||
nextjs,
|
||||
viteGeneric,
|
||||
staticHtml,
|
||||
]);
|
||||
|
||||
export const PREVIEW_MODES = Object.freeze(['source', 'component']);
|
||||
export const STYLE_MODES = Object.freeze(['scoped', 'astro-global-prefixed']);
|
||||
export const COMMENT_SYNTAXES = Object.freeze(['html', 'jsx']);
|
||||
export const INJECT_KINDS = Object.freeze(['adapter', 'tag']);
|
||||
|
||||
export const SOURCE_TRAIT_DEFAULTS = Object.freeze({
|
||||
preview: 'source',
|
||||
styleMode: 'scoped',
|
||||
styleTag: '<style data-impeccable-css="SESSION_ID">',
|
||||
commentSyntax: 'html',
|
||||
injectScriptAttrs: '',
|
||||
});
|
||||
|
||||
/** The patch kind the generic tag strategy records in the journal. */
|
||||
export const TAG_PATCH_KIND = 'live-tag';
|
||||
|
||||
/**
|
||||
* Undo functions keyed by the `patch` value an artifact carries. Built from
|
||||
* the entries so a new adapter registers its own undo alongside its apply.
|
||||
*/
|
||||
export const PATCH_UNDOERS = Object.freeze(Object.assign(
|
||||
{ [TAG_PATCH_KIND]: unpatchTagFile },
|
||||
...FRAMEWORKS.map((framework) => framework.inject.unpatch || {}),
|
||||
));
|
||||
|
||||
/**
|
||||
* First entry whose detect() matches. Returns { framework, project } where
|
||||
* project is the detector's descriptor (adapters read it; tag frameworks
|
||||
* mostly ignore it).
|
||||
*/
|
||||
export function resolveFramework(cwd = process.cwd(), config = null) {
|
||||
for (const framework of FRAMEWORKS) {
|
||||
const project = framework.detect(cwd, config);
|
||||
if (project) return { framework, project };
|
||||
}
|
||||
// Unreachable while static-html stays terminal, but a caller that reorders
|
||||
// the array should get a diagnosable null rather than a silent tag inject.
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Source-authoring traits for one file, merged over SOURCE_TRAIT_DEFAULTS.
|
||||
* `framework` names the entry that claimed the extension, or null.
|
||||
*/
|
||||
export function resolveSourceTraits(filePath) {
|
||||
const ext = path.extname(String(filePath || '')).toLowerCase();
|
||||
for (const framework of FRAMEWORKS) {
|
||||
const source = framework.source;
|
||||
if (!source || !source.extensions.includes(ext)) continue;
|
||||
const { extensions, ...traits } = source;
|
||||
return { framework: framework.name, ...SOURCE_TRAIT_DEFAULTS, ...traits };
|
||||
}
|
||||
return { framework: null, ...SOURCE_TRAIT_DEFAULTS };
|
||||
}
|
||||
|
||||
/**
|
||||
* Extra gitignore patterns the resolved framework needs beyond the static
|
||||
* LIVE_IGNORE_PATTERNS list (paths that depend on a detected srcDir or file
|
||||
* extension and so cannot be written down ahead of time).
|
||||
*/
|
||||
export function frameworkIgnorePatterns(resolved) {
|
||||
const fn = resolved?.framework?.inject?.ignorePatterns;
|
||||
return typeof fn === 'function' ? (fn(resolved.project) || []) : [];
|
||||
}
|
||||
|
||||
/**
|
||||
* The files this injection will create or patch, in journal-artifact form.
|
||||
* Adapters declare their own; the tag strategy patches exactly the resolved
|
||||
* config files.
|
||||
*/
|
||||
export function describeInjectArtifacts(resolved, { cwd = process.cwd(), files = [] } = {}) {
|
||||
if (!resolved) return [];
|
||||
const { framework, project } = resolved;
|
||||
if (framework.inject.kind === 'adapter') {
|
||||
return (framework.inject.artifacts?.({ cwd, project }) || []).filter((a) => a && a.path);
|
||||
}
|
||||
return files.map((file) => ({
|
||||
kind: 'patched',
|
||||
path: file,
|
||||
patch: TAG_PATCH_KIND,
|
||||
markers: [...TAG_PATCH_MARKERS],
|
||||
}));
|
||||
}
|
||||
@@ -0,0 +1,197 @@
|
||||
/**
|
||||
* Crash-safe injection journal.
|
||||
*
|
||||
* Injection writes into the user's source tree: generated components, a Nuxt
|
||||
* client plugin, marker blocks inside a layout, a patched CSP meta tag. The
|
||||
* clean path removes all of it on stop. The unclean paths do not:
|
||||
*
|
||||
* - the dev server is SIGKILLed, so `--remove` never runs;
|
||||
* - the project changes shape between start and stop (a nuxt.config appears,
|
||||
* a package.json is edited), so detection resolves a different framework
|
||||
* and the old framework's artifacts are nobody's business;
|
||||
* - stop runs from a different directory than start did.
|
||||
*
|
||||
* So every inject records what it wrote to `.impeccable/live/inject-journal.json`
|
||||
* before the next one runs, and both inject and `--remove` reconcile that
|
||||
* record against the tree.
|
||||
*
|
||||
* **The journal is a claim of ownership, not a to-do list.** Healing an
|
||||
* artifact only ever removes what still carries our marker; a generated file
|
||||
* the user has since replaced, or a layout they have since un-patched by hand,
|
||||
* is dropped from the journal untouched.
|
||||
*
|
||||
* **Path resolution is appRoot-relative.** Live entry scripts chdir onto the
|
||||
* roots manifest (`enterLiveRoot`) before doing anything, so a journal written
|
||||
* by a session started in the app root is found by a stop issued from any
|
||||
* directory inside the repo.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { PATCH_UNDOERS } from './index.mjs';
|
||||
|
||||
export const INJECT_JOURNAL_VERSION = 1;
|
||||
export const INJECT_JOURNAL_RELPATH = '.impeccable/live/inject-journal.json';
|
||||
|
||||
export function injectJournalPath(cwd = process.cwd()) {
|
||||
return path.join(cwd, ...INJECT_JOURNAL_RELPATH.split('/'));
|
||||
}
|
||||
|
||||
export function readInjectJournal(cwd = process.cwd()) {
|
||||
const file = injectJournalPath(cwd);
|
||||
let raw;
|
||||
try {
|
||||
raw = JSON.parse(fs.readFileSync(file, 'utf-8'));
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
if (!raw || typeof raw !== 'object' || !Array.isArray(raw.artifacts)) return null;
|
||||
return raw;
|
||||
}
|
||||
|
||||
export function clearInjectJournal(cwd = process.cwd()) {
|
||||
try { fs.unlinkSync(injectJournalPath(cwd)); } catch { /* already gone */ }
|
||||
}
|
||||
|
||||
function writeInjectJournal(cwd, journal) {
|
||||
const file = injectJournalPath(cwd);
|
||||
fs.mkdirSync(path.dirname(file), { recursive: true });
|
||||
fs.writeFileSync(file, JSON.stringify(journal, null, 2) + '\n', 'utf-8');
|
||||
return file;
|
||||
}
|
||||
|
||||
/**
|
||||
* Record the artifacts an injection just wrote. Replaces any previous record:
|
||||
* callers heal first (see healInjectJournal), so nothing survivable is lost.
|
||||
*/
|
||||
export function recordInjection(cwd = process.cwd(), { framework, port, artifacts = [] } = {}) {
|
||||
if (!artifacts.length) {
|
||||
clearInjectJournal(cwd);
|
||||
return null;
|
||||
}
|
||||
return writeInjectJournal(cwd, {
|
||||
version: INJECT_JOURNAL_VERSION,
|
||||
appRoot: path.resolve(cwd),
|
||||
framework: framework || null,
|
||||
port: Number.isFinite(Number(port)) ? Number(port) : null,
|
||||
pid: process.pid,
|
||||
recordedAt: new Date().toISOString(),
|
||||
artifacts,
|
||||
});
|
||||
}
|
||||
|
||||
function normalizeRel(cwd, rel) {
|
||||
return path.resolve(cwd, String(rel || '')).split(path.sep).join('/');
|
||||
}
|
||||
|
||||
function readIfPresent(abs) {
|
||||
try {
|
||||
return fs.readFileSync(abs, 'utf-8');
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function pruneEmptyDirs(dir, stopDir) {
|
||||
let current = path.resolve(dir);
|
||||
const stop = path.resolve(stopDir);
|
||||
while (current !== stop && current.startsWith(stop + path.sep)) {
|
||||
try {
|
||||
if (fs.readdirSync(current).length > 0) return;
|
||||
fs.rmdirSync(current);
|
||||
} catch {
|
||||
return;
|
||||
}
|
||||
current = path.dirname(current);
|
||||
}
|
||||
}
|
||||
|
||||
function insideProject(cwd, abs) {
|
||||
const rel = path.relative(path.resolve(cwd), path.resolve(abs));
|
||||
return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
|
||||
}
|
||||
|
||||
function healArtifact(cwd, artifact, undoers) {
|
||||
const abs = path.resolve(cwd, artifact.path);
|
||||
// The journal is a project-local file, i.e. attacker-writable input in a
|
||||
// cloned repo. Never touch anything outside the project tree, whatever the
|
||||
// journal claims to own.
|
||||
if (!insideProject(cwd, abs)) return { path: artifact.path, action: 'refused_outside_project' };
|
||||
const content = readIfPresent(abs);
|
||||
if (content === null) return { path: artifact.path, action: 'absent' };
|
||||
|
||||
if (artifact.kind === 'created') {
|
||||
// Only reclaim a generated file that still carries our marker; a created
|
||||
// artifact with no marker at all is unverifiable and stays untouched.
|
||||
if (!artifact.marker || !content.includes(artifact.marker)) {
|
||||
return { path: artifact.path, action: 'disowned' };
|
||||
}
|
||||
try { fs.rmSync(abs, { force: true }); } catch { return null; }
|
||||
if (artifact.pruneTo !== undefined) {
|
||||
const pruneRoot = path.resolve(cwd, artifact.pruneTo || '.');
|
||||
if (insideProject(cwd, pruneRoot) || pruneRoot === path.resolve(cwd)) {
|
||||
pruneEmptyDirs(path.dirname(abs), pruneRoot);
|
||||
}
|
||||
}
|
||||
return { path: artifact.path, action: 'removed' };
|
||||
}
|
||||
|
||||
if (artifact.kind === 'patched') {
|
||||
const markers = Array.isArray(artifact.markers) ? artifact.markers : [];
|
||||
// No marker left means the patch is already gone; never run an undo over
|
||||
// a file we no longer recognize (the undoers normalize whitespace).
|
||||
if (markers.length && !markers.some((marker) => content.includes(marker))) {
|
||||
return { path: artifact.path, action: 'disowned' };
|
||||
}
|
||||
const undo = undoers[artifact.patch];
|
||||
if (typeof undo !== 'function') return null;
|
||||
const next = undo(content);
|
||||
if (next === content) return { path: artifact.path, action: 'disowned' };
|
||||
try { fs.writeFileSync(abs, next, 'utf-8'); } catch { return null; }
|
||||
return { path: artifact.path, action: 'unpatched' };
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Reconcile the journal against the tree.
|
||||
*
|
||||
* `keep` is the set of paths the current operation legitimately owns — the
|
||||
* artifacts an inject is about to (re)write. Everything else in the journal is
|
||||
* an orphan of a session that is gone, and gets healed. This keeps a repeat
|
||||
* inject byte-idempotent: the artifacts it is about to rewrite are kept, not
|
||||
* torn down and rebuilt.
|
||||
*
|
||||
* Returns `{ healed, kept }`. `healed` lists only artifacts whose file was
|
||||
* actually changed or removed, so callers can stay silent when nothing was
|
||||
* orphaned. Idempotent: a second call finds an empty journal.
|
||||
*/
|
||||
export function healInjectJournal(cwd = process.cwd(), { keep = [], undoers = PATCH_UNDOERS } = {}) {
|
||||
const journal = readInjectJournal(cwd);
|
||||
if (!journal) return { healed: [], kept: [] };
|
||||
|
||||
const keepSet = new Set(keep.map((rel) => normalizeRel(cwd, rel)));
|
||||
const healed = [];
|
||||
const kept = [];
|
||||
|
||||
for (const artifact of journal.artifacts) {
|
||||
if (!artifact || typeof artifact.path !== 'string') continue;
|
||||
if (keepSet.has(normalizeRel(cwd, artifact.path))) {
|
||||
kept.push(artifact);
|
||||
continue;
|
||||
}
|
||||
const outcome = healArtifact(cwd, artifact, undoers);
|
||||
if (outcome && (outcome.action === 'removed' || outcome.action === 'unpatched')) {
|
||||
healed.push(outcome);
|
||||
}
|
||||
}
|
||||
|
||||
if (kept.length) {
|
||||
writeInjectJournal(cwd, { ...journal, artifacts: kept });
|
||||
} else {
|
||||
clearInjectJournal(cwd);
|
||||
}
|
||||
|
||||
return { healed, kept };
|
||||
}
|
||||
@@ -0,0 +1,49 @@
|
||||
/**
|
||||
* Next.js registry entry.
|
||||
*
|
||||
* Next takes the generic tag strategy: the App Router's root layout renders
|
||||
* `<html>…<body>` in JSX, so the marker-wrapped script block goes in there
|
||||
* verbatim. Nothing about injection differs from a plain Vite app, which is
|
||||
* why live-inject.mjs never had a Next branch. The entry exists so the
|
||||
* registry can name what it is looking at.
|
||||
*/
|
||||
|
||||
import { fileExists, findConfigFile, hasAnyDependency } from './detect-utils.mjs';
|
||||
|
||||
const NEXT_CONFIG_RE = /^next\.config\.(?:js|mjs|cjs|ts|mts|cts)$/;
|
||||
|
||||
const ROUTER_ENTRY_CANDIDATES = [
|
||||
'app/layout.tsx', 'app/layout.jsx', 'app/layout.ts', 'app/layout.js',
|
||||
'src/app/layout.tsx', 'src/app/layout.jsx', 'src/app/layout.ts', 'src/app/layout.js',
|
||||
'pages/_app.tsx', 'pages/_app.jsx', 'pages/_app.ts', 'pages/_app.js',
|
||||
'pages/_document.tsx', 'pages/_document.jsx',
|
||||
'src/pages/_app.tsx', 'src/pages/_app.jsx',
|
||||
];
|
||||
|
||||
export function detectNextProject(cwd = process.cwd()) {
|
||||
const configFile = findConfigFile(cwd, NEXT_CONFIG_RE);
|
||||
if (configFile) return { configFile, via: 'config' };
|
||||
if (hasAnyDependency(cwd, ['next'])) return { configFile: null, via: 'package' };
|
||||
// Next's file conventions are distinctive enough to stand alone: a root
|
||||
// `app/layout.*` or `pages/_app.*` is not a shape other bundlers produce.
|
||||
const entry = ROUTER_ENTRY_CANDIDATES.find((rel) => fileExists(cwd, rel));
|
||||
if (entry) return { configFile: null, via: 'router-entry', entry };
|
||||
return null;
|
||||
}
|
||||
|
||||
export const nextjs = {
|
||||
name: 'nextjs',
|
||||
|
||||
detect(cwd) {
|
||||
return detectNextProject(cwd);
|
||||
},
|
||||
|
||||
inject: { kind: 'tag' },
|
||||
|
||||
source: {
|
||||
extensions: ['.tsx', '.jsx'],
|
||||
preview: 'source',
|
||||
styleMode: 'scoped',
|
||||
commentSyntax: 'jsx',
|
||||
},
|
||||
};
|
||||
@@ -0,0 +1,161 @@
|
||||
/**
|
||||
* Nuxt registry entry, and the Nuxt adapter itself.
|
||||
*
|
||||
* A script element placed in app.vue is compiled as Vue-rendered DOM and is
|
||||
* not executed. Nuxt instead auto-discovers client plugins. Keep the adapter
|
||||
* generated, dev-only, and outside user-authored source: Live creates one
|
||||
* marked .client.ts plugin on start and removes it on stop.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { buildLiveScriptSrc } from './script-src.mjs';
|
||||
import { findConfigFile } from './detect-utils.mjs';
|
||||
|
||||
export const NUXT_PLUGIN_MARKER = 'impeccable-live-nuxt-plugin';
|
||||
export const NUXT_PLUGIN_NAME = 'impeccable-live.client.ts';
|
||||
|
||||
const NUXT_CONFIG_RE = /^nuxt\.config\.(?:js|mjs|cjs|ts|mts|cts)$/;
|
||||
|
||||
export function detectNuxtProject(cwd = process.cwd()) {
|
||||
const configFile = findConfigFile(cwd, NUXT_CONFIG_RE);
|
||||
if (!configFile) return null;
|
||||
|
||||
const config = fs.readFileSync(path.join(cwd, configFile), 'utf-8');
|
||||
const literalSrcDir = config.match(/\bsrcDir\s*:\s*(['"])([^'"]+)\1/);
|
||||
let appDir = '';
|
||||
if (literalSrcDir) {
|
||||
const candidate = literalSrcDir[2]
|
||||
.replace(/\\/g, '/')
|
||||
.replace(/^\.\//, '')
|
||||
.replace(/\/+$/, '');
|
||||
const normalized = path.posix.normalize(candidate);
|
||||
if (normalized !== '..' && !normalized.startsWith('../') && !path.isAbsolute(normalized)) {
|
||||
appDir = normalized === '.' ? '' : normalized;
|
||||
}
|
||||
} else if (
|
||||
fs.existsSync(path.join(cwd, 'app', 'app.vue'))
|
||||
|| fs.existsSync(path.join(cwd, 'app', 'pages'))
|
||||
) {
|
||||
appDir = 'app';
|
||||
}
|
||||
|
||||
const pluginFile = [appDir, 'plugins', NUXT_PLUGIN_NAME].filter(Boolean).join('/');
|
||||
return { configFile, appDir, pluginFile };
|
||||
}
|
||||
|
||||
export function buildNuxtPlugin(port, token) {
|
||||
return `/* ${NUXT_PLUGIN_MARKER} */
|
||||
const liveSrc = '${buildLiveScriptSrc(port, token)}';
|
||||
const liveSelector = 'script[data-impeccable-live-nuxt]';
|
||||
|
||||
export default defineNuxtPlugin(() => {
|
||||
if (!import.meta.dev || typeof document === 'undefined') return;
|
||||
|
||||
const expectedSrc = new URL(liveSrc, window.location.href).href;
|
||||
let script = document.querySelector(liveSelector);
|
||||
if (script?.src === expectedSrc) return;
|
||||
script?.remove();
|
||||
|
||||
script = document.createElement('script');
|
||||
script.src = liveSrc;
|
||||
script.async = true;
|
||||
script.dataset.impeccableLiveNuxt = '';
|
||||
document.head.appendChild(script);
|
||||
|
||||
import.meta.hot?.dispose(() => {
|
||||
if (script?.isConnected) script.remove();
|
||||
});
|
||||
});
|
||||
/* /${NUXT_PLUGIN_MARKER} */
|
||||
`;
|
||||
}
|
||||
|
||||
export function applyNuxtLiveAdapter({ cwd = process.cwd(), port, token, project = detectNuxtProject(cwd) }) {
|
||||
if (!project) return { error: 'nuxt_not_detected' };
|
||||
const absFile = path.join(cwd, project.pluginFile);
|
||||
const existing = fs.existsSync(absFile) ? fs.readFileSync(absFile, 'utf-8') : null;
|
||||
if (existing !== null && !existing.includes(NUXT_PLUGIN_MARKER)) {
|
||||
return {
|
||||
file: project.pluginFile,
|
||||
error: 'nuxt_plugin_conflict',
|
||||
hint: `${project.pluginFile} already exists and is not managed by Impeccable Live`,
|
||||
};
|
||||
}
|
||||
|
||||
const content = buildNuxtPlugin(port, token);
|
||||
fs.mkdirSync(path.dirname(absFile), { recursive: true });
|
||||
if (content !== existing) fs.writeFileSync(absFile, content, 'utf-8');
|
||||
return {
|
||||
file: project.pluginFile,
|
||||
inserted: true,
|
||||
changed: content !== existing,
|
||||
devOnly: true,
|
||||
};
|
||||
}
|
||||
|
||||
export function removeNuxtLiveAdapter({ cwd = process.cwd(), project = detectNuxtProject(cwd) }) {
|
||||
if (!project) return { error: 'nuxt_not_detected' };
|
||||
const absFile = path.join(cwd, project.pluginFile);
|
||||
if (!fs.existsSync(absFile)) {
|
||||
return { file: project.pluginFile, removed: false, note: 'no adapter present' };
|
||||
}
|
||||
const content = fs.readFileSync(absFile, 'utf-8');
|
||||
if (!content.includes(NUXT_PLUGIN_MARKER)) {
|
||||
return {
|
||||
file: project.pluginFile,
|
||||
removed: false,
|
||||
error: 'nuxt_plugin_conflict',
|
||||
hint: `${project.pluginFile} is not managed by Impeccable Live`,
|
||||
};
|
||||
}
|
||||
fs.unlinkSync(absFile);
|
||||
const pluginDir = path.dirname(absFile);
|
||||
if (fs.readdirSync(pluginDir).length === 0) fs.rmdirSync(pluginDir);
|
||||
return { file: project.pluginFile, removed: true };
|
||||
}
|
||||
|
||||
export const nuxt = {
|
||||
name: 'nuxt',
|
||||
|
||||
detect(cwd) {
|
||||
return detectNuxtProject(cwd);
|
||||
},
|
||||
|
||||
inject: {
|
||||
kind: 'adapter',
|
||||
|
||||
apply({ cwd, port, token, project }) {
|
||||
return applyNuxtLiveAdapter({ cwd, port, token, project });
|
||||
},
|
||||
|
||||
remove({ cwd, project }) {
|
||||
return removeNuxtLiveAdapter({ cwd, project });
|
||||
},
|
||||
|
||||
// The plugin path depends on the resolved srcDir, so it cannot live in the
|
||||
// static ignore list the way the SvelteKit paths do.
|
||||
ignorePatterns(project) {
|
||||
return project?.pluginFile ? [project.pluginFile] : [];
|
||||
},
|
||||
|
||||
artifacts({ project }) {
|
||||
if (!project?.pluginFile) return [];
|
||||
return [{
|
||||
kind: 'created',
|
||||
path: project.pluginFile,
|
||||
marker: NUXT_PLUGIN_MARKER,
|
||||
// Mirrors removeNuxtLiveAdapter: the generated `plugins/` directory
|
||||
// goes when it empties, its parent stays.
|
||||
pruneTo: path.posix.dirname(path.posix.dirname(project.pluginFile)),
|
||||
}];
|
||||
},
|
||||
},
|
||||
|
||||
source: {
|
||||
extensions: ['.vue'],
|
||||
preview: 'source',
|
||||
styleMode: 'scoped',
|
||||
commentSyntax: 'html',
|
||||
},
|
||||
};
|
||||
@@ -0,0 +1,17 @@
|
||||
/**
|
||||
* The one place that builds the `/live.js` URL the browser loads.
|
||||
*
|
||||
* Every injection path needs it (the generic script tag, the Nuxt client
|
||||
* plugin, the SvelteKit root component, the TanStack mount component), and a
|
||||
* separate module keeps that shared leaf free of import cycles: the framework
|
||||
* entries import it, and nothing here imports a framework entry.
|
||||
*/
|
||||
|
||||
/**
|
||||
* When a token is supplied it rides as a `?token=...` query param so the
|
||||
* server's token-gated /live.js handler authorizes the fetch.
|
||||
*/
|
||||
export function buildLiveScriptSrc(port, token) {
|
||||
const base = 'http://localhost:' + port + '/live.js';
|
||||
return token ? base + '?token=' + encodeURIComponent(token) : base;
|
||||
}
|
||||
@@ -0,0 +1,26 @@
|
||||
/**
|
||||
* Static HTML registry entry: the terminal fallback.
|
||||
*
|
||||
* Hand-written pages, a multi-page site emitted by a generator, anything with
|
||||
* no bundler config at the app root. `detect` always matches, so this entry
|
||||
* must stay last in FRAMEWORKS. Its behavior is the plain tag strategy, which
|
||||
* is what live-inject.mjs did for every unrecognized project before the
|
||||
* registry existed.
|
||||
*/
|
||||
|
||||
export const staticHtml = {
|
||||
name: 'static-html',
|
||||
|
||||
detect() {
|
||||
return { via: 'fallback' };
|
||||
},
|
||||
|
||||
inject: { kind: 'tag' },
|
||||
|
||||
source: {
|
||||
extensions: ['.html', '.htm'],
|
||||
preview: 'source',
|
||||
styleMode: 'scoped',
|
||||
commentSyntax: 'html',
|
||||
},
|
||||
};
|
||||
@@ -0,0 +1,71 @@
|
||||
/**
|
||||
* SvelteKit registry entry.
|
||||
*
|
||||
* Detection and the apply/remove pair are the existing adapter's
|
||||
* (`../sveltekit-adapter.mjs`); this file only declares them to the registry
|
||||
* and names the artifacts the journal has to be able to heal.
|
||||
*/
|
||||
|
||||
import {
|
||||
SVELTE_LAYOUT_MARKER_OPEN,
|
||||
SVELTE_LIVE_ROOT_COMPONENT,
|
||||
applySvelteKitLiveAdapter,
|
||||
detectSvelteKitProject,
|
||||
removeSvelteKitLiveAdapter,
|
||||
unpatchSvelteLayout,
|
||||
} from '../sveltekit-adapter.mjs';
|
||||
|
||||
export const sveltekit = {
|
||||
name: 'sveltekit',
|
||||
|
||||
detect(cwd, config) {
|
||||
return detectSvelteKitProject(cwd, config);
|
||||
},
|
||||
|
||||
inject: {
|
||||
kind: 'adapter',
|
||||
|
||||
apply({ cwd, port, token, config }) {
|
||||
return applySvelteKitLiveAdapter({ cwd, port, token, config });
|
||||
},
|
||||
|
||||
remove({ cwd, config }) {
|
||||
return removeSvelteKitLiveAdapter({ cwd, config });
|
||||
},
|
||||
|
||||
// The generated root component and the `src/lib/impeccable/` runtime paths
|
||||
// are already in the static LIVE_IGNORE_PATTERNS list, so nothing extra.
|
||||
ignorePatterns() {
|
||||
return [];
|
||||
},
|
||||
|
||||
artifacts({ project }) {
|
||||
return [
|
||||
{
|
||||
kind: 'created',
|
||||
path: SVELTE_LIVE_ROOT_COMPONENT,
|
||||
marker: 'impeccable-live-root',
|
||||
pruneTo: 'src',
|
||||
},
|
||||
{
|
||||
kind: 'patched',
|
||||
path: project?.layoutFile || 'src/routes/+layout.svelte',
|
||||
patch: 'sveltekit-layout',
|
||||
markers: [SVELTE_LAYOUT_MARKER_OPEN],
|
||||
},
|
||||
];
|
||||
},
|
||||
|
||||
unpatch: {
|
||||
'sveltekit-layout': unpatchSvelteLayout,
|
||||
},
|
||||
},
|
||||
|
||||
source: {
|
||||
extensions: ['.svelte'],
|
||||
// Svelte resets component-local state on markup HMR updates, so variants
|
||||
// are mounted from generated components rather than written into the route.
|
||||
preview: 'component',
|
||||
commentSyntax: 'html',
|
||||
},
|
||||
};
|
||||
@@ -0,0 +1,247 @@
|
||||
/**
|
||||
* The generic `tag` injection strategy.
|
||||
*
|
||||
* Frameworks without a dedicated adapter get a literal marker-wrapped
|
||||
* `<script src>` block written into the entry template named by
|
||||
* `.impeccable/live/config.json`. This module owns that block: building it,
|
||||
* inserting it at the configured anchor, removing it again, and the
|
||||
* Content-Security-Policy meta patch that keeps the cross-origin load allowed.
|
||||
*
|
||||
* It is deliberately framework-agnostic. Per-framework knowledge (Astro's
|
||||
* `is:inline`, for instance) arrives as the `scriptAttrs` argument, resolved
|
||||
* from the registry by the caller, so nothing here has to branch on a file
|
||||
* extension or a project shape.
|
||||
*/
|
||||
|
||||
import { buildLiveScriptSrc } from './script-src.mjs';
|
||||
|
||||
export const MARKER_OPEN_TEXT = 'impeccable-live-start';
|
||||
export const MARKER_CLOSE_TEXT = 'impeccable-live-end';
|
||||
|
||||
/** Markers that identify a file as still carrying our tag-strategy patch. */
|
||||
export const TAG_PATCH_MARKERS = Object.freeze([MARKER_OPEN_TEXT, 'data-impeccable-csp-original']);
|
||||
|
||||
function commentOpen(syntax) { return syntax === 'jsx' ? '{/*' : '<!--'; }
|
||||
function commentClose(syntax) { return syntax === 'jsx' ? '*/}' : '-->'; }
|
||||
|
||||
/**
|
||||
* `scriptAttrs` is a pre-rendered attribute string (trailing space included)
|
||||
* that the registry supplies for the target file. Astro is the only framework
|
||||
* that uses it today: Astro processes `<script>` tags by default and rewrites
|
||||
* src to its own bundled URL, so `is:inline ` opts out and the literal external
|
||||
* src survives.
|
||||
*/
|
||||
export function buildTagBlock(syntax, port, token, scriptAttrs = '') {
|
||||
const open = commentOpen(syntax);
|
||||
const close = commentClose(syntax);
|
||||
return (
|
||||
open + ' ' + MARKER_OPEN_TEXT + ' ' + close + '\n' +
|
||||
'<script ' + scriptAttrs + 'src="' + buildLiveScriptSrc(port, token) + '"></script>\n' +
|
||||
open + ' ' + MARKER_CLOSE_TEXT + ' ' + close + '\n'
|
||||
);
|
||||
}
|
||||
|
||||
function detectLineEnding(content) {
|
||||
if (content.includes('\r\n')) return '\r\n';
|
||||
if (content.includes('\r')) return '\r';
|
||||
return '\n';
|
||||
}
|
||||
|
||||
function normalizeLineEndings(content, lineEnding) {
|
||||
return lineEnding === '\n' ? content : content.replace(/\n/g, lineEnding);
|
||||
}
|
||||
|
||||
function readLineEndingAt(content, index) {
|
||||
if (content[index] === '\r' && content[index + 1] === '\n') return '\r\n';
|
||||
if (content[index] === '\n') return '\n';
|
||||
if (content[index] === '\r') return '\r';
|
||||
return '';
|
||||
}
|
||||
|
||||
export function insertTag(content, config, port, token, scriptAttrs = '') {
|
||||
const lineEnding = detectLineEnding(content);
|
||||
const block = normalizeLineEndings(buildTagBlock(config.commentSyntax, port, token, scriptAttrs), lineEnding);
|
||||
// insertBefore: match the LAST occurrence. Anchors like `</body>` naturally
|
||||
// belong at the end, and the same literal can appear earlier in code blocks
|
||||
// within rendered documentation pages.
|
||||
if (config.insertBefore) {
|
||||
const idx = content.lastIndexOf(config.insertBefore);
|
||||
if (idx === -1) return content;
|
||||
return content.slice(0, idx) + block + content.slice(idx);
|
||||
}
|
||||
// insertAfter: match the FIRST occurrence — typical anchors like `<head>` or
|
||||
// `<body>` open near the top of the document.
|
||||
const idx = content.indexOf(config.insertAfter);
|
||||
if (idx === -1) return content;
|
||||
const after = idx + config.insertAfter.length;
|
||||
// Preserve an existing trailing newline if the anchor already has one.
|
||||
// Slice the remainder from the original anchor offset, not prefix.length:
|
||||
// in the no-newline case prefix is one char longer than the anchor (the
|
||||
// appended '\n'), so slicing by prefix.length would drop the first real
|
||||
// character after the anchor (#227).
|
||||
const existingNewline = readLineEndingAt(content, after);
|
||||
const prefix = content.slice(0, after) + (existingNewline || lineEnding);
|
||||
const rest = content.slice(after + existingNewline.length);
|
||||
return prefix + block + rest;
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove the live script block. Matches either HTML or JSX comment markers
|
||||
* regardless of config (so stale tags from a wrong config can still be cleaned).
|
||||
*
|
||||
* Indent-preserving: captures any whitespace immediately preceding the opener
|
||||
* marker and re-emits it in place of the removed block. `insertTag` inserted
|
||||
* the block *after* the original line's indent and *before* the anchor (e.g.
|
||||
* `</body>`), which moved the indent onto the opener line and left the anchor
|
||||
* unindented. Replacing the whole block (plus its trailing newline) with just
|
||||
* the captured indent hands the indent back to the anchor that follows.
|
||||
*/
|
||||
export function removeTag(content, _syntax) {
|
||||
const patterns = [
|
||||
/([ \t]*)<!--\s*impeccable-live-start\s*-->[\s\S]*?<!--\s*impeccable-live-end\s*-->([ \t]*(?:\r\n|\n|\r|$)?)/,
|
||||
/([ \t]*)\{\/\*\s*impeccable-live-start\s*\*\/\}[\s\S]*?\{\/\*\s*impeccable-live-end\s*\*\/\}([ \t]*(?:\r\n|\n|\r|$)?)/,
|
||||
];
|
||||
for (const pat of patterns) {
|
||||
let changed = false;
|
||||
let next = content;
|
||||
do {
|
||||
content = next;
|
||||
next = content.replace(pat, (_match, leadingIndent, trailing = '') => {
|
||||
if (/[\r\n]/.test(trailing)) return leadingIndent;
|
||||
return leadingIndent || trailing || '';
|
||||
});
|
||||
if (next !== content) changed = true;
|
||||
} while (next !== content);
|
||||
if (changed) return next;
|
||||
}
|
||||
return content;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Content-Security-Policy meta-tag patcher
|
||||
//
|
||||
// When the user's HTML carries `<meta http-equiv="Content-Security-Policy">`,
|
||||
// the cross-origin load of /live.js (and the SSE/POST connection back to
|
||||
// localhost:PORT) is blocked unless the CSP explicitly allows that origin.
|
||||
//
|
||||
// On insert: append `http://localhost:PORT` to `script-src` and `connect-src`,
|
||||
// and stash the original `content` value in a `data-impeccable-csp-original`
|
||||
// attribute (base64) so revert is exact.
|
||||
//
|
||||
// On remove: detect the marker attribute, decode it, restore the original
|
||||
// content value verbatim, drop the marker.
|
||||
//
|
||||
// Header-based CSP (Next.js headers, Nuxt routeRules, SvelteKit kit.csp,
|
||||
// shared helpers) is NOT patched here — those need framework-specific config
|
||||
// edits and are handled via the existing detect-csp.mjs reference output.
|
||||
// Only the in-source meta-tag form gets the auto-patch.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const CSP_MARKER_ATTR = 'data-impeccable-csp-original';
|
||||
|
||||
function findCspMetaTags(content) {
|
||||
const out = [];
|
||||
const tagRe = /<meta\s+([^>]*?)\/?>/gis;
|
||||
let m;
|
||||
while ((m = tagRe.exec(content)) !== null) {
|
||||
const attrs = m[1];
|
||||
if (!/(http-equiv|httpEquiv)\s*=\s*(['"])Content-Security-Policy\2/i.test(attrs)) continue;
|
||||
out.push({ start: m.index, end: m.index + m[0].length, full: m[0], attrs });
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function getAttr(attrs, name) {
|
||||
const re = new RegExp(`\\b${name}\\s*=\\s*(['"])([\\s\\S]*?)\\1`, 'i');
|
||||
const m = attrs.match(re);
|
||||
return m ? { quote: m[1], value: m[2], full: m[0] } : null;
|
||||
}
|
||||
|
||||
function appendOriginToDirective(csp, directive, origin) {
|
||||
const re = new RegExp(`(^|;)(\\s*)(${directive})\\s+([^;]*)`, 'i');
|
||||
const m = csp.match(re);
|
||||
if (m) {
|
||||
const tokens = m[4].trim().split(/\s+/);
|
||||
if (tokens.includes(origin)) return csp;
|
||||
return csp.replace(re, `${m[1]}${m[2]}${m[3]} ${[...tokens, origin].join(' ')}`);
|
||||
}
|
||||
// Directive missing — add it. Use 'self' + origin so we don't inadvertently
|
||||
// narrow the policy compared to the default-src fallback (most users with
|
||||
// an explicit CSP have 'self' there).
|
||||
return csp.trim().replace(/;?\s*$/, '') + `; ${directive} 'self' ${origin}`;
|
||||
}
|
||||
|
||||
export function patchCspMeta(content, port) {
|
||||
const tags = findCspMetaTags(content);
|
||||
if (tags.length === 0) return content;
|
||||
const origin = `http://localhost:${port}`;
|
||||
|
||||
// Walk last-to-first so prior splices don't invalidate later indices.
|
||||
let result = content;
|
||||
for (let i = tags.length - 1; i >= 0; i--) {
|
||||
const tag = tags[i];
|
||||
const attrs = tag.attrs;
|
||||
if (getAttr(attrs, CSP_MARKER_ATTR)) continue; // already patched
|
||||
const contentAttr = getAttr(attrs, 'content');
|
||||
if (!contentAttr) continue;
|
||||
|
||||
const original = contentAttr.value;
|
||||
let patched = original;
|
||||
patched = appendOriginToDirective(patched, 'script-src', origin);
|
||||
patched = appendOriginToDirective(patched, 'connect-src', origin);
|
||||
// The shader overlay during 'generating' creates a screenshot via
|
||||
// URL.createObjectURL, producing a `blob:` URL — img-src 'self' rejects
|
||||
// those. Add `blob:` so the overlay doesn't throw a CSP violation.
|
||||
patched = appendOriginToDirective(patched, 'img-src', 'blob:');
|
||||
if (patched === original) continue;
|
||||
|
||||
const newContentAttr = `content=${contentAttr.quote}${patched}${contentAttr.quote}`;
|
||||
const marker = `${CSP_MARKER_ATTR}="${Buffer.from(original, 'utf-8').toString('base64')}"`;
|
||||
// The tagRe captures any whitespace between the last attribute and the
|
||||
// closing `/>` as part of `attrs`. Naively appending ` ${marker}` after
|
||||
// a replace would land it BEFORE that trailing space, leaving a double
|
||||
// space inside attrs and clobbering the space before `/>`. Split off
|
||||
// the trailing whitespace, splice the marker into the attribute body,
|
||||
// and re-append the original trailing whitespace so a self-closing
|
||||
// `<meta … />` round-trips byte-for-byte.
|
||||
const trailingWs = (attrs.match(/[ \t]*$/) || [''])[0];
|
||||
const attrsBody = attrs.slice(0, attrs.length - trailingWs.length);
|
||||
const newAttrs = attrsBody.replace(contentAttr.full, newContentAttr) + ' ' + marker + trailingWs;
|
||||
const newTag = tag.full.replace(attrs, newAttrs);
|
||||
|
||||
result = result.slice(0, tag.start) + newTag + result.slice(tag.end);
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
export function revertCspMeta(content) {
|
||||
const tags = findCspMetaTags(content);
|
||||
if (tags.length === 0) return content;
|
||||
|
||||
let result = content;
|
||||
for (let i = tags.length - 1; i >= 0; i--) {
|
||||
const tag = tags[i];
|
||||
const origAttr = getAttr(tag.attrs, CSP_MARKER_ATTR);
|
||||
if (!origAttr) continue;
|
||||
const contentAttr = getAttr(tag.attrs, 'content');
|
||||
if (!contentAttr) continue;
|
||||
|
||||
let originalValue;
|
||||
try { originalValue = Buffer.from(origAttr.value, 'base64').toString('utf-8'); }
|
||||
catch { continue; }
|
||||
|
||||
const newContentAttr = `content=${contentAttr.quote}${originalValue}${contentAttr.quote}`;
|
||||
let newAttrs = tag.attrs.replace(contentAttr.full, newContentAttr);
|
||||
// Drop the marker attribute and any single space immediately preceding it.
|
||||
newAttrs = newAttrs.replace(new RegExp(`\\s*${origAttr.full}`), '');
|
||||
const newTag = tag.full.replace(tag.attrs, newAttrs);
|
||||
|
||||
result = result.slice(0, tag.start) + newTag + result.slice(tag.end);
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
/** The journal's undo for a tag-strategy patch: drop the block, restore CSP. */
|
||||
export function unpatchTagFile(content) {
|
||||
return revertCspMeta(removeTag(content));
|
||||
}
|
||||
@@ -0,0 +1,70 @@
|
||||
/**
|
||||
* TanStack Start registry entry.
|
||||
*
|
||||
* Detection and the apply/remove pair are the existing adapter's
|
||||
* (`../tanstack-adapter.mjs`); this file only declares them to the registry
|
||||
* and names the artifacts the journal has to be able to heal.
|
||||
*/
|
||||
|
||||
import {
|
||||
TANSTACK_MARKER_OPEN,
|
||||
applyTanStackLiveAdapter,
|
||||
detectTanStackStartProject,
|
||||
removeTanStackLiveAdapter,
|
||||
unpatchTanStackRoot,
|
||||
} from '../tanstack-adapter.mjs';
|
||||
|
||||
export const tanstackStart = {
|
||||
name: 'tanstack-start',
|
||||
|
||||
detect(cwd) {
|
||||
return detectTanStackStartProject(cwd);
|
||||
},
|
||||
|
||||
inject: {
|
||||
kind: 'adapter',
|
||||
|
||||
apply({ cwd, port, token, project }) {
|
||||
return applyTanStackLiveAdapter({ cwd, port, token, project });
|
||||
},
|
||||
|
||||
remove({ cwd, project }) {
|
||||
return removeTanStackLiveAdapter({ cwd, project });
|
||||
},
|
||||
|
||||
// The mount component's extension follows the root route's, so the path
|
||||
// cannot live in the static ignore list.
|
||||
ignorePatterns(project) {
|
||||
return project?.componentFile ? [project.componentFile] : [];
|
||||
},
|
||||
|
||||
artifacts({ project }) {
|
||||
if (!project) return [];
|
||||
return [
|
||||
{
|
||||
kind: 'created',
|
||||
path: project.componentFile,
|
||||
marker: 'impeccable-live-tanstack',
|
||||
pruneTo: 'src',
|
||||
},
|
||||
{
|
||||
kind: 'patched',
|
||||
path: project.rootRoute,
|
||||
patch: 'tanstack-root',
|
||||
markers: [TANSTACK_MARKER_OPEN],
|
||||
},
|
||||
];
|
||||
},
|
||||
|
||||
unpatch: {
|
||||
'tanstack-root': unpatchTanStackRoot,
|
||||
},
|
||||
},
|
||||
|
||||
source: {
|
||||
extensions: ['.tsx', '.jsx'],
|
||||
preview: 'source',
|
||||
styleMode: 'scoped',
|
||||
commentSyntax: 'jsx',
|
||||
},
|
||||
};
|
||||
@@ -0,0 +1,42 @@
|
||||
/**
|
||||
* Generic Vite registry entry: a bundled app with a real `index.html` entry
|
||||
* and no framework-specific document ownership. React, Vue, Solid, Preact and
|
||||
* a plain TanStack Router SPA all land here — the marker-wrapped script block
|
||||
* goes straight into the HTML entry.
|
||||
*
|
||||
* This is the entry that catches everything with a bundler config; only
|
||||
* static-html sits below it.
|
||||
*/
|
||||
|
||||
import { fileExists, findConfigFile, hasAnyDependency } from './detect-utils.mjs';
|
||||
|
||||
const VITE_CONFIG_RE = /^vite\.config\.(?:js|mjs|cjs|ts|mts|cts)$/;
|
||||
|
||||
export function detectViteProject(cwd = process.cwd()) {
|
||||
const configFile = findConfigFile(cwd, VITE_CONFIG_RE);
|
||||
if (configFile) return { configFile, via: 'config' };
|
||||
if (hasAnyDependency(cwd, ['vite'])) return { configFile: null, via: 'package' };
|
||||
// A zero-config Vite app is index.html + package.json, the same pair
|
||||
// roots.mjs treats as an app root.
|
||||
if (fileExists(cwd, 'index.html') && fileExists(cwd, 'package.json')) {
|
||||
return { configFile: null, via: 'zero-config' };
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
export const viteGeneric = {
|
||||
name: 'vite-generic',
|
||||
|
||||
detect(cwd) {
|
||||
return detectViteProject(cwd);
|
||||
},
|
||||
|
||||
inject: { kind: 'tag' },
|
||||
|
||||
source: {
|
||||
extensions: ['.tsx', '.jsx'],
|
||||
preview: 'source',
|
||||
styleMode: 'scoped',
|
||||
commentSyntax: 'jsx',
|
||||
},
|
||||
};
|
||||
@@ -0,0 +1,142 @@
|
||||
/**
|
||||
* Just-in-time agent instructions for live mode.
|
||||
*
|
||||
* The live scripts, not the reference doc, own situational plumbing: every
|
||||
* event printed by live-poll carries an `_instructions` string describing
|
||||
* exactly what to do NEXT, with real ids, paths, and line numbers already
|
||||
* substituted and only the active path's rules included (a svelte-component
|
||||
* session never sees JSX guidance, and vice versa). live.md stays lean: the
|
||||
* session contract, harness policy, and design-quality guidance that is not
|
||||
* situational (identity lock, variation axes, parameter budgets).
|
||||
*
|
||||
* Keep these strings imperative, concrete, and short. They are read by an
|
||||
* agent mid-session; every sentence must earn its tokens. Instructions are
|
||||
* versioned with the scripts, so they cannot drift from behavior the way a
|
||||
* hand-maintained doc can.
|
||||
*/
|
||||
|
||||
const PLAN_POINTER = 'Plan per live.md section 4: extract the identity lock, pick default vs departure mode, commit each variant to a DIFFERENT primary axis, squint-test the trio. Size parameter knobs per section 7 budgets.';
|
||||
|
||||
function pollCmd(scriptsPath) {
|
||||
return `node ${scriptsPath}/live-poll.mjs`;
|
||||
}
|
||||
|
||||
function replyCmd(scriptsPath, id, rest) {
|
||||
return `${pollCmd(scriptsPath)} --reply ${id} ${rest}`;
|
||||
}
|
||||
|
||||
export function instructionsForEvent(event, { scriptsPath = '{{scripts_path}}' } = {}) {
|
||||
if (!event || typeof event !== 'object') return undefined;
|
||||
switch (event.type) {
|
||||
case 'generate':
|
||||
return generateInstructions(event, scriptsPath);
|
||||
case 'steer':
|
||||
return `Do what the message asks (page edits, navigation help, or a short answer). Then reply exactly once: ${replyCmd(scriptsPath, event.id, 'steer_done ["optional short toast"]')} (on failure: --reply ${event.id} error "Short reason"). No pickup ack; poll again immediately after.`;
|
||||
case 'prefetch':
|
||||
return `Speculative pre-read, no reply owed: resolve ${JSON.stringify(event.pageUrl || '/')} to its source file (root "/" is usually the boot's pageFile; multi-page sites map /foo to public/foo/index.html; SPAs map all routes to one entry), read it into context, then poll again. Skip if you cannot resolve it confidently.`;
|
||||
case 'variant_mount_failed':
|
||||
return `The browser could NOT render variant ${event.variant}${event.url ? ` (module: ${event.url})` : ''}${event.error ? `: ${String(event.error).slice(0, 200)}` : ''}. The user sees a persistent error card, not variants. Fix the variant source files, then reply ${replyCmd(scriptsPath, event.id, 'done --file <manifest or source path>')}; the browser retries on its own. Poll again after the reply.`;
|
||||
case 'accept':
|
||||
return acceptInstructions(event, scriptsPath);
|
||||
case 'discard':
|
||||
return event?._completionAck?.ok === true
|
||||
? 'Original restored and durable completion acknowledged; nothing to do. Poll again.'
|
||||
: `Completion was not acknowledged: run node ${scriptsPath}/live-complete.mjs --id ${event.id} --discarded, then poll again.`;
|
||||
case 'manual_edit_apply':
|
||||
return `The user already clicked Apply; never ask, discard, or redirect. Delegate the source edits to the impeccable_manual_edit_applier subagent when available (pass cwd, scripts path, event id, page URL, chunk/deadline, batch, evidencePath); it must not poll or reply. ${event.repair ? 'A `repair` payload is present: the previous Apply changed source but validation failed; fix the CURRENT source, never roll back yourself. ' : ''}Reply exactly once: ${replyCmd(scriptsPath, event.id, `done --data '{"status":"done","appliedEntryIds":[...],"failed":[],"files":[...],"notes":[]}'`)} (status "partial"/"error" with failed[] when not every entry applied). Then poll again.`;
|
||||
case 'timeout':
|
||||
return 'No event arrived; poll again immediately.';
|
||||
case 'exit':
|
||||
return `Session over: kill any background poll, then node ${scriptsPath}/live-server.mjs stop (removes the injected script tag). Sweep leftover impeccable-variants-start / impeccable-carbonize-start markers from source.`;
|
||||
default:
|
||||
return undefined;
|
||||
}
|
||||
}
|
||||
|
||||
function generateInstructions(event, scriptsPath) {
|
||||
const id = event.id;
|
||||
const scaffold = event.scaffold;
|
||||
const steps = [];
|
||||
|
||||
if (event.screenshotPath) {
|
||||
steps.push(`Read the annotated screenshot first: ${event.screenshotPath}. Comment {x,y} positions bind text to the child under that point; strokes read by shape (loop = emphasis on this thing, arrow = direction, cross = delete).`);
|
||||
} else {
|
||||
steps.push('No screenshot was sent (the user did not annotate); do not ask for one and do not screenshot the page. Work from element.outerHTML, the computed styles, and the prompt.');
|
||||
}
|
||||
|
||||
if (event.mode === 'insert') {
|
||||
steps.push(insertScaffoldInstructions(event, scriptsPath));
|
||||
} else if (scaffold?.previewMode === 'svelte-component') {
|
||||
steps.push(svelteComponentInstructions(event, scaffold, scriptsPath));
|
||||
} else if (scaffold && scaffold.sourceWritten === false) {
|
||||
steps.push(deferredWrapperInstructions(event, scaffold, scriptsPath));
|
||||
} else if (scaffold) {
|
||||
steps.push(`The wrapper is already written into ${scaffold.file}. Splice preview CSS plus all ${event.count} variants at line ${scaffold.insertLine} in ONE edit, following the returned cssAuthoring contract (styleTag, selector strategy, forbidden patterns). Each variant div holds exactly ONE top-level element (same tag as the original); first visible, others display: none.`);
|
||||
} else {
|
||||
steps.push(`Preflight could not scaffold${event.scaffoldError ? ` (${event.scaffoldError})` : ''}. Run node ${scriptsPath}/live-wrap.mjs --id ${id} --count ${event.count} --element-id "${event.element?.id || ''}" --classes "${(event.element?.classes || []).join(',')}" --tag "${event.element?.tagName || ''}" --text "<first ~80 chars of the picked element's textContent>". Keep the flags separate; --text disambiguates repeated siblings. On a fallback error, follow live.md's Handle fallback.`);
|
||||
}
|
||||
|
||||
steps.push(event.action && event.action !== 'impeccable'
|
||||
? `Action is "${event.action}": read reference/${event.action}.md before planning; its MUST params are non-negotiable. ${PLAN_POINTER}`
|
||||
: `Freeform action: work from SKILL.md rules plus craft-floor.md; no sub-command file. ${PLAN_POINTER}`);
|
||||
|
||||
steps.push(`When all ${event.count} variants are delivered: ${replyCmd(scriptsPath, id, 'done --file <project-root-relative path you wrote>')}. Then poll again. If generation fails after the browser flipped to GENERATING, reply --reply ${id} error "Short reason" so the bar resets (never live-accept --discard for this).`);
|
||||
|
||||
return steps.map((s, i) => `${i + 1}. ${s}`).join('\n');
|
||||
}
|
||||
|
||||
function svelteComponentInstructions(event, scaffold, scriptsPath) {
|
||||
const dir = scaffold.componentDir;
|
||||
const count = event.count;
|
||||
return `Svelte component preview. EDIT the existing stubs ${dir}/v1.svelte ... v${count}.svelte in place; never delete or recreate them; do not read them back (the prop-substituted markup is in scaffold.componentStubMarkup). Keep the stub's control flow ({#each}, {#if}) and propContract prop names exactly; never flatten a loop into literal items. The stub <style> is seeded with the source rules that style the selection; restyle or delete freely, and know that any seeded rule you do not re-declare is REMOVED from source on accept (the preview never applied it). ALL your CSS goes inside that ONE existing <style> block: Svelte forbids a second top-level style element, and a publish with a non-compiling variant is bounced back to you with file and line. Semantic class selectors only: no @scope, no data-impeccable-* attributes. Params go in ${dir}/params.json keyed by variant number (never an attribute); author knob CSS against var(--p-<id>, default) and :global([data-p-<id>="..."]). Reply with --file ${scaffold.file}. Accept later merges everything into ${scaffold.sourceFile} mechanically; you have no post-accept cleanup.`;
|
||||
}
|
||||
|
||||
function deferredWrapperInstructions(event, scaffold, scriptsPath) {
|
||||
const insertNote = Number(scaffold.replaceEndLine) < Number(scaffold.replaceStartLine)
|
||||
? ` (replaceEndLine < replaceStartLine: this is an INSERTION at line ${scaffold.replaceStartLine}; remove nothing)`
|
||||
: '';
|
||||
return `The wrapper is NOT in source yet. In ONE edit to ${scaffold.file}: splice preview CSS plus all ${event.count} variants into scaffold.wrapperBlock at the "Variants: insert below this line" marker, then replace lines ${scaffold.replaceStartLine}-${scaffold.replaceEndLine}${insertNote} with the result. Two separate writes reload the framework mid-publish and strand the browser at 0/N. Author CSS per the returned cssAuthoring contract; each variant div holds exactly ONE top-level element (same tag as the original); first visible, others display: none. On JSX/TSX wrap the <style> content in a template literal and use className / style={{...}}.`;
|
||||
}
|
||||
|
||||
function insertScaffoldInstructions(event, scriptsPath) {
|
||||
const scaffold = event.scaffold;
|
||||
const base = `Insert mode: net-new content sized around ${event.placeholder?.width || '?'}x${event.placeholder?.height || '?'} at the chosen anchor; load craft-floor.md before writing net-new markup.`;
|
||||
if (scaffold?.previewMode === 'svelte-component') {
|
||||
return `${base} Write each inserted variant as a single-root Svelte component under ${scaffold.componentDir} (no data-impeccable-* attributes, CSS in each component's <style>). Never edit the route during generation; reply with --file ${scaffold.file}.`;
|
||||
}
|
||||
if (scaffold && scaffold.sourceWritten === false) {
|
||||
return `${base} Splice your variants into scaffold.wrapperBlock at the marker and insert the result at line ${scaffold.replaceStartLine} of ${scaffold.file} in ONE edit.`;
|
||||
}
|
||||
return `${base} If no scaffold payload is present, run node ${scriptsPath}/live-insert.mjs --id ${event.id} --count ${event.count} --position ${event.insert?.position || 'after'} with the anchor flags from event.insert.anchor, then splice variants at the returned insertLine.`;
|
||||
}
|
||||
|
||||
function acceptInstructions(event, scriptsPath) {
|
||||
const result = event._acceptResult || {};
|
||||
const ackOk = event._completionAck?.ok === true;
|
||||
const prefix = ackOk ? '' : `Completion was NOT acknowledged: run node ${scriptsPath}/live-status.mjs, finish any cleanup, then node ${scriptsPath}/live-complete.mjs --id ${event.id}. `;
|
||||
|
||||
if (result.handled === true && result.carbonize === true) {
|
||||
return `${prefix}Carbonize cleanup is REQUIRED now, before the next poll, in ${result.file}: (1) locate the impeccable-carbonize-start/end block and read the impeccable-param-values comment; (2) move the CSS rules into the stylesheet that owns this area; (3) bake params while rewriting selectors (@scope wrappers to semantic classes, keep only the chosen data-p branch, substitute range literals); (4) unwrap the accepted content and drop every data-impeccable-* / data-p-* attribute; (5) delete the inline <style>, the param-values comment, and both markers plus dead @scope rules. Then run node ${scriptsPath}/live-complete.mjs --id ${event.id} and verify phase "completed"; it refuses with source_dirty while leftovers remain. Poll again only after that.`;
|
||||
}
|
||||
if (result.handled === true) {
|
||||
return `${prefix}Accept was merged into source mechanically; nothing to clean up. Poll again.`;
|
||||
}
|
||||
if (result.mode === 'fallback') {
|
||||
return `${prefix}The session lived in a generated file, so accept refused to persist there. Write the accepted variant into the true source you identified during Handle fallback, remove the temporary wrapper from the served file, then poll again.`;
|
||||
}
|
||||
if (result.mode === 'error') {
|
||||
if (result.error === 'source_locked') {
|
||||
return `${prefix}The source file is briefly locked by a publisher. Re-run the exact same live-accept.mjs command (idempotent); do NOT hand-edit the file, and do not poll past this.`;
|
||||
}
|
||||
if (result.error === 'accept_receipt_conflict') {
|
||||
return `${prefix}This session already resolved as ${result.priorOperation || 'a prior operation'}; do not edit anything. Run node ${scriptsPath}/live-status.mjs and tell the user what the session resolved to.`;
|
||||
}
|
||||
return `${prefix}Accept failed: ${result.error || 'unknown error'}. Source was not touched; do not hand-edit. Run node ${scriptsPath}/live-status.mjs before continuing.`;
|
||||
}
|
||||
return `${prefix}No mechanical accept result; read ${result.file || 'the session source file'}, find the impeccable markers, and finish the merge by hand. Poll again after.`;
|
||||
}
|
||||
|
||||
/** Boot instructions attached to live.mjs's success payload. */
|
||||
export function bootInstructions({ scriptsPath = '{{scripts_path}}' } = {}) {
|
||||
return `Open the app URL that serves a pageFiles entry (never serverPort; that is the helper). Then start the poll loop per your harness policy in live.md and re-run ${pollCmd(scriptsPath)} immediately after every event or reply. Every event carries _instructions: follow them; they are the authoritative next step with real ids and paths filled in. A poll that is running is a poll you are SERVICING: never announce you are waiting and idle your turn; stay on the exec session until it returns an event, and never end a turn while a poll is outstanding.`;
|
||||
}
|
||||
@@ -0,0 +1,508 @@
|
||||
/**
|
||||
* Live root resolution: the single place that decides which directories a live
|
||||
* session operates on. Every live entry script resolves this once at startup
|
||||
* (see enterLiveRoot) instead of trusting its ambient cwd, which is how a
|
||||
* `cd` used to silently fork the whole system into a second, empty project.
|
||||
*
|
||||
* Four distinct roots travel together as one manifest:
|
||||
*
|
||||
* appRoot what the dev server serves; where live session state,
|
||||
* injected adapters, and preview modules live.
|
||||
* repoRoot the git boundary (falls back to appRoot outside git).
|
||||
* contextRoot the nearest directory from appRoot up to repoRoot carrying
|
||||
* PRODUCT.md / DESIGN.md (canonical spot or a fallback dir).
|
||||
* sessionRoot <appRoot>/.impeccable/live — durable live state.
|
||||
*
|
||||
* appRoot detection keys on dev-server config presence (vite/svelte/next/
|
||||
* astro/nuxt/... config files), not on monorepo brand markers. A nested
|
||||
* website/ with vite.config.js wins over a repo root that merely has a
|
||||
* package.json. Workspace declarations are one input, not the gatekeeper.
|
||||
*
|
||||
* The resolved manifest is persisted at <appRoot>/.impeccable/live/roots.json
|
||||
* plus a pointer at <repoRoot>/.impeccable/live/app-root.json when the two
|
||||
* differ, so a helper invoked from anywhere inside the repo finds the same
|
||||
* roots the boot decided on. When several apps in one repo run live, the
|
||||
* pointer follows the most recent boot; per-app roots.json files stay put.
|
||||
*/
|
||||
import fs from 'node:fs';
|
||||
import os from 'node:os';
|
||||
import path from 'node:path';
|
||||
import { execFileSync } from 'node:child_process';
|
||||
import { resolveProjectRoot } from '../context.mjs';
|
||||
|
||||
const ROOTS_MANIFEST_VERSION = 1;
|
||||
const ROOTS_FILE = 'roots.json';
|
||||
const POINTER_FILE = 'app-root.json';
|
||||
|
||||
const PRODUCT_NAMES = ['PRODUCT.md', 'Product.md', 'product.md'];
|
||||
const DESIGN_NAMES = ['DESIGN.md', 'Design.md', 'design.md'];
|
||||
const CONTEXT_FALLBACK_DIRS = ['.agents/context', 'docs'];
|
||||
|
||||
// Presence of any of these marks a directory as a dev-served app root.
|
||||
const DEV_CONFIG_MARKERS = [
|
||||
'vite.config.js', 'vite.config.ts', 'vite.config.mjs', 'vite.config.mts', 'vite.config.cjs',
|
||||
'svelte.config.js', 'svelte.config.mjs', 'svelte.config.ts',
|
||||
'next.config.js', 'next.config.mjs', 'next.config.ts',
|
||||
'astro.config.mjs', 'astro.config.js', 'astro.config.ts', 'astro.config.cjs',
|
||||
'nuxt.config.ts', 'nuxt.config.js', 'nuxt.config.mjs',
|
||||
'remix.config.js', 'react-router.config.ts',
|
||||
'angular.json',
|
||||
'webpack.config.js', 'webpack.config.ts',
|
||||
];
|
||||
|
||||
const CANDIDATE_SCAN_IGNORED = new Set([
|
||||
'node_modules', '.git', 'dist', 'build', 'coverage', 'vendor', 'vendors',
|
||||
'.next', '.nuxt', '.svelte-kit', '.astro', '.turbo', '.cache', '.vercel',
|
||||
]);
|
||||
const CANDIDATE_SCAN_DEPTH = 2;
|
||||
|
||||
function exists(p) {
|
||||
try { fs.statSync(p); return true; } catch { return false; }
|
||||
}
|
||||
|
||||
function isDir(p) {
|
||||
try { return fs.statSync(p).isDirectory(); } catch { return false; }
|
||||
}
|
||||
|
||||
function firstExisting(dir, names) {
|
||||
for (const name of names) {
|
||||
const abs = path.join(dir, name);
|
||||
if (exists(abs)) return abs;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function hasDevConfig(dir) {
|
||||
if (DEV_CONFIG_MARKERS.some((name) => exists(path.join(dir, name)))) return true;
|
||||
// A plain Vite app can run with zero config: index.html + package.json.
|
||||
return exists(path.join(dir, 'index.html')) && exists(path.join(dir, 'package.json'));
|
||||
}
|
||||
|
||||
function isAppRoot(dir) {
|
||||
// A directory already configured for live IS an app root, dev config or not
|
||||
// (plain static multi-page projects have no bundler config).
|
||||
return hasDevConfig(dir) || exists(path.join(dir, '.impeccable', 'live', 'config.json'));
|
||||
}
|
||||
|
||||
function findContextFile(dir, names) {
|
||||
const direct = firstExisting(dir, names);
|
||||
if (direct) return direct;
|
||||
for (const rel of CONTEXT_FALLBACK_DIRS) {
|
||||
const nested = firstExisting(path.join(dir, rel), names);
|
||||
if (nested) return nested;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
export function findGitRoot(startDir) {
|
||||
let dir = path.resolve(startDir);
|
||||
const home = path.resolve(os.homedir());
|
||||
while (true) {
|
||||
if (dir === home) return null;
|
||||
if (exists(path.join(dir, '.git'))) return dir;
|
||||
const parent = path.dirname(dir);
|
||||
if (parent === dir) return null;
|
||||
dir = parent;
|
||||
}
|
||||
}
|
||||
|
||||
function walkUp(startDir, upperBound, visit) {
|
||||
let dir = path.resolve(startDir);
|
||||
const stop = path.resolve(upperBound);
|
||||
const home = path.resolve(os.homedir());
|
||||
while (true) {
|
||||
if (dir === home) return null;
|
||||
const hit = visit(dir);
|
||||
if (hit) return hit;
|
||||
if (dir === stop) return null;
|
||||
const parent = path.dirname(dir);
|
||||
if (parent === dir) return null;
|
||||
dir = parent;
|
||||
}
|
||||
}
|
||||
|
||||
function insideOrEqual(candidate, root) {
|
||||
const rel = path.relative(path.resolve(root), path.resolve(candidate));
|
||||
return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
|
||||
}
|
||||
|
||||
/**
|
||||
* Scan downward (bounded depth) for directories carrying a dev-server config.
|
||||
* Used when live boots from a directory that is not itself an app root and no
|
||||
* --target narrows the choice: one candidate is auto-picked, several become a
|
||||
* selection prompt.
|
||||
*/
|
||||
export function discoverAppCandidates(rootDir, depth = CANDIDATE_SCAN_DEPTH) {
|
||||
const found = [];
|
||||
const scan = (dir, remaining) => {
|
||||
let entries;
|
||||
try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
|
||||
for (const entry of entries) {
|
||||
if (!entry.isDirectory()) continue;
|
||||
if (entry.name.startsWith('.') || CANDIDATE_SCAN_IGNORED.has(entry.name)) continue;
|
||||
const abs = path.join(dir, entry.name);
|
||||
// Same criterion as the upward walk (isAppRoot): a live-configured
|
||||
// plain-static site with no bundler markers is still an app, and
|
||||
// missing it here would silently fall back to the wrong root.
|
||||
if (isAppRoot(abs)) {
|
||||
found.push(abs);
|
||||
continue; // nested apps below an app root are that app's business
|
||||
}
|
||||
if (remaining > 1) scan(abs, remaining - 1);
|
||||
}
|
||||
};
|
||||
scan(path.resolve(rootDir), depth);
|
||||
return found.sort();
|
||||
}
|
||||
|
||||
/**
|
||||
* Fresh root resolution. Never reads a persisted manifest.
|
||||
*
|
||||
* Returns { manifest } on success or { selection } when several candidate
|
||||
* apps exist and nothing disambiguates.
|
||||
*/
|
||||
export function resolveRoots({ cwd = process.cwd(), targetPath = null } = {}) {
|
||||
const absCwd = path.resolve(cwd);
|
||||
const absTarget = targetPath
|
||||
? (path.isAbsolute(targetPath) ? targetPath : path.resolve(absCwd, targetPath))
|
||||
: null;
|
||||
const targetDir = absTarget
|
||||
? (isDir(absTarget) ? absTarget : path.dirname(absTarget))
|
||||
: absCwd;
|
||||
|
||||
// The walk bound must be an ancestor of the target: a git root found from
|
||||
// the CWD is only usable when the target actually lives inside it,
|
||||
// otherwise the walk would climb out of both trees.
|
||||
const targetGitRoot = findGitRoot(targetDir);
|
||||
const cwdGitRoot = targetGitRoot ? null : findGitRoot(absCwd);
|
||||
const repoRoot = targetGitRoot
|
||||
|| (cwdGitRoot && insideOrEqual(targetDir, cwdGitRoot) ? cwdGitRoot : null);
|
||||
// Without a git boundary, never ascend above the starting directory: the
|
||||
// filesystem above an unversioned project is not ours to interpret.
|
||||
const upperBound = repoRoot || targetDir;
|
||||
|
||||
// The workspace-aware legacy resolution (context.mjs) still decides two
|
||||
// things: the fallback when no app marker exists, and how far the marker
|
||||
// walk may ascend when an explicit target selected a workspace child. A
|
||||
// root-level live config must never shadow a child the target picked.
|
||||
const legacyRoot = resolveProjectRoot(absCwd, absTarget ? { targetPath: absTarget } : {});
|
||||
const markerBound = absTarget && insideOrEqual(targetDir, legacyRoot) && insideOrEqual(legacyRoot, upperBound)
|
||||
? legacyRoot
|
||||
: upperBound;
|
||||
|
||||
let appRoot = walkUp(targetDir, markerBound, (dir) => (isAppRoot(dir) ? dir : null));
|
||||
let resolvedFrom = appRoot
|
||||
? (absTarget ? `target:${path.relative(absCwd, absTarget) || '.'}` : 'cwd')
|
||||
: null;
|
||||
|
||||
if (!appRoot && !absTarget) {
|
||||
const candidates = discoverAppCandidates(absCwd);
|
||||
if (candidates.length === 1) {
|
||||
appRoot = candidates[0];
|
||||
resolvedFrom = `candidate:${path.relative(absCwd, appRoot)}`;
|
||||
} else if (candidates.length > 1) {
|
||||
return {
|
||||
selection: {
|
||||
candidates: candidates.map((abs) => ({
|
||||
name: path.basename(abs),
|
||||
path: path.relative(absCwd, abs).split(path.sep).join('/'),
|
||||
})),
|
||||
},
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
if (!appRoot) {
|
||||
// No app marker anywhere: defer to the workspace-aware legacy resolution
|
||||
// (workspace child for a targeted monorepo path, cwd otherwise). Never
|
||||
// adopt an arbitrary ancestor just because it has a package.json, and
|
||||
// never adopt a root that does not even contain the target.
|
||||
appRoot = insideOrEqual(targetDir, legacyRoot) ? legacyRoot : targetDir;
|
||||
resolvedFrom = 'fallback';
|
||||
}
|
||||
|
||||
const effectiveRepoRoot = repoRoot && insideOrEqual(appRoot, repoRoot) ? repoRoot : appRoot;
|
||||
|
||||
// Each context file resolves independently: a child app may carry its own
|
||||
// PRODUCT.md while inheriting DESIGN.md from the repo root (or vice versa).
|
||||
const productPath = walkUp(appRoot, effectiveRepoRoot, (dir) => findContextFile(dir, PRODUCT_NAMES));
|
||||
const designPath = walkUp(appRoot, effectiveRepoRoot, (dir) => findContextFile(dir, DESIGN_NAMES));
|
||||
const contextRoot = productPath
|
||||
? path.dirname(productPath)
|
||||
: designPath
|
||||
? path.dirname(designPath)
|
||||
: null;
|
||||
|
||||
return {
|
||||
manifest: {
|
||||
version: ROOTS_MANIFEST_VERSION,
|
||||
appRoot,
|
||||
repoRoot: effectiveRepoRoot,
|
||||
contextRoot,
|
||||
sessionRoot: path.join(appRoot, '.impeccable', 'live'),
|
||||
productPath,
|
||||
designPath,
|
||||
resolvedFrom,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function rootsFilePath(appRoot) {
|
||||
return path.join(appRoot, '.impeccable', 'live', ROOTS_FILE);
|
||||
}
|
||||
|
||||
function pointerFilePath(repoRoot) {
|
||||
return path.join(repoRoot, '.impeccable', 'live', POINTER_FILE);
|
||||
}
|
||||
|
||||
export function writeRootsManifest(manifest) {
|
||||
const file = rootsFilePath(manifest.appRoot);
|
||||
fs.mkdirSync(path.dirname(file), { recursive: true });
|
||||
fs.writeFileSync(file, JSON.stringify(manifest, null, 2));
|
||||
if (path.resolve(manifest.repoRoot) !== path.resolve(manifest.appRoot)) {
|
||||
const pointer = pointerFilePath(manifest.repoRoot);
|
||||
fs.mkdirSync(path.dirname(pointer), { recursive: true });
|
||||
// The pointer records EVERY app that has booted live in this repo, most
|
||||
// recent first. A single last-boot-wins value made a helper run from the
|
||||
// repo root silently target whichever app booted last, even while an
|
||||
// earlier app's session was the one still live.
|
||||
const entries = readPointerEntries(manifest.repoRoot)
|
||||
.filter((entry) => path.resolve(entry.appRoot) !== path.resolve(manifest.appRoot));
|
||||
entries.unshift({ appRoot: manifest.appRoot, bootedAt: new Date().toISOString() });
|
||||
fs.writeFileSync(pointer, JSON.stringify({ version: 2, appRoots: entries }));
|
||||
}
|
||||
return file;
|
||||
}
|
||||
|
||||
function readPointerEntries(repoRoot) {
|
||||
try {
|
||||
const raw = JSON.parse(fs.readFileSync(pointerFilePath(repoRoot), 'utf-8'));
|
||||
if (Array.isArray(raw?.appRoots)) {
|
||||
return raw.appRoots.filter((entry) => entry && typeof entry.appRoot === 'string');
|
||||
}
|
||||
// v1 shape: a single { appRoot } value.
|
||||
if (raw && typeof raw.appRoot === 'string') return [{ appRoot: raw.appRoot }];
|
||||
return [];
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* True when the app's live helper server is recorded and its pid is alive.
|
||||
* A liveness signal alone misclassifies a REUSED pid (helper died without
|
||||
* removing server.json, the OS handed the pid to something else), so the
|
||||
* process's command line must also look like a node process; that removes
|
||||
* reuse by arbitrary processes. A pid reused by another node process remains
|
||||
* a residual false positive, which the multi-app warning and --target
|
||||
* escape hatch cover.
|
||||
*/
|
||||
function hasLiveServer(appRoot) {
|
||||
let pid;
|
||||
let port;
|
||||
let token;
|
||||
try {
|
||||
const info = JSON.parse(fs.readFileSync(path.join(appRoot, '.impeccable', 'live', 'server.json'), 'utf-8'));
|
||||
if (!info || typeof info.pid !== 'number') return false;
|
||||
pid = info.pid;
|
||||
port = Number(info.port);
|
||||
token = typeof info.token === 'string' ? info.token : null;
|
||||
process.kill(pid, 0);
|
||||
} catch (err) {
|
||||
// EPERM: the process exists but is not signalable by this user.
|
||||
if (err?.code !== 'EPERM') return false;
|
||||
}
|
||||
// Liveness alone misclassifies a REUSED pid, and a bare TCP connect
|
||||
// misclassifies a coincidental listener on a reused port. The decisive
|
||||
// signal is IDENTITY: the helper answers its authenticated /status
|
||||
// endpoint with the token server.json records; nothing else on that port
|
||||
// can. The probe is a spawned node one-liner so it works identically on
|
||||
// every platform.
|
||||
if (Number.isInteger(port) && port > 0 && token) {
|
||||
try {
|
||||
execFileSync(process.execPath, ['-e', [
|
||||
"const req = require('node:http').get({ host: '127.0.0.1', port: Number(process.argv[1]), path: '/status?token=' + encodeURIComponent(process.argv[2]), timeout: 1200 }, (res) => { res.resume(); process.exit(res.statusCode === 200 ? 0 : 1); });",
|
||||
"req.on('timeout', () => { req.destroy(); process.exit(1); });",
|
||||
"req.on('error', () => process.exit(1));",
|
||||
].join(''), String(port), token], { timeout: 4000, stdio: 'ignore' });
|
||||
return true;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
// Every server.json this codebase has ever written records port + token
|
||||
// (see writeLiveServerInfo). A record without them is malformed or foreign
|
||||
// and cannot be authenticated, so it does not count as a live helper;
|
||||
// resolution falls to the durable-session tier, which is the correct
|
||||
// recovery path for a stopped or crashed helper anyway.
|
||||
return false;
|
||||
}
|
||||
|
||||
const TERMINAL_SESSION_PHASES = new Set(['completed', 'discarded']);
|
||||
|
||||
/**
|
||||
* True when the app's durable session store holds a session that is not
|
||||
* terminal. With every helper server stopped, this is what distinguishes
|
||||
* "the app whose interrupted session the user is trying to recover" from an
|
||||
* app that merely booted more recently.
|
||||
*/
|
||||
function hasActiveDurableSession(appRoot) {
|
||||
const dir = path.join(appRoot, '.impeccable', 'live', 'sessions');
|
||||
let entries;
|
||||
try {
|
||||
entries = fs.readdirSync(dir);
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
for (const name of entries) {
|
||||
if (!name.endsWith('.snapshot.json')) continue;
|
||||
try {
|
||||
const snapshot = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf-8'));
|
||||
if (snapshot?.phase && !TERMINAL_SESSION_PHASES.has(snapshot.phase)) return true;
|
||||
} catch { /* skip unreadable snapshots */ }
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
function readManifestAt(appRoot) {
|
||||
try {
|
||||
const raw = JSON.parse(fs.readFileSync(rootsFilePath(appRoot), 'utf-8'));
|
||||
if (!raw || typeof raw.appRoot !== 'string') return null;
|
||||
// A manifest is only trusted where it claims to live; anything else is a
|
||||
// copied or stale file.
|
||||
if (path.resolve(raw.appRoot) !== path.resolve(appRoot)) return null;
|
||||
return raw;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve the roots for the live session governing `cwd`, preferring a
|
||||
* persisted manifest (written by the boot) over fresh detection:
|
||||
*
|
||||
* 1. Walk up from cwd looking for .impeccable/live/roots.json.
|
||||
* 2. At the git root, follow .impeccable/live/app-root.json to the app.
|
||||
* 3. Fresh resolveRoots().
|
||||
*
|
||||
* Fresh results are NOT persisted here; only the boot (live.mjs / server
|
||||
* startup) writes manifests, so ad-hoc helper invocations cannot mint
|
||||
* conflicting truth.
|
||||
*/
|
||||
export function resolveLiveRoots(cwd = process.cwd(), { targetPath = null } = {}) {
|
||||
const absCwd = path.resolve(cwd);
|
||||
|
||||
if (!targetPath) {
|
||||
const persisted = walkUp(absCwd, findGitRoot(absCwd) || absCwd, (dir) => readManifestAt(dir));
|
||||
if (persisted) return { manifest: persisted, source: 'persisted' };
|
||||
|
||||
const gitRoot = findGitRoot(absCwd);
|
||||
if (gitRoot) {
|
||||
// Several apps in one repo may have booted live. Preference order:
|
||||
// a running helper server, then an app whose durable store still holds
|
||||
// a non-terminal session (the stopped session the user is recovering),
|
||||
// then the most recent boot. A stale pointer entry must never redirect
|
||||
// status/poll/accept onto the wrong app's session store.
|
||||
const candidates = readPointerEntries(gitRoot)
|
||||
.map((entry) => readManifestAt(entry.appRoot))
|
||||
.filter(Boolean);
|
||||
if (candidates.length > 0) {
|
||||
const liveApps = candidates.filter((manifest) => hasLiveServer(manifest.appRoot));
|
||||
const recoveringApps = liveApps.length > 0
|
||||
? liveApps
|
||||
: candidates.filter((manifest) => hasActiveDurableSession(manifest.appRoot));
|
||||
const tier = recoveringApps.length > 0 ? recoveringApps : candidates;
|
||||
// Multiple apps qualifying at the same tier is inherent ambiguity:
|
||||
// intent is unknowable from the repo root. The choice stays
|
||||
// deterministic (most recent boot first), but it must be LOUD, not
|
||||
// silent, so the agent can re-anchor when it meant the other app.
|
||||
if (tier.length > 1) {
|
||||
const chosen = tier[0].appRoot;
|
||||
const others = tier.slice(1).map((manifest) => manifest.appRoot).join(', ');
|
||||
process.stderr.write(
|
||||
`[impeccable live] Multiple apps in this repo have live state; using ${chosen}. `
|
||||
+ `Other candidate(s): ${others}. Run from the app directory (or pass --target) to address a specific app.\n`,
|
||||
);
|
||||
}
|
||||
return { manifest: tier[0], source: 'pointer' };
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const fresh = resolveRoots({ cwd: absCwd, targetPath });
|
||||
if (fresh.selection) return { selection: fresh.selection, source: 'fresh' };
|
||||
return { manifest: fresh.manifest, source: 'fresh' };
|
||||
}
|
||||
|
||||
/**
|
||||
* Consume a `--target <path>` / `--target=<path>` pair from an argv array,
|
||||
* returning the value and removing the tokens so downstream flag parsers
|
||||
* (which do not know the option) never see them.
|
||||
*/
|
||||
export function consumeTargetArg(argv = process.argv) {
|
||||
for (let i = 0; i < argv.length; i++) {
|
||||
const arg = argv[i];
|
||||
if (arg === '--target') {
|
||||
const value = argv[i + 1];
|
||||
// A --target with no usable value must not degrade into implicit root
|
||||
// selection: these helpers mutate session state, and "the most recent
|
||||
// app" is exactly what the caller was trying NOT to get.
|
||||
if (typeof value !== 'string' || value === '' || value.startsWith('--')) {
|
||||
throw new Error('--target requires a path value (use --target <path> or --target=<path>)');
|
||||
}
|
||||
argv.splice(i, 2);
|
||||
return value;
|
||||
}
|
||||
if (typeof arg === 'string' && arg.startsWith('--target=')) {
|
||||
const value = arg.slice('--target='.length);
|
||||
if (value === '') {
|
||||
throw new Error('--target requires a path value (use --target <path> or --target=<path>)');
|
||||
}
|
||||
argv.splice(i, 1);
|
||||
return value;
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Entry-point guard for live CLI scripts: resolve the governing roots and
|
||||
* make appRoot the process cwd so every downstream path derivation agrees
|
||||
* with the boot. An explicit `--target <path>` on the helper's command line
|
||||
* overrides pointer resolution, which is what disambiguates a repo with
|
||||
* several live apps (the multi-app warning names this escape hatch, so it
|
||||
* has to actually work on every helper). Returns the manifest. On selection
|
||||
* ambiguity it stays in the current directory (the boot flow handles
|
||||
* prompting); a malformed --target exits with an error instead of silently
|
||||
* falling back to implicit selection, which could mutate the wrong app.
|
||||
*/
|
||||
export function enterLiveRoot(cwd = process.cwd()) {
|
||||
let targetPath;
|
||||
try {
|
||||
targetPath = consumeTargetArg(process.argv);
|
||||
} catch (err) {
|
||||
console.error(`[impeccable live] ${err.message}`);
|
||||
process.exit(1);
|
||||
}
|
||||
const resolved = resolveLiveRoots(cwd, targetPath ? { targetPath } : {});
|
||||
if (!resolved.manifest) return null;
|
||||
const appRoot = resolved.manifest.appRoot;
|
||||
if (path.resolve(cwd) !== path.resolve(appRoot)) {
|
||||
// Failing to land on the resolved appRoot must be fatal: a helper that
|
||||
// silently keeps its ambient cwd derives server, session, and source
|
||||
// paths from a different project and mutates the wrong state. A manifest
|
||||
// pointing at a deleted directory is stale ambient truth, not a reason
|
||||
// to guess.
|
||||
if (!isDir(appRoot)) {
|
||||
console.error(`[impeccable live] resolved app root does not exist: ${appRoot} (stale roots manifest? re-run the live boot, or pass --target <path>)`);
|
||||
process.exit(1);
|
||||
}
|
||||
try {
|
||||
process.chdir(appRoot);
|
||||
} catch (err) {
|
||||
console.error(`[impeccable live] could not enter app root ${appRoot}: ${err.message}`);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
return resolved.manifest;
|
||||
}
|
||||
@@ -1,26 +1,40 @@
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { getLegacyLiveSessionsDir, getLiveSessionsDir, safeSessionId } from '../lib/impeccable-paths.mjs';
|
||||
import { COMPLETED_SESSION_PHASES, GENERATION_FENCED_SESSION_PHASES } from './vocabulary.mjs';
|
||||
|
||||
const COMPLETED_PHASES = new Set(['completed', 'discarded']);
|
||||
export const GENERATION_FENCED_PHASES = new Set([
|
||||
'accept_requested',
|
||||
'discard_requested',
|
||||
'carbonize_required',
|
||||
'completed',
|
||||
'discarded',
|
||||
]);
|
||||
const COMPLETED_PHASES = new Set(COMPLETED_SESSION_PHASES);
|
||||
export const GENERATION_FENCED_PHASES = new Set(GENERATION_FENCED_SESSION_PHASES);
|
||||
|
||||
// The snapshot file carries two bookkeeping fields the snapshot itself does not
|
||||
// own: how large the journal was when the snapshot was written, and the next
|
||||
// sequence number. Both are stripped before a snapshot is handed to a caller.
|
||||
// The byte count is what makes a cached snapshot verifiable — the journal is
|
||||
// append-only, so a matching size means no event has landed since.
|
||||
const META_JOURNAL_BYTES = '__journalBytes';
|
||||
const META_NEXT_SEQ = '__nextSeq';
|
||||
|
||||
// TODO(revision-unification): `checkpointRevision`, `browserCheckpointRevision`,
|
||||
// and `publicationCheckpointRevision` are three counters for two domains.
|
||||
// `checkpointRevision` is a compatibility mirror of the browser counter kept for
|
||||
// older readers. Collapsing them means changing what a resumed browser compares
|
||||
// its local revision against, so it belongs in a pass that owns resume ordering,
|
||||
// not in a caching change.
|
||||
|
||||
export function createLiveSessionStore({ cwd = process.cwd(), sessionId } = {}) {
|
||||
const rootDir = getLiveSessionsDir(cwd);
|
||||
const legacyRootDir = getLegacyLiveSessionsDir(cwd);
|
||||
fs.mkdirSync(rootDir, { recursive: true });
|
||||
|
||||
// No snapshot cache on purpose: appendEvent and getSnapshot both rebuild from
|
||||
// the journal so sequence numbers and phase fences never come from a stale
|
||||
// in-memory copy when the publisher/complete helpers append from another
|
||||
// process. A cache written but never read would grow per session for the
|
||||
// lifetime of the server without ever saving a rebuild.
|
||||
// Derived state per session, keyed by what the journal looked like when it was
|
||||
// derived. Publisher/complete helpers append from other processes, so the key
|
||||
// is the journal's own (path, size, mtime) rather than a trusted local write
|
||||
// count: an append this process did not make invalidates the entry and the
|
||||
// next read replays. Without the cache every append and every read replayed
|
||||
// the whole journal, which made a long session quadratic in its own length.
|
||||
/** @type {Map<string, { snapshot: object, nextSeq: number, journalPath: string, size: number, mtimeMs: number }>} */
|
||||
const derived = new Map();
|
||||
|
||||
function getReadableJournalPath(id) {
|
||||
const primary = getJournalPath(rootDir, id);
|
||||
if (fs.existsSync(primary)) return primary;
|
||||
@@ -29,42 +43,116 @@ export function createLiveSessionStore({ cwd = process.cwd(), sessionId } = {})
|
||||
return primary;
|
||||
}
|
||||
|
||||
/**
|
||||
* The current derived state for a session, from the in-memory cache when the
|
||||
* journal has not moved, from the snapshot file when that file is provably
|
||||
* current, and from a full replay otherwise.
|
||||
*/
|
||||
function readState(id, { allowSnapshotFile = true } = {}) {
|
||||
const journalPath = getReadableJournalPath(id);
|
||||
const stat = statOrNull(journalPath);
|
||||
const size = stat ? stat.size : -1;
|
||||
const mtimeMs = stat ? stat.mtimeMs : -1;
|
||||
|
||||
const cached = derived.get(id);
|
||||
if (cached && cached.journalPath === journalPath && cached.size === size && cached.mtimeMs === mtimeMs) {
|
||||
return cached;
|
||||
}
|
||||
|
||||
if (allowSnapshotFile && stat) {
|
||||
const hydrated = readSnapshotFile(getSnapshotPath(rootDir, id), id, size);
|
||||
if (hydrated) {
|
||||
const entry = { ...hydrated, journalPath, size, mtimeMs };
|
||||
derived.set(id, entry);
|
||||
return entry;
|
||||
}
|
||||
}
|
||||
|
||||
const rebuilt = rebuildSnapshotFromJournal(journalPath, id);
|
||||
const entry = { snapshot: rebuilt.snapshot, nextSeq: rebuilt.nextSeq, journalPath, size, mtimeMs };
|
||||
derived.set(id, entry);
|
||||
return entry;
|
||||
}
|
||||
|
||||
function persist(id, snapshot, nextSeq) {
|
||||
const snapshotPath = getSnapshotPath(rootDir, id);
|
||||
const journalPath = getReadableJournalPath(id);
|
||||
const stat = statOrNull(journalPath);
|
||||
writeSnapshot(snapshotPath, snapshot, { journalBytes: stat ? stat.size : -1, nextSeq });
|
||||
derived.set(id, {
|
||||
snapshot,
|
||||
nextSeq,
|
||||
journalPath,
|
||||
size: stat ? stat.size : -1,
|
||||
mtimeMs: stat ? stat.mtimeMs : -1,
|
||||
});
|
||||
}
|
||||
|
||||
return {
|
||||
rootDir,
|
||||
legacyRootDir,
|
||||
appendEvent(event) {
|
||||
const normalized = normalizeEvent(event, sessionId);
|
||||
const journalPath = getJournalPath(rootDir, normalized.id);
|
||||
const snapshotPath = getSnapshotPath(rootDir, normalized.id);
|
||||
const legacyJournalPath = getJournalPath(legacyRootDir, normalized.id);
|
||||
if (!fs.existsSync(journalPath) && fs.existsSync(legacyJournalPath)) {
|
||||
fs.copyFileSync(legacyJournalPath, journalPath);
|
||||
// The readable path just moved from legacy to primary; anything derived
|
||||
// against the old path describes a file this session no longer reads.
|
||||
derived.delete(normalized.id);
|
||||
}
|
||||
// Publisher/complete helpers can append from a separate process while
|
||||
// the server is alive. Rebuild here so sequence numbers and phase
|
||||
// fences never come from a stale in-memory cache.
|
||||
const prior = rebuildSnapshotFromJournal(getReadableJournalPath(normalized.id), normalized.id);
|
||||
const seq = prior.nextSeq;
|
||||
// Reuse the derived state when the journal has not changed under us, and
|
||||
// apply the new event on top of it. Correctness still comes from the
|
||||
// journal: any append from another process invalidates the entry above
|
||||
// and this replays before writing, so sequence numbers and phase fences
|
||||
// are never taken from a stale copy.
|
||||
const prior = readState(normalized.id);
|
||||
const entry = {
|
||||
seq,
|
||||
seq: prior.nextSeq,
|
||||
id: normalized.id,
|
||||
type: normalized.type,
|
||||
ts: new Date().toISOString(),
|
||||
event: normalized,
|
||||
};
|
||||
fs.appendFileSync(journalPath, JSON.stringify(entry) + '\n');
|
||||
const next = applyEvent(prior.snapshot, entry, prior.diagnostics);
|
||||
writeSnapshot(snapshotPath, next);
|
||||
const next = applyEvent(prior.snapshot, entry);
|
||||
persist(normalized.id, next, prior.nextSeq + 1);
|
||||
return next;
|
||||
},
|
||||
/**
|
||||
* True when a journal exists for the id in either root. appendEvent
|
||||
* CREATES a journal for any id it is handed, so callers that should only
|
||||
* ever touch existing sessions (browser checkpoints, mount acks) check
|
||||
* here first — otherwise a stale id from another project's browser
|
||||
* storage materializes a ghost session in this store.
|
||||
*/
|
||||
has(id) {
|
||||
if (!id || typeof id !== 'string') return false;
|
||||
return fs.existsSync(getJournalPath(rootDir, id))
|
||||
|| fs.existsSync(getJournalPath(legacyRootDir, id));
|
||||
},
|
||||
/**
|
||||
* Read-only. `live-status` and `live-resume` call this against a session a
|
||||
* running server owns; writing the snapshot file here made every read a
|
||||
* write and let a reader's replay of a half-written journal land on disk.
|
||||
* Snapshot files are written by appendEvent and by flush().
|
||||
*/
|
||||
getSnapshot(id = sessionId, opts = {}) {
|
||||
if (!id) throw new Error('session id required');
|
||||
const journalPath = getReadableJournalPath(id);
|
||||
const snapshotPath = getSnapshotPath(rootDir, id);
|
||||
const rebuilt = rebuildSnapshotFromJournal(journalPath, id);
|
||||
writeSnapshot(snapshotPath, rebuilt.snapshot);
|
||||
if (!opts.includeCompleted && COMPLETED_PHASES.has(rebuilt.snapshot.phase)) return null;
|
||||
return rebuilt.snapshot;
|
||||
const { snapshot } = readState(id);
|
||||
if (!opts.includeCompleted && COMPLETED_PHASES.has(snapshot.phase)) return null;
|
||||
return snapshot;
|
||||
},
|
||||
/**
|
||||
* Write the snapshot file for a session without appending an event. The
|
||||
* durable truth is the journal, so this only refreshes the read cache other
|
||||
* processes use; callers that need the state itself should use getSnapshot.
|
||||
*/
|
||||
flush(id = sessionId) {
|
||||
if (!id) throw new Error('session id required');
|
||||
const state = readState(id, { allowSnapshotFile: false });
|
||||
persist(id, state.snapshot, state.nextSeq);
|
||||
return state.snapshot;
|
||||
},
|
||||
listActiveSessions() {
|
||||
const ids = new Set();
|
||||
@@ -74,6 +162,9 @@ export function createLiveSessionStore({ cwd = process.cwd(), sessionId } = {})
|
||||
if (name.endsWith('.jsonl')) ids.add(name.slice(0, -'.jsonl'.length));
|
||||
}
|
||||
}
|
||||
// Each id goes through readState, so a session whose journal has not moved
|
||||
// since it was last derived costs a stat and nothing more. The server calls
|
||||
// this on every /status and on every SSE connect.
|
||||
return [...ids]
|
||||
.sort()
|
||||
.map((id) => this.getSnapshot(id))
|
||||
@@ -82,6 +173,39 @@ export function createLiveSessionStore({ cwd = process.cwd(), sessionId } = {})
|
||||
};
|
||||
}
|
||||
|
||||
function statOrNull(filePath) {
|
||||
try {
|
||||
return fs.statSync(filePath);
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Hydrate derived state from a snapshot file, but only when it provably
|
||||
* describes the journal as it stands right now. Anything short of an exact byte
|
||||
* match on an append-only file means events landed after the snapshot was
|
||||
* written, and the caller replays instead.
|
||||
*/
|
||||
function readSnapshotFile(snapshotPath, id, journalBytes) {
|
||||
let parsed;
|
||||
try {
|
||||
parsed = JSON.parse(fs.readFileSync(snapshotPath, 'utf-8'));
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
if (!parsed || typeof parsed !== 'object') return null;
|
||||
if (parsed[META_JOURNAL_BYTES] !== journalBytes) return null;
|
||||
if (!Number.isInteger(parsed[META_NEXT_SEQ])) return null;
|
||||
const nextSeq = parsed[META_NEXT_SEQ];
|
||||
delete parsed[META_JOURNAL_BYTES];
|
||||
delete parsed[META_NEXT_SEQ];
|
||||
// The journal owns identity; a snapshot file copied between session ids is
|
||||
// not a reason to answer with the wrong id.
|
||||
if (parsed.id !== id) return null;
|
||||
return { snapshot: { ...baseSnapshot(id), ...parsed }, nextSeq };
|
||||
}
|
||||
|
||||
function normalizeEvent(event, fallbackId) {
|
||||
if (!event || typeof event !== 'object') throw new Error('event object required');
|
||||
const id = event.id || fallbackId;
|
||||
@@ -127,11 +251,37 @@ function baseSnapshot(id) {
|
||||
generationCanceledAt: null,
|
||||
cancelReason: null,
|
||||
annotationArtifacts: [],
|
||||
// Render truth. `arrivedVariants` says what the agent published; these say
|
||||
// what the browser actually got on screen. They are kept alongside the
|
||||
// published counters rather than replacing them so older readers keep
|
||||
// working, but they are the only fields that answer "did the user ever see
|
||||
// a variant".
|
||||
mountedVariants: [],
|
||||
mountFailures: [],
|
||||
renderState: null,
|
||||
diagnostics: [],
|
||||
updatedAt: null,
|
||||
};
|
||||
}
|
||||
|
||||
// How many mount failures a session keeps. The card in the browser shows the
|
||||
// newest one; the agent needs enough history to spot a variant that fails
|
||||
// every republish, not the whole retry storm.
|
||||
const MOUNT_FAILURE_HISTORY = 5;
|
||||
|
||||
/**
|
||||
* `pending` = the agent published and nothing has acked yet, `mounted` = at
|
||||
* least one variant reached the DOM, `failed` = the browser reported failures
|
||||
* and nothing ever mounted. A single success outranks any number of failures:
|
||||
* the user is looking at something.
|
||||
*/
|
||||
function deriveRenderState(snapshot) {
|
||||
if (snapshot.mountedVariants.length > 0) return 'mounted';
|
||||
if (snapshot.mountFailures.length > 0) return 'failed';
|
||||
if (snapshot.generationCompletedAt) return 'pending';
|
||||
return null;
|
||||
}
|
||||
|
||||
function rebuildSnapshotFromJournal(journalPath, id) {
|
||||
let snapshot = baseSnapshot(id);
|
||||
const diagnostics = [];
|
||||
@@ -159,7 +309,7 @@ function rebuildSnapshotFromJournal(journalPath, id) {
|
||||
return { snapshot, diagnostics, nextSeq };
|
||||
}
|
||||
|
||||
function applyEvent(snapshot, entry, inheritedDiagnostics = []) {
|
||||
function applyEvent(snapshot, entry) {
|
||||
const event = entry.event || entry;
|
||||
const next = {
|
||||
...snapshot,
|
||||
@@ -168,14 +318,13 @@ function applyEvent(snapshot, entry, inheritedDiagnostics = []) {
|
||||
generationTimings: { ...(snapshot.generationTimings || {}) },
|
||||
variantPlan: snapshot.variantPlan || null,
|
||||
annotationArtifacts: [...(snapshot.annotationArtifacts || [])],
|
||||
mountedVariants: [...(snapshot.mountedVariants || [])],
|
||||
mountFailures: [...(snapshot.mountFailures || [])],
|
||||
renderState: snapshot.renderState ?? null,
|
||||
diagnostics: [...(snapshot.diagnostics || [])],
|
||||
updatedAt: entry.ts || new Date().toISOString(),
|
||||
};
|
||||
|
||||
if (inheritedDiagnostics.length && next.diagnostics.length === 0) {
|
||||
next.diagnostics = [...inheritedDiagnostics];
|
||||
}
|
||||
|
||||
switch (event.type) {
|
||||
case 'generate':
|
||||
next.phase = 'generate_requested';
|
||||
@@ -184,6 +333,11 @@ function applyEvent(snapshot, entry, inheritedDiagnostics = []) {
|
||||
next.pendingEventSeq = entry.seq ?? next.pendingEventSeq;
|
||||
next.pendingEvent = toPendingEvent(event);
|
||||
next.variantPlan = null;
|
||||
// A new cycle publishes new files: everything the browser told us about
|
||||
// the previous batch is now about modules that no longer exist.
|
||||
next.mountedVariants = [];
|
||||
next.mountFailures = [];
|
||||
next.renderState = null;
|
||||
if (event.screenshotPath) upsertArtifact(next.annotationArtifacts, { type: 'screenshot', path: event.screenshotPath });
|
||||
break;
|
||||
case 'variant_plan':
|
||||
@@ -238,7 +392,45 @@ function applyEvent(snapshot, entry, inheritedDiagnostics = []) {
|
||||
message: 'Accepted variant still has carbonize markers that must be folded into source CSS.',
|
||||
});
|
||||
}
|
||||
next.renderState = deriveRenderState(next);
|
||||
break;
|
||||
case 'variant_mounted': {
|
||||
const variant = Number(event.variant);
|
||||
if (!Number.isInteger(variant) || variant < 1) {
|
||||
next.diagnostics.push({ error: 'malformed_mount_ack', type: event.type, variant: event.variant ?? null });
|
||||
break;
|
||||
}
|
||||
if (!next.mountedVariants.includes(variant)) {
|
||||
next.mountedVariants = [...next.mountedVariants, variant].sort((a, b) => a - b);
|
||||
}
|
||||
next.renderState = deriveRenderState(next);
|
||||
break;
|
||||
}
|
||||
case 'variant_mount_failed': {
|
||||
const variant = Number(event.variant);
|
||||
if (!Number.isInteger(variant) || variant < 1) {
|
||||
next.diagnostics.push({ error: 'malformed_mount_ack', type: event.type, variant: event.variant ?? null });
|
||||
break;
|
||||
}
|
||||
next.mountFailures = [
|
||||
...next.mountFailures,
|
||||
{
|
||||
variant,
|
||||
url: typeof event.url === 'string' ? event.url : null,
|
||||
error: typeof event.error === 'string' ? event.error : null,
|
||||
at: event.at ?? (Date.parse(entry.ts || '') || Date.now()),
|
||||
},
|
||||
].slice(-MOUNT_FAILURE_HISTORY);
|
||||
next.renderState = deriveRenderState(next);
|
||||
// The failure needs an agent reply, so it must survive a helper
|
||||
// restart the same way a generate does. Never clobber a still-pending
|
||||
// generate: a progressive publish can fail an early mount while the
|
||||
// generate event itself is still leased.
|
||||
if (!next.pendingEvent) {
|
||||
next.pendingEvent = toPendingEvent(event);
|
||||
}
|
||||
break;
|
||||
}
|
||||
case 'checkpoint':
|
||||
if (next.generationCanceled || GENERATION_FENCED_PHASES.has(next.phase)) {
|
||||
next.diagnostics.push({ error: 'checkpoint_after_terminal_ignored', phase: event.phase ?? null, revision: event.revision ?? null });
|
||||
@@ -361,6 +553,11 @@ function upsertArtifact(artifacts, artifact) {
|
||||
}
|
||||
}
|
||||
|
||||
function writeSnapshot(snapshotPath, snapshot) {
|
||||
fs.writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2) + '\n');
|
||||
function writeSnapshot(snapshotPath, snapshot, meta) {
|
||||
const payload = {
|
||||
...snapshot,
|
||||
[META_JOURNAL_BYTES]: meta?.journalBytes ?? -1,
|
||||
[META_NEXT_SEQ]: meta?.nextSeq ?? 1,
|
||||
};
|
||||
fs.writeFileSync(snapshotPath, JSON.stringify(payload, null, 2) + '\n');
|
||||
}
|
||||
|
||||
@@ -0,0 +1,961 @@
|
||||
/**
|
||||
* AST-based Svelte scaffolding for live component previews.
|
||||
*
|
||||
* The scaffolder turns the selected block of a route's markup into a detached
|
||||
* preview component whose dynamic values arrive as props. The old
|
||||
* implementation matched `{...}` with a regex, which flattened control-flow
|
||||
* blocks ({#each}, {#if}) into scalar text props and shipped structurally
|
||||
* wrong previews. This module uses the app's own svelte compiler
|
||||
* (parse with modern: true) and replaces only expressions that are FREE,
|
||||
* i.e. reference identifiers not bound by an enclosing template scope:
|
||||
*
|
||||
* {#each stages as stage, i} stages -> collection prop (array)
|
||||
* <span>{stage.label}</span> bound -> left verbatim
|
||||
* {/each}
|
||||
* <p>{footerNote}</p> free -> text prop (string)
|
||||
*
|
||||
* Constructs that cannot work in a detached component (component tags whose
|
||||
* imports live in the route file, bind:/use: directives, await blocks,
|
||||
* render tags) mark the analysis unsupported; the caller falls back to
|
||||
* source-preview mode, which keeps the markup inside the route file where
|
||||
* those references still resolve. A wrong preview is worse than a plain one.
|
||||
*
|
||||
* The compiler is resolved from the APP's node_modules, never bundled: the
|
||||
* preview must be parsed by the same svelte version that will compile it.
|
||||
*/
|
||||
|
||||
import { createRequire } from 'node:module';
|
||||
import path from 'node:path';
|
||||
|
||||
const HANDLER_ATTR_RE = /^on[a-z]/;
|
||||
|
||||
/**
|
||||
* Resolve the app's svelte compiler synchronously (svelte 5 ships a CJS
|
||||
* compiler build, so createRequire works and the accept/scaffold pipeline
|
||||
* stays synchronous). Returns { parse, compile, VERSION } or null.
|
||||
*/
|
||||
export function loadSvelteCompiler(appRoot) {
|
||||
try {
|
||||
const req = createRequire(path.join(appRoot, 'package.json'));
|
||||
const mod = req('svelte/compiler');
|
||||
if (typeof mod.parse !== 'function') return null;
|
||||
const major = parseInt(String(mod.VERSION || '0'), 10);
|
||||
if (major < 5) return null; // detached mount() previews are svelte 5 only
|
||||
return { parse: mod.parse, compile: mod.compile, VERSION: mod.VERSION };
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// ESTree helpers
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Collect the root identifiers an ESTree expression reads. Walks generically;
|
||||
* skips non-computed member properties and non-computed/non-shorthand object
|
||||
* keys, which are names, not references.
|
||||
*/
|
||||
export function collectRootIdentifiers(node, out = new Set()) {
|
||||
if (!node || typeof node !== 'object') return out;
|
||||
if (Array.isArray(node)) {
|
||||
for (const item of node) collectRootIdentifiers(item, out);
|
||||
return out;
|
||||
}
|
||||
switch (node.type) {
|
||||
case 'Identifier':
|
||||
out.add(node.name);
|
||||
return out;
|
||||
case 'MemberExpression':
|
||||
collectRootIdentifiers(node.object, out);
|
||||
if (node.computed) collectRootIdentifiers(node.property, out);
|
||||
return out;
|
||||
case 'Property':
|
||||
if (node.computed) collectRootIdentifiers(node.key, out);
|
||||
collectRootIdentifiers(node.value, out);
|
||||
return out;
|
||||
case 'ArrowFunctionExpression':
|
||||
case 'FunctionExpression': {
|
||||
// Params shadow outer names inside the body.
|
||||
const bound = new Set();
|
||||
for (const param of node.params || []) collectPatternNames(param, bound);
|
||||
const inner = collectRootIdentifiers(node.body, new Set());
|
||||
for (const name of inner) if (!bound.has(name)) out.add(name);
|
||||
return out;
|
||||
}
|
||||
default: {
|
||||
for (const key of Object.keys(node)) {
|
||||
if (key === 'type' || key === 'start' || key === 'end' || key === 'loc' || key === 'range' || key === 'parent') continue;
|
||||
collectRootIdentifiers(node[key], out);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/** Collect names bound by a destructuring pattern (each contexts, const tags). */
|
||||
export function collectPatternNames(pattern, out = new Set()) {
|
||||
if (!pattern || typeof pattern !== 'object') return out;
|
||||
switch (pattern.type) {
|
||||
case 'Identifier':
|
||||
out.add(pattern.name);
|
||||
return out;
|
||||
case 'ObjectPattern':
|
||||
for (const prop of pattern.properties || []) {
|
||||
if (prop.type === 'RestElement') collectPatternNames(prop.argument, out);
|
||||
else collectPatternNames(prop.value, out);
|
||||
}
|
||||
return out;
|
||||
case 'ArrayPattern':
|
||||
for (const el of pattern.elements || []) if (el) collectPatternNames(el, out);
|
||||
return out;
|
||||
case 'AssignmentPattern':
|
||||
collectPatternNames(pattern.left, out);
|
||||
return out;
|
||||
case 'RestElement':
|
||||
collectPatternNames(pattern.argument, out);
|
||||
return out;
|
||||
default:
|
||||
return out;
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Template analysis
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
class Analysis {
|
||||
constructor(source) {
|
||||
this.source = source;
|
||||
this.replacements = []; // { start, end, prop } source ranges to swap
|
||||
this.contract = []; // [{ prop, expr, kind, ... }]
|
||||
this.byExpr = new Map(); // expr text -> contract entry
|
||||
this.usedNames = new Set();
|
||||
this.unsupported = null;
|
||||
}
|
||||
|
||||
fail(reason) {
|
||||
if (!this.unsupported) this.unsupported = reason;
|
||||
}
|
||||
|
||||
propFor(exprText, kind, extra = {}) {
|
||||
const existing = this.byExpr.get(exprText);
|
||||
if (existing) return existing;
|
||||
const base = derivePropName(exprText);
|
||||
let name = base;
|
||||
let n = 2;
|
||||
while (this.usedNames.has(name)) name = `${base}${n++}`;
|
||||
this.usedNames.add(name);
|
||||
const entry = { prop: name, expr: exprText, kind, ...extra };
|
||||
this.byExpr.set(exprText, entry);
|
||||
this.contract.push(entry);
|
||||
return entry;
|
||||
}
|
||||
}
|
||||
|
||||
// A derived prop name lands in `let { <name> } = $props()`; a reserved word
|
||||
// there is a syntax error the session only hits at import time.
|
||||
const RESERVED_PROP_NAMES = new Set([
|
||||
'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger',
|
||||
'default', 'delete', 'do', 'else', 'enum', 'export', 'extends', 'false',
|
||||
'finally', 'for', 'function', 'if', 'implements', 'import', 'in',
|
||||
'instanceof', 'interface', 'let', 'new', 'null', 'package', 'private',
|
||||
'protected', 'public', 'return', 'static', 'super', 'switch', 'this',
|
||||
'throw', 'true', 'try', 'typeof', 'undefined', 'var', 'void', 'while',
|
||||
'with', 'yield',
|
||||
]);
|
||||
|
||||
export function derivePropName(expr) {
|
||||
const tail = String(expr).match(/(?:\.|\[["']?)([A-Za-z_$][\w$]*)["']?\]?\s*$/);
|
||||
const candidate = (tail && tail[1])
|
||||
|| (String(expr).match(/^([A-Za-z_$][\w$]*)$/) || [])[1]
|
||||
|| 'value';
|
||||
return RESERVED_PROP_NAMES.has(candidate) ? `${candidate}Value` : candidate;
|
||||
}
|
||||
|
||||
function exprText(source, node) {
|
||||
return source.slice(node.start, node.end);
|
||||
}
|
||||
|
||||
// Identifiers that resolve in ANY module scope. They are neither hydratable
|
||||
// props nor evidence of route coupling, so they count as neither free nor
|
||||
// bound: `{Math.round(x)}` must not mint a prop named `round`, and
|
||||
// `{fmt(stage.label)}` must not pass as global-only.
|
||||
const GLOBAL_IDENTIFIERS = new Set([
|
||||
'Math', 'JSON', 'Date', 'Intl', 'Number', 'String', 'Boolean', 'Array',
|
||||
'Object', 'Map', 'Set', 'Promise', 'RegExp', 'NaN', 'Infinity', 'undefined',
|
||||
'isNaN', 'isFinite', 'parseInt', 'parseFloat', 'encodeURIComponent',
|
||||
'decodeURIComponent', 'console', 'window', 'document', 'navigator',
|
||||
'location', 'structuredClone', 'crypto',
|
||||
]);
|
||||
|
||||
function classifyRoots(node, scopes) {
|
||||
const roots = collectRootIdentifiers(node);
|
||||
let bound = 0;
|
||||
let free = 0;
|
||||
for (const name of roots) {
|
||||
if (GLOBAL_IDENTIFIERS.has(name)) continue;
|
||||
if (scopes.some((scope) => scope.has(name))) bound++;
|
||||
else free++;
|
||||
}
|
||||
return { bound, free };
|
||||
}
|
||||
|
||||
function isFree(node, scopes) {
|
||||
const { bound, free } = classifyRoots(node, scopes);
|
||||
return free > 0 && bound === 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* An expression mixing loop-bound and outer free identifiers (e.g.
|
||||
* `{fmt(stage.label)}` where `fmt` lives in the route script) can neither
|
||||
* become a prop (the bound part varies per item) nor survive detachment
|
||||
* verbatim (the free name is undeclared in the preview and throws at mount,
|
||||
* past the compile gate, because globals make it legal to the compiler).
|
||||
* Source-preview mode is the only correct home for it.
|
||||
*/
|
||||
function failOnMixedExpression(node, scopes, analysis, source) {
|
||||
const { bound, free } = classifyRoots(node, scopes);
|
||||
if (bound > 0 && free > 0) {
|
||||
analysis.fail(`expression mixing loop and outer identifiers ({${exprText(source, node).slice(0, 60)}}) requires source-preview mode`);
|
||||
return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Analyze a parsed template fragment. `scopes` is a stack of Sets of bound
|
||||
* names; the outermost call passes an empty stack.
|
||||
*/
|
||||
function analyzeFragment(fragment, analysis, scopes) {
|
||||
if (!fragment || !Array.isArray(fragment.nodes)) return;
|
||||
// ConstTag declarations bind for the whole fragment.
|
||||
const fragmentScope = new Set();
|
||||
const nextScopes = [...scopes, fragmentScope];
|
||||
for (const node of fragment.nodes) {
|
||||
if (node.type === 'ConstTag' && node.declaration) {
|
||||
for (const decl of node.declaration.declarations || []) {
|
||||
collectPatternNames(decl.id, fragmentScope);
|
||||
}
|
||||
}
|
||||
}
|
||||
for (const node of fragment.nodes) analyzeNode(node, analysis, nextScopes);
|
||||
}
|
||||
|
||||
function analyzeNode(node, analysis, scopes) {
|
||||
if (!node || analysis.unsupported) return;
|
||||
switch (node.type) {
|
||||
case 'Text':
|
||||
case 'Comment':
|
||||
return;
|
||||
case 'ExpressionTag': {
|
||||
if (failOnMixedExpression(node.expression, scopes, analysis, analysis.source)) return;
|
||||
if (isFree(node.expression, scopes)) {
|
||||
const text = exprText(analysis.source, node.expression);
|
||||
const entry = analysis.propFor(text, 'text');
|
||||
// node.start/end include the braces; keep them, swap the inside.
|
||||
analysis.replacements.push({ start: node.expression.start, end: node.expression.end, prop: entry.prop });
|
||||
}
|
||||
return;
|
||||
}
|
||||
case 'HtmlTag': {
|
||||
if (failOnMixedExpression(node.expression, scopes, analysis, analysis.source)) return;
|
||||
if (isFree(node.expression, scopes)) {
|
||||
const text = exprText(analysis.source, node.expression);
|
||||
const entry = analysis.propFor(text, 'raw');
|
||||
analysis.replacements.push({ start: node.expression.start, end: node.expression.end, prop: entry.prop });
|
||||
}
|
||||
return;
|
||||
}
|
||||
case 'ConstTag': {
|
||||
// Its expression may read free names; leave them: the declaration
|
||||
// travels with the markup and stays valid only if its inputs do.
|
||||
if (node.declaration) {
|
||||
for (const decl of node.declaration.declarations || []) {
|
||||
if (decl.init && failOnMixedExpression(decl.init, scopes, analysis, analysis.source)) return;
|
||||
if (decl.init && isFree(decl.init, scopes)) {
|
||||
const text = exprText(analysis.source, decl.init);
|
||||
const entry = analysis.propFor(text, 'text');
|
||||
analysis.replacements.push({ start: decl.init.start, end: decl.init.end, prop: entry.prop });
|
||||
}
|
||||
}
|
||||
}
|
||||
return;
|
||||
}
|
||||
case 'EachBlock': {
|
||||
if (failOnMixedExpression(node.expression, scopes, analysis, analysis.source)) return;
|
||||
if (isFree(node.expression, scopes)) {
|
||||
const text = exprText(analysis.source, node.expression);
|
||||
const item = describeEachItem(node, analysis.source);
|
||||
// Keyed each: the key must evaluate to a distinct value per hydrated
|
||||
// item or Svelte throws each_key_duplicate at mount. A key that is a
|
||||
// plain member of the item (the common `(item.id)` shape) gets a
|
||||
// synthetic per-index value injected by the browser (keyField).
|
||||
// Anything else cannot be hydrated safely; source-preview mode keeps
|
||||
// it correct.
|
||||
if (node.key) {
|
||||
const keyInfo = classifyEachKey(node);
|
||||
if (keyInfo.unsupported) {
|
||||
analysis.fail(keyInfo.unsupported);
|
||||
return;
|
||||
}
|
||||
if (keyInfo.keyField) {
|
||||
if (item.textSlots.some((slot) => slot.key === keyInfo.keyField)) {
|
||||
// The key doubles as a displayed slot; a synthetic value would
|
||||
// change visible text, and the displayed text may not be
|
||||
// unique. Not previewable in a detached component.
|
||||
analysis.fail('each key that is also a displayed field requires source-preview mode');
|
||||
return;
|
||||
}
|
||||
item.keyField = keyInfo.keyField;
|
||||
}
|
||||
}
|
||||
const entry = analysis.propFor(text, 'collection', { item });
|
||||
analysis.replacements.push({ start: node.expression.start, end: node.expression.end, prop: entry.prop });
|
||||
}
|
||||
const bound = new Set();
|
||||
if (node.context) collectPatternNames(node.context, bound);
|
||||
if (node.index) bound.add(node.index);
|
||||
analyzeFragment(node.body, analysis, [...scopes, bound]);
|
||||
if (node.fallback) analyzeFragment(node.fallback, analysis, scopes);
|
||||
return;
|
||||
}
|
||||
case 'IfBlock': {
|
||||
if (failOnMixedExpression(node.test, scopes, analysis, analysis.source)) return;
|
||||
if (isFree(node.test, scopes)) {
|
||||
const text = exprText(analysis.source, node.test);
|
||||
// The browser hydrates a free condition from what the live page
|
||||
// currently shows: when the consequent's root element is present
|
||||
// under the picked element, the condition is on.
|
||||
const entry = analysis.propFor(text, 'condition', {
|
||||
probe: describeElementProbe(node.consequent),
|
||||
});
|
||||
analysis.replacements.push({ start: node.test.start, end: node.test.end, prop: entry.prop });
|
||||
}
|
||||
analyzeFragment(node.consequent, analysis, scopes);
|
||||
if (node.alternate) analyzeFragment(node.alternate, analysis, scopes);
|
||||
return;
|
||||
}
|
||||
case 'KeyBlock': {
|
||||
if (failOnMixedExpression(node.expression, scopes, analysis, analysis.source)) return;
|
||||
if (isFree(node.expression, scopes)) {
|
||||
const text = exprText(analysis.source, node.expression);
|
||||
const entry = analysis.propFor(text, 'text');
|
||||
analysis.replacements.push({ start: node.expression.start, end: node.expression.end, prop: entry.prop });
|
||||
}
|
||||
analyzeFragment(node.fragment, analysis, scopes);
|
||||
return;
|
||||
}
|
||||
case 'SnippetBlock': {
|
||||
const bound = new Set();
|
||||
for (const param of node.parameters || []) collectPatternNames(param, bound);
|
||||
// The snippet's own name becomes available to render tags in this file.
|
||||
analyzeFragment(node.body, analysis, [...scopes, bound]);
|
||||
return;
|
||||
}
|
||||
case 'RegularElement':
|
||||
case 'SlotElement':
|
||||
case 'TitleElement': {
|
||||
if (node.name === 'script') {
|
||||
// An inline script inside the selected block carries route-scoped
|
||||
// code; running it a second time from a detached preview is wrong.
|
||||
analysis.fail('inline script element requires source-preview mode');
|
||||
return;
|
||||
}
|
||||
analyzeAttributes(node, analysis, scopes);
|
||||
if (!analysis.unsupported) analyzeFragment(node.fragment, analysis, scopes);
|
||||
return;
|
||||
}
|
||||
case 'SvelteElement':
|
||||
case 'SvelteFragment':
|
||||
case 'SvelteBoundary': {
|
||||
analyzeAttributes(node, analysis, scopes);
|
||||
if (!analysis.unsupported) analyzeFragment(node.fragment, analysis, scopes);
|
||||
return;
|
||||
}
|
||||
case 'Component':
|
||||
case 'SvelteComponent':
|
||||
case 'SvelteSelf':
|
||||
// The component's import lives in the route file; a detached preview
|
||||
// cannot resolve it. Source-preview mode keeps it working.
|
||||
analysis.fail(`component tag <${node.name || 'Component'}> requires source-preview mode`);
|
||||
return;
|
||||
case 'RenderTag':
|
||||
analysis.fail('render tag requires source-preview mode');
|
||||
return;
|
||||
case 'AwaitBlock':
|
||||
analysis.fail('await block requires source-preview mode');
|
||||
return;
|
||||
case 'SvelteHead':
|
||||
case 'SvelteWindow':
|
||||
case 'SvelteDocument':
|
||||
case 'SvelteBody':
|
||||
analysis.fail(`${node.type} requires source-preview mode`);
|
||||
return;
|
||||
default: {
|
||||
if (node.fragment) analyzeFragment(node.fragment, analysis, scopes);
|
||||
return;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
function analyzeAttributes(node, analysis, scopes) {
|
||||
for (const attr of node.attributes || []) {
|
||||
switch (attr.type) {
|
||||
case 'Attribute': {
|
||||
if (attr.value === true) break;
|
||||
const parts = Array.isArray(attr.value) ? attr.value : [attr.value];
|
||||
for (const part of parts) {
|
||||
if (!part || part.type !== 'ExpressionTag') continue;
|
||||
if (failOnMixedExpression(part.expression, scopes, analysis, analysis.source)) return;
|
||||
if (!isFree(part.expression, scopes)) continue;
|
||||
const text = exprText(analysis.source, part.expression);
|
||||
const kind = HANDLER_ATTR_RE.test(attr.name) ? 'handler' : 'text';
|
||||
const entry = analysis.propFor(text, kind);
|
||||
analysis.replacements.push({ start: part.expression.start, end: part.expression.end, prop: entry.prop });
|
||||
}
|
||||
break;
|
||||
}
|
||||
case 'ClassDirective': {
|
||||
const expr = attr.expression;
|
||||
if (expr && failOnMixedExpression(expr, scopes, analysis, analysis.source)) return;
|
||||
if (expr && isFree(expr, scopes)) {
|
||||
const text = exprText(analysis.source, expr);
|
||||
// The directive's class name is literal, so the live DOM answers
|
||||
// the condition directly: the class is either present or not.
|
||||
const entry = analysis.propFor(text, 'condition', {
|
||||
probe: { className: attr.name },
|
||||
});
|
||||
analysis.replacements.push({ start: expr.start, end: expr.end, prop: entry.prop });
|
||||
}
|
||||
break;
|
||||
}
|
||||
case 'StyleDirective': {
|
||||
// Unlike ClassDirective, a style directive stores its value in
|
||||
// attribute shape: `true` for the shorthand, else an array of parts.
|
||||
const parts = attr.value === true ? [] : (Array.isArray(attr.value) ? attr.value : [attr.value]);
|
||||
for (const part of parts) {
|
||||
if (part?.type === 'ExpressionTag'
|
||||
&& failOnMixedExpression(part.expression, scopes, analysis, analysis.source)) {
|
||||
return;
|
||||
}
|
||||
}
|
||||
const dynamic = parts.some((part) => part?.type === 'ExpressionTag' && isFree(part.expression, scopes));
|
||||
const shorthandFree = attr.value === true && isFree({ type: 'Identifier', name: attr.name }, scopes);
|
||||
if (dynamic || shorthandFree) {
|
||||
// style:opacity={x} carries a css VALUE, not a boolean, and the
|
||||
// computed value on the live element is not reliably recoverable in
|
||||
// the shape the expression produced. A falsified style is worse
|
||||
// than an HMR-resetting preview.
|
||||
analysis.fail(`style:${attr.name} with a dynamic value requires source-preview mode`);
|
||||
}
|
||||
break;
|
||||
}
|
||||
case 'BindDirective':
|
||||
analysis.fail(`bind:${attr.name} requires source-preview mode`);
|
||||
return;
|
||||
case 'UseDirective':
|
||||
analysis.fail(`use:${attr.name} requires source-preview mode`);
|
||||
return;
|
||||
case 'AnimateDirective':
|
||||
case 'TransitionDirective':
|
||||
// Motion directives reference route-scoped or svelte/transition
|
||||
// imports; a detached preview cannot resolve them.
|
||||
analysis.fail(`${attr.type} requires source-preview mode`);
|
||||
return;
|
||||
case 'OnDirective': {
|
||||
// Legacy on:click syntax; treat like handler attributes.
|
||||
const expr = attr.expression;
|
||||
if (expr && failOnMixedExpression(expr, scopes, analysis, analysis.source)) return;
|
||||
if (expr && isFree(expr, scopes)) {
|
||||
const text = exprText(analysis.source, expr);
|
||||
const entry = analysis.propFor(text, 'handler');
|
||||
analysis.replacements.push({ start: expr.start, end: expr.end, prop: entry.prop });
|
||||
}
|
||||
break;
|
||||
}
|
||||
case 'SpreadAttribute':
|
||||
analysis.fail('spread attribute requires source-preview mode');
|
||||
return;
|
||||
default:
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Describe the repeating item of an each block for browser-side hydration:
|
||||
* the item's root element (tag + static classes, used to count live
|
||||
* iterations) and the ordered text slots that reference loop bindings.
|
||||
*/
|
||||
function describeEachItem(node, source) {
|
||||
const body = node.body;
|
||||
const rootEl = (body?.nodes || []).find((n) => n.type === 'RegularElement');
|
||||
|
||||
const textSlots = [];
|
||||
const staticTexts = [];
|
||||
let nestedUnsupported = false;
|
||||
const collectStatics = (fragment) => {
|
||||
for (const child of fragment?.nodes || []) {
|
||||
if (child.type === 'Text') {
|
||||
const trimmed = String(child.data || '').trim();
|
||||
if (trimmed) staticTexts.push(trimmed);
|
||||
} else if (child.type === 'IfBlock') {
|
||||
collectStatics(child.consequent);
|
||||
if (child.alternate) collectStatics(child.alternate);
|
||||
} else if (child.type === 'EachBlock') {
|
||||
collectStatics(child.body);
|
||||
} else if (child.fragment) {
|
||||
collectStatics(child.fragment);
|
||||
}
|
||||
}
|
||||
};
|
||||
collectStatics(body);
|
||||
const attrSlots = [];
|
||||
// The hydration item is a SHALLOW object whose string fields are the exact
|
||||
// property names the markup accesses, filled from the rendered page. That
|
||||
// model supports one item access per slot, optionally wrapped in a global
|
||||
// transform ({Math.round(r.score)} hydrates `score`). Shapes it cannot
|
||||
// represent split two ways: CRASHY ones would throw at mount time against a
|
||||
// shallow item (deep paths like r.meta.label, method calls like r.format())
|
||||
// and force the source-preview fallback; LOSSY ones render wrong but safe
|
||||
// (bare {r}, multi-access expressions that would double their text) and
|
||||
// also fall back in text position, where the damage is visible.
|
||||
const boundAs = (name, scopeInfos) => {
|
||||
for (let i = scopeInfos.length - 1; i >= 0; i--) {
|
||||
const info = scopeInfos[i];
|
||||
if (info.indexName === name) return 'index';
|
||||
if (info.itemName === name) return 'item';
|
||||
if (info.names.has(name)) return 'field';
|
||||
}
|
||||
return null;
|
||||
};
|
||||
const slotKeysOf = (expression, scopeInfos) => {
|
||||
const keys = new Set();
|
||||
let crashy = false;
|
||||
let lossy = false;
|
||||
let touches = false;
|
||||
const visit = (node, ctx) => {
|
||||
if (!node || typeof node !== 'object' || crashy) return;
|
||||
if (Array.isArray(node)) {
|
||||
for (const item of node) visit(item, {});
|
||||
return;
|
||||
}
|
||||
switch (node.type) {
|
||||
case 'Identifier': {
|
||||
const kind = boundAs(node.name, scopeInfos);
|
||||
if (!kind) return;
|
||||
touches = true;
|
||||
if (kind === 'index') return; // the runtime each provides it
|
||||
if (kind === 'item') { lossy = true; return; } // bare item reference
|
||||
if (ctx.callee) { crashy = true; return; } // field() on a hydrated string
|
||||
keys.add(node.name); // destructured context field
|
||||
return;
|
||||
}
|
||||
case 'MemberExpression': {
|
||||
if (
|
||||
!node.computed
|
||||
&& node.object?.type === 'Identifier'
|
||||
&& boundAs(node.object.name, scopeInfos) === 'item'
|
||||
&& node.property?.type === 'Identifier'
|
||||
) {
|
||||
touches = true;
|
||||
// item.a.b or item.method(): a shallow string field throws here.
|
||||
if (ctx.memberObject || ctx.callee) { crashy = true; return; }
|
||||
keys.add(node.property.name);
|
||||
return;
|
||||
}
|
||||
visit(node.object, { memberObject: true });
|
||||
if (node.computed) visit(node.property, {});
|
||||
return;
|
||||
}
|
||||
case 'CallExpression':
|
||||
visit(node.callee, { callee: true });
|
||||
for (const arg of node.arguments || []) visit(arg, {});
|
||||
return;
|
||||
case 'ArrowFunctionExpression':
|
||||
case 'FunctionExpression': {
|
||||
// Closures cannot hydrate; only lossy when they capture the item.
|
||||
const roots = collectRootIdentifiers(node);
|
||||
if ([...roots].some((name) => boundAs(name, scopeInfos))) { touches = true; lossy = true; }
|
||||
return;
|
||||
}
|
||||
case 'Property':
|
||||
if (node.computed) visit(node.key, {});
|
||||
visit(node.value, {});
|
||||
return;
|
||||
default: {
|
||||
for (const key of Object.keys(node)) {
|
||||
if (key === 'type' || key === 'start' || key === 'end' || key === 'loc' || key === 'range' || key === 'parent') continue;
|
||||
visit(node[key], {});
|
||||
}
|
||||
}
|
||||
}
|
||||
};
|
||||
visit(expression, {});
|
||||
if (crashy) return { crashy: true };
|
||||
if (lossy || keys.size > 1) return { lossy: true };
|
||||
if (!touches || keys.size === 0) return { skip: true };
|
||||
return { key: [...keys][0] };
|
||||
};
|
||||
const staticClassesOf = (el) => {
|
||||
const classes = [];
|
||||
for (const attr of el?.attributes || []) {
|
||||
if (attr.type === 'Attribute' && attr.name === 'class' && Array.isArray(attr.value)) {
|
||||
for (const part of attr.value) {
|
||||
if (part.type === 'Text') classes.push(...part.data.split(/\s+/).filter(Boolean));
|
||||
}
|
||||
}
|
||||
}
|
||||
return classes;
|
||||
};
|
||||
const scopeInfoOf = (eachNode) => {
|
||||
const names = new Set();
|
||||
if (eachNode.context) collectPatternNames(eachNode.context, names);
|
||||
return {
|
||||
names,
|
||||
itemName: eachNode.context?.type === 'Identifier' ? eachNode.context.name : null,
|
||||
indexName: eachNode.index || null,
|
||||
};
|
||||
};
|
||||
const walkForSlots = (fragment, scopeInfos) => {
|
||||
for (const child of fragment?.nodes || []) {
|
||||
if (child.type === 'ExpressionTag') {
|
||||
const slot = slotKeysOf(child.expression, scopeInfos);
|
||||
if (slot.crashy || slot.lossy) { nestedUnsupported = true; continue; }
|
||||
if (slot.skip) continue;
|
||||
textSlots.push({ key: slot.key, expr: exprText(source, child.expression) });
|
||||
} else if (child.type === 'RegularElement' || child.type === 'SvelteElement') {
|
||||
// Bound values in ATTRIBUTES (href={link.href}, src={item.img}) are
|
||||
// part of the item too: the browser reads the rendered attribute off
|
||||
// the live element, so the preview does not mount with empty links.
|
||||
// Only a single-expression attribute hydrates exactly; a mixed value
|
||||
// ("card {r.status}") stays unhydrated because the rendered attribute
|
||||
// is not separable into its parts, which was the prior behavior.
|
||||
for (const attr of child.attributes || []) {
|
||||
if (attr.type !== 'Attribute' || attr.value === true) continue;
|
||||
if (HANDLER_ATTR_RE.test(attr.name)) continue; // functions cannot hydrate
|
||||
const parts = Array.isArray(attr.value) ? attr.value : [attr.value];
|
||||
const exprParts = parts.filter((part) => part?.type === 'ExpressionTag');
|
||||
for (const part of exprParts) {
|
||||
const slot = slotKeysOf(part.expression, scopeInfos);
|
||||
if (slot.crashy) { nestedUnsupported = true; continue; }
|
||||
if (slot.skip || slot.lossy) continue;
|
||||
if (parts.length !== 1) continue; // mixed static+dynamic value
|
||||
attrSlots.push({
|
||||
key: slot.key,
|
||||
expr: exprText(source, part.expression),
|
||||
attr: attr.name,
|
||||
tag: child.name || null,
|
||||
classes: staticClassesOf(child),
|
||||
});
|
||||
}
|
||||
}
|
||||
walkForSlots(child.fragment, scopeInfos);
|
||||
continue;
|
||||
} else if (child.type === 'EachBlock') {
|
||||
const roots = collectRootIdentifiers(child.expression);
|
||||
const boundNested = [...roots].some((name) => boundAs(name, scopeInfos));
|
||||
if (boundNested) nestedUnsupported = true; // nested per-item arrays: no hydration plan yet
|
||||
walkForSlots(child.body, [...scopeInfos, scopeInfoOf(child)]);
|
||||
} else if (child.type === 'IfBlock') {
|
||||
walkForSlots(child.consequent, scopeInfos);
|
||||
if (child.alternate) walkForSlots(child.alternate, scopeInfos);
|
||||
} else if (child.fragment) {
|
||||
walkForSlots(child.fragment, scopeInfos);
|
||||
}
|
||||
}
|
||||
};
|
||||
walkForSlots(body, [scopeInfoOf(node)]);
|
||||
|
||||
const staticClasses = [];
|
||||
for (const attr of rootEl?.attributes || []) {
|
||||
if (attr.type === 'Attribute' && attr.name === 'class' && Array.isArray(attr.value)) {
|
||||
for (const part of attr.value) {
|
||||
if (part.type === 'Text') staticClasses.push(...part.data.split(/\s+/).filter(Boolean));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
rootTag: rootEl?.name || null,
|
||||
rootClasses: staticClasses,
|
||||
textSlots,
|
||||
attrSlots,
|
||||
staticTexts,
|
||||
nestedUnsupported,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Classify a keyed each block's key expression:
|
||||
* { keyField } member of the loop item (e.g. `(expense.id)` when the
|
||||
* context binds `expense`): browser injects a unique
|
||||
* per-index value under that field.
|
||||
* {} key is the whole loop item or the index: already
|
||||
* distinct per iteration, nothing to inject.
|
||||
* { unsupported } free or complex keys: cannot hydrate distinct values.
|
||||
*/
|
||||
function classifyEachKey(node) {
|
||||
const bound = new Set();
|
||||
if (node.context) collectPatternNames(node.context, bound);
|
||||
if (node.index) bound.add(node.index);
|
||||
const key = node.key;
|
||||
const roots = collectRootIdentifiers(key);
|
||||
const usesLoopBinding = [...roots].some((name) => bound.has(name));
|
||||
if (!usesLoopBinding) {
|
||||
// A key that ignores the loop item is constant across iterations:
|
||||
// guaranteed duplicate keys at mount.
|
||||
return { unsupported: 'each key not derived from the loop item requires source-preview mode' };
|
||||
}
|
||||
if (key.type === 'Identifier' && bound.has(key.name)) return {};
|
||||
if (
|
||||
key.type === 'MemberExpression'
|
||||
&& !key.computed
|
||||
&& key.object?.type === 'Identifier'
|
||||
&& bound.has(key.object.name)
|
||||
&& key.property?.type === 'Identifier'
|
||||
) {
|
||||
return { keyField: key.property.name };
|
||||
}
|
||||
return { unsupported: 'complex each key requires source-preview mode' };
|
||||
}
|
||||
|
||||
/**
|
||||
* Describe a fragment's root element for browser presence probing:
|
||||
* { tag, classes } of the first RegularElement, or null for text-only
|
||||
* fragments (which cannot be probed reliably).
|
||||
*/
|
||||
function describeElementProbe(fragment) {
|
||||
const rootEl = (fragment?.nodes || []).find((n) => n.type === 'RegularElement');
|
||||
if (!rootEl) return null;
|
||||
const classes = [];
|
||||
for (const attr of rootEl.attributes || []) {
|
||||
if (attr.type === 'Attribute' && attr.name === 'class' && Array.isArray(attr.value)) {
|
||||
for (const part of attr.value) {
|
||||
if (part.type === 'Text') classes.push(...part.data.split(/\s+/).filter(Boolean));
|
||||
}
|
||||
}
|
||||
}
|
||||
return { tag: rootEl.name, classes };
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Public API
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Analyze a markup block and produce the prop-substituted scaffold markup and
|
||||
* the v2 prop contract. Returns { ok: false, reason } when the block needs
|
||||
* source-preview mode (parse failure or unsupported construct).
|
||||
*/
|
||||
export function analyzeSvelteMarkup(markup, parse) {
|
||||
const source = String(markup || '');
|
||||
let ast;
|
||||
try {
|
||||
ast = parse(source, { modern: true });
|
||||
} catch (err) {
|
||||
return { ok: false, reason: `svelte parse failed: ${err.message}` };
|
||||
}
|
||||
if (ast.instance || ast.module) {
|
||||
return { ok: false, reason: 'selected block contains a script tag' };
|
||||
}
|
||||
const analysis = new Analysis(source);
|
||||
analyzeFragment(ast.fragment, analysis, []);
|
||||
if (analysis.unsupported) {
|
||||
return { ok: false, reason: analysis.unsupported };
|
||||
}
|
||||
for (const entry of analysis.contract) {
|
||||
if (entry.kind === 'collection' && entry.item?.nestedUnsupported) {
|
||||
return { ok: false, reason: 'per-item content (nested blocks or expressions) this preview cannot hydrate requires source-preview mode' };
|
||||
}
|
||||
}
|
||||
|
||||
const markupWithProps = applyReplacements(source, analysis.replacements);
|
||||
return {
|
||||
ok: true,
|
||||
markupWithProps,
|
||||
contract: analysis.contract.map((entry) => ({
|
||||
prop: entry.prop,
|
||||
expr: entry.expr,
|
||||
kind: entry.kind,
|
||||
// Kept for backward compatibility with v1 consumers (fake e2e agent,
|
||||
// text-only restore paths).
|
||||
placeholder: `{${entry.expr}}`,
|
||||
...(entry.item ? { item: entry.item } : {}),
|
||||
...(entry.probe ? { probe: entry.probe } : {}),
|
||||
})),
|
||||
};
|
||||
}
|
||||
|
||||
function applyReplacements(source, replacements) {
|
||||
const sorted = [...replacements].sort((a, b) => b.start - a.start);
|
||||
let out = source;
|
||||
for (const { start, end, prop } of sorted) {
|
||||
out = out.slice(0, start) + prop + out.slice(end);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
/**
|
||||
* Restore a variant's markup back to route-source form: every free
|
||||
* identifier that matches a contract prop is replaced by its original
|
||||
* expression. AST-based so `{#each stages as stage}` restores to
|
||||
* `{#each data.stages as stage}` even though the prop appears without braces.
|
||||
*/
|
||||
export function restoreSvelteMarkup(markup, contract, parse) {
|
||||
const source = String(markup || '');
|
||||
const byProp = new Map();
|
||||
for (const entry of contract || []) byProp.set(entry.prop, entry.expr);
|
||||
if (byProp.size === 0) return { ok: true, markup: source };
|
||||
|
||||
let ast;
|
||||
try {
|
||||
ast = parse(source, { modern: true });
|
||||
} catch (err) {
|
||||
return { ok: false, reason: `variant parse failed: ${err.message}` };
|
||||
}
|
||||
|
||||
const replacements = [];
|
||||
const visitExpr = (expression, scopes) => {
|
||||
if (!expression) return;
|
||||
collectFreeIdentifierRanges(expression, scopes, (name, start, end) => {
|
||||
const original = byProp.get(name);
|
||||
if (original != null && original !== name) replacements.push({ start, end, prop: original });
|
||||
});
|
||||
};
|
||||
|
||||
const walk = (fragment, scopes) => {
|
||||
const fragmentScope = new Set();
|
||||
const nextScopes = [...scopes, fragmentScope];
|
||||
for (const node of fragment?.nodes || []) {
|
||||
if (node.type === 'ConstTag' && node.declaration) {
|
||||
for (const decl of node.declaration.declarations || []) collectPatternNames(decl.id, fragmentScope);
|
||||
}
|
||||
}
|
||||
for (const node of fragment?.nodes || []) {
|
||||
switch (node?.type) {
|
||||
case 'ExpressionTag':
|
||||
case 'HtmlTag':
|
||||
visitExpr(node.expression, nextScopes);
|
||||
break;
|
||||
case 'ConstTag':
|
||||
for (const decl of node.declaration?.declarations || []) visitExpr(decl.init, nextScopes);
|
||||
break;
|
||||
case 'EachBlock': {
|
||||
visitExpr(node.expression, nextScopes);
|
||||
const bound = new Set();
|
||||
if (node.context) collectPatternNames(node.context, bound);
|
||||
if (node.index) bound.add(node.index);
|
||||
// The key evaluates per item, so the loop context and index are in
|
||||
// scope there. Visiting it with outer scopes only let a contract
|
||||
// prop that shares a loop binding's name rewrite the key.
|
||||
if (node.key) visitExpr(node.key, [...nextScopes, bound]);
|
||||
walk(node.body, [...nextScopes, bound]);
|
||||
if (node.fallback) walk(node.fallback, nextScopes);
|
||||
break;
|
||||
}
|
||||
case 'IfBlock':
|
||||
visitExpr(node.test, nextScopes);
|
||||
walk(node.consequent, nextScopes);
|
||||
if (node.alternate) walk(node.alternate, nextScopes);
|
||||
break;
|
||||
case 'KeyBlock':
|
||||
visitExpr(node.expression, nextScopes);
|
||||
walk(node.fragment, nextScopes);
|
||||
break;
|
||||
case 'SnippetBlock': {
|
||||
const bound = new Set();
|
||||
for (const param of node.parameters || []) collectPatternNames(param, bound);
|
||||
walk(node.body, [...nextScopes, bound]);
|
||||
break;
|
||||
}
|
||||
default: {
|
||||
for (const attr of node?.attributes || []) {
|
||||
if (attr.type === 'Attribute' && Array.isArray(attr.value)) {
|
||||
for (const part of attr.value) {
|
||||
if (part?.type === 'ExpressionTag') visitExpr(part.expression, nextScopes);
|
||||
}
|
||||
} else if (attr.expression) {
|
||||
visitExpr(attr.expression, nextScopes);
|
||||
}
|
||||
}
|
||||
if (node?.fragment) walk(node.fragment, nextScopes);
|
||||
}
|
||||
}
|
||||
}
|
||||
};
|
||||
walk(ast.fragment, []);
|
||||
|
||||
return { ok: true, markup: applyReplacements(source, replacements) };
|
||||
}
|
||||
|
||||
/**
|
||||
* Report [name, start, end] for every free root identifier READ in an
|
||||
* expression (skips member properties, object keys, shadowed names).
|
||||
*/
|
||||
function collectFreeIdentifierRanges(node, scopes, emit) {
|
||||
const visit = (n, localBound) => {
|
||||
if (!n || typeof n !== 'object') return;
|
||||
if (Array.isArray(n)) { for (const item of n) visit(item, localBound); return; }
|
||||
switch (n.type) {
|
||||
case 'Identifier': {
|
||||
const bound = localBound.has(n.name) || scopes.some((s) => s.has(n.name));
|
||||
if (!bound) emit(n.name, n.start, n.end);
|
||||
return;
|
||||
}
|
||||
case 'MemberExpression':
|
||||
visit(n.object, localBound);
|
||||
if (n.computed) visit(n.property, localBound);
|
||||
return;
|
||||
case 'Property':
|
||||
if (n.computed) visit(n.key, localBound);
|
||||
visit(n.value, localBound);
|
||||
return;
|
||||
case 'ArrowFunctionExpression':
|
||||
case 'FunctionExpression': {
|
||||
const inner = new Set(localBound);
|
||||
for (const param of n.params || []) collectPatternNames(param, inner);
|
||||
visit(n.body, inner);
|
||||
return;
|
||||
}
|
||||
default:
|
||||
for (const key of Object.keys(n)) {
|
||||
if (key === 'type' || key === 'start' || key === 'end' || key === 'loc' || key === 'range' || key === 'parent') continue;
|
||||
visit(n[key], localBound);
|
||||
}
|
||||
}
|
||||
};
|
||||
visit(node, new Set());
|
||||
}
|
||||
|
||||
/**
|
||||
* Build the preview component's script block from a v2 contract, with
|
||||
* defaults that keep an unhydrated mount rendering instead of crashing.
|
||||
*/
|
||||
export function buildPropsScriptV2(contract) {
|
||||
if (!contract || contract.length === 0) {
|
||||
return '<script>\n /** @type {Record<string, never>} */\n let {} = $props();\n</script>\n';
|
||||
}
|
||||
const defaults = {
|
||||
text: "''",
|
||||
raw: "''",
|
||||
condition: 'false',
|
||||
collection: '[]',
|
||||
handler: '() => {}',
|
||||
};
|
||||
const types = {
|
||||
text: 'string',
|
||||
raw: 'string',
|
||||
condition: 'boolean',
|
||||
collection: 'Array<Record<string, unknown>>',
|
||||
handler: '() => void',
|
||||
};
|
||||
const names = contract
|
||||
.map((c) => `${c.prop} = ${defaults[c.kind] ?? "''"}`)
|
||||
.join(', ');
|
||||
const typeFields = contract
|
||||
.map((c) => ` ${c.prop}?: ${types[c.kind] ?? 'string'};`)
|
||||
.join('\n');
|
||||
return `<script>\n /** @type {{\n${typeFields}\n }} */\n let { ${names} } = $props();\n</script>\n`;
|
||||
}
|
||||
@@ -10,9 +10,38 @@ import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import os from 'node:os';
|
||||
import { createHash } from 'node:crypto';
|
||||
import {
|
||||
analyzeSvelteMarkup,
|
||||
buildPropsScriptV2,
|
||||
loadSvelteCompiler,
|
||||
restoreSvelteMarkup,
|
||||
} from './svelte-ast.mjs';
|
||||
import {
|
||||
bakeParamValues,
|
||||
collectAllSelectors,
|
||||
collectUnusedSelectors,
|
||||
normalizeSelector,
|
||||
parseStylesheet,
|
||||
pruneUnusedSelectors,
|
||||
reconcileCss,
|
||||
serializeNodes,
|
||||
splitSelectorList,
|
||||
} from './accept-css.mjs';
|
||||
import { verifyAcceptedSource } from './accept-verify.mjs';
|
||||
|
||||
// Preview modules stay under node_modules on purpose: SvelteKit restricts
|
||||
// vite's server.fs.allow to src/lib, src/routes, .svelte-kit, and
|
||||
// node_modules, so an .impeccable/ tree under the app root 403s (verified
|
||||
// against a real SvelteKit dev server). Staleness from node_modules being
|
||||
// unwatched is solved by REVISIONED module paths instead: every publish
|
||||
// snapshots the variant files into a fresh r<N>/ directory and the browser
|
||||
// imports from there, so a republished fix can never be pinned by a
|
||||
// transform cache keyed on the old path.
|
||||
export const SVELTE_COMPONENT_ROOT = 'node_modules/.impeccable-live';
|
||||
// A short-lived interim location; swept so no project keeps a stray tree.
|
||||
export const LEGACY_SVELTE_COMPONENT_ROOT = '.impeccable/live/previews';
|
||||
export const SVELTE_RUNTIME_FILE = `${SVELTE_COMPONENT_ROOT}/__runtime.js`;
|
||||
export const SVELTE_PROBE_FILE = `${SVELTE_COMPONENT_ROOT}/__probe.js`;
|
||||
export const DEFERRED_ACCEPTS_FILE = '.impeccable/live/deferred-svelte-component-accepts.json';
|
||||
|
||||
const MUSTACHE_RE = /\{([^{}]+)\}/g;
|
||||
@@ -32,9 +61,18 @@ export function manifestPathForSession(id, cwd = process.cwd()) {
|
||||
|
||||
export function ensureRuntimeHelper(cwd = process.cwd()) {
|
||||
const file = path.join(cwd, SVELTE_RUNTIME_FILE);
|
||||
if (fs.existsSync(file)) return file;
|
||||
fs.mkdirSync(path.dirname(file), { recursive: true });
|
||||
fs.writeFileSync(file, `export { mount, unmount } from 'svelte';\n`, 'utf-8');
|
||||
if (!fs.existsSync(file)) {
|
||||
fs.writeFileSync(file, `export { mount, unmount } from 'svelte';\n`, 'utf-8');
|
||||
}
|
||||
// Attach-time probe: the browser imports this through the dev server before
|
||||
// the first mount. A 404 here means the resolved app root and the dev
|
||||
// server's root disagree, and the session fails with a named error instead
|
||||
// of a silent fall-back to the picker at first variant.
|
||||
const probe = path.join(cwd, SVELTE_PROBE_FILE);
|
||||
if (!fs.existsSync(probe)) {
|
||||
fs.writeFileSync(probe, `export const impeccableLivePreviewProbe = true;\n`, 'utf-8');
|
||||
}
|
||||
return file;
|
||||
}
|
||||
|
||||
@@ -136,6 +174,14 @@ function buildInsertVariantStub(variantNum) {
|
||||
return `${buildPropsScript([])}<div class="impeccable-insert-preview">Insert variant ${variantNum}</div>\n\n<style>\n .impeccable-insert-preview { display: block; }\n</style>\n`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Scaffold a component-preview session. The scaffold is AST-based: the app's
|
||||
* own svelte compiler parses the selected markup, control-flow blocks are
|
||||
* preserved (an each collection crosses the prop contract as ONE structured
|
||||
* prop, its loop body verbatim), and constructs a detached preview cannot
|
||||
* support return `{ fallback: 'source-preview', reason }` so the caller keeps
|
||||
* the markup inside the route file instead of shipping a wrong preview.
|
||||
*/
|
||||
export function scaffoldSvelteComponentSession({
|
||||
id,
|
||||
count,
|
||||
@@ -145,25 +191,55 @@ export function scaffoldSvelteComponentSession({
|
||||
originalLines,
|
||||
cwd = process.cwd(),
|
||||
}) {
|
||||
const originalMarkup = originalLines.join('\n');
|
||||
|
||||
const compiler = loadSvelteCompiler(cwd);
|
||||
if (!compiler) {
|
||||
return { fallback: 'source-preview', reason: 'svelte 5 compiler not resolvable from the app root' };
|
||||
}
|
||||
const analysis = analyzeSvelteMarkup(originalMarkup, compiler.parse);
|
||||
if (!analysis.ok) {
|
||||
return { fallback: 'source-preview', reason: analysis.reason };
|
||||
}
|
||||
|
||||
ensureRuntimeHelper(cwd);
|
||||
const dir = componentSessionDir(id, cwd);
|
||||
fs.mkdirSync(dir, { recursive: true });
|
||||
|
||||
const originalMarkup = originalLines.join('\n');
|
||||
const contract = buildPropContract(extractMustacheExpressions(originalMarkup));
|
||||
const originalWithProps = substituteExprsWithProps(originalMarkup, contract);
|
||||
const contract = analysis.contract;
|
||||
const seeded = extractMatchingSourceCss(
|
||||
safeReadSource(path.resolve(cwd, sourceFile)),
|
||||
originalMarkup,
|
||||
);
|
||||
const seededCss = seeded.css;
|
||||
// The preview compiles in isolation, so NONE of these source rules applied
|
||||
// to what the user approved. Accept enforces that preview truth: any of
|
||||
// them the variant does not re-declare is superseded and removed, instead
|
||||
// of re-attaching to the accepted markup through kept class names (the
|
||||
// ".decisions grid grabs the new board" failure). Only the CLASS-matched
|
||||
// selectors are candidates; tag rules style shared route elements.
|
||||
const seededSelectors = [...seeded.supersedable];
|
||||
|
||||
const manifest = {
|
||||
id,
|
||||
previewMode: 'svelte-component',
|
||||
contractVersion: 2,
|
||||
sourceFile: sourceFile.split(path.sep).join('/'),
|
||||
sourceStartLine,
|
||||
sourceEndLine,
|
||||
count,
|
||||
propContract: contract,
|
||||
originalMarkup,
|
||||
seededSelectors,
|
||||
componentDir: path.relative(cwd, dir).split(path.sep).join('/'),
|
||||
// Absolute paths let the browser fall back to /@fs/ imports when the dev
|
||||
// server's base or root makes root-relative URLs miss, and probe whether
|
||||
// the preview tree is reachable at all before blaming a variant.
|
||||
componentDirAbs: dir.split(path.sep).join('/'),
|
||||
runtimeModule: `/${SVELTE_RUNTIME_FILE}`,
|
||||
runtimeModuleAbs: path.join(cwd, SVELTE_RUNTIME_FILE).split(path.sep).join('/'),
|
||||
probeModule: `/${SVELTE_PROBE_FILE}`,
|
||||
probeModuleAbs: path.join(cwd, SVELTE_PROBE_FILE).split(path.sep).join('/'),
|
||||
};
|
||||
|
||||
fs.writeFileSync(path.join(dir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
|
||||
@@ -171,7 +247,7 @@ export function scaffoldSvelteComponentSession({
|
||||
for (let n = 1; n <= count; n++) {
|
||||
const variantFile = path.join(dir, `v${n}.svelte`);
|
||||
if (!fs.existsSync(variantFile)) {
|
||||
fs.writeFileSync(variantFile, buildVariantStub(n, originalWithProps, contract), 'utf-8');
|
||||
fs.writeFileSync(variantFile, buildVariantStubV2(n, analysis.markupWithProps, contract, seededCss), 'utf-8');
|
||||
}
|
||||
}
|
||||
|
||||
@@ -180,9 +256,100 @@ export function scaffoldSvelteComponentSession({
|
||||
manifestFile: path.relative(cwd, path.join(dir, 'manifest.json')).split(path.sep).join('/'),
|
||||
componentDir: manifest.componentDir,
|
||||
propContract: contract,
|
||||
// Inlined so the generate event's scaffold payload carries the stub
|
||||
// shape; the agent edits vN.svelte in place instead of spending reads on
|
||||
// the manifest and stub files (or deleting and recreating them).
|
||||
stubMarkup: analysis.markupWithProps,
|
||||
seededCss,
|
||||
};
|
||||
}
|
||||
|
||||
function safeReadSource(filePath) {
|
||||
try { return fs.readFileSync(filePath, 'utf-8'); } catch { return ''; }
|
||||
}
|
||||
|
||||
function escapeSelectorToken(token) {
|
||||
return String(token).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
||||
}
|
||||
|
||||
/**
|
||||
* Seed variant stubs with the source component's rules that already style the
|
||||
* selected markup, so variants start from the real cascade (a detached
|
||||
* preview inherits none of the route's compile-scoped CSS) instead of
|
||||
* reimplementing it blind.
|
||||
*
|
||||
* Returns { css, supersedable }. `css` is every matching rule (class OR tag
|
||||
* matched). `supersedable` holds only the CLASS-matched selectors: those are
|
||||
* the accept-time removal candidates. Tag selectors (h1, a, p) style shared
|
||||
* elements across the whole route, so they seed the preview but are never
|
||||
* candidates for removal.
|
||||
*/
|
||||
export function extractMatchingSourceCss(routeSource, originalMarkup) {
|
||||
const empty = { css: '', supersedable: new Set() };
|
||||
const styleMatch = String(routeSource || '').match(/<style\b[^>]*>([\s\S]*?)<\/style\s*>/i);
|
||||
if (!styleMatch) return empty;
|
||||
const classNames = new Set();
|
||||
const classRe = /class\s*=\s*(["'])(.*?)\1/g;
|
||||
let m;
|
||||
while ((m = classRe.exec(originalMarkup))) {
|
||||
for (const cls of m[2].split(/\s+/)) if (cls && !cls.includes('{')) classNames.add(cls);
|
||||
}
|
||||
const tagRe = /<([a-z][a-z0-9-]*)/gi;
|
||||
const tags = new Set();
|
||||
while ((m = tagRe.exec(originalMarkup))) tags.add(m[1].toLowerCase());
|
||||
if (classNames.size === 0 && tags.size === 0) return empty;
|
||||
|
||||
// Token-boundary matching, never substring: `.btn` must not match
|
||||
// `.btn-primary`, and `.stage` must not match `.stages`. A substring hit
|
||||
// seeds a rule that never styled the pick, and a falsely seeded selector
|
||||
// becomes an accept-time DELETION of a hand-written rule.
|
||||
const classRes = [...classNames].map((cls) => new RegExp('\\.' + escapeSelectorToken(cls) + '(?![A-Za-z0-9_-])'));
|
||||
const tagRes = [...tags].map((tag) => new RegExp('(^|[\\s>+~,(])' + escapeSelectorToken(tag) + '(?![A-Za-z0-9_-])', 'i'));
|
||||
const classMatches = (selector) => classRes.some((re) => re.test(selector));
|
||||
const tagMatches = (selector) => tagRes.some((re) => re.test(selector));
|
||||
|
||||
const supersedable = new Set();
|
||||
const ruleMatches = (prelude) => {
|
||||
let matched = false;
|
||||
for (const selector of splitSelectorList(prelude)) {
|
||||
if (classMatches(selector)) {
|
||||
matched = true;
|
||||
supersedable.add(normalizeSelector(selector));
|
||||
} else if (tagMatches(selector)) {
|
||||
matched = true;
|
||||
}
|
||||
}
|
||||
return matched;
|
||||
};
|
||||
|
||||
const pick = (nodes) => {
|
||||
const kept = [];
|
||||
for (const node of nodes) {
|
||||
if (node.type === 'rule' && ruleMatches(node.prelude)) kept.push(node);
|
||||
else if (node.type === 'at' && node.children) {
|
||||
const children = pick(node.children);
|
||||
if (children.length) kept.push({ ...node, children });
|
||||
}
|
||||
}
|
||||
return kept;
|
||||
};
|
||||
return { css: serializeNodes(pick(parseStylesheet(styleMatch[1]))), supersedable };
|
||||
}
|
||||
|
||||
function buildVariantStubV2(variantNum, markupWithProps, contract, seededCss) {
|
||||
const propsComment = contract.length > 0
|
||||
? `\n<!-- Props: ${contract.map((c) => `${c.prop} (${c.kind}) <- {${c.expr}}`).join(', ')} -->\n`
|
||||
: '';
|
||||
// The guard comments must never contain the literal "<style" character
|
||||
// sequence: agents (and the fake test agent) locate the style block with
|
||||
// string searches, and a mention inside a comment truncates their surgery
|
||||
// mid-comment.
|
||||
const css = seededCss
|
||||
? `\n<style>\n /* Variant ${variantNum}: seeded from the route's current rules; restyle or delete freely.\n ALL rules go inside THIS block. Svelte allows exactly one top-level style\n element per component; appending a second one is a compile error. */\n${seededCss.split('\n').map((l) => (l.trim() ? ' ' + l : '')).join('\n')}\n</style>\n`
|
||||
: `\n<style>\n /* Variant ${variantNum}: add all CSS inside THIS block. Svelte allows exactly\n one top-level style element; a second one is a compile error. */\n</style>\n`;
|
||||
return `${buildPropsScriptV2(contract)}${propsComment}${markupWithProps.trim()}\n${css}`;
|
||||
}
|
||||
|
||||
export function scaffoldSvelteComponentInsertSession({
|
||||
id,
|
||||
count,
|
||||
@@ -213,7 +380,11 @@ export function scaffoldSvelteComponentInsertSession({
|
||||
count,
|
||||
propContract: [],
|
||||
componentDir: path.relative(cwd, dir).split(path.sep).join('/'),
|
||||
componentDirAbs: dir.split(path.sep).join('/'),
|
||||
runtimeModule: `/${SVELTE_RUNTIME_FILE}`,
|
||||
runtimeModuleAbs: path.join(cwd, SVELTE_RUNTIME_FILE).split(path.sep).join('/'),
|
||||
probeModule: `/${SVELTE_PROBE_FILE}`,
|
||||
probeModuleAbs: path.join(cwd, SVELTE_PROBE_FILE).split(path.sep).join('/'),
|
||||
};
|
||||
|
||||
fs.writeFileSync(path.join(dir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
|
||||
@@ -238,16 +409,24 @@ export function findSvelteComponentManifest(id, cwd = process.cwd()) {
|
||||
if (fs.existsSync(direct)) {
|
||||
return readManifest(direct);
|
||||
}
|
||||
const root = path.join(cwd, SVELTE_COMPONENT_ROOT);
|
||||
if (!fs.existsSync(root)) return null;
|
||||
for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
|
||||
if (!entry.isDirectory()) continue;
|
||||
const candidate = path.join(root, entry.name, 'manifest.json');
|
||||
if (!fs.existsSync(candidate)) continue;
|
||||
try {
|
||||
const manifest = readManifest(candidate);
|
||||
if (manifest?.id === id) return { ...manifest, manifestPath: candidate };
|
||||
} catch { /* skip */ }
|
||||
// Legacy location: a session scaffolded by an older version can still be
|
||||
// accepted after an upgrade.
|
||||
const legacyDirect = path.join(cwd, LEGACY_SVELTE_COMPONENT_ROOT, id, 'manifest.json');
|
||||
if (fs.existsSync(legacyDirect)) {
|
||||
return readManifest(legacyDirect);
|
||||
}
|
||||
for (const rootRel of [SVELTE_COMPONENT_ROOT, LEGACY_SVELTE_COMPONENT_ROOT]) {
|
||||
const root = path.join(cwd, rootRel);
|
||||
if (!fs.existsSync(root)) continue;
|
||||
for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
|
||||
if (!entry.isDirectory()) continue;
|
||||
const candidate = path.join(root, entry.name, 'manifest.json');
|
||||
if (!fs.existsSync(candidate)) continue;
|
||||
try {
|
||||
const manifest = readManifest(candidate);
|
||||
if (manifest?.id === id) return { ...manifest, manifestPath: candidate };
|
||||
} catch { /* skip */ }
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
@@ -451,35 +630,6 @@ function rewriteParamSelectors(selector, paramValues) {
|
||||
return { keep, selector: next };
|
||||
}
|
||||
|
||||
function splitSelectorList(prelude) {
|
||||
const selectors = [];
|
||||
let start = 0;
|
||||
let bracket = 0;
|
||||
let paren = 0;
|
||||
let quote = null;
|
||||
for (let i = 0; i < prelude.length; i++) {
|
||||
const ch = prelude[i];
|
||||
if (quote) {
|
||||
if (ch === '\\') i++;
|
||||
else if (ch === quote) quote = null;
|
||||
continue;
|
||||
}
|
||||
if (ch === '"' || ch === "'") {
|
||||
quote = ch;
|
||||
continue;
|
||||
}
|
||||
if (ch === '[') bracket++;
|
||||
else if (ch === ']') bracket = Math.max(0, bracket - 1);
|
||||
else if (ch === '(') paren++;
|
||||
else if (ch === ')') paren = Math.max(0, paren - 1);
|
||||
else if (ch === ',' && bracket === 0 && paren === 0) {
|
||||
selectors.push(prelude.slice(start, i));
|
||||
start = i + 1;
|
||||
}
|
||||
}
|
||||
selectors.push(prelude.slice(start));
|
||||
return selectors;
|
||||
}
|
||||
|
||||
function selectorHasVariant(selector, variantNum) {
|
||||
return variantSelectorRegex(variantNum).test(selector);
|
||||
@@ -527,10 +677,24 @@ export function inlineSvelteComponentAccept(manifest, variantNum, paramValues =
|
||||
|
||||
const rootTag = matchOpeningTag(markup)?.tag || 'div';
|
||||
const contract = manifest.propContract || [];
|
||||
const compiler = loadSvelteCompiler(cwd);
|
||||
const mergedMarkup = mergeOriginalTopLevelAttrs(markup, manifest.originalMarkup || '');
|
||||
const restoredMarkup = substitutePropsWithExprs(mergedMarkup, contract)
|
||||
.split('\n')
|
||||
.map((line) => line.trimEnd());
|
||||
|
||||
// Restore props back to route expressions. Contract v2 restores through the
|
||||
// AST so a prop used without braces (each headers, attribute positions)
|
||||
// still maps back to its original expression; v1 falls back to the textual
|
||||
// placeholder swap.
|
||||
let restoredText;
|
||||
if (Number(manifest.contractVersion) === 2 && compiler) {
|
||||
const restored = restoreSvelteMarkup(mergedMarkup, contract, compiler.parse);
|
||||
if (!restored.ok) {
|
||||
return { handled: false, error: 'Accepted variant does not parse: ' + restored.reason, ...resultBase };
|
||||
}
|
||||
restoredText = restored.markup;
|
||||
} else {
|
||||
restoredText = substitutePropsWithExprs(mergedMarkup, contract);
|
||||
}
|
||||
const restoredMarkup = restoredText.split('\n').map((line) => line.trimEnd());
|
||||
|
||||
const sourceContent = fs.readFileSync(sourceFile, 'utf-8');
|
||||
const sourceLines = sourceContent.split('\n');
|
||||
@@ -541,10 +705,7 @@ export function inlineSvelteComponentAccept(manifest, variantNum, paramValues =
|
||||
}
|
||||
|
||||
const indent = sourceLines[start].match(/^(\s*)/)?.[1] || '';
|
||||
const indentedMarkup = restoredMarkup.map((line) => {
|
||||
if (line.trim() === '') return '';
|
||||
return indent + line.trimStart();
|
||||
});
|
||||
const indentedMarkup = reindentPreservingStructure(restoredMarkup, indent);
|
||||
|
||||
let newLines = [
|
||||
...sourceLines.slice(0, start),
|
||||
@@ -552,25 +713,235 @@ export function inlineSvelteComponentAccept(manifest, variantNum, paramValues =
|
||||
...sourceLines.slice(end + 1),
|
||||
];
|
||||
|
||||
const sanitizedCss = sanitizeAcceptedSvelteCss(cssLines, variantNum, paramValues, rootTag);
|
||||
const bakedCss = bakeParamValuesInCss(sanitizedCss, paramValues);
|
||||
if (bakedCss.length > 0) {
|
||||
newLines = appendCssToSvelteStyle(newLines, bakedCss);
|
||||
// Selectors that were already unused before this accept are the user's
|
||||
// pre-existing code; the pruning pass must not touch them.
|
||||
const preUnused = compiler ? collectUnusedSelectors(sourceContent, compiler.compile) : new Set();
|
||||
|
||||
// Bake params (declared kinds from params.json drive branch pruning), then
|
||||
// MERGE into the component's existing style block: matching selectors are
|
||||
// replaced, new ones appended. Appending alone is how superseded rules used
|
||||
// to survive their own replacement.
|
||||
const declaredParams = readDeclaredParams(manifest, variantNum, cwd);
|
||||
let variantCss = cssLines.join('\n');
|
||||
if (/data-impeccable-variant|impeccable-variant-ready/.test(variantCss)) {
|
||||
// Defensive: strip preview-wrapper selectors that authoring rules forbid
|
||||
// on this path but an off-spec agent may still emit.
|
||||
variantCss = sanitizeAcceptedSvelteCss(cssLines, variantNum, paramValues, rootTag).join('\n');
|
||||
}
|
||||
const bakedCss = bakeParamValues(variantCss, declaredParams, paramValues || {});
|
||||
const cssStats = { replaced: 0, appended: 0, pruned: [], superseded: [] };
|
||||
if (bakedCss.trim()) {
|
||||
const merged = mergeCssIntoSvelteSource(newLines.join('\n'), bakedCss);
|
||||
newLines = merged.text.split('\n');
|
||||
cssStats.replaced = merged.replaced;
|
||||
cssStats.appended = merged.appended;
|
||||
}
|
||||
|
||||
let finalText = newLines.join('\n');
|
||||
|
||||
// Preview truth: the detached preview never applied the source rules that
|
||||
// styled the replaced selection, so the user approved a design without
|
||||
// them. Any seeded selector the variant did not re-declare is superseded;
|
||||
// left in place it re-attaches through kept class names (the accepted root
|
||||
// keeps its original classes) and re-layouts markup it no longer owns.
|
||||
//
|
||||
// Removal is bounded by ownership: a selector whose classes are still used
|
||||
// by route markup OUTSIDE the replaced region does not belong to the pick
|
||||
// alone, and removing it would strip styling from markup this accept never
|
||||
// touched. Keeping it risks a visible re-attachment quirk on the accepted
|
||||
// region; deleting it breaks the rest of the route. Keep it.
|
||||
const outsideMarkup = [...sourceLines.slice(0, start), ...sourceLines.slice(end + 1)]
|
||||
.join('\n')
|
||||
.replace(/<style\b[^>]*>[\s\S]*?<\/style\s*>/gi, '');
|
||||
const outsideClasses = new Set();
|
||||
{
|
||||
const attrRe = /class\s*=\s*(["'])(.*?)\1/g;
|
||||
let cm;
|
||||
while ((cm = attrRe.exec(outsideMarkup))) {
|
||||
for (const cls of cm[2].split(/\s+/)) if (cls && !cls.includes('{')) outsideClasses.add(cls);
|
||||
}
|
||||
const directiveRe = /class:([A-Za-z0-9_-]+)/g;
|
||||
while ((cm = directiveRe.exec(outsideMarkup))) outsideClasses.add(cm[1]);
|
||||
}
|
||||
const usedOutsideReplacedRegion = (selector) => {
|
||||
const classTokenRe = /\.([A-Za-z0-9_-]+)/g;
|
||||
let tm;
|
||||
while ((tm = classTokenRe.exec(selector))) {
|
||||
if (outsideClasses.has(tm[1])) return true;
|
||||
}
|
||||
return false;
|
||||
};
|
||||
const incomingSelectors = collectAllSelectors(bakedCss);
|
||||
const superseded = (manifest.seededSelectors || [])
|
||||
.map((selector) => normalizeSelector(selector))
|
||||
.filter((selector) => selector && !incomingSelectors.has(selector) && !usedOutsideReplacedRegion(selector));
|
||||
if (superseded.length > 0) {
|
||||
const scrubbed = removeSelectorsFromSvelteSource(finalText, new Set(superseded));
|
||||
finalText = scrubbed.text;
|
||||
cssStats.superseded = scrubbed.removed;
|
||||
}
|
||||
|
||||
if (compiler) {
|
||||
const pruned = pruneUnusedSelectors(finalText, compiler.compile, { skipSelectors: preUnused });
|
||||
finalText = pruned.source;
|
||||
cssStats.pruned = pruned.removed;
|
||||
}
|
||||
|
||||
// Postcondition: no selector from the user's pre-accept CSS may vanish
|
||||
// unless the compiler-driven prune or the preview-truth supersession
|
||||
// deliberately removed it. This turns any parser or reconciler defect into
|
||||
// a loud refusal instead of silent damage to a hand-written style block.
|
||||
const lostSelectors = findLostSelectors(sourceContent, finalText, [
|
||||
...cssStats.pruned,
|
||||
...cssStats.superseded,
|
||||
]);
|
||||
if (lostSelectors.length > 0) {
|
||||
return {
|
||||
handled: false,
|
||||
error: 'CSS reconciliation would lose selectors from the existing style block: '
|
||||
+ lostSelectors.join(', ')
|
||||
+ '. Source not modified; accept the variant manually.',
|
||||
mode: 'error',
|
||||
...resultBase,
|
||||
};
|
||||
}
|
||||
|
||||
try {
|
||||
fs.writeFileSync(sourceFile, newLines.join('\n'), 'utf-8');
|
||||
fs.writeFileSync(sourceFile, finalText, 'utf-8');
|
||||
} catch (err) {
|
||||
return { handled: false, error: 'Failed to write Svelte source: ' + err.message, ...resultBase };
|
||||
}
|
||||
removeSvelteComponentSession(manifest.id, cwd);
|
||||
|
||||
const verify = verifyAcceptedSource(finalText);
|
||||
return {
|
||||
handled: true,
|
||||
css: cssStats,
|
||||
verify,
|
||||
...resultBase,
|
||||
};
|
||||
}
|
||||
|
||||
/** Re-indent a block onto `indent` while preserving its internal structure. */
|
||||
export function reindentPreservingStructure(lines, indent) {
|
||||
const nonEmpty = lines.filter((line) => line.trim() !== '');
|
||||
if (nonEmpty.length === 0) return lines.map(() => '');
|
||||
const minIndent = Math.min(...nonEmpty.map((line) => (line.match(/^\s*/) || [''])[0].length));
|
||||
return lines.map((line) => {
|
||||
if (line.trim() === '') return '';
|
||||
const current = (line.match(/^\s*/) || [''])[0].length;
|
||||
return indent + line.slice(Math.min(minIndent, current));
|
||||
});
|
||||
}
|
||||
|
||||
function styleBlockText(sourceText) {
|
||||
const match = String(sourceText || '').match(/<style\b[^>]*>([\s\S]*?)<\/style\s*>/i);
|
||||
return match ? match[1] : '';
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove every rule whose (normalized) selector list is fully contained in
|
||||
* `selectors` from the component's style block, at any at-rule nesting depth.
|
||||
* Rules that mix doomed and surviving selectors keep the survivors.
|
||||
*/
|
||||
export function removeSelectorsFromSvelteSource(sourceText, selectors) {
|
||||
const text = String(sourceText || '');
|
||||
const styleRe = /<style\b[^>]*>([\s\S]*?)<\/style\s*>/gi;
|
||||
let lastMatch = null;
|
||||
let m;
|
||||
while ((m = styleRe.exec(text))) lastMatch = m;
|
||||
if (!lastMatch) return { text, removed: [] };
|
||||
|
||||
const removed = [];
|
||||
const transform = (nodes) => {
|
||||
const kept = [];
|
||||
for (const node of nodes) {
|
||||
if (node.type === 'rule') {
|
||||
const survivors = [];
|
||||
for (const selector of splitSelectorList(node.prelude)) {
|
||||
if (selectors.has(normalizeSelector(selector))) removed.push(normalizeSelector(selector));
|
||||
else survivors.push(selector);
|
||||
}
|
||||
if (survivors.length > 0) kept.push({ ...node, prelude: survivors.join(', ') });
|
||||
} else if (node.type === 'at' && node.children) {
|
||||
const children = transform(node.children);
|
||||
if (children.length > 0) kept.push({ ...node, children });
|
||||
} else {
|
||||
kept.push(node);
|
||||
}
|
||||
}
|
||||
return kept;
|
||||
};
|
||||
|
||||
const nodes = transform(parseStylesheet(lastMatch[1]));
|
||||
if (removed.length === 0) return { text, removed };
|
||||
const openTag = lastMatch[0].slice(0, lastMatch[0].indexOf('>') + 1);
|
||||
const rebuilt = `${openTag}\n${serializeNodes(nodes).split('\n').map((l) => (l.trim() ? ' ' + l : '')).join('\n')}\n</style>`;
|
||||
return {
|
||||
text: text.slice(0, lastMatch.index) + rebuilt + text.slice(lastMatch.index + lastMatch[0].length),
|
||||
removed,
|
||||
};
|
||||
}
|
||||
|
||||
export function findLostSelectors(beforeSource, afterSource, prunedSelectors = []) {
|
||||
const before = collectAllSelectors(styleBlockText(beforeSource));
|
||||
const after = collectAllSelectors(styleBlockText(afterSource));
|
||||
const pruned = new Set((prunedSelectors || []).map((s) => normalizeSelector(s)));
|
||||
const lost = [];
|
||||
for (const selector of before) {
|
||||
if (!after.has(selector) && !pruned.has(selector)) lost.push(selector);
|
||||
}
|
||||
return lost;
|
||||
}
|
||||
|
||||
function readDeclaredParams(manifest, variantNum, cwd) {
|
||||
try {
|
||||
const raw = JSON.parse(fs.readFileSync(path.join(cwd, manifest.componentDir, 'params.json'), 'utf-8'));
|
||||
const list = raw?.[String(variantNum)];
|
||||
return Array.isArray(list) ? list : [];
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Merge CSS into a svelte component's top-level style block (created when
|
||||
* absent), replacing rules whose selectors match and appending the rest.
|
||||
*/
|
||||
export function mergeCssIntoSvelteSource(sourceText, incomingCss) {
|
||||
const text = String(sourceText || '');
|
||||
const styleRe = /<style\b[^>]*>([\s\S]*?)<\/style\s*>/gi;
|
||||
let lastMatch = null;
|
||||
let m;
|
||||
while ((m = styleRe.exec(text))) lastMatch = m;
|
||||
|
||||
if (!lastMatch) {
|
||||
const { css, replaced, appended } = reconcileCss('', incomingCss);
|
||||
return {
|
||||
text: `${text.replace(/\s*$/, '')}\n\n<style>\n${indentCssBlock(css)}\n</style>\n`,
|
||||
replaced,
|
||||
appended,
|
||||
};
|
||||
}
|
||||
|
||||
const inner = lastMatch[1];
|
||||
const { css, replaced, appended } = reconcileCss(inner, incomingCss);
|
||||
const openTag = lastMatch[0].slice(0, lastMatch[0].indexOf('>') + 1);
|
||||
const replacedBlock = `${openTag}\n${indentCssBlock(css)}\n</style>`;
|
||||
return {
|
||||
text: text.slice(0, lastMatch.index) + replacedBlock + text.slice(lastMatch.index + lastMatch[0].length),
|
||||
replaced,
|
||||
appended,
|
||||
};
|
||||
}
|
||||
|
||||
function indentCssBlock(css) {
|
||||
return String(css || '')
|
||||
.split('\n')
|
||||
.map((line) => (line.trim() === '' ? '' : ' ' + line))
|
||||
.join('\n');
|
||||
}
|
||||
|
||||
function inlineSvelteComponentInsertAccept({
|
||||
manifest,
|
||||
markup,
|
||||
@@ -601,10 +972,7 @@ function inlineSvelteComponentInsertAccept({
|
||||
|
||||
const nearbyLine = sourceLines[insertIndex] ?? sourceLines[insertIndex - 1] ?? '';
|
||||
const indent = nearbyLine.match(/^(\s*)/)?.[1] || '';
|
||||
const indentedMarkup = restoredMarkup.map((line) => {
|
||||
if (line.trim() === '') return '';
|
||||
return indent + line.trimStart();
|
||||
});
|
||||
const indentedMarkup = reindentPreservingStructure(restoredMarkup, indent);
|
||||
|
||||
let newLines = [
|
||||
...sourceLines.slice(0, insertIndex),
|
||||
@@ -612,10 +980,15 @@ function inlineSvelteComponentInsertAccept({
|
||||
...sourceLines.slice(insertIndex),
|
||||
];
|
||||
|
||||
const sanitizedCss = sanitizeAcceptedSvelteCss(cssLines, variantNum, paramValues, rootTag);
|
||||
const bakedCss = bakeParamValuesInCss(sanitizedCss, paramValues);
|
||||
if (bakedCss.length > 0) {
|
||||
newLines = appendCssToSvelteStyle(newLines, bakedCss);
|
||||
let variantCss = cssLines.join('\n');
|
||||
if (/data-impeccable-variant|impeccable-variant-ready/.test(variantCss)) {
|
||||
variantCss = sanitizeAcceptedSvelteCss(cssLines, variantNum, paramValues, rootTag).join('\n');
|
||||
}
|
||||
const declaredParams = readDeclaredParams(manifest, variantNum, cwd);
|
||||
const bakedCss = bakeParamValues(variantCss, declaredParams, paramValues || {});
|
||||
if (bakedCss.trim()) {
|
||||
const merged = mergeCssIntoSvelteSource(newLines.join('\n'), bakedCss);
|
||||
newLines = merged.text.split('\n');
|
||||
}
|
||||
|
||||
try {
|
||||
@@ -625,8 +998,10 @@ function inlineSvelteComponentInsertAccept({
|
||||
}
|
||||
removeSvelteComponentSession(manifest.id, cwd);
|
||||
|
||||
const verify = verifyAcceptedSource(newLines.join('\n'));
|
||||
return {
|
||||
handled: true,
|
||||
verify,
|
||||
...resultBase,
|
||||
};
|
||||
}
|
||||
@@ -729,18 +1104,159 @@ export function removeSvelteComponentSession(id, cwd = process.cwd()) {
|
||||
} catch { /* non-fatal */ }
|
||||
}
|
||||
|
||||
export function removeAllSvelteComponentSessions(cwd = process.cwd()) {
|
||||
const root = path.join(cwd, SVELTE_COMPONENT_ROOT);
|
||||
if (!fs.existsSync(root)) return;
|
||||
for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
|
||||
if (!entry.isDirectory()) continue;
|
||||
if (entry.name.startsWith('__')) continue;
|
||||
/**
|
||||
* Compile-check every variant component of a session with the app's own
|
||||
* compiler, BEFORE the browser ever imports them. A variant that does not
|
||||
* compile (the classic: a second top-level <style> appended next to the
|
||||
* seeded one) used to surface as a red Vite overlay in the user's page plus
|
||||
* a mount-failure round trip; bounced at publish time it is a private
|
||||
* agent-side fix with the exact file and line.
|
||||
*/
|
||||
export function compileCheckVariants(id, cwd = process.cwd()) {
|
||||
const manifest = findSvelteComponentManifest(id, cwd);
|
||||
if (!manifest || !manifest.manifestPath) return { ok: true, failures: [], checked: 0 };
|
||||
const compiler = loadSvelteCompiler(cwd);
|
||||
if (!compiler || typeof compiler.compile !== 'function') return { ok: true, failures: [], checked: 0 };
|
||||
const sessionDir = path.dirname(manifest.manifestPath);
|
||||
const failures = [];
|
||||
let checked = 0;
|
||||
let entries = [];
|
||||
try { entries = fs.readdirSync(sessionDir); } catch { return { ok: true, failures: [], checked: 0 }; }
|
||||
for (const name of entries) {
|
||||
if (!/^v\d+\.svelte$/.test(name)) continue;
|
||||
checked++;
|
||||
try {
|
||||
fs.rmSync(path.join(root, entry.name), { recursive: true, force: true });
|
||||
compiler.compile(fs.readFileSync(path.join(sessionDir, name), 'utf-8'), { generate: false });
|
||||
} catch (err) {
|
||||
failures.push({
|
||||
file: `${manifest.componentDir}/${name}`,
|
||||
line: err?.start?.line ?? null,
|
||||
column: err?.start?.column ?? null,
|
||||
message: String(err?.message || err).split('\n')[0].slice(0, 300),
|
||||
});
|
||||
}
|
||||
}
|
||||
return { ok: failures.length === 0, failures, checked };
|
||||
}
|
||||
|
||||
/**
|
||||
* Snapshot the agent-authored variant files into a fresh revision directory
|
||||
* and stamp the manifest. Called by the server on every publish (`done`
|
||||
* reply) for a component session; the browser imports from the revision dir,
|
||||
* so the dev server can never serve a stale compile of a republished file.
|
||||
*/
|
||||
export function bumpSvelteComponentPreviewRevision(id, cwd = process.cwd()) {
|
||||
const manifest = findSvelteComponentManifest(id, cwd);
|
||||
if (!manifest || !manifest.manifestPath) return null;
|
||||
const sessionDir = path.dirname(manifest.manifestPath);
|
||||
const revision = Number(manifest.revision || 0) + 1;
|
||||
const revDirName = `r${revision}`;
|
||||
const revDir = path.join(sessionDir, revDirName);
|
||||
try {
|
||||
fs.mkdirSync(revDir, { recursive: true });
|
||||
let entries = [];
|
||||
try { entries = fs.readdirSync(sessionDir, { withFileTypes: true }); } catch { /* empty */ }
|
||||
for (const entry of entries) {
|
||||
if (!entry.isFile()) continue;
|
||||
if (entry.name === 'manifest.json') continue;
|
||||
fs.copyFileSync(path.join(sessionDir, entry.name), path.join(revDir, entry.name));
|
||||
}
|
||||
// Previous revision dirs are dead the moment a new one exists.
|
||||
for (const entry of entries) {
|
||||
if (entry.isDirectory() && /^r\d+$/.test(entry.name) && entry.name !== revDirName) {
|
||||
try { fs.rmSync(path.join(sessionDir, entry.name), { recursive: true, force: true }); } catch { /* non-fatal */ }
|
||||
}
|
||||
}
|
||||
const relSessionDir = path.relative(cwd, sessionDir).split(path.sep).join('/');
|
||||
const updated = {
|
||||
...manifest,
|
||||
revision,
|
||||
revisionDir: `${relSessionDir}/${revDirName}`,
|
||||
revisionDirAbs: revDir.split(path.sep).join('/'),
|
||||
};
|
||||
delete updated.manifestPath;
|
||||
fs.writeFileSync(manifest.manifestPath, JSON.stringify(updated, null, 2) + '\n', 'utf-8');
|
||||
return { revision, revisionDir: updated.revisionDir };
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Stop-path sweep. The whole `node_modules/.impeccable-live` tree is
|
||||
* impeccable-owned and gitignored, so once no session should survive there is
|
||||
* nothing left worth keeping: the per-session dirs, the generated
|
||||
* `__runtime.js`, and the parent directory all go. The old per-entry loop
|
||||
* skipped `__*` entries and the parent, which left the runtime shim and an
|
||||
* empty directory in every project that ever ran live mode once.
|
||||
*/
|
||||
export function removeAllSvelteComponentSessions(cwd = process.cwd()) {
|
||||
for (const rootRel of [SVELTE_COMPONENT_ROOT, LEGACY_SVELTE_COMPONENT_ROOT]) {
|
||||
const root = path.join(cwd, rootRel);
|
||||
if (!fs.existsSync(root)) continue;
|
||||
try {
|
||||
fs.rmSync(root, { recursive: true, force: true });
|
||||
} catch { /* non-fatal */ }
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Boot-path sweep. A restart must not delete the tree wholesale: sessions
|
||||
* recorded in the session store may still be mid-generation. Remove only the
|
||||
* session dirs whose id has no active snapshot, then drop `__runtime.js` and
|
||||
* the parent directory when nothing is left to serve.
|
||||
*
|
||||
* @param {Iterable<string>} activeIds session ids that must be preserved
|
||||
* @returns {{ removed: string[], removedRoot: boolean, kept: string[] }}
|
||||
*/
|
||||
export function sweepInactiveSvelteComponentSessions(activeIds = [], cwd = process.cwd()) {
|
||||
const result = { removed: [], removedRoot: false, kept: [] };
|
||||
const active = new Set();
|
||||
for (const id of activeIds || []) {
|
||||
if (typeof id === 'string' && id) active.add(id);
|
||||
}
|
||||
|
||||
for (const rootRel of [SVELTE_COMPONENT_ROOT, LEGACY_SVELTE_COMPONENT_ROOT]) {
|
||||
const root = path.join(cwd, rootRel);
|
||||
if (!fs.existsSync(root)) continue;
|
||||
|
||||
let entries;
|
||||
try {
|
||||
entries = fs.readdirSync(root, { withFileTypes: true });
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
|
||||
let keptHere = 0;
|
||||
for (const entry of entries) {
|
||||
if (!entry.isDirectory()) continue;
|
||||
if (entry.name.startsWith('__')) continue;
|
||||
if (active.has(entry.name)) {
|
||||
result.kept.push(entry.name);
|
||||
keptHere++;
|
||||
continue;
|
||||
}
|
||||
try {
|
||||
fs.rmSync(path.join(root, entry.name), { recursive: true, force: true });
|
||||
result.removed.push(entry.name);
|
||||
} catch {
|
||||
// Could not remove it, so it still occupies the tree; treat it as kept
|
||||
// so the parent directory is not torn out from under it.
|
||||
result.kept.push(entry.name);
|
||||
keptHere++;
|
||||
}
|
||||
}
|
||||
|
||||
if (keptHere === 0) {
|
||||
try {
|
||||
fs.rmSync(root, { recursive: true, force: true });
|
||||
result.removedRoot = true;
|
||||
} catch { /* non-fatal */ }
|
||||
}
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
export function deferredAcceptsPath(cwd = process.cwd()) {
|
||||
const key = createHash('sha1').update(path.resolve(cwd)).digest('hex').slice(0, 16);
|
||||
return path.join(os.tmpdir(), 'impeccable-live', key, 'deferred-svelte-component-accepts.json');
|
||||
|
||||
@@ -7,6 +7,7 @@
|
||||
* actual live UI remains the shared plain-DOM browser chrome.
|
||||
*/
|
||||
|
||||
import crypto from 'node:crypto';
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
@@ -14,6 +15,28 @@ export const SVELTE_LIVE_ROOT_COMPONENT = 'src/lib/impeccable/ImpeccableLiveRoot
|
||||
export const SVELTE_LAYOUT_MARKER_OPEN = '<!-- impeccable-live-svelte-start -->';
|
||||
export const SVELTE_LAYOUT_MARKER_CLOSE = '<!-- impeccable-live-svelte-end -->';
|
||||
export const SVELTE_ROOT_IMPORT = "import ImpeccableLiveRoot from '$lib/impeccable/ImpeccableLiveRoot.svelte';";
|
||||
// Matches the import at ANY revision (or none). [ \t]* bounds only, never
|
||||
// \s*: a greedy \s* after the statement swallowed the next line's
|
||||
// indentation on removal, leaving a formatting scar in user layouts.
|
||||
const SVELTE_ROOT_IMPORT_LINE_RE = /^[ \t]*import ImpeccableLiveRoot from '\$lib\/impeccable\/ImpeccableLiveRoot\.svelte(?:\?[^']*)?';[ \t]*\r?\n?/gm;
|
||||
|
||||
/**
|
||||
* The import specifier carries a token-derived revision query. The adapter
|
||||
* component embeds the helper token, and Vite (client AND SSR) can keep
|
||||
* serving a stale compiled module after the file is rewritten on a helper
|
||||
* restart; the browser then requests /live.js with a rotated-out token and
|
||||
* gets a 401 with no picker. A changed specifier is a different module id,
|
||||
* which no cache survives.
|
||||
*/
|
||||
export function svelteRootImportLine(rev) {
|
||||
if (!rev) return SVELTE_ROOT_IMPORT;
|
||||
return "import ImpeccableLiveRoot from '$lib/impeccable/ImpeccableLiveRoot.svelte?impeccable-live=" + rev + "';";
|
||||
}
|
||||
|
||||
export function svelteAdapterRev(token) {
|
||||
if (!token) return null;
|
||||
return crypto.createHash('sha256').update(String(token)).digest('hex').slice(0, 8);
|
||||
}
|
||||
|
||||
export function detectSvelteKitProject(cwd = process.cwd(), config = null) {
|
||||
const appHtml = findSvelteKitAppHtml(cwd, config);
|
||||
@@ -50,7 +73,7 @@ export function applySvelteKitLiveAdapter({ cwd = process.cwd(), port, token, co
|
||||
fs.mkdirSync(path.dirname(layoutAbs), { recursive: true });
|
||||
const layoutExisted = fs.existsSync(layoutAbs);
|
||||
const before = layoutExisted ? fs.readFileSync(layoutAbs, 'utf-8') : defaultSvelteLayout();
|
||||
const after = patchSvelteLayout(before);
|
||||
const after = patchSvelteLayout(before, { rev: svelteAdapterRev(token) });
|
||||
fs.writeFileSync(layoutAbs, after, 'utf-8');
|
||||
|
||||
return {
|
||||
@@ -94,15 +117,27 @@ export function removeSvelteKitLiveAdapter({ cwd = process.cwd(), config = null
|
||||
};
|
||||
}
|
||||
|
||||
export function patchSvelteLayout(content) {
|
||||
export function patchSvelteLayout(content, { rev = null } = {}) {
|
||||
let out = String(content || '');
|
||||
if (!out.includes(SVELTE_ROOT_IMPORT)) {
|
||||
const scriptMatch = out.match(/<script(?:\s[^>]*)?>/i);
|
||||
if (scriptMatch) {
|
||||
const insertAt = scriptMatch.index + scriptMatch[0].length;
|
||||
out = out.slice(0, insertAt) + '\n ' + SVELTE_ROOT_IMPORT + out.slice(insertAt);
|
||||
} else {
|
||||
out = `<script>\n ${SVELTE_ROOT_IMPORT}\n</script>\n\n` + out;
|
||||
const importLine = svelteRootImportLine(rev);
|
||||
if (!out.includes(importLine)) {
|
||||
// An import at an older revision is replaced in place, keeping its
|
||||
// indentation; only a layout with no impeccable import gets an insert.
|
||||
let replaced = false;
|
||||
out = out.replace(SVELTE_ROOT_IMPORT_LINE_RE, (line) => {
|
||||
if (replaced) return '';
|
||||
replaced = true;
|
||||
const indent = (line.match(/^[ \t]*/) || [''])[0];
|
||||
return indent + importLine + '\n';
|
||||
});
|
||||
if (!replaced) {
|
||||
const scriptMatch = out.match(/<script(?:\s[^>]*)?>/i);
|
||||
if (scriptMatch) {
|
||||
const insertAt = scriptMatch.index + scriptMatch[0].length;
|
||||
out = out.slice(0, insertAt) + '\n ' + importLine + out.slice(insertAt);
|
||||
} else {
|
||||
out = `<script>\n ${importLine}\n</script>\n\n` + out;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -131,8 +166,8 @@ export function unpatchSvelteLayout(content) {
|
||||
'g',
|
||||
);
|
||||
out = out.replace(blockRe, '$1');
|
||||
out = out.replace(new RegExp('^\\s*' + escapeRegExp(SVELTE_ROOT_IMPORT) + '\\s*\\n?', 'gm'), '');
|
||||
out = out.replace(/<script>\s*<\/script>\s*\n?/g, '');
|
||||
out = out.replace(SVELTE_ROOT_IMPORT_LINE_RE, '');
|
||||
out = out.replace(/<script>\s*<\/script>[ \t]*\r?\n?/g, '');
|
||||
return out.replace(/\n{3,}/g, '\n\n');
|
||||
}
|
||||
|
||||
@@ -193,6 +228,11 @@ export function buildSvelteLiveRootComponent(port, token) {
|
||||
script.src = LIVE_URL;
|
||||
script.async = true;
|
||||
script.dataset.impeccableLiveScript = 'true';
|
||||
script.onerror = () => console.error(
|
||||
'[impeccable] live.js failed to load from ' + LIVE_URL
|
||||
+ ' (helper down, or the token rotated while a stale adapter module was cached).'
|
||||
+ ' Re-run the live boot, then reload this page.'
|
||||
);
|
||||
document.head.appendChild(script);
|
||||
|
||||
return () => {
|
||||
|
||||
@@ -19,7 +19,7 @@
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { buildLiveScriptSrc } from '../live-inject.mjs';
|
||||
import { buildLiveScriptSrc } from './frameworks/script-src.mjs';
|
||||
|
||||
export const TANSTACK_MARKER_OPEN = '{/* impeccable-live-tanstack-start */}';
|
||||
export const TANSTACK_MARKER_CLOSE = '{/* impeccable-live-tanstack-end */}';
|
||||
|
||||
@@ -34,3 +34,138 @@ export const LIVE_COMMANDS = [
|
||||
|
||||
// Action values accepted by the live event protocol, in palette order.
|
||||
export const VISUAL_ACTIONS = LIVE_COMMANDS.map((c) => c.value);
|
||||
|
||||
/*
|
||||
* ---------------------------------------------------------------------------
|
||||
* Protocol vocabulary
|
||||
* ---------------------------------------------------------------------------
|
||||
* The enums below are the wire contract between the browser overlay, the live
|
||||
* helper server, and the durable session journal. They live here rather than in
|
||||
* the modules that use them so a value cannot be added to the validator without
|
||||
* the store and the server seeing it too.
|
||||
*
|
||||
* live-browser.js still cannot import this file (it is served raw and injected
|
||||
* as an IIFE), so its local phase table repeats the agent-phase names. Anything
|
||||
* the server can broadcast must appear in AGENT_PHASES here first.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Phases the live server broadcasts as `agent_phase`, in lifecycle order.
|
||||
* Every one of these is emitted by `recordAgentPhase()` in live-server.mjs;
|
||||
* the validator rejects anything else, so a typo in a phase name fails loudly
|
||||
* instead of quietly ranking as an unknown phase in the browser's progress bar.
|
||||
*/
|
||||
export const AGENT_PHASES = Object.freeze([
|
||||
'picked_up',
|
||||
'scaffolding',
|
||||
'source_ready',
|
||||
'scaffold_fallback',
|
||||
'generation_ready',
|
||||
'first_reviewable',
|
||||
'second_reviewable',
|
||||
'all_variants_ready',
|
||||
]);
|
||||
|
||||
/** Event types the helper server accepts from the browser over POST /events. */
|
||||
export const CLIENT_EVENT_TYPES = Object.freeze([
|
||||
'generate',
|
||||
'accept',
|
||||
'discard',
|
||||
'checkpoint',
|
||||
'agent_phase',
|
||||
'variant_mounted',
|
||||
'variant_mount_failed',
|
||||
'exit',
|
||||
'prefetch',
|
||||
'manual_edits',
|
||||
'steer',
|
||||
'carbonize_cleanup',
|
||||
]);
|
||||
|
||||
/**
|
||||
* Event types the durable journal applies. A superset of CLIENT_EVENT_TYPES:
|
||||
* the agent-side helpers (live-poll, live-complete) and the server itself
|
||||
* append the rest. An event type missing here lands as `unknown_event_type`
|
||||
* in the snapshot diagnostics.
|
||||
*/
|
||||
export const JOURNAL_EVENT_TYPES = Object.freeze([
|
||||
'generate',
|
||||
'variant_plan',
|
||||
'detector_waivers',
|
||||
'agent_phase',
|
||||
'variants_ready',
|
||||
'agent_done',
|
||||
'variant_mounted',
|
||||
'variant_mount_failed',
|
||||
'checkpoint',
|
||||
'accept',
|
||||
'accept_intent',
|
||||
'manual_edit_apply',
|
||||
'steer',
|
||||
'steer_done',
|
||||
'carbonize_cleanup',
|
||||
'discard',
|
||||
'discarded',
|
||||
'complete',
|
||||
'agent_error',
|
||||
]);
|
||||
|
||||
/** Phases the session store assigns to a snapshot. */
|
||||
export const SESSION_PHASES = Object.freeze([
|
||||
'new',
|
||||
'generate_requested',
|
||||
'variants_ready',
|
||||
'carbonize_required',
|
||||
'carbonize_cleanup_requested',
|
||||
'manual_edit_apply_requested',
|
||||
'steer_requested',
|
||||
'steer_done',
|
||||
'accept_requested',
|
||||
'discard_requested',
|
||||
'discarded',
|
||||
'completed',
|
||||
'agent_error',
|
||||
]);
|
||||
|
||||
/** Phases that retire a session from the active list. */
|
||||
export const COMPLETED_SESSION_PHASES = Object.freeze(['completed', 'discarded']);
|
||||
|
||||
/**
|
||||
* Phases after which a late generation write is a ghost from a canceled cycle.
|
||||
* The store journals such an event as a diagnostic instead of applying it.
|
||||
*/
|
||||
export const GENERATION_FENCED_SESSION_PHASES = Object.freeze([
|
||||
'accept_requested',
|
||||
'discard_requested',
|
||||
'carbonize_required',
|
||||
'completed',
|
||||
'discarded',
|
||||
]);
|
||||
|
||||
/**
|
||||
* `reason` values carried on checkpoint events. Not validated (an unknown
|
||||
* reason is journaled, never rejected) because the reason is diagnostic
|
||||
* breadcrumb, not control flow. Two exceptions drive behavior and are split
|
||||
* out below.
|
||||
*/
|
||||
export const CHECKPOINT_REASONS = Object.freeze([
|
||||
'generate_started',
|
||||
'variants_progress',
|
||||
'variants_ready',
|
||||
'browser_resumed',
|
||||
'browser_resumed_svelte_component',
|
||||
'param_changed',
|
||||
'variant_anchor_missing',
|
||||
'component_preview_anchor_missing',
|
||||
'steer_input_focused',
|
||||
'steer_submitted',
|
||||
'steer_send_failed',
|
||||
'steer_done',
|
||||
'steer_error',
|
||||
]);
|
||||
|
||||
/** Checkpoint reasons the server reads as variant-publication progress. */
|
||||
export const VARIANT_PROGRESS_CHECKPOINT_REASONS = Object.freeze([
|
||||
'variants_progress',
|
||||
'variants_ready',
|
||||
]);
|
||||
|
||||
@@ -0,0 +1,102 @@
|
||||
One-time live-mode project setup. Loaded from [live.md](live.md) only when `live.mjs` reports `config_missing` / `config_invalid`, when `configDrift` needs handling, or when the config lacks `cspChecked`. Not part of the per-session hot path.
|
||||
|
||||
## Write the config
|
||||
|
||||
Create the file at the `path` the boot reported (default `.impeccable/live/config.json`):
|
||||
|
||||
```json
|
||||
{
|
||||
"files": ["<path-or-glob>", "<path-or-glob>", ...],
|
||||
"exclude": ["<optional-glob>", ...],
|
||||
"insertBefore": "</body>",
|
||||
"commentSyntax": "html",
|
||||
"cspChecked": true
|
||||
}
|
||||
```
|
||||
|
||||
`files` is the inject target: **the HTML files the browser actually loads**, not necessarily source (tracked vs generated does not matter here; wrap has its own generated-file guard). Entries are literal paths or globs. `exclude` (optional) skips files a `files` glob would otherwise include (email templates, demo fixtures). `cspChecked` records that the CSP step below has run; absent on first setup.
|
||||
|
||||
**Hard-excluded paths (cannot be overridden):** `**/node_modules/**` and `**/.git/**`; injecting there would instrument third-party code.
|
||||
|
||||
**Glob syntax:** `**` matches any number of segments (including zero), `*` matches within a segment, `?` matches one character. Paths are project-root-relative with forward slashes.
|
||||
|
||||
| Framework | `files` | `insertBefore` | `commentSyntax` |
|
||||
|-----------|---------|----------------|-----------------|
|
||||
| SPA with single shell (Vite / React / Plain HTML) | `["index.html"]` | `</body>` | `html` |
|
||||
| Next.js (App Router) | `["app/layout.tsx"]` | `</body>` | `jsx` |
|
||||
| Next.js (Pages) | `["pages/_document.tsx"]` | `</body>` | `jsx` |
|
||||
| Nuxt | `["app.vue"]` | `</body>` | `html` |
|
||||
| Svelte / SvelteKit | `["src/app.html"]` | `</body>` | `html` |
|
||||
| TanStack Router (SPA, Vite) | `["index.html"]` | `</body>` | `html` |
|
||||
| TanStack Start (SSR) | `["src/routes/__root.tsx"]` | `<Scripts` | `jsx` |
|
||||
| Astro | `[" <root layout .astro>"]` | `</body>` | `html` |
|
||||
| Multi-page (separate HTML per route) | `["public/**/*.html"]` glob over the served dir | `</body>` | `html` |
|
||||
|
||||
Pick an anchor that exists in every file (`</body>` almost always works); `insertAfter` matches after a line instead. For multi-page sites prefer a glob so new pages are picked up automatically. For sites whose pages are rebuilt by a generator, the inject survives only until the next regeneration: re-run `live.mjs` after each build (accept is unaffected; it writes true source via the fallback flow).
|
||||
|
||||
**Framework adapters (auto-detected at inject time).** Every inject records what it wrote in `.impeccable/live/inject-journal.json`; the next inject or remove heals artifacts a crash or wrong-directory stop left behind. SvelteKit, Nuxt, and TanStack Start server-render their document shell, so a raw `<script>` in the entry template will not execute reliably; `live-inject.mjs` detects them and routes to a dedicated adapter (SvelteKit: dev-only root component from `+layout.svelte`; Nuxt: dev-only `.client.ts` plugin; TanStack Start: a generated dev-only `ImpeccableLiveRoot` component in `__root`). The `files` value stays a valid detection/CSP hint but is not the literal insertion site. A plain TanStack Router SPA takes the baseline Vite path.
|
||||
|
||||
## Config drift
|
||||
|
||||
On every boot the project is scanned for HTML files under common page roots (`public/`, `src/`, `app/`, `pages/`) that the resolved `files` list does not cover; they surface as `configDrift.orphans` with a hint. Tell the user once per session which files are uncovered and offer to add them or switch `files` to a glob. Never auto-update the config; the user decides. `configDrift` is `null` when there is no drift.
|
||||
|
||||
## CSP detection (first-time only)
|
||||
|
||||
If `config.cspChecked === true`, skip this whole section; the user was already asked once.
|
||||
|
||||
```bash
|
||||
node .cursor/skills/impeccable/scripts/detect-csp.mjs
|
||||
```
|
||||
|
||||
Output `{ shape, signals }`; the shape names the *patch mechanism*, so one template covers many frameworks:
|
||||
|
||||
- **`null`**: no CSP; write the config with `cspChecked: true` and stop here.
|
||||
- **`append-arrays`**: CSP as structured directive arrays; auto-patchable (monorepo helpers with `additionalScriptSrc`/`additionalConnectSrc`, SvelteKit `kit.csp.directives`, Nuxt `nuxt-security`).
|
||||
- **`append-string`**: CSP as a literal value string; auto-patchable (inline `next.config.*` `headers()`, Nuxt `routeRules`).
|
||||
- **`middleware`** / **`meta-tag`**: detected but not auto-patched. Show the user the detected files, ask them to add `http://localhost:8400` to `script-src` and `connect-src` manually, then mark `cspChecked: true` and proceed.
|
||||
|
||||
### Consent prompt (use this phrasing)
|
||||
|
||||
> **CSP patch needed.** I detected a Content Security Policy in your project that blocks `http://localhost:8400`: the live picker won't load without an allowance. Here's the change I'd make:
|
||||
>
|
||||
> ```diff
|
||||
> [file: <patchTarget>]
|
||||
> [exact diff, 2-5 lines]
|
||||
> ```
|
||||
>
|
||||
> It's guarded by `NODE_ENV === "development"` so the extra entry only appears in dev and never reaches production. You can remove it any time by reverting this file. Apply? [y/n]
|
||||
|
||||
On "no": skip the patch, note that live will not work until the allowance is added manually, and still write `cspChecked: true` (the question has been asked). On "yes": apply the shape's patch below, then write `cspChecked: true`.
|
||||
|
||||
### append-arrays
|
||||
|
||||
Declare near the top of the file that holds the CSP arrays, then append `...__impeccableLiveDev` to the script-src and connect-src arrays:
|
||||
|
||||
```ts
|
||||
// Dev-only allowance so impeccable live mode can load. Guarded by NODE_ENV.
|
||||
const __impeccableLiveDev =
|
||||
process.env.NODE_ENV === "development" ? ["http://localhost:8400"] : [];
|
||||
```
|
||||
|
||||
Per-framework: Next.js + monorepo helper: edit the *app's* `next.config.*` (not the shared helper), appending to `additionalScriptSrc` / `additionalConnectSrc`. SvelteKit: `svelte.config.js`, `kit.csp.directives['script-src']` and `['connect-src']`. Nuxt + nuxt-security: `nuxt.config.*`, `security.headers.contentSecurityPolicy['script-src']` and `['connect-src']`. Reference outputs: `tests/framework-fixtures/nextjs-turborepo/expected-after-patch.ts`, `tests/framework-fixtures/sveltekit-csp/expected-after-patch.js`. Idempotency: if `__impeccableLiveDev` already exists in the file, the patch is applied; just mark `cspChecked: true`.
|
||||
|
||||
### append-string
|
||||
|
||||
Two-point patch: declare a dev-only string, interpolate it into the CSP value at both directives (leading space so it concatenates cleanly; convert literals to template strings as part of the edit):
|
||||
|
||||
```ts
|
||||
// Dev-only allowance so impeccable live mode can load.
|
||||
const __impeccableLiveDev =
|
||||
process.env.NODE_ENV === "development" ? " http://localhost:8400" : "";
|
||||
```
|
||||
|
||||
- `script-src 'self' 'unsafe-inline'` becomes `` `script-src 'self' 'unsafe-inline'${__impeccableLiveDev}` ``
|
||||
- `connect-src 'self'` becomes `` `connect-src 'self'${__impeccableLiveDev}` ``
|
||||
|
||||
Per-framework: Next.js inline `headers()` in `next.config.*`; Nuxt `routeRules['/**'].headers['Content-Security-Policy']` in `nuxt.config.*`. Reference outputs: `tests/framework-fixtures/nextjs-inline-csp/expected-after-patch.js`, `tests/framework-fixtures/nuxt-csp/expected-after-patch.ts`.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If the user said "no" to the CSP patch and later reports live not working: their dev CSP blocks `http://localhost:8400`. Delete `cspChecked` from `.impeccable/live/config.json` and re-run `live.mjs`; setup asks again.
|
||||
|
||||
After setup, re-run `live.mjs`.
|
||||
@@ -2,50 +2,33 @@ Interactive live variant mode: select elements in the browser, pick a design act
|
||||
|
||||
## Prerequisites
|
||||
|
||||
A running dev server with hot module replacement (Vite, Next.js, Bun, etc.), OR a static HTML file open in the browser.
|
||||
A running dev server with HMR (Vite, Next.js, Bun, etc.), OR a static HTML file open in the browser. If the dev server's default port is busy, the app is very likely ALREADY running; probe the default URL before spawning a second server.
|
||||
|
||||
## The contract (read once)
|
||||
|
||||
Execute in order. No step skipped, no step reordered.
|
||||
Execute in order. No step skipped, no step reordered. Every tool output in live mode may carry an `_instructions` field: it is the authoritative next step for that exact situation, with real ids and paths substituted; when it conflicts with your recollection of this document, `_instructions` wins.
|
||||
|
||||
1. `live.mjs`: boot. If the request names or implies a file, route, or app inside a monorepo, infer the concrete path and run `node .cursor/skills/impeccable/scripts/live.mjs --target <path>` instead; then run the rest of this live session from the returned `projectRoot`.
|
||||
1. `live.mjs`: boot. If the request names or implies a file, route, or app inside a monorepo, infer the concrete path and run `node .cursor/skills/impeccable/scripts/live.mjs --target <path>` instead; then run the rest of this live session from the returned `projectRoot`. The boot resolves the app root from dev-server config files and persists it in `.impeccable/live/roots.json`; every helper re-anchors to that manifest at startup (a wrong cwd cannot fork session state), PRODUCT.md / DESIGN.md are discovered upward to the git root, and relative helper args like `--file` resolve against the app root.
|
||||
2. Open the app URL that serves `pageFile` (infer from `package.json`, docs, terminal output, or an open tab). Never use `serverPort`; it's the helper, not the app. **Cursor:** `browser_navigate` to that URL before polling; do not skip. **Other harnesses:** use the available browser tool; if the URL is uncertain, ask the user once.
|
||||
3. Poll loop with the default long timeout (600000 ms). Run `live-poll.mjs` again immediately after every event or `--reply`; Codex runs this one-shot poll in the foreground. Never pass a short `--timeout=`.
|
||||
|
||||
The global bar **Impeccable mark** dims and shows a pulsing amber dot when no agent is long-polling `/poll`. Hover the mark for the hint; restart `live-poll.mjs` to reconnect.
|
||||
4. On `generate`: reuse `event.scaffold` when present; read the screenshot if present; load the action's reference; deliver variants using the delivery policy below; `--reply done`; poll again. Generate in this thread. You already hold the project's tokens, conventions, and file layout; that context is the job, not overhead. During a live cycle the overlay's preview IS the verification channel: the user sees every variant rendered in their real page and picks. Do not screenshot, re-render, or QA variants between generate and accept; apply craft-floor's contrast, spacing, and type floors by construction as you write, not as a post-write inspection pass. Full verification, computed contrast, breakpoints, real-copy overflow, runs once at accept on the chosen variant during carbonize cleanup.
|
||||
5. On `steer`: read the message and `pageUrl`; do the work (page edits, navigation help, or a short reply in the `--reply` message); `--reply steer_done`; poll again. No pickup ack. The Steer bar unlocks when `steer_done` arrives over SSE.
|
||||
6. On `accept` / `discard`: the poll script runs `live-accept.mjs`, acknowledges the delivered event, and prints `_completionAck`. Plain accepts/discards are terminal immediately. Carbonize accepts remain recoverable until the foreground task runs `live-complete.mjs --id EVENT_ID`; finish that cleanup before polling again.
|
||||
7. If interrupted, run `live-status.mjs` or `live-resume.mjs` before guessing. The durable journal replays unacknowledged work after helper restart. A dropped SSE connection or a closed tab does not end the session: the journal under `.impeccable/live/sessions/` is canonical, the injected `live.js` re-attaches when the page reopens, and `live-resume.mjs` replays the active snapshot. Tell the user to reopen the app URL (or restart `live-poll.mjs`) and continue; fall back to the direct-edit loop only when `live-resume.mjs` reports no active session, never because disconnects felt frequent.
|
||||
3. Poll loop with the default long timeout (600000 ms). Run `live-poll.mjs` again immediately after every event or `--reply`; Codex runs this one-shot poll in the foreground. Never pass a short `--timeout=`. The global bar's **Impeccable mark** dims with a pulsing amber dot when nothing is polling `/poll`; restart `live-poll.mjs` to reconnect.
|
||||
4. On `generate`: reuse `event.scaffold` when present; read the screenshot if present; load the action's reference; deliver variants; `--reply done`; poll again. Generate in this thread: you already hold the project's tokens and layout. The overlay preview IS the verification channel; do not screenshot, re-render, or QA variants between generate and accept. Apply craft-floor's contrast, spacing, and type floors by construction as you write; full verification runs once at accept on the chosen variant.
|
||||
5. On `steer`: read the message and `pageUrl`; do the work; `--reply steer_done`; poll again. No pickup ack.
|
||||
6. On `accept` / `discard`: the poll script runs `live-accept.mjs`, acknowledges delivery, and prints `_completionAck`. Plain accepts/discards are terminal immediately; carbonize accepts stay recoverable until `live-complete.mjs --id EVENT_ID` runs. Finish that cleanup before polling again.
|
||||
7. If interrupted, run `live-status.mjs` or `live-resume.mjs` before guessing. The journal under `.impeccable/live/sessions/` is canonical and replays unacknowledged work after a helper restart; the injected `live.js` re-attaches when the page reopens. Fall back to the direct-edit loop only when `live-resume.mjs` reports no active session, never because disconnects felt frequent.
|
||||
8. On `exit`: run the cleanup at the bottom.
|
||||
|
||||
Harness policy:
|
||||
- **Claude Code**: run the poll as a **background task** (no short timeout). The harness notifies you when it completes, so the main conversation stays free while you generate and publish in it. Do not block the shell.
|
||||
- **Cursor**: run **one-shot** poll in a **background terminal** with notify on `"type":"(steer|generate|accept|discard|exit)"`. After each event the poll exits; handle it, `--reply`, then start `live-poll.mjs` again. Do **not** use `--stream` on Cursor: incremental stdout notify is slower in practice than exit-based notify (~5s vs sub-second in testing).
|
||||
- **Codex**: run the default one-shot poll in a **yielded foreground exec session**. Do not suffix it with `&`, use `--stream`, or leave Live without an active foreground poll. Handle every event in the main task; after each handler/reply, restart the foreground poll.
|
||||
- **Other harnesses**: one-shot foreground unless you know stdout reliably returns to this session when a shell exits.
|
||||
- **Claude Code**: run the poll as a **background task** (no short timeout); the harness notifies you on completion. Do not block the shell.
|
||||
- **Cursor**: **one-shot** poll in a **background terminal** with notify on `"type":"(steer|generate|accept|discard|manual_edit_apply|variant_mount_failed|prefetch|exit)"`; handle, `--reply`, restart the poll. Do **not** use `--stream` on Cursor (measured ~5s pickup vs sub-second one-shot).
|
||||
- **Codex**: default one-shot poll in a **yielded foreground exec session**. No `&`, no `--stream`, never leave Live without an active foreground poll. Starting the poll is not enough: SERVICE it (keep reading the exec session until it returns an event). Never announce "waiting for the user" and idle; a yielded poll nobody reads is a dead session, and the user's Go sits unanswered.
|
||||
- **Other harnesses**: one-shot foreground unless you know stdout reliably returns when a shell exits.
|
||||
|
||||
Generation delivery policy:
|
||||
- **Default (Cursor and other harnesses):** keep the established atomic single-edit delivery. Do not switch a harness to progressive until its poll loop is known not to block on the extra publish calls. This avoids trading model latency for extra tool-call latency on harnesses with different streaming behavior.
|
||||
Delivery policy: atomic single-edit delivery everywhere; do not switch a harness to progressive publishing unless its poll loop is known not to block on the extra calls.
|
||||
|
||||
Chat is overhead. No recap, no tutorial output, no pasting PRODUCT / DESIGN bodies. Spend tokens on tools and edits; on failure, one or two short sentences.
|
||||
|
||||
## Start
|
||||
|
||||
```bash
|
||||
node .cursor/skills/impeccable/scripts/live.mjs
|
||||
```
|
||||
|
||||
Output JSON: `{ ok, serverPort, serverToken, pageFiles, hasProduct, product, productPath, hasDesign, design, designPath }`. `pageFiles` is the list of HTML entries the live script was injected into. Keep PRODUCT.md, DESIGN.md, and any surface brief already loaded by Setup in mind for variant generation: **DESIGN.md wins on visual decisions; PRODUCT.md wins on durable product and voice decisions; the surface brief wins on this surface's strategy.** When DESIGN.md is missing, identity is **not** absent; extract it from CSS variables, computed styles, and sibling components on the page (see Step 4 Phase A). Identity preservation is the default; departure requires the user's explicit redesign/replacement intent.
|
||||
|
||||
`serverPort` and `serverToken` belong to the small **Impeccable live helper** HTTP server (serves `/live.js`, SSE, and `/poll`). That port is **not** your dev server and is usually not the URL you open to view the app. The browser page is whatever origin serves one of the `pageFiles` entries (Vite / Next / Bun / tunnel / LAN hostname).
|
||||
|
||||
If output is `{ ok: false, error: "config_missing" | "config_invalid", path }`, this project hasn't been configured for live mode (or its config is stale). See **First-time setup** at the bottom.
|
||||
|
||||
## Poll loop
|
||||
|
||||
**Default (portable, all harnesses):**
|
||||
|
||||
```
|
||||
LOOP:
|
||||
node .cursor/skills/impeccable/scripts/live-poll.mjs # default long timeout; no --timeout=
|
||||
@@ -57,253 +40,143 @@ LOOP:
|
||||
"discard" → Handle Discard; LOOP
|
||||
"prefetch" → Handle Prefetch; LOOP
|
||||
"manual_edit_apply" → Handle Manual Edit Apply; reply done|partial|error; LOOP
|
||||
"variant_mount_failed" → Fix the variant files; reply done --file <path>; LOOP
|
||||
"timeout" → LOOP
|
||||
"exit" → break → Cleanup
|
||||
```
|
||||
|
||||
**Stream mode (experimental, not for Cursor):**
|
||||
`variant_mount_failed` means the browser could not render what you published (`variant`, module `url`, `error`). The user sees a persistent error card, not variants. Fix the variant files, then `--reply EVENT_ID done --file <manifest or source path>`; the browser retries on its own.
|
||||
|
||||
```
|
||||
node .cursor/skills/impeccable/scripts/live-poll.mjs --stream # stays running; one JSON line per event
|
||||
Handle event; run --reply in a separate command
|
||||
Repeat until "exit" line → Cleanup
|
||||
**Stream mode** (`--stream`, experimental, never on Cursor): one long-lived process, one JSON line per event, `--reply` from a separate command. Only for harnesses that read incremental stdout reliably.
|
||||
|
||||
## Start
|
||||
|
||||
```bash
|
||||
node .cursor/skills/impeccable/scripts/live.mjs
|
||||
```
|
||||
|
||||
Stream keeps one process alive and waits for `--reply` ack before polling again. Useful only when the harness reads incremental stdout reliably and quickly. **Cursor is not one of those:** background pattern notify on a long-running shell was ~5s to pick up events vs sub-second for one-shot exit notify. Default to one-shot everywhere unless you have measured otherwise.
|
||||
Output JSON: `{ ok, serverPort, serverToken, pageFiles, roots, hasProduct, product, productPath, hasDesign, design, designPath, hasSurfaceBrief, surfaceBrief }`. `roots` is the resolved root manifest; `projectRoot` mirrors `roots.appRoot`. The surface brief rides along; do not shell out to `surface-brief.mjs` separately. Precedence for generation: **DESIGN.md wins on visual decisions; PRODUCT.md wins on durable product and voice decisions; the surface brief wins on this surface's strategy.** When DESIGN.md is missing, identity is **not** absent; extract it from CSS variables, computed styles, and sibling components (Step 4 Phase A). Identity preservation is the default; departure requires the user's explicit redesign intent.
|
||||
|
||||
`serverPort`/`serverToken` belong to the small helper HTTP server (`/live.js`, SSE, `/poll`), not your dev server; the page URL is whatever origin serves a `pageFiles` entry.
|
||||
|
||||
If output is `{ ok: false, error: "config_missing" | "config_invalid", path }`, this project needs one-time configuration: read [live-setup.md](live-setup.md) and follow it. If the output carries a non-null `configDrift`, tell the user once which HTML files are uncovered and suggest adding them or switching `files` to a glob; never auto-edit the config.
|
||||
|
||||
## Recovery commands
|
||||
|
||||
The live helper persists an append-only journal under `.impeccable/live/sessions/`. Browser checkpoints are advisory but durable; the journal is canonical. This is local durable recovery state, not project source.
|
||||
|
||||
Use these commands when the chat was interrupted, polling was missed, the helper restarted, or the browser reloaded:
|
||||
The append-only journal under `.impeccable/live/sessions/` is canonical durable state (not project source). When the chat was interrupted, polling was missed, the helper restarted, or the browser reloaded:
|
||||
|
||||
```bash
|
||||
node .cursor/skills/impeccable/scripts/live-status.mjs
|
||||
node .cursor/skills/impeccable/scripts/live-resume.mjs --id SESSION_ID
|
||||
node .cursor/skills/impeccable/scripts/live-complete.mjs --id SESSION_ID
|
||||
node .cursor/skills/impeccable/scripts/live-status.mjs # helper state, active sessions, queued events; works with the helper down
|
||||
node .cursor/skills/impeccable/scripts/live-resume.mjs --id SESSION_ID # active snapshot, pending event, next safe action
|
||||
node .cursor/skills/impeccable/scripts/live-complete.mjs --id SESSION_ID # canonical manual final acknowledgement after verified cleanup
|
||||
```
|
||||
|
||||
- `live-status.mjs` prints connected helper state, active durable sessions, and queued pending events. It works even when the helper is down by reading the journal directly.
|
||||
- `live-resume.mjs` prints the active snapshot, pending event, checkpoint phase, visible variant, parameter values, and the next safe agent action.
|
||||
- `live-complete.mjs` is the canonical manual final acknowledgement. Use it after carbonize/manual cleanup is verified and no further poll acknowledgement will happen automatically.
|
||||
|
||||
Server restart rule: start `live-server.mjs` again, then poll. Startup requeues unacknowledged pending events from the journal, so do not ask the user to click Go again unless `live-resume.mjs` says no active session exists.
|
||||
Server restart rule: start `live-server.mjs` again, then poll; startup requeues unacknowledged events, so never ask the user to click Go again unless `live-resume.mjs` says no active session exists.
|
||||
|
||||
## Handle `generate`
|
||||
|
||||
**Replace mode** (default): `{id, action, freeformPrompt?, count, pageUrl, element, screenshotPath?, comments?, strokes?}`.
|
||||
|
||||
**Insert mode** (`event.mode === "insert"`): `{id, mode: "insert", count, pageUrl, insert: { position, anchor }, placeholder: { width, height }, freeformPrompt?, screenshotPath?, comments?, strokes?}`. No `action`. Requires a non-empty `freeformPrompt` **or** annotations. Screenshot is sent only when annotations exist (same rule as replace). Use `placeholder` dimensions as a soft size hint for net-new content.
|
||||
**Insert mode** (`event.mode === "insert"`): `{id, mode: "insert", count, pageUrl, insert: { position, anchor }, placeholder: { width, height }, freeformPrompt?, screenshotPath?, comments?, strokes?}`. No `action`; requires a non-empty `freeformPrompt` **or** annotations. `placeholder` is a soft size hint.
|
||||
|
||||
Speed matters; the user is watching the selected element. Reuse server preflight metadata when available, minimize discovery calls, and follow the harness-specific delivery policy above.
|
||||
Speed matters; the user is watching the selected element. Reuse preflight metadata, minimize discovery calls.
|
||||
|
||||
### Insert mode branch
|
||||
|
||||
When `event.mode === "insert"`:
|
||||
|
||||
1. Read the screenshot if `event.screenshotPath` is present (annotations only).
|
||||
2. If `event.scaffold` is present, use it as the insert-helper result and do **not** run the helper again. Otherwise run the insert helper instead of wrap:
|
||||
1. Read the screenshot if present (annotations only).
|
||||
2. If `event.scaffold` is present, use it and do **not** run the helper again. Otherwise:
|
||||
|
||||
```bash
|
||||
node .cursor/skills/impeccable/scripts/live-insert.mjs --id EVENT_ID --count EVENT_COUNT --position after \
|
||||
--element-id "ANCHOR_ID" --classes "class1,class2" --tag "section" --text "ANCHOR_TEXT"
|
||||
```
|
||||
|
||||
- `--position` ← `event.insert.position` (`before` | `after`)
|
||||
- Anchor flags ← `event.insert.anchor` (same mapping as wrap: id, classes, tag, text)
|
||||
|
||||
The scaffold has **no** `data-impeccable-variant="original"`. Variants are net-new HTML+CSS inserted at `insertLine`. On source-preview targets the scaffold carries `sourceWritten: false` with `wrapperBlock`, `replaceStartLine`, and `replaceEndLine` (here `replaceEndLine < replaceStartLine`, an insertion): splice your variants into `wrapperBlock` at the marker and insert the result at `replaceStartLine` in one edit, exactly as the wrap section describes, so the framework reloads once. Decide the visitor mode from the surface and load [craft-floor.md](craft-floor.md) before writing net-new markup (freeform only, no action sub-command). Deliver using the harness policy, then `--reply done`.
|
||||
|
||||
For Svelte/SvelteKit targets, `live-insert.mjs` returns `previewMode: "svelte-component"` with `mode: "insert"`, `file` pointing at a temporary `node_modules/.impeccable-live/<id>/manifest.json`, `componentDir` pointing at the variant component files, and `sourceFile` pointing at the real `.svelte` route. Write each inserted variant as a real Svelte component (`v1.svelte`, `v2.svelte`, …) under `componentDir`. Insert variants must be non-empty net-new content with a single top-level root, no `data-impeccable-*` attributes, and CSS in each component's `<style>` block. Do **not** edit the route source during generation; the browser mounts the temporary component before/after the live anchor while the user cycles variants. On Accept, `live-accept.mjs` inserts the selected component markup into `sourceFile` immediately and deletes the temp session after the source write succeeds.
|
||||
|
||||
For non-Svelte targets, on accept/discard, `live-accept.mjs` removes the wrapper block; the anchor element is untouched.
|
||||
`--position` ← `event.insert.position`; anchor flags map exactly like wrap's. The scaffold has **no** `data-impeccable-variant="original"`; variants are net-new HTML+CSS at `insertLine`. On source-preview targets the scaffold carries `sourceWritten: false` with `wrapperBlock` and `replaceEndLine < replaceStartLine` (an insertion): splice variants into `wrapperBlock` at the marker and insert at `replaceStartLine` in ONE edit, exactly as the wrap section describes. Decide the visitor mode from the surface and load [craft-floor.md](craft-floor.md) before writing net-new markup. Svelte targets follow the same component flow as wrap below (`mode: "insert"` in the manifest): each variant is a real single-root component under `componentDir` with no `data-impeccable-*` attributes; never edit the route during generation; accept splices the chosen markup into `sourceFile` mechanically. For non-Svelte targets, accept/discard removes the wrapper; the anchor is untouched.
|
||||
|
||||
### Replace mode (default)
|
||||
|
||||
### 1. Read the screenshot (if present)
|
||||
|
||||
`event.screenshotPath` is **only sent when the user placed at least one comment or stroke before Go.** When present, it's an absolute path to a PNG of the element as rendered with the annotations baked in. **Read it before planning**: annotations encode user intent not recoverable from `element.outerHTML` alone.
|
||||
`event.screenshotPath` is sent **only when the user annotated before Go**; it is a PNG of the element with annotations baked in. Read it before planning. When absent, do not ask for one or screenshot the page yourself: without annotations a screenshot anchors you on the existing design and fights the three-distinct-directions brief; work from `element.outerHTML`, the computed styles, and the prompt.
|
||||
|
||||
When `screenshotPath` is absent, don't ask for one and don't go looking for the current rendering. The omission is deliberate: without annotations, a screenshot would anchor the model on the existing design and fight the three-distinct-directions brief. Work from `element.outerHTML`, the computed styles in `event.element`, and the freeform prompt if present.
|
||||
|
||||
`event.comments` and `event.strokes` carry structured metadata alongside the visual. Treat the screenshot as primary; use the structured data for specifics worth quoting (e.g. the exact text of a comment).
|
||||
|
||||
Reading annotations precisely:
|
||||
|
||||
- **Comment position carries meaning.** Its `{x, y}` is element-local CSS px (same coord space as `element.boundingRect`). Find the child under that point and apply the comment text LOCALLY to that sub-element. A comment near the title is about the title, not a global description.
|
||||
- **Comments and strokes are independent annotations** unless clearly paired by overlap or tight proximity. Don't let the visual weight of a prominent stroke override the precise location of a textually-specific comment elsewhere.
|
||||
- **Strokes are gestures; read them by shape.** Closed loop = "this thing" (emphasis / focus); arrow = direction (move / point to); cross or slash = delete; free scribble = emphasis or delete depending on context. A loop around region X means "pay attention to X," not "only change pixels inside X."
|
||||
- **When a stroke's intent is ambiguous** (circle or arrow? emphasis or move?), state your reading in one sentence of rationale rather than silently guessing. If the uncertainty materially changes the brief, ask one short clarifying question before generating.
|
||||
Annotation semantics: a comment's `{x, y}` is element-local and binds the text to the child under that point (a comment near the title is about the title). Comments and strokes are independent unless clearly paired. Strokes read by shape: closed loop = "this thing" (emphasis, not a clipping region); arrow = direction or movement; cross/slash = delete; scribble = emphasis or delete by context. If a stroke's intent is genuinely ambiguous and it changes the brief, ask one short question before generating; otherwise state your reading in one sentence.
|
||||
|
||||
### 2. Wrap the element
|
||||
|
||||
When `event.scaffold` is present, the local helper already found the source and computed the wrapper before the poll returned. Treat `event.scaffold` as the successful helper output and skip this command entirely. `event.scaffoldAttempted` with `scaffoldError` means local preflight could not finish; use the command/fallback path below. This optimization removes a deterministic tool round trip without changing the generated design.
|
||||
When `event.scaffold` is present, the helper already found the source and computed the wrapper; treat it as the successful output and skip the command. `event.scaffoldAttempted` with `scaffoldError` means preflight could not finish; use the command below.
|
||||
|
||||
**On source-preview targets `event.scaffold` carries `sourceWritten: false`.** The helper did NOT write the wrapper into source; it hands you the wrapper as `scaffold.wrapperBlock` plus the picked element's source range (`scaffold.replaceStartLine`, `scaffold.replaceEndLine`, 1-indexed). Write the wrapper **and** all variants in ONE edit: splice your variants into `wrapperBlock` at the "Variants: insert below this line" marker, then replace source lines `[replaceStartLine, replaceEndLine]` with the result. A separate scaffold write reloads the framework before your variant write lands, and a browser caught mid-reload misses the `done` and sits at 0/N; the single edit avoids it. (`replaceEndLine < replaceStartLine` means insert mode: insert `wrapperBlock`, remove nothing.) The `svelte-component` path never sets `sourceWritten`; it follows the component-preview flow below unchanged.
|
||||
**On source-preview targets `event.scaffold` carries `sourceWritten: false`.** The helper did NOT write the wrapper; it hands you `scaffold.wrapperBlock` plus the picked element's source range (`replaceStartLine`, `replaceEndLine`, 1-indexed). Write the wrapper **and** all variants in ONE edit: splice your variants into `wrapperBlock` at the "Variants: insert below this line" marker, then replace lines `[replaceStartLine, replaceEndLine]` with the result. A separate scaffold write reloads the framework before your variant write lands and strands the browser at 0/N. (`replaceEndLine < replaceStartLine` means insert mode: insert, remove nothing.) The `svelte-component` path never sets `sourceWritten`.
|
||||
|
||||
```bash
|
||||
node .cursor/skills/impeccable/scripts/live-wrap.mjs --id EVENT_ID --count EVENT_COUNT --element-id "ELEMENT_ID" --classes "class1,class2" --tag "div" --text "TEXT_SNIPPET"
|
||||
```
|
||||
|
||||
Flag mapping. Keep them separate, don't collapse into `--query`:
|
||||
Flag mapping (keep separate, never collapse into `--query`): `--element-id` ← `event.element.id`; `--classes` ← classes joined with commas; `--tag` ← tagName; `--text` ← first ~80 chars of textContent, **every call**: it disambiguates repeated sibling components, without it wrap lands on the first match. If `event.pageUrl` implies the file, pass `--file PATH`. If `--text` still matches several candidates, wrap exits `{ error: "element_ambiguous", candidates, fallback: "agent-driven" }`: pick the right range from page context and write the wrapper manually per the fallback flow.
|
||||
|
||||
- `--element-id` ← `event.element.id`
|
||||
- `--classes` ← `event.element.classes` joined with commas
|
||||
- `--tag` ← `event.element.tagName`
|
||||
- `--text` ← first ~80 chars of `event.element.textContent` (trim, single-line). **Pass this every call.** When the picked element shares classes + tag with sibling components (a list of `<Card>`s, repeating sections), this is what disambiguates which branch in source to wrap. Without it, wrap silently lands on the first match and may rewrite the wrong element.
|
||||
Success output: `{ file, insertLine, commentSyntax, styleMode, styleTag, cssSelectorPrefixExamples, cssAuthoring }` (plus the `sourceWritten: false` fields above on source-preview targets). Run directly with no preflight scaffold, it writes the wrapper itself and you splice variants at `insertLine`. `styleMode` controls how preview CSS must be authored. Treat it as a detected capability mode, not a framework guess: `scoped` means `@scope ([data-impeccable-variant="N"])` rules; `astro-global-prefixed` means explicit `[data-impeccable-variant="N"]` prefixes with the exact returned `styleTag`. Use `cssAuthoring` as the source of truth for the current file (styleTag, selector strategy, requirements, forbidden patterns); apply no framework-specific exception unless it says to.
|
||||
|
||||
The helper searches ID first, then classes, then tag + class combo. If `event.pageUrl` implies the file (e.g. `/` is usually `index.html`), pass `--file PATH` to skip the search. `--query` is a fallback for raw text search only; do not use it for normal element lookups.
|
||||
For Svelte/SvelteKit targets, `live-wrap.mjs` returns `previewMode: "svelte-component"` with `file` pointing at a temporary `node_modules/.impeccable-live/<id>/manifest.json`, `componentDir` holding the variant components, and `sourceFile` the real route. The scaffold is AST-based: control-flow blocks (`{#each}`, `{#if}`) survive intact and a free each-collection crosses the contract as ONE structured prop (kind `collection`). The payload includes `componentStubMarkup` (the prop-substituted markup already written into every stub), so do not read the manifest or stubs back. EDIT `v1.svelte`, `v2.svelte`, ... in place; never delete and recreate them; keep the stub's control flow and `propContract` prop names; never flatten a loop into literal items. The stub `<style>` arrives seeded with the source rules that currently style the selection; restyle or delete them freely. On accept, any seeded rule your variant does not re-declare is REMOVED from the source (the preview never applied it, so the user approved a design without it). Use semantic class selectors, no `@scope`, no `data-impeccable-*`. Reply with `--file` set to the manifest path; the browser mounts the compiled components so Svelte HMR does not reset page state. Accept merges the chosen component back mechanically (markup restored to route expressions, CSS reconciled, params baked, indentation preserved); you have no post-accept cleanup on this path. When the selection contains constructs a detached preview cannot support (component tags, `bind:`/`use:`, await blocks, inline scripts, spread attributes), wrap returns the normal source-preview wrapper with `previewFallback: { from: "svelte-component", reason }`; just follow the returned shape.
|
||||
|
||||
If `--text` matches multiple candidates equally well, wrap exits with `{ error: "element_ambiguous", candidates: [...] }` and `fallback: "agent-driven"`: read the candidate line ranges, decide which one matches the picked element from page context, and write the wrapper manually per the fallback flow.
|
||||
|
||||
Output on success: `{ file, insertLine, commentSyntax, styleMode, styleTag, cssSelectorPrefixExamples, cssAuthoring }`. On source-preview targets it also returns `sourceWritten: false`, `wrapperBlock`, `replaceStartLine`, and `replaceEndLine` (write it yourself per the `event.scaffold` note above). When you run this command directly (no preflight scaffold), it writes the wrapper into source itself, so there is no `wrapperBlock` and you splice variants at `insertLine`.
|
||||
|
||||
For Svelte/SvelteKit targets, `live-wrap.mjs` returns `previewMode: "svelte-component"` with `file` pointing at a temporary `node_modules/.impeccable-live/<id>/manifest.json`, `componentDir` pointing at the variant component files, and `sourceFile` pointing at the real `.svelte` route. Write each variant as a real Svelte component (`v1.svelte`, `v2.svelte`, …) under `componentDir`; use the `propContract` prop names for dynamic text (`{propName}`), not literal snapshot strings. Put variant CSS in each component's `<style>` block with semantic class selectors (no `@scope`, no `data-impeccable-*`). Reply with `--file` set to the manifest path; the browser dynamically imports and mounts the compiled components so Svelte HMR does not reset page state while the user cycles variants. On Accept, `live-accept.mjs` inlines the accepted component back into `sourceFile` immediately after source promotion succeeds.
|
||||
|
||||
**Params on component-preview paths go in a sidecar, never as an attribute.** Svelte parses `{` inside an attribute value as the start of an expression, and both Svelte/Vue previews mount without an HTML variant wrapper. Declare params in `componentDir/params.json`, keyed by variant number, using the exact param schema from section 7:
|
||||
**Params on component-preview paths go in a sidecar, never as an attribute** (Svelte parses `{` in attribute values as an expression). Declare them in `componentDir/params.json` keyed by variant number, using the schema from section 7:
|
||||
|
||||
```json
|
||||
{
|
||||
"1": [
|
||||
{"id":"density","kind":"steps","default":"snug","label":"Density","options":[
|
||||
{"value":"airy","label":"Airy"},{"value":"snug","label":"Snug"},{"value":"packed","label":"Packed"}
|
||||
]}
|
||||
],
|
||||
"2": [
|
||||
{"id":"accent","kind":"range","min":0,"max":1,"step":0.05,"default":0.5,"label":"Accent"}
|
||||
]
|
||||
}
|
||||
{ "1": [ {"id":"density","kind":"steps","default":"snug","label":"Density","options":[
|
||||
{"value":"airy","label":"Airy"},{"value":"snug","label":"Snug"} ]} ] }
|
||||
```
|
||||
|
||||
Author the component `<style>` against `var(--p-<id>, default)` for `range`/`toggle` and `[data-p-<id>="…"]` for `steps`; wrap those selectors in `:global(...)` so the knob values the runtime sets on the mounted root reach your rules. The browser reads `params.json`, docks the panel, and drives `--p-*` / `data-p-*` on the mounted component exactly as it does for the HTML/JSX path.
|
||||
Author the component `<style>` against `var(--p-<id>, default)` for `range`/`toggle` and `[data-p-<id>="…"]` for `steps`, wrapped in `:global(...)` so runtime knob values on the mounted root reach your rules.
|
||||
|
||||
`styleMode` controls how preview CSS must be authored. Treat it as a detected capability mode, not a framework guess:
|
||||
|
||||
- `scoped`: use `@scope ([data-impeccable-variant="N"])` rules.
|
||||
- `astro-global-prefixed`: use explicit `[data-impeccable-variant="N"]` selector prefixes and the exact `styleTag` returned by the tool.
|
||||
|
||||
Use `cssAuthoring` as the source of truth for the current file. It includes the exact `styleTag`, selector strategy, selector examples, requirements, and forbidden patterns. Do not apply a framework-specific exception unless the returned `styleMode` / `cssAuthoring.mode` says to.
|
||||
|
||||
**Fallback errors.** Wrap only writes into files it judges to be source (tracked by git, not marked GENERATED, not listed in config's `generatedFiles`). If it can't land on a source file, it errors without writing; accepting a variant into a generated file is silent data loss. Three shapes:
|
||||
|
||||
- `{ error: "file_is_generated", file, hint }`: user-supplied `--file` points at a generated file.
|
||||
- `{ error: "element_not_in_source", generatedMatch, hint }`: element exists only in a generated file (the next build would wipe any edits).
|
||||
- `{ error: "element_not_found", hint }`: element isn't in any project file; likely runtime-injected (JS component, dynamic render from data).
|
||||
|
||||
All three carry `fallback: "agent-driven"`. Follow **Handle fallback** below.
|
||||
**Fallback errors.** Wrap refuses to write into non-source files (generated, untracked): accepting into one is silent data loss. Three shapes, all with `fallback: "agent-driven"` (see **Handle fallback**): `file_is_generated` (your `--file` points at a generated file), `element_not_in_source` with `generatedMatch` (element only exists generated), `element_not_found` (likely runtime-injected).
|
||||
|
||||
### 3. Load the action's reference
|
||||
|
||||
If `event.action` is `impeccable` (the default freeform action), work from SKILL.md's design rules plus [craft-floor.md](craft-floor.md), and decide the visitor mode from the selected surface. Do not load a sub-command reference. **Freeform is not a pass to skip parameters:** you still follow the composition budget and the freeform bias in **§7 Parameters** below. Sub-command files list MUST-have signature knobs; freeform has no such file, so sizing knobs from surface weight and primary axes is entirely on you.
|
||||
|
||||
Any other `event.action` (`bolder`, `quieter`, `distill`, `polish`, `typeset`, `colorize`, `layout`, `adapt`, `animate`, `delight`, `overdrive`): Read `reference/<action>.md` before planning. Each sub-command encodes a specific discipline; skipping its reference produces generic output. Those files may require specific params; layer them on top of the §7 budget, not instead of it.
|
||||
`event.action` is `impeccable` (freeform): work from SKILL.md's design rules plus [craft-floor.md](craft-floor.md); decide the visitor mode from the surface; do not load a sub-command reference. Freeform is not a pass to skip parameters: follow the budget and freeform bias in section 7. Any other action (`bolder`, `quieter`, `distill`, `polish`, `typeset`, `colorize`, `layout`, `adapt`, `animate`, `delight`, `overdrive`): read `reference/<action>.md` before planning; its MUST params layer on top of the section 7 budget.
|
||||
|
||||
### 4. Plan three variants: identity first, then mode, then axes
|
||||
|
||||
The wrong frame for live mode is "show three different design directions." Live runs on an existing surface; the brand has already been chosen. The job is variation **within identity**, not selection between identities. Failure mode: three editorial-typographic variants on a brief that wasn't editorial. Bigger failure mode: three off-brand variants the user can't accept because they don't look like their product.
|
||||
|
||||
Four phases. Do them in order.
|
||||
Live runs on an existing surface; the brand is already chosen. The job is variation **within identity**, not selection between identities. The worst failure is three off-brand variants the user cannot accept. Four phases, in order.
|
||||
|
||||
#### Phase A: Extract the identity (non-skippable)
|
||||
|
||||
The existing surface has an identity already. Read it before planning anything. Sources, in priority order:
|
||||
|
||||
1. **DESIGN.md** if loaded: read the visual system fields (palette, type pairing, motion, components). This is the authoritative answer.
|
||||
2. **CSS custom properties** in the page's stylesheets (`:root { --color-...; --font-...; ... }`): these are de-facto tokens.
|
||||
3. **Computed styles** on the picked element and its parent: colors, fonts, spacing scales, corner radii.
|
||||
4. **Sibling components on the page**: what visual rhetoric do existing components use? (Asymmetric or centered? Dense or airy? Bold or quiet?)
|
||||
|
||||
Write down what you see in **one sentence**. The sentence describes the surface that's actually on screen; it is not aspirational, not opinionated, not edited toward what the brand "should" be. Capture, in roughly this order:
|
||||
|
||||
- The dominant surface color and accent color, by hex or token name (use the actual values, not categories like "warm" or "neutral").
|
||||
- The type pairing: the actual font names loaded, primary first.
|
||||
- The layout topology: how the dominant elements are arranged (stacked / side-by-side / grid / asymmetric / overlay).
|
||||
- The surface treatment: corners, borders, shadows, density of decoration.
|
||||
- The voice tone you read off the copy itself, not off the aesthetic feel.
|
||||
|
||||
Be specific. "Modern" is not a color, "elegant" is not a type pairing, "clean" is not a layout. If you can't extract a real value for an axis, skip it rather than fabricate. The point is to record what is, not to describe what you wish it were.
|
||||
|
||||
Do not name an aesthetic family in this sentence; that is a conclusion, not observed identity data. Letting conclusions into Phase A collapses the identity lock into a self-fulfilling prophecy.
|
||||
|
||||
This sentence is the **identity lock**. Every variant must be readable as the same brand if rendered side by side. Skipping this phase is the primary cause of off-brand variants. Absence of DESIGN.md is never an excuse; extract from CSS and computed styles instead.
|
||||
Sources in priority order: DESIGN.md's visual system fields; CSS custom properties (de-facto tokens); computed styles on the picked element and parent; sibling components' visual rhetoric. Write ONE sentence recording what is actually on screen: dominant surface and accent color (real values, not "warm"), the loaded font pairing, layout topology (stacked / side-by-side / grid / asymmetric / overlay), surface treatment (corners, borders, shadows, decoration density), and the voice tone read off the copy. Be specific; skip an axis rather than fabricate; do not name an aesthetic family (a conclusion, not data). This sentence is the **identity lock**: every variant must read as the same brand side by side. Absence of DESIGN.md is never an excuse.
|
||||
|
||||
#### Phase B: Pick mode (default vs departure)
|
||||
|
||||
**Default mode**: the existing identity is preserved. Variants vary expression axes within it. *This is the right mode for ~90% of live sessions.* The user picked an element on a real product they're shipping; they expect variants of *their* hero, not three different brands' heroes.
|
||||
|
||||
**Departure mode**: the existing identity is rejected. Variants propose alternatives consistent with durable product and brand truth. Trigger only when the user explicitly asks for departure in the current request or freeform prompt ("redesign this", "rebuild this from scratch", "what if it weren't editorial at all", "show me something completely different"). A stale page critique or an old task note is not replacement authorization.
|
||||
|
||||
If you're unsure, you're in default mode. The cost of being wrong about default is "three on-brand variants with similar feel": recoverable, the user picks none. The cost of being wrong about departure is "three off-brand variants": unrecoverable, the user is annoyed.
|
||||
**Default** preserves the identity and varies expression within it; right for ~90% of sessions. **Departure** rejects the identity; trigger ONLY on the user's explicit ask in the current request or prompt ("redesign this", "rebuild from scratch", "something completely different"); a stale critique or old note is not authorization. Unsure means default: wrong-default costs "three on-brand variants with similar feel" (recoverable), wrong-departure costs three off-brand variants (unrecoverable).
|
||||
|
||||
#### Phase C: Plan three variants
|
||||
|
||||
**Default mode.** Each variant commits to a different **primary axis** of difference, while preserving the identity sentence. The six axes:
|
||||
**Default mode.** Each variant commits to a different **primary axis**, preserving the identity sentence. The six axes: 1 **Hierarchy** (which element commands the eye), 2 **Layout topology** (stacked / side-by-side / grid / asymmetric / overlay), 3 **Typographic system** (pairing logic, scale ratio, case/weight, *within the available faces*), 4 **Color strategy** (which existing palette role carries the surface: Restrained / Committed / Full palette / Drenched; existing tokens only), 5 **Density** (minimal / comfortable / dense), 6 **Structural decomposition** (merge, split, progressive disclosure). Three variants, three DIFFERENT axes: the same brand at three angles. New fonts, new hues, or new aesthetic-family signals belong to departure mode only.
|
||||
|
||||
1. **Hierarchy**: which element commands the eye?
|
||||
2. **Layout topology**: stacked / side-by-side / grid / asymmetric / overlay
|
||||
3. **Typographic system**: pairing logic, scale ratio, case/weight strategy *within the available faces*
|
||||
4. **Color strategy**: which existing palette role carries the surface (Restrained / Committed / Full palette / Drenched). Use the brand's existing palette tokens, not new colors.
|
||||
5. **Density**: minimal / comfortable / dense
|
||||
6. **Structural decomposition**: merge, split, progressive disclosure
|
||||
**Departure mode.** Each variant anchors to a different aesthetic direction derived from the brand, never a fixed catalog: read PRODUCT.md's Brand Personality words; derive physical, spatial, or material experiences that embody them; from those, derive three directions genuinely different from each other AND from the current surface; reject reflex choices whose rationale would fit a neighboring product. Each direction must be one concrete sentence naming a real-world referent ("a museum exhibition label system", not "clean and minimal").
|
||||
|
||||
Three variants → three DIFFERENT axes. The trio reads as *the same brand at three angles*. Do not introduce new fonts, new palette hues, or new aesthetic-family signals; those belong to departure mode.
|
||||
|
||||
**While planning each variant, also name its 2–3 parameter knobs** (per the §7 budget table). Parameters are part of the design, not a decoration added afterward. If the variant explores density, expose a density knob. If it explores color commitment, expose a color-amount range. Deciding "what's tunable" during planning produces better knobs than retrofitting them onto finished HTML.
|
||||
|
||||
**Departure mode.** Each variant anchors to a different **aesthetic direction**, derived from PRODUCT.md's audience world and voice plus the current DESIGN.md. Do not pick from a fixed catalog; derive directions from this product.
|
||||
|
||||
Instead, work from the brand:
|
||||
|
||||
1. Read PRODUCT.md's Brand Personality words. Derive physical, spatial, or material experiences that embody them without starting from a design style.
|
||||
2. From those physical experiences, derive three visual directions that are genuinely different from each other AND from the current surface you're departing.
|
||||
3. Reject any direction chosen by reflex rather than derived from the brand. Start over from the personality words when the rationale could fit a neighboring product.
|
||||
4. Each direction must be expressible in one concrete sentence that names a real-world referent ("a museum exhibition label system for a contemporary art gallery" not "clean and minimal"). If your sentence contains only adjectives, it's not concrete enough.
|
||||
5. **While planning each direction, also name its 2–3 parameter knobs** (per the §7 budget table). The same principle as default mode: decide "what's tunable" during planning, not after writing the HTML. A departure-mode hero with 0 parameters is not "bold creative vision," it's a missed opportunity for the user to fine-tune the direction they pick.
|
||||
**In both modes, name each variant's 2 or 3 parameter knobs while planning** (section 7 budget). Parameters are part of the design; deciding "what's tunable" during planning beats retrofitting.
|
||||
|
||||
#### Phase D: Squint test
|
||||
|
||||
**Default mode squint.** Read each variant's identity sentence and compare to the locked identity from Phase A. If any variant has drifted to a different palette, type voice, or visual rhetoric, it has crossed into departure mode by accident; rework. Then check that each variant commits to a different primary axis. Three "tighter density" variants is failure.
|
||||
**Default:** compare each variant against the Phase A lock; palette, type voice, or rhetoric drift means it crossed into departure by accident: rework. Then confirm three different primary axes; three "tighter density" variants is failure. **Departure:** two passes, family before sentence. Family pass (non-negotiable): label each variant with a concrete family of your own choosing; shared or interchangeable labels mean rework. Sentence pass: three one-line descriptions side by side; two that rhyme mean rework. When the primary axis is color or theme, the trio must not share theme + dominant hue: three color worlds, not three shades.
|
||||
|
||||
**Departure mode squint.** Two passes, family before sentence:
|
||||
**Action-specific invocations** must vary along the action's dimension:
|
||||
|
||||
1. **Family pass.** Give each variant a concrete family label of your own choosing. If two variants share a label, or a label fits another variant equally well, rework. Do not use a fixed vocabulary. *This pass is non-negotiable in departure mode and catches monoculture the sentence pass misses.*
|
||||
2. **Sentence pass.** Write three one-sentence descriptions side by side. If two of them rhyme ("both feature big type" / "both are stacks of sections" / "both center the CTA"), rework the offender.
|
||||
|
||||
**When the primary axis is color or theme, forbid the trio from sharing theme + dominant hue.** Two dark-plus-one-dark is not distinct. Aim for three color worlds, not three shades of the same.
|
||||
|
||||
**For action-specific invocations**, each variant must vary along the dimension the action names:
|
||||
|
||||
- `bolder`: amplify a different dimension per variant (scale / saturation / structural change). Not three "slightly bigger" variants.
|
||||
- `bolder`: amplify a different dimension per variant (scale / saturation / structural change).
|
||||
- `quieter`: pull back a different dimension (color / ornament / spacing).
|
||||
- `distill`: remove a different class of excess (visual noise / redundant content / nested structure).
|
||||
- `polish`: target a different refinement axis (rhythm / hierarchy / micro-details like corner radii, focus states, optical kerning).
|
||||
- `typeset`: different type pairing AND different scale ratio each. Not three riffs on one pairing.
|
||||
- `colorize`: different hue family each (not shades of one hue). Vary chroma and contrast strategy.
|
||||
- `layout`: different structural arrangement (stacked / side-by-side / grid / asymmetric). Not spacing tweaks.
|
||||
- `adapt`: different target context per variant (mobile-first / tablet / desktop / print or low-data). Don't make three mobile layouts.
|
||||
- `animate`: different motion vocabulary (cascade stagger / clip wipe / scale-and-focus / morph / parallax). Not three staggered fades.
|
||||
- `delight`: different flavor of personality (unexpected micro-interaction / typographic surprise / illustrated accent / sonic-or-haptic moment / easter-egg interaction).
|
||||
- `overdrive`: different convention broken (scale / structure / motion / input model / state transitions). Skip `overdrive.md`'s "propose and ask" step; live mode is non-interactive.
|
||||
- `polish`: a different refinement axis (rhythm / hierarchy / micro-details).
|
||||
- `typeset`: different pairing AND different scale ratio each.
|
||||
- `colorize`: different hue family each; vary chroma and contrast strategy.
|
||||
- `layout`: different structural arrangement, not spacing tweaks.
|
||||
- `adapt`: different target context per variant (mobile-first / tablet / desktop / print or low-data).
|
||||
- `animate`: different motion vocabulary (cascade stagger / clip wipe / scale-and-focus / morph / parallax).
|
||||
- `delight`: different flavor of personality (micro-interaction / typographic surprise / illustrated accent / sonic-or-haptic / easter egg).
|
||||
- `overdrive`: different convention broken (scale / structure / motion / input model / state transitions); skip its "propose and ask" step, live is non-interactive.
|
||||
|
||||
### 5. Apply the freeform prompt (if present)
|
||||
|
||||
`event.freeformPrompt` is the user's ceiling on direction (all variants must honor it), but still explore meaningfully different *interpretations*. The interpretations stay within whichever mode you picked in Phase B.
|
||||
|
||||
In **default mode**, the prompt narrows the axes you choose, not the identity. *"Make it feel more confident"* → variant 1 amplifies hierarchy (one element commands the eye), variant 2 commits the existing accent color (Committed strategy on the brand's hue), variant 3 tightens density and removes decorative slack. Three different axes, same brand.
|
||||
|
||||
In **departure mode**, the prompt narrows the lanes you draw from, not the families. *"Make it feel like a newspaper front page"* would itself be a departure-mode prompt; honor it but pick three meaningfully different newspaper-adjacent lanes (broadsheet vs. tabloid vs. trade journal), and run the family pass to confirm they don't collapse into one.
|
||||
|
||||
When the prompt conflicts with a confirmed binding brand commitment or DESIGN.md invariant, preserve the invariant unless the user explicitly revokes or replaces it. Task-local strategy from the matching surface brief may change when the user changes that surface's goal.
|
||||
`event.freeformPrompt` is the user's ceiling on direction: all variants honor it while exploring different interpretations within the Phase B mode. Default mode: the prompt narrows the axes, not the identity ("more confident" → one variant amplifies hierarchy, one commits the accent color, one tightens density). Departure mode: the prompt narrows the lanes, not the families ("newspaper front page" → broadsheet vs tabloid vs trade journal, then run the family pass). When the prompt conflicts with a binding brand commitment or DESIGN.md invariant, preserve the invariant unless the user explicitly revokes it.
|
||||
|
||||
### 6. Deliver variants
|
||||
|
||||
Complete HTML replacement of the original element for each variant, not a CSS-only patch. Consider the element's context (computed styles, parent structure, CSS variables from `event.element`).
|
||||
|
||||
Colocate preview CSS as a `<style>` tag inside the variant wrapper; `<style>` works anywhere in modern browsers and keeps each delivered state internally complete (no FOUC).
|
||||
|
||||
**Atomic default:** write CSS + all variants + parameter manifests in one edit at `insertLine`, preserving the established behavior.
|
||||
|
||||
Use the `cssAuthoring` object returned by `live-wrap.mjs` to author the temporary preview CSS. The style opening tag shown below is the common case; replace it with `cssAuthoring.styleTag` when the tool returns a different one. The variant markup shape is otherwise stable:
|
||||
Complete HTML replacement of the original element per variant, not a CSS-only patch. Colocate preview CSS as a `<style>` tag inside the wrapper. **Atomic default:** CSS + all variants + parameter manifests in one edit at `insertLine`.
|
||||
|
||||
```html
|
||||
<!-- Variants: insert below this line -->
|
||||
@@ -314,92 +187,55 @@ Use the `cssAuthoring` object returned by `live-wrap.mjs` to author the temporar
|
||||
<!-- variant 1: full element replacement (single top-level element) -->
|
||||
</div>
|
||||
<div data-impeccable-variant="2" style="display: none">
|
||||
<!-- variant 2: full element replacement -->
|
||||
<!-- variant 2 -->
|
||||
</div>
|
||||
<div data-impeccable-variant="3" style="display: none">
|
||||
<!-- variant 3: full element replacement -->
|
||||
<!-- variant 3 -->
|
||||
</div>
|
||||
```
|
||||
|
||||
**Each variant div contains exactly one top-level element: the full replacement for the original.** Use the same tag as the original (e.g. `<section>` if the user picked a `<section>`). Loose siblings (heading + paragraph + div as direct children of the variant div) break the outline tracking and the accept flow, which both assume one child.
|
||||
Replace the style opening tag with `cssAuthoring.styleTag` when the tool returns a different one. **Each variant div contains exactly one top-level element**, same tag as the original; loose siblings break outline tracking and accept. First variant visible, all others `display: none`. The browser's MutationObserver accepts atomic or progressive arrival; accepting an arrived variant fences the worker, so later publications are rejected.
|
||||
|
||||
The first variant has no `display: none` (visible by default). All others do. If variants use only inline styles and no preview CSS, omit the `<style>` tag entirely.
|
||||
For `styleMode: "scoped"`, author every `:scope` rule with a descendant combinator: the `@scope` boundary is the variant wrapper div, not your element, so a bare `:scope { ... }` styles a `display: contents` shell. Always step in (`:scope > .card`, `:scope .hero-title`). The fake test agent's CSS in `tests/live-e2e/agent.mjs` is a faithful template.
|
||||
|
||||
The browser's MutationObserver accepts either delivery shape. On the transactional progressive path it shows arrived variants and pending dots immediately; Accept and Discard are available as soon as one variant exists. Accepting an arrived variant fences the worker before the browser releases the picker, so later publications are rejected.
|
||||
|
||||
For `styleMode: "scoped"`, author every `:scope` rule with a descendant combinator. The `@scope` boundary is the **variant wrapper `<div data-impeccable-variant="N">`**, not the element you're designing. A bare `:scope { background: cream; }` styles the wrapper, not the inner replacement, so the cream lands on a `display: contents` shell while the actual element keeps page defaults. Always step in: `:scope > .card`, `:scope > section`, `:scope .hero-title`, etc. The fake test agent's CSS in `tests/live-e2e/agent.mjs` is a faithful template; every scoped rule starts `:scope > ...`.
|
||||
|
||||
**JSX / TSX target files.** Wrap `<style>` content in a template literal so the CSS `{` / `}` aren't parsed as JSX expressions, and use `className=` / `style={{…}}` on every variant element. Keep `data-impeccable-*` attributes as-is; they're plain strings:
|
||||
**JSX / TSX targets:** wrap `<style>` content in a template literal (CSS braces would parse as JSX), use `className=` / `style={{…}}`, keep `data-impeccable-*` attributes as plain strings:
|
||||
|
||||
```tsx
|
||||
<style data-impeccable-css="SESSION_ID">{`
|
||||
@scope ([data-impeccable-variant="1"]) { ... }
|
||||
@scope ([data-impeccable-variant="2"]) { ... }
|
||||
`}</style>
|
||||
<div data-impeccable-variant="1">
|
||||
{/* variant 1 */}
|
||||
</div>
|
||||
<div data-impeccable-variant="2" style={{ display: 'none' }}>
|
||||
{/* variant 2 */}
|
||||
</div>
|
||||
```
|
||||
|
||||
The wrap script already gives you a single-rooted JSX wrapper: a `<div data-impeccable-variants="…">` outer element with the marker comments tucked inside. Drop the variants block above into the "Variants: insert below this line" comment and the source stays valid TSX.
|
||||
The wrap script provides a single-rooted JSX wrapper with the marker comments inside; drop the block at the marker and the source stays valid TSX.
|
||||
|
||||
### 7. Parameters (composition-sized, 0–4 per variant)
|
||||
### 7. Parameters (composition-sized, 0-4 per variant)
|
||||
|
||||
Each variant can expose **coarse** knobs alongside the full HTML/CSS replacement. The browser docks a small panel to the right of the outline with one control per parameter. The user drags/clicks and sees instant feedback: there is zero regeneration cost because the knob toggles a CSS variable or data attribute that the variant's scoped CSS is already authored against.
|
||||
Each variant can expose **coarse** knobs; the browser docks one control per parameter with zero regeneration cost (knobs drive a CSS variable or data attribute your scoped CSS is authored against). Wire an axis as soon as the user could plausibly mutter "a bit tighter" or "a touch more accent" without wanting a regeneration; micro-margins and one-off nudges are not parameters. Freeform bias: you chose the axes, so expose them; a hero with 0 params is almost always a mistake, and 1 is underweight unless the design is a genuine fixed point.
|
||||
|
||||
**What “optional” does not mean.** Parameters are not nice-to-have decoration on large work. The word meant “omit controls that are redundant or cosmetic,” not “default to zero because three variants were enough work.”
|
||||
Budget scales with the element's VISUAL weight (count visual children, not DOM depth):
|
||||
|
||||
**When to add.** As soon as the variant’s scoped CSS has a meaningful continuous or stepped axis: density, color amount, type scale, motion intensity, column weight, and so on. If you can imagine the user muttering “a bit tighter” or “a touch more accent” **without** wanting a full regeneration, wire that axis. **Not** micro-margins or one-off nudges; those are not parameters.
|
||||
- **Leaf / tiny** (button, icon, bare heading): **0 params.**
|
||||
- **Small composition** (simple card, labeled input, ≤ ~5 visual children): **0-1**.
|
||||
- **Medium composition** (section, nav cluster, 6-15 children): **target 2**; 1 if simple.
|
||||
- **Large composition** (hero, full region, 16+ children or sub-sections): **target 2-3, up to 4** when independent axes are all authored in CSS.
|
||||
|
||||
**Freeform (`action` is `impeccable`) bias.** You did not load a sub-command reference, so you must **choose** signature axes yourself. Match the budget table: for a hero or large composition, that means **2–3 axes per variant**, not 1. Prefer knobs that sit on the dimensions where your three variants actually differ (if density varies, expose it as a `steps` knob; if color commitment varies, expose it as a `range`). A hero that ships with **0** params is almost always a mistake, not a judgment call. A hero with exactly **1** param is underweight unless the design is genuinely a fixed-point comparison. Start from the budget table, not from zero.
|
||||
**Hard cap: four** per variant. For named sub-commands, the action reference's MUST params are non-negotiable when expressible; respect the cap, no duplicate knobs.
|
||||
|
||||
**Budget scales with the element's visual weight, not token budget.** Knobs need real estate to read as tunable; three sliders on a single control are noise.
|
||||
|
||||
- **Leaf / tiny**: a single button, icon, input, bare heading, solitary paragraph: **0 params.**
|
||||
- **Small composition**: labeled input, simple card, short callout (≤ ~5 visual children): **0–1** params when one dominant axis is obvious; otherwise **0.**
|
||||
- **Medium composition**: section component, nav cluster, dense card, short feature block (6–15 visual children): **target 2**; **1** is acceptable if the block is simple; **0** only when variants are truly fixed points.
|
||||
- **Large composition**: hero section, full page region, spread layout, strong internal structure (16+ visual children or multiple sub-sections): **target 2–3**; **up to 4** when several independent axes (e.g. structure `steps` + `density` + one accent) are all authored in scoped CSS.
|
||||
|
||||
**When in doubt, ask whether a dial exists before defaulting to zero.** The user can always request more variants, but the point of live mode is instant tuning without another Go. Crowding the panel is bad; **under-shipping** knobs on a dense composition is the more common failure for freeform. Count by **visual** children, not DOM depth; a shallow-but-wide hero is still large.
|
||||
|
||||
**Hard cap per variant**: at most **four** parameters so the panel stays legible; rare fifth only if the reference explicitly allows it.
|
||||
|
||||
**How to declare.** Put a JSON manifest on the variant wrapper (HTML/JSX path). **On the `svelte-component` path, do not use this attribute.** Declare params in `componentDir/params.json` keyed by variant number instead (see the component-preview paragraphs in the wrap section). The param schema below is identical for every path.
|
||||
**Declare** on the HTML/JSX path as a wrapper attribute (component-preview paths use `componentDir/params.json` instead, same schema, keyed by variant number; see the wrap section):
|
||||
|
||||
```html
|
||||
<div data-impeccable-variant="1" data-impeccable-params='[
|
||||
{"id":"color-amount","kind":"range","min":0,"max":1,"step":0.05,"default":0.5,"label":"Color amount"},
|
||||
{"id":"density","kind":"steps","default":"snug","label":"Density","options":[
|
||||
{"value":"airy","label":"Airy"},
|
||||
{"value":"snug","label":"Snug"},
|
||||
{"value":"packed","label":"Packed"}
|
||||
]},
|
||||
{"id":"serif","kind":"toggle","default":false,"label":"Serif display"}
|
||||
]'>
|
||||
...variant content...
|
||||
</div>
|
||||
```
|
||||
|
||||
**Three kinds:**
|
||||
Three kinds: `range` (slider; drives `--p-<id>`; author `var(--p-color-amount, 0.5)`; fields min/max/step/default/label), `steps` (segmented radio; drives `data-p-<id>`; author `:scope[data-p-density="airy"] .grid { ... }`; fields options/default/label), `toggle` (drives both `--p-<id>: 0|1` and attribute presence; fields default/label). Reset on variant switch is a known limitation: each variant starts at its declared defaults.
|
||||
|
||||
- `range`: smooth slider. Drives a CSS custom property `--p-<id>` on the variant wrapper. Author CSS with `var(--p-color-amount, 0.5)`. Fields: `min`, `max`, `step`, `default` (number), `label`.
|
||||
- `steps`: segmented radio. Drives a data attribute `data-p-<id>` on the variant wrapper. Author CSS with `:scope[data-p-density="airy"] .grid { ... }`. Fields: `options` (array of `{value, label}`), `default` (string), `label`.
|
||||
- `toggle`: on/off switch. Drives BOTH a CSS var (`--p-<id>: 0|1`) and a data attribute (present when on, absent when off). Use whichever is more convenient. Fields: `default` (boolean), `label`.
|
||||
|
||||
**Signature params per action.** For named sub-commands, read that action’s `reference/<action>.md` for one or two **MUST** params (e.g. `layout` → `density`). Those are non-negotiable when the design can express them. **Freeform has no file-level MUST**; the **Freeform (`impeccable`) bias** in this section is the stand-in. If the user’s action is both stylized and sub-command (e.g. `colorize`), the sub-command’s MUST list takes precedence for its axes; still respect the **Hard cap** and add no redundant duplicate knobs.
|
||||
|
||||
**Reset on variant switch.** User dials density on v1, flips to v2, v2 starts at v2's declared defaults. Known limitation; preservation across variants may land later.
|
||||
|
||||
**On accept**, the browser sends the user's current values in the accept event. `live-accept.mjs` writes them as a sibling comment:
|
||||
|
||||
```html
|
||||
<!-- impeccable-param-values SESSION_ID: {"color-amount":0.7,"density":"packed"} -->
|
||||
```
|
||||
|
||||
The carbonize cleanup step (see below) reads that comment and bakes the chosen values into the final CSS. For `steps`/`toggle` attribute selectors: keep only the branch matching the chosen value, drop the others, collapse `:scope[data-p-density="packed"] .grid` to a semantic class rule. For `range` vars: either substitute the literal or keep the var with the chosen value as its new default.
|
||||
**On accept**, the browser sends current values and `live-accept.mjs` writes them as a sibling comment: `<!-- impeccable-param-values SESSION_ID: {"color-amount":0.7} -->`. Carbonize cleanup bakes them: keep only the matching `steps`/`toggle` branch, drop the others, collapse `:scope[data-p-…]` to semantic rules; substitute `range` literals or update the var's default.
|
||||
|
||||
### 8. Signal done
|
||||
|
||||
@@ -407,127 +243,56 @@ The carbonize cleanup step (see below) reads that comment and bakes the chosen v
|
||||
node .cursor/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID done --file RELATIVE_PATH
|
||||
```
|
||||
|
||||
`RELATIVE_PATH` is relative to project root (`public/index.html`, `src/App.tsx`, etc.); the browser fetches source directly if the dev server lacks HMR.
|
||||
|
||||
Then run `live-poll.mjs` again immediately.
|
||||
`RELATIVE_PATH` is relative to project root; the browser fetches source directly if the dev server lacks HMR. Then poll again immediately.
|
||||
|
||||
### Aborting an in-flight session
|
||||
|
||||
If wrap or generation fails after the browser has flipped to GENERATING (e.g. wrap landed on the wrong source branch and you've already reverted it, or generation hit an unrecoverable error), tell the **browser** so its bar resets to PICKING:
|
||||
|
||||
```bash
|
||||
node .cursor/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID error "Short reason"
|
||||
```
|
||||
|
||||
Don't run `live-accept --discard` for this; that's a pure file mutator, the browser doesn't see it, and the bar gets stuck on the GENERATING dots forever (the user has to refresh). `--discard` is only correct when the **browser** initiated the discard (user clicked ✕ during CYCLING) and the agent is just running source-side cleanup the browser already triggered.
|
||||
If wrap or generation fails after the browser flipped to GENERATING, tell the **browser** so its bar resets: `node .cursor/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID error "Short reason"`. Never use `live-accept --discard` for this (pure file mutator, browser never sees it, bar sticks on dots); `--discard` is only source-side cleanup for a discard the browser itself initiated.
|
||||
|
||||
## Handle fallback
|
||||
|
||||
When wrap returns `fallback: "agent-driven"`, the deterministic flow doesn't apply. Pick up here.
|
||||
When wrap returns `fallback: "agent-driven"`, you pick the source file yourself; the goal is unchanged: three preview variants now, and the accepted one persisted where the next build cannot wipe it.
|
||||
|
||||
The goal is the same: give the user three variants to choose from AND persist the accepted one in a place the next build won't wipe. The difference is that you have to pick the right source file yourself.
|
||||
|
||||
### Step 1: Identify where the element actually lives
|
||||
|
||||
Use the error payload:
|
||||
|
||||
- `element_not_in_source` with `generatedMatch: "public/docs/foo.html"`: the served HTML is generated. Find the generator (grep for writers of that path, e.g. `scripts/build-sub-pages.js`, an Astro/Next template) and locate the template or partial that emits this element.
|
||||
- `element_not_found`: the element is runtime-injected. Look for the component that renders it (React/Vue/Svelte), the JS that assembles it, or the data source that feeds it.
|
||||
- `file_is_generated` with `file: "..."`: user pointed at a generated file explicitly. Same resolution as `element_not_in_source`.
|
||||
|
||||
Read the candidate source until you're confident where a change to the element would belong. If the change is purely visual, that source might be a shared stylesheet, not the template.
|
||||
|
||||
### Step 2: Show three variants in the DOM for preview
|
||||
|
||||
The browser bar is waiting for variants. Even without a wrapper in source, you still need to show something:
|
||||
|
||||
1. Manually write the wrapper scaffold into the **served** file (the one the browser actually loaded). Use the same structure `live-wrap.mjs` produces; `<!-- impeccable-variants-start ID --><div data-impeccable-variants="ID" data-impeccable-variant-count="3" style="display: contents">…</div><!-- end -->`.
|
||||
2. Insert your three variant divs inside it, same shape as the deterministic path.
|
||||
3. Signal done with `--reply EVENT_ID done --file <served file>`. The browser's no-HMR fallback will fetch and inject.
|
||||
|
||||
This served-file edit is **temporary**: next regen wipes it, and that's fine. The real work happens on accept.
|
||||
|
||||
### Step 3: On accept, write to true source
|
||||
|
||||
When the accept event arrives (`_acceptResult.handled` will usually be `false` here because accept also refuses to persist into generated files; see Handle accept for the carbonize branch), extract the accepted variant's content and write it into the source you identified in Step 1:
|
||||
|
||||
- Structural change → edit the template / component source.
|
||||
- Visual-only change → add or update rules in the appropriate stylesheet; remove the inline `<style>` scope.
|
||||
- Dynamic from data → update the data source or the render logic.
|
||||
|
||||
Then remove the temporary wrapper from the served file if it's still there.
|
||||
|
||||
### Step 4: On discard, clean up the served file
|
||||
|
||||
Remove the wrapper you inserted in Step 2. Nothing else to do.
|
||||
1. **Find where the element really lives** from the error payload: `element_not_in_source` + `generatedMatch` means the served HTML is generated, so find the generator's template or partial; `element_not_found` means runtime-injected, so find the rendering component or data source; `file_is_generated` resolves the same way. A purely visual change may belong in a shared stylesheet rather than a template.
|
||||
2. **Preview in the served file**: manually write the same wrapper scaffold `live-wrap.mjs` produces (`<!-- impeccable-variants-start ID --><div data-impeccable-variants="ID" data-impeccable-variant-count="3" style="display: contents">…</div><!-- end -->`) into the file the browser actually loaded, insert your variant divs, `--reply EVENT_ID done --file <served file>`. This edit is temporary; a regen wiping it is fine.
|
||||
3. **On accept, write to true source** (accept refuses generated files, so `_acceptResult.handled` is usually `false` here): structural change → template/component source; visual-only → the right stylesheet; content rendered from data → the data source or render logic. Then remove the temporary wrapper from the served file.
|
||||
4. **On discard**, just remove the temporary wrapper.
|
||||
|
||||
## Handle `accept`
|
||||
|
||||
Event: `{id, variantId, _acceptResult, _completionAck}`. The poll script already ran `live-accept.mjs` to handle the file operation deterministically, then acknowledged event delivery to the helper. The browser DOM is already updated.
|
||||
Event: `{id, variantId, _acceptResult, _completionAck}`. The poll script already ran `live-accept.mjs` deterministically and acknowledged delivery; the browser DOM is already updated.
|
||||
|
||||
- The accept event includes `pageUrl`; the poll script must forward it to `live-accept.mjs --page-url PAGE_URL` so accept-time cleanup only scrubs staged copy edits for the current page.
|
||||
- `_completionAck.ok !== true`: do not poll yet. Run `live-status.mjs` / `live-resume.mjs`, complete the cleanup manually if needed, then run `live-complete.mjs --id EVENT_ID`.
|
||||
- `_acceptResult.handled: true` and `carbonize: false`: nothing to do. Poll again.
|
||||
- `_acceptResult.handled: true` and `carbonize: true`: post-accept cleanup is required, but it must not stall Codex's control lane. See "Required after accept (carbonize)" below. The `event._acceptResult.todo` field, `_completionAck.requiresComplete`, and stderr banner all point at this required follow-up; none are decorative.
|
||||
- `_acceptResult.handled: false, mode: "fallback"`: the session lived in a generated file and the script refused to persist there. You've already written the accepted variant into true source during Handle fallback Step 3; just clean up the temporary wrapper in the served file if any, and poll again.
|
||||
- `_acceptResult.handled: false, mode: "error"`: the operation genuinely failed. **Do not hand-edit the file**; the source was not touched and editing it yourself would either double-apply or race whoever holds it.
|
||||
- `error: "source_locked"`: a generation publish holds the file. Run the same `live-accept.mjs` command again; it is idempotent and will succeed once the publisher releases. Do not poll past it.
|
||||
- `error: "accept_receipt_conflict"`: this session already resolved as `priorOperation` (on `priorVariantId` for an accept), so the request contradicts durable truth. Do not edit. Run `live-status.mjs` and tell the user what the session actually resolved to.
|
||||
- anything else: report the error briefly and run `live-status.mjs` before continuing.
|
||||
- `_acceptResult.handled: false` without `mode`: manual cleanup: read file, find markers, edit.
|
||||
- `_completionAck.ok !== true`: do not poll yet. Run `live-status.mjs` / `live-resume.mjs`, finish cleanup manually if needed, then `live-complete.mjs --id EVENT_ID`.
|
||||
- `handled: true, carbonize: false`: nothing to do; poll again.
|
||||
- `handled: true, carbonize: true`: required cleanup below; `_acceptResult.todo`, `_completionAck.requiresComplete`, and the stderr banner all point at it.
|
||||
- `handled: false, mode: "fallback"`: the session lived in a generated file; you already wrote true source in fallback Step 3; clean the temporary wrapper and poll.
|
||||
- `handled: false, mode: "error"`: **do not hand-edit the file.** `source_locked`: rerun the same `live-accept.mjs` command (idempotent) until the publisher releases. `accept_receipt_conflict`: the session already resolved as `priorOperation`; run `live-status.mjs` and tell the user. Anything else: report briefly, run `live-status.mjs` first.
|
||||
- `handled: false` without `mode`: manual cleanup: read file, find markers, edit.
|
||||
|
||||
### Required after accept (carbonize)
|
||||
|
||||
When `_acceptResult.carbonize === true`, the accepted variant was stitched into source with helper markers and inline CSS so the browser can render it immediately with no visual gap. That stitch-in is **temporary**. The agent must rewrite it into permanent form before doing anything else. Skipping this leaves dead `@scope` rules for unaccepted variants, a pointless `data-impeccable-variant` wrapper, and `impeccable-carbonize-start/end` comment noise in the source file; all of which accumulate across sessions.
|
||||
`carbonize: true` means the accepted variant is stitched into source with helper markers and inline CSS (so the browser renders with no gap). That stitch-in is temporary; rewrite it into permanent form before anything else, or dead `@scope` rules, wrapper divs, and marker comments accumulate across sessions. Five steps, synchronously, before the next poll:
|
||||
|
||||
Do these five steps synchronously before the next poll. The source lock, generation epoch, and expected-source hash remain the final safety gates against a generator finishing concurrently with Accept.
|
||||
1. **Locate the carbonize block** in `_acceptResult.file`: bracketed by `<!-- impeccable-carbonize-start/end SESSION_ID -->` with a `<style data-impeccable-css>` element; read the `<!-- impeccable-param-values -->` comment first when present, it drives steps 3 and 4.
|
||||
2. **Move the CSS rules** into the project's real stylesheet (whichever already owns styling for the surrounding element).
|
||||
3. **Bake param values while rewriting selectors**: retarget `@scope ([data-impeccable-variant="N"])` to real semantic classes; keep only the `:scope[data-p-<id>="VALUE"]` branch matching the chosen value; substitute `var(--p-<id>)` literals or update the var's default.
|
||||
4. **Unwrap the accepted content**: delete the inner variant div (and on JSX the outer `data-impeccable-carbonize` div); drop `data-impeccable-params` and all `data-p-*` attributes.
|
||||
5. **Delete** the inline `<style>` block, the param-values comment, both carbonize markers, and any `@scope` rules for non-accepted variants.
|
||||
|
||||
1. **Locate the carbonize block** in the source file (`_acceptResult.file`). It's bracketed by `<!-- impeccable-carbonize-start SESSION_ID -->` and `<!-- impeccable-carbonize-end SESSION_ID -->` and contains a `<style data-impeccable-css="SESSION_ID">` element. If the variant declared parameters, an `<!-- impeccable-param-values SESSION_ID: {...} -->` comment sits alongside the style tag with the user's chosen values; read it first; it drives steps 3 and 4 below.
|
||||
2. **Move the CSS rules** into the project's real stylesheet. Which stylesheet depends on the project (e.g. `site/styles/workflow.css` for an Astro project, or the component's co-located CSS file for a Vite/Next project; pick whichever already owns styling for the surrounding element).
|
||||
3. **Bake in parameter values while rewriting selectors.** For `@scope ([data-impeccable-variant="N"])` wrappers: retarget to real, semantic classes on the accepted HTML (`.why-visual--v2 .v2-label { … }`). For `:scope[data-p-<id>="VALUE"]` selectors: keep only the branch matching the chosen value from the param-values comment; drop the others (they're dead after accept). For `var(--p-<id>, DEFAULT)` in the CSS: either substitute the literal value, or if the param is still useful as a knob going forward, leave the var and update its initial declaration to the chosen value.
|
||||
4. **Unwrap the accepted content.** Delete the inner `<div data-impeccable-variant="N" style="display: contents">` that wraps it. On JSX/TSX, also delete the outer `<div data-impeccable-carbonize="SESSION_ID" style={{ display: 'contents' }}>` wrapper if present (accept adds it so ternary/`return` slots keep a single root). Drop `data-impeccable-params` and any `data-p-*` attributes; those are live-mode plumbing, not source.
|
||||
5. **Delete the inline `<style>` block, the `<!-- impeccable-param-values -->` comment if present, and both `<!-- impeccable-carbonize-start/end -->` markers.** Also drop any `@scope` rules for variants other than the accepted one; those are dead code now.
|
||||
|
||||
After the file is clean, the cleanup owner runs `live-complete.mjs --id SESSION_ID` and verifies `phase: "completed"`. Poll again only after that verification.
|
||||
Then run `live-complete.mjs --id SESSION_ID` and verify `phase: "completed"` before polling again. The command is a gate, not a formality: it refuses with `error: "source_dirty"` plus findings while any live-mode leftover remains; fix and rerun (`--force` only for false positives).
|
||||
|
||||
## Handle `discard`
|
||||
|
||||
Event: `{id, _acceptResult, _completionAck}`. The poll script already restored the original, removed all variant markers, and acknowledged `discarded` durable completion. Nothing to do unless `_completionAck.ok !== true`; in that case run `live-complete.mjs --id EVENT_ID --discarded`, then poll again.
|
||||
Event: `{id, _acceptResult, _completionAck}`. The poll script already restored the original and acknowledged `discarded`. Nothing to do unless `_completionAck.ok !== true`; then `live-complete.mjs --id EVENT_ID --discarded` and poll again.
|
||||
|
||||
## Handle `steer`
|
||||
|
||||
Event: `{id, message, pageUrl}`. The user typed or spoke into the global bar **Steer** control: page-level direction without picking an element or launching variant generation.
|
||||
|
||||
The mic button uses the browser **Web Speech API** (MVP): click to start, speak, stop automatically when the utterance ends, then the transcript submits as a steer event. Click again while listening to cancel without submitting.
|
||||
|
||||
This is lighter than `generate`: no screenshot, no element context, no variant cycling. Read `message` and inspect the live page or project files as needed, then either make edits or answer in prose.
|
||||
|
||||
When finished:
|
||||
|
||||
```bash
|
||||
node .cursor/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID steer_done ["Optional short note for a browser toast"]
|
||||
```
|
||||
|
||||
On failure:
|
||||
|
||||
```bash
|
||||
node .cursor/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID error "Short reason"
|
||||
```
|
||||
|
||||
Then poll again immediately. Do not send a separate "picked up" reply. The Steer bar stays locked until `steer_done` or `error` arrives over SSE.
|
||||
Event: `{id, message, pageUrl}`: page-level direction from the global bar's Steer control (typed or spoken), no element context, no variant cycling. Read `message`, inspect the page or files as needed, make edits or answer in prose. Reply `node .cursor/skills/impeccable/scripts/live-poll.mjs --reply EVENT_ID steer_done ["Optional short toast"]`, or on failure `--reply EVENT_ID error "Short reason"`, then poll immediately. No separate pickup reply; the Steer bar unlocks on `steer_done` or `error`.
|
||||
|
||||
## Handle `prefetch`
|
||||
|
||||
Event: `{pageUrl}`. The browser fires this the first time the user selects an element on a given route, as a latency shortcut; it signals the user is likely about to Go on a page you haven't read yet.
|
||||
|
||||
Resolve `pageUrl` to the underlying file:
|
||||
|
||||
- Root `/` → the `pageFile` returned by `live.mjs` (usually `public/index.html` or equivalent).
|
||||
- Sub-routes (e.g. `/docs`, `/docs/live`) → the generated or source file for that route. Use your knowledge of the project layout (multi-page static sites often resolve `/foo` → `public/foo/index.html`; SPAs may map all routes to a single entry).
|
||||
|
||||
Read the file into context, then poll again. No `--reply`: this is speculative pre-work; Go will come later. If you can't confidently resolve the route to a file, skip and poll again.
|
||||
|
||||
Dedupe is the browser's job (one prefetch per unique pathname per session); trust it. If the same file shows up twice from different routes mapping to the same file, the second Read is cached anyway.
|
||||
Event: `{pageUrl}`: fired once per route on first selection; the user is likely about to Go on a page you have not read. Resolve the route to its file (root `/` is usually the boot's `pageFile`; multi-page sites often map `/foo` to `public/foo/index.html`; SPAs map everything to one entry), read it, poll again. No `--reply`. If you cannot resolve it confidently, skip and poll.
|
||||
|
||||
## Handle `manual_edit_apply`
|
||||
|
||||
@@ -543,12 +308,7 @@ After source edits finish, reply exactly once with `node .cursor/skills/impeccab
|
||||
|
||||
## Exit
|
||||
|
||||
The user can stop live mode by:
|
||||
- Saying "stop live mode" / "exit live" in chat
|
||||
- Closing the browser tab (SSE drops, poll returns `exit` after 8s)
|
||||
- The browser's exit button
|
||||
|
||||
When the poll returns `exit`, proceed to cleanup. If the poll is still running as a background task, kill it first.
|
||||
The user stops live mode by saying so in chat, closing the tab (SSE drops; poll returns `exit` after 8s), or the browser's exit button. On `exit`, kill any still-running background poll, then clean up.
|
||||
|
||||
## Cleanup
|
||||
|
||||
@@ -556,175 +316,8 @@ When the poll returns `exit`, proceed to cleanup. If the poll is still running a
|
||||
node .cursor/skills/impeccable/scripts/live-server.mjs stop
|
||||
```
|
||||
|
||||
Stops the HTTP server and runs `live-inject.mjs --remove` to strip `localhost:…/live.js` from the HTML entry. To stop the server but keep the inject tag (for a quick restart), use `stop --keep-inject`. `.impeccable/live/config.json` persists as project config for future sessions.
|
||||
Stops the helper and runs `live-inject.mjs --remove` to strip the injected script (use `stop --keep-inject` to keep it for a quick restart; `.impeccable/live/config.json` persists as project config). Then search for and remove any leftover `impeccable-variants-start` wrappers and `impeccable-carbonize-start` blocks.
|
||||
|
||||
Then:
|
||||
- Remove any leftover variant wrappers (search for `impeccable-variants-start` markers).
|
||||
- Remove any leftover carbonize blocks (search for `impeccable-carbonize-start` markers).
|
||||
## First-time setup
|
||||
|
||||
## First-time setup (config missing or invalid)
|
||||
|
||||
If `live.mjs` outputs `{ ok: false, error: "config_missing" | "config_invalid", path }`, write the live config at the reported path. By default this is `.impeccable/live/config.json`.
|
||||
|
||||
Schema:
|
||||
|
||||
```json
|
||||
{
|
||||
"files": ["<path-or-glob>", "<path-or-glob>", ...],
|
||||
"exclude": ["<optional-glob>", ...],
|
||||
"insertBefore": "</body>",
|
||||
"commentSyntax": "html",
|
||||
"cspChecked": true
|
||||
}
|
||||
```
|
||||
|
||||
`files` is the inject target; **the HTML files the browser actually loads**, not necessarily source. Each entry is either a literal path (`"public/index.html"`) or a glob pattern (`"public/**/*.html"`). Tracked or generated doesn't matter here; wrap has its own generated-file guard and routes accepts through the fallback flow.
|
||||
|
||||
`exclude` (optional) is a list of glob patterns matching files to skip, even if a `files` glob would have included them. Use for email templates, demo fixtures, or any HTML that isn't a live page.
|
||||
|
||||
`cspChecked` tracks whether the CSP detection step below has already run. Absent on first setup; set to `true` after CSP is checked (whether patched, declined, or not needed).
|
||||
|
||||
**Hard-excluded paths (cannot be overridden).** `**/node_modules/**` and `**/.git/**` are never matched regardless of what the user writes. These are vendor/metadata directories and injecting into them would silently instrument third-party code.
|
||||
|
||||
**Glob syntax.** `**` matches any number of path segments (including zero), `*` matches any characters except `/`, `?` matches a single character except `/`. Paths are always relative to the project root with forward slashes.
|
||||
|
||||
| Framework | `files` | `insertBefore` | `commentSyntax` |
|
||||
|-----------|---------|----------------|-----------------|
|
||||
| SPA with single shell (Vite / React / Plain HTML) | `["index.html"]` | `</body>` | `html` |
|
||||
| Next.js (App Router) | `["app/layout.tsx"]` | `</body>` | `jsx` |
|
||||
| Next.js (Pages) | `["pages/_document.tsx"]` | `</body>` | `jsx` |
|
||||
| Nuxt | `["app.vue"]` | `</body>` | `html` |
|
||||
| Svelte / SvelteKit | `["src/app.html"]` | `</body>` | `html` |
|
||||
| TanStack Router (SPA, Vite) | `["index.html"]` | `</body>` | `html` |
|
||||
| TanStack Start (SSR) | `["src/routes/__root.tsx"]` | `<Scripts` | `jsx` |
|
||||
| Astro | `[" <root layout .astro>"]` | `</body>` | `html` |
|
||||
| Multi-page (separate HTML per route) | `["public/**/*.html"]`: a glob covering the served directory | `</body>` | `html` |
|
||||
|
||||
Pick an anchor that exists in every file (`</body>` almost always works). Use `insertAfter` if the anchor should match **after** a specific line.
|
||||
|
||||
**Framework adapters (auto-detected at inject time).** SvelteKit, Nuxt, and TanStack Start server-render their document shell, so a raw `<script>` in the entry template will not execute reliably. `live-inject.mjs` detects these from the project and routes to a dedicated adapter instead of the literal `files` patch: SvelteKit mounts a dev-only root component from `+layout.svelte`; Nuxt writes a dev-only `.client.ts` plugin; TanStack Start (detected by `@tanstack/react-start` plus `src/routes/__root.tsx`) patches the `__root` document to render a generated dev-only `src/impeccable/ImpeccableLiveRoot` component that appends the bundle on mount. The `files` value stays a valid detection/CSP hint but is not the literal insertion site. A plain TanStack Router SPA (no `@tanstack/react-start`) has a static `index.html` and takes the baseline Vite path with no adapter.
|
||||
|
||||
For multi-page sites, **prefer a glob over a literal file list**. New pages added later are picked up automatically on the next `live-inject.mjs` run; no config maintenance needed.
|
||||
|
||||
For multi-page sites whose pages are *rebuilt* by a generator (Astro, static-site generators, custom scripts like `build-sub-pages.js`), the inject survives only until the next regeneration. Re-run `live.mjs` after each build. Accept is unaffected; it writes to true source via the fallback flow.
|
||||
|
||||
### Drift-heal warning
|
||||
|
||||
On every `live.mjs` boot, after inject, the project is scanned for HTML files under common page-source roots (`public/`, `src/`, `app/`, `pages/`). If any exist that aren't covered by the resolved `files` list, the output includes a `configDrift` field:
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"serverPort": 8400,
|
||||
"pageFiles": [ "..." ],
|
||||
"configDrift": {
|
||||
"orphans": ["public/new-section/index.html", "public/docs/new-command.html"],
|
||||
"orphanCount": 2,
|
||||
"hint": "2 HTML file(s) exist but aren't in config.files. Consider adding them, or use a glob pattern like \"public/**/*.html\"."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
When `configDrift` is present, surface it to the user once per session before entering the poll loop:
|
||||
|
||||
> Noticed N HTML file(s) in the project that aren't in `config.files`:
|
||||
>
|
||||
> - `public/new-section/index.html`
|
||||
> - `public/docs/new-command.html`
|
||||
>
|
||||
> Add them, or switch `files` to a glob like `["public/**/*.html"]` and let it track new pages automatically?
|
||||
|
||||
Don't auto-update the config; let the user decide. `configDrift` is `null` when there's no drift.
|
||||
|
||||
### CSP detection (first-time only)
|
||||
|
||||
If `config.cspChecked === true`, skip this entire section. You already asked this user once; the answer sticks.
|
||||
|
||||
Otherwise, run the detection helper:
|
||||
|
||||
```bash
|
||||
node .cursor/skills/impeccable/scripts/detect-csp.mjs
|
||||
```
|
||||
|
||||
Output: `{ shape, signals }` where `shape` is one of `append-arrays`, `append-string`, `middleware`, `meta-tag`, or `null`. The shape is named by *patch mechanism*, so one template covers many frameworks.
|
||||
|
||||
- **`null`**: no CSP; skip to writing `.impeccable/live/config.json` with `cspChecked: true`.
|
||||
- **`append-arrays`**: CSP defined as structured directive arrays. Auto-patchable. See *append-arrays* below. Covers:
|
||||
- Monorepo helpers with `additionalScriptSrc` / `additionalConnectSrc` options (Next.js + shared config package)
|
||||
- SvelteKit `kit.csp.directives`
|
||||
- Nuxt `nuxt-security` module's `contentSecurityPolicy`
|
||||
- **`append-string`**: CSP written as a literal value string. Auto-patchable. See *append-string* below. Covers:
|
||||
- Inline `next.config.*` `headers()` with a CSP literal
|
||||
- Nuxt `routeRules` / `nitro.routeRules` headers
|
||||
- **`middleware`** or **`meta-tag`**: rarer. Detected but not auto-patched in v1. Show the user the detected files and ask them to add `http://localhost:8400` to `script-src` and `connect-src` manually, then mark `cspChecked: true` and proceed.
|
||||
|
||||
#### Consent prompt template
|
||||
|
||||
Use this phrasing so the experience is consistent across agents:
|
||||
|
||||
> **CSP patch needed.** I detected a Content Security Policy in your project that blocks `http://localhost:8400`: the live picker won't load without an allowance. Here's the change I'd make:
|
||||
>
|
||||
> ```diff
|
||||
> [file: <patchTarget>]
|
||||
> [exact diff, 2–5 lines]
|
||||
> ```
|
||||
>
|
||||
> It's guarded by `NODE_ENV === "development"` so the extra entry only appears in dev and never reaches production. You can remove it any time by reverting this file. Apply? [y/n]
|
||||
|
||||
On "no": skip the patch, mention live won't work until the user adds the allowance manually, still write `cspChecked: true` (the question's been asked).
|
||||
|
||||
On "yes": apply the Shape-specific patch below, then write `cspChecked: true`.
|
||||
|
||||
#### append-arrays
|
||||
|
||||
CSP expressed as structured directive arrays. Patch mechanism: declare a dev-only array, spread it into the script-src and connect-src arrays.
|
||||
|
||||
**Declare near the top of the file that holds the CSP arrays:**
|
||||
|
||||
```ts
|
||||
// Dev-only allowance so impeccable live mode can load. Guarded by NODE_ENV.
|
||||
const __impeccableLiveDev =
|
||||
process.env.NODE_ENV === "development" ? ["http://localhost:8400"] : [];
|
||||
```
|
||||
|
||||
**Append `...__impeccableLiveDev` to the script-src and connect-src directive arrays.** Per-framework specifics:
|
||||
|
||||
- **Next.js + monorepo helper**: edit the *app's* `next.config.*` (not the shared helper), appending to `additionalScriptSrc` and `additionalConnectSrc` passed into `createBaseNextConfig` (or equivalent). Keeps the shared package clean.
|
||||
- **SvelteKit**: edit `svelte.config.js`, appending to `kit.csp.directives['script-src']` and `kit.csp.directives['connect-src']`.
|
||||
- **Nuxt + nuxt-security**: edit `nuxt.config.*`, appending to `security.headers.contentSecurityPolicy['script-src']` and `['connect-src']`.
|
||||
|
||||
Reference outputs:
|
||||
- `tests/framework-fixtures/nextjs-turborepo/expected-after-patch.ts` (Next.js)
|
||||
- `tests/framework-fixtures/sveltekit-csp/expected-after-patch.js` (SvelteKit)
|
||||
|
||||
Idempotency: if `__impeccableLiveDev` already exists in the file, the patch is already applied; skip asking and just mark `cspChecked: true`.
|
||||
|
||||
#### append-string
|
||||
|
||||
CSP built as a literal value string. Two-point patch: declare a dev-only string near the top, interpolate it into the CSP at the `script-src` and `connect-src` directives.
|
||||
|
||||
```ts
|
||||
// Dev-only allowance so impeccable live mode can load.
|
||||
const __impeccableLiveDev =
|
||||
process.env.NODE_ENV === "development" ? " http://localhost:8400" : "";
|
||||
```
|
||||
|
||||
Then in the CSP value string:
|
||||
- `script-src 'self' 'unsafe-inline'` → `` `script-src 'self' 'unsafe-inline'${__impeccableLiveDev}` ``
|
||||
- `connect-src 'self'` → `` `connect-src 'self'${__impeccableLiveDev}` ``
|
||||
|
||||
(Leading space on the dev string so it concatenates cleanly into the existing value. Convert the literal CSP directives into template strings as part of the edit if they aren't already.)
|
||||
|
||||
Per-framework specifics:
|
||||
- **Next.js inline `headers()`**: edit `next.config.*`, splicing the variable into the CSP value.
|
||||
- **Nuxt `routeRules`**: edit `nuxt.config.*`, splicing into the CSP in `routeRules['/**'].headers['Content-Security-Policy']`.
|
||||
|
||||
Reference outputs:
|
||||
- `tests/framework-fixtures/nextjs-inline-csp/expected-after-patch.js` (Next.js)
|
||||
- `tests/framework-fixtures/nuxt-csp/expected-after-patch.ts` (Nuxt)
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
If a user says "no" to the CSP patch at setup time and later complains that live doesn't work: their dev CSP blocks `http://localhost:8400`. Fix: delete `cspChecked` from `.impeccable/live/config.json` and re-run `live.mjs`: setup will ask again.
|
||||
|
||||
Then re-run `live.mjs`.
|
||||
Only when `live.mjs` reports `config_missing` / `config_invalid`, or `configDrift` needs explaining, or the config lacks `cspChecked`: read [live-setup.md](live-setup.md). It owns the config schema, the per-framework `files` table, injection adapters, drift healing, and the CSP detection and consent flow.
|
||||
|
||||
@@ -27,6 +27,7 @@ import {
|
||||
inlineSvelteComponentAccept,
|
||||
removeSvelteComponentSession,
|
||||
} from './live/svelte-component.mjs';
|
||||
import { enterLiveRoot } from './live/roots.mjs';
|
||||
|
||||
const ACCEPT_LOCK_WAIT_MS = 1_000;
|
||||
// Mirrors VARIANT_ID_PATTERN in live/event-validation.mjs, which gates the same
|
||||
@@ -946,6 +947,7 @@ function argVal(args, flag) {
|
||||
// Auto-execute when run directly
|
||||
const _running = process.argv[1];
|
||||
if (_running?.endsWith('live-accept.mjs') || _running?.endsWith('live-accept.mjs/')) {
|
||||
enterLiveRoot();
|
||||
acceptCli();
|
||||
}
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -3,8 +3,12 @@
|
||||
* Canonical durable completion acknowledgement for Impeccable live sessions.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { createLiveSessionStore } from './live/session-store.mjs';
|
||||
import { readLiveServerInfo } from './lib/impeccable-paths.mjs';
|
||||
import { enterLiveRoot } from './live/roots.mjs';
|
||||
import { verifyAcceptedFile } from './live/accept-verify.mjs';
|
||||
|
||||
function parseArgs(argv) {
|
||||
const out = { status: 'complete' };
|
||||
@@ -15,6 +19,7 @@ function parseArgs(argv) {
|
||||
else if (arg === '--discarded' || arg === '--discard') out.status = 'discarded';
|
||||
else if (arg === '--error') { out.status = 'agent_error'; out.message = argv[++i] || 'unknown error'; }
|
||||
else if (arg.startsWith('--error=')) { out.status = 'agent_error'; out.message = arg.slice('--error='.length); }
|
||||
else if (arg === '--force') out.force = true;
|
||||
else if (arg === '--help' || arg === '-h') out.help = true;
|
||||
}
|
||||
return out;
|
||||
@@ -23,10 +28,36 @@ function parseArgs(argv) {
|
||||
export async function completeCli() {
|
||||
const args = parseArgs(process.argv.slice(2));
|
||||
if (args.help || !args.id) {
|
||||
console.log(`Usage: node live-complete.mjs --id SESSION_ID [--discarded|--error MESSAGE]\n\nAppend the final durable session acknowledgement. Use after accept/discard cleanup is verified.`);
|
||||
console.log(`Usage: node live-complete.mjs --id SESSION_ID [--discarded|--error MESSAGE] [--force]\n\nAppend the final durable session acknowledgement. Use after accept/discard cleanup is verified.\nCompletion is refused while the session's source file still carries live-mode leftovers\n(markers, data-p-* attributes, unbaked --p-* vars); fix the file or pass --force.`);
|
||||
process.exit(args.help ? 0 : 1);
|
||||
}
|
||||
|
||||
// The carbonize contract used to be prose; this makes it mechanical. A
|
||||
// "complete" while the source still carries live plumbing is how markers
|
||||
// and dead param branches accumulated across sessions.
|
||||
if (args.status === 'complete' && !args.force) {
|
||||
const store = createLiveSessionStore({ cwd: process.cwd(), sessionId: args.id });
|
||||
const snapshot = store.getSnapshot(args.id, { includeCompleted: true });
|
||||
const sourceFile = snapshot?.sourceFile;
|
||||
const absSource = sourceFile ? path.resolve(process.cwd(), sourceFile) : null;
|
||||
const relSource = absSource ? path.relative(process.cwd(), absSource) : null;
|
||||
const insideProject = relSource !== null && relSource !== '' && !relSource.startsWith('..') && !path.isAbsolute(relSource);
|
||||
if (insideProject && !relSource.startsWith('node_modules' + path.sep) && !relSource.startsWith('node_modules/')) {
|
||||
const verify = verifyAcceptedFile(fs, absSource);
|
||||
if (!verify.clean) {
|
||||
console.log(JSON.stringify({
|
||||
ok: false,
|
||||
error: 'source_dirty',
|
||||
id: args.id,
|
||||
file: sourceFile,
|
||||
findings: verify.findings,
|
||||
hint: 'The accepted source still carries live-mode leftovers. Finish the carbonize cleanup (bake params, remove markers and data-p-* attributes), then run live-complete again. Use --force only if a finding is a false positive.',
|
||||
}, null, 2));
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const serverInfo = readServerInfo();
|
||||
const serverResult = serverInfo ? await completeThroughServer(serverInfo, args) : null;
|
||||
if (serverResult?.ok) {
|
||||
@@ -71,5 +102,6 @@ async function completeThroughServer(info, args) {
|
||||
|
||||
const _running = process.argv[1];
|
||||
if (_running?.endsWith('live-complete.mjs') || _running?.endsWith('live-complete.mjs/')) {
|
||||
enterLiveRoot();
|
||||
completeCli();
|
||||
}
|
||||
|
||||
@@ -7,6 +7,11 @@
|
||||
* every subsequent run, this script handles insert/remove deterministically
|
||||
* with zero LLM involvement.
|
||||
*
|
||||
* Framework knowledge lives in `live/frameworks/` — detection order, adapters,
|
||||
* the generic tag strategy, and the per-extension authoring traits live-wrap
|
||||
* reads. This file is the CLI around it: resolve config, resolve the
|
||||
* framework, heal orphaned artifacts, apply or remove, record the journal.
|
||||
*
|
||||
* Usage:
|
||||
* node live-inject.mjs --port PORT [--token TOKEN] # Insert the live script tag
|
||||
* node live-inject.mjs --remove # Remove the live script tag
|
||||
@@ -23,22 +28,36 @@ import path from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { resolveLiveConfigPath } from './lib/impeccable-paths.mjs';
|
||||
import {
|
||||
applySvelteKitLiveAdapter,
|
||||
detectSvelteKitProject,
|
||||
removeSvelteKitLiveAdapter,
|
||||
} from './live/sveltekit-adapter.mjs';
|
||||
describeInjectArtifacts,
|
||||
frameworkIgnorePatterns,
|
||||
resolveFramework,
|
||||
resolveSourceTraits,
|
||||
} from './live/frameworks/index.mjs';
|
||||
import {
|
||||
applyTanStackLiveAdapter,
|
||||
detectTanStackStartProject,
|
||||
removeTanStackLiveAdapter,
|
||||
} from './live/tanstack-adapter.mjs';
|
||||
clearInjectJournal,
|
||||
healInjectJournal,
|
||||
recordInjection,
|
||||
} from './live/frameworks/journal.mjs';
|
||||
import {
|
||||
buildTagBlock,
|
||||
insertTag,
|
||||
patchCspMeta,
|
||||
removeTag,
|
||||
revertCspMeta,
|
||||
} from './live/frameworks/tag-strategy.mjs';
|
||||
import { buildLiveScriptSrc } from './live/frameworks/script-src.mjs';
|
||||
import { enterLiveRoot } from './live/roots.mjs';
|
||||
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
||||
const CONFIG_PATH = resolveLiveConfigPath({ cwd: process.cwd(), scriptsDir: __dirname });
|
||||
const MARKER_OPEN_TEXT = 'impeccable-live-start';
|
||||
const MARKER_CLOSE_TEXT = 'impeccable-live-end';
|
||||
const NUXT_PLUGIN_MARKER = 'impeccable-live-nuxt-plugin';
|
||||
const NUXT_PLUGIN_NAME = 'impeccable-live.client.ts';
|
||||
// Resolved lazily so the enterLiveRoot() chdir in the CLI guard below takes
|
||||
// effect first; module scope runs before the guard.
|
||||
let CONFIG_PATH_CACHED = null;
|
||||
function CONFIG_PATH_GET() {
|
||||
if (!CONFIG_PATH_CACHED) {
|
||||
CONFIG_PATH_CACHED = resolveLiveConfigPath({ cwd: process.cwd(), scriptsDir: __dirname });
|
||||
}
|
||||
return CONFIG_PATH_CACHED;
|
||||
}
|
||||
const IGNORE_MARKER_OPEN = '# impeccable-live-ignore-start';
|
||||
const IGNORE_MARKER_CLOSE = '# impeccable-live-ignore-end';
|
||||
|
||||
@@ -47,6 +66,9 @@ export const LIVE_IGNORE_PATTERNS = Object.freeze([
|
||||
'.impeccable/hook.pending.json',
|
||||
'.impeccable/config.local.json',
|
||||
'.impeccable/live/server.json',
|
||||
'.impeccable/live/roots.json',
|
||||
'.impeccable/live/app-root.json',
|
||||
'.impeccable/live/inject-journal.json',
|
||||
'.impeccable/live/sessions/',
|
||||
'.impeccable/live/previews/',
|
||||
'.impeccable/live/annotations/',
|
||||
@@ -102,60 +124,61 @@ Output (JSON):
|
||||
}
|
||||
|
||||
if (args.includes('--check')) {
|
||||
if (!fs.existsSync(CONFIG_PATH)) {
|
||||
console.log(JSON.stringify({ ok: false, error: 'config_missing', path: CONFIG_PATH }));
|
||||
// Deliberately read-only: --check runs from status paths and must never
|
||||
// mutate the tree. Journal reconciliation happens on the inject run.
|
||||
if (!fs.existsSync(CONFIG_PATH_GET())) {
|
||||
console.log(JSON.stringify({ ok: false, error: 'config_missing', path: CONFIG_PATH_GET() }));
|
||||
process.exit(0);
|
||||
}
|
||||
let cfg;
|
||||
try {
|
||||
cfg = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
|
||||
cfg = JSON.parse(fs.readFileSync(CONFIG_PATH_GET(), 'utf-8'));
|
||||
} catch (err) {
|
||||
console.log(JSON.stringify({ ok: false, error: 'config_invalid', message: err.message, path: CONFIG_PATH }));
|
||||
console.log(JSON.stringify({ ok: false, error: 'config_invalid', message: err.message, path: CONFIG_PATH_GET() }));
|
||||
return;
|
||||
}
|
||||
try {
|
||||
validateConfig(cfg);
|
||||
} catch (err) {
|
||||
console.log(JSON.stringify({ ok: false, error: 'config_invalid', message: err.message, path: CONFIG_PATH }));
|
||||
console.log(JSON.stringify({ ok: false, error: 'config_invalid', message: err.message, path: CONFIG_PATH_GET() }));
|
||||
return;
|
||||
}
|
||||
console.log(JSON.stringify({ ok: true, config: cfg, path: CONFIG_PATH }));
|
||||
console.log(JSON.stringify({ ok: true, config: cfg, path: CONFIG_PATH_GET() }));
|
||||
return;
|
||||
}
|
||||
|
||||
// Load config
|
||||
if (!fs.existsSync(CONFIG_PATH)) {
|
||||
console.error(JSON.stringify({ ok: false, error: 'config_missing', path: CONFIG_PATH }));
|
||||
if (!fs.existsSync(CONFIG_PATH_GET())) {
|
||||
console.error(JSON.stringify({ ok: false, error: 'config_missing', path: CONFIG_PATH_GET() }));
|
||||
process.exit(1);
|
||||
}
|
||||
const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
|
||||
const config = JSON.parse(fs.readFileSync(CONFIG_PATH_GET(), 'utf-8'));
|
||||
validateConfig(config);
|
||||
|
||||
const resolvedFiles = resolveFiles(process.cwd(), config);
|
||||
const svelteKit = detectSvelteKitProject(process.cwd(), config);
|
||||
const nuxt = detectNuxtProject(process.cwd());
|
||||
const tanstack = svelteKit || nuxt ? null : detectTanStackStartProject(process.cwd());
|
||||
const cwd = process.cwd();
|
||||
const resolvedFiles = resolveFiles(cwd, config);
|
||||
const resolved = resolveFramework(cwd, config);
|
||||
const isAdapter = resolved?.framework.inject.kind === 'adapter';
|
||||
|
||||
if (args.includes('--remove')) {
|
||||
if (svelteKit) {
|
||||
const adapterResult = removeSvelteKitLiveAdapter({ cwd: process.cwd(), config });
|
||||
console.log(JSON.stringify({ ok: true, adapter: 'sveltekit', results: [adapterResult] }));
|
||||
return;
|
||||
}
|
||||
if (tanstack) {
|
||||
const adapterResult = removeTanStackLiveAdapter({ cwd: process.cwd(), project: tanstack });
|
||||
console.log(JSON.stringify({ ok: !adapterResult.error, adapter: 'tanstack-start', results: [adapterResult] }));
|
||||
if (adapterResult.error) process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
if (nuxt) {
|
||||
const adapterResult = removeNuxtLiveAdapter({ cwd: process.cwd(), project: nuxt });
|
||||
console.log(JSON.stringify({ ok: !adapterResult.error, adapter: 'nuxt', results: [adapterResult] }));
|
||||
if (adapterResult.error) process.exitCode = 1;
|
||||
if (isAdapter) {
|
||||
const adapterResult = resolved.framework.inject.remove({ cwd, config, project: resolved.project });
|
||||
const ok = !(adapterResult && adapterResult.error);
|
||||
// Anything the adapter could not reach (its detection may have shifted
|
||||
// since the session started) is still on the journal.
|
||||
const { healed } = healInjectJournal(cwd);
|
||||
clearInjectJournal(cwd);
|
||||
console.log(JSON.stringify({
|
||||
ok,
|
||||
adapter: resolved.framework.name,
|
||||
results: [adapterResult],
|
||||
healed: healed.length ? healed : undefined,
|
||||
}));
|
||||
if (!ok) process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
const results = resolvedFiles.map((relFile) => {
|
||||
const absFile = path.resolve(process.cwd(), relFile);
|
||||
const absFile = path.resolve(cwd, relFile);
|
||||
if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
|
||||
const content = fs.readFileSync(absFile, 'utf-8');
|
||||
const detagged = removeTag(content, config.commentSyntax);
|
||||
@@ -168,7 +191,9 @@ Output (JSON):
|
||||
cspReverted: updated !== detagged,
|
||||
};
|
||||
});
|
||||
console.log(JSON.stringify({ ok: true, results }));
|
||||
const { healed } = healInjectJournal(cwd);
|
||||
clearInjectJournal(cwd);
|
||||
console.log(JSON.stringify({ ok: true, results, healed: healed.length ? healed : undefined }));
|
||||
return;
|
||||
}
|
||||
|
||||
@@ -180,50 +205,68 @@ Output (JSON):
|
||||
process.exit(1);
|
||||
}
|
||||
// Optional server token: appended to the /live.js src so the token-gated
|
||||
// /live.js handler authorizes the browser fetch. `live.mjs` always passes it.
|
||||
// /live.js handler authorizes the browser fetch. `live.mjs` always passes
|
||||
// it; a manual `--port`-only invocation reads the running helper's token
|
||||
// from server.json instead of writing an unauthenticated URL that 401s.
|
||||
const tokenIdx = args.indexOf('--token');
|
||||
const token = tokenIdx !== -1 ? args[tokenIdx + 1] : undefined;
|
||||
const gitIgnore = ensureLiveGitIgnores(
|
||||
process.cwd(),
|
||||
nuxt ? [nuxt.pluginFile] : tanstack ? [tanstack.componentFile] : [],
|
||||
);
|
||||
let token = tokenIdx !== -1 ? args[tokenIdx + 1] : undefined;
|
||||
if (!token) {
|
||||
try {
|
||||
const info = JSON.parse(fs.readFileSync(path.join(cwd, '.impeccable', 'live', 'server.json'), 'utf-8'));
|
||||
// A record for a DIFFERENT port is a stale or foreign helper; its token
|
||||
// would 401 just the same, so only adopt a matching one.
|
||||
if (info?.token && Number(info.port) === port) token = info.token;
|
||||
} catch { /* no running helper recorded; keep legacy tokenless behavior */ }
|
||||
}
|
||||
|
||||
if (svelteKit) {
|
||||
const adapterResult = applySvelteKitLiveAdapter({ cwd: process.cwd(), port, token, config });
|
||||
console.log(JSON.stringify({ ok: true, port, adapter: 'sveltekit', gitIgnore, results: [adapterResult] }));
|
||||
return;
|
||||
}
|
||||
if (tanstack) {
|
||||
const adapterResult = applyTanStackLiveAdapter({ cwd: process.cwd(), port, token, project: tanstack });
|
||||
console.log(JSON.stringify({
|
||||
ok: !adapterResult.error,
|
||||
// Reconcile before writing anything. Artifacts this run is about to own are
|
||||
// kept (so a repeat inject stays byte-idempotent); artifacts left behind by
|
||||
// a session that never got to stop are healed.
|
||||
const plannedArtifacts = describeInjectArtifacts(resolved, { cwd, files: resolvedFiles });
|
||||
const { healed } = healInjectJournal(cwd, { keep: plannedArtifacts.map((a) => a.path) });
|
||||
|
||||
const gitIgnore = ensureLiveGitIgnores(cwd, frameworkIgnorePatterns(resolved));
|
||||
// In a nested-app repo the roots pointer lives at the REPO root, outside the
|
||||
// reach of the appRoot-relative ignore block above; give that directory its
|
||||
// own local excludes so the pointer (absolute host paths) never gets staged.
|
||||
try {
|
||||
const rootsManifest = JSON.parse(fs.readFileSync(path.join(cwd, '.impeccable', 'live', 'roots.json'), 'utf-8'));
|
||||
if (rootsManifest?.repoRoot && path.resolve(rootsManifest.repoRoot) !== path.resolve(cwd)) {
|
||||
ensureLiveGitIgnores(rootsManifest.repoRoot);
|
||||
}
|
||||
} catch { /* no manifest: single-root project */ }
|
||||
|
||||
if (isAdapter) {
|
||||
const adapterResult = resolved.framework.inject.apply({
|
||||
cwd,
|
||||
port,
|
||||
adapter: 'tanstack-start',
|
||||
token,
|
||||
config,
|
||||
project: resolved.project,
|
||||
});
|
||||
const ok = !(adapterResult && adapterResult.error);
|
||||
if (ok) recordInjection(cwd, { framework: resolved.framework.name, port, artifacts: plannedArtifacts });
|
||||
console.log(JSON.stringify({
|
||||
ok,
|
||||
port,
|
||||
adapter: resolved.framework.name,
|
||||
gitIgnore,
|
||||
results: [adapterResult],
|
||||
healed: healed.length ? healed : undefined,
|
||||
}));
|
||||
if (adapterResult.error) process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
if (nuxt) {
|
||||
const adapterResult = applyNuxtLiveAdapter({ cwd: process.cwd(), port, token, project: nuxt });
|
||||
console.log(JSON.stringify({
|
||||
ok: !adapterResult.error,
|
||||
port,
|
||||
adapter: 'nuxt',
|
||||
gitIgnore,
|
||||
results: [adapterResult],
|
||||
}));
|
||||
if (adapterResult.error) process.exitCode = 1;
|
||||
if (!ok) process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
|
||||
const results = resolvedFiles.map((relFile) => {
|
||||
const absFile = path.resolve(process.cwd(), relFile);
|
||||
const absFile = path.resolve(cwd, relFile);
|
||||
if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
|
||||
const content = fs.readFileSync(absFile, 'utf-8');
|
||||
const withoutOld = revertCspMeta(removeTag(content, config.commentSyntax));
|
||||
const withTag = insertTag(withoutOld, config, port, relFile, token);
|
||||
// Per-file, not per-project: a Vite app can hold an .astro partial, and a
|
||||
// framework project's entry template is often plain HTML.
|
||||
const scriptAttrs = resolveSourceTraits(relFile).injectScriptAttrs;
|
||||
const withTag = insertTag(withoutOld, config, port, token, scriptAttrs);
|
||||
if (withTag === withoutOld) {
|
||||
return { file: relFile, error: 'insertion_point_not_found', anchor: config.insertBefore || config.insertAfter };
|
||||
}
|
||||
@@ -236,7 +279,19 @@ Output (JSON):
|
||||
};
|
||||
});
|
||||
const anyInserted = results.some((r) => r.inserted);
|
||||
console.log(JSON.stringify({ ok: anyInserted, port, gitIgnore, results }));
|
||||
const writtenFiles = new Set(results.filter((r) => r.inserted).map((r) => r.file));
|
||||
recordInjection(cwd, {
|
||||
framework: resolved?.framework.name,
|
||||
port,
|
||||
artifacts: plannedArtifacts.filter((a) => writtenFiles.has(a.path)),
|
||||
});
|
||||
console.log(JSON.stringify({
|
||||
ok: anyInserted,
|
||||
port,
|
||||
gitIgnore,
|
||||
results,
|
||||
healed: healed.length ? healed : undefined,
|
||||
}));
|
||||
if (!anyInserted) process.exit(1);
|
||||
}
|
||||
|
||||
@@ -271,115 +326,6 @@ export function ensureLiveGitIgnores(cwd = process.cwd(), extraPatterns = []) {
|
||||
};
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Nuxt adapter
|
||||
//
|
||||
// A script element placed in app.vue is compiled as Vue-rendered DOM and is
|
||||
// not executed. Nuxt instead auto-discovers client plugins. Keep the adapter
|
||||
// generated, dev-only, and outside user-authored source: Live creates one
|
||||
// marked .client.ts plugin on start and removes it on stop.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export function detectNuxtProject(cwd = process.cwd()) {
|
||||
const configFile = fs.readdirSync(cwd, { withFileTypes: true })
|
||||
.find((entry) => entry.isFile() && /^nuxt\.config\.(?:js|mjs|cjs|ts|mts|cts)$/.test(entry.name))
|
||||
?.name;
|
||||
if (!configFile) return null;
|
||||
|
||||
const config = fs.readFileSync(path.join(cwd, configFile), 'utf-8');
|
||||
const literalSrcDir = config.match(/\bsrcDir\s*:\s*(['"])([^'"]+)\1/);
|
||||
let appDir = '';
|
||||
if (literalSrcDir) {
|
||||
const candidate = literalSrcDir[2]
|
||||
.replace(/\\/g, '/')
|
||||
.replace(/^\.\//, '')
|
||||
.replace(/\/+$/, '');
|
||||
const normalized = path.posix.normalize(candidate);
|
||||
if (normalized !== '..' && !normalized.startsWith('../') && !path.isAbsolute(normalized)) {
|
||||
appDir = normalized === '.' ? '' : normalized;
|
||||
}
|
||||
} else if (
|
||||
fs.existsSync(path.join(cwd, 'app', 'app.vue'))
|
||||
|| fs.existsSync(path.join(cwd, 'app', 'pages'))
|
||||
) {
|
||||
appDir = 'app';
|
||||
}
|
||||
|
||||
const pluginFile = [appDir, 'plugins', NUXT_PLUGIN_NAME].filter(Boolean).join('/');
|
||||
return { configFile, appDir, pluginFile };
|
||||
}
|
||||
|
||||
export function buildNuxtPlugin(port, token) {
|
||||
return `/* ${NUXT_PLUGIN_MARKER} */
|
||||
const liveSrc = '${buildLiveScriptSrc(port, token)}';
|
||||
const liveSelector = 'script[data-impeccable-live-nuxt]';
|
||||
|
||||
export default defineNuxtPlugin(() => {
|
||||
if (!import.meta.dev || typeof document === 'undefined') return;
|
||||
|
||||
const expectedSrc = new URL(liveSrc, window.location.href).href;
|
||||
let script = document.querySelector(liveSelector);
|
||||
if (script?.src === expectedSrc) return;
|
||||
script?.remove();
|
||||
|
||||
script = document.createElement('script');
|
||||
script.src = liveSrc;
|
||||
script.async = true;
|
||||
script.dataset.impeccableLiveNuxt = '';
|
||||
document.head.appendChild(script);
|
||||
|
||||
import.meta.hot?.dispose(() => {
|
||||
if (script?.isConnected) script.remove();
|
||||
});
|
||||
});
|
||||
/* /${NUXT_PLUGIN_MARKER} */
|
||||
`;
|
||||
}
|
||||
|
||||
export function applyNuxtLiveAdapter({ cwd = process.cwd(), port, token, project = detectNuxtProject(cwd) }) {
|
||||
if (!project) return { error: 'nuxt_not_detected' };
|
||||
const absFile = path.join(cwd, project.pluginFile);
|
||||
const existing = fs.existsSync(absFile) ? fs.readFileSync(absFile, 'utf-8') : null;
|
||||
if (existing !== null && !existing.includes(NUXT_PLUGIN_MARKER)) {
|
||||
return {
|
||||
file: project.pluginFile,
|
||||
error: 'nuxt_plugin_conflict',
|
||||
hint: `${project.pluginFile} already exists and is not managed by Impeccable Live`,
|
||||
};
|
||||
}
|
||||
|
||||
const content = buildNuxtPlugin(port, token);
|
||||
fs.mkdirSync(path.dirname(absFile), { recursive: true });
|
||||
if (content !== existing) fs.writeFileSync(absFile, content, 'utf-8');
|
||||
return {
|
||||
file: project.pluginFile,
|
||||
inserted: true,
|
||||
changed: content !== existing,
|
||||
devOnly: true,
|
||||
};
|
||||
}
|
||||
|
||||
export function removeNuxtLiveAdapter({ cwd = process.cwd(), project = detectNuxtProject(cwd) }) {
|
||||
if (!project) return { error: 'nuxt_not_detected' };
|
||||
const absFile = path.join(cwd, project.pluginFile);
|
||||
if (!fs.existsSync(absFile)) {
|
||||
return { file: project.pluginFile, removed: false, note: 'no adapter present' };
|
||||
}
|
||||
const content = fs.readFileSync(absFile, 'utf-8');
|
||||
if (!content.includes(NUXT_PLUGIN_MARKER)) {
|
||||
return {
|
||||
file: project.pluginFile,
|
||||
removed: false,
|
||||
error: 'nuxt_plugin_conflict',
|
||||
hint: `${project.pluginFile} is not managed by Impeccable Live`,
|
||||
};
|
||||
}
|
||||
fs.unlinkSync(absFile);
|
||||
const pluginDir = path.dirname(absFile);
|
||||
if (fs.readdirSync(pluginDir).length === 0) fs.rmdirSync(pluginDir);
|
||||
return { file: project.pluginFile, removed: true };
|
||||
}
|
||||
|
||||
function resolveIgnoreTarget(cwd) {
|
||||
const gitExcludePath = resolveGitInfoExcludePath(cwd);
|
||||
if (gitExcludePath) {
|
||||
@@ -527,242 +473,31 @@ function validateConfig(cfg) {
|
||||
}
|
||||
}
|
||||
|
||||
function commentOpen(syntax) { return syntax === 'jsx' ? '{/*' : '<!--'; }
|
||||
function commentClose(syntax) { return syntax === 'jsx' ? '*/}' : '-->'; }
|
||||
|
||||
/**
|
||||
* Build the /live.js src the browser loads. When a token is supplied it rides
|
||||
* as a `?token=...` query param so the server's token-gated /live.js handler
|
||||
* authorizes the fetch. Shared by every injection path (HTML/JSX script tag,
|
||||
* the Nuxt plugin, the SvelteKit root component) so they stay in sync.
|
||||
*/
|
||||
export function buildLiveScriptSrc(port, token) {
|
||||
const base = 'http://localhost:' + port + '/live.js';
|
||||
return token ? base + '?token=' + encodeURIComponent(token) : base;
|
||||
}
|
||||
|
||||
function buildTagBlock(syntax, port, filePath, token) {
|
||||
const open = commentOpen(syntax);
|
||||
const close = commentClose(syntax);
|
||||
// Astro processes <script> tags by default and rewrites src to its own
|
||||
// bundled URL. is:inline opts out so the literal external src survives.
|
||||
const isAstro = typeof filePath === 'string' && filePath.endsWith('.astro');
|
||||
const scriptAttrs = isAstro ? 'is:inline ' : '';
|
||||
return (
|
||||
open + ' ' + MARKER_OPEN_TEXT + ' ' + close + '\n' +
|
||||
'<script ' + scriptAttrs + 'src="' + buildLiveScriptSrc(port, token) + '"></script>\n' +
|
||||
open + ' ' + MARKER_CLOSE_TEXT + ' ' + close + '\n'
|
||||
);
|
||||
}
|
||||
|
||||
function detectLineEnding(content) {
|
||||
if (content.includes('\r\n')) return '\r\n';
|
||||
if (content.includes('\r')) return '\r';
|
||||
return '\n';
|
||||
}
|
||||
|
||||
function normalizeLineEndings(content, lineEnding) {
|
||||
return lineEnding === '\n' ? content : content.replace(/\n/g, lineEnding);
|
||||
}
|
||||
|
||||
function readLineEndingAt(content, index) {
|
||||
if (content[index] === '\r' && content[index + 1] === '\n') return '\r\n';
|
||||
if (content[index] === '\n') return '\n';
|
||||
if (content[index] === '\r') return '\r';
|
||||
return '';
|
||||
}
|
||||
|
||||
function insertTag(content, config, port, filePath, token) {
|
||||
const lineEnding = detectLineEnding(content);
|
||||
const block = normalizeLineEndings(buildTagBlock(config.commentSyntax, port, filePath, token), lineEnding);
|
||||
// insertBefore: match the LAST occurrence. Anchors like `</body>` naturally
|
||||
// belong at the end, and the same literal can appear earlier in code blocks
|
||||
// within rendered documentation pages.
|
||||
if (config.insertBefore) {
|
||||
const idx = content.lastIndexOf(config.insertBefore);
|
||||
if (idx === -1) return content;
|
||||
return content.slice(0, idx) + block + content.slice(idx);
|
||||
}
|
||||
// insertAfter: match the FIRST occurrence — typical anchors like `<head>` or
|
||||
// `<body>` open near the top of the document.
|
||||
const idx = content.indexOf(config.insertAfter);
|
||||
if (idx === -1) return content;
|
||||
const after = idx + config.insertAfter.length;
|
||||
// Preserve an existing trailing newline if the anchor already has one.
|
||||
// Slice the remainder from the original anchor offset, not prefix.length:
|
||||
// in the no-newline case prefix is one char longer than the anchor (the
|
||||
// appended '\n'), so slicing by prefix.length would drop the first real
|
||||
// character after the anchor (#227).
|
||||
const existingNewline = readLineEndingAt(content, after);
|
||||
const prefix = content.slice(0, after) + (existingNewline || lineEnding);
|
||||
const rest = content.slice(after + existingNewline.length);
|
||||
return prefix + block + rest;
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove the live script block. Matches either HTML or JSX comment markers
|
||||
* regardless of config (so stale tags from a wrong config can still be cleaned).
|
||||
*
|
||||
* Indent-preserving: captures any whitespace immediately preceding the opener
|
||||
* marker and re-emits it in place of the removed block. `insertTag` inserted
|
||||
* the block *after* the original line's indent and *before* the anchor (e.g.
|
||||
* `</body>`), which moved the indent onto the opener line and left the anchor
|
||||
* unindented. Replacing the whole block (plus its trailing newline) with just
|
||||
* the captured indent hands the indent back to the anchor that follows.
|
||||
*/
|
||||
function removeTag(content, _syntax) {
|
||||
const patterns = [
|
||||
/([ \t]*)<!--\s*impeccable-live-start\s*-->[\s\S]*?<!--\s*impeccable-live-end\s*-->([ \t]*(?:\r\n|\n|\r|$)?)/,
|
||||
/([ \t]*)\{\/\*\s*impeccable-live-start\s*\*\/\}[\s\S]*?\{\/\*\s*impeccable-live-end\s*\*\/\}([ \t]*(?:\r\n|\n|\r|$)?)/,
|
||||
];
|
||||
for (const pat of patterns) {
|
||||
let changed = false;
|
||||
let next = content;
|
||||
do {
|
||||
content = next;
|
||||
next = content.replace(pat, (_match, leadingIndent, trailing = '') => {
|
||||
if (/[\r\n]/.test(trailing)) return leadingIndent;
|
||||
return leadingIndent || trailing || '';
|
||||
});
|
||||
if (next !== content) changed = true;
|
||||
} while (next !== content);
|
||||
if (changed) return next;
|
||||
}
|
||||
return content;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Content-Security-Policy meta-tag patcher
|
||||
//
|
||||
// When the user's HTML carries `<meta http-equiv="Content-Security-Policy">`,
|
||||
// the cross-origin load of /live.js (and the SSE/POST connection back to
|
||||
// localhost:PORT) is blocked unless the CSP explicitly allows that origin.
|
||||
//
|
||||
// On insert: append `http://localhost:PORT` to `script-src` and `connect-src`,
|
||||
// and stash the original `content` value in a `data-impeccable-csp-original`
|
||||
// attribute (base64) so revert is exact.
|
||||
//
|
||||
// On remove: detect the marker attribute, decode it, restore the original
|
||||
// content value verbatim, drop the marker.
|
||||
//
|
||||
// Header-based CSP (Next.js headers, Nuxt routeRules, SvelteKit kit.csp,
|
||||
// shared helpers) is NOT patched here — those need framework-specific config
|
||||
// edits and are handled via the existing detect-csp.mjs reference output.
|
||||
// Only the in-source meta-tag form gets the auto-patch.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const CSP_MARKER_ATTR = 'data-impeccable-csp-original';
|
||||
|
||||
function findCspMetaTags(content) {
|
||||
const out = [];
|
||||
const tagRe = /<meta\s+([^>]*?)\/?>/gis;
|
||||
let m;
|
||||
while ((m = tagRe.exec(content)) !== null) {
|
||||
const attrs = m[1];
|
||||
if (!/(http-equiv|httpEquiv)\s*=\s*(['"])Content-Security-Policy\2/i.test(attrs)) continue;
|
||||
out.push({ start: m.index, end: m.index + m[0].length, full: m[0], attrs });
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function getAttr(attrs, name) {
|
||||
const re = new RegExp(`\\b${name}\\s*=\\s*(['"])([\\s\\S]*?)\\1`, 'i');
|
||||
const m = attrs.match(re);
|
||||
return m ? { quote: m[1], value: m[2], full: m[0] } : null;
|
||||
}
|
||||
|
||||
function appendOriginToDirective(csp, directive, origin) {
|
||||
const re = new RegExp(`(^|;)(\\s*)(${directive})\\s+([^;]*)`, 'i');
|
||||
const m = csp.match(re);
|
||||
if (m) {
|
||||
const tokens = m[4].trim().split(/\s+/);
|
||||
if (tokens.includes(origin)) return csp;
|
||||
return csp.replace(re, `${m[1]}${m[2]}${m[3]} ${[...tokens, origin].join(' ')}`);
|
||||
}
|
||||
// Directive missing — add it. Use 'self' + origin so we don't inadvertently
|
||||
// narrow the policy compared to the default-src fallback (most users with
|
||||
// an explicit CSP have 'self' there).
|
||||
return csp.trim().replace(/;?\s*$/, '') + `; ${directive} 'self' ${origin}`;
|
||||
}
|
||||
|
||||
export function patchCspMeta(content, port) {
|
||||
const tags = findCspMetaTags(content);
|
||||
if (tags.length === 0) return content;
|
||||
const origin = `http://localhost:${port}`;
|
||||
|
||||
// Walk last-to-first so prior splices don't invalidate later indices.
|
||||
let result = content;
|
||||
for (let i = tags.length - 1; i >= 0; i--) {
|
||||
const tag = tags[i];
|
||||
const attrs = tag.attrs;
|
||||
if (getAttr(attrs, CSP_MARKER_ATTR)) continue; // already patched
|
||||
const contentAttr = getAttr(attrs, 'content');
|
||||
if (!contentAttr) continue;
|
||||
|
||||
const original = contentAttr.value;
|
||||
let patched = original;
|
||||
patched = appendOriginToDirective(patched, 'script-src', origin);
|
||||
patched = appendOriginToDirective(patched, 'connect-src', origin);
|
||||
// The shader overlay during 'generating' creates a screenshot via
|
||||
// URL.createObjectURL, producing a `blob:` URL — img-src 'self' rejects
|
||||
// those. Add `blob:` so the overlay doesn't throw a CSP violation.
|
||||
patched = appendOriginToDirective(patched, 'img-src', 'blob:');
|
||||
if (patched === original) continue;
|
||||
|
||||
const newContentAttr = `content=${contentAttr.quote}${patched}${contentAttr.quote}`;
|
||||
const marker = `${CSP_MARKER_ATTR}="${Buffer.from(original, 'utf-8').toString('base64')}"`;
|
||||
// The tagRe captures any whitespace between the last attribute and the
|
||||
// closing `/>` as part of `attrs`. Naively appending ` ${marker}` after
|
||||
// a replace would land it BEFORE that trailing space, leaving a double
|
||||
// space inside attrs and clobbering the space before `/>`. Split off
|
||||
// the trailing whitespace, splice the marker into the attribute body,
|
||||
// and re-append the original trailing whitespace so a self-closing
|
||||
// `<meta … />` round-trips byte-for-byte.
|
||||
const trailingWs = (attrs.match(/[ \t]*$/) || [''])[0];
|
||||
const attrsBody = attrs.slice(0, attrs.length - trailingWs.length);
|
||||
const newAttrs = attrsBody.replace(contentAttr.full, newContentAttr) + ' ' + marker + trailingWs;
|
||||
const newTag = tag.full.replace(attrs, newAttrs);
|
||||
|
||||
result = result.slice(0, tag.start) + newTag + result.slice(tag.end);
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
export function revertCspMeta(content) {
|
||||
const tags = findCspMetaTags(content);
|
||||
if (tags.length === 0) return content;
|
||||
|
||||
let result = content;
|
||||
for (let i = tags.length - 1; i >= 0; i--) {
|
||||
const tag = tags[i];
|
||||
const origAttr = getAttr(tag.attrs, CSP_MARKER_ATTR);
|
||||
if (!origAttr) continue;
|
||||
const contentAttr = getAttr(tag.attrs, 'content');
|
||||
if (!contentAttr) continue;
|
||||
|
||||
let originalValue;
|
||||
try { originalValue = Buffer.from(origAttr.value, 'base64').toString('utf-8'); }
|
||||
catch { continue; }
|
||||
|
||||
const newContentAttr = `content=${contentAttr.quote}${originalValue}${contentAttr.quote}`;
|
||||
let newAttrs = tag.attrs.replace(contentAttr.full, newContentAttr);
|
||||
// Drop the marker attribute and any single space immediately preceding it.
|
||||
newAttrs = newAttrs.replace(new RegExp(`\\s*${origAttr.full}`), '');
|
||||
const newTag = tag.full.replace(tag.attrs, newAttrs);
|
||||
|
||||
result = result.slice(0, tag.start) + newTag + result.slice(tag.end);
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Auto-execute
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const _running = process.argv[1];
|
||||
if (_running?.endsWith('live-inject.mjs') || _running?.endsWith('live-inject.mjs/')) {
|
||||
enterLiveRoot();
|
||||
injectCli();
|
||||
}
|
||||
|
||||
export { insertTag, removeTag, validateConfig, buildTagBlock };
|
||||
// patchCspMeta + revertCspMeta are exported above where they're defined.
|
||||
// Re-exported so long-standing importers (live.mjs, the adapter modules, the
|
||||
// test suites) keep their entry points while the implementations live in
|
||||
// live/frameworks/.
|
||||
export {
|
||||
buildLiveScriptSrc,
|
||||
buildTagBlock,
|
||||
insertTag,
|
||||
patchCspMeta,
|
||||
removeTag,
|
||||
revertCspMeta,
|
||||
validateConfig,
|
||||
};
|
||||
export {
|
||||
applyNuxtLiveAdapter,
|
||||
buildNuxtPlugin,
|
||||
detectNuxtProject,
|
||||
removeNuxtLiveAdapter,
|
||||
} from './live/frameworks/nuxt.mjs';
|
||||
|
||||
@@ -26,6 +26,7 @@ import {
|
||||
scaffoldSvelteComponentInsertSession,
|
||||
shouldUseSvelteComponentInjection,
|
||||
} from './live/svelte-component.mjs';
|
||||
import { enterLiveRoot } from './live/roots.mjs';
|
||||
|
||||
const INSERT_POSITIONS = new Set(['before', 'after']);
|
||||
|
||||
@@ -286,5 +287,6 @@ Output (JSON):
|
||||
|
||||
const _running = process.argv[1];
|
||||
if (_running?.endsWith('live-insert.mjs') || _running?.endsWith('live-insert.mjs/')) {
|
||||
enterLiveRoot();
|
||||
insertCli();
|
||||
}
|
||||
|
||||
@@ -14,6 +14,8 @@ import path from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { completionAckForAcceptResult, completionTypeForAcceptResult } from './live/completion.mjs';
|
||||
import { readLiveServerInfo } from './lib/impeccable-paths.mjs';
|
||||
import { enterLiveRoot } from './live/roots.mjs';
|
||||
import { instructionsForEvent } from './live/instructions.mjs';
|
||||
|
||||
// Absolute path to a sibling script in this skill's scripts dir, so runtime
|
||||
// error hints print a directly-runnable command instead of a placeholder.
|
||||
@@ -27,7 +29,7 @@ const scriptCmd = (name) => `node "${path.join(SELF_DIR, name)}"`;
|
||||
export const PER_REQUEST_TIMEOUT_MS = 270_000;
|
||||
export const DEFAULT_EVENT_LEASE_MS = 600_000;
|
||||
|
||||
const EVENT_TYPES_NEEDING_AGENT_REPLY = new Set(['generate', 'steer', 'manual_edit_apply', 'carbonize_cleanup']);
|
||||
const EVENT_TYPES_NEEDING_AGENT_REPLY = new Set(['generate', 'steer', 'manual_edit_apply', 'carbonize_cleanup', 'variant_mount_failed']);
|
||||
|
||||
function readServerInfo() {
|
||||
const record = readLiveServerInfo(process.cwd());
|
||||
@@ -117,8 +119,11 @@ export async function postReply(base, token, reply) {
|
||||
});
|
||||
if (!res.ok) {
|
||||
const body = await res.json().catch(() => ({}));
|
||||
const parts = [body.error || res.statusText, body.reason, body.hint].filter(Boolean);
|
||||
throw new Error(parts.join(': '));
|
||||
const failureLines = Array.isArray(body.failures)
|
||||
? body.failures.map((f) => ` ${f.file}${f.line != null ? `:${f.line}` : ''} ${f.message}`).join('\n')
|
||||
: null;
|
||||
const parts = [body.error || res.statusText, body.reason, body.hint, failureLines, body._instructions].filter(Boolean);
|
||||
throw new Error(parts.join('\n'));
|
||||
}
|
||||
}
|
||||
|
||||
@@ -261,6 +266,13 @@ export function writeCarbonizeBanner(event) {
|
||||
}
|
||||
|
||||
export function printPollEvent(event) {
|
||||
// Situational plumbing rides with the event itself: `_instructions` is the
|
||||
// authoritative next step, with real ids and paths substituted, so the
|
||||
// reference doc can stay lean and can never drift from script behavior.
|
||||
if (event && typeof event === 'object' && !event._instructions) {
|
||||
const instructions = instructionsForEvent(event, { scriptsPath: SELF_DIR });
|
||||
if (instructions) event._instructions = instructions;
|
||||
}
|
||||
console.log(JSON.stringify(event));
|
||||
}
|
||||
|
||||
@@ -412,5 +424,6 @@ export function normalizePollTypes(value) {
|
||||
// Auto-execute when run directly
|
||||
const _running = process.argv[1];
|
||||
if (_running?.endsWith('live-poll.mjs') || _running?.endsWith('live-poll.mjs/')) {
|
||||
enterLiveRoot();
|
||||
pollCli();
|
||||
}
|
||||
|
||||
@@ -4,6 +4,7 @@
|
||||
*/
|
||||
|
||||
import { createLiveSessionStore } from './live/session-store.mjs';
|
||||
import { enterLiveRoot } from './live/roots.mjs';
|
||||
|
||||
function manualApplyReplyCommand(eventOrId = 'EVENT_ID') {
|
||||
const id = typeof eventOrId === 'string' ? eventOrId : eventOrId?.id || 'EVENT_ID';
|
||||
@@ -49,6 +50,28 @@ function collectManualApplyFiles(batch) {
|
||||
return [...new Set(files.filter((file) => typeof file === 'string' && file.length > 0))].sort();
|
||||
}
|
||||
|
||||
/**
|
||||
* The browser's render truth, folded into a small block the agent reads before
|
||||
* it decides what to do. `arrivedVariants` only says the agent published;
|
||||
* `renderState` says whether any of it reached a screen.
|
||||
*/
|
||||
export function renderSummary(snapshot = {}) {
|
||||
return {
|
||||
renderState: snapshot.renderState ?? null,
|
||||
mountedVariants: Array.isArray(snapshot.mountedVariants) ? snapshot.mountedVariants : [],
|
||||
mountFailures: Array.isArray(snapshot.mountFailures) ? snapshot.mountFailures : [],
|
||||
};
|
||||
}
|
||||
|
||||
export function mountFailureAction(snapshot = {}) {
|
||||
const failures = Array.isArray(snapshot.mountFailures) ? snapshot.mountFailures : [];
|
||||
const latest = failures[failures.length - 1];
|
||||
if (!latest) return null;
|
||||
const where = latest.url ? ` from ${latest.url}` : '';
|
||||
const why = latest.error ? ` (${latest.error})` : '';
|
||||
return `The browser failed to mount variant ${latest.variant}${where}${why}; nothing is on screen. Fix the variant files, then reply with live-poll.mjs --reply ${snapshot?.pendingEvent?.id || snapshot?.id || 'SESSION_ID'} done --file <manifest or source path> for the queued variant_mount_failed event (or republish) so the browser retries.`;
|
||||
}
|
||||
|
||||
function parseArgs(argv) {
|
||||
const out = { id: null };
|
||||
for (let i = 0; i < argv.length; i++) {
|
||||
@@ -75,20 +98,26 @@ export async function resumeCli() {
|
||||
}
|
||||
|
||||
const pending = snapshot.pendingEvent || null;
|
||||
const nextAction = pending
|
||||
? pending.type === 'manual_edit_apply'
|
||||
? manualApplyResumeHint(pending)
|
||||
: `Run live-poll.mjs, handle ${pending.type} ${pending.id}, then acknowledge with live-poll.mjs --reply ${pending.id} done.`
|
||||
: snapshot.phase === 'carbonize_required'
|
||||
? `Finish carbonize cleanup${snapshot.sourceFile ? ` in ${snapshot.sourceFile}` : ''}, then run live-complete.mjs --id ${snapshot.id}.`
|
||||
: snapshot.phase === 'accept_requested'
|
||||
? `Run live-complete.mjs --id ${snapshot.id} after verifying the accepted variant is written.`
|
||||
: `Inspect ${snapshot.id}; no pending agent event is currently queued.`;
|
||||
const render = renderSummary(snapshot);
|
||||
// A failed render outranks the generic pending-event hint: the agent needs to
|
||||
// know the user is staring at an error card, not at variants. A leased manual
|
||||
// Apply still outranks both, because abandoning that lease loses user edits.
|
||||
const mountAction = render.renderState === 'failed' ? mountFailureAction(snapshot) : null;
|
||||
const nextAction = pending?.type === 'manual_edit_apply'
|
||||
? manualApplyResumeHint(pending)
|
||||
: mountAction || (pending
|
||||
? `Run live-poll.mjs, handle ${pending.type} ${pending.id}, then acknowledge with live-poll.mjs --reply ${pending.id} done.`
|
||||
: snapshot.phase === 'carbonize_required'
|
||||
? `Finish carbonize cleanup${snapshot.sourceFile ? ` in ${snapshot.sourceFile}` : ''}, then run live-complete.mjs --id ${snapshot.id}.`
|
||||
: snapshot.phase === 'accept_requested'
|
||||
? `Run live-complete.mjs --id ${snapshot.id} after verifying the accepted variant is written.`
|
||||
: `Inspect ${snapshot.id}; no pending agent event is currently queued.`);
|
||||
|
||||
console.log(JSON.stringify({ active: true, snapshot, pendingEvent: pending, nextAction }, null, 2));
|
||||
console.log(JSON.stringify({ active: true, snapshot, pendingEvent: pending, render, nextAction }, null, 2));
|
||||
}
|
||||
|
||||
const _running = process.argv[1];
|
||||
if (_running?.endsWith('live-resume.mjs') || _running?.endsWith('live-resume.mjs/')) {
|
||||
enterLiveRoot();
|
||||
resumeCli();
|
||||
}
|
||||
|
||||
@@ -33,7 +33,10 @@ import { runGenerationPreflight } from './live/generation-preflight.mjs';
|
||||
import { validateEvent } from './live/event-validation.mjs';
|
||||
import { selectAvailablePendingEvent } from './live/poll-lanes.mjs';
|
||||
import { createManualEditRoutes } from './live/manual-edit-routes.mjs';
|
||||
import { LIVE_COMMANDS } from './live/vocabulary.mjs';
|
||||
import {
|
||||
LIVE_COMMANDS,
|
||||
VARIANT_PROGRESS_CHECKPOINT_REASONS as VARIANT_PROGRESS_CHECKPOINT_REASON_LIST,
|
||||
} from './live/vocabulary.mjs';
|
||||
import {
|
||||
getDesignSidecarPath,
|
||||
getLiveDir,
|
||||
@@ -51,24 +54,53 @@ import {
|
||||
} from './live/manual-apply.mjs';
|
||||
import {
|
||||
applyDeferredSvelteComponentAccepts,
|
||||
bumpSvelteComponentPreviewRevision,
|
||||
compileCheckVariants,
|
||||
removeAllSvelteComponentSessions,
|
||||
sweepInactiveSvelteComponentSessions,
|
||||
} from './live/svelte-component.mjs';
|
||||
import { enterLiveRoot } from './live/roots.mjs';
|
||||
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
||||
// PRODUCT.md / DESIGN.md live wherever context.mjs resolves. The generated
|
||||
// DESIGN sidecar is project-local at .impeccable/design.json, with legacy
|
||||
// DESIGN.json fallback for existing projects.
|
||||
const PROJECT_CONTEXT = loadContext(process.cwd());
|
||||
const CONTEXT_DIR = PROJECT_CONTEXT.contextDir;
|
||||
const DESIGN_MD_PATH = PROJECT_CONTEXT.designPath
|
||||
? path.resolve(process.cwd(), PROJECT_CONTEXT.designPath)
|
||||
: null;
|
||||
// Anchor the whole process on the live roots manifest before anything derives
|
||||
// a path from cwd. A server started from the wrong directory re-roots itself
|
||||
// onto the appRoot the boot decided on instead of minting a second project.
|
||||
const LIVE_ROOTS = enterLiveRoot(process.cwd());
|
||||
|
||||
// PRODUCT.md / DESIGN.md context, resolved lazily and per request so a server
|
||||
// that outlives an `impeccable document` run (or a context file created after
|
||||
// boot) reports current truth instead of a boot-time snapshot. The roots
|
||||
// manifest wins when the ambient resolution misses (nested app inheriting
|
||||
// repo-level context files).
|
||||
function resolveProjectContext() {
|
||||
const ctx = loadContext(process.cwd());
|
||||
const designPath = ctx.designPath
|
||||
? path.resolve(process.cwd(), ctx.designPath)
|
||||
: (LIVE_ROOTS?.designPath && fs.existsSync(LIVE_ROOTS.designPath) ? LIVE_ROOTS.designPath : null);
|
||||
const hasProduct = ctx.hasProduct
|
||||
|| !!(LIVE_ROOTS?.productPath && fs.existsSync(LIVE_ROOTS.productPath));
|
||||
return {
|
||||
...ctx,
|
||||
hasProduct,
|
||||
hasDesign: !!designPath,
|
||||
resolvedDesignPath: designPath,
|
||||
contextDir: ctx.contextDir || LIVE_ROOTS?.contextRoot || process.cwd(),
|
||||
designContextDir: ctx.designContextDir
|
||||
|| (designPath ? path.dirname(designPath) : null),
|
||||
};
|
||||
}
|
||||
const DEFAULT_POLL_TIMEOUT = 600_000; // 10 min — agent re-polls on timeout anyway
|
||||
const SSE_HEARTBEAT_INTERVAL = 30_000; // keepalive ping every 30s
|
||||
|
||||
// The browser events allowed to mint a NEW session journal. `generate` starts
|
||||
// a variant session at Go; `steer` mints its own request id. Every other
|
||||
// id-carrying event must land on an existing session (see the unknown_session
|
||||
// gate in the /events handler).
|
||||
const SESSION_CREATING_EVENT_TYPES = new Set(['generate', 'steer']);
|
||||
// The browser checkpoints for several unrelated reasons (see checkpointPayload
|
||||
// in live-browser.js). Only these two report that variant availability changed,
|
||||
// and only they may drive variant_progress / the *_reviewable phases.
|
||||
const VARIANT_PROGRESS_CHECKPOINT_REASONS = new Set(['variants_progress', 'variants_ready']);
|
||||
const VARIANT_PROGRESS_CHECKPOINT_REASONS = new Set(VARIANT_PROGRESS_CHECKPOINT_REASON_LIST);
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Port detection
|
||||
@@ -150,7 +182,16 @@ function chatAgentLikelyActive() {
|
||||
const MAX_ANNOTATION_BYTES = 10 * 1024 * 1024;
|
||||
|
||||
function enqueueEvent(event) {
|
||||
if (!event || (event.id && state.pendingEvents.some((entry) => entry.event?.id === event.id && entry.event?.type === event.type))) return;
|
||||
if (!event) return;
|
||||
// Dedupe by (session, type), except mount failures, which are per-variant:
|
||||
// variant 2 failing must not be swallowed because variant 1's failure is
|
||||
// still queued.
|
||||
const duplicate = event.id && state.pendingEvents.some((entry) => (
|
||||
entry.event?.id === event.id
|
||||
&& entry.event?.type === event.type
|
||||
&& (event.type !== 'variant_mount_failed' || entry.event?.variant === event.variant)
|
||||
));
|
||||
if (duplicate) return;
|
||||
state.pendingEvents.push({ event, leaseUntil: 0, seq: state.nextEventSeq++ });
|
||||
flushPendingPolls();
|
||||
}
|
||||
@@ -445,6 +486,11 @@ function summarizeActiveSessionForClient(snapshot = {}) {
|
||||
generationCompletedAt: snapshot.generationCompletedAt ?? null,
|
||||
generationCanceled: snapshot.generationCanceled === true,
|
||||
cancelReason: snapshot.cancelReason ?? null,
|
||||
// Render truth, so a browser with no localStorage can rehydrate to the
|
||||
// same comparison the server already knows about.
|
||||
mountedVariants: Array.isArray(snapshot.mountedVariants) ? snapshot.mountedVariants : [],
|
||||
mountFailures: Array.isArray(snapshot.mountFailures) ? snapshot.mountFailures : [],
|
||||
renderState: snapshot.renderState ?? null,
|
||||
};
|
||||
}
|
||||
|
||||
@@ -618,7 +664,7 @@ function hasProjectContext() {
|
||||
// PRODUCT.md carries brand voice / anti-references — that's what determines
|
||||
// whether variants are brand-aware. DESIGN.md (visual tokens) is a separate
|
||||
// concern, surfaced by the design panel's own empty state.
|
||||
return !!PROJECT_CONTEXT.hasProduct;
|
||||
return !!resolveProjectContext().hasProduct;
|
||||
}
|
||||
|
||||
function statOrNull(filePath) {
|
||||
@@ -690,6 +736,7 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
|
||||
port: state.port,
|
||||
vocabulary: LIVE_COMMANDS,
|
||||
commandPrefix: IMPECCABLE_COMMAND_PREFIX,
|
||||
appRoot: process.cwd(),
|
||||
parts,
|
||||
});
|
||||
res.writeHead(200, {
|
||||
@@ -827,8 +874,9 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
|
||||
const token = url.searchParams.get('token');
|
||||
if (token !== state.token) { res.writeHead(401); res.end('Unauthorized'); return; }
|
||||
|
||||
const mdPath = DESIGN_MD_PATH;
|
||||
const jsonPath = resolveDesignSidecarPath(process.cwd(), PROJECT_CONTEXT.designContextDir || CONTEXT_DIR) || getDesignSidecarPath(process.cwd());
|
||||
const projectContext = resolveProjectContext();
|
||||
const mdPath = projectContext.resolvedDesignPath;
|
||||
const jsonPath = resolveDesignSidecarPath(process.cwd(), projectContext.designContextDir || projectContext.contextDir) || getDesignSidecarPath(process.cwd());
|
||||
const mdStat = statOrNull(mdPath);
|
||||
const jsonStat = statOrNull(jsonPath);
|
||||
|
||||
@@ -979,6 +1027,20 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
|
||||
res.end(JSON.stringify({ ok: true }));
|
||||
return;
|
||||
}
|
||||
// Only the events that START a session may create its journal.
|
||||
// Everything else (checkpoints, mount acks, accept/discard) must
|
||||
// reference a session THIS store already knows: appendEvent creates a
|
||||
// journal for any id it is handed, so without this gate a browser
|
||||
// resuming another project's session from per-origin storage (two
|
||||
// apps sharing a localhost port) materializes a ghost session here
|
||||
// that keeps reattaching after every discard.
|
||||
if (msg.id && state.sessionStore
|
||||
&& !SESSION_CREATING_EVENT_TYPES.has(msg.type)
|
||||
&& !state.sessionStore.has(msg.id)) {
|
||||
res.writeHead(404, { 'Content-Type': 'application/json' });
|
||||
res.end(JSON.stringify({ error: 'unknown_session', id: msg.id }));
|
||||
return;
|
||||
}
|
||||
const missedCompletion = detectMissedGenerationCompletion(msg);
|
||||
if (state.sessionStore && msg.id) {
|
||||
try {
|
||||
@@ -997,7 +1059,25 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
|
||||
if (msg.type === 'exit') {
|
||||
cleanupSvelteComponentSessionsBeforeExit();
|
||||
}
|
||||
if (msg.type !== 'checkpoint') {
|
||||
// An ORPHANED discard is the browser reporting that the session's
|
||||
// wrapper no longer exists in source (edited or regenerated away).
|
||||
// There is no cleanup for an agent to perform, and asking one to run
|
||||
// the normal discard flow would just fail against the missing
|
||||
// scaffolding, so the server terminalizes the session itself and the
|
||||
// event stays out of the poll queue.
|
||||
const orphanedDiscard = msg.type === 'discard' && msg.orphaned === true;
|
||||
if (orphanedDiscard && state.sessionStore && msg.id) {
|
||||
try {
|
||||
state.sessionStore.appendEvent({ type: 'discarded', id: msg.id, orphaned: true });
|
||||
} catch { /* the discard_requested phase already left the resumable set */ }
|
||||
}
|
||||
// `variant_mounted` is the happy path: it is journaled above so the
|
||||
// snapshot carries render truth, but there is nothing for the agent to
|
||||
// do about it, so it stays out of the poll queue and off the SSE bus.
|
||||
// `variant_mount_failed` is the opposite: the agent published something
|
||||
// the browser could not render, and only the agent can fix it, so it
|
||||
// goes to the queue as a first-class event.
|
||||
if (msg.type !== 'checkpoint' && msg.type !== 'variant_mounted' && !orphanedDiscard) {
|
||||
enqueueEvent(msg);
|
||||
}
|
||||
res.writeHead(200, { 'Content-Type': 'application/json' });
|
||||
@@ -1099,7 +1179,8 @@ function sessionFileMetadataFromPollReply(file) {
|
||||
const base = { file: normalized };
|
||||
const metadataFile = normalized;
|
||||
if (!metadataFile.endsWith('/manifest.json') && metadataFile !== 'manifest.json') return base;
|
||||
if (!metadataFile.includes('node_modules/.impeccable-live/')
|
||||
if (!metadataFile.includes('.impeccable/live/previews/')
|
||||
&& !metadataFile.includes('node_modules/.impeccable-live/')
|
||||
&& !metadataFile.includes('src/lib/impeccable/')
|
||||
&& !metadataFile.includes('/.impeccable-live/')) return base;
|
||||
|
||||
@@ -1139,7 +1220,14 @@ function inferSourceEventType(msg = {}, pendingEvents = state.pendingEvents) {
|
||||
// `agent_done` can be the automatic acknowledgement for a carbonize Accept.
|
||||
// New pollers send sourceEventType explicitly; default to generate only for
|
||||
// older callers so a late worker cannot acknowledge a queued Accept.
|
||||
if (msg.type === 'agent_done' || msg.type === 'done') return 'generate';
|
||||
if (msg.type === 'agent_done' || msg.type === 'done') {
|
||||
// A `done` reply to a mount failure is the republish that unblocks the
|
||||
// browser. Without this the ack would look for a `generate` that was
|
||||
// already retired, the mount-failure event would stay queued, and the next
|
||||
// poll would hand the same failure back to the agent forever.
|
||||
if (!pendingTypes.has('generate') && pendingTypes.has('variant_mount_failed')) return 'variant_mount_failed';
|
||||
return 'generate';
|
||||
}
|
||||
// `error` is reference/live.md's documented failure reply, and parseReplyArgs
|
||||
// never sets sourceEventType on it (the poller is a fresh process that cannot
|
||||
// know what it leased). Returning undefined here makes acknowledgePendingEvent
|
||||
@@ -1264,6 +1352,30 @@ function handlePollPost(req, res) {
|
||||
return;
|
||||
}
|
||||
const replyFileMeta = sessionFileMetadataFromPollReply(msg.file);
|
||||
// A publish (done reply carrying a component manifest) snapshots the
|
||||
// variant files into a fresh revision dir before the browser is told:
|
||||
// the import path changes every publish, so no transform cache can pin a
|
||||
// stale compile of a republished module (node_modules is unwatched).
|
||||
// Broken variants are bounced HERE, before the browser imports anything:
|
||||
// a compile error that reaches the page is a red overlay in the user's
|
||||
// face; bounced at publish it is a private fix with file and line.
|
||||
if (replyFileMeta.previewMode === 'svelte-component'
|
||||
&& msg.id
|
||||
&& (msg.type === 'done' || !msg.type)) {
|
||||
let compileCheck = { ok: true, failures: [] };
|
||||
try { compileCheck = compileCheckVariants(msg.id, process.cwd()); } catch { /* best-effort */ }
|
||||
if (!compileCheck.ok) {
|
||||
res.writeHead(422, { 'Content-Type': 'application/json' });
|
||||
res.end(JSON.stringify({
|
||||
error: 'variant_compile_failed',
|
||||
id: msg.id,
|
||||
failures: compileCheck.failures,
|
||||
_instructions: 'The publish was NOT delivered: the listed variant file(s) do not compile, so the browser never saw them. Fix each failure at the given file and line (the most common cause is a second top-level <style> element; Svelte allows exactly one, so merge all rules into the existing block), then send the same --reply done again.',
|
||||
}));
|
||||
return;
|
||||
}
|
||||
try { bumpSvelteComponentPreviewRevision(msg.id, process.cwd()); } catch { /* best-effort */ }
|
||||
}
|
||||
if (state.sessionStore && msg.id && !skipJournalReply) {
|
||||
try {
|
||||
const eventType = msg.type === 'steer_done'
|
||||
@@ -1335,6 +1447,51 @@ function cleanupSvelteComponentSessionsBeforeExit() {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* A previous run that died without its shutdown hook leaves preview component
|
||||
* dirs behind. Drop the ones whose session the store no longer considers
|
||||
* active; anything still active is mid-generation and must survive a restart.
|
||||
*/
|
||||
function sweepOrphanSvelteComponentSessionsOnStartup() {
|
||||
try {
|
||||
const activeIds = (state.sessionStore?.listActiveSessions() || [])
|
||||
.map((snapshot) => snapshot?.id)
|
||||
.filter(Boolean);
|
||||
const result = sweepInactiveSvelteComponentSessions(activeIds, process.cwd());
|
||||
if (result.removed.length > 0 || result.removedRoot) {
|
||||
console.log('[impeccable] swept orphaned Svelte component sessions:', JSON.stringify(result));
|
||||
}
|
||||
} catch (err) {
|
||||
console.warn('[impeccable] Svelte component session sweep failed:', err.message);
|
||||
}
|
||||
}
|
||||
|
||||
// Accept receipts are a short-lived idempotency record for a single accept.
|
||||
// Nothing reads one after the session that wrote it is gone, so they only need
|
||||
// to outlive a crash-and-retry window.
|
||||
const ACCEPT_RECEIPT_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000;
|
||||
|
||||
function sweepStaleAcceptReceiptsOnStartup() {
|
||||
try {
|
||||
const dir = path.join(getLiveDir(process.cwd()), 'accept-receipts');
|
||||
if (!fs.existsSync(dir)) return;
|
||||
const cutoff = Date.now() - ACCEPT_RECEIPT_MAX_AGE_MS;
|
||||
let removed = 0;
|
||||
for (const name of fs.readdirSync(dir)) {
|
||||
if (!name.endsWith('.json') && !name.endsWith('.tmp')) continue;
|
||||
const file = path.join(dir, name);
|
||||
try {
|
||||
if (fs.statSync(file).mtimeMs >= cutoff) continue;
|
||||
fs.rmSync(file, { force: true });
|
||||
removed++;
|
||||
} catch { /* non-fatal */ }
|
||||
}
|
||||
if (removed > 0) console.log(`[impeccable] removed ${removed} accept receipt(s) older than 14 days`);
|
||||
} catch (err) {
|
||||
console.warn('[impeccable] accept receipt retention sweep failed:', err.message);
|
||||
}
|
||||
}
|
||||
|
||||
function applyLegacyDeferredAcceptsOnStartup() {
|
||||
try {
|
||||
const result = applyDeferredSvelteComponentAccepts(process.cwd());
|
||||
@@ -1474,6 +1631,8 @@ manualApply.rollbackTransaction({
|
||||
reason: 'manual_edit_server_start_recovered_abandoned_transaction',
|
||||
});
|
||||
applyLegacyDeferredAcceptsOnStartup();
|
||||
sweepOrphanSvelteComponentSessionsOnStartup();
|
||||
sweepStaleAcceptReceiptsOnStartup();
|
||||
restorePendingEventsFromStore();
|
||||
manualApply.pruneStaleEvidence();
|
||||
const portArg = args.find(a => a.startsWith('--port='));
|
||||
|
||||
@@ -5,7 +5,8 @@
|
||||
|
||||
import { createLiveSessionStore } from './live/session-store.mjs';
|
||||
import { readLiveServerInfo } from './lib/impeccable-paths.mjs';
|
||||
import { manualApplyResumeHint } from './live-resume.mjs';
|
||||
import { manualApplyResumeHint, mountFailureAction, renderSummary } from './live-resume.mjs';
|
||||
import { enterLiveRoot } from './live/roots.mjs';
|
||||
|
||||
function readServerInfo() {
|
||||
return readLiveServerInfo(process.cwd())?.info || null;
|
||||
@@ -28,6 +29,8 @@ export async function statusCli() {
|
||||
const store = createLiveSessionStore({ cwd: process.cwd() });
|
||||
const activeSessions = store.listActiveSessions();
|
||||
const manualApply = findPendingManualApply(server, activeSessions);
|
||||
const sessions = server?.activeSessions || activeSessions;
|
||||
const renderFailure = sessions.find((session) => session?.renderState === 'failed') || null;
|
||||
const payload = {
|
||||
liveServer: server ? {
|
||||
status: server.status,
|
||||
@@ -36,14 +39,16 @@ export async function statusCli() {
|
||||
agentPolling: server.agentPolling,
|
||||
pendingEvents: server.pendingEvents,
|
||||
} : null,
|
||||
activeSessions: server?.activeSessions || activeSessions,
|
||||
recoveryHint: recoveryHint({ server, manualApply }),
|
||||
activeSessions: sessions,
|
||||
render: sessions.map((session) => ({ id: session?.id ?? null, ...renderSummary(session) })),
|
||||
recoveryHint: recoveryHint({ server, manualApply, renderFailure }),
|
||||
};
|
||||
console.log(JSON.stringify(payload, null, 2));
|
||||
}
|
||||
|
||||
function recoveryHint({ server, manualApply }) {
|
||||
function recoveryHint({ server, manualApply, renderFailure }) {
|
||||
if (manualApply) return manualApplyResumeHint(manualApply);
|
||||
if (renderFailure) return mountFailureAction(renderFailure);
|
||||
if (server) {
|
||||
return 'Run live-poll.mjs to continue pending work, or live-complete.mjs --id <session> after manual cleanup.';
|
||||
}
|
||||
@@ -61,5 +66,6 @@ function findPendingManualApply(server, activeSessions) {
|
||||
|
||||
const _running = process.argv[1];
|
||||
if (_running?.endsWith('live-status.mjs') || _running?.endsWith('live-status.mjs/')) {
|
||||
enterLiveRoot();
|
||||
statusCli();
|
||||
}
|
||||
|
||||
@@ -17,11 +17,13 @@ import { isGeneratedFile } from './lib/is-generated.mjs';
|
||||
import { resolveLiveTemplateExtensions } from './lib/template-extensions.mjs';
|
||||
import { readBuffer as readManualEditsBuffer } from './live/manual-edits-buffer.mjs';
|
||||
import { findSourceFile } from './live/source-search.mjs';
|
||||
import { resolveSourceTraits } from './live/frameworks/index.mjs';
|
||||
import {
|
||||
buildSvelteComponentCssAuthoring,
|
||||
scaffoldSvelteComponentSession,
|
||||
shouldUseSvelteComponentInjection,
|
||||
} from './live/svelte-component.mjs';
|
||||
import { enterLiveRoot } from './live/roots.mjs';
|
||||
|
||||
export async function wrapCli() {
|
||||
const args = process.argv.slice(2);
|
||||
@@ -293,8 +295,10 @@ The agent should insert variant HTML at insertLine.`);
|
||||
.join('\n');
|
||||
const originalIndented = reindentOriginal(' ');
|
||||
const relTargetFile = path.relative(process.cwd(), targetFile).split(path.sep).join('/');
|
||||
const useSvelteComponent = shouldUseSvelteComponentInjection(targetFile);
|
||||
const useFrameworkComponent = useSvelteComponent;
|
||||
// The registry says which files get component preview; the svelte-component
|
||||
// module keeps the env escape hatch that turns it off.
|
||||
const useSvelteComponent = resolveSourceTraits(targetFile).preview === 'component'
|
||||
&& shouldUseSvelteComponentInjection(targetFile);
|
||||
|
||||
// Wrapper attributes differ by syntax. HTML allows plain string attrs;
|
||||
// JSX requires object-literal style and parses string attrs as HTML (which
|
||||
@@ -343,12 +347,18 @@ The agent should insert variant HTML at insertLine.`);
|
||||
let svelteSession = null;
|
||||
let deferredWrapper = null;
|
||||
|
||||
let sveltePreviewFallback = null;
|
||||
if (useSvelteComponent) {
|
||||
// Svelte/SvelteKit resets component-local state on markup HMR updates.
|
||||
// Keep generation source-neutral: agents write real variant components
|
||||
// under the generated componentDir, the browser mounts them into the live
|
||||
// DOM, and live-accept.mjs inlines the accepted variant back into the route.
|
||||
svelteSession = scaffoldSvelteComponentSession({
|
||||
//
|
||||
// The scaffold is AST-based and refuses markup a detached preview cannot
|
||||
// support (component tags, bind:/use:, await blocks, bound nested each).
|
||||
// Refusal falls back to the plain source-preview wrapper below: an
|
||||
// HMR-resetting but CORRECT preview beats a detached wrong one.
|
||||
const scaffolded = scaffoldSvelteComponentSession({
|
||||
id,
|
||||
count,
|
||||
sourceFile: relTargetFile,
|
||||
@@ -357,10 +367,18 @@ The agent should insert variant HTML at insertLine.`);
|
||||
originalLines,
|
||||
cwd: process.cwd(),
|
||||
});
|
||||
outputFile = path.resolve(process.cwd(), svelteSession.manifestFile);
|
||||
outputStartLine = 1;
|
||||
outputEndLine = 1;
|
||||
insertLine = 1;
|
||||
if (scaffolded && scaffolded.fallback === 'source-preview') {
|
||||
sveltePreviewFallback = scaffolded.reason || 'unsupported markup';
|
||||
} else {
|
||||
svelteSession = scaffolded;
|
||||
outputFile = path.resolve(process.cwd(), svelteSession.manifestFile);
|
||||
outputStartLine = 1;
|
||||
outputEndLine = 1;
|
||||
insertLine = 1;
|
||||
}
|
||||
}
|
||||
if (svelteSession) {
|
||||
// component preview: outputs already set above
|
||||
} else if (deferSourceWrite) {
|
||||
// Deferred source write: compute the scaffold text but leave source
|
||||
// untouched. The agent replaces the picked element's source range with
|
||||
@@ -396,15 +414,19 @@ The agent should insert variant HTML at insertLine.`);
|
||||
|
||||
const outputRelFile = path.relative(process.cwd(), outputFile).split(path.sep).join('/');
|
||||
|
||||
const svelteComponentAuthoring = useSvelteComponent ? buildSvelteComponentCssAuthoring(count) : null;
|
||||
const componentPreviewActive = !!svelteSession;
|
||||
const svelteComponentAuthoring = componentPreviewActive ? buildSvelteComponentCssAuthoring(count) : null;
|
||||
const componentSession = svelteSession;
|
||||
const componentPreviewMode = useSvelteComponent ? 'svelte-component' : undefined;
|
||||
const componentPreviewMode = componentPreviewActive ? 'svelte-component' : undefined;
|
||||
const previewMode = componentPreviewMode;
|
||||
|
||||
console.log(JSON.stringify({
|
||||
file: outputRelFile,
|
||||
sourceFile: useFrameworkComponent ? relTargetFile : undefined,
|
||||
sourceFile: componentPreviewActive ? relTargetFile : undefined,
|
||||
previewMode,
|
||||
previewFallback: sveltePreviewFallback
|
||||
? { from: 'svelte-component', reason: sveltePreviewFallback }
|
||||
: undefined,
|
||||
// Deferred source write: the wrapper is NOT yet in source. The agent
|
||||
// replaces [replaceStartLine, replaceEndLine] with `wrapperBlock` (variants
|
||||
// spliced at the "insert below this line" marker) in one atomic edit.
|
||||
@@ -414,8 +436,9 @@ The agent should insert variant HTML at insertLine.`);
|
||||
replaceEndLine: deferredWrapper ? deferredWrapper.replaceEndLine : undefined,
|
||||
componentDir: componentSession?.componentDir,
|
||||
propContract: componentSession?.propContract,
|
||||
sourceStartLine: useFrameworkComponent ? startLine + 1 : undefined,
|
||||
sourceEndLine: useFrameworkComponent ? endLine + 1 : undefined,
|
||||
componentStubMarkup: componentSession?.stubMarkup,
|
||||
sourceStartLine: componentPreviewActive ? startLine + 1 : undefined,
|
||||
sourceEndLine: componentPreviewActive ? endLine + 1 : undefined,
|
||||
startLine: outputStartLine, // 1-indexed for the agent
|
||||
// wrapperLines is an array but one element (the original-content slot)
|
||||
// is a `\n`-joined multi-line string, so the actual file-row count is
|
||||
@@ -426,8 +449,8 @@ The agent should insert variant HTML at insertLine.`);
|
||||
insertLine, // 1-indexed: where variants go
|
||||
commentSyntax: commentSyntax,
|
||||
styleMode: componentPreviewMode || styleMode.mode,
|
||||
styleTag: useFrameworkComponent ? null : styleMode.styleTag,
|
||||
cssSelectorPrefixExamples: useFrameworkComponent ? [] : buildCssSelectorPrefixExamples(styleMode.mode, count),
|
||||
styleTag: componentPreviewActive ? null : styleMode.styleTag,
|
||||
cssSelectorPrefixExamples: componentPreviewActive ? [] : buildCssSelectorPrefixExamples(styleMode.mode, count),
|
||||
cssAuthoring: svelteComponentAuthoring || buildCssAuthoring(styleMode, count),
|
||||
originalLineCount: originalLines.length,
|
||||
}));
|
||||
@@ -630,27 +653,22 @@ function attrEscapeDouble(str) {
|
||||
.replace(/>/g, '>');
|
||||
}
|
||||
|
||||
/**
|
||||
* Comment syntax, style mode, and preview strategy all come from the framework
|
||||
* registry, keyed on the target file's extension: `.jsx`/`.tsx` author JSX
|
||||
* comments, `.astro` needs global-prefixed preview CSS because Astro scopes
|
||||
* component styles away from the generated wrappers, `.svelte` gets component
|
||||
* preview. See live/frameworks/index.mjs for why extension and not project.
|
||||
*/
|
||||
function detectCommentSyntax(filePath) {
|
||||
const ext = path.extname(filePath).toLowerCase();
|
||||
if (ext === '.jsx' || ext === '.tsx') {
|
||||
return { open: '{/*', close: '*/}' };
|
||||
}
|
||||
// HTML, Vue, Svelte, Astro all use HTML comments
|
||||
return { open: '<!--', close: '-->' };
|
||||
return resolveSourceTraits(filePath).commentSyntax === 'jsx'
|
||||
? { open: '{/*', close: '*/}' }
|
||||
: { open: '<!--', close: '-->' };
|
||||
}
|
||||
|
||||
function detectStyleMode(filePath) {
|
||||
const ext = path.extname(filePath).toLowerCase();
|
||||
if (ext === '.astro') {
|
||||
return {
|
||||
mode: 'astro-global-prefixed',
|
||||
styleTag: '<style is:inline data-impeccable-css="SESSION_ID">',
|
||||
};
|
||||
}
|
||||
return {
|
||||
mode: 'scoped',
|
||||
styleTag: '<style data-impeccable-css="SESSION_ID">',
|
||||
};
|
||||
const traits = resolveSourceTraits(filePath);
|
||||
return { mode: traits.styleMode, styleTag: traits.styleTag };
|
||||
}
|
||||
|
||||
function buildCssSelectorPrefixExamples(styleMode, count) {
|
||||
@@ -890,6 +908,7 @@ function findClosingLine(lines, start) {
|
||||
// Auto-execute when run directly (node live-wrap.mjs ...)
|
||||
const _running = process.argv[1];
|
||||
if (_running?.endsWith('live-wrap.mjs') || _running?.endsWith('live-wrap.mjs/')) {
|
||||
enterLiveRoot();
|
||||
wrapCli();
|
||||
}
|
||||
|
||||
|
||||
@@ -21,10 +21,13 @@ import { execSync } from 'node:child_process';
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { loadContext, resolveTargetSelection } from './context.mjs';
|
||||
import { resolveTargetSelection } from './context.mjs';
|
||||
import { resolveFiles } from './live-inject.mjs';
|
||||
import { readLiveServerInfo } from './lib/impeccable-paths.mjs';
|
||||
import { resolveSurfaceBrief } from './lib/surface-briefs.mjs';
|
||||
import { resolveLiveTarget } from './live-target.mjs';
|
||||
import { bootInstructions } from './live/instructions.mjs';
|
||||
import { resolveRoots, writeRootsManifest } from './live/roots.mjs';
|
||||
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
||||
|
||||
@@ -60,6 +63,8 @@ The agent should then:
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
// Legacy workspace-monorepo selection first: it carries richer candidate
|
||||
// metadata (context inheritance status) than the roots scan.
|
||||
const targetSelection = resolveTargetSelection(liveTarget.originalCwd, liveTarget.targetOptions);
|
||||
if (targetSelection) {
|
||||
console.log(JSON.stringify({
|
||||
@@ -71,11 +76,31 @@ The agent should then:
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
const ctx = loadContext(liveTarget.originalCwd, liveTarget.targetOptions);
|
||||
const activeCwd = ctx.projectRoot;
|
||||
const rootsResult = resolveRoots({
|
||||
cwd: liveTarget.originalCwd,
|
||||
targetPath: liveTarget.absoluteTargetPath,
|
||||
});
|
||||
if (rootsResult.selection) {
|
||||
console.log(JSON.stringify({
|
||||
ok: false,
|
||||
error: 'target_selection_required',
|
||||
targetCandidates: rootsResult.selection.candidates,
|
||||
hint: 'Several apps with a dev-server config exist. Ask the user which one to use, then rerun with --target <path into that app>.',
|
||||
}, null, 2));
|
||||
process.exit(0);
|
||||
}
|
||||
const roots = rootsResult.manifest;
|
||||
const activeCwd = roots.appRoot;
|
||||
const outputTargetPath = liveTarget.targetPath || null;
|
||||
|
||||
const missingContext = missingLiveContext(ctx);
|
||||
// Gate on readable CONTENT, not path existence, so an empty or unreadable
|
||||
// PRODUCT.md routes to init instead of passing the gate and then reporting
|
||||
// hasProduct: false in the same payload.
|
||||
const product = safeRead(roots.productPath);
|
||||
const design = safeRead(roots.designPath);
|
||||
const missingContext = [];
|
||||
if (!product) missingContext.push('PRODUCT.md');
|
||||
if (!design) missingContext.push('DESIGN.md');
|
||||
if (missingContext.length > 0) {
|
||||
console.log(JSON.stringify({
|
||||
ok: false,
|
||||
@@ -83,14 +108,18 @@ The agent should then:
|
||||
missing: missingContext,
|
||||
nextCommand: missingContext.includes('PRODUCT.md') ? 'init' : 'document',
|
||||
targetPath: outputTargetPath,
|
||||
projectRoot: ctx.projectRoot,
|
||||
repoRoot: ctx.repoRoot,
|
||||
productPath: ctx.productPath,
|
||||
designPath: ctx.designPath,
|
||||
projectRoot: roots.appRoot,
|
||||
repoRoot: roots.repoRoot,
|
||||
productPath: relOrNull(liveTarget.originalCwd, roots.productPath),
|
||||
designPath: relOrNull(liveTarget.originalCwd, roots.designPath),
|
||||
}, null, 2));
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
// Persist the decision before anything else spawns, so every helper the
|
||||
// agent runs later (from any cwd inside the repo) lands on the same roots.
|
||||
writeRootsManifest(roots);
|
||||
|
||||
// 1. Check config (fail fast if missing — no point starting anything else)
|
||||
const checkOut = runScript('live-inject.mjs', ['--check'], { cwd: activeCwd });
|
||||
const checkResult = safeParse(checkOut);
|
||||
@@ -98,8 +127,8 @@ The agent should then:
|
||||
console.log(JSON.stringify({
|
||||
...(checkResult || { ok: false, error: 'check_failed', raw: checkOut }),
|
||||
targetPath: outputTargetPath,
|
||||
projectRoot: ctx.projectRoot,
|
||||
repoRoot: ctx.repoRoot,
|
||||
projectRoot: roots.appRoot,
|
||||
repoRoot: roots.repoRoot,
|
||||
}));
|
||||
process.exit(0);
|
||||
}
|
||||
@@ -134,7 +163,28 @@ The agent should then:
|
||||
const resolvedFiles = resolveFiles(activeCwd, checkResult.config);
|
||||
const drift = scanForDrift(activeCwd, resolvedFiles, checkResult.config);
|
||||
|
||||
// 5. Emit everything the agent needs
|
||||
// 5. Emit everything the agent needs. The surface brief rides along so the
|
||||
// agent does not spend three more tool calls (and a --help miss) on
|
||||
// surface-brief.mjs before the first poll.
|
||||
let surfaceBrief = null;
|
||||
let surfaceBriefPath = null;
|
||||
try {
|
||||
// Briefs live under .impeccable/surfaces, which in a nested-app repo sits
|
||||
// at the CONTEXT or repo root, not the app root; context.mjs already finds
|
||||
// them there, and live must not report "no brief" for the same project.
|
||||
const briefRoots = [roots.appRoot, roots.contextRoot, roots.repoRoot]
|
||||
.filter(Boolean)
|
||||
.filter((dir, i, arr) => arr.findIndex((other) => path.resolve(other) === path.resolve(dir)) === i);
|
||||
for (const briefRoot of briefRoots) {
|
||||
const resolvedBrief = resolveSurfaceBrief(briefRoot, liveTarget.absoluteTargetPath || null);
|
||||
if (!resolvedBrief?.brief) continue;
|
||||
surfaceBrief = resolvedBrief.brief.text ?? safeRead(resolvedBrief.brief.path);
|
||||
surfaceBriefPath = resolvedBrief.brief.path
|
||||
? path.relative(liveTarget.originalCwd, resolvedBrief.brief.path)
|
||||
: null;
|
||||
break;
|
||||
}
|
||||
} catch { /* briefs are optional context */ }
|
||||
console.log(JSON.stringify({
|
||||
ok: true,
|
||||
serverPort: serverInfo.port,
|
||||
@@ -143,22 +193,29 @@ The agent should then:
|
||||
liveConfigPath: checkResult.path,
|
||||
configDrift: drift,
|
||||
targetPath: outputTargetPath,
|
||||
projectRoot: ctx.projectRoot,
|
||||
repoRoot: ctx.repoRoot,
|
||||
hasProduct: ctx.hasProduct,
|
||||
product: ctx.product,
|
||||
productPath: ctx.productPath,
|
||||
hasDesign: ctx.hasDesign,
|
||||
design: ctx.design,
|
||||
designPath: ctx.designPath,
|
||||
projectRoot: roots.appRoot,
|
||||
repoRoot: roots.repoRoot,
|
||||
roots,
|
||||
hasProduct: !!product,
|
||||
product,
|
||||
productPath: relOrNull(liveTarget.originalCwd, roots.productPath),
|
||||
hasDesign: !!design,
|
||||
design,
|
||||
designPath: relOrNull(liveTarget.originalCwd, roots.designPath),
|
||||
hasSurfaceBrief: !!surfaceBrief,
|
||||
surfaceBrief,
|
||||
surfaceBriefPath,
|
||||
_instructions: bootInstructions({ scriptsPath: __dirname }),
|
||||
}, null, 2));
|
||||
}
|
||||
|
||||
function missingLiveContext(ctx) {
|
||||
const missing = [];
|
||||
if (!ctx.hasProduct) missing.push('PRODUCT.md');
|
||||
if (!ctx.hasDesign) missing.push('DESIGN.md');
|
||||
return missing;
|
||||
function safeRead(p) {
|
||||
if (!p) return null;
|
||||
try { return fs.readFileSync(p, 'utf-8'); } catch { return null; }
|
||||
}
|
||||
|
||||
function relOrNull(base, p) {
|
||||
return p ? path.relative(base, p) : null;
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
@@ -0,0 +1,617 @@
|
||||
/**
|
||||
* Accept-time CSS reconciliation for live mode.
|
||||
*
|
||||
* The old accept path appended the chosen variant's whole <style> body in
|
||||
* front of the component's existing rules, which preserved every superseded
|
||||
* declaration (the "old divider borders survive the accept" bug) and left
|
||||
* dead parameter branches in source. This module makes acceptance a merge:
|
||||
*
|
||||
* reconcileCss replace rules whose selectors match, append new ones
|
||||
* bakeParamValues collapse --p-* vars and [data-p-*] branches to the
|
||||
* user's chosen values, driven by the declared param
|
||||
* kinds from params.json (not regex sniffing)
|
||||
* pruneUnusedSelectors use the framework compiler's own unused-selector
|
||||
* warnings to delete rules the accepted markup no longer
|
||||
* references
|
||||
*
|
||||
* The parser is hand-rolled on purpose: skill scripts run standalone inside
|
||||
* user projects and cannot rely on this repo's node_modules. It is a small
|
||||
* recursive block parser (comment- and string-aware), not a spec-complete
|
||||
* CSS parser; everything it emits round-trips byte-for-byte through raw
|
||||
* slices except the rules deliberately changed.
|
||||
*/
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Parsing
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Parse a stylesheet into a flat tree.
|
||||
* Node shapes:
|
||||
* { type: 'rule', prelude, body, start, end, preludeStart }
|
||||
* { type: 'at', name, prelude, children|body, start, end } (children when
|
||||
* the block contains rules: media/supports/layer/container/scope)
|
||||
* { type: 'comment', text, start, end }
|
||||
*/
|
||||
export function parseStylesheet(css, offset = 0) {
|
||||
const text = String(css || '');
|
||||
const nodes = [];
|
||||
let i = 0;
|
||||
|
||||
const skipWs = () => { while (i < text.length && /\s/.test(text[i])) i++; };
|
||||
|
||||
while (i < text.length) {
|
||||
skipWs();
|
||||
if (i >= text.length) break;
|
||||
|
||||
if (text[i] === '/' && text[i + 1] === '*') {
|
||||
const start = i;
|
||||
const close = text.indexOf('*/', i + 2);
|
||||
i = close === -1 ? text.length : close + 2;
|
||||
nodes.push({ type: 'comment', text: text.slice(start, i), start: offset + start, end: offset + i });
|
||||
continue;
|
||||
}
|
||||
|
||||
const preludeStart = i;
|
||||
const boundary = scanToBlockOrStatementEnd(text, i);
|
||||
if (boundary.kind === 'none') break; // trailing garbage / declarations at top level
|
||||
if (boundary.kind === 'statement') {
|
||||
// Block-less at-statement (@import, @charset, @layer names;). Emitted
|
||||
// as its own node so the FOLLOWING rule still indexes for
|
||||
// reconciliation instead of being folded into this prelude.
|
||||
const raw = text.slice(preludeStart, boundary.index + 1).trim();
|
||||
if (raw) {
|
||||
nodes.push({
|
||||
type: 'at',
|
||||
name: (raw.match(/^@([A-Za-z-]+)/) || [])[1] || '',
|
||||
prelude: raw.replace(/;$/, ''),
|
||||
statement: true,
|
||||
start: offset + preludeStart,
|
||||
end: offset + boundary.index + 1,
|
||||
});
|
||||
}
|
||||
i = boundary.index + 1;
|
||||
continue;
|
||||
}
|
||||
const braceIdx = boundary.index;
|
||||
const prelude = text.slice(preludeStart, braceIdx).trim();
|
||||
const bodyStart = braceIdx + 1;
|
||||
const bodyEnd = scanBlockEnd(text, bodyStart);
|
||||
const body = text.slice(bodyStart, bodyEnd);
|
||||
const nodeEnd = Math.min(text.length, bodyEnd + 1);
|
||||
|
||||
if (prelude.startsWith('@')) {
|
||||
const name = (prelude.match(/^@([A-Za-z-]+)/) || [])[1] || '';
|
||||
if (['media', 'supports', 'layer', 'container', 'scope'].includes(name)) {
|
||||
nodes.push({
|
||||
type: 'at',
|
||||
name,
|
||||
prelude,
|
||||
children: parseStylesheet(body, offset + bodyStart),
|
||||
start: offset + preludeStart,
|
||||
end: offset + nodeEnd,
|
||||
});
|
||||
} else {
|
||||
nodes.push({
|
||||
type: 'at',
|
||||
name,
|
||||
prelude,
|
||||
body,
|
||||
start: offset + preludeStart,
|
||||
end: offset + nodeEnd,
|
||||
});
|
||||
}
|
||||
} else if (prelude) {
|
||||
nodes.push({
|
||||
type: 'rule',
|
||||
prelude,
|
||||
body,
|
||||
start: offset + preludeStart,
|
||||
end: offset + nodeEnd,
|
||||
preludeStart: offset + preludeStart,
|
||||
});
|
||||
}
|
||||
i = nodeEnd;
|
||||
}
|
||||
return nodes;
|
||||
}
|
||||
|
||||
/**
|
||||
* Scan for the next structural boundary: the `{` opening a block, or the `;`
|
||||
* ending a block-less at-statement, whichever comes first (string- and
|
||||
* comment-aware). Returns { kind: 'block' | 'statement' | 'none', index }.
|
||||
*/
|
||||
function scanToBlockOrStatementEnd(text, from) {
|
||||
let i = from;
|
||||
let quote = null;
|
||||
while (i < text.length) {
|
||||
const ch = text[i];
|
||||
if (quote) {
|
||||
if (ch === '\\') i++;
|
||||
else if (ch === quote) quote = null;
|
||||
} else if (ch === '"' || ch === "'") {
|
||||
quote = ch;
|
||||
} else if (ch === '/' && text[i + 1] === '*') {
|
||||
const close = text.indexOf('*/', i + 2);
|
||||
i = close === -1 ? text.length : close + 1;
|
||||
} else if (ch === '{') {
|
||||
return { kind: 'block', index: i };
|
||||
} else if (ch === ';') {
|
||||
return { kind: 'statement', index: i };
|
||||
}
|
||||
i++;
|
||||
}
|
||||
return { kind: 'none', index: -1 };
|
||||
}
|
||||
|
||||
function scanBlockEnd(text, from) {
|
||||
let i = from;
|
||||
let depth = 1;
|
||||
let quote = null;
|
||||
while (i < text.length) {
|
||||
const ch = text[i];
|
||||
if (quote) {
|
||||
if (ch === '\\') i++;
|
||||
else if (ch === quote) quote = null;
|
||||
} else if (ch === '"' || ch === "'") {
|
||||
quote = ch;
|
||||
} else if (ch === '/' && text[i + 1] === '*') {
|
||||
const close = text.indexOf('*/', i + 2);
|
||||
i = close === -1 ? text.length : close + 1;
|
||||
} else if (ch === '{') {
|
||||
depth++;
|
||||
} else if (ch === '}') {
|
||||
depth--;
|
||||
if (depth === 0) return i;
|
||||
}
|
||||
i++;
|
||||
}
|
||||
return text.length;
|
||||
}
|
||||
|
||||
export function serializeNodes(nodes, indent = '') {
|
||||
const out = [];
|
||||
for (const node of nodes) {
|
||||
if (node.type === 'comment') {
|
||||
out.push(indent + node.text);
|
||||
} else if (node.type === 'rule') {
|
||||
out.push(`${indent}${node.prelude} {${formatBody(node.body, indent)}}`);
|
||||
} else if (node.type === 'at' && node.children) {
|
||||
out.push(`${indent}${node.prelude} {`);
|
||||
out.push(serializeNodes(node.children, indent + ' '));
|
||||
out.push(`${indent}}`);
|
||||
} else if (node.type === 'at' && node.statement) {
|
||||
out.push(`${indent}${node.prelude};`);
|
||||
} else if (node.type === 'at') {
|
||||
out.push(`${indent}${node.prelude} {${formatBody(node.body, indent)}}`);
|
||||
}
|
||||
}
|
||||
return out.join('\n');
|
||||
}
|
||||
|
||||
function formatBody(body, indent) {
|
||||
const trimmed = String(body || '').trim();
|
||||
if (!trimmed) return ' ';
|
||||
const lines = trimmed.split('\n').map((l) => l.trim()).filter(Boolean);
|
||||
if (lines.length === 1 && lines[0].length < 60) return ` ${lines[0]} `;
|
||||
return '\n' + lines.map((l) => `${indent} ${l}`).join('\n') + `\n${indent}`;
|
||||
}
|
||||
|
||||
export function normalizeSelector(prelude) {
|
||||
return String(prelude || '')
|
||||
.replace(/\s+/g, ' ')
|
||||
.replace(/\s*([>+~,])\s*/g, '$1')
|
||||
.trim();
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Reconciliation
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Merge variant CSS into existing CSS. Rules whose (at-context, normalized
|
||||
* selector) match an existing rule REPLACE that rule's body in place; new
|
||||
* rules append at the end under their at-context. Returns { css, replaced,
|
||||
* appended }.
|
||||
*/
|
||||
export function reconcileCss(existingCss, variantCss) {
|
||||
const existing = parseStylesheet(existingCss);
|
||||
const incoming = parseStylesheet(variantCss);
|
||||
let replaced = 0;
|
||||
let appended = 0;
|
||||
|
||||
const mergeLevel = (existingNodes, incomingNodes) => {
|
||||
const index = new Map();
|
||||
for (const node of existingNodes) {
|
||||
if (node.type === 'rule') index.set(normalizeSelector(node.prelude), node);
|
||||
}
|
||||
const atIndex = new Map();
|
||||
for (const node of existingNodes) {
|
||||
if (node.type === 'at' && node.children) atIndex.set(normalizeSelector(node.prelude), node);
|
||||
}
|
||||
// Baking can leave several incoming rules with the same selector (e.g. a
|
||||
// base rule plus a stripped param branch). The first one REPLACES the
|
||||
// existing body; later same-selector rules extend it, never clobber it.
|
||||
const touched = new Set();
|
||||
for (const node of incomingNodes) {
|
||||
if (node.type === 'comment') continue;
|
||||
if (node.type === 'rule') {
|
||||
const key = normalizeSelector(node.prelude);
|
||||
const match = index.get(key);
|
||||
if (match) {
|
||||
if (touched.has(key)) {
|
||||
match.body = `${match.body.trim()}\n${node.body.trim()}`;
|
||||
} else if (match.body.trim() !== node.body.trim()) {
|
||||
match.body = node.body;
|
||||
replaced++;
|
||||
}
|
||||
touched.add(key);
|
||||
} else {
|
||||
// New base rules go BEFORE the existing top-level media blocks:
|
||||
// appended after them, an equal-specificity base rule wins the
|
||||
// cascade over the stylesheet's earlier responsive overrides and
|
||||
// silently weakens the mobile styles for any still-shared class.
|
||||
const appendedNode = { ...node };
|
||||
const firstAt = existingNodes.findIndex((n) => n.type === 'at' && n.children);
|
||||
if (firstAt === -1) existingNodes.push(appendedNode);
|
||||
else existingNodes.splice(firstAt, 0, appendedNode);
|
||||
index.set(key, appendedNode);
|
||||
touched.add(key);
|
||||
appended++;
|
||||
}
|
||||
} else if (node.type === 'at' && node.children) {
|
||||
const key = normalizeSelector(node.prelude);
|
||||
const match = atIndex.get(key);
|
||||
if (match) {
|
||||
mergeLevel(match.children, node.children);
|
||||
} else {
|
||||
existingNodes.push({ ...node });
|
||||
atIndex.set(key, existingNodes[existingNodes.length - 1]);
|
||||
appended++;
|
||||
}
|
||||
} else {
|
||||
existingNodes.push({ ...node });
|
||||
appended++;
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
mergeLevel(existing, incoming);
|
||||
return { css: serializeNodes(existing), replaced, appended };
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Parameter baking
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Replace every `var(--p-<id>, fallback)` / `var(--p-<id>)` occurrence with a
|
||||
* literal value. Paren-aware: fallbacks containing calc()/nested vars are
|
||||
* handled, unlike the old `[^)]+` regex.
|
||||
*/
|
||||
export function substituteParamVar(css, id, value) {
|
||||
const text = String(css || '');
|
||||
const needle = `var(--p-${id}`;
|
||||
let out = '';
|
||||
let i = 0;
|
||||
while (i < text.length) {
|
||||
const idx = text.indexOf(needle, i);
|
||||
if (idx === -1) { out += text.slice(i); break; }
|
||||
const after = idx + needle.length;
|
||||
// Must be end of the var name: `)` or `,`.
|
||||
if (after < text.length && text[after] !== ')' && text[after] !== ',') {
|
||||
out += text.slice(i, after);
|
||||
i = after;
|
||||
continue;
|
||||
}
|
||||
let j = after;
|
||||
let depth = 1; // we are inside var(
|
||||
while (j < text.length && depth > 0) {
|
||||
if (text[j] === '(') depth++;
|
||||
else if (text[j] === ')') depth--;
|
||||
j++;
|
||||
}
|
||||
out += text.slice(i, idx) + String(value);
|
||||
i = j;
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function normalizeToggleForVar(value) {
|
||||
return value === true || value === 'true' || value === 1 || value === '1' || value === 'on' ? '1' : '0';
|
||||
}
|
||||
|
||||
function isToggleOn(value) {
|
||||
return normalizeToggleForVar(value) === '1';
|
||||
}
|
||||
|
||||
/**
|
||||
* Strip `[data-p-<id>="value"]` / `[data-p-<id>]` attribute selectors from a
|
||||
* selector, deciding survival by the chosen value:
|
||||
* returns null when the selector targets a non-chosen branch (drop it),
|
||||
* otherwise the selector with the attribute test removed and any emptied
|
||||
* :global() wrappers cleaned up.
|
||||
*/
|
||||
export function stripParamSelector(selector, id, kind, chosenValue) {
|
||||
const attrRe = new RegExp(`\\[data-p-${escapeRegExp(id)}(?:=(["'])(.*?)\\1)?\\]`, 'g');
|
||||
let drop = false;
|
||||
let out = String(selector).replace(attrRe, (_m, _q, expected) => {
|
||||
if (kind === 'steps') {
|
||||
if (expected == null || String(expected) === String(chosenValue)) return '';
|
||||
drop = true;
|
||||
return '';
|
||||
}
|
||||
// toggle: the runtime sets data-p-<id>="on" when on and removes the
|
||||
// attribute when off. A branch survives baking only if it actually
|
||||
// matched at preview time with the chosen state: the presence form and
|
||||
// the literal "on" form match while on; every other valued form
|
||||
// (["false"], ["0"], ...) never matched and is dead regardless of state.
|
||||
if (expected != null && expected !== 'on') {
|
||||
drop = true;
|
||||
return '';
|
||||
}
|
||||
if (!isToggleOn(chosenValue)) {
|
||||
drop = true;
|
||||
return '';
|
||||
}
|
||||
return '';
|
||||
});
|
||||
if (drop) return null;
|
||||
out = out
|
||||
.replace(/:global\(\s*\)/g, '')
|
||||
.replace(/\s+/g, ' ')
|
||||
.replace(/^\s*[>+~]\s*/, '')
|
||||
.trim();
|
||||
return out || null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Bake chosen parameter values into CSS. `params` is the declared parameter
|
||||
* list for the accepted variant (from params.json); `values` maps id ->
|
||||
* chosen value (falling back to each param's declared default).
|
||||
*/
|
||||
export function bakeParamValues(css, params = [], values = {}) {
|
||||
let nodes = parseStylesheet(css);
|
||||
|
||||
const chosen = new Map();
|
||||
for (const param of params || []) {
|
||||
if (!param || !param.id) continue;
|
||||
const has = values && Object.prototype.hasOwnProperty.call(values, param.id);
|
||||
chosen.set(param.id, { kind: param.kind, value: has ? values[param.id] : param.default });
|
||||
}
|
||||
// Values sent for params that were never declared still bake as ranges,
|
||||
// so an out-of-sync manifest degrades to the old behavior, not to silence.
|
||||
for (const [id, value] of Object.entries(values || {})) {
|
||||
if (!chosen.has(id)) chosen.set(id, { kind: 'range', value });
|
||||
}
|
||||
|
||||
const bakeBody = (body) => {
|
||||
let out = String(body || '');
|
||||
for (const [id, { kind, value }] of chosen) {
|
||||
const literal = kind === 'toggle' ? normalizeToggleForVar(value) : String(value);
|
||||
out = substituteParamVar(out, id, literal);
|
||||
}
|
||||
// Strip the readiness sentinel as a DECLARATION, not a line: a one-line
|
||||
// rule carrying the sentinel plus real declarations must keep the rest.
|
||||
return out
|
||||
.replace(/(^|;)\s*--impeccable-variant-ready\s*:[^;{}]*/g, '$1')
|
||||
.replace(/;\s*;/g, ';')
|
||||
.replace(/^\s*;\s*/, '');
|
||||
};
|
||||
|
||||
const transform = (list) => {
|
||||
const result = [];
|
||||
for (const node of list) {
|
||||
if (node.type === 'at' && node.children) {
|
||||
const children = transform(node.children);
|
||||
if (children.length > 0) result.push({ ...node, children });
|
||||
continue;
|
||||
}
|
||||
if (node.type !== 'rule') {
|
||||
if (node.type === 'at') result.push({ ...node, body: bakeBody(node.body) });
|
||||
else result.push(node);
|
||||
continue;
|
||||
}
|
||||
const selectors = splitSelectorList(node.prelude);
|
||||
const kept = [];
|
||||
for (let selector of selectors) {
|
||||
let alive = true;
|
||||
for (const [id, { kind, value }] of chosen) {
|
||||
if (kind !== 'steps' && kind !== 'toggle') continue;
|
||||
if (!selector.includes(`data-p-${id}`)) continue;
|
||||
const next = stripParamSelector(selector, id, kind, value);
|
||||
if (next == null) { alive = false; break; }
|
||||
selector = next;
|
||||
}
|
||||
if (alive && selector.trim()) kept.push(selector.trim());
|
||||
}
|
||||
if (kept.length === 0) continue;
|
||||
const body = bakeBody(node.body);
|
||||
if (!body.trim()) continue;
|
||||
result.push({ ...node, prelude: kept.join(', '), body });
|
||||
}
|
||||
return result;
|
||||
};
|
||||
|
||||
nodes = transform(nodes);
|
||||
return serializeNodes(nodes);
|
||||
}
|
||||
|
||||
export function splitSelectorList(prelude) {
|
||||
const selectors = [];
|
||||
let start = 0;
|
||||
let bracket = 0;
|
||||
let paren = 0;
|
||||
let quote = null;
|
||||
const text = String(prelude || '');
|
||||
for (let i = 0; i < text.length; i++) {
|
||||
const ch = text[i];
|
||||
if (quote) {
|
||||
if (ch === '\\') i++;
|
||||
else if (ch === quote) quote = null;
|
||||
continue;
|
||||
}
|
||||
if (ch === '"' || ch === "'") quote = ch;
|
||||
else if (ch === '[') bracket++;
|
||||
else if (ch === ']') bracket = Math.max(0, bracket - 1);
|
||||
else if (ch === '(') paren++;
|
||||
else if (ch === ')') paren = Math.max(0, paren - 1);
|
||||
else if (ch === ',' && bracket === 0 && paren === 0) {
|
||||
selectors.push(text.slice(start, i));
|
||||
start = i + 1;
|
||||
}
|
||||
}
|
||||
selectors.push(text.slice(start));
|
||||
return selectors.map((s) => s.trim()).filter(Boolean);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Compiler-driven pruning
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Remove selectors the framework compiler reports as unused from a full
|
||||
* component source. `compileFn` is the app's svelte compile; warnings with
|
||||
* code `css_unused_selector` carry character offsets into the source.
|
||||
* `skipSelectors` protects selectors that were already unused before the
|
||||
* accept: pre-existing dead rules are the user's code, not live-mode debris.
|
||||
* Returns { source, removed } where removed lists the pruned selector texts.
|
||||
*/
|
||||
export function collectUnusedSelectors(componentSource, compileFn) {
|
||||
try {
|
||||
const { warnings } = compileFn(String(componentSource || ''), { generate: false });
|
||||
return new Set((warnings || [])
|
||||
.filter((w) => w.code === 'css_unused_selector'
|
||||
&& Number.isInteger(w.start?.character)
|
||||
&& Number.isInteger(w.end?.character))
|
||||
.map((w) => String(componentSource).slice(w.start.character, w.end.character).trim()));
|
||||
} catch {
|
||||
return new Set();
|
||||
}
|
||||
}
|
||||
|
||||
export function pruneUnusedSelectors(componentSource, compileFn, { skipSelectors } = {}) {
|
||||
let source = String(componentSource || '');
|
||||
const removed = [];
|
||||
const skip = skipSelectors instanceof Set ? skipSelectors : new Set(skipSelectors || []);
|
||||
for (let pass = 0; pass < 3; pass++) {
|
||||
let warnings;
|
||||
try {
|
||||
({ warnings } = compileFn(source, { generate: false }));
|
||||
} catch {
|
||||
return { source, removed }; // never let pruning break an accept
|
||||
}
|
||||
const unused = (warnings || [])
|
||||
.filter((w) => w.code === 'css_unused_selector'
|
||||
&& Number.isInteger(w.start?.character)
|
||||
&& Number.isInteger(w.end?.character))
|
||||
.filter((w) => !skip.has(source.slice(w.start.character, w.end.character).trim()))
|
||||
.sort((a, b) => b.start.character - a.start.character);
|
||||
if (unused.length === 0) break;
|
||||
|
||||
let next = source;
|
||||
for (const warning of unused) {
|
||||
const result = removeSelectorAt(next, warning.start.character, warning.end.character);
|
||||
if (result.changed) {
|
||||
removed.push(result.selector);
|
||||
next = result.source;
|
||||
}
|
||||
}
|
||||
if (next === source) break;
|
||||
source = next;
|
||||
}
|
||||
return { source, removed };
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove the selector at [start, end) from its rule. When it is the rule's
|
||||
* only selector, remove the whole rule (prelude through closing brace).
|
||||
*/
|
||||
function removeSelectorAt(source, start, end) {
|
||||
const selector = source.slice(start, end);
|
||||
|
||||
// Find the rule boundaries around the selector.
|
||||
const braceIdx = source.indexOf('{', end);
|
||||
if (braceIdx === -1) return { changed: false, selector, source };
|
||||
const bodyEnd = scanBlockEnd(source, braceIdx + 1);
|
||||
|
||||
// Prelude spans backward from the brace to the previous } ; { or the end
|
||||
// of the <style> open tag. A bare `>` is NOT a boundary: it is the child
|
||||
// combinator, and cutting there truncates a selector list like
|
||||
// `.a > .b, .c` mid-prelude. Only a `>` that closes a `<style ...>` tag
|
||||
// bounds the walk.
|
||||
let preludeStart = start;
|
||||
for (let i = start - 1; i >= 0; i--) {
|
||||
const ch = source[i];
|
||||
if (ch === '}' || ch === '{' || ch === ';') { preludeStart = i + 1; break; }
|
||||
if (ch === '>') {
|
||||
const styleOpen = source.lastIndexOf('<style', i);
|
||||
if (styleOpen !== -1 && source.indexOf('>', styleOpen) === i) { preludeStart = i + 1; break; }
|
||||
continue; // child combinator inside the prelude
|
||||
}
|
||||
if (i === 0) preludeStart = 0;
|
||||
}
|
||||
const prelude = source.slice(preludeStart, braceIdx);
|
||||
const selectors = splitSelectorList(prelude);
|
||||
const target = selector.trim();
|
||||
const kept = selectors.filter((s) => s !== target);
|
||||
|
||||
if (kept.length === selectors.length) {
|
||||
// Offsets did not line up with a full selector in the list; be safe.
|
||||
return { changed: false, selector, source };
|
||||
}
|
||||
|
||||
if (kept.length === 0) {
|
||||
// Remove the entire rule including trailing newline.
|
||||
let ruleEnd = Math.min(source.length, bodyEnd + 1);
|
||||
while (ruleEnd < source.length && source[ruleEnd] === '\n') ruleEnd++;
|
||||
let ruleStart = preludeStart;
|
||||
while (ruleStart > 0 && (source[ruleStart - 1] === ' ' || source[ruleStart - 1] === '\t')) ruleStart--;
|
||||
return { changed: true, selector: target, source: source.slice(0, ruleStart) + source.slice(ruleEnd) };
|
||||
}
|
||||
|
||||
const indent = (prelude.match(/^\s*/) || [''])[0];
|
||||
return {
|
||||
changed: true,
|
||||
selector: target,
|
||||
source: source.slice(0, preludeStart) + indent + kept.join(', ') + ' ' + source.slice(braceIdx, source.length),
|
||||
};
|
||||
}
|
||||
|
||||
function escapeRegExp(value) {
|
||||
return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
||||
}
|
||||
|
||||
/**
|
||||
* Collect every normalized selector in a CSS text, including inside nested
|
||||
* at-blocks. Used by the accept postcondition: a selector present before the
|
||||
* accept may only disappear if the compiler reported it unused; anything
|
||||
* else means the parser or reconciler damaged the user's file, and the write
|
||||
* must be refused rather than silently committed.
|
||||
*/
|
||||
export function collectAllSelectors(css, out = new Set()) {
|
||||
for (const node of parseStylesheet(css)) {
|
||||
if (node.type === 'rule') {
|
||||
for (const selector of splitSelectorList(node.prelude)) out.add(normalizeSelector(selector));
|
||||
} else if (node.type === 'at' && node.children) {
|
||||
for (const child of node.children) {
|
||||
if (child.type === 'rule') {
|
||||
for (const selector of splitSelectorList(child.prelude)) out.add(normalizeSelector(selector));
|
||||
} else if (child.type === 'at' && child.children) {
|
||||
collectSelectorsFromNodes(child.children, out);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function collectSelectorsFromNodes(nodes, out) {
|
||||
for (const node of nodes) {
|
||||
if (node.type === 'rule') {
|
||||
for (const selector of splitSelectorList(node.prelude)) out.add(normalizeSelector(selector));
|
||||
} else if (node.type === 'at' && node.children) {
|
||||
collectSelectorsFromNodes(node.children, out);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,60 @@
|
||||
/**
|
||||
* Postcondition scanner for accepted/carbonized source. The carbonize
|
||||
* contract used to exist only as prose in reference/live.md; nothing checked
|
||||
* that an accept actually left the file clean, so dead param branches,
|
||||
* preview attributes, and marker comments accumulated across sessions. This
|
||||
* scanner is the mechanical form of that contract. live-complete refuses to
|
||||
* mark a carbonize session complete while the file is dirty, and the
|
||||
* mechanical Svelte accept runs it on its own output as a self-check.
|
||||
*/
|
||||
|
||||
// Param patterns are anchored to the exact shapes live mode writes
|
||||
// (attribute-with-value / selector forms, var() references), not bare
|
||||
// substrings, so user tokens that merely share the prefix cannot trip the
|
||||
// completion gate.
|
||||
const FORBIDDEN = [
|
||||
{ marker: 'impeccable-variants-start', why: 'variant wrapper comment left in source' },
|
||||
{ marker: 'impeccable-variants-end', why: 'variant wrapper comment left in source' },
|
||||
{ marker: 'impeccable-carbonize-start', why: 'carbonize block not rewritten into permanent form' },
|
||||
{ marker: 'impeccable-carbonize-end', why: 'carbonize block not rewritten into permanent form' },
|
||||
{ marker: 'impeccable-param-values', why: 'param-values comment not baked and removed' },
|
||||
{ marker: 'data-impeccable-', why: 'live-mode plumbing attribute left on markup' },
|
||||
{ marker: /\bdata-p-[A-Za-z0-9_-]+\s*(?:=|\])/, label: 'data-p-*', why: 'preview parameter attribute left on markup' },
|
||||
{ marker: /var\(\s*--p-[A-Za-z0-9_-]+\s*[,)]/, label: 'var(--p-*)', why: 'preview parameter variable not baked to a literal' },
|
||||
{ marker: '--impeccable-variant-ready', why: 'preview readiness sentinel left in CSS' },
|
||||
];
|
||||
|
||||
/**
|
||||
* Scan file text for live-mode leftovers. Returns { clean, findings } where
|
||||
* each finding is { marker, line, excerpt, why }.
|
||||
*/
|
||||
export function verifyAcceptedSource(text) {
|
||||
const findings = [];
|
||||
const lines = String(text || '').split('\n');
|
||||
for (let i = 0; i < lines.length; i++) {
|
||||
const line = lines[i];
|
||||
for (const { marker, label, why } of FORBIDDEN) {
|
||||
const hit = marker instanceof RegExp ? marker.test(line) : line.includes(marker);
|
||||
if (hit) {
|
||||
findings.push({
|
||||
marker: label || String(marker),
|
||||
line: i + 1,
|
||||
excerpt: line.trim().slice(0, 120),
|
||||
why,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
return { clean: findings.length === 0, findings };
|
||||
}
|
||||
|
||||
/** Convenience wrapper for CLI callers: read + scan, tolerating a missing file. */
|
||||
export function verifyAcceptedFile(fs, filePath) {
|
||||
let text;
|
||||
try {
|
||||
text = fs.readFileSync(filePath, 'utf-8');
|
||||
} catch {
|
||||
return { clean: true, findings: [], missing: true };
|
||||
}
|
||||
return { ...verifyAcceptedSource(text), missing: false };
|
||||
}
|
||||
@@ -32,10 +32,15 @@ export function readLiveBrowserScriptParts(parts, readFile = (filePath) => fs.re
|
||||
}));
|
||||
}
|
||||
|
||||
export function assembleLiveBrowserScript({ token, port, vocabulary, commandPrefix = '/', parts }) {
|
||||
export function assembleLiveBrowserScript({ token, port, vocabulary, commandPrefix = '/', appRoot = null, parts }) {
|
||||
const prelude =
|
||||
`window.__IMPECCABLE_TOKEN__ = '${token}';\n` +
|
||||
`window.__IMPECCABLE_PORT__ = ${port};\n` +
|
||||
// Project identity for browser-side session storage. localStorage is
|
||||
// keyed by ORIGIN, and two projects routinely share a localhost port
|
||||
// across time; saved sessions carry this value so a resume can tell a
|
||||
// foreign project's leftovers from its own.
|
||||
`window.__IMPECCABLE_APP_ROOT__ = ${JSON.stringify(appRoot)};\n` +
|
||||
`window.__IMPECCABLE_COMMAND_PREFIX__ = ${JSON.stringify(commandPrefix)};\n` +
|
||||
// Canonical command vocabulary (values + labels + icons). live-browser.js
|
||||
// builds its action picker from this instead of an inline copy.
|
||||
|
||||
@@ -5,17 +5,26 @@
|
||||
|
||||
import { canCreateInsert } from './insert-ui.mjs';
|
||||
|
||||
// The accepted visual action values come from the canonical vocabulary so the
|
||||
// validator, the picker UI, and the marketing demo never drift. Imported (not
|
||||
// just re-exported) so it is also in scope for the validators below.
|
||||
import { VISUAL_ACTIONS } from './vocabulary.mjs';
|
||||
export { VISUAL_ACTIONS };
|
||||
// The accepted protocol values come from the canonical vocabulary so the
|
||||
// validator, the store, the server, and the picker UI never drift. Imported
|
||||
// (not just re-exported) so they are also in scope for the validators below.
|
||||
import { AGENT_PHASES, CLIENT_EVENT_TYPES, VISUAL_ACTIONS } from './vocabulary.mjs';
|
||||
export { AGENT_PHASES, CLIENT_EVENT_TYPES, VISUAL_ACTIONS };
|
||||
|
||||
const AGENT_PHASE_SET = new Set(AGENT_PHASES);
|
||||
|
||||
const ID_PATTERN = /^[0-9a-f]{8}$/;
|
||||
const VARIANT_ID_PATTERN = /^[0-9]{1,3}$/;
|
||||
const INSERT_POSITIONS = new Set(['before', 'after']);
|
||||
const FORBIDDEN_MANUAL_EDIT_TEXT_CHARS = ['<', '{', '}', '`'];
|
||||
|
||||
// Mount acknowledgements carry a module URL and a raw exception message from
|
||||
// the page. Both are attacker-adjacent (any script on the page can POST them
|
||||
// with the token it can already read), so they are length-capped before they
|
||||
// reach the journal.
|
||||
export const MOUNT_URL_MAX_LENGTH = 2000;
|
||||
export const MOUNT_ERROR_MAX_LENGTH = 1000;
|
||||
|
||||
function isValidId(v) { return typeof v === 'string' && ID_PATTERN.test(v); }
|
||||
function isValidVariantId(v) { return typeof v === 'string' && VARIANT_ID_PATTERN.test(v); }
|
||||
|
||||
@@ -92,6 +101,36 @@ function validateManualEditEvent(msg, label) {
|
||||
return null;
|
||||
}
|
||||
|
||||
function isValidMountVariant(value) {
|
||||
return Number.isInteger(value) && value >= 1 && value <= 999;
|
||||
}
|
||||
|
||||
/**
|
||||
* Mount acknowledgements are the browser's answer to "did the thing you
|
||||
* published actually render". They are validated strictly because the render
|
||||
* truth in the session snapshot is built from them: a malformed ack that slid
|
||||
* through would report a variant as mounted that never was.
|
||||
*/
|
||||
function validateMountAck(msg) {
|
||||
if (!isValidId(msg.id)) return 'variant_mounted: missing or malformed id';
|
||||
if (!isValidMountVariant(msg.variant)) return 'variant_mounted: variant must be an integer 1-999';
|
||||
if (msg.url !== undefined) {
|
||||
if (typeof msg.url !== 'string') return 'variant_mounted: url must be string';
|
||||
if (msg.url.length > MOUNT_URL_MAX_LENGTH) return 'variant_mounted: url too long';
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function validateMountFailure(msg) {
|
||||
if (!isValidId(msg.id)) return 'variant_mount_failed: missing or malformed id';
|
||||
if (!isValidMountVariant(msg.variant)) return 'variant_mount_failed: variant must be an integer 1-999';
|
||||
if (typeof msg.url !== 'string' || !msg.url.trim()) return 'variant_mount_failed: url required';
|
||||
if (msg.url.length > MOUNT_URL_MAX_LENGTH) return 'variant_mount_failed: url too long';
|
||||
if (typeof msg.error !== 'string' || !msg.error.trim()) return 'variant_mount_failed: error required';
|
||||
if (msg.error.length > MOUNT_ERROR_MAX_LENGTH) return 'variant_mount_failed: error too long';
|
||||
return null;
|
||||
}
|
||||
|
||||
export function validateEvent(msg) {
|
||||
if (!msg || typeof msg !== 'object' || !msg.type) return 'Missing or invalid message';
|
||||
switch (msg.type) {
|
||||
@@ -120,13 +159,21 @@ export function validateEvent(msg) {
|
||||
return null;
|
||||
case 'agent_phase':
|
||||
if (!isValidId(msg.id)) return 'agent_phase: missing or malformed id';
|
||||
if (typeof msg.phase !== 'string' || !/^[a-z][a-z0-9_]{1,63}$/.test(msg.phase)) {
|
||||
return 'agent_phase: missing or malformed phase';
|
||||
if (typeof msg.phase !== 'string' || !msg.phase) return 'agent_phase: missing phase';
|
||||
// The enum, not a shape pattern. A phase the browser cannot rank is a
|
||||
// phase the progress bar cannot show, so accepting an arbitrary
|
||||
// lowercase word only defers the failure to the UI.
|
||||
if (!AGENT_PHASE_SET.has(msg.phase)) {
|
||||
return 'agent_phase: unknown phase ' + msg.phase + ' (expected one of ' + AGENT_PHASES.join(', ') + ')';
|
||||
}
|
||||
if (msg.durationMs !== undefined && (!Number.isFinite(msg.durationMs) || msg.durationMs < 0)) {
|
||||
return 'agent_phase: durationMs must be a non-negative number';
|
||||
}
|
||||
return null;
|
||||
case 'variant_mounted':
|
||||
return validateMountAck(msg);
|
||||
case 'variant_mount_failed':
|
||||
return validateMountFailure(msg);
|
||||
case 'exit':
|
||||
return null;
|
||||
case 'prefetch':
|
||||
|
||||
@@ -0,0 +1,47 @@
|
||||
/**
|
||||
* Astro registry entry.
|
||||
*
|
||||
* Astro takes the generic tag strategy, with two Astro-specific values that
|
||||
* used to sit as inline `endsWith('.astro')` branches in live-inject.mjs and
|
||||
* live-wrap.mjs:
|
||||
*
|
||||
* injectScriptAttrs Astro processes <script> tags by default and rewrites
|
||||
* src to its own bundled URL; is:inline opts out.
|
||||
* styleMode Astro scopes component styles, which strips preview CSS
|
||||
* off the generated variant wrappers, so preview rules are
|
||||
* authored global and prefixed instead of @scope'd.
|
||||
*/
|
||||
|
||||
import { findConfigFile, hasAnyDependency, literalConfigFiles } from './detect-utils.mjs';
|
||||
|
||||
const ASTRO_CONFIG_RE = /^astro\.config\.(?:js|mjs|cjs|ts|mts|cts)$/;
|
||||
|
||||
export function detectAstroProject(cwd = process.cwd(), config = null) {
|
||||
const configFile = findConfigFile(cwd, ASTRO_CONFIG_RE);
|
||||
if (configFile) return { configFile, via: 'config' };
|
||||
if (hasAnyDependency(cwd, ['astro'])) return { configFile: null, via: 'package' };
|
||||
// A tree of .astro entry templates with no astro.config still belongs to
|
||||
// Astro; the configured injection target names it.
|
||||
const entry = literalConfigFiles(cwd, config).find((rel) => rel.endsWith('.astro'));
|
||||
if (entry) return { configFile: null, via: 'config-files', entry };
|
||||
return null;
|
||||
}
|
||||
|
||||
export const astro = {
|
||||
name: 'astro',
|
||||
|
||||
detect(cwd, config) {
|
||||
return detectAstroProject(cwd, config);
|
||||
},
|
||||
|
||||
inject: { kind: 'tag' },
|
||||
|
||||
source: {
|
||||
extensions: ['.astro'],
|
||||
preview: 'source',
|
||||
styleMode: 'astro-global-prefixed',
|
||||
styleTag: '<style is:inline data-impeccable-css="SESSION_ID">',
|
||||
commentSyntax: 'html',
|
||||
injectScriptAttrs: 'is:inline ',
|
||||
},
|
||||
};
|
||||
@@ -0,0 +1,73 @@
|
||||
/**
|
||||
* Small read-only probes the framework entries share.
|
||||
*
|
||||
* Every helper here is cheap and failure-tolerant: detection runs on every
|
||||
* inject, against project trees that may be half-installed, so a missing or
|
||||
* malformed file means "not this framework", never a throw.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
/** Merged dependency names from package.json, or an empty object. */
|
||||
export function readPackageDeps(cwd) {
|
||||
const file = path.join(cwd, 'package.json');
|
||||
try {
|
||||
const pkg = JSON.parse(fs.readFileSync(file, 'utf-8'));
|
||||
return {
|
||||
...(pkg.dependencies || {}),
|
||||
...(pkg.devDependencies || {}),
|
||||
...(pkg.peerDependencies || {}),
|
||||
};
|
||||
} catch {
|
||||
return {};
|
||||
}
|
||||
}
|
||||
|
||||
export function hasAnyDependency(cwd, names) {
|
||||
const deps = readPackageDeps(cwd);
|
||||
return names.some((name) => Boolean(deps[name]));
|
||||
}
|
||||
|
||||
/** First top-level file name matching `re`, or null. */
|
||||
export function findConfigFile(cwd, re) {
|
||||
try {
|
||||
return fs.readdirSync(cwd, { withFileTypes: true })
|
||||
.find((entry) => entry.isFile() && re.test(entry.name))
|
||||
?.name ?? null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
export function fileExists(cwd, rel) {
|
||||
try {
|
||||
return fs.existsSync(path.join(cwd, rel));
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
export function firstExistingFile(cwd, candidates) {
|
||||
for (const rel of candidates) {
|
||||
if (fileExists(cwd, rel)) return rel;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Literal (non-glob) entries of `config.files` that exist on disk. Several
|
||||
* detectors read the configured injection target as a signal, which is how the
|
||||
* bare fixtures — a tree of `.astro` files with no astro.config — still resolve
|
||||
* to the framework that authored them.
|
||||
*/
|
||||
export function literalConfigFiles(cwd, config) {
|
||||
const files = Array.isArray(config?.files) ? config.files : [];
|
||||
const out = [];
|
||||
for (const rel of files) {
|
||||
if (typeof rel !== 'string' || rel.includes('*') || rel.includes('?')) continue;
|
||||
const normalized = rel.split(path.sep).join('/');
|
||||
if (fileExists(cwd, normalized)) out.push(normalized);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
@@ -0,0 +1,143 @@
|
||||
/**
|
||||
* The live-mode framework registry.
|
||||
*
|
||||
* Before this existed, framework knowledge was smeared across live-inject.mjs
|
||||
* (detection order, the Nuxt adapter, the Astro `is:inline` branch), the two
|
||||
* adapter modules, and live-wrap.mjs (which extension gets component preview,
|
||||
* which gets Astro's global-prefixed CSS, which gets JSX comments). Adding or
|
||||
* fixing a framework meant reading all of them.
|
||||
*
|
||||
* One entry per framework now declares everything the live scripts need:
|
||||
*
|
||||
* name stable identifier; also the `adapter` value in inject JSON.
|
||||
* detect (cwd, config) → falsy when this is not the project, otherwise
|
||||
* a truthy project descriptor that apply/remove/artifacts read.
|
||||
* Order in FRAMEWORKS is priority order; first truthy wins.
|
||||
* inject { kind: 'adapter', apply, remove, ignorePatterns, artifacts,
|
||||
* unpatch } for frameworks that server-render their document
|
||||
* shell, or { kind: 'tag' } for the generic marker-wrapped
|
||||
* <script src> block.
|
||||
* source how live-wrap treats files this framework authors:
|
||||
* extensions, preview ('source' | 'component'), styleMode,
|
||||
* styleTag, commentSyntax, injectScriptAttrs. Anything omitted
|
||||
* falls back to SOURCE_TRAIT_DEFAULTS.
|
||||
*
|
||||
* Two rules hold the thing together:
|
||||
*
|
||||
* 1. **Detection order is injection priority.** SvelteKit → Nuxt → TanStack
|
||||
* Start → Astro → Next → Vite → static HTML, exactly the order
|
||||
* live-inject.mjs used to hard-code. static-html always matches, so
|
||||
* resolveFramework never returns null.
|
||||
* 2. **Source traits resolve by file extension, not by project.** A SvelteKit
|
||||
* project's injection target is `src/app.html`; a Vite app can contain
|
||||
* `.astro` partials. live-wrap has always keyed these off the target file,
|
||||
* and resolveSourceTraits keeps it that way. Several entries may claim the
|
||||
* same extension (`.tsx` belongs to three); when they do, the values must
|
||||
* agree, which tests/live-frameworks.test.mjs asserts.
|
||||
*/
|
||||
|
||||
import path from 'node:path';
|
||||
|
||||
import { sveltekit } from './sveltekit.mjs';
|
||||
import { nuxt } from './nuxt.mjs';
|
||||
import { tanstackStart } from './tanstack-start.mjs';
|
||||
import { astro } from './astro.mjs';
|
||||
import { nextjs } from './nextjs.mjs';
|
||||
import { viteGeneric } from './vite-generic.mjs';
|
||||
import { staticHtml } from './static-html.mjs';
|
||||
import { TAG_PATCH_MARKERS, unpatchTagFile } from './tag-strategy.mjs';
|
||||
|
||||
/** Priority order. Do not reorder without re-reading rule 1 above. */
|
||||
export const FRAMEWORKS = Object.freeze([
|
||||
sveltekit,
|
||||
nuxt,
|
||||
tanstackStart,
|
||||
astro,
|
||||
nextjs,
|
||||
viteGeneric,
|
||||
staticHtml,
|
||||
]);
|
||||
|
||||
export const PREVIEW_MODES = Object.freeze(['source', 'component']);
|
||||
export const STYLE_MODES = Object.freeze(['scoped', 'astro-global-prefixed']);
|
||||
export const COMMENT_SYNTAXES = Object.freeze(['html', 'jsx']);
|
||||
export const INJECT_KINDS = Object.freeze(['adapter', 'tag']);
|
||||
|
||||
export const SOURCE_TRAIT_DEFAULTS = Object.freeze({
|
||||
preview: 'source',
|
||||
styleMode: 'scoped',
|
||||
styleTag: '<style data-impeccable-css="SESSION_ID">',
|
||||
commentSyntax: 'html',
|
||||
injectScriptAttrs: '',
|
||||
});
|
||||
|
||||
/** The patch kind the generic tag strategy records in the journal. */
|
||||
export const TAG_PATCH_KIND = 'live-tag';
|
||||
|
||||
/**
|
||||
* Undo functions keyed by the `patch` value an artifact carries. Built from
|
||||
* the entries so a new adapter registers its own undo alongside its apply.
|
||||
*/
|
||||
export const PATCH_UNDOERS = Object.freeze(Object.assign(
|
||||
{ [TAG_PATCH_KIND]: unpatchTagFile },
|
||||
...FRAMEWORKS.map((framework) => framework.inject.unpatch || {}),
|
||||
));
|
||||
|
||||
/**
|
||||
* First entry whose detect() matches. Returns { framework, project } where
|
||||
* project is the detector's descriptor (adapters read it; tag frameworks
|
||||
* mostly ignore it).
|
||||
*/
|
||||
export function resolveFramework(cwd = process.cwd(), config = null) {
|
||||
for (const framework of FRAMEWORKS) {
|
||||
const project = framework.detect(cwd, config);
|
||||
if (project) return { framework, project };
|
||||
}
|
||||
// Unreachable while static-html stays terminal, but a caller that reorders
|
||||
// the array should get a diagnosable null rather than a silent tag inject.
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Source-authoring traits for one file, merged over SOURCE_TRAIT_DEFAULTS.
|
||||
* `framework` names the entry that claimed the extension, or null.
|
||||
*/
|
||||
export function resolveSourceTraits(filePath) {
|
||||
const ext = path.extname(String(filePath || '')).toLowerCase();
|
||||
for (const framework of FRAMEWORKS) {
|
||||
const source = framework.source;
|
||||
if (!source || !source.extensions.includes(ext)) continue;
|
||||
const { extensions, ...traits } = source;
|
||||
return { framework: framework.name, ...SOURCE_TRAIT_DEFAULTS, ...traits };
|
||||
}
|
||||
return { framework: null, ...SOURCE_TRAIT_DEFAULTS };
|
||||
}
|
||||
|
||||
/**
|
||||
* Extra gitignore patterns the resolved framework needs beyond the static
|
||||
* LIVE_IGNORE_PATTERNS list (paths that depend on a detected srcDir or file
|
||||
* extension and so cannot be written down ahead of time).
|
||||
*/
|
||||
export function frameworkIgnorePatterns(resolved) {
|
||||
const fn = resolved?.framework?.inject?.ignorePatterns;
|
||||
return typeof fn === 'function' ? (fn(resolved.project) || []) : [];
|
||||
}
|
||||
|
||||
/**
|
||||
* The files this injection will create or patch, in journal-artifact form.
|
||||
* Adapters declare their own; the tag strategy patches exactly the resolved
|
||||
* config files.
|
||||
*/
|
||||
export function describeInjectArtifacts(resolved, { cwd = process.cwd(), files = [] } = {}) {
|
||||
if (!resolved) return [];
|
||||
const { framework, project } = resolved;
|
||||
if (framework.inject.kind === 'adapter') {
|
||||
return (framework.inject.artifacts?.({ cwd, project }) || []).filter((a) => a && a.path);
|
||||
}
|
||||
return files.map((file) => ({
|
||||
kind: 'patched',
|
||||
path: file,
|
||||
patch: TAG_PATCH_KIND,
|
||||
markers: [...TAG_PATCH_MARKERS],
|
||||
}));
|
||||
}
|
||||
@@ -0,0 +1,197 @@
|
||||
/**
|
||||
* Crash-safe injection journal.
|
||||
*
|
||||
* Injection writes into the user's source tree: generated components, a Nuxt
|
||||
* client plugin, marker blocks inside a layout, a patched CSP meta tag. The
|
||||
* clean path removes all of it on stop. The unclean paths do not:
|
||||
*
|
||||
* - the dev server is SIGKILLed, so `--remove` never runs;
|
||||
* - the project changes shape between start and stop (a nuxt.config appears,
|
||||
* a package.json is edited), so detection resolves a different framework
|
||||
* and the old framework's artifacts are nobody's business;
|
||||
* - stop runs from a different directory than start did.
|
||||
*
|
||||
* So every inject records what it wrote to `.impeccable/live/inject-journal.json`
|
||||
* before the next one runs, and both inject and `--remove` reconcile that
|
||||
* record against the tree.
|
||||
*
|
||||
* **The journal is a claim of ownership, not a to-do list.** Healing an
|
||||
* artifact only ever removes what still carries our marker; a generated file
|
||||
* the user has since replaced, or a layout they have since un-patched by hand,
|
||||
* is dropped from the journal untouched.
|
||||
*
|
||||
* **Path resolution is appRoot-relative.** Live entry scripts chdir onto the
|
||||
* roots manifest (`enterLiveRoot`) before doing anything, so a journal written
|
||||
* by a session started in the app root is found by a stop issued from any
|
||||
* directory inside the repo.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { PATCH_UNDOERS } from './index.mjs';
|
||||
|
||||
export const INJECT_JOURNAL_VERSION = 1;
|
||||
export const INJECT_JOURNAL_RELPATH = '.impeccable/live/inject-journal.json';
|
||||
|
||||
export function injectJournalPath(cwd = process.cwd()) {
|
||||
return path.join(cwd, ...INJECT_JOURNAL_RELPATH.split('/'));
|
||||
}
|
||||
|
||||
export function readInjectJournal(cwd = process.cwd()) {
|
||||
const file = injectJournalPath(cwd);
|
||||
let raw;
|
||||
try {
|
||||
raw = JSON.parse(fs.readFileSync(file, 'utf-8'));
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
if (!raw || typeof raw !== 'object' || !Array.isArray(raw.artifacts)) return null;
|
||||
return raw;
|
||||
}
|
||||
|
||||
export function clearInjectJournal(cwd = process.cwd()) {
|
||||
try { fs.unlinkSync(injectJournalPath(cwd)); } catch { /* already gone */ }
|
||||
}
|
||||
|
||||
function writeInjectJournal(cwd, journal) {
|
||||
const file = injectJournalPath(cwd);
|
||||
fs.mkdirSync(path.dirname(file), { recursive: true });
|
||||
fs.writeFileSync(file, JSON.stringify(journal, null, 2) + '\n', 'utf-8');
|
||||
return file;
|
||||
}
|
||||
|
||||
/**
|
||||
* Record the artifacts an injection just wrote. Replaces any previous record:
|
||||
* callers heal first (see healInjectJournal), so nothing survivable is lost.
|
||||
*/
|
||||
export function recordInjection(cwd = process.cwd(), { framework, port, artifacts = [] } = {}) {
|
||||
if (!artifacts.length) {
|
||||
clearInjectJournal(cwd);
|
||||
return null;
|
||||
}
|
||||
return writeInjectJournal(cwd, {
|
||||
version: INJECT_JOURNAL_VERSION,
|
||||
appRoot: path.resolve(cwd),
|
||||
framework: framework || null,
|
||||
port: Number.isFinite(Number(port)) ? Number(port) : null,
|
||||
pid: process.pid,
|
||||
recordedAt: new Date().toISOString(),
|
||||
artifacts,
|
||||
});
|
||||
}
|
||||
|
||||
function normalizeRel(cwd, rel) {
|
||||
return path.resolve(cwd, String(rel || '')).split(path.sep).join('/');
|
||||
}
|
||||
|
||||
function readIfPresent(abs) {
|
||||
try {
|
||||
return fs.readFileSync(abs, 'utf-8');
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function pruneEmptyDirs(dir, stopDir) {
|
||||
let current = path.resolve(dir);
|
||||
const stop = path.resolve(stopDir);
|
||||
while (current !== stop && current.startsWith(stop + path.sep)) {
|
||||
try {
|
||||
if (fs.readdirSync(current).length > 0) return;
|
||||
fs.rmdirSync(current);
|
||||
} catch {
|
||||
return;
|
||||
}
|
||||
current = path.dirname(current);
|
||||
}
|
||||
}
|
||||
|
||||
function insideProject(cwd, abs) {
|
||||
const rel = path.relative(path.resolve(cwd), path.resolve(abs));
|
||||
return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
|
||||
}
|
||||
|
||||
function healArtifact(cwd, artifact, undoers) {
|
||||
const abs = path.resolve(cwd, artifact.path);
|
||||
// The journal is a project-local file, i.e. attacker-writable input in a
|
||||
// cloned repo. Never touch anything outside the project tree, whatever the
|
||||
// journal claims to own.
|
||||
if (!insideProject(cwd, abs)) return { path: artifact.path, action: 'refused_outside_project' };
|
||||
const content = readIfPresent(abs);
|
||||
if (content === null) return { path: artifact.path, action: 'absent' };
|
||||
|
||||
if (artifact.kind === 'created') {
|
||||
// Only reclaim a generated file that still carries our marker; a created
|
||||
// artifact with no marker at all is unverifiable and stays untouched.
|
||||
if (!artifact.marker || !content.includes(artifact.marker)) {
|
||||
return { path: artifact.path, action: 'disowned' };
|
||||
}
|
||||
try { fs.rmSync(abs, { force: true }); } catch { return null; }
|
||||
if (artifact.pruneTo !== undefined) {
|
||||
const pruneRoot = path.resolve(cwd, artifact.pruneTo || '.');
|
||||
if (insideProject(cwd, pruneRoot) || pruneRoot === path.resolve(cwd)) {
|
||||
pruneEmptyDirs(path.dirname(abs), pruneRoot);
|
||||
}
|
||||
}
|
||||
return { path: artifact.path, action: 'removed' };
|
||||
}
|
||||
|
||||
if (artifact.kind === 'patched') {
|
||||
const markers = Array.isArray(artifact.markers) ? artifact.markers : [];
|
||||
// No marker left means the patch is already gone; never run an undo over
|
||||
// a file we no longer recognize (the undoers normalize whitespace).
|
||||
if (markers.length && !markers.some((marker) => content.includes(marker))) {
|
||||
return { path: artifact.path, action: 'disowned' };
|
||||
}
|
||||
const undo = undoers[artifact.patch];
|
||||
if (typeof undo !== 'function') return null;
|
||||
const next = undo(content);
|
||||
if (next === content) return { path: artifact.path, action: 'disowned' };
|
||||
try { fs.writeFileSync(abs, next, 'utf-8'); } catch { return null; }
|
||||
return { path: artifact.path, action: 'unpatched' };
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Reconcile the journal against the tree.
|
||||
*
|
||||
* `keep` is the set of paths the current operation legitimately owns — the
|
||||
* artifacts an inject is about to (re)write. Everything else in the journal is
|
||||
* an orphan of a session that is gone, and gets healed. This keeps a repeat
|
||||
* inject byte-idempotent: the artifacts it is about to rewrite are kept, not
|
||||
* torn down and rebuilt.
|
||||
*
|
||||
* Returns `{ healed, kept }`. `healed` lists only artifacts whose file was
|
||||
* actually changed or removed, so callers can stay silent when nothing was
|
||||
* orphaned. Idempotent: a second call finds an empty journal.
|
||||
*/
|
||||
export function healInjectJournal(cwd = process.cwd(), { keep = [], undoers = PATCH_UNDOERS } = {}) {
|
||||
const journal = readInjectJournal(cwd);
|
||||
if (!journal) return { healed: [], kept: [] };
|
||||
|
||||
const keepSet = new Set(keep.map((rel) => normalizeRel(cwd, rel)));
|
||||
const healed = [];
|
||||
const kept = [];
|
||||
|
||||
for (const artifact of journal.artifacts) {
|
||||
if (!artifact || typeof artifact.path !== 'string') continue;
|
||||
if (keepSet.has(normalizeRel(cwd, artifact.path))) {
|
||||
kept.push(artifact);
|
||||
continue;
|
||||
}
|
||||
const outcome = healArtifact(cwd, artifact, undoers);
|
||||
if (outcome && (outcome.action === 'removed' || outcome.action === 'unpatched')) {
|
||||
healed.push(outcome);
|
||||
}
|
||||
}
|
||||
|
||||
if (kept.length) {
|
||||
writeInjectJournal(cwd, { ...journal, artifacts: kept });
|
||||
} else {
|
||||
clearInjectJournal(cwd);
|
||||
}
|
||||
|
||||
return { healed, kept };
|
||||
}
|
||||
@@ -0,0 +1,49 @@
|
||||
/**
|
||||
* Next.js registry entry.
|
||||
*
|
||||
* Next takes the generic tag strategy: the App Router's root layout renders
|
||||
* `<html>…<body>` in JSX, so the marker-wrapped script block goes in there
|
||||
* verbatim. Nothing about injection differs from a plain Vite app, which is
|
||||
* why live-inject.mjs never had a Next branch. The entry exists so the
|
||||
* registry can name what it is looking at.
|
||||
*/
|
||||
|
||||
import { fileExists, findConfigFile, hasAnyDependency } from './detect-utils.mjs';
|
||||
|
||||
const NEXT_CONFIG_RE = /^next\.config\.(?:js|mjs|cjs|ts|mts|cts)$/;
|
||||
|
||||
const ROUTER_ENTRY_CANDIDATES = [
|
||||
'app/layout.tsx', 'app/layout.jsx', 'app/layout.ts', 'app/layout.js',
|
||||
'src/app/layout.tsx', 'src/app/layout.jsx', 'src/app/layout.ts', 'src/app/layout.js',
|
||||
'pages/_app.tsx', 'pages/_app.jsx', 'pages/_app.ts', 'pages/_app.js',
|
||||
'pages/_document.tsx', 'pages/_document.jsx',
|
||||
'src/pages/_app.tsx', 'src/pages/_app.jsx',
|
||||
];
|
||||
|
||||
export function detectNextProject(cwd = process.cwd()) {
|
||||
const configFile = findConfigFile(cwd, NEXT_CONFIG_RE);
|
||||
if (configFile) return { configFile, via: 'config' };
|
||||
if (hasAnyDependency(cwd, ['next'])) return { configFile: null, via: 'package' };
|
||||
// Next's file conventions are distinctive enough to stand alone: a root
|
||||
// `app/layout.*` or `pages/_app.*` is not a shape other bundlers produce.
|
||||
const entry = ROUTER_ENTRY_CANDIDATES.find((rel) => fileExists(cwd, rel));
|
||||
if (entry) return { configFile: null, via: 'router-entry', entry };
|
||||
return null;
|
||||
}
|
||||
|
||||
export const nextjs = {
|
||||
name: 'nextjs',
|
||||
|
||||
detect(cwd) {
|
||||
return detectNextProject(cwd);
|
||||
},
|
||||
|
||||
inject: { kind: 'tag' },
|
||||
|
||||
source: {
|
||||
extensions: ['.tsx', '.jsx'],
|
||||
preview: 'source',
|
||||
styleMode: 'scoped',
|
||||
commentSyntax: 'jsx',
|
||||
},
|
||||
};
|
||||
@@ -0,0 +1,161 @@
|
||||
/**
|
||||
* Nuxt registry entry, and the Nuxt adapter itself.
|
||||
*
|
||||
* A script element placed in app.vue is compiled as Vue-rendered DOM and is
|
||||
* not executed. Nuxt instead auto-discovers client plugins. Keep the adapter
|
||||
* generated, dev-only, and outside user-authored source: Live creates one
|
||||
* marked .client.ts plugin on start and removes it on stop.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { buildLiveScriptSrc } from './script-src.mjs';
|
||||
import { findConfigFile } from './detect-utils.mjs';
|
||||
|
||||
export const NUXT_PLUGIN_MARKER = 'impeccable-live-nuxt-plugin';
|
||||
export const NUXT_PLUGIN_NAME = 'impeccable-live.client.ts';
|
||||
|
||||
const NUXT_CONFIG_RE = /^nuxt\.config\.(?:js|mjs|cjs|ts|mts|cts)$/;
|
||||
|
||||
export function detectNuxtProject(cwd = process.cwd()) {
|
||||
const configFile = findConfigFile(cwd, NUXT_CONFIG_RE);
|
||||
if (!configFile) return null;
|
||||
|
||||
const config = fs.readFileSync(path.join(cwd, configFile), 'utf-8');
|
||||
const literalSrcDir = config.match(/\bsrcDir\s*:\s*(['"])([^'"]+)\1/);
|
||||
let appDir = '';
|
||||
if (literalSrcDir) {
|
||||
const candidate = literalSrcDir[2]
|
||||
.replace(/\\/g, '/')
|
||||
.replace(/^\.\//, '')
|
||||
.replace(/\/+$/, '');
|
||||
const normalized = path.posix.normalize(candidate);
|
||||
if (normalized !== '..' && !normalized.startsWith('../') && !path.isAbsolute(normalized)) {
|
||||
appDir = normalized === '.' ? '' : normalized;
|
||||
}
|
||||
} else if (
|
||||
fs.existsSync(path.join(cwd, 'app', 'app.vue'))
|
||||
|| fs.existsSync(path.join(cwd, 'app', 'pages'))
|
||||
) {
|
||||
appDir = 'app';
|
||||
}
|
||||
|
||||
const pluginFile = [appDir, 'plugins', NUXT_PLUGIN_NAME].filter(Boolean).join('/');
|
||||
return { configFile, appDir, pluginFile };
|
||||
}
|
||||
|
||||
export function buildNuxtPlugin(port, token) {
|
||||
return `/* ${NUXT_PLUGIN_MARKER} */
|
||||
const liveSrc = '${buildLiveScriptSrc(port, token)}';
|
||||
const liveSelector = 'script[data-impeccable-live-nuxt]';
|
||||
|
||||
export default defineNuxtPlugin(() => {
|
||||
if (!import.meta.dev || typeof document === 'undefined') return;
|
||||
|
||||
const expectedSrc = new URL(liveSrc, window.location.href).href;
|
||||
let script = document.querySelector(liveSelector);
|
||||
if (script?.src === expectedSrc) return;
|
||||
script?.remove();
|
||||
|
||||
script = document.createElement('script');
|
||||
script.src = liveSrc;
|
||||
script.async = true;
|
||||
script.dataset.impeccableLiveNuxt = '';
|
||||
document.head.appendChild(script);
|
||||
|
||||
import.meta.hot?.dispose(() => {
|
||||
if (script?.isConnected) script.remove();
|
||||
});
|
||||
});
|
||||
/* /${NUXT_PLUGIN_MARKER} */
|
||||
`;
|
||||
}
|
||||
|
||||
export function applyNuxtLiveAdapter({ cwd = process.cwd(), port, token, project = detectNuxtProject(cwd) }) {
|
||||
if (!project) return { error: 'nuxt_not_detected' };
|
||||
const absFile = path.join(cwd, project.pluginFile);
|
||||
const existing = fs.existsSync(absFile) ? fs.readFileSync(absFile, 'utf-8') : null;
|
||||
if (existing !== null && !existing.includes(NUXT_PLUGIN_MARKER)) {
|
||||
return {
|
||||
file: project.pluginFile,
|
||||
error: 'nuxt_plugin_conflict',
|
||||
hint: `${project.pluginFile} already exists and is not managed by Impeccable Live`,
|
||||
};
|
||||
}
|
||||
|
||||
const content = buildNuxtPlugin(port, token);
|
||||
fs.mkdirSync(path.dirname(absFile), { recursive: true });
|
||||
if (content !== existing) fs.writeFileSync(absFile, content, 'utf-8');
|
||||
return {
|
||||
file: project.pluginFile,
|
||||
inserted: true,
|
||||
changed: content !== existing,
|
||||
devOnly: true,
|
||||
};
|
||||
}
|
||||
|
||||
export function removeNuxtLiveAdapter({ cwd = process.cwd(), project = detectNuxtProject(cwd) }) {
|
||||
if (!project) return { error: 'nuxt_not_detected' };
|
||||
const absFile = path.join(cwd, project.pluginFile);
|
||||
if (!fs.existsSync(absFile)) {
|
||||
return { file: project.pluginFile, removed: false, note: 'no adapter present' };
|
||||
}
|
||||
const content = fs.readFileSync(absFile, 'utf-8');
|
||||
if (!content.includes(NUXT_PLUGIN_MARKER)) {
|
||||
return {
|
||||
file: project.pluginFile,
|
||||
removed: false,
|
||||
error: 'nuxt_plugin_conflict',
|
||||
hint: `${project.pluginFile} is not managed by Impeccable Live`,
|
||||
};
|
||||
}
|
||||
fs.unlinkSync(absFile);
|
||||
const pluginDir = path.dirname(absFile);
|
||||
if (fs.readdirSync(pluginDir).length === 0) fs.rmdirSync(pluginDir);
|
||||
return { file: project.pluginFile, removed: true };
|
||||
}
|
||||
|
||||
export const nuxt = {
|
||||
name: 'nuxt',
|
||||
|
||||
detect(cwd) {
|
||||
return detectNuxtProject(cwd);
|
||||
},
|
||||
|
||||
inject: {
|
||||
kind: 'adapter',
|
||||
|
||||
apply({ cwd, port, token, project }) {
|
||||
return applyNuxtLiveAdapter({ cwd, port, token, project });
|
||||
},
|
||||
|
||||
remove({ cwd, project }) {
|
||||
return removeNuxtLiveAdapter({ cwd, project });
|
||||
},
|
||||
|
||||
// The plugin path depends on the resolved srcDir, so it cannot live in the
|
||||
// static ignore list the way the SvelteKit paths do.
|
||||
ignorePatterns(project) {
|
||||
return project?.pluginFile ? [project.pluginFile] : [];
|
||||
},
|
||||
|
||||
artifacts({ project }) {
|
||||
if (!project?.pluginFile) return [];
|
||||
return [{
|
||||
kind: 'created',
|
||||
path: project.pluginFile,
|
||||
marker: NUXT_PLUGIN_MARKER,
|
||||
// Mirrors removeNuxtLiveAdapter: the generated `plugins/` directory
|
||||
// goes when it empties, its parent stays.
|
||||
pruneTo: path.posix.dirname(path.posix.dirname(project.pluginFile)),
|
||||
}];
|
||||
},
|
||||
},
|
||||
|
||||
source: {
|
||||
extensions: ['.vue'],
|
||||
preview: 'source',
|
||||
styleMode: 'scoped',
|
||||
commentSyntax: 'html',
|
||||
},
|
||||
};
|
||||
@@ -0,0 +1,17 @@
|
||||
/**
|
||||
* The one place that builds the `/live.js` URL the browser loads.
|
||||
*
|
||||
* Every injection path needs it (the generic script tag, the Nuxt client
|
||||
* plugin, the SvelteKit root component, the TanStack mount component), and a
|
||||
* separate module keeps that shared leaf free of import cycles: the framework
|
||||
* entries import it, and nothing here imports a framework entry.
|
||||
*/
|
||||
|
||||
/**
|
||||
* When a token is supplied it rides as a `?token=...` query param so the
|
||||
* server's token-gated /live.js handler authorizes the fetch.
|
||||
*/
|
||||
export function buildLiveScriptSrc(port, token) {
|
||||
const base = 'http://localhost:' + port + '/live.js';
|
||||
return token ? base + '?token=' + encodeURIComponent(token) : base;
|
||||
}
|
||||
@@ -0,0 +1,26 @@
|
||||
/**
|
||||
* Static HTML registry entry: the terminal fallback.
|
||||
*
|
||||
* Hand-written pages, a multi-page site emitted by a generator, anything with
|
||||
* no bundler config at the app root. `detect` always matches, so this entry
|
||||
* must stay last in FRAMEWORKS. Its behavior is the plain tag strategy, which
|
||||
* is what live-inject.mjs did for every unrecognized project before the
|
||||
* registry existed.
|
||||
*/
|
||||
|
||||
export const staticHtml = {
|
||||
name: 'static-html',
|
||||
|
||||
detect() {
|
||||
return { via: 'fallback' };
|
||||
},
|
||||
|
||||
inject: { kind: 'tag' },
|
||||
|
||||
source: {
|
||||
extensions: ['.html', '.htm'],
|
||||
preview: 'source',
|
||||
styleMode: 'scoped',
|
||||
commentSyntax: 'html',
|
||||
},
|
||||
};
|
||||
@@ -0,0 +1,71 @@
|
||||
/**
|
||||
* SvelteKit registry entry.
|
||||
*
|
||||
* Detection and the apply/remove pair are the existing adapter's
|
||||
* (`../sveltekit-adapter.mjs`); this file only declares them to the registry
|
||||
* and names the artifacts the journal has to be able to heal.
|
||||
*/
|
||||
|
||||
import {
|
||||
SVELTE_LAYOUT_MARKER_OPEN,
|
||||
SVELTE_LIVE_ROOT_COMPONENT,
|
||||
applySvelteKitLiveAdapter,
|
||||
detectSvelteKitProject,
|
||||
removeSvelteKitLiveAdapter,
|
||||
unpatchSvelteLayout,
|
||||
} from '../sveltekit-adapter.mjs';
|
||||
|
||||
export const sveltekit = {
|
||||
name: 'sveltekit',
|
||||
|
||||
detect(cwd, config) {
|
||||
return detectSvelteKitProject(cwd, config);
|
||||
},
|
||||
|
||||
inject: {
|
||||
kind: 'adapter',
|
||||
|
||||
apply({ cwd, port, token, config }) {
|
||||
return applySvelteKitLiveAdapter({ cwd, port, token, config });
|
||||
},
|
||||
|
||||
remove({ cwd, config }) {
|
||||
return removeSvelteKitLiveAdapter({ cwd, config });
|
||||
},
|
||||
|
||||
// The generated root component and the `src/lib/impeccable/` runtime paths
|
||||
// are already in the static LIVE_IGNORE_PATTERNS list, so nothing extra.
|
||||
ignorePatterns() {
|
||||
return [];
|
||||
},
|
||||
|
||||
artifacts({ project }) {
|
||||
return [
|
||||
{
|
||||
kind: 'created',
|
||||
path: SVELTE_LIVE_ROOT_COMPONENT,
|
||||
marker: 'impeccable-live-root',
|
||||
pruneTo: 'src',
|
||||
},
|
||||
{
|
||||
kind: 'patched',
|
||||
path: project?.layoutFile || 'src/routes/+layout.svelte',
|
||||
patch: 'sveltekit-layout',
|
||||
markers: [SVELTE_LAYOUT_MARKER_OPEN],
|
||||
},
|
||||
];
|
||||
},
|
||||
|
||||
unpatch: {
|
||||
'sveltekit-layout': unpatchSvelteLayout,
|
||||
},
|
||||
},
|
||||
|
||||
source: {
|
||||
extensions: ['.svelte'],
|
||||
// Svelte resets component-local state on markup HMR updates, so variants
|
||||
// are mounted from generated components rather than written into the route.
|
||||
preview: 'component',
|
||||
commentSyntax: 'html',
|
||||
},
|
||||
};
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user