mirror of
https://github.com/pbakaus/impeccable.git
synced 2026-09-11 21:57:14 +03:00
Preserve experimental Live app-server workstream
Snapshot the current app-server implementation, shared Live optimizations, generated harness output, and in-progress site work before restoring polling as the primary runtime path. Prepared with Codex assistance under maintainer direction.
This commit is contained in:
Paul Bakaus
@@ -13,48 +13,48 @@ Approach every design task as the design lead at a small studio known for giving
|
||||
|
||||
## Setup
|
||||
|
||||
1. Run `node .github/skills/impeccable/scripts/context.mjs` once per session (if the runtime shows this skill's loaded base directory, run `node <skill-base-dir>/scripts/context.mjs`; keep cwd at the user's project). It prints the project's PRODUCT.md and DESIGN.md when they exist; follow what it prints, including any `UPDATE_AVAILABLE` directive (ask once, never block). If it reports `NO_PRODUCT_MD`: for `init`, `teach`, `craft`, `shape`, or wording that clearly maps to a from-scratch build flow, divert into `reference/init.md` first, **unless no user can respond** (a one-shot or automated run, or the user said not to ask): then write your own one-paragraph understanding of the product, audience, and the page's job from the brief and continue. For scoped evaluate/refine/fix requests against existing code, never divert into init; the existing code is the context.
|
||||
2. If the user invoked a sub-command (`audit`, `polish`, `live`, ...), read **`reference/<command>.md`** (the `.native` variant from the Commands table when the platform is `ios`/`android`/`adaptive`) and follow it. `craft` and `shape` requests follow the build path: the new-work gate below owns the flow, and on unattended runs its checkpoints resolve without pausing.
|
||||
1. Run `node .github/skills/impeccable/scripts/context.mjs` once per session (if the runtime shows this skill's loaded base directory, run `node <skill-base-dir>/scripts/context.mjs`; keep cwd at the user's project). It prints the project's context and its directives; follow what it prints. Once its output is in the conversation, never rerun it on a later turn.
|
||||
2. `craft` and `shape` are build-path exceptions: the new-work gate below owns their flow, and on unattended runs its checkpoints resolve without pausing. For any other invoked sub-command (`audit`, `polish`, `live`, ...), immediately read **`reference/<command>.md`** after `context.mjs` (the `.native` variant from the Commands table when the platform is `ios`/`android`/`adaptive`) and follow it. This read is a hard gate: do not inspect the target, run command-specific scripts, or edit files until the reference is loaded.
|
||||
3. Read at least one project file (CSS / tokens / theme / a representative component) to learn what world you're in. If PRODUCT.md's `## Platform` is `ios` or `android`, also read `reference/<platform>.md` (`adaptive` reads both).
|
||||
|
||||
## How to design
|
||||
|
||||
**The brief wins.** Where the brief pins down a direction (a named aesthetic, an era, a place, a material, a specific font or palette), follow it exactly, including when it asks for a look this skill warns is saturated. Redirecting a pinned direction toward your own taste is a failure, not a save.
|
||||
|
||||
**Existing worlds are sacred.** Most of impeccable's work happens inside a site or app that already exists. When the surface has a committed design system (real tokens, deliberately chosen faces, a palette the brand owns), work inside that world: extend it, sharpen it, leave it unmistakably the same brand, and never degrade a working page's performance. Inventing parallel colors, fonts, or styles on an existing surface is a defect, not creativity.
|
||||
**Existing worlds are sacred.** Most of impeccable's work happens inside a site or app that already exists. When the surface has a committed design system (real tokens, deliberately chosen faces, a palette the brand owns), work inside that world: extend it, sharpen it, leave it unmistakably the same brand, and never degrade a working page's performance. Inventing parallel colors, fonts, or styles on an existing surface is a defect, not creativity. A scoped refinement keeps the named scope's content and media footprint unless the brief explicitly changes them; build the added emphasis by recomposing what is already there through hierarchy, proportion, rhythm, and the system's own motifs.
|
||||
|
||||
**New identity work reads the playbook first.** When nothing committed exists (greenfield, or a codebase with no real tokens or chosen faces), or the user asks for a redesign that discards the current look, you MUST read [reference/new-work.md](reference/new-work.md) before making any design decision. Not optional, not skippable under time pressure: producing new identity without it yields the generic default this skill exists to prevent. A redesign is new work; derive the concept from the subject and the brief, not from the incumbent page's structure or styling. `context.mjs` prints this directive when it detects the situation. Scoped fixes inside an existing world don't need the playbook; the craft floor below governs them.
|
||||
**New identity work reads the playbook first.** When nothing committed exists (greenfield, or a codebase with no real tokens or chosen faces), or the user asks for a redesign that discards the current look, you MUST read [reference/new-work.md](reference/new-work.md) before making any design decision. Not optional, not skippable under time pressure: producing new identity without it yields the generic default this skill exists to prevent. A redesign is new work; read the incumbent as evidence, not as a template or an obstacle: where it carries a deliberate, ownable visual idea, preserve that lineage and intensify it instead of replacing it with contemporary polish. `context.mjs` prints this directive when it detects the situation. Scoped fixes inside an existing world don't need the playbook; the craft floor below governs them.
|
||||
|
||||
## Craft floor
|
||||
|
||||
Build to this floor without announcing it. The design detector (the project hook, `node .github/skills/impeccable/scripts/detect.mjs --json <file>`, or `audit`) verifies most of it mechanically; any finding it raises is a defect to fix, not a suggestion.
|
||||
|
||||
- Contrast: body text ≥4.5:1 against its background (placeholders too); large text ≥3:1. Gray text on a colored background looks washed out: use a darker shade of the background's own hue, or a transparency of the text color.
|
||||
- Shadows describe real light: an offset and a soft blur. A zero-offset colored halo is decoration announcing itself.
|
||||
- Spacing has rhythm: generous separations, tight groupings; cramped padding reads as broken. Watch CSS specificity: classes that cancel each other's padding (a `.section` fighting a `.cta`) silently collapse section spacing. Verify computed spacing, not intended spacing.
|
||||
- Type: body line length 65-75ch; display clamp() max ≤6rem; letter-spacing ≥-0.04em; `text-wrap: balance` on headings; modular scale ≥1.25 between steps; light-on-dark adds 0.05-0.1 line-height. Pair faces on a contrast axis, never two similar-but-not-identical ones; one family with committed weight contrast beats a timid pair. Test headings at every breakpoint; overflow means reduce the clamp or rewrite the copy.
|
||||
- Structural devices (numbering, eyebrows, dividers) must encode something true about the content; the same device repeated above every section regardless of content is scaffolding.
|
||||
- Motion is part of the build: one orchestrated moment beats scattered effects; ease-out exponential curves; `prefers-reduced-motion` alternatives always; reveals enhance an already-visible default (content gated on a class-triggered transition ships blank in hidden tabs and headless renderers). Responsive down to mobile and visible keyboard focus are part of the floor.
|
||||
- Ship real content (no placeholders, dead links, or fake controls), cover the interaction states people will actually hit (hover, focus, disabled, loading, error, empty), and respect the project's build pipeline: edit source, never write into build output directly.
|
||||
- Before finishing, re-read the brief: every requirement it names must exist on the page, findable in seconds. A beautiful page missing an asked-for feature is unfinished.
|
||||
- Copy is design material: write from the user's side of the screen, active voice, a control says exactly what happens, errors explain what went wrong and how to fix it. Specific beats clever.
|
||||
|
||||
## Registers
|
||||
## Modes
|
||||
|
||||
Name the visitor's mode before designing; the page's grammar follows from it, and most ruined pages are one mode wearing another mode's grammar. **The mode belongs to the surface, not the subject**: a landing page for a dense technical tool is still Persuade, with Persuade's full permission to be striking; a docs page for a fashion house is still Read. Deciding a page can be plain because its subject is workmanlike is the same category error in reverse. The brief and the surface decide the mode; PRODUCT.md's `register` field survives only as a family hint (`brand` covers Persuade and Experience, `product` covers Operate and Read). Depth beyond the paragraphs below: [reference/new-work.md](reference/new-work.md) when inventing identity, [reference/operate.md](reference/operate.md) for substantial Operate and Read work.
|
||||
|
||||
**Persuade** (landing pages, marketing, campaigns; design IS the product). The deliverable is an impression that stops the scroll, earns the click, converts. Spans every genre (tech, luxury, consumer); don't collapse them into one look. Briefs that imply imagery must ship real, verified imagery; a colored rectangle where a photo belongs reads as incomplete. New Persuade surfaces take their typeface procedure and reject list from [reference/new-work.md](reference/new-work.md).
|
||||
**Persuade** (the surface exists to win someone over; design IS the product). The deliverable is an impression that stops the scroll, earns the click, converts. Spans every genre; don't collapse them into one look. On new surfaces, briefs that imply imagery must ship real, verified imagery; a colored rectangle where a photo belongs reads as incomplete. New Persuade surfaces take their typeface procedure and reject list from [reference/new-work.md](reference/new-work.md).
|
||||
|
||||
**Operate** (app UI, dashboards, admin, tools; design SERVES the task). A person getting something done: density, scanability, and consistency outrank expressiveness. These surfaces earn trust by feeling native to their platform: system font stacks and workhorse UI faces are legitimate and often correct here (the Persuade reject list does not apply). The brand lives in the details: focus states, empty states, microcopy, one owned accent. The usage scene is part of the spec: an interface read outdoors, in motion, or at a glance must survive its real ambient light, and the theme follows the scene, not the category's habit.
|
||||
**Operate** (the surface is a tool someone works in; design SERVES the task). A person getting something done: scanability and consistency outrank expressiveness. These surfaces earn trust by feeling native to their platform: system font stacks and workhorse UI faces are legitimate and often correct here (the Persuade reject list does not apply). The brand lives in the details: focus states, empty states, microcopy, one owned accent. The usage scene is part of the spec: an interface read outdoors, in motion, or at a glance must survive its real ambient light, and the theme follows the scene, not the category's habit.
|
||||
|
||||
**Read** (documentation, guides, editorial, long-form). The deliverable is comprehension: typographic rigor, a navigable structure the reader can hold in their head, hierarchy built for scanning, chrome that stays out of the way. Density follows the reader's task, not atmosphere, and nothing stands between the reader and the answer. The brand lives in type, spacing, and small accents.
|
||||
**Read** (the surface exists to be understood; long-form, reference, guidance). The deliverable is comprehension, and comprehension is earned twice: a structure the reader can hold in their head with nothing standing between them and the answer, and a reading experience good enough to stay in, through typographic quality and whatever visual or interactive support genuinely helps the reader follow. The brand lives in type, spacing, and small accents.
|
||||
|
||||
**Experience** (an album, a portfolio, a publication, a body of work). The page IS the work: the artifact leads, the interface recedes, and the visitor meets the work itself in the first viewport at every screen size. Boldness here means trusting the work.
|
||||
**Experience** (the surface presents a body of work; the page IS the work). The artifact leads, the interface recedes, and the visitor meets the work itself in the first viewport at every screen size. Boldness here means trusting the work.
|
||||
|
||||
## Craft floor
|
||||
|
||||
Build to this floor without announcing it. The design detector (the project hook, `node .github/skills/impeccable/scripts/detect.mjs --json <file>`, or `audit`) verifies most of it mechanically; resolve every finding before finalizing. Fix real defects, but use context judgment rather than distorting intentional design to appease a false positive. Classify any intentional exception explicitly and use the hook system's narrowest appropriate waiver when it must persist.
|
||||
|
||||
- Contrast: body text ≥4.5:1 against its background (placeholders too); large text ≥3:1. Gray text on a colored background looks washed out: use a darker shade of the background's own hue, or a transparency of the text color.
|
||||
- Shadows describe real light: an offset and a soft blur. A zero-offset colored halo is decoration announcing itself.
|
||||
- Spacing has rhythm: generous separations, tight groupings; cramped padding reads as broken; the space above a heading exceeds the space below it. Verify computed spacing, not intended spacing.
|
||||
- Type: body line length 65-75ch; display clamp() max ≤6rem; letter-spacing ≥-0.04em; `text-wrap: balance` on headings; modular scale ≥1.25 between steps; light-on-dark adds 0.05-0.1 line-height. Pair faces on a contrast axis, never two similar-but-not-identical ones; one family with committed weight contrast beats a timid pair. Test headings at every breakpoint; overflow means reduce the clamp or rewrite the copy.
|
||||
- Motion is part of the build: one orchestrated moment beats scattered effects; ease-out exponential curves; reveals enhance an already-visible default (content gated on a class-triggered transition ships blank in hidden tabs and headless renderers). Responsive down to mobile and visible keyboard focus are part of the floor.
|
||||
- Ship real content (no placeholders, dead links, or fake controls) and cover the interaction states people will actually hit (hover, focus, disabled, loading, error, empty).
|
||||
- Copy is design material: name things the way the page's own people speak, make every control say what it does, and make every error say what happened and what to do next.
|
||||
- Before finishing, re-read the brief: every requirement it names must exist on the page, findable in seconds. A beautiful page missing an asked-for feature is unfinished.
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Category | Description | Reference |
|
||||
|---|---|---|---|
|
||||
| `craft [feature]` | Build | Deprecated alias: the standard build flow with attended checkpoints | [reference/new-work.md](reference/new-work.md) |
|
||||
| `craft [feature]` | Build | The standard build flow with attended checkpoints | [reference/new-work.md](reference/new-work.md) |
|
||||
| `shape [feature]` | Build | Plan UX/UI before writing code | [reference/shape.md](reference/shape.md) |
|
||||
| `init` | Build | Set up project context: PRODUCT.md, DESIGN.md, live config, next steps | [reference/init.md](reference/init.md) |
|
||||
| `document` | Build | Generate DESIGN.md from existing project code | [reference/document.md](reference/document.md) |
|
||||
@@ -78,7 +78,7 @@ Name the visitor's mode before designing; the page's grammar follows from it, an
|
||||
| `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) |
|
||||
| `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) |
|
||||
|
||||
Routing: **no argument** → read [reference/routing.md](reference/routing.md) and present the context-aware menu (never auto-run a command). **First word matches a command** (or `pin` / `unpin` / `hooks`) → load its reference (native variant on native platforms) and follow it; everything after the command name is the target. **Intent clearly maps to one command** ("fix the spacing" → `layout`, "rewrite this error" → `clarify`) → same; if two fit, ask once. **Otherwise** → general design invocation: apply Setup and this file's guidance; builds flow through the new-work gate above, whose playbook carries the direction checkpoint and the finishing pass. `teach` is a deprecated alias for `init`, and `craft` is a deprecated alias for the standard build flow with attended checkpoints (its old reference redirects). If setup diverted into `init` for a build request, finish init, refresh context, then resume.
|
||||
Routing: **no argument** → read [reference/routing.md](reference/routing.md) and present the context-aware menu (never auto-run a command). **First word matches a command** (or `pin` / `unpin` / `hooks`) → load its reference (native variant on native platforms) and follow it; everything after the command name is the target. **Intent clearly maps to one command** ("fix the spacing" → `layout`, "rewrite this error" → `clarify`) → same; if two fit, ask once. **Otherwise** → general design invocation: apply Setup and this file's guidance; builds flow through the new-work gate above, whose playbook carries the direction checkpoint and the finishing pass. `teach` routes to `init`, and `craft` routes to the standard build flow with attended checkpoints. If setup diverted into `init` for a build request, finish init, refresh context, then resume.
|
||||
|
||||
**Pin / Unpin:** `node .github/skills/impeccable/scripts/pin.mjs <pin|unpin> <command>` creates or removes a standalone `/<command>` shortcut. Report the script's result concisely; relay stderr verbatim on error.
|
||||
|
||||
|
||||
@@ -1,120 +1,31 @@
|
||||
When asked for "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the opposite of bold. Reject them first, then increase visual impact by making the existing design language more decisive, specific, and committed.
|
||||
> **Additional context needed**: which section is the target, and what must stay untouched.
|
||||
|
||||
---
|
||||
"Bolder" is an amplification request, and almost always it is scoped to something that already exists. The surrounding page, its system, and its conventions are the given. Your job is to raise one part to the conviction the rest already implies, without rebuilding anything the brief did not name. The reflex answer, reaching for more effects, is the opposite of bold; reject it first.
|
||||
|
||||
## Register
|
||||
## Scope is sovereign
|
||||
|
||||
Persuade + Experience: "bolder" means distinctive. Express a stronger point of view through hierarchy, pacing, proportion, copy, evidence, and one committed visual idea.
|
||||
"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, stop and ask the user directly to clarify what you cannot infer. before expanding it, naming the exact addition and the job it would do.
|
||||
|
||||
Operate + Read: "bolder" rarely means theatrics; those undermine trust. It means stronger hierarchy, clearer weight contrast, sharper information density, and more decisive prioritization. The amplification is in clarity, not drama.
|
||||
## Why it reads flat
|
||||
|
||||
---
|
||||
A section usually reads flat for reasons its neighbors have already solved. Look at what the rest of the page does that this section does not: the display type at full strength, the structural devices that carry meaning, the signature motif, the density and pacing, the specificity of the copy. A flat section is typically one that quietly opts out of the system's own strongest moves. The most reliable bolder pass brings the target up to the expressive level its neighbors already reach, in the system's own vocabulary rather than a new one.
|
||||
|
||||
## Assess Current State
|
||||
## The amplification
|
||||
|
||||
Analyze what makes the design feel too safe or boring:
|
||||
- **Amplify what the system already owns.** Reuse its motif and its type scale at full strength, turned up for this section rather than invented for it. The bolder version should look more like the same brand, not less.
|
||||
- **Let the content carry the weight.** Flat copy makes a flat design, and no amount of size fixes a generic claim. Make every word specific enough to earn its place, and let the section's real evidence do the work that a decorative addition would otherwise fake.
|
||||
- **Commit, then clarify.** Half-measures read as noise. Make the one decisive move completely, then quiet everything around it so the move is legible. If every element got louder, the section got flatter.
|
||||
- **Give it its own rhythm.** The target should read as a peak in the scroll, a shift in density or pace from what surrounds it, not simply more of the same.
|
||||
|
||||
1. **Identify weakness sources**:
|
||||
- **Generic choices**: The page could belong to any product in the category.
|
||||
- **Timid scale**: Everything is medium-sized with no clear lead.
|
||||
- **Low contrast**: Important and supporting elements have similar visual weight.
|
||||
- **Static**: The surface has no meaningful moment of emphasis.
|
||||
- **Predictable**: The composition follows a default pattern without a point of view.
|
||||
- **Flat hierarchy**: Nothing stands out or commands attention.
|
||||
## The skeleton test
|
||||
|
||||
2. **Understand the context**:
|
||||
- What is the brand personality?
|
||||
- What is the purpose of this surface?
|
||||
- Who is the audience?
|
||||
- What design system, tokens, components, and visual conventions already exist?
|
||||
Strip the copy out of your planned section and study the bare structure. Does the skeleton still say what this section is and why it matters, through hierarchy and the system's devices alone? If it only works once the words return, the boldness is in the text size, not the design. A placeholder for an image or artifact names a job, an anchor and a piece of evidence, not a cue to drop in a decorative photo; fill that job with whatever the subject actually has.
|
||||
|
||||
If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer.
|
||||
## Before you finish
|
||||
|
||||
**CRITICAL**: "Bolder" does not mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random noise.
|
||||
- Everything outside the named target is unchanged.
|
||||
- No new color, font, or system primitive appeared without being asked for.
|
||||
- The conventions the section carried, including anything that drives an action, still work the same way.
|
||||
- The section is unmistakably the same brand, only more sure of itself.
|
||||
|
||||
**WARNING - AI SLOP TRAP**: Review ALL the DON'T guidelines from the parent impeccable skill (already loaded in this context) before proceeding. Bold means distinctive, not "more effects."
|
||||
|
||||
## Design-System Lock
|
||||
|
||||
If the project has `DESIGN.md`, tokens, theme variables, or established component styles, treat that system as the boundary. Make the existing language stronger before adding new language.
|
||||
|
||||
Do not invent new colors, gradients, radii, shadows, fonts, decorative backgrounds, or effects just because the request says "bolder." A bolder pass should usually change emphasis, proportion, rhythm, density, contrast, copy, artifact specificity, and layout relationships while staying inside the documented system.
|
||||
|
||||
If the existing system is genuinely too limited to express the bolder direction, stop and ask the user before expanding it. Name the exact additions, the role each would play, and why the current system cannot do the job. If the user approves expansion, update the design system or tokens alongside the implementation.
|
||||
|
||||
## Plan Amplification
|
||||
|
||||
Create a strategy to increase impact while maintaining coherence:
|
||||
|
||||
- **Focal point**: Pick one thing the viewer should remember, then make the rest support it.
|
||||
- **System levers**: Identify which existing tokens, components, layout patterns, and copy structures can carry more weight.
|
||||
- **Risk budget**: Decide how far the surface can push while still feeling like the same product or brand.
|
||||
- **Hierarchy amplification**: Increase contrast between primary, secondary, and tertiary content instead of making every element louder.
|
||||
|
||||
**IMPORTANT**: Bold design must still be usable. Impact without function is just decoration.
|
||||
|
||||
## Amplify the Design
|
||||
|
||||
Systematically increase impact through intention, not a menu of effects:
|
||||
|
||||
### Typography Amplification
|
||||
- Strengthen the existing type hierarchy before changing typefaces.
|
||||
- Make important text meaningfully more dominant, and make supporting text quieter.
|
||||
- Use weight, measure, spacing, and line breaks to sharpen the point of view.
|
||||
- Add or replace fonts only after user-approved design-system expansion.
|
||||
|
||||
### Color Amplification
|
||||
- Use the existing palette more decisively before adding colors.
|
||||
- Shift the proportion, placement, and contrast of documented colors to clarify meaning.
|
||||
- Treat any new color, gradient, or tint ramp as a design-system expansion that requires user approval.
|
||||
- Keep color tied to hierarchy, state, or brand meaning; do not use it as surface decoration.
|
||||
|
||||
### Spatial Amplification
|
||||
- Change proportion, density, alignment, and sequencing so the composition has a stronger point of view.
|
||||
- Create clearer contrast between dense evidence and open breathing room.
|
||||
- Let layout express priority and narrative order before adding ornament.
|
||||
- Preserve responsive behavior and avoid text overflow at every breakpoint.
|
||||
|
||||
### Surface Amplification
|
||||
- Use existing surface, border, radius, and shadow rules more deliberately.
|
||||
- Remove timid half-measures: either give an element a clear role or simplify it.
|
||||
- Add texture, depth, illustration, or decorative treatments only when already established by the system or explicitly approved.
|
||||
- Make real product artifacts, imagery, data, or copy carry attention before reaching for effects.
|
||||
|
||||
### Motion & Animation
|
||||
- Design one meaningful moment of emphasis when motion genuinely supports the point.
|
||||
- Make interaction feedback feel more decisive without becoming distracting.
|
||||
- Keep transitions smooth and intentional.
|
||||
- **Bolder != scroll-fade-rise on every section.** That's the saturated AI default, the opposite of bold.
|
||||
|
||||
### Composition Boldness
|
||||
- Make the dominant idea unmistakable.
|
||||
- Use layout tension, sequencing, contrast, and restraint to create a stronger read.
|
||||
- Let the page's structure communicate priority before adding decorative layers.
|
||||
- If every element is louder, the composition is not bolder; it is flatter.
|
||||
|
||||
**NEVER**:
|
||||
- Add undocumented design-system primitives without user approval
|
||||
- Add effects randomly without purpose
|
||||
- Hide weak hierarchy behind decoration
|
||||
- Sacrifice readability for aesthetics
|
||||
- Make everything bold; contrast is the point
|
||||
- Ignore accessibility
|
||||
- Overwhelm with motion
|
||||
- Copy trendy aesthetics blindly
|
||||
|
||||
## Verify Quality
|
||||
|
||||
Ensure amplification maintains usability and coherence:
|
||||
|
||||
- **System-faithful**: Did the pass make the existing design language stronger before adding anything new?
|
||||
- **No undocumented drift**: Are new colors, gradients, shadows, radii, fonts, and effects either absent or explicitly approved and documented?
|
||||
- **NOT AI slop**: Does this look like every other AI-generated "bold" design? If yes, start over.
|
||||
- **Still functional**: Can users accomplish tasks without distraction?
|
||||
- **Coherent**: Does everything feel intentional and unified?
|
||||
- **Memorable**: Will users remember this experience for the intended reason?
|
||||
- **Performant and accessible**: Does the result stay fast, readable, responsive, and WCAG-conscious?
|
||||
|
||||
**The test**: If you showed this to someone and said "AI made this bolder," would they believe you immediately? If yes, you've failed. Bold means distinctive, not "more AI effects."
|
||||
|
||||
When the result feels right, hand off to `/impeccable polish` for the final pass.
|
||||
When the target holds its own without pulling the page apart, hand off to `/impeccable polish` for the final pass.
|
||||
|
||||
@@ -0,0 +1,32 @@
|
||||
# Live generation worker
|
||||
|
||||
You generate reviewable variants for an existing interface. The supervisor owns all filesystem writes, publication, cancellation, and recovery. Return only the requested structured output.
|
||||
|
||||
## Identity and quality
|
||||
|
||||
- Preserve the existing product identity by default: palette roles, available fonts, component roles, copy, semantics, accessibility, and public APIs.
|
||||
- Treat DESIGN.md as visual authority and PRODUCT.md as strategy/voice authority.
|
||||
- Define one shared identity lock and distinct design axes before authoring the first variant.
|
||||
- Make each variant independently shippable. Vary hierarchy, topology, typography, color commitment, density, or structural decomposition, not arbitrary decoration.
|
||||
- Preserve short labels as readable units and avoid unnecessary wrapping at the supplied viewport.
|
||||
- Prefer hierarchy, proportion, rhythm, and composition before adding nested chrome.
|
||||
- Silently reject overflow, awkward wrapping, accidental compression, weak alignment, inaccessible states, and off-brand component treatments.
|
||||
|
||||
## Authoring contract
|
||||
|
||||
- The selected root is a complete replacement with exactly one top-level element.
|
||||
- Preserve copy and dynamic relationships unless the user explicitly requests content changes.
|
||||
- Never emit `data-impeccable-*` wrappers inside variant markup.
|
||||
- Follow `event.scaffold.cssAuthoring` exactly. Fence every preview selector to its variant.
|
||||
- Do not write source or project files. Return only paths and content permitted by the current output schema.
|
||||
- Published variants are immutable. Never repeat or revise an earlier variant in a later phase.
|
||||
- The staged artifact identifies the exact selected page/component. Inspect its real imports, shared layouts, styles, tokens, and route ownership with read-only tools whenever needed; do not assume a single-page project or guess from filenames.
|
||||
|
||||
## Progressive phases
|
||||
|
||||
- `first`: return variant 1 and the complete coherent plan. Defer parameters.
|
||||
- `remainder`: return variants 2 through N together, following the stored plan, plus final parameter wiring CSS and the manifest for every variant. Do not change variant 1 or any default appearance.
|
||||
- `params`: recovery only when all variants were durably published but their parameters were not. Return only parameter wiring CSS and the manifest.
|
||||
- Parameters are coarse, meaningful axes already present in the designs. Tiny elements may have none; larger compositions usually expose two or three. Never exceed four per variant.
|
||||
|
||||
The supervisor runs the Impeccable detector before publication. On a repair turn, use judgment on every finding: fix real defects, but preserve contextually intentional design and detector false positives by returning the narrow `detectorWaivers` entry requested by the repair schema with a concrete reason. Never persist project ignore config or add inline ignore comments from this read-only worker. Publication proceeds only when every new finding was fixed or explicitly waived.
|
||||
@@ -10,21 +10,24 @@ Execute in order. No step skipped, no step reordered.
|
||||
|
||||
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 .github/skills/impeccable/scripts/live.mjs --target <path>` instead; then run the rest of this live session from the returned `projectRoot`.
|
||||
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). After every event or `--reply`, run `live-poll.mjs` again immediately. Never pass a short `--timeout=`.
|
||||
3. Poll loop with the default long timeout (600000 ms). Portable harnesses run `live-poll.mjs` again immediately after every event or `--reply`. Codex with the dedicated worker keeps the returned `--stream` control command alive instead. 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`: read screenshot if present; load the action's reference; plan three distinct directions; write all variants in one edit; `--reply done`; poll again.
|
||||
4. On `generate`: reuse `event.scaffold` when present; read the screenshot if present; load the action's reference; plan three distinct directions; deliver variants using the harness policy below; `--reply done`; poll again.
|
||||
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 you finish cleanup, run `live-complete.mjs --id EVENT_ID`, and only then poll again.
|
||||
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 control task runs `live-complete.mjs --id EVENT_ID`; the Codex control stream waits for that event reply without exiting, while synchronous harnesses finish 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.
|
||||
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. 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 poll in the **foreground** (blocking shell; not a background task, not a subagent). Codex background exec sessions do not reliably surface poll stdout back into the conversation at the moment events arrive, so a "fire-and-forget" background poll will stall live mode.
|
||||
- **Codex**: `live.mjs` starts a dedicated app-server generation lane by default and returns its exact persistent foreground control command. Run that `--stream` command once in a yielded foreground exec session; do not suffix it with `&`, restart it after each event, or launch an overlapping poll. The yielded shell remains alive while the model handles Steer, manual Apply, or carbonize through separate tool calls; after the model posts `--reply`, the same stream resumes polling automatically. Keep the task open until Live exits. The stream dynamically adds generation events only if the dedicated worker fails or exits. When the worker is explicitly disabled or unavailable, preserve the portable one-shot foreground path and delegate to the low-effort `impeccable_live_generator` agent with a compact handoff. Do not paste this full reference into the handoff.
|
||||
- **Other harnesses**: one-shot foreground unless you know stdout reliably returns to this session when a shell exits.
|
||||
|
||||
Generation delivery policy:
|
||||
- **Default (Claude Code, Cursor, and other harnesses):** keep the established atomic single-edit delivery unless that harness has independently demonstrated that progressive tool calls are faster and reliable. This avoids trading model latency for extra tool-call latency on harnesses with different streaming behavior.
|
||||
|
||||
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
|
||||
@@ -35,6 +38,10 @@ node .github/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 and DESIGN.md in mind for variant generation; **DESIGN.md wins on visual decisions; PRODUCT.md wins on strategic/voice decisions.** 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 from existing identity requires an explicit trigger from PRODUCT.md anti-references or the user's freeform prompt.
|
||||
|
||||
If output includes `codexWorker.enabled: true`, run the returned `codexWorker.foregroundPoll` command once and keep its yielded exec session alive. The dedicated lane owns `generate,accept,discard,prefetch`; the foreground owns `steer,manual_edit_apply,carbonize_cleanup,exit`. The fallback flag restores generation to the foreground only when the worker's owned process record is failed or unreachable. When a control event is printed, handle it through separate tool calls and post its reply; the stream waits for that acknowledgement and then resumes automatically. The browser reports foreground availability while this stream is polling or waiting for its leased control event acknowledgement. Do not start another poll, and do not end the task with a final response until Live exits.
|
||||
|
||||
If output includes `codexWorker.error: "codex_cli_unavailable"`, tell the user once that Live is using foreground generation, then run the returned unfiltered `codexWorker.foregroundPoll`. Do not retry or install anything during the session. The browser mark carries a static status dot and explains that installing Codex CLI, running `codex login`, and restarting Live enables background variants.
|
||||
|
||||
`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.
|
||||
@@ -86,20 +93,60 @@ node .github/skills/impeccable/scripts/live-complete.mjs --id SESSION_ID
|
||||
|
||||
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.
|
||||
|
||||
### Dedicated Codex worker
|
||||
|
||||
Codex uses a Live-owned persistent app-server supervisor instead of using the desktop task as the poll supervisor:
|
||||
|
||||
```bash
|
||||
node .github/skills/impeccable/scripts/live.mjs
|
||||
```
|
||||
|
||||
Activation is process-local: the worker is enabled by default only when the process carries a Codex runtime signal, so a committed setting cannot switch another harness onto Codex. Set `IMPECCABLE_LIVE_CODEX_WORKER=0` to force the portable foreground path. Project config may tune delivery or select the explicit `fast` profile without enabling the worker in another harness:
|
||||
|
||||
```json
|
||||
{
|
||||
"experimentalCodexWorker": {
|
||||
"profile": "quality",
|
||||
"delivery": "progressive"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The app-server worker is **default-on in Codex and Codex-only**. Claude, Gemini, Cursor, and every other harness keep the portable foreground/atomic behavior. Before detaching anything, Live resolves the configured Codex executable using the same explicit-path/PATH rules as Node spawn. A missing CLI becomes an immediate, durable foreground fallback with setup guidance instead of a misleading prewarm state. Otherwise Live records the worker as `starting` and returns immediately, so app-server initialization overlaps page/dev-server startup. Run only the returned foreground control poll. It checks the owned worker process every two seconds and safely restores generation/accept/discard leasing if startup, authentication, model selection, or the worker process fails. Dedicated-worker leases expire after 15 seconds, so a hard process loss cannot strand browser work behind the portable ten-minute lease.
|
||||
|
||||
```bash
|
||||
node .github/skills/impeccable/scripts/live-poll.mjs --stream --types=steer,manual_edit_apply,carbonize_cleanup,exit --codex-worker-fallback
|
||||
```
|
||||
|
||||
The supervisor launches its own `codex app-server --stdio` process, dynamically prefers the strongest visible general model (currently GPT-5.6 Sol), and uses medium reasoning. The optional `fast` profile retains Spark/mini selection and low reasoning for controlled comparisons. It creates a dedicated Impeccable-owned thread and persists only that id in `.impeccable/live/codex-worker.json`; it never lists, resumes, steers, or writes to the desktop task. A crash reconnect may resume that id only when the ownership marker and project cwd both match. Clean Live exit interrupts the active turn, archives the dedicated thread, and stops app-server.
|
||||
|
||||
The first generation turn in a worker task attaches the installed Impeccable skill as a native app-server skill input and resolves inherited/monorepo PRODUCT.md and DESIGN.md through the same context loader as the foreground skill. Each generation supplies the exact selected source artifact, event, scaffold, page URL, and action reference. The persistent read-only thread decides which imports, route layouts, styles, tokens, or shared components it needs to inspect; no lexical source-neighborhood heuristic stands in for repository understanding. Annotated requests attach `screenshotPath` as a real high-detail local image instead of a JSON path.
|
||||
|
||||
One persistent app-server thread performs both normal generation turns so identity, repository discoveries, the variant plan, and skill guidance remain coherent. Model turns run read-only and return structured staged-artifact files. Before publication, the supervisor runs the Impeccable detector against the staged candidate, compares it with the pre-existing baseline, and asks the same thread for one repair when new findings appear. The repair must fix real defects or explicitly classify contextually intentional/false-positive findings with narrow, reasoned per-candidate waivers; only findings left neither fixed nor waived block publication. Existing project detector ignores are honored by the scan, while the read-only worker never persists new config or inline suppressions. The supervisor then validates paths and publishes exclusively through the generation publisher's epoch/source-hash/immutable-prefix fence. Source-wrapper sessions use an isolated preview under `.impeccable/live/previews/`; the true source stays byte-identical until Accept. Progressive variant 1 is immediately reviewable; variants 2 through N and their parameters arrive together from turn two. Accept/Discard interrupts the active app-server turn, while the durable generation fence rejects any late completion that still races cancellation.
|
||||
|
||||
Controls:
|
||||
|
||||
```bash
|
||||
node .github/skills/impeccable/scripts/live-codex-worker.mjs --status
|
||||
node .github/skills/impeccable/scripts/live-codex-worker.mjs --stop
|
||||
```
|
||||
|
||||
Model and binary overrides are `IMPECCABLE_LIVE_CODEX_PROFILE`, `IMPECCABLE_LIVE_CODEX_MODEL`, `IMPECCABLE_LIVE_CODEX_EFFORT`, and `IMPECCABLE_CODEX_PATH`. `delivery: "atomic"` retains the one-turn publication control. Steer, manual Apply, carbonize cleanup, and Exit remain on the high-judgment foreground control lane; the server's type filter prevents either lane from leasing the other's events.
|
||||
|
||||
## 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.
|
||||
|
||||
Speed matters; the user is watching a spinner. Minimize tool calls by using the wrap/insert helper and writing all variants in a single edit.
|
||||
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.
|
||||
|
||||
### Insert mode branch
|
||||
|
||||
When `event.mode === "insert"`:
|
||||
|
||||
1. Read the screenshot if `event.screenshotPath` is present (annotations only).
|
||||
2. Run the insert helper instead of wrap:
|
||||
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:
|
||||
|
||||
```bash
|
||||
node .github/skills/impeccable/scripts/live-insert.mjs --id EVENT_ID --count EVENT_COUNT --position after \
|
||||
@@ -109,7 +156,7 @@ node .github/skills/impeccable/scripts/live-insert.mjs --id EVENT_ID --count EVE
|
||||
- `--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`. For Operate/Read surfaces load `operate.md`; Persuade/Experience surfaces use SKILL.md's mode guidance plus `new-work.md` when the variant invents identity (freeform only, no action sub-command). Write all variants in one edit, then `--reply done`.
|
||||
The scaffold has **no** `data-impeccable-variant="original"`. Variants are net-new HTML+CSS inserted at `insertLine`. For Operate/Read surfaces load `operate.md`; Persuade/Experience surfaces use SKILL.md's mode guidance plus `new-work.md` when the variant invents identity (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.
|
||||
|
||||
@@ -134,6 +181,8 @@ Reading annotations precisely:
|
||||
|
||||
### 2. Wrap the element
|
||||
|
||||
When `event.scaffold` is present, the local helper already found and wrapped the source 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.
|
||||
|
||||
```bash
|
||||
node .github/skills/impeccable/scripts/live-wrap.mjs --id EVENT_ID --count EVENT_COUNT --element-id "ELEMENT_ID" --classes "class1,class2" --tag "div" --text "TEXT_SNIPPET"
|
||||
```
|
||||
@@ -153,7 +202,9 @@ Output on success: `{ file, insertLine, commentSyntax, styleMode, styleTag, cssS
|
||||
|
||||
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 the Svelte component path go in a sidecar, never as an attribute.** Svelte parses `{` inside an attribute value as the start of an expression, so a `data-impeccable-params='[{…}]'` attribute on a component element fails to compile (`Expected token }`). Declare params for this path in `componentDir/params.json`, keyed by variant number, using the exact param schema from section 7:
|
||||
For Nuxt/Vue targets, `live-wrap.mjs` returns `previewMode: "vue-component"` with `file` pointing at an app-local generated manifest under `<appDir>/.impeccable-live/<id>/manifest.json`, `componentDir` pointing at real Vue SFC variants, and `sourceFile` pointing at the untouched `.vue` route. Write `v1.vue`, `v2.vue`, … with one root inside `<template>` and variant CSS in `<style scoped>`; keep dynamic text on the `propContract` bindings as `{{ propName }}`. Do **not** rewrite `sourceFile` during generation: Nuxt/Vite compiles and mounts these dev-only modules without invalidating the route. Accept is the only route write and inlines the selected template/CSS under the source lock; Discard deletes the generated session.
|
||||
|
||||
**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:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -291,11 +342,13 @@ In **departure mode**, the prompt narrows the lanes you draw from, not the famil
|
||||
|
||||
When the prompt and PRODUCT.md anti-references conflict (the prompt asks for X, the anti-references ban X), the anti-references win; they describe the brand's standing position, the prompt is one moment.
|
||||
|
||||
### 6. Write all variants in a single edit
|
||||
### 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`).
|
||||
|
||||
Write CSS + all variants in ONE edit at the `insertLine` reported by `wrap`. Colocate CSS as a `<style>` tag inside the variant wrapper; `<style>` works anywhere in modern browsers and this ensures CSS and HTML arrive atomically (no FOUC).
|
||||
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:
|
||||
|
||||
@@ -319,7 +372,7 @@ Use the `cssAuthoring` object returned by `live-wrap.mjs` to author the temporar
|
||||
|
||||
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.
|
||||
|
||||
One edit, all variants; the browser's MutationObserver picks everything up in one pass.
|
||||
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 > ...`.
|
||||
|
||||
@@ -361,7 +414,7 @@ Each variant can expose **coarse** knobs alongside the full HTML/CSS replacement
|
||||
|
||||
**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 `svelte-component` path, do not use this attribute** (Svelte can't compile `{` inside an attribute value). Declare params in `componentDir/params.json` keyed by variant number instead (see the Svelte component paragraph in the wrap section). The param schema below is identical for both paths.
|
||||
**How to declare.** Put a JSON manifest on the variant wrapper (HTML/JSX path). **On `svelte-component` and `vue-component` paths, 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.
|
||||
|
||||
```html
|
||||
<div data-impeccable-variant="1" data-impeccable-params='[
|
||||
@@ -462,7 +515,7 @@ Event: `{id, variantId, _acceptResult, _completionAck}`. The poll script already
|
||||
- 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 before the next poll.** See the "Required after accept (carbonize)" section below. The `event._acceptResult.todo` field, `_completionAck.requiresComplete`, and a stderr banner all point at this required follow-up; none are decorative. After cleanup, run `live-complete.mjs --id EVENT_ID`, then 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` without `mode`: manual cleanup: read file, find markers, edit.
|
||||
|
||||
@@ -470,7 +523,9 @@ Event: `{id, variantId, _acceptResult, _completionAck}`. The poll script already
|
||||
|
||||
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.
|
||||
|
||||
Do these five steps in the current thread, synchronously, before the next poll. Do not poll again until the file is clean.
|
||||
**Codex:** the persistent foreground control stream prints the cleanup event and then waits for its acknowledgement; this does not block the model. Leave that yielded exec session running, perform these five steps through separate tool calls in the main task, run `live-complete.mjs --id SESSION_ID`, and post the event reply. The same stream resumes polling automatically after the acknowledgement. A later Generate cannot be leased by this waiting control stream; the source lock, generation epoch, and expected-source hash remain the final safety gates.
|
||||
|
||||
**Other harnesses:** unless an equivalent independently supervised cleanup worker is proven, do these five steps synchronously before the next poll.
|
||||
|
||||
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).
|
||||
@@ -478,9 +533,9 @@ Do these five steps in the current thread, synchronously, before the next poll.
|
||||
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, run `live-complete.mjs --id SESSION_ID`, verify it reports `phase: "completed"`, then poll again.
|
||||
After the file is clean, the cleanup owner runs `live-complete.mjs --id SESSION_ID` and verifies `phase: "completed"`. The Codex supervisor keeps polling throughout; synchronous harnesses poll again only after that verification.
|
||||
|
||||
A background agent may be used for the rewrite, but the current thread is responsible for verifying the five steps are complete before issuing the next poll. In practice, inline is usually faster and less error-prone.
|
||||
With the dedicated worker, Accept emits a foreground `carbonize_cleanup` control event: `{id, sessionId, file, variantId, acceptResult}`. Perform the same five steps above for `sessionId`, run `live-complete.mjs --id SESSION_ID`, then acknowledge the control event with `live-poll.mjs --reply EVENT_ID complete --file FILE`. Do not restart the control poll; the existing stream resumes after this reply.
|
||||
|
||||
## Handle `discard`
|
||||
|
||||
@@ -545,6 +600,7 @@ When the poll returns `exit`, proceed to cleanup. If the poll is still running a
|
||||
## Cleanup
|
||||
|
||||
```bash
|
||||
node .github/skills/impeccable/scripts/live-codex-worker.mjs --stop # only when codexWorker.enabled was true
|
||||
node .github/skills/impeccable/scripts/live-server.mjs stop
|
||||
```
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ You are reading this because nothing committed exists yet (greenfield), or the u
|
||||
|
||||
## Seed
|
||||
|
||||
If the project is brand-new (no committed tokens, fonts, or brand colors found in the code), run `node .github/skills/impeccable/scripts/palette.mjs` for a brand seed color. The seed exists to break your reflex palette; it does not override the subject. When the subject's world clearly dictates color (an era, a place, a material, a medium), derive the palette from that world and use the seed only to check yourself. Otherwise anchor on it. The palette has exactly two legitimate sources: the seed, or the subject's world. What the category usually looks like is neither, and quietly swapping in the category's habitual palette and theme after drawing a seed is the reflex this step exists to break. Use OKLCH throughout. Skip this entirely when the code already has committed brand colors: identity-preservation wins.
|
||||
If the project is brand-new (no committed tokens, fonts, or brand colors found in the code), run `node .github/skills/impeccable/scripts/palette.mjs` for a brand seed color. The seed exists to break your reflex palette; it does not override the subject. When the subject's world clearly dictates color (an era, a place, a material, a medium), derive the palette from that world and use the seed only to check yourself. Otherwise anchor on it. The palette has exactly two legitimate sources: the seed, or the subject's world. What the category usually looks like is neither, and quietly swapping in the category's habitual palette and theme after drawing a seed is the reflex this step exists to break. Color commits at page scale: fields that own whole regions, not accents scattered over a neutral ground. A dark page with one glowing accent is the category's reflex, not a choice. Use OKLCH throughout. Skip this entirely when the code already has committed brand colors: identity-preservation wins.
|
||||
|
||||
## Ground it in the subject
|
||||
|
||||
@@ -12,19 +12,21 @@ Name one concrete subject, its audience, and the page's single job. The subject'
|
||||
|
||||
## Decide, then build
|
||||
|
||||
Sketch three directions in one line each before choosing: they must differ in concept, not in polish. If the direction you'd instinctively ship is the one any competent studio would also reach for, it is the default wearing your name; pick the direction that is most specific to this subject and still serves the mode.
|
||||
Derive the concept with this procedure, recording each step in your reasoning before the next begins. One: state the product's unique mechanism in one sentence, the thing competitors cannot truthfully claim. Two: competitive analysis; describe the page this category always ships, and the counter-position page a contrarian ships, and treat both structures as off the table. Three: from the audience's world and the subject's cultural home, list seven concrete materials, objects, documents, or rituals they know by heart, each with one line on why it resonates and can carry the mechanism, ordered by resonance. Four: run `node .github/skills/impeccable/scripts/concept-seed.mjs` and follow what it prints: it assigns which candidate to build (your top-ranked candidate is what every run would ship; a single ranking is deterministic, so the dice come from outside) and supplies challenger forms to weigh against your list on exactly two axes, audience identification and product clarity. Five: the chosen form supplies the page's structure, reading order, and component conventions; the product supplies every fact. Commit every atom: nav, buttons, inputs, and links are rebuilt in the form's vocabulary, and a stock component inside a committed form is a lapse. The form has its own native arrangement; borrow its skeleton, not just its clothes. Land the first build fully committed; committing is the hard part, and the passes that follow exist to make the committed thing clear and effective, never to dilute it. Conversion conventions live inside the form's own vocabulary: a hero that hooks in one line, a visible primary action, a legible reading order. The chosen form also dictates the first viewport's geometry: render the form at the scale it has in life, edge to edge when that is its nature; embedding it as a panel inside a standard marketing layout forfeits it. Cinematic full-bleed openings, intentionally divergent grids, and color drenched across whole regions are in bounds whenever the form calls for them; on an unattended build, the safe layout is the risk. The form has native motion, what it does in life between states; give the page that motion once, orchestrated, rather than scattered hover effects.
|
||||
|
||||
Then state the chosen direction as a contract, written as a comment block at the top of the artifact (invisible to visitors, binding for you): the concept in one line; what a visitor would describe an hour after one viewport; why this page could not be the modal competitor page; the signature; and what the first viewport does instead of a generic header. If any answer is missing or reads like a mood, the direction isn't decided yet. The build is judged against this contract; delivering different pixels than the contract promises is a defect on whichever side is weaker. When a user can respond and the work is substantial, pause there for confirmation; when the harness has native image generation, follow [codex.md](codex.md)'s mock flow before code. When no user can respond, record the decision in your reasoning and proceed without pausing. Either way the decision comes first; code that precedes a direction is the template reflex in motion.
|
||||
Then state the chosen direction as a contract, written as a comment block at the top of the artifact (invisible to visitors, binding for you), five short blocks, two hundred words at most. UNIQUE: the one idea this page owns. NOT-TEMPLATE: how the page's structure differs from the category's standard arrangement, stated plainly and honestly. OWN-WORLD: the palette and component language, specific enough that the components and colors alone, shown without content, would be recognizable as this page's world and nobody else's. STORY: what the visitor understands, believes, and does, from first viewport to action. FIRST VIEWPORT: the exact composition, what is where and at what scale. FORM: the chosen candidate and its position on your ordered list, plus the seed key the script printed. If any block is missing or reads like a mood, the direction isn't decided yet. The build is judged against this contract; delivering different pixels than the contract promises is a defect on whichever side is weaker. When a user can respond and the work is substantial, pause there for confirmation; when the harness has native image generation, follow [codex.md](codex.md)'s mock flow before code. When no user can respond, record the decision in your reasoning and proceed without pausing. Either way the decision comes first; code that precedes a direction is the template reflex in motion.
|
||||
|
||||
## Plan, self-check, build
|
||||
|
||||
Plan a compact token system in your reasoning: palette, type, layout concept in one sentence, and a **signature**: the one element this surface will be remembered by, drawn from the subject's world. A signature carries weight: sized and placed so the page organizes itself around it. The layout has exactly two legitimate sources: the concept, or the content's own structure. The category's habitual skeleton is neither, and assembling the usual sections in the usual order after choosing a concept is the same reflex the palette rule breaks, expressed in structure. Then audit the plan: work through what you'd produce for a similar brief from another client, and wherever the two plans converge (same palette family, same face, same skeleton), that part is your generic default, not a choice. Revise it, then build, deriving every color and type decision from the revised plan.
|
||||
|
||||
**The first viewport is a thesis, not a header.** The visitor should meet the concept doing its job immediately: the work itself, the product working, the content answering, the task at hand. Generic chrome around a generic promise is the template answer; earn it or replace it. The memory test: if someone left after one viewport, what would they describe an hour later? If the honest answer is a mood ("clean", "tasteful"), the concept hasn't committed yet.
|
||||
**Pace the scroll like a studio.** The scroll is a rhythm, not a stack: alternate full-bleed bands of the palette, vary the treatment from section to section inside the one system (a dense passage earns a quiet one, a graphic section earns a typographic one), ground at least one section in the signature motif as texture, and end anchored by a real close. One spacing rhythm throughout, kept like a promise: sections breathe in large, legible beats, and the space above a heading always exceeds the space below it. A page whose every section wears the same weight and density reads as monotone no matter how strong the concept.
|
||||
|
||||
**The first viewport is a thesis, not a header.** The visitor should meet the concept doing its job immediately: the work itself, the product working, the content answering, the task at hand. Generic chrome around a generic promise is the template answer; earn it or replace it. The composition is derived the same way the palette is: if a neighboring product could ship the same arrangement of the same blocks, the viewport isn't composed yet. The memory test: if someone left after one viewport, what would they describe an hour later? If the honest answer is a mood ("clean", "tasteful"), the concept hasn't committed yet.
|
||||
|
||||
**Everything bold, nothing bland.** Bold is not decoration and not clutter; it is commitment to the concept, carried through every section. Commitment takes whatever form the concept and the mode demand: maximal or severely clean, drenched in color or nearly monochrome, copy so precise it stings, the product demonstrating itself, or a system so exact it feels inevitable (a decisive typographic voice, one owned accent, an unmistakable rhythm). A spare page built on one uncompromising idea is bold; a busy page of tasteful defaults is bland. The signature is where the concept peaks, not the only place it lives; cut anything that neither advances the concept nor serves the visitor's mode. Polish is the floor, not the point: when torn between refined and committed, commit.
|
||||
|
||||
**Prove, don't claim.** A surface earns belief by showing its subject doing its job: the interface at work, the mechanism dramatized, the content delivering, specifics a competitor couldn't copy-paste. The visitor should understand by looking, before reading a word. Sections that restate a claim in different words add length, not substance.
|
||||
**Prove, don't claim.** A surface earns belief by showing its subject doing its job: the interface at work, the mechanism dramatized, the content delivering, specifics a competitor couldn't copy-paste. The visitor should understand by looking, before reading a word. Sections that restate a claim in different words add length, not substance, and a page that demonstrates everything you discovered while planning reads as cruft: build only the sections a visitor needs to understand, trust, and act.
|
||||
|
||||
## Commit
|
||||
|
||||
@@ -53,3 +55,5 @@ Layout: asymmetric compositions and intentional grid breaks are on the table; fl
|
||||
## Finish like a studio
|
||||
|
||||
Look at what you built the way a design lead would, with whatever eyes the harness gives you (browser, screenshot tool, or reading the code cold): major sections individually on long pages, mobile and desktop at minimum. Write an honest critique against the brief and the stated direction, patch material defects, and re-inspect; don't invent defects to demonstrate diligence. Then verify against SKILL.md's craft floor and run the detector; a bold page that ships mechanical defects is not done, and neither is a polished page missing something the brief asked for.
|
||||
|
||||
When the harness can run a separate agent, the review above belongs there, not here: hand the reviewer the artifact path, its direction contract, and the detector command, and have it return a short list of material fixes; apply them and finish. A fresh reader catches what the builder's own eyes slide past, and the build thread stays spent on building.
|
||||
|
||||
@@ -0,0 +1,132 @@
|
||||
{
|
||||
"_comment": "Challenger pool for concept-seed.mjs. Each entry is a culturally legible FORM (a thing people already know how to read) that can supply a page's structure, reading order, and component conventions. Sources: original curation + gpt-5.6-sol + gemini-3.5-pro expansion passes (2026-07-14), deduped. FOR PAUL'S CURATION: cut freely; the script samples 3 per run. Keep entries brand-free and subject-agnostic; the structural elements after the comma are what the page inherits.",
|
||||
"printed_editorial": [
|
||||
"a naturalist's field guide, with specimen plates and identification keys",
|
||||
"a broadsheet newspaper's sports section, with match reports and standings tables",
|
||||
"a farmer's almanac, with seasonal charts and terse forecasts",
|
||||
"a classified ads section, with dense typographic categories and bold lead-in keywords",
|
||||
"a dictionary spread, with alphabetic guide words, nested definitions, and cross-references",
|
||||
"an encyclopedia double-spread, with a central subject summary, marginal cross-references, and index tags",
|
||||
"a comic-book page, with panel rhythm, reading gutters, and caption tiers",
|
||||
"a storyboard sheet, with shot frames, sequence numbers, and action notes",
|
||||
"a literary journal's table of contents, with author names, abstract snippets, and leader dots",
|
||||
"a fashion lookbook, with full-bleed imagery, asymmetric text columns, and tiny credits",
|
||||
"a zine, hand-assembled, with cut-paper collage and typewritten columns",
|
||||
"a paperback's back cover and front matter, with blurbs and a table of contents",
|
||||
"a mail-order catalog, with numbered item grids, specification tables, and an order form",
|
||||
"a theater playbill, with cast hierarchies, act-and-scene structure, and advertising margins",
|
||||
"a pharmacopoeia monograph, with indications, dosage tables, and contraindications",
|
||||
"an atlas plate, with indexed regions, layered legends, and coordinate grids"
|
||||
],
|
||||
"instruments_panels": [
|
||||
"a mission-control status wall, with countdown clocks and go/no-go polls",
|
||||
"a ship's bridge instrument panel, with engine-order telegraph and compass repeaters",
|
||||
"a recording studio mixing console, with repeated channel strips, shared buses, and master controls",
|
||||
"a patch-bay diagram, with source-destination matrices and signal groupings",
|
||||
"an aircraft preflight checklist, with phased sections, binary confirmations, and hold points",
|
||||
"an oscilloscope faceplate, with a calibrated grid, overlaid traces, and channel controls",
|
||||
"a sonar sweep display, with concentric distance rings, sweep lines, and blip markers",
|
||||
"a weather station's synoptic chart, with fronts, isobars, and station models",
|
||||
"a seismograph station's drum recorders and event logs",
|
||||
"a darkroom contact sheet, with thumbnail grids, frame numbers, and grease-pencil selection marks",
|
||||
"a camera viewfinder overlay, with framing grid lines, exposure bars, and status indicators",
|
||||
"a medical triage chart, with color-coded priority tiers, vital-sign thresholds, and symptom checklists",
|
||||
"a hospital patient chart, with a summary header, time-series observations, and alert annotations",
|
||||
"a periodic table, with categorical families, ordered coordinates, and encoded properties"
|
||||
],
|
||||
"places_signage": [
|
||||
"a metro system's map and station signage, with colored line routes, transfer nodes, and zone boundaries",
|
||||
"a rail-platform sign system, with directional bands, stop sequences, and numbered exits",
|
||||
"an airport departures board, with flip-dot rows, gate status alerts, and scheduled timelines",
|
||||
"a motorway sign gantry, with lane-aligned choices, route shields, and distance cues",
|
||||
"an emergency evacuation plan, with a fixed you-are-here point, branching routes, and priority exits",
|
||||
"a theater's lobby cards and marquee, with cast lists and act summaries",
|
||||
"a race circuit's pit wall timing screens, with sector splits and tyre stints",
|
||||
"a national park trailhead kiosk, with route markers, difficulty grades, and safety notices",
|
||||
"a botanical garden trail map, with legend symbols, path grades, and specimen stations",
|
||||
"a museum gallery directory, with floor-plan shapes, wing names, and room-by-room listings",
|
||||
"a harbor's tide table board and small-craft advisories",
|
||||
"a pilgrimage route map, with staged waypoints, distance intervals, and destination seals",
|
||||
"a parking garage level guide, with colored floor zones, bay numbering, and exit arrows",
|
||||
"a supermarket planogram, with shelf bands, repeated facings, and priority zones"
|
||||
],
|
||||
"records_documents": [
|
||||
"a court transcript, with examination, exhibits, and a verdict",
|
||||
"a legal case file, with a cover index, chronologically tabbed evidence, and disposition stamps",
|
||||
"a ship's log, with watch entries, positions, and weather remarks",
|
||||
"an expedition's field notebook, with sketches, measurements, and daily entries",
|
||||
"a laboratory notebook, with dated experiments, observations, and sign-offs",
|
||||
"a botanist's herbarium sheet, with mounted specimens, label cards, and collection metadata",
|
||||
"a passport booklet, with identity front matter, repeated entry fields, and chronological stamps",
|
||||
"a customs declaration form, with gated sections, coded responses, and signature checkpoints",
|
||||
"a census questionnaire, with fill-in boxes, branching yes/no paths, and instruction margins",
|
||||
"a ballot paper, with constrained choices, section-by-section progression, and verification marks",
|
||||
"a title deed and property survey, with plot boundaries and easements",
|
||||
"a cadastral survey map, with parcel boundaries, plot numbers, and keyed ownership records",
|
||||
"a patent folio, with numbered figures, claim hierarchies, and reference labels",
|
||||
"an industrial standards sheet, with numbered clauses, dimensioned diagrams, and tolerance tables",
|
||||
"a repair manual's exploded-parts diagrams, with numbered callouts and lookup tables",
|
||||
"a double-entry ledger, with mirrored debit-credit columns, running balances, and period totals",
|
||||
"a bank statement, with opening and closing summaries, chronological transactions, and reconciled totals",
|
||||
"a bank passbook, with ruled entries and teller stamps",
|
||||
"a utility bill, with historical usage charts, payment-due boxes, and itemized fees",
|
||||
"a shipping manifest, with grouped consignments, tracking codes, and exception flags",
|
||||
"a telephone directory, with alphabetic columns, index tabs, and compact locator codes",
|
||||
"a library card catalog, with standardized records, alphabetical dividers, and linked subject codes"
|
||||
],
|
||||
"broadcast_ephemera": [
|
||||
"a teletext service, with page numbers, block graphics, and channel colors",
|
||||
"a printed TV programme guide, with time grids and circled listings",
|
||||
"a radio station's program log and request-line cards",
|
||||
"a vintage radio receiver plate, with slide tuning bands, frequency markings, and signal meters",
|
||||
"a cinema's projection booth reel-change cue sheets",
|
||||
"a cinema ticket stub, with seat coordinates, screen numbers, and entry barcodes",
|
||||
"a vinyl double-album gatefold, with liner notes, track listing, and credits panel",
|
||||
"a video-rental shop, with hand-labeled cassettes and membership cards",
|
||||
"a shortwave listener's QSL card collection and frequency schedules",
|
||||
"a photographic slide carousel and its typed index card"
|
||||
],
|
||||
"commerce_packaging": [
|
||||
"a seed packet's front-and-back panels, with sowing instructions and zone tables",
|
||||
"a mail-order seed catalog, with variety grids and growing-zone tables",
|
||||
"a hardware store's parts drawers, with bin labels and spec cards",
|
||||
"a pharmacy prescription label and patient-information leaflet",
|
||||
"a matchbook and cigar-band graphics, with foil stamping and tiny type",
|
||||
"a produce market's chalkboard price signs and crate-side stencils",
|
||||
"a market price board, with commodity rows, live rate changes, and unit legends",
|
||||
"a restaurant order rail, with time-ordered tickets, station assignments, and completion marks",
|
||||
"a restaurant order ticket, with seat numbers, modifier checkmarks, and timestamps",
|
||||
"an auction house catalog, with lot numbers, estimate bands, and condition reports",
|
||||
"a coupon sheet, with perforated modules, denomination hierarchy, and redemption conditions",
|
||||
"a recipe card, with an ingredient inventory, ordered steps, and timing checkpoints"
|
||||
],
|
||||
"games_rituals": [
|
||||
"a chess annotation sheet, with move pairs and evaluation symbols",
|
||||
"a tournament bracket, with converging match paths, round-by-round hierarchy, and a single outcome",
|
||||
"a scorekeeper's baseball scorecard, with position numbers and inning grids",
|
||||
"a bingo hall's number board and dabbed cards",
|
||||
"a lotería board, with a numbered image grid, compact labels, and call-and-response progression",
|
||||
"a tarot spread, with card positions and a reading order",
|
||||
"a board game's rulebook, with setup diagrams and turn order",
|
||||
"a crossword page, with grid, clues across and down, and a setter's note",
|
||||
"a kanban board, with staged columns, movable work cards, and explicit capacity limits",
|
||||
"a perpetual calendar, with nested time scales, repeating cycles, and movable indicators"
|
||||
],
|
||||
"world_manuscript_forms": [
|
||||
"an East Asian handscroll, with continuous lateral progression, scene breaks, and a terminal colophon",
|
||||
"a Chinese accordion-fold book, with panel-by-panel progression and paired image-text registers",
|
||||
"a Japanese bento box partition, with distinct compartments and a central main focus",
|
||||
"a Korean folding screen, with modular vertical panels, panoramic continuity, and a center axis",
|
||||
"an Indian palm-leaf manuscript, with long horizontal folios, line bands around a binding axis, and leaf numbers",
|
||||
"a Persian manuscript page, with a central narrative panel, nested marginal commentary, and illuminated thresholds",
|
||||
"an annotated manuscript folio, with a central text block, marginal glosses, and tiered section markers",
|
||||
"an Ethiopian codex spread, with facing text columns, color-coded voices, and ornamental dividers",
|
||||
"a Brazilian cordel chapbook, with a declarative cover, short sequential sections, and illustrated breaks",
|
||||
"an Aztec tribute codex, with pictorial quantity symbols, item icons, and origin-town signs",
|
||||
"an Islamic geometric tile system, with interlocking symmetry lines, border courses, and calligraphic bands",
|
||||
"an African block-print textile grid, with repeating symbolic patterns, border frames, and color blocks",
|
||||
"a vintage postcard back, with a split-half line, message field, and stamp-and-address boxes",
|
||||
"a stamp collector's album, with mounted specimens and perforation notes",
|
||||
"sheet music, with synchronized staves, movement markers, and recurring motifs"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,88 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* Concept-seed picker: the dice half of the new-work concept procedure.
|
||||
*
|
||||
* The model derives a grounded shortlist of candidate FORMS from the
|
||||
* audience's world and the subject's cultural home (see
|
||||
* reference/new-work.md). Left alone, it then always builds its #1 —
|
||||
* and a single model's resonance ranking is deterministic, so every run
|
||||
* in a category ships the same one or two concepts. Measured: 30/35
|
||||
* identical concepts across 16 prompt framings; the model cannot roll
|
||||
* its own dice.
|
||||
*
|
||||
* This script rolls them from outside, the same trick that made the
|
||||
* palette seed work:
|
||||
* - BUILD INDEX (2-5): which entry of the model's own resonance-ordered
|
||||
* shortlist to build. The dice never choose an ungrounded ingredient;
|
||||
* they only refuse the argmax rut. (Index 1 is excluded: that's the
|
||||
* concept every run would ship anyway.)
|
||||
* - CHALLENGERS (3): outside forms from concept-ingredients.json, weighed
|
||||
* against the derived candidates on exactly two axes — audience
|
||||
* identification and product clarity. They win only when they beat the
|
||||
* grounded list; measured behavior is that they lose to strong cultural
|
||||
* material and win over thin categories, which is the intended shape.
|
||||
*
|
||||
* Usage:
|
||||
* node scripts/concept-seed.mjs # roll at random
|
||||
* node scripts/concept-seed.mjs --from <key> # deterministic (hash key)
|
||||
*
|
||||
* Env vars:
|
||||
* IMPECCABLE_CONCEPT_SEED — same as --from; for reproducible eval runs.
|
||||
*/
|
||||
|
||||
import crypto from 'node:crypto';
|
||||
import { readFileSync } from 'node:fs';
|
||||
import { dirname, join } from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
|
||||
const here = dirname(fileURLToPath(import.meta.url));
|
||||
const pool = JSON.parse(readFileSync(join(here, 'concept-ingredients.json'), 'utf8'));
|
||||
|
||||
const args = process.argv.slice(2);
|
||||
const fromIdx = args.indexOf('--from');
|
||||
// When no key is supplied, generate one and print it: a user reporting a
|
||||
// bad outcome can hand us the key and we replay the exact roll.
|
||||
const key = fromIdx !== -1
|
||||
? args[fromIdx + 1]
|
||||
: (process.env.IMPECCABLE_CONCEPT_SEED || crypto.randomBytes(4).toString('hex'));
|
||||
|
||||
function hashUnit(k, salt) {
|
||||
const h = crypto.createHash('sha256').update(`${salt}:${k}`).digest();
|
||||
return h.readUInt32BE(0) / 0xffffffff;
|
||||
}
|
||||
const unit = (salt) => hashUnit(key, salt);
|
||||
|
||||
const buildIndex = 3 + Math.floor(unit('index') * 5); // 3..7
|
||||
|
||||
const entries = Object.entries(pool)
|
||||
.filter(([k]) => !k.startsWith('_'))
|
||||
.flatMap(([, list]) => list);
|
||||
const picks = [];
|
||||
const taken = new Set();
|
||||
for (let i = 0; picks.length < 3 && i < 60; i++) {
|
||||
const idx = Math.floor(unit(`challenger-${i}`) * entries.length) % entries.length;
|
||||
if (!taken.has(idx)) {
|
||||
taken.add(idx);
|
||||
picks.push(entries[idx]);
|
||||
}
|
||||
}
|
||||
|
||||
process.stdout.write(`CONCEPT SEED (key: ${key}; rerun with --from ${key} to reproduce this roll)
|
||||
BUILD INDEX: ${buildIndex}
|
||||
After ordering your derived candidates by resonance, build the page whose
|
||||
form comes from candidate number ${buildIndex}, exactly as if it had ranked
|
||||
first: full commitment. Your top-ranked candidate is what every run in this
|
||||
category would ship; the assignment exists to refuse that rut, not to
|
||||
punish it.
|
||||
CHALLENGERS (weigh against your derived candidates on the same two axes,
|
||||
audience identification and product clarity; a challenger wins only when
|
||||
it beats the grounded list on both):
|
||||
1. ${picks[0]}
|
||||
2. ${picks[1]}
|
||||
3. ${picks[2]}
|
||||
If a challenger wins, it replaces the assigned candidate. If the surface is
|
||||
an existing world whose incumbent carries a deliberate, ownable idea, the
|
||||
incumbent IS the chosen candidate: intensify its lineage and ignore the
|
||||
roll entirely. The same override applies when the user, PRODUCT.md, or
|
||||
DESIGN.md pins a direction: pinned direction beats the roll, always.
|
||||
`);
|
||||
@@ -899,11 +899,14 @@ async function cli() {
|
||||
// — cheap models miss the empty case more often than the explicit one.
|
||||
const parts = [
|
||||
'NO_PRODUCT_MD: This project has no PRODUCT.md yet. ' +
|
||||
'Follow SKILL.md Setup step 1: for `init`, `teach`, `craft`, `shape`, ' +
|
||||
'For `init`, `teach`, `craft`, `shape`, ' +
|
||||
'or wording that clearly maps to a from-scratch build/shape flow, load ' +
|
||||
'reference/init.md and write PRODUCT.md first; for any other (scoped) ' +
|
||||
'command against existing code, proceed using the code as context and ' +
|
||||
`offer \`${IMPECCABLE_COMMAND} init\` as a suggestion (do not block).`,
|
||||
'reference/init.md and write PRODUCT.md first, unless no user can ' +
|
||||
'respond (a one-shot or automated run, or the user said not to ask): ' +
|
||||
'then write a one-paragraph understanding of the product, audience, ' +
|
||||
'and the page\'s job from the brief, and continue. For any other ' +
|
||||
'(scoped) command against existing code, proceed using the code as ' +
|
||||
`context and offer \`${IMPECCABLE_COMMAND} init\` as a suggestion (do not block).`,
|
||||
'NEW_WORK: No committed design context was found. If this task produces ' +
|
||||
'new design (a build from scratch, or a redesign that discards the ' +
|
||||
'current look), you MUST read reference/new-work.md before making any ' +
|
||||
|
||||
@@ -1222,7 +1222,7 @@ if (IS_BROWSER) {
|
||||
return {
|
||||
type: f.type || f.id,
|
||||
category: ap ? ap.category : 'quality',
|
||||
severity: ap?.severity || 'warning',
|
||||
severity: f.severity || ap?.severity || 'warning',
|
||||
detail: f.detail || f.snippet,
|
||||
ignoreValue: f.ignoreValue || f.value || '',
|
||||
name: ap ? ap.name : (f.type || f.id),
|
||||
@@ -1477,6 +1477,7 @@ if (IS_BROWSER) {
|
||||
|
||||
const findings = [
|
||||
...checkElementBordersDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
|
||||
...checkElementPseudoStripeDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
|
||||
...checkElementColorsDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
|
||||
...checkElementMotionDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
|
||||
...checkElementGlowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
|
||||
@@ -1488,6 +1489,7 @@ if (IS_BROWSER) {
|
||||
...checkElementClippedOverflowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
|
||||
...checkElementGptBorderShadowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
|
||||
...checkElementTextOverflowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
|
||||
...checkElementBlinkingCursorDOM(el).map(f => ({ type: f.id, detail: f.snippet, ...(f.severity ? { severity: f.severity } : {}) })),
|
||||
...checkElementDesignSystemDOM(el, designSystem, designSeen),
|
||||
].filter(f => _ruleOk(f.type));
|
||||
|
||||
@@ -1526,12 +1528,55 @@ if (IS_BROWSER) {
|
||||
addBrowserFindings(groupMap, document.body, sectionKickerFindings);
|
||||
}
|
||||
|
||||
const numberedLabelFindings = checkNumberedSectionLabelsDOM()
|
||||
.map(f => ({ type: f.id, detail: f.snippet }))
|
||||
.filter(f => _ruleOk(f.type));
|
||||
if (numberedLabelFindings.length > 0) {
|
||||
pageLevelFindings.push(...numberedLabelFindings);
|
||||
addBrowserFindings(groupMap, document.body, numberedLabelFindings);
|
||||
}
|
||||
|
||||
const repeatedTextFindings = checkRepeatedContainerTextDOM()
|
||||
.map(f => ({ type: f.id, detail: f.snippet }))
|
||||
.filter(f => _ruleOk(f.type));
|
||||
if (repeatedTextFindings.length > 0) {
|
||||
pageLevelFindings.push(...repeatedTextFindings);
|
||||
addBrowserFindings(groupMap, document.body, repeatedTextFindings);
|
||||
}
|
||||
|
||||
const layoutFindings = checkLayout().filter(f => _ruleOk(f.type));
|
||||
for (const f of layoutFindings) {
|
||||
const el = f.el || document.body;
|
||||
addBrowserFindings(groupMap, el, [{ type: f.type, detail: f.detail || f.snippet }]);
|
||||
}
|
||||
|
||||
// Heading rhythm (browser-only: needs real layout for the gap math)
|
||||
const headingRhythmFindings = checkHeadingRhythmDOM().filter(f => _ruleOk(f.type));
|
||||
for (const f of headingRhythmFindings) {
|
||||
addBrowserFindings(groupMap, f.el || document.body, [{ type: f.type, detail: f.detail }]);
|
||||
}
|
||||
|
||||
// Edge-flush cards in horizontal scrollers (browser-only: needs real
|
||||
// layout for the scroller clip box vs card rect math)
|
||||
const edgeFlushFindings = checkEdgeFlushCardsDOM().filter(f => _ruleOk(f.type));
|
||||
for (const f of edgeFlushFindings) {
|
||||
addBrowserFindings(groupMap, f.el || document.body, [{ type: f.type, detail: f.detail }]);
|
||||
}
|
||||
|
||||
// Text occlusion / element overlap (browser-only: needs real layout +
|
||||
// elementFromPoint to confirm what actually paints on top)
|
||||
const occlusionFindings = checkTextOcclusionDOM().filter(f => _ruleOk(f.type));
|
||||
for (const f of occlusionFindings) {
|
||||
addBrowserFindings(groupMap, f.el || document.body, [{ type: f.type, detail: f.detail }]);
|
||||
}
|
||||
|
||||
// First-viewport column overflow — the stretched-hero signature
|
||||
// (browser-only: needs real layout for the content-extent math)
|
||||
const colOverflowFindings = checkFirstViewportColumnOverflowDOM().filter(f => _ruleOk(f.type));
|
||||
for (const f of colOverflowFindings) {
|
||||
addBrowserFindings(groupMap, f.el || document.body, [{ type: f.type, detail: f.detail }]);
|
||||
}
|
||||
|
||||
// Page-level quality checks (headings, etc.)
|
||||
const qualityFindings = checkPageQualityDOM().filter(f => _ruleOk(f.type));
|
||||
if (qualityFindings.length > 0) {
|
||||
@@ -1557,7 +1602,25 @@ if (IS_BROWSER) {
|
||||
}
|
||||
const htmlPatternFindings = checkHtmlPatterns(docClone.outerHTML);
|
||||
if (htmlPatternFindings.length > 0) {
|
||||
const mapped = htmlPatternFindings.map(f => ({ type: f.id, detail: f.snippet })).filter(f => _ruleOk(f.type));
|
||||
const mapped = htmlPatternFindings.map(f => {
|
||||
const item = { type: f.id, detail: f.snippet };
|
||||
if (f.severity) {
|
||||
item.severity = f.severity;
|
||||
} else if (f.id === 'pulsing-dot' && f.selector) {
|
||||
// The string scan promotes header/nav dots on its own; with a live
|
||||
// layout also promote dots resting in the first ~900px of the page
|
||||
// (the hero region), which the source scan cannot measure.
|
||||
try {
|
||||
const dotEl = document.querySelector(f.selector);
|
||||
if (dotEl) {
|
||||
const rect = dotEl.getBoundingClientRect();
|
||||
const pageTop = rect.top + (window.scrollY || 0);
|
||||
if (pageTop <= 900) item.severity = 'error';
|
||||
}
|
||||
} catch { /* unresolvable selector: keep registry severity */ }
|
||||
}
|
||||
return item;
|
||||
}).filter(f => _ruleOk(f.type));
|
||||
pageLevelFindings.push(...mapped);
|
||||
addBrowserFindings(groupMap, document.body, mapped);
|
||||
}
|
||||
@@ -1931,6 +1994,9 @@ if (IS_BROWSER) {
|
||||
window.impeccableDetectAsync = detectAsync;
|
||||
window.impeccableScan = scan;
|
||||
window.impeccableScanAsync = scanAsync;
|
||||
// Raw measurement for the URL engine's content-hidden-at-rest pass: it
|
||||
// drives a reveal sweep from Node and thresholds the result itself.
|
||||
window.impeccableMeasureHiddenText = measureHiddenTextDOM;
|
||||
window.impeccableCollectVisualContrastCandidates = collectVisualContrastCandidates;
|
||||
window.impeccableAnalyzeVisualContrast = analyzeVisualContrast;
|
||||
window.impeccableGetLastVisualContrastAnalyses = () => lastVisualContrastAnalyses.slice();
|
||||
|
||||
@@ -96,6 +96,8 @@ Options:
|
||||
--gemini Also report Gemini-specific provider tells (off by default)
|
||||
--scope <name> Only report rules in the given design domain
|
||||
(type, layout). Comma-separated.
|
||||
--viewport <WxH> Browser viewport for URL scans (default 1280x800),
|
||||
e.g. --viewport 390x844 for a mobile-width pass
|
||||
--no-config Do not apply project config, detector ignores, inline
|
||||
ignore comments, or DESIGN.md
|
||||
--no-inline-ignores Do not honor in-file impeccable-disable* ignore comments
|
||||
@@ -118,7 +120,8 @@ Inline ignores:
|
||||
Detection modes:
|
||||
HTML files Static HTML/CSS analysis (default, catches linked CSS)
|
||||
Non-HTML files Regex pattern matching (CSS, JSX, TSX, etc.)
|
||||
URLs Puppeteer full browser rendering (auto-detected)
|
||||
URLs Puppeteer full browser rendering (auto-detected;
|
||||
http(s):// and file:// URLs)
|
||||
|
||||
Examples:
|
||||
impeccable detect src/
|
||||
@@ -174,6 +177,20 @@ async function detectCli() {
|
||||
args.splice(i, inline ? 1 : 2);
|
||||
i -= 1;
|
||||
}
|
||||
let viewport = null;
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
if (args[i] !== '--viewport' && !args[i].startsWith('--viewport=')) continue;
|
||||
const inline = args[i].startsWith('--viewport=');
|
||||
const value = inline ? args[i].slice('--viewport='.length) : args[i + 1];
|
||||
const match = /^(\d{2,5})x(\d{2,5})$/i.exec(value || '');
|
||||
if (!match) {
|
||||
process.stderr.write('Error: --viewport requires a WxH value, e.g. --viewport 390x844\n');
|
||||
process.exit(1);
|
||||
}
|
||||
viewport = { width: Number(match[1]), height: Number(match[2]) };
|
||||
args.splice(i, inline ? 1 : 2);
|
||||
i -= 1;
|
||||
}
|
||||
const unknownScopes = scopes.filter(s => !RULE_SCOPES.has(s));
|
||||
if (unknownScopes.length > 0) {
|
||||
process.stderr.write(
|
||||
@@ -189,6 +206,7 @@ async function detectCli() {
|
||||
const inlineIgnoresEnabled = configEnabled && !args.includes('--no-inline-ignores');
|
||||
const scanOptions = { providers, inlineIgnores: inlineIgnoresEnabled };
|
||||
if (designSystem) scanOptions.designSystem = designSystem;
|
||||
if (viewport) scanOptions.viewport = viewport;
|
||||
const targets = args.filter(a => !a.startsWith('--'));
|
||||
|
||||
if (helpMode) { printUsage(); process.exit(0); }
|
||||
@@ -199,12 +217,17 @@ async function detectCli() {
|
||||
allFindings = await handleStdin(scanOptions);
|
||||
} else {
|
||||
const paths = targets.length > 0 ? targets : [process.cwd()];
|
||||
const urlTargetCount = paths.filter(target => /^https?:\/\//i.test(target)).length;
|
||||
// file:// URLs get the same Puppeteer-rendered pass as http(s) — the
|
||||
// real cascade, real computed styles, real layout. Callers that want a
|
||||
// browser-grade scan of a local artifact can pass file:///abs/path.html
|
||||
// instead of the bare path (which stays on the static engine).
|
||||
const urlRe = /^(?:https?|file):\/\//i;
|
||||
const urlTargetCount = paths.filter(target => urlRe.test(target)).length;
|
||||
const browserDetector = urlTargetCount > 1 ? await createBrowserDetector() : null;
|
||||
|
||||
try {
|
||||
for (const target of paths) {
|
||||
if (/^https?:\/\//i.test(target)) {
|
||||
if (urlRe.test(target)) {
|
||||
try {
|
||||
const scanner = browserDetector
|
||||
? (url) => browserDetector.detectUrl(url, scanOptions)
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -6,6 +6,34 @@ import { finding } from '../../findings.mjs';
|
||||
import { filterByProviders } from '../../registry/antipatterns.mjs';
|
||||
import { profileFindingsAsync, profileStep, profileStepAsync } from '../../profile/profiler.mjs';
|
||||
import { captureVisualContrastCandidate } from '../visual/screenshot-contrast.mjs';
|
||||
import { checkContentHiddenAtRest } from '../../rules/checks.mjs';
|
||||
|
||||
// Reveal sweep + invisible-text measurement for the content-hidden-at-rest
|
||||
// rule. Scrolls through the document with instant jumps (bypasses CSS
|
||||
// scroll-behavior: smooth) so IntersectionObserver / scroll reveal handlers
|
||||
// get every chance to fire, returns to the top, lets transitions settle,
|
||||
// then measures how much text still renders invisible. A healthy
|
||||
// reveal-on-scroll page drops to ~0 after the sweep; a page whose reveal
|
||||
// script died keeps most of its text at opacity 0.
|
||||
async function measureContentHiddenAfterReveal(page) {
|
||||
await page.evaluate(async () => {
|
||||
const step = Math.max(200, Math.floor(window.innerHeight * 0.7));
|
||||
const max = Math.max(
|
||||
document.documentElement.scrollHeight || 0,
|
||||
document.body?.scrollHeight || 0,
|
||||
);
|
||||
for (let y = 0; y <= max; y += step) {
|
||||
window.scrollTo({ top: y, left: 0, behavior: 'instant' });
|
||||
await new Promise(resolve => requestAnimationFrame(() => setTimeout(resolve, 40)));
|
||||
}
|
||||
window.scrollTo({ top: 0, left: 0, behavior: 'instant' });
|
||||
await new Promise(resolve => setTimeout(resolve, 700));
|
||||
});
|
||||
return page.evaluate(() => {
|
||||
if (typeof window.impeccableMeasureHiddenText !== 'function') return null;
|
||||
return window.impeccableMeasureHiddenText();
|
||||
});
|
||||
}
|
||||
|
||||
function serializeDesignSystemForBrowser(designSystem) {
|
||||
if (!designSystem?.present) return null;
|
||||
@@ -158,6 +186,19 @@ async function detectUrl(url, options = {}) {
|
||||
ruleId: 'new-page',
|
||||
target: url,
|
||||
}, () => browser.newPage());
|
||||
|
||||
// Uncaught exceptions and parse errors surface as pageerror events. The
|
||||
// listener must attach before goto: a syntax error fires during the
|
||||
// initial parse, long before the load event. Dedupe by message; a single
|
||||
// broken loop can otherwise throw hundreds of identical errors.
|
||||
const pageErrors = [];
|
||||
if (options?.scriptErrors !== false) {
|
||||
page.on('pageerror', (err) => {
|
||||
const message = String(err?.message || err).split('\n')[0].trim().slice(0, 160);
|
||||
if (message && !pageErrors.includes(message)) pageErrors.push(message);
|
||||
});
|
||||
}
|
||||
|
||||
let results = [];
|
||||
try {
|
||||
await profileStepAsync(profile, {
|
||||
@@ -213,9 +254,29 @@ async function detectUrl(url, options = {}) {
|
||||
return window.impeccableDetect({ decorate: false, serialize: true });
|
||||
});
|
||||
return serializedGroups.flatMap(({ findings }) =>
|
||||
findings.map(f => ({ id: f.type, snippet: f.detail, ignoreValue: f.ignoreValue || '' }))
|
||||
findings.map(f => ({ id: f.type, snippet: f.detail, ignoreValue: f.ignoreValue || '', severity: f.severity || '' }))
|
||||
);
|
||||
});
|
||||
// Content invisible at rest: reveal sweep, then re-measure. Runs after
|
||||
// the main scan (which must see the true at-rest state) and before the
|
||||
// visual contrast fallback (the sweep restores scroll to the top).
|
||||
if (options?.contentHidden !== false) {
|
||||
const hiddenFindings = await profileFindingsAsync(profile, {
|
||||
engine: 'browser',
|
||||
phase: 'scan',
|
||||
ruleId: 'content-hidden-at-rest',
|
||||
target: url,
|
||||
}, async () => {
|
||||
const measured = await measureContentHiddenAfterReveal(page);
|
||||
return measured ? checkContentHiddenAtRest(measured) : [];
|
||||
});
|
||||
results.push(...hiddenFindings);
|
||||
}
|
||||
|
||||
for (const message of pageErrors.slice(0, 3)) {
|
||||
results.push({ id: 'script-error', snippet: message });
|
||||
}
|
||||
|
||||
const visualFindings = await runVisualContrastFallback(page, serializedGroups, options, profile, url);
|
||||
results.push(...visualFindings);
|
||||
} finally {
|
||||
@@ -237,6 +298,9 @@ async function detectUrl(url, options = {}) {
|
||||
return filterByProviders(results.map(f => {
|
||||
const item = finding(f.id, url, f.snippet);
|
||||
if (f.ignoreValue) item.ignoreValue = f.ignoreValue;
|
||||
// Per-finding severity promotion (e.g. hero-region pulsing dot)
|
||||
// overrides the registry default carried by finding().
|
||||
if (f.severity && f.severity !== item.severity) item.severity = f.severity;
|
||||
return item;
|
||||
}), options.providers);
|
||||
}
|
||||
|
||||
@@ -2,7 +2,7 @@ import { GENERIC_FONTS, OVERUSED_FONTS } from '../../shared/constants.mjs';
|
||||
import { isNeutralColor } from '../../shared/color.mjs';
|
||||
import { extractGoogleFontFamilies } from '../../shared/fonts.mjs';
|
||||
import { checkSourceDesignSystem } from '../../design-system.mjs';
|
||||
import { scanCssTextForGlow } from '../../rules/checks.mjs';
|
||||
import { scanCssTextForGlow, scanCssTextForMarquee, scanCssTextForRadialHalo } from '../../rules/checks.mjs';
|
||||
import { isFullPage } from '../../shared/page.mjs';
|
||||
import { applyInlineIgnores } from '../../shared/inline-ignores.mjs';
|
||||
import { finding } from '../../findings.mjs';
|
||||
@@ -326,6 +326,17 @@ const REGEX_ANALYZERS = [
|
||||
const lines = content.substring(0, hits[0].index).split('\n');
|
||||
return [finding('dark-glow', filePath, hits[0].snippet, lines.length)];
|
||||
},
|
||||
// Radial-gradient background halo on a dark page (the gradient sibling
|
||||
// of the dark-glow shadow tell).
|
||||
(content, filePath) => {
|
||||
const hits = scanCssTextForRadialHalo(content);
|
||||
if (hits.length === 0) return [];
|
||||
const lines = content.substring(0, hits[0].index).split('\n');
|
||||
return [finding('radial-halo', filePath, hits[0].snippet, lines.length)];
|
||||
},
|
||||
// Auto-scrolling marquees (<marquee> or infinite horizontal loop
|
||||
// animations).
|
||||
(content, filePath) => scanCssTextForMarquee(content).map(hit => finding('marquee', filePath, hit.snippet)),
|
||||
];
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
@@ -2,7 +2,7 @@ import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import { profileStep, recordProfileEvent } from '../../profile/profiler.mjs';
|
||||
import { parseAnyColor, resolveLengthPx, resolveVarRefs } from '../../rules/checks.mjs';
|
||||
import { collectCssCustomProps, cssLengthToPx, parseAnyColor, resolveLengthPx, resolveVarRefs } from '../../rules/checks.mjs';
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// jsdom CSS-variable border override map
|
||||
@@ -425,6 +425,22 @@ function extractStaticColor(value) {
|
||||
if (!value) return '';
|
||||
const raw = String(value).trim();
|
||||
if (/^var\(/i.test(raw)) return raw;
|
||||
// color-mix(...) needs balanced-paren capture (its arguments regularly
|
||||
// contain nested var()/oklch() calls AND the keyword `transparent`, which
|
||||
// the flat regex below would otherwise pluck out of the middle of the
|
||||
// expression and report as the whole color).
|
||||
const mixStart = raw.search(/color-mix\(/i);
|
||||
if (mixStart !== -1) {
|
||||
let depth = 0;
|
||||
for (let i = raw.indexOf('(', mixStart); i < raw.length; i++) {
|
||||
if (raw[i] === '(') depth++;
|
||||
else if (raw[i] === ')') {
|
||||
depth--;
|
||||
if (depth === 0) return raw.slice(mixStart, i + 1);
|
||||
}
|
||||
}
|
||||
return '';
|
||||
}
|
||||
const colorLike = raw.match(/(?:rgba?\([^)]+\)|oklch\([^)]+\)|oklab\([^)]+\)|lch\([^)]+\)|lab\([^)]+\)|hsla?\([^)]+\)|hwb\([^)]+\)|#[0-9a-f]{3,8}\b|\b(?:black|white|gray|grey|silver|red|green|blue|transparent)\b)/i);
|
||||
if (!colorLike) return '';
|
||||
return colorLike[0];
|
||||
@@ -537,6 +553,15 @@ function expandStaticDeclaration(prop, value) {
|
||||
const beforeImage = hasImage ? v.split(/(?:repeating-)?(?:linear|radial|conic)-gradient\(|url\(/i)[0] : v;
|
||||
const color = extractStaticColor(hasImage ? beforeImage : v);
|
||||
if (color) out.push(['backgroundColor', color]);
|
||||
// The `background` shorthand resets every longhand it does not set.
|
||||
// Without this, `pre code { background: none }` leaves an earlier
|
||||
// `background: var(--surface)` color standing and the contrast checks
|
||||
// measure text against a surface the browser never paints. var() values
|
||||
// stay untouched: they may resolve to a color later in the pipeline.
|
||||
if (!color && !hasImage && !/var\(/i.test(v)) {
|
||||
out.push(['backgroundColor', 'rgba(0, 0, 0, 0)']);
|
||||
out.push(['backgroundImage', 'none']);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
if (p === 'border') {
|
||||
@@ -707,7 +732,20 @@ function collectStaticCssRules(cssText, csstree) {
|
||||
});
|
||||
});
|
||||
for (const selector of splitCssList(selectorText)) {
|
||||
if (selector) rules.push({ selector, declarations, specificity: staticSpecificity(selector), order: order++ });
|
||||
if (!selector) continue;
|
||||
// :hover rules can't be matched statically as-is (no interaction
|
||||
// state), but they carry real cascade weight while hovered. Tag
|
||||
// them and record a state-stripped selector so the hover pass can
|
||||
// find their targets; specificity stays computed from the ORIGINAL
|
||||
// selector (per CSS, :hover counts as a class).
|
||||
const isHover = /:hover\b/i.test(selector);
|
||||
let matchSelector = null;
|
||||
if (isHover) {
|
||||
matchSelector = selector.replace(/:hover\b/gi, '').trim();
|
||||
if (!matchSelector || /[>+~]\s*$/.test(matchSelector)) matchSelector = null;
|
||||
else matchSelector = matchSelector.replace(/(^|[\s>+~])(?=$|[\s>+~])/g, '$1*');
|
||||
}
|
||||
rules.push({ selector, declarations, specificity: staticSpecificity(selector), order: order++, isHover, matchSelector });
|
||||
}
|
||||
return;
|
||||
}
|
||||
@@ -810,6 +848,13 @@ class StaticDocument {
|
||||
this.domutils = modules.domutils;
|
||||
this._wrappers = new WeakMap();
|
||||
this._styleMap = new WeakMap();
|
||||
this._hoverStyleMap = new WeakMap();
|
||||
this._accentDashPseudo = new WeakSet();
|
||||
// Elements whose ::before/::after paints a full-cover opaque surface
|
||||
// (position absolute/fixed + inset 0 + solid background). The pseudo is
|
||||
// the element's visible background for contrast purposes even though it
|
||||
// never joins the element cascade.
|
||||
this._pseudoSurface = new WeakMap();
|
||||
}
|
||||
wrap(node) {
|
||||
let wrapped = this._wrappers.get(node);
|
||||
@@ -846,6 +891,24 @@ class StaticDocument {
|
||||
getStyle(el) {
|
||||
return this._styleMap.get(el.node) || makeStaticStyle();
|
||||
}
|
||||
setHoverStyle(node, style) {
|
||||
this._hoverStyleMap.set(node, style);
|
||||
}
|
||||
getHoverStyle(el) {
|
||||
return this._hoverStyleMap.get(el.node) || null;
|
||||
}
|
||||
setAccentDashPseudo(node) {
|
||||
this._accentDashPseudo.add(node);
|
||||
}
|
||||
hasAccentDashPseudo(el) {
|
||||
return this._accentDashPseudo.has(el.node);
|
||||
}
|
||||
setPseudoSurface(node, color) {
|
||||
this._pseudoSurface.set(node, color);
|
||||
}
|
||||
getPseudoSurface(el) {
|
||||
return this._pseudoSurface.get(el.node) || null;
|
||||
}
|
||||
}
|
||||
|
||||
function makeStaticStyle(values = {}) {
|
||||
@@ -861,6 +924,9 @@ function buildStaticWindow(staticDoc) {
|
||||
return {
|
||||
document: staticDoc,
|
||||
getComputedStyle: (el) => staticDoc.getStyle(el),
|
||||
getHoverStyle: (el) => staticDoc.getHoverStyle(el),
|
||||
hasAccentDashPseudo: (el) => staticDoc.hasAccentDashPseudo(el),
|
||||
getPseudoSurface: (el) => staticDoc.getPseudoSurface(el),
|
||||
};
|
||||
}
|
||||
|
||||
@@ -891,6 +957,13 @@ function collectStaticCssText(root, fileDir, profile, filePath, modules) {
|
||||
|
||||
function buildStaticStyleMap(root, staticDoc, cssText, modules, profile, filePath) {
|
||||
const specified = new Map();
|
||||
// Declarations from :hover rules, matched via their state-stripped
|
||||
// selectors. Merged per-property against the resting cascade in
|
||||
// computeNode — a hover declaration only takes effect if it would win
|
||||
// the cascade while the element is hovered (all resting rules still
|
||||
// apply in that state).
|
||||
const hoverSpecified = new Map();
|
||||
const rootCustomProps = collectCssCustomProps(cssText);
|
||||
const allNodes = modules.selectAll('*', root.children || []);
|
||||
const rules = profileStep(profile, {
|
||||
engine: 'static-html',
|
||||
@@ -906,9 +979,65 @@ function buildStaticStyleMap(root, staticDoc, cssText, modules, profile, filePat
|
||||
target: filePath,
|
||||
}, () => {
|
||||
for (const rule of rules) {
|
||||
// ::before/::after rules can't join the element cascade (pseudo
|
||||
// elements aren't DOM nodes), but one shape matters to the eyebrow
|
||||
// check: the short chromatic "kicker dash" (content box 8-80px wide,
|
||||
// 1-6px tall, accent-colored fill). Mark the base-selector matches
|
||||
// so checkElementHeroEyebrow can see the dash.
|
||||
if (!rule.isHover) {
|
||||
const pm = rule.selector.match(/^(.+?)\s*::?(?:before|after)$/i);
|
||||
if (pm) {
|
||||
const decls = new Map();
|
||||
for (const d of rule.declarations) decls.set(d.prop.toLowerCase(), d.value);
|
||||
const w = cssLengthToPx(resolveVarRefs(decls.get('width') || decls.get('inline-size') || '', rootCustomProps));
|
||||
const h = cssLengthToPx(resolveVarRefs(decls.get('height') || decls.get('block-size') || '', rootCustomProps));
|
||||
if (w != null && h != null && w >= 8 && w <= 80 && h >= 1 && h <= 6) {
|
||||
const bgRaw = String(resolveVarRefs(decls.get('background-color') || decls.get('background') || '', rootCustomProps));
|
||||
const token = bgRaw.match(/(?:rgba?|hsla?|oklch|oklab|lab|lch|hwb|color-mix)\([^)]*(?:\([^)]*\))?[^)]*\)|#[0-9a-f]{3,8}\b/i);
|
||||
const c = parseAnyColor(token ? token[0] : bgRaw);
|
||||
if (c && (c.a ?? 1) >= 0.1 && Math.max(c.r, c.g, c.b) - Math.min(c.r, c.g, c.b) >= 30) {
|
||||
try {
|
||||
for (const node of modules.selectAll(pm[1], root.children || [])) {
|
||||
staticDoc.setAccentDashPseudo(node);
|
||||
}
|
||||
} catch { /* unsupported base selector */ }
|
||||
}
|
||||
}
|
||||
// Full-cover surface pseudo: the CTA construction where the
|
||||
// element itself stays transparent and a ::before/::after with
|
||||
// position absolute/fixed + inset 0 (or all four sides 0, or
|
||||
// 100% width and height) plus an opaque background paints the
|
||||
// visible surface. Mark base-selector matches so the contrast
|
||||
// checks measure text against the surface the browser renders.
|
||||
const pseudoPos = String(decls.get('position') || '').toLowerCase();
|
||||
if (pseudoPos === 'absolute' || pseudoPos === 'fixed') {
|
||||
const zeroLen = v => v != null && /^0(?:px)?$/.test(String(v).trim());
|
||||
const insetRaw = String(decls.get('inset') || '').trim();
|
||||
const coversBox = (insetRaw !== '' && insetRaw.split(/\s+/).every(t => /^0(?:px)?$/.test(t)))
|
||||
|| ['top', 'right', 'bottom', 'left'].every(side => zeroLen(decls.get(side)))
|
||||
|| (String(decls.get('width') || '').trim() === '100%'
|
||||
&& String(decls.get('height') || '').trim() === '100%');
|
||||
if (coversBox && decls.has('content')) {
|
||||
const surfRaw = String(resolveVarRefs(decls.get('background-color') || decls.get('background') || '', rootCustomProps));
|
||||
const surfToken = surfRaw.match(/(?:rgba?|hsla?|oklch|oklab|lab|lch|hwb|color-mix)\([^)]*(?:\([^)]*\))?[^)]*\)|#[0-9a-f]{3,8}\b/i);
|
||||
const surf = parseAnyColor(surfToken ? surfToken[0] : surfRaw);
|
||||
if (surf && (surf.a ?? 1) >= 0.9 && !/gradient/i.test(surfRaw)) {
|
||||
try {
|
||||
for (const node of modules.selectAll(pm[1], root.children || [])) {
|
||||
staticDoc.setPseudoSurface(node, surf);
|
||||
}
|
||||
} catch { /* unsupported base selector */ }
|
||||
}
|
||||
}
|
||||
}
|
||||
continue;
|
||||
}
|
||||
}
|
||||
const matchSelector = rule.isHover ? rule.matchSelector : rule.selector;
|
||||
if (!matchSelector) continue;
|
||||
let matched;
|
||||
try {
|
||||
matched = modules.selectAll(rule.selector, root.children || []);
|
||||
matched = modules.selectAll(matchSelector, root.children || []);
|
||||
} catch {
|
||||
recordProfileEvent(profile, {
|
||||
engine: 'static-html',
|
||||
@@ -917,13 +1046,13 @@ function buildStaticStyleMap(root, staticDoc, cssText, modules, profile, filePat
|
||||
target: filePath,
|
||||
ms: 0,
|
||||
findings: 0,
|
||||
detail: rule.selector,
|
||||
detail: matchSelector,
|
||||
});
|
||||
continue;
|
||||
}
|
||||
for (const node of matched) {
|
||||
for (const decl of rule.declarations) {
|
||||
applyStaticDeclaration(specified, node, decl.prop, decl.value, {
|
||||
applyStaticDeclaration(rule.isHover ? hoverSpecified : specified, node, decl.prop, decl.value, {
|
||||
important: decl.important,
|
||||
specificity: rule.specificity,
|
||||
order: rule.order,
|
||||
@@ -966,6 +1095,28 @@ function buildStaticStyleMap(root, staticDoc, cssText, modules, profile, filePat
|
||||
}
|
||||
const style = makeStaticStyle(values);
|
||||
staticDoc.setStyle(node, style);
|
||||
|
||||
// Hover pass: limited to the two properties the hover-contrast check
|
||||
// consumes. A hover declaration wins only if it beats the resting
|
||||
// winner for that property under normal cascade rules (specificity /
|
||||
// order / importance) — exactly what a browser computes while the
|
||||
// element is hovered.
|
||||
const hoverMap = hoverSpecified.get(node);
|
||||
if (hoverMap) {
|
||||
let hoverValues = null;
|
||||
for (const prop of ['color', 'backgroundColor']) {
|
||||
const hoverDecl = hoverMap.get(prop);
|
||||
if (!hoverDecl) continue;
|
||||
const restingDecl = specifiedMap.get(prop);
|
||||
if (!compareStaticPriority(restingDecl, hoverDecl)) continue;
|
||||
const next = normalizeStaticCssValue(prop, hoverDecl.value, customProps, parentStyle, values);
|
||||
if (next === values[prop]) continue;
|
||||
if (!hoverValues) hoverValues = { ...values };
|
||||
hoverValues[prop] = next;
|
||||
}
|
||||
if (hoverValues) staticDoc.setHoverStyle(node, makeStaticStyle(hoverValues));
|
||||
}
|
||||
|
||||
for (const child of node.children || []) {
|
||||
if (child.type === 'tag') computeNode(child, style, customProps);
|
||||
}
|
||||
|
||||
@@ -18,6 +18,7 @@ import {
|
||||
checkElementGlow,
|
||||
checkElementGptBorderShadow,
|
||||
checkElementHeroEyebrow,
|
||||
checkElementHoverContrast,
|
||||
checkElementIconTile,
|
||||
checkElementItalicSerif,
|
||||
checkElementMotion,
|
||||
@@ -25,8 +26,10 @@ import {
|
||||
checkElementQuality,
|
||||
checkCreamPalette,
|
||||
checkHtmlPatterns,
|
||||
checkNumberedSectionLabelsFromDoc,
|
||||
checkPageLayout,
|
||||
checkPageQualityFromDoc,
|
||||
checkRepeatedContainerTextFromDoc,
|
||||
checkRepeatedSectionKickersFromDoc,
|
||||
resolveBackground,
|
||||
resolveBorderRadiusPx,
|
||||
@@ -90,8 +93,9 @@ function checkElementBrokenImage(el) {
|
||||
}
|
||||
|
||||
const STATIC_ELEMENT_RULES = [
|
||||
{ id: 'border-rules', selector: '*', run: (el, tag, style, window, customPropMap) => checkElementBorders(tag, style, null, resolveBorderRadiusPx(el, style, parseFloat(style.width) || 0, window)) },
|
||||
{ id: 'border-rules', selector: '*', run: (el, tag, style, window, customPropMap) => checkElementBorders(tag, style, null, resolveBorderRadiusPx(el, style, parseFloat(style.width) || 0, window), el) },
|
||||
{ id: 'color-rules', selector: '*', run: (el, tag, style, window, customPropMap) => checkElementColors(el, style, tag, window, customPropMap, false) },
|
||||
{ id: 'hover-color-rules', selector: '*', run: (el, tag, style, window) => checkElementHoverContrast(el, style, tag, window) },
|
||||
{ id: 'dark-glow', selector: '*', run: (el, tag, style, window, customPropMap) => checkElementGlow(tag, style, resolveBackground(el.parentElement || el, window, customPropMap)) },
|
||||
{ id: 'motion-rules', selector: '*', run: (el, tag, style) => checkElementMotion(tag, style) },
|
||||
{ id: 'icon-tile-stack', selector: 'h1,h2,h3,h4,h5,h6', run: (el, tag, _style, window) => checkElementIconTile(el, tag, window) },
|
||||
@@ -200,6 +204,12 @@ async function detectHtml(filePath, options = {}) {
|
||||
for (const f of runPageCheck('repeated-section-kickers', () => checkRepeatedSectionKickersFromDoc(document, window))) {
|
||||
findings.push(finding(f.id, filePath, f.snippet));
|
||||
}
|
||||
for (const f of runPageCheck('numbered-section-labels', () => checkNumberedSectionLabelsFromDoc(document, window))) {
|
||||
findings.push(finding(f.id, filePath, f.snippet));
|
||||
}
|
||||
for (const f of runPageCheck('repeated-container-text', () => checkRepeatedContainerTextFromDoc(document, window))) {
|
||||
findings.push(finding(f.id, filePath, f.snippet));
|
||||
}
|
||||
for (const f of runPageCheck('layout-rules', () => checkPageLayout(document, window))) {
|
||||
findings.push(finding(f.id, filePath, f.snippet));
|
||||
}
|
||||
@@ -212,7 +222,12 @@ async function detectHtml(filePath, options = {}) {
|
||||
for (const f of runPageCheck('html-patterns', () => checkHtmlPatterns(html).filter(item =>
|
||||
item.id !== 'bounce-easing' && item.id !== 'layout-transition'
|
||||
))) {
|
||||
findings.push(finding(f.id, filePath, f.snippet));
|
||||
const item = finding(f.id, filePath, f.snippet);
|
||||
// Position-aware severity promotion: checks may attach a per-finding
|
||||
// severity (e.g. a pulsing dot inside a header/nav landmark) that
|
||||
// overrides the registry default.
|
||||
if (f.severity) item.severity = f.severity;
|
||||
findings.push(item);
|
||||
}
|
||||
// Text-content analyzers (em-dash overuse, marketing buzzwords,
|
||||
// numbered section markers, aphoristic cadence) live in the regex
|
||||
|
||||
@@ -6,7 +6,7 @@ function getAP(id) {
|
||||
|
||||
function finding(id, filePath, snippet, line = 0) {
|
||||
const ap = getAP(id);
|
||||
return { antipattern: id, name: ap.name, description: ap.description, severity: ap.severity || 'warning', file: filePath, line, snippet };
|
||||
return { antipattern: id, name: ap.name, description: ap.description, severity: ap.severity || 'warning', category: ap.category || null, file: filePath, line, snippet };
|
||||
}
|
||||
|
||||
export { getAP, finding };
|
||||
|
||||
@@ -104,6 +104,33 @@ const ANTIPATTERNS = [
|
||||
skillSection: 'Motion',
|
||||
skillGuideline: 'bounce or elastic easing',
|
||||
},
|
||||
{
|
||||
id: 'pulsing-dot',
|
||||
category: 'slop',
|
||||
name: 'Pulsing status dot',
|
||||
description:
|
||||
'Small pulsing status dots simulate liveness decoratively. Reserve pulse animation for indicators tied to genuinely live, changing data; a static indicator with clear labeling is honest and calmer.',
|
||||
skillSection: 'Motion',
|
||||
skillGuideline: 'decorative pulsing status dot',
|
||||
},
|
||||
{
|
||||
id: 'blinking-cursor',
|
||||
category: 'slop',
|
||||
severity: 'advisory',
|
||||
name: 'Decorative blinking cursor',
|
||||
description:
|
||||
'A blinking text cursor animated into a hero or landing section simulates typing where no input exists. It borrows the dev-tool aesthetic as decoration. Real editable fields draw their own caret; anywhere else, let the composition hold attention without a fake prompt.',
|
||||
skillSection: 'Motion',
|
||||
},
|
||||
{
|
||||
id: 'shape-assembled-illustration',
|
||||
category: 'slop',
|
||||
severity: 'advisory',
|
||||
name: 'Shape-assembled illustration',
|
||||
description:
|
||||
'A large inline SVG that builds a pictorial scene from a pile of primitive shapes reads as placeholder clip art, not illustration. Icons, logos, and data graphics are fine at their scale; a hero-sized visual deserves real artwork, a photograph, or a deliberately drawn graphic.',
|
||||
skillSection: 'Imagery',
|
||||
},
|
||||
{
|
||||
id: 'dark-glow',
|
||||
category: 'slop',
|
||||
@@ -113,6 +140,24 @@ const ANTIPATTERNS = [
|
||||
skillSection: 'Color & Contrast',
|
||||
skillGuideline: 'dark mode with glowing accents',
|
||||
},
|
||||
{
|
||||
id: 'radial-halo',
|
||||
category: 'slop',
|
||||
name: 'Radial-gradient background halo',
|
||||
description:
|
||||
'A chromatic radial-gradient wash — saturated at the center, fading to transparent — used as a decorative background glow on a dark page. Same tell as glowing shadows, drawn with a gradient instead of a shadow. Ground the surface with a solid or subtly shifted background instead.',
|
||||
skillSection: 'Color & Contrast',
|
||||
skillGuideline: 'dark mode with glowing accents',
|
||||
},
|
||||
{
|
||||
id: 'marquee',
|
||||
category: 'slop',
|
||||
name: 'Auto-scrolling marquee',
|
||||
description:
|
||||
'Continuously auto-scrolling content demands attention it has not earned and hides half its content at any moment. Reserve motion for content that changes; let readers move at their own pace.',
|
||||
skillSection: 'Motion',
|
||||
skillGuideline: 'auto-scrolling marquee',
|
||||
},
|
||||
{
|
||||
id: 'icon-tile-stack',
|
||||
category: 'slop',
|
||||
@@ -154,6 +199,17 @@ const ANTIPATTERNS = [
|
||||
skillSection: 'Typography',
|
||||
skillGuideline: 'repeated eyebrow or kicker labels as section scaffolding',
|
||||
},
|
||||
{
|
||||
id: 'numbered-section-labels',
|
||||
category: 'slop',
|
||||
scopes: ['type'],
|
||||
severity: 'advisory',
|
||||
name: 'Tiny numbered section labels',
|
||||
description:
|
||||
'Small numeric index labels riding next to section headings, repeated section after section, are AI editorial scaffolding — a page numbering its own chapters instead of earning structure. Let hierarchy, content, and rhythm carry the sequence.',
|
||||
skillSection: 'Layout & Space',
|
||||
skillGuideline: 'numbered section markers',
|
||||
},
|
||||
{
|
||||
id: 'numbered-section-markers',
|
||||
category: 'slop',
|
||||
@@ -223,6 +279,49 @@ const ANTIPATTERNS = [
|
||||
},
|
||||
|
||||
// ── Quality: general design and accessibility issues ──
|
||||
{
|
||||
id: 'script-error',
|
||||
category: 'quality',
|
||||
severity: 'error',
|
||||
name: 'Uncaught script error on load',
|
||||
description:
|
||||
'A script threw an uncaught exception or failed to parse while the page loaded. Broken JavaScript silently kills reveals, interactions, and dynamic content, and can leave most of a page invisible. Fix the error before judging anything else.',
|
||||
},
|
||||
{
|
||||
id: 'content-hidden-at-rest',
|
||||
category: 'quality',
|
||||
severity: 'error',
|
||||
scopes: ['layout'],
|
||||
name: 'Content invisible at rest',
|
||||
description:
|
||||
'A large share of the page text sits at opacity 0 or visibility hidden even after every reveal handler had a chance to run. This is the failed-reveal signature: the content shipped but never becomes visible. Make content visible by default and let JavaScript enhance its entrance instead of gating its existence.',
|
||||
},
|
||||
{
|
||||
id: 'edge-flush-cards',
|
||||
category: 'quality',
|
||||
scopes: ['layout'],
|
||||
name: 'Cards flush against the scroller edge',
|
||||
description:
|
||||
'Cards inside a horizontal scroller or tab panel sit flush against the container edge at rest while keeping a gutter on the other side, so their edges and rounded corners get cut off. Usually the panel is sized wider than its clip box. Keep a consistent inset on both sides.',
|
||||
},
|
||||
{
|
||||
id: 'text-occlusion',
|
||||
category: 'quality',
|
||||
scopes: ['layout'],
|
||||
name: 'Text occluded by an overlapping element',
|
||||
description:
|
||||
'Text is painted under an opaque element or a second text run, so part of it cannot be read. A decorative box, a stacked layer, or an inline element with leaked padding lands on the words instead of beside them. Give overlapping layers room, or move the text out from under the layer above it.',
|
||||
skillSection: 'Layout & Space',
|
||||
},
|
||||
{
|
||||
id: 'first-viewport-column-overflow',
|
||||
category: 'quality',
|
||||
scopes: ['layout'],
|
||||
name: 'One column stretches the first viewport',
|
||||
description:
|
||||
'A multi-column opening section lets one column run far past the fold while its sibling fits in a single viewport, so the short column floats in dead space and the fold falls deep inside one section. Balance the columns, cap the tall one, or let the long content flow below the opening row.',
|
||||
skillSection: 'Layout & Space',
|
||||
},
|
||||
{
|
||||
id: 'gray-on-color',
|
||||
category: 'quality',
|
||||
@@ -292,6 +391,15 @@ const ANTIPATTERNS = [
|
||||
description:
|
||||
'Heading levels should not skip (e.g. h1 then h3 with no h2). Screen readers use heading hierarchy for navigation. Skipping levels breaks the document outline.',
|
||||
},
|
||||
{
|
||||
id: 'heading-rhythm',
|
||||
category: 'quality',
|
||||
scopes: ['layout', 'type'],
|
||||
name: 'Heading crowded against the previous block',
|
||||
description:
|
||||
'A heading binds to the content it introduces, so the rendered space above it should exceed the space below it. When headings across a page sit as close or closer to the block above than to their own content, every section reads as if it captions the previous one. Open up the space above each heading.',
|
||||
skillSection: 'Layout & Space',
|
||||
},
|
||||
{
|
||||
id: 'justified-text',
|
||||
category: 'quality',
|
||||
@@ -336,6 +444,13 @@ const ANTIPATTERNS = [
|
||||
skillSection: 'Layout & Space',
|
||||
skillGuideline: 'content wider than its container',
|
||||
},
|
||||
{
|
||||
id: 'repeated-container-text',
|
||||
category: 'quality',
|
||||
name: 'Same text repeated inside one container',
|
||||
description:
|
||||
'The same literal text rendered three or more times in structurally different spots inside a single card or panel is redundant messaging — usually a status or label wired into every slot of a template. Say it once, in the slot where it matters most.',
|
||||
},
|
||||
{
|
||||
id: 'clipped-overflow-container',
|
||||
category: 'quality',
|
||||
@@ -418,7 +533,7 @@ const ANTIPATTERNS = [
|
||||
gated: 'gpt',
|
||||
name: 'Decorative grid-line background',
|
||||
description:
|
||||
'A two-axis grid drawn with hairline linear-gradient layers ("1px, transparent 1px" on both axes) is a recurring generated-UI signature. Reserve grid overlays for actual canvas, map, blueprint, or measurement surfaces; elsewhere use product structure or a plain surface.',
|
||||
'A decorative grid or line-field background drawn with hairline linear-gradient layers tiled by a fixed pixel cell is a recurring generated-UI signature. Reserve grid overlays for actual canvas, map, blueprint, or measurement surfaces; elsewhere use product structure or a plain surface.',
|
||||
skillSection: 'Visual Details',
|
||||
skillGuideline: 'two-axis grid-line gradient background',
|
||||
},
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -26,6 +26,7 @@
|
||||
* loadDetector() -> Promise<{ detectText, detectHtml }>
|
||||
* matchesAnyGlob(filePath, globs)
|
||||
* normalizeScanTargets(primaryTargets, projectCwd)
|
||||
* extractDirectionContract(content) / renderContractAudit(entries, opts)
|
||||
* runHook(deps) -> { exitCode, stdout, audit, reason? }
|
||||
* runStopHook(deps) -> { exitCode, stdout, audit, emission? }
|
||||
*
|
||||
@@ -1842,6 +1843,76 @@ export async function runHook({ stdinJson, env = {}, cwd = process.cwd(), now =
|
||||
}
|
||||
}
|
||||
|
||||
// ── Direction-contract audit ─────────────────────────────────────────────
|
||||
// The skill's decide-then-build step opens the built HTML artifact with a
|
||||
// DIRECTION CONTRACT comment (UNIQUE / NOT-TEMPLATE / OWN-WORLD / STORY /
|
||||
// FIRST VIEWPORT / FORM blocks). At Stop time the deep pass extracts that
|
||||
// comment and feeds it back so the model audits the render against its own
|
||||
// promises. Proven in the eval harness: sample contracts promised radical
|
||||
// compositions and the build shipped the standard template anyway, because
|
||||
// nothing ever judged the build against the contract. Zero extra API calls:
|
||||
// this is a message, not a judge. It fires at most once per file per session
|
||||
// (a `contractAudited` flag on the session cache entry, the same state the
|
||||
// deep pass uses for finding dedupe) and rides the Stop pass's existing
|
||||
// emission rather than adding another block round.
|
||||
|
||||
// How far into the file to look for the leading comment. A contract lives at
|
||||
// the very top of the artifact; anything deeper is not the contract.
|
||||
export const CONTRACT_HEAD_CHARS = 6000;
|
||||
// The contract/concept marker must appear early in the comment body, so a
|
||||
// license header or unrelated note does not get mistaken for a contract.
|
||||
export const CONTRACT_MARKER_CHARS = 200;
|
||||
// Cap the extracted contract so a rambling comment cannot blow up the
|
||||
// Stop message.
|
||||
export const CONTRACT_MAX_CHARS = 1800;
|
||||
// Cap contract sections per Stop emission so many touched artifacts cannot
|
||||
// stack an unbounded message.
|
||||
export const CONTRACT_AUDIT_MAX_FILES = 3;
|
||||
|
||||
/**
|
||||
* Extract the artifact's own direction-contract comment: the first HTML
|
||||
* comment in the head of the file, when its opening chars identify it as a
|
||||
* contract/concept block. Returns the trimmed, length-capped body, or null
|
||||
* when the file carries none (no comment, unclosed comment, marker missing,
|
||||
* or the comment starts past the head window).
|
||||
*/
|
||||
export function extractDirectionContract(content) {
|
||||
if (typeof content !== 'string' || !content) return null;
|
||||
const head = content.slice(0, CONTRACT_HEAD_CHARS);
|
||||
const m = /<!--([\s\S]*?)-->/.exec(head);
|
||||
if (!m) return null;
|
||||
const body = m[1].trim();
|
||||
if (!body || !/contract|concept/i.test(body.slice(0, CONTRACT_MARKER_CHARS))) return null;
|
||||
return body.slice(0, CONTRACT_MAX_CHARS);
|
||||
}
|
||||
|
||||
/**
|
||||
* Render the contract-audit section of the Stop message. `entries` is
|
||||
* [{ filePath, contract }]; at most CONTRACT_AUDIT_MAX_FILES are shown.
|
||||
* The two failure shapes named here are the ones observed in practice:
|
||||
* a promise the pixels do not deliver, and a contract whose own plan is
|
||||
* the standard template wearing the concept's nouns.
|
||||
*/
|
||||
export function renderContractAudit(entries, opts = {}) {
|
||||
if (!Array.isArray(entries) || entries.length === 0) return '';
|
||||
const cwd = opts.cwd || process.cwd();
|
||||
const shown = entries.slice(0, CONTRACT_AUDIT_MAX_FILES);
|
||||
const blocks = shown.map(({ filePath, contract }) => {
|
||||
const display = relativize(filePath, cwd);
|
||||
return `${display} opens with this direction contract, written when the direction was decided:\n\n${contract}`;
|
||||
});
|
||||
return [
|
||||
`${ENVELOPE_PREFIX} Direction-contract audit. Before finishing, audit the rendered page against the contract it opens with, promise by promise.`,
|
||||
'',
|
||||
blocks.join('\n\n'),
|
||||
'',
|
||||
'Two failure shapes to check honestly:',
|
||||
'1. A promise that is not in the pixels: the contract describes a composition or structure the built page does not deliver, because the build fell back to a standard arrangement, possibly one the contract explicitly rejects. Rebuild that part until the render matches the promise.',
|
||||
"2. A contract whose own section plan is the standard template wearing the concept's nouns: if a neighboring product could ship the same sequence of sections under different labels, revise the plan and the page together.",
|
||||
'State each promise and whether the render delivers it, and fix every gap before finishing.',
|
||||
].join('\n');
|
||||
}
|
||||
|
||||
// Cap on files the Stop deep pass will scan. The touched-file list is
|
||||
// session-scoped and already capped per edit, but a very long session could
|
||||
// accumulate more than the 30s hook timeout comfortably covers.
|
||||
@@ -1850,7 +1921,10 @@ export const STOP_MAX_FILES = 20;
|
||||
/**
|
||||
* Run the Stop-event deep pass: the FULL detector rule set over every UI
|
||||
* file touched this session, surfaced once, deduped against everything the
|
||||
* per-edit hook already reported. Same result contract as runHook():
|
||||
* per-edit hook already reported. Touched HTML artifacts that open with a
|
||||
* direction-contract comment additionally get a one-time contract-audit
|
||||
* section appended after the detector findings (see extractDirectionContract
|
||||
* above). Same result contract as runHook():
|
||||
* { exitCode, stdout, audit, emission? }
|
||||
*
|
||||
* Never throws; exits silent (and fast) when the session touched no UI
|
||||
@@ -1917,6 +1991,7 @@ export async function runStopHook({ stdinJson, env = {}, cwd = process.cwd(), no
|
||||
const scanOptions = designSystemOptions(config, det, projectCwd);
|
||||
|
||||
const freshGroups = [];
|
||||
const contractEntries = [];
|
||||
let scanned = 0;
|
||||
for (const filePath of touched) {
|
||||
if (scanned >= STOP_MAX_FILES) break;
|
||||
@@ -1937,6 +2012,22 @@ export async function runStopHook({ stdinJson, env = {}, cwd = process.cwd(), no
|
||||
const useHtmlEngine = configuredExt
|
||||
? configuredExt.engine === 'html'
|
||||
: (ext === '.html' || ext === '.htm');
|
||||
|
||||
// Direction-contract audit: HTML artifacts only, at most once per file
|
||||
// per session. The flag lives on the same session cache entry the
|
||||
// finding dedupe uses, so a second Stop fire stays quiet about it.
|
||||
if (useHtmlEngine) {
|
||||
const fileEntry = ensureFile(cache, sessionId, filePath);
|
||||
if (!fileEntry.contractAudited) {
|
||||
const contract = extractDirectionContract(content);
|
||||
if (contract) {
|
||||
fileEntry.contractAudited = true;
|
||||
ensureSession(cache, sessionId).updatedAt = Date.now();
|
||||
contractEntries.push({ filePath, contract });
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (useHtmlEngine && typeof det.detectHtml === 'function') {
|
||||
try { findings = await det.detectHtml(filePath, scanOptions); } catch { findings = []; }
|
||||
} else {
|
||||
@@ -1955,24 +2046,41 @@ export async function runStopHook({ stdinJson, env = {}, cwd = process.cwd(), no
|
||||
}
|
||||
audit.scannedFiles = scanned;
|
||||
|
||||
if (freshGroups.length === 0) {
|
||||
if (freshGroups.length === 0 && contractEntries.length === 0) {
|
||||
return result({ emitted: false, skipped: 'stop-clean', durationMs: Date.now() - started });
|
||||
}
|
||||
|
||||
// Fresh findings earn the cache write; they also mark this batch as
|
||||
// surfaced so the next Stop fire is silent unless new issues appear.
|
||||
// Fresh findings and first-time contract audits earn the cache write;
|
||||
// both mark this batch as surfaced so the next Stop fire is silent
|
||||
// unless new issues appear.
|
||||
persistCache(projectCwd, cache);
|
||||
|
||||
const text = appendDesignSystemNote(renderGroupedTemplate(freshGroups, config, { cwd: projectCwd }), scanOptions);
|
||||
// Detector findings first, then the contract audit. Both ride the same
|
||||
// single Stop emission: the audit never adds an extra block round.
|
||||
const parts = [];
|
||||
if (freshGroups.length > 0) {
|
||||
parts.push(renderGroupedTemplate(freshGroups, config, { cwd: projectCwd }));
|
||||
}
|
||||
if (contractEntries.length > 0) {
|
||||
parts.push(renderContractAudit(contractEntries, { cwd: projectCwd }));
|
||||
}
|
||||
const text = appendDesignSystemNote(parts.join('\n\n'), scanOptions);
|
||||
return {
|
||||
exitCode: 0,
|
||||
stdout: payload(text, 'Stop', harness),
|
||||
emission: { kind: 'stop-deep-pass', groups: freshGroups },
|
||||
emission: {
|
||||
kind: 'stop-deep-pass',
|
||||
groups: freshGroups,
|
||||
...(contractEntries.length > 0
|
||||
? { contractFiles: contractEntries.map((entry) => entry.filePath) }
|
||||
: {}),
|
||||
},
|
||||
audit: {
|
||||
...audit,
|
||||
emitted: true,
|
||||
freshFiles: freshGroups.length,
|
||||
freshFindings: freshGroups.reduce((sum, group) => sum + group.findings.length, 0),
|
||||
...(contractEntries.length > 0 ? { contractAudits: contractEntries.length } : {}),
|
||||
chars: text.length,
|
||||
durationMs: Date.now() - started,
|
||||
},
|
||||
|
||||
@@ -10,7 +10,9 @@
|
||||
* `hookSpecificOutput.additionalContext` when findings exist.
|
||||
* - Stop: runs the FULL detector rule set over every UI file touched this
|
||||
* session (the deep pass), deduped against what the per-edit pass already
|
||||
* surfaced, and emits once via the Stop additionalContext channel.
|
||||
* surfaced, and emits once via the Stop additionalContext channel. Touched
|
||||
* HTML artifacts opening with a direction-contract comment get a one-time
|
||||
* contract-audit section appended to the same emission.
|
||||
*
|
||||
* Contract: never break a turn. Always exit 0. Clean files emit a small ack
|
||||
* unless quiet mode is enabled; a clean Stop pass is silent.
|
||||
|
||||
@@ -60,6 +60,10 @@ export function getLiveServerPath(cwd = process.cwd(), options = {}) {
|
||||
return path.join(getLiveDir(cwd, options), 'server.json');
|
||||
}
|
||||
|
||||
export function getLiveCodexWorkerStatePath(cwd = process.cwd(), options = {}) {
|
||||
return path.join(getLiveDir(cwd, options), 'codex-worker.json');
|
||||
}
|
||||
|
||||
export function getLegacyLiveServerPath(cwd = process.cwd(), options = {}) {
|
||||
return path.join(resolveProjectRoot(cwd, options), '.impeccable-live.json');
|
||||
}
|
||||
|
||||
@@ -16,15 +16,27 @@
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { isGeneratedFile } from './lib/is-generated.mjs';
|
||||
import { getLiveDir } from './lib/impeccable-paths.mjs';
|
||||
import { readBuffer as readManualEditsBuffer, writeBuffer as writeManualEditsBuffer } from './live/manual-edits-buffer.mjs';
|
||||
import { withSourceLockSync } from './live/source-lock.mjs';
|
||||
import {
|
||||
applyDeferredSvelteComponentAccepts,
|
||||
findSvelteComponentManifest,
|
||||
inlineSvelteComponentAccept,
|
||||
removeSvelteComponentSession,
|
||||
} from './live/svelte-component.mjs';
|
||||
import {
|
||||
findVueComponentManifest,
|
||||
inlineVueComponentAccept,
|
||||
retireVueComponentSession,
|
||||
} from './live/vue-component.mjs';
|
||||
import {
|
||||
findSourceArtifactManifest,
|
||||
removeSourceArtifactSession,
|
||||
} from './live/source-artifact.mjs';
|
||||
|
||||
const EXTENSIONS = ['.html', '.jsx', '.tsx', '.vue', '.svelte', '.astro'];
|
||||
const ACCEPT_LOCK_WAIT_MS = 1_000;
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// CLI
|
||||
@@ -65,6 +77,32 @@ Output (JSON):
|
||||
if (!id) { console.error('Missing --id'); process.exit(1); }
|
||||
if (!isDiscard && !variantNum) { console.error('Need --discard or --variant N'); process.exit(1); }
|
||||
|
||||
const requestedOperation = isDiscard ? 'discard' : 'accept';
|
||||
const priorReceipt = readAcceptReceipt(process.cwd(), id);
|
||||
if (priorReceipt) {
|
||||
const sameOperation = priorReceipt.operation === requestedOperation
|
||||
&& (isDiscard || String(priorReceipt.variantId) === String(variantNum));
|
||||
console.log(JSON.stringify(sameOperation
|
||||
? { ...priorReceipt.result, handled: true, alreadyApplied: true }
|
||||
: {
|
||||
handled: false,
|
||||
error: 'accept_receipt_conflict',
|
||||
priorOperation: priorReceipt.operation,
|
||||
priorVariantId: priorReceipt.variantId ?? null,
|
||||
}));
|
||||
return;
|
||||
}
|
||||
const emitResult = (result) => {
|
||||
if (result?.handled !== false) {
|
||||
writeAcceptReceipt(process.cwd(), id, {
|
||||
operation: requestedOperation,
|
||||
variantId: isDiscard ? null : String(variantNum),
|
||||
result,
|
||||
});
|
||||
}
|
||||
console.log(JSON.stringify(result));
|
||||
};
|
||||
|
||||
let paramValues = null;
|
||||
if (paramValuesRaw) {
|
||||
try { paramValues = JSON.parse(paramValuesRaw); }
|
||||
@@ -72,34 +110,147 @@ Output (JSON):
|
||||
}
|
||||
|
||||
// Find the file containing this session's markers
|
||||
const found = findSessionFile(id, process.cwd());
|
||||
const sourceArtifactManifest = findSourceArtifactManifest(id, process.cwd());
|
||||
const found = sourceArtifactManifest ? null : findSessionFile(id, process.cwd());
|
||||
const svelteComponentManifest = found ? null : findSvelteComponentManifest(id, process.cwd());
|
||||
const vueComponentManifest = found || svelteComponentManifest ? null : findVueComponentManifest(id, process.cwd());
|
||||
|
||||
if (!found && !svelteComponentManifest) {
|
||||
if (!found && !sourceArtifactManifest && !svelteComponentManifest && !vueComponentManifest) {
|
||||
console.log(JSON.stringify({ handled: false, error: 'Session markers not found for id: ' + id }));
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
if (svelteComponentManifest) {
|
||||
if (sourceArtifactManifest) {
|
||||
if (isDiscard) {
|
||||
removeSvelteComponentSession(id, process.cwd());
|
||||
console.log(JSON.stringify({
|
||||
removeSourceArtifactSession(id, process.cwd());
|
||||
emitResult({
|
||||
handled: true,
|
||||
file: svelteComponentManifest.sourceFile,
|
||||
file: sourceArtifactManifest.sourceFile,
|
||||
sourceFile: sourceArtifactManifest.sourceFile,
|
||||
previewMode: sourceArtifactManifest.previewMode,
|
||||
carbonize: false,
|
||||
previewMode: 'svelte-component',
|
||||
componentDir: svelteComponentManifest.componentDir,
|
||||
}));
|
||||
});
|
||||
return;
|
||||
}
|
||||
|
||||
let result;
|
||||
try {
|
||||
result = inlineSvelteComponentAccept(
|
||||
svelteComponentManifest,
|
||||
variantNum,
|
||||
paramValues,
|
||||
process.cwd(),
|
||||
result = withSourceLockSync(
|
||||
sourceArtifactManifest.sourcePath,
|
||||
'accept:' + id,
|
||||
() => acceptSourceArtifact(sourceArtifactManifest, variantNum, paramValues),
|
||||
{ waitMs: ACCEPT_LOCK_WAIT_MS },
|
||||
);
|
||||
} catch (err) {
|
||||
result = { handled: false, error: err.message };
|
||||
}
|
||||
if (result.handled !== false) {
|
||||
removeSourceArtifactSession(id, process.cwd());
|
||||
try {
|
||||
scrubManualEditsAgainstOriginalBlock(result.acceptedOriginalText || '', process.cwd(), pageUrl);
|
||||
} catch {}
|
||||
}
|
||||
delete result.acceptedOriginalText;
|
||||
if (result.carbonize) {
|
||||
result.todo = 'REQUIRED before next poll: carbonize cleanup in ' + sourceArtifactManifest.sourceFile + '. See reference/live.md "Required after accept".';
|
||||
}
|
||||
emitResult({
|
||||
handled: result.handled !== false,
|
||||
file: sourceArtifactManifest.sourceFile,
|
||||
sourceFile: sourceArtifactManifest.sourceFile,
|
||||
previewMode: sourceArtifactManifest.previewMode,
|
||||
...result,
|
||||
});
|
||||
return;
|
||||
}
|
||||
|
||||
if (vueComponentManifest) {
|
||||
if (isDiscard) {
|
||||
let result;
|
||||
try {
|
||||
result = withSourceLockSync(
|
||||
path.resolve(process.cwd(), vueComponentManifest.sourceFile),
|
||||
'discard:' + id,
|
||||
() => {
|
||||
retireVueComponentSession(id, process.cwd());
|
||||
return { handled: true };
|
||||
},
|
||||
{ waitMs: ACCEPT_LOCK_WAIT_MS },
|
||||
);
|
||||
} catch (err) {
|
||||
result = { handled: false, error: err.message };
|
||||
}
|
||||
emitResult({
|
||||
...result,
|
||||
file: vueComponentManifest.sourceFile,
|
||||
carbonize: false,
|
||||
previewMode: 'vue-component',
|
||||
componentDir: vueComponentManifest.componentDir,
|
||||
});
|
||||
return;
|
||||
}
|
||||
|
||||
let result;
|
||||
try {
|
||||
result = withSourceLockSync(
|
||||
path.resolve(process.cwd(), vueComponentManifest.sourceFile),
|
||||
'accept:' + id,
|
||||
() => inlineVueComponentAccept(vueComponentManifest, variantNum, process.cwd()),
|
||||
{ waitMs: ACCEPT_LOCK_WAIT_MS },
|
||||
);
|
||||
} catch (err) {
|
||||
result = {
|
||||
handled: false,
|
||||
error: err.message,
|
||||
file: vueComponentManifest.sourceFile,
|
||||
sourceFile: vueComponentManifest.sourceFile,
|
||||
previewMode: 'vue-component',
|
||||
componentDir: vueComponentManifest.componentDir,
|
||||
carbonize: false,
|
||||
};
|
||||
}
|
||||
emitResult(result);
|
||||
return;
|
||||
}
|
||||
|
||||
if (svelteComponentManifest) {
|
||||
if (isDiscard) {
|
||||
let result;
|
||||
try {
|
||||
result = withSourceLockSync(
|
||||
path.resolve(process.cwd(), svelteComponentManifest.sourceFile),
|
||||
'discard:' + id,
|
||||
() => {
|
||||
removeSvelteComponentSession(id, process.cwd());
|
||||
return { handled: true };
|
||||
},
|
||||
{ waitMs: ACCEPT_LOCK_WAIT_MS },
|
||||
);
|
||||
} catch (err) {
|
||||
result = { handled: false, error: err.message };
|
||||
}
|
||||
emitResult({
|
||||
...result,
|
||||
file: svelteComponentManifest.sourceFile,
|
||||
carbonize: false,
|
||||
previewMode: 'svelte-component',
|
||||
componentDir: svelteComponentManifest.componentDir,
|
||||
});
|
||||
return;
|
||||
}
|
||||
|
||||
let result;
|
||||
try {
|
||||
result = withSourceLockSync(
|
||||
path.resolve(process.cwd(), svelteComponentManifest.sourceFile),
|
||||
'accept:' + id,
|
||||
() => inlineSvelteComponentAccept(
|
||||
svelteComponentManifest,
|
||||
variantNum,
|
||||
paramValues,
|
||||
process.cwd(),
|
||||
),
|
||||
{ waitMs: ACCEPT_LOCK_WAIT_MS },
|
||||
);
|
||||
} catch (err) {
|
||||
result = {
|
||||
@@ -114,7 +265,7 @@ Output (JSON):
|
||||
if (result.carbonize) {
|
||||
result.todo = 'REQUIRED before next poll: carbonize cleanup in ' + result.file + '. See reference/live.md "Required after accept".';
|
||||
}
|
||||
console.log(JSON.stringify({ handled: result.handled !== false, ...result }));
|
||||
emitResult({ handled: result.handled !== false, ...result });
|
||||
return;
|
||||
}
|
||||
|
||||
@@ -146,7 +297,7 @@ Output (JSON):
|
||||
|
||||
if (isDiscard) {
|
||||
const result = handleDiscard(id, lines, targetFile);
|
||||
console.log(JSON.stringify({ handled: true, file: relFile, carbonize: false, ...result }));
|
||||
emitResult({ handled: true, file: relFile, carbonize: false, ...result });
|
||||
} else {
|
||||
const result = handleAccept(id, variantNum, lines, targetFile, paramValues);
|
||||
const acceptedOriginalText = result.acceptedOriginalText || '';
|
||||
@@ -167,7 +318,7 @@ Output (JSON):
|
||||
// Non-fatal; the buffer stays as-is and the user can discard later.
|
||||
}
|
||||
}
|
||||
console.log(JSON.stringify({ handled: true, file: relFile, ...result }));
|
||||
emitResult({ handled: true, file: relFile, ...result });
|
||||
}
|
||||
}
|
||||
|
||||
@@ -235,7 +386,14 @@ function scrubManualEditsAgainstFile(_targetFile, cwd = process.cwd(), originalB
|
||||
// Discard
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
function handleDiscard(id, lines, targetFile) {
|
||||
function handleDiscard(id, _lines, targetFile) {
|
||||
return withSourceLockSync(targetFile, 'discard:' + id, () => {
|
||||
const lines = fs.readFileSync(targetFile, 'utf-8').split('\n');
|
||||
return handleDiscardUnlocked(id, lines, targetFile);
|
||||
}, { waitMs: ACCEPT_LOCK_WAIT_MS });
|
||||
}
|
||||
|
||||
function handleDiscardUnlocked(id, lines, targetFile) {
|
||||
const block = findMarkerBlock(id, lines);
|
||||
if (!block) return { handled: false, error: 'Markers not found' };
|
||||
|
||||
@@ -330,7 +488,24 @@ function reindentContent(contentLines, fromIndent, toIndent) {
|
||||
});
|
||||
}
|
||||
|
||||
function handleAccept(id, variantNum, lines, targetFile, paramValues) {
|
||||
function handleAccept(id, variantNum, _lines, targetFile, paramValues) {
|
||||
return withSourceLockSync(targetFile, 'accept:' + id, () => {
|
||||
const lines = fs.readFileSync(targetFile, 'utf-8').split('\n');
|
||||
return handleAcceptUnlocked(id, variantNum, lines, targetFile, paramValues);
|
||||
}, { waitMs: ACCEPT_LOCK_WAIT_MS });
|
||||
}
|
||||
|
||||
function handleAcceptUnlocked(id, variantNum, lines, targetFile, paramValues) {
|
||||
const built = buildAcceptedWrappedSource(id, variantNum, lines, targetFile, paramValues);
|
||||
if (built.handled === false) return built;
|
||||
fs.writeFileSync(targetFile, built.content, 'utf-8');
|
||||
return {
|
||||
carbonize: built.carbonize,
|
||||
acceptedOriginalText: built.acceptedOriginalText,
|
||||
};
|
||||
}
|
||||
|
||||
function buildAcceptedWrappedSource(id, variantNum, lines, targetFile, paramValues) {
|
||||
const block = findMarkerBlock(id, lines);
|
||||
if (!block) return { handled: false, error: 'Markers not found' };
|
||||
|
||||
@@ -375,9 +550,38 @@ function handleAccept(id, variantNum, lines, targetFile, paramValues) {
|
||||
...replacement,
|
||||
...lines.slice(replaceRange.end + 1),
|
||||
];
|
||||
fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
|
||||
return {
|
||||
content: newLines.join('\n'),
|
||||
carbonize: needsCarbonize,
|
||||
acceptedOriginalText: originalContent.join('\n'),
|
||||
};
|
||||
}
|
||||
|
||||
return { carbonize: needsCarbonize, acceptedOriginalText: originalContent.join('\n') };
|
||||
function acceptSourceArtifact(manifest, variantNum, paramValues) {
|
||||
const source = fs.readFileSync(manifest.sourcePath, 'utf-8');
|
||||
const preview = fs.readFileSync(manifest.previewPath, 'utf-8');
|
||||
const original = String(manifest.originalSource || '');
|
||||
if (!original) return { handled: false, error: 'source_artifact_original_missing' };
|
||||
const first = source.indexOf(original);
|
||||
if (first < 0) return { handled: false, error: 'source_artifact_original_changed' };
|
||||
if (source.indexOf(original, first + original.length) >= 0) {
|
||||
return { handled: false, error: 'source_artifact_original_ambiguous' };
|
||||
}
|
||||
const wrapped = source.slice(0, first) + preview + source.slice(first + original.length);
|
||||
const built = buildAcceptedWrappedSource(
|
||||
manifest.id,
|
||||
variantNum,
|
||||
wrapped.split('\n'),
|
||||
manifest.sourcePath,
|
||||
paramValues,
|
||||
);
|
||||
if (built.handled === false) return built;
|
||||
fs.writeFileSync(manifest.sourcePath, built.content, 'utf-8');
|
||||
return {
|
||||
handled: true,
|
||||
carbonize: built.carbonize,
|
||||
acceptedOriginalText: built.acceptedOriginalText,
|
||||
};
|
||||
}
|
||||
|
||||
function readSourceShadowPreviewMeta(content, id) {
|
||||
@@ -798,6 +1002,28 @@ function searchDir(dir, query, seen, depth) {
|
||||
// Utilities
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
function acceptReceiptPath(cwd, id) {
|
||||
return path.join(getLiveDir(cwd), 'accept-receipts', `${id}.json`);
|
||||
}
|
||||
|
||||
function readAcceptReceipt(cwd, id) {
|
||||
try { return JSON.parse(fs.readFileSync(acceptReceiptPath(cwd, id), 'utf-8')); } catch { return null; }
|
||||
}
|
||||
|
||||
function writeAcceptReceipt(cwd, id, receipt) {
|
||||
const file = acceptReceiptPath(cwd, id);
|
||||
fs.mkdirSync(path.dirname(file), { recursive: true });
|
||||
const value = {
|
||||
id,
|
||||
...receipt,
|
||||
completedAt: new Date().toISOString(),
|
||||
};
|
||||
const temporary = `${file}.${process.pid}.${Date.now()}.tmp`;
|
||||
fs.writeFileSync(temporary, JSON.stringify(value, null, 2) + '\n', 'utf-8');
|
||||
fs.renameSync(temporary, file);
|
||||
return value;
|
||||
}
|
||||
|
||||
function argVal(args, flag) {
|
||||
const idx = args.indexOf(flag);
|
||||
return idx !== -1 && idx + 1 < args.length ? args[idx + 1] : null;
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,292 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
import { spawn } from 'node:child_process';
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
|
||||
import { createCodexAppServerClient } from './live/codex-app-server-client.mjs';
|
||||
import {
|
||||
CODEX_CLI_SETUP_URL,
|
||||
CODEX_WORKER_OWNER,
|
||||
codexWorkerProcessStateIsOwned,
|
||||
codexWorkerStateIsOwned,
|
||||
resolveCodexExecutable,
|
||||
resolveCodexWorkerConfig,
|
||||
} from './live/codex-worker.mjs';
|
||||
import { CodexLiveWorkerSupervisor } from './live/codex-worker-supervisor.mjs';
|
||||
import {
|
||||
getLiveCodexWorkerStatePath,
|
||||
readLiveServerInfo,
|
||||
resolveLiveConfigPath,
|
||||
} from './lib/impeccable-paths.mjs';
|
||||
|
||||
const args = process.argv.slice(2);
|
||||
const cwd = process.cwd();
|
||||
const scriptPath = fileURLToPath(import.meta.url);
|
||||
const scriptsDir = path.dirname(scriptPath);
|
||||
const statePath = getLiveCodexWorkerStatePath(cwd);
|
||||
|
||||
if (args.includes('--help') || args.includes('-h')) {
|
||||
console.log(`Usage: node live-codex-worker.mjs [--background [--no-wait] | --status | --stop]
|
||||
|
||||
Codex Live generation supervisor. It owns a separate
|
||||
app-server process and dedicated worker thread; it never attaches to the
|
||||
foreground desktop task.
|
||||
|
||||
It is enabled by default when a Codex runtime signal is present. Set
|
||||
IMPECCABLE_LIVE_CODEX_WORKER=0 to use the portable foreground path.
|
||||
Project config may tune the worker but cannot activate it across harnesses.
|
||||
|
||||
Optional environment:
|
||||
IMPECCABLE_LIVE_CODEX_PROFILE quality (default) or fast
|
||||
IMPECCABLE_LIVE_CODEX_MODEL Model override; otherwise a quality model is selected dynamically
|
||||
IMPECCABLE_LIVE_CODEX_EFFORT Reasoning effort override (default: medium)
|
||||
IMPECCABLE_CODEX_PATH Codex binary path (default: codex)
|
||||
|
||||
Outside Codex this command exits without polling, leaving the portable
|
||||
foreground Live path unchanged.`);
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
if (args.includes('--status')) {
|
||||
const state = readJson(statePath);
|
||||
console.log(JSON.stringify(state
|
||||
? { ...state, reachable: pidReachable(state.pid) }
|
||||
: { ok: false, status: 'not_started' }));
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
if (args.includes('--stop')) {
|
||||
const state = readJson(statePath);
|
||||
if (state?.pid && !codexWorkerProcessStateIsOwned(state, cwd)) {
|
||||
console.log(JSON.stringify({
|
||||
ok: false,
|
||||
status: 'not_stopped',
|
||||
error: 'codex_worker_state_unowned',
|
||||
}));
|
||||
process.exitCode = 2;
|
||||
process.exit();
|
||||
}
|
||||
if (!state?.pid || !pidReachable(state.pid)) {
|
||||
console.log(JSON.stringify({ ok: true, status: 'not_running' }));
|
||||
process.exit(0);
|
||||
}
|
||||
process.kill(state.pid, 'SIGTERM');
|
||||
const stopped = await waitFor(
|
||||
() => !pidReachable(state.pid),
|
||||
positiveInteger(process.env.IMPECCABLE_LIVE_CODEX_STOP_TIMEOUT_MS, 5_000),
|
||||
);
|
||||
if (!stopped) {
|
||||
console.log(JSON.stringify({ ok: false, status: 'stop_timeout', pid: state.pid }));
|
||||
process.exitCode = 2;
|
||||
process.exit();
|
||||
}
|
||||
console.log(JSON.stringify({ ok: true, status: 'stopped', pid: state.pid }));
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
const liveConfig = readLiveConfig(cwd);
|
||||
const config = resolveCodexWorkerConfig({ env: process.env, liveConfig });
|
||||
if (!config.enabled) {
|
||||
console.log(JSON.stringify({
|
||||
ok: false,
|
||||
error: 'codex_worker_disabled',
|
||||
fallback: 'foreground',
|
||||
}));
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
if (args.includes('--background')) {
|
||||
const existing = readJson(statePath);
|
||||
if (codexWorkerProcessStateIsOwned(existing, cwd)
|
||||
&& existing?.pid
|
||||
&& pidReachable(existing.pid)
|
||||
&& ['starting', 'ready', 'working'].includes(existing.status)) {
|
||||
console.log(JSON.stringify({ ...existing, ok: true, reused: true }));
|
||||
process.exit(0);
|
||||
}
|
||||
}
|
||||
|
||||
const executable = resolveCodexExecutable(config.codexPath, { cwd, env: process.env });
|
||||
if (!executable.available) {
|
||||
const unavailable = writeState({
|
||||
ok: false,
|
||||
owner: CODEX_WORKER_OWNER,
|
||||
pid: null,
|
||||
status: 'unavailable',
|
||||
mode: 'foreground',
|
||||
error: executable.error,
|
||||
command: executable.command,
|
||||
message: 'Codex CLI not found. Live is using the main agent for generation.',
|
||||
setup: {
|
||||
docsUrl: CODEX_CLI_SETUP_URL,
|
||||
afterInstall: 'codex login',
|
||||
},
|
||||
});
|
||||
console.log(JSON.stringify({ ...unavailable, fallback: 'foreground' }));
|
||||
process.exit(0);
|
||||
}
|
||||
config.codexPath = executable.resolvedPath;
|
||||
|
||||
if (args.includes('--background')) {
|
||||
fs.mkdirSync(path.dirname(statePath), { recursive: true });
|
||||
const logPath = path.join(path.dirname(statePath), 'codex-worker.log');
|
||||
const logFd = fs.openSync(logPath, 'a');
|
||||
const child = spawn(process.execPath, [scriptPath, '--foreground'], {
|
||||
cwd,
|
||||
env: process.env,
|
||||
detached: true,
|
||||
stdio: ['ignore', logFd, logFd],
|
||||
});
|
||||
child.unref();
|
||||
fs.closeSync(logFd);
|
||||
const observed = readJson(statePath);
|
||||
const starting = observed?.pid === child.pid && ['ready', 'working'].includes(observed.status)
|
||||
? observed
|
||||
: writeState({
|
||||
ok: true,
|
||||
owner: CODEX_WORKER_OWNER,
|
||||
pid: child.pid,
|
||||
status: 'starting',
|
||||
threadId: null,
|
||||
model: config.model,
|
||||
effort: config.effort,
|
||||
profile: config.profile,
|
||||
delivery: config.delivery,
|
||||
});
|
||||
if (args.includes('--no-wait')) {
|
||||
console.log(JSON.stringify({ ...starting, ok: true, starting: true, logPath }));
|
||||
process.exit(0);
|
||||
}
|
||||
const ready = await waitFor(() => {
|
||||
const state = readJson(statePath);
|
||||
if (state?.pid !== child.pid) return null;
|
||||
if (state.status === 'error') return state;
|
||||
return ['ready', 'working'].includes(state.status) ? state : null;
|
||||
}, positiveInteger(process.env.IMPECCABLE_LIVE_CODEX_START_TIMEOUT_MS, 12_000));
|
||||
if (!ready || ready.status === 'error') {
|
||||
let terminated = true;
|
||||
if (pidReachable(child.pid)) {
|
||||
process.kill(child.pid, 'SIGTERM');
|
||||
terminated = Boolean(await waitFor(
|
||||
() => !pidReachable(child.pid),
|
||||
positiveInteger(process.env.IMPECCABLE_LIVE_CODEX_STOP_TIMEOUT_MS, 2_000),
|
||||
));
|
||||
}
|
||||
console.log(JSON.stringify({
|
||||
ok: false,
|
||||
error: ready?.error || 'codex_worker_start_timeout',
|
||||
fallback: terminated ? 'foreground' : null,
|
||||
terminated,
|
||||
childPid: child.pid,
|
||||
logPath,
|
||||
}));
|
||||
process.exitCode = 2;
|
||||
} else {
|
||||
console.log(JSON.stringify({ ...ready, ok: true, logPath }));
|
||||
}
|
||||
process.exit();
|
||||
}
|
||||
|
||||
await runForeground();
|
||||
|
||||
async function runForeground() {
|
||||
const server = readLiveServerInfo(cwd)?.info;
|
||||
if (!server?.port || !server?.token) {
|
||||
writeState({ ok: false, status: 'error', error: 'live_server_not_running' });
|
||||
process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
const client = createCodexAppServerClient({
|
||||
command: config.codexPath,
|
||||
cwd,
|
||||
requestTimeoutMs: 30_000,
|
||||
turnTimeoutMs: 240_000,
|
||||
clientInfo: {
|
||||
name: 'impeccable_live',
|
||||
title: 'Impeccable Live dedicated worker',
|
||||
version: '0.1.0',
|
||||
},
|
||||
});
|
||||
const supervisor = new CodexLiveWorkerSupervisor({
|
||||
cwd,
|
||||
base: `http://localhost:${server.port}`,
|
||||
token: server.token,
|
||||
client,
|
||||
config,
|
||||
statePath,
|
||||
scriptsDir,
|
||||
log: (message) => process.stderr.write(`[impeccable-codex-worker] ${message}\n`),
|
||||
});
|
||||
let shuttingDown = false;
|
||||
const shutdown = async () => {
|
||||
if (shuttingDown) return;
|
||||
shuttingDown = true;
|
||||
await supervisor.shutdown({ archive: true }).catch(() => {});
|
||||
process.exit(0);
|
||||
};
|
||||
process.once('SIGINT', shutdown);
|
||||
process.once('SIGTERM', shutdown);
|
||||
try {
|
||||
await supervisor.initialize();
|
||||
await supervisor.run();
|
||||
} catch (error) {
|
||||
writeState({
|
||||
ok: false,
|
||||
status: 'error',
|
||||
error: error.message,
|
||||
stack: error.stack,
|
||||
});
|
||||
await supervisor.shutdown().catch(() => {});
|
||||
process.exitCode = 1;
|
||||
}
|
||||
}
|
||||
|
||||
function readLiveConfig(projectCwd) {
|
||||
const configPath = resolveLiveConfigPath({ cwd: projectCwd, scriptsDir });
|
||||
return readJson(configPath) || {};
|
||||
}
|
||||
|
||||
function writeState(value) {
|
||||
fs.mkdirSync(path.dirname(statePath), { recursive: true });
|
||||
const state = {
|
||||
cwd: path.resolve(cwd),
|
||||
pid: process.pid,
|
||||
updatedAt: new Date().toISOString(),
|
||||
...value,
|
||||
};
|
||||
const temporary = `${statePath}.${process.pid}.${Date.now()}.tmp`;
|
||||
fs.writeFileSync(temporary, JSON.stringify(state, null, 2) + '\n', 'utf-8');
|
||||
fs.renameSync(temporary, statePath);
|
||||
return state;
|
||||
}
|
||||
|
||||
function readJson(file) {
|
||||
try { return JSON.parse(fs.readFileSync(file, 'utf-8')); } catch { return null; }
|
||||
}
|
||||
|
||||
function pidReachable(pid) {
|
||||
if (!Number.isInteger(pid) || pid < 1) return false;
|
||||
try {
|
||||
process.kill(pid, 0);
|
||||
return true;
|
||||
} catch (error) {
|
||||
return error?.code === 'EPERM';
|
||||
}
|
||||
}
|
||||
|
||||
async function waitFor(check, timeoutMs) {
|
||||
const deadline = Date.now() + timeoutMs;
|
||||
while (Date.now() < deadline) {
|
||||
const result = check();
|
||||
if (result) return result;
|
||||
await new Promise((resolve) => setTimeout(resolve, 25));
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function positiveInteger(value, fallback) {
|
||||
const parsed = Number(value);
|
||||
return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
|
||||
}
|
||||
@@ -27,6 +27,8 @@ 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';
|
||||
const IGNORE_MARKER_OPEN = '# impeccable-live-ignore-start';
|
||||
const IGNORE_MARKER_CLOSE = '# impeccable-live-ignore-end';
|
||||
|
||||
@@ -35,9 +37,14 @@ export const LIVE_IGNORE_PATTERNS = Object.freeze([
|
||||
'.impeccable/hook.pending.json',
|
||||
'.impeccable/config.local.json',
|
||||
'.impeccable/live/server.json',
|
||||
'.impeccable/live/codex-worker.json',
|
||||
'.impeccable/live/codex-worker.log',
|
||||
'.impeccable/live/sessions/',
|
||||
'.impeccable/live/previews/',
|
||||
'.impeccable/live/annotations/',
|
||||
'.impeccable/live/artifacts/',
|
||||
'.impeccable/live/accept-receipts/',
|
||||
'.impeccable/live/locks/',
|
||||
'.impeccable/live/cache/',
|
||||
'.impeccable/live/manual-edit-apply-transaction.json',
|
||||
'.impeccable/live/manual-edit-events.jsonl',
|
||||
@@ -46,10 +53,15 @@ export const LIVE_IGNORE_PATTERNS = Object.freeze([
|
||||
'.impeccable/live/deferred-svelte-component-accepts.json',
|
||||
'.impeccable-live.json',
|
||||
'.impeccable-live/',
|
||||
'app/.impeccable-live/',
|
||||
'src/.impeccable-live/',
|
||||
'node_modules/.impeccable-live/',
|
||||
'src/lib/impeccable/ImpeccableLiveRoot.svelte',
|
||||
'src/lib/impeccable/__runtime.js',
|
||||
'src/lib/impeccable/[0-9a-f]*/',
|
||||
'plugins/impeccable-live.client.ts',
|
||||
'app/plugins/impeccable-live.client.ts',
|
||||
'src/plugins/impeccable-live.client.ts',
|
||||
]);
|
||||
|
||||
/**
|
||||
@@ -113,6 +125,7 @@ Output (JSON):
|
||||
|
||||
const resolvedFiles = resolveFiles(process.cwd(), config);
|
||||
const svelteKit = detectSvelteKitProject(process.cwd(), config);
|
||||
const nuxt = detectNuxtProject(process.cwd());
|
||||
|
||||
if (args.includes('--remove')) {
|
||||
if (svelteKit) {
|
||||
@@ -120,6 +133,12 @@ Output (JSON):
|
||||
console.log(JSON.stringify({ ok: true, adapter: 'sveltekit', results: [adapterResult] }));
|
||||
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;
|
||||
return;
|
||||
}
|
||||
const results = resolvedFiles.map((relFile) => {
|
||||
const absFile = path.resolve(process.cwd(), relFile);
|
||||
if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
|
||||
@@ -145,13 +164,28 @@ Output (JSON):
|
||||
console.error(JSON.stringify({ ok: false, error: 'missing_port' }));
|
||||
process.exit(1);
|
||||
}
|
||||
const gitIgnore = ensureLiveGitIgnores(process.cwd());
|
||||
const gitIgnore = ensureLiveGitIgnores(
|
||||
process.cwd(),
|
||||
nuxt ? [nuxt.pluginFile] : [],
|
||||
);
|
||||
|
||||
if (svelteKit) {
|
||||
const adapterResult = applySvelteKitLiveAdapter({ cwd: process.cwd(), port, config });
|
||||
console.log(JSON.stringify({ ok: true, port, adapter: 'sveltekit', gitIgnore, results: [adapterResult] }));
|
||||
return;
|
||||
}
|
||||
if (nuxt) {
|
||||
const adapterResult = applyNuxtLiveAdapter({ cwd: process.cwd(), port, project: nuxt });
|
||||
console.log(JSON.stringify({
|
||||
ok: !adapterResult.error,
|
||||
port,
|
||||
adapter: 'nuxt',
|
||||
gitIgnore,
|
||||
results: [adapterResult],
|
||||
}));
|
||||
if (adapterResult.error) process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
|
||||
const results = resolvedFiles.map((relFile) => {
|
||||
const absFile = path.resolve(process.cwd(), relFile);
|
||||
@@ -175,12 +209,12 @@ Output (JSON):
|
||||
if (!anyInserted) process.exit(1);
|
||||
}
|
||||
|
||||
export function ensureLiveGitIgnores(cwd = process.cwd()) {
|
||||
export function ensureLiveGitIgnores(cwd = process.cwd(), extraPatterns = []) {
|
||||
const target = resolveIgnoreTarget(cwd);
|
||||
const existing = fs.existsSync(target.path) ? fs.readFileSync(target.path, 'utf-8') : '';
|
||||
const block = [
|
||||
IGNORE_MARKER_OPEN,
|
||||
...LIVE_IGNORE_PATTERNS,
|
||||
...new Set([...LIVE_IGNORE_PATTERNS, ...extraPatterns]),
|
||||
IGNORE_MARKER_CLOSE,
|
||||
].join('\n');
|
||||
const markerRe = new RegExp(`${escapeRegExp(IGNORE_MARKER_OPEN)}[\\s\\S]*?${escapeRegExp(IGNORE_MARKER_CLOSE)}`);
|
||||
@@ -202,10 +236,119 @@ export function ensureLiveGitIgnores(cwd = process.cwd()) {
|
||||
file: path.relative(cwd, target.path).split(path.sep).join('/'),
|
||||
mode: target.mode,
|
||||
changed: updated !== existing,
|
||||
patterns: [...LIVE_IGNORE_PATTERNS],
|
||||
patterns: [...new Set([...LIVE_IGNORE_PATTERNS, ...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) {
|
||||
return `/* ${NUXT_PLUGIN_MARKER} */
|
||||
const liveSrc = 'http://localhost:${port}/live.js';
|
||||
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, 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);
|
||||
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) {
|
||||
|
||||
@@ -10,10 +10,12 @@
|
||||
*/
|
||||
|
||||
import { execFileSync } from 'node:child_process';
|
||||
import fs from 'node:fs';
|
||||
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 { getLiveCodexWorkerStatePath, readLiveServerInfo } from './lib/impeccable-paths.mjs';
|
||||
import { codexWorkerProcessStateIsOwned } from './live/codex-worker.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']);
|
||||
const EVENT_TYPES_NEEDING_AGENT_REPLY = new Set(['generate', 'steer', 'manual_edit_apply', 'carbonize_cleanup']);
|
||||
|
||||
function readServerInfo() {
|
||||
const record = readLiveServerInfo(process.cwd());
|
||||
@@ -38,8 +40,8 @@ function readServerInfo() {
|
||||
return record.info;
|
||||
}
|
||||
|
||||
export function buildPollReplyPayload(token, { id, type, message, file, data }) {
|
||||
return { token, id, type, message, file, data };
|
||||
export function buildPollReplyPayload(token, { id, type, message, file, data, sourceEventType }) {
|
||||
return { token, id, type, message, file, data, sourceEventType };
|
||||
}
|
||||
|
||||
export function manualApplyPollBanner(event = {}) {
|
||||
@@ -152,7 +154,14 @@ export async function waitForEventAck(base, token, eventId, {
|
||||
return false;
|
||||
}
|
||||
|
||||
export async function fetchNextEvent(base, token, { totalDeadline } = {}) {
|
||||
export async function fetchNextEvent(base, token, {
|
||||
totalDeadline,
|
||||
types,
|
||||
resolveTypes,
|
||||
perRequestTimeoutMs = PER_REQUEST_TIMEOUT_MS,
|
||||
leaseMs = DEFAULT_EVENT_LEASE_MS,
|
||||
signal,
|
||||
} = {}) {
|
||||
while (true) {
|
||||
if (totalDeadline && Date.now() >= totalDeadline) {
|
||||
return { type: 'timeout' };
|
||||
@@ -161,8 +170,15 @@ export async function fetchNextEvent(base, token, { totalDeadline } = {}) {
|
||||
const remaining = totalDeadline
|
||||
? totalDeadline - Date.now()
|
||||
: PER_REQUEST_TIMEOUT_MS;
|
||||
const slice = Math.min(Math.max(remaining, 1000), PER_REQUEST_TIMEOUT_MS);
|
||||
const res = await fetch(`${base}/poll?token=${token}&timeout=${slice}&leaseMs=${DEFAULT_EVENT_LEASE_MS}`);
|
||||
const slice = Math.min(Math.max(remaining, 1000), perRequestTimeoutMs);
|
||||
const query = new URLSearchParams({
|
||||
token,
|
||||
timeout: String(slice),
|
||||
leaseMs: String(leaseMs),
|
||||
});
|
||||
const normalizedTypes = normalizePollTypes(resolveTypes ? await resolveTypes() : types);
|
||||
if (normalizedTypes.length > 0) query.set('types', normalizedTypes.join(','));
|
||||
const res = await fetch(`${base}/poll?${query}`, { signal });
|
||||
|
||||
if (res.status === 401) {
|
||||
const err = new Error('Authentication failed. The server token may have changed.');
|
||||
@@ -184,7 +200,7 @@ export async function fetchNextEvent(base, token, { totalDeadline } = {}) {
|
||||
}
|
||||
}
|
||||
|
||||
export async function augmentEventWithAcceptHandling(event, base, token) {
|
||||
export async function augmentEventWithAcceptHandling(event, base, token, { deferReply = false } = {}) {
|
||||
if (event.type !== 'accept' && event.type !== 'discard') return event;
|
||||
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
||||
@@ -202,11 +218,21 @@ export async function augmentEventWithAcceptHandling(event, base, token) {
|
||||
event._acceptResult = { handled: false, mode: 'error', error: err.message };
|
||||
}
|
||||
|
||||
if (deferReply) {
|
||||
event._completionAck = { ok: false, deferred: true };
|
||||
return event;
|
||||
}
|
||||
await completeAcceptHandling(event, base, token);
|
||||
return event;
|
||||
}
|
||||
|
||||
export async function completeAcceptHandling(event, base, token) {
|
||||
const completionType = completionTypeForAcceptResult(event.type, event._acceptResult);
|
||||
try {
|
||||
await postReply(base, token, {
|
||||
id: event.id,
|
||||
type: completionType,
|
||||
sourceEventType: event.type,
|
||||
message: event._acceptResult?.error,
|
||||
file: event._acceptResult?.file,
|
||||
data: event._acceptResult?.carbonize === true ? { carbonize: true } : undefined,
|
||||
@@ -217,7 +243,6 @@ export async function augmentEventWithAcceptHandling(event, base, token) {
|
||||
if (!event._completionAck) {
|
||||
event._completionAck = completionAckForAcceptResult(event.id, completionType, event._acceptResult);
|
||||
}
|
||||
|
||||
return event;
|
||||
}
|
||||
|
||||
@@ -245,9 +270,9 @@ export function printPollEvent(event) {
|
||||
console.log(JSON.stringify(event));
|
||||
}
|
||||
|
||||
export async function runPollOnce(base, token, { totalTimeout = 600_000 } = {}) {
|
||||
export async function runPollOnce(base, token, { totalTimeout = 600_000, types, resolveTypes, perRequestTimeoutMs } = {}) {
|
||||
const deadline = Date.now() + totalTimeout;
|
||||
const event = await fetchNextEvent(base, token, { totalDeadline: deadline });
|
||||
const event = await fetchNextEvent(base, token, { totalDeadline: deadline, types, resolveTypes, perRequestTimeoutMs });
|
||||
await augmentEventWithAcceptHandling(event, base, token);
|
||||
writeCarbonizeBanner(event);
|
||||
printPollEvent(event);
|
||||
@@ -258,11 +283,14 @@ export async function runPollStream(base, token, {
|
||||
ackTimeoutMs = 600_000,
|
||||
ackPollIntervalMs = 400,
|
||||
shouldContinue = () => true,
|
||||
types,
|
||||
resolveTypes,
|
||||
perRequestTimeoutMs,
|
||||
} = {}) {
|
||||
process.stderr.write('[impeccable-poll] stream mode: one JSON object per line on stdout; use --reply while this process stays running\n');
|
||||
|
||||
while (shouldContinue()) {
|
||||
const event = await fetchNextEvent(base, token);
|
||||
const event = await fetchNextEvent(base, token, { types, resolveTypes, perRequestTimeoutMs });
|
||||
await augmentEventWithAcceptHandling(event, base, token);
|
||||
writeCarbonizeBanner(event);
|
||||
printPollEvent(event);
|
||||
@@ -322,14 +350,18 @@ Modes:
|
||||
|
||||
Options:
|
||||
--timeout=MS One-shot poll timeout in ms (default: 600000). Ignored in --stream mode
|
||||
--types=A,B Lease only these event types (used by partitioned Codex control lane)
|
||||
--codex-worker-fallback
|
||||
Add generation events only if the dedicated Codex worker fails or exits
|
||||
--ack-timeout=MS Stream mode: max wait for --reply after generate/steer (default: 600000)
|
||||
--file PATH Attach a source file path to the reply (generate/steer flow)
|
||||
--data JSON Attach a JSON result object to the reply (manual_edit_apply flow). Must be valid JSON
|
||||
--help Show this help message
|
||||
|
||||
Harness note:
|
||||
Default one-shot mode is the portable contract for Claude Code, Codex, and Cursor.
|
||||
--stream is experimental for harnesses with fast incremental stdout; do not use on Cursor.`);
|
||||
Default one-shot mode is the portable contract for Claude Code, Cursor, and foreground fallback.
|
||||
Codex uses --stream only for the dedicated worker's narrow foreground control lane.
|
||||
Do not use --stream on Cursor.`);
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
@@ -360,23 +392,55 @@ Harness note:
|
||||
}
|
||||
|
||||
const streamMode = args.includes('--stream');
|
||||
const typesArg = args.find((a) => a.startsWith('--types='));
|
||||
const types = normalizePollTypes(typesArg ? typesArg.slice('--types='.length) : null);
|
||||
const workerFallback = args.includes('--codex-worker-fallback');
|
||||
const resolveTypes = workerFallback ? () => resolveCodexWorkerFallbackTypes(types) : null;
|
||||
const perRequestTimeoutMs = workerFallback ? 2_000 : undefined;
|
||||
const ackTimeoutArg = args.find((a) => a.startsWith('--ack-timeout='));
|
||||
const ackTimeoutMs = ackTimeoutArg ? parseInt(ackTimeoutArg.split('=')[1], 10) : 600_000;
|
||||
|
||||
try {
|
||||
if (streamMode) {
|
||||
await runPollStream(base, info.token, { ackTimeoutMs });
|
||||
await runPollStream(base, info.token, { ackTimeoutMs, types, resolveTypes, perRequestTimeoutMs });
|
||||
return;
|
||||
}
|
||||
|
||||
const timeoutArg = args.find((a) => a.startsWith('--timeout='));
|
||||
const totalTimeout = timeoutArg ? parseInt(timeoutArg.split('=')[1], 10) : 600_000;
|
||||
await runPollOnce(base, info.token, { totalTimeout });
|
||||
await runPollOnce(base, info.token, { totalTimeout, types, resolveTypes, perRequestTimeoutMs });
|
||||
} catch (err) {
|
||||
handlePollError(err);
|
||||
}
|
||||
}
|
||||
|
||||
export function normalizePollTypes(value) {
|
||||
const values = Array.isArray(value) ? value : String(value || '').split(',');
|
||||
return [...new Set(values.map((type) => String(type).trim()).filter(Boolean))];
|
||||
}
|
||||
|
||||
export function resolveCodexWorkerFallbackTypes(baseTypes, {
|
||||
cwd = process.cwd(),
|
||||
state = readJson(getLiveCodexWorkerStatePath(cwd)),
|
||||
isPidReachable = pidReachable,
|
||||
} = {}) {
|
||||
const base = normalizePollTypes(baseTypes);
|
||||
const workerOwnsGeneration = codexWorkerProcessStateIsOwned(state, cwd)
|
||||
&& ['starting', 'ready', 'working'].includes(state?.status)
|
||||
&& isPidReachable(state?.pid);
|
||||
if (workerOwnsGeneration) return base;
|
||||
return normalizePollTypes([...base, 'generate', 'accept', 'discard', 'prefetch']);
|
||||
}
|
||||
|
||||
function readJson(file) {
|
||||
try { return JSON.parse(fs.readFileSync(file, 'utf-8')); } catch { return null; }
|
||||
}
|
||||
|
||||
function pidReachable(pid) {
|
||||
if (!Number.isInteger(pid) || pid <= 0) return false;
|
||||
try { process.kill(pid, 0); return true; } catch { return false; }
|
||||
}
|
||||
|
||||
// Auto-execute when run directly
|
||||
const _running = process.argv[1];
|
||||
if (_running?.endsWith('live-poll.mjs') || _running?.endsWith('live-poll.mjs/')) {
|
||||
|
||||
@@ -0,0 +1,37 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
import {
|
||||
prepareGenerationArtifact,
|
||||
publishGenerationArtifact,
|
||||
} from './live/generation-publisher.mjs';
|
||||
|
||||
const args = process.argv.slice(2);
|
||||
const result = args.includes('--prepare')
|
||||
? prepareGenerationArtifact({
|
||||
id: arg(args, '--id'),
|
||||
sourceFile: arg(args, '--file'),
|
||||
})
|
||||
: publishGenerationArtifact({
|
||||
id: arg(args, '--id'),
|
||||
epoch: Number(arg(args, '--epoch')),
|
||||
sourceFile: arg(args, '--file'),
|
||||
artifactFile: arg(args, '--artifact'),
|
||||
expectedSourceHash: arg(args, '--expected-source-hash'),
|
||||
arrivedVariants: optionalNumber(arg(args, '--arrived')),
|
||||
expectedVariants: optionalNumber(arg(args, '--expected')),
|
||||
publicationKind: arg(args, '--kind'),
|
||||
});
|
||||
|
||||
console.log(JSON.stringify(result));
|
||||
if (!result.ok) process.exitCode = 2;
|
||||
|
||||
function arg(values, name) {
|
||||
const index = values.indexOf(name);
|
||||
return index >= 0 ? values[index + 1] : undefined;
|
||||
}
|
||||
|
||||
function optionalNumber(value) {
|
||||
if (value === undefined) return undefined;
|
||||
const number = Number(value);
|
||||
return Number.isInteger(number) ? number : undefined;
|
||||
}
|
||||
@@ -29,11 +29,14 @@ import {
|
||||
resolveLiveBrowserScriptParts,
|
||||
} from './live/browser-script-parts.mjs';
|
||||
import { createLiveSessionStore } from './live/session-store.mjs';
|
||||
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 {
|
||||
getDesignSidecarPath,
|
||||
getLiveCodexWorkerStatePath,
|
||||
getLiveDir,
|
||||
getLiveAnnotationsDir,
|
||||
IMPECCABLE_COMMAND_PREFIX,
|
||||
@@ -51,6 +54,7 @@ import {
|
||||
applyDeferredSvelteComponentAccepts,
|
||||
removeAllSvelteComponentSessions,
|
||||
} from './live/svelte-component.mjs';
|
||||
import { removeAllVueComponentSessions } from './live/vue-component.mjs';
|
||||
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
||||
// PRODUCT.md / DESIGN.md live wherever context.mjs resolves. The generated
|
||||
@@ -156,29 +160,135 @@ function restorePendingEventsFromStore() {
|
||||
}
|
||||
}
|
||||
|
||||
function findAvailablePendingEvent(now = Date.now()) {
|
||||
for (const entry of state.pendingEvents) {
|
||||
if (entry.leaseUntil && entry.leaseUntil > now) continue;
|
||||
return entry;
|
||||
}
|
||||
return null;
|
||||
function findAvailablePendingEvent(now = Date.now(), types = null) {
|
||||
return selectAvailablePendingEvent(state.pendingEvents, { now, types });
|
||||
}
|
||||
|
||||
function leaseEvent(entry, leaseMs) {
|
||||
prepareGenerateEventForLease(entry);
|
||||
if (!entry.event?.id) {
|
||||
const idx = state.pendingEvents.indexOf(entry);
|
||||
if (idx !== -1) state.pendingEvents.splice(idx, 1);
|
||||
return entry.event;
|
||||
}
|
||||
entry.leaseUntil = Date.now() + leaseMs;
|
||||
recordGenerateDelivery(entry);
|
||||
scheduleLeaseFlush();
|
||||
broadcastAgentPollingIfChanged();
|
||||
return entry.event;
|
||||
}
|
||||
|
||||
function acknowledgePendingEvent(id) {
|
||||
function recordGenerateDelivery(entry) {
|
||||
const event = entry?.event;
|
||||
if (!event || event.type !== 'generate' || event.generationReadyAt) return;
|
||||
const at = Date.now();
|
||||
entry.event = { ...event, generationReadyAt: at };
|
||||
state.sessionStore?.appendEvent(entry.event);
|
||||
recordAgentPhase(event.id, 'generation_ready', { at });
|
||||
}
|
||||
|
||||
function prepareGenerateEventForLease(entry) {
|
||||
const event = entry?.event;
|
||||
if (!event || event.type !== 'generate' || event.scaffoldAttempted) return;
|
||||
|
||||
recordAgentPhase(event.id, 'picked_up');
|
||||
recordAgentPhase(event.id, 'scaffolding');
|
||||
const worker = getCodexWorkerStatus();
|
||||
const result = runGenerationPreflight(event, {
|
||||
cwd: process.cwd(),
|
||||
scriptsDir: __dirname,
|
||||
isolated: worker?.mode === 'dedicated-app-server' && worker?.reachable === true,
|
||||
});
|
||||
entry.event = {
|
||||
...event,
|
||||
scaffoldAttempted: true,
|
||||
scaffoldDurationMs: result.durationMs ?? null,
|
||||
...(result.ok ? { scaffold: result.scaffold } : { scaffoldError: result.error || result.reason }),
|
||||
};
|
||||
state.sessionStore?.appendEvent(entry.event);
|
||||
recordAgentPhase(event.id, result.ok ? 'source_ready' : 'scaffold_fallback', {
|
||||
durationMs: result.durationMs ?? null,
|
||||
previewMode: result.scaffold?.previewMode || 'source',
|
||||
});
|
||||
}
|
||||
|
||||
function recordAgentPhase(id, phase, details = {}) {
|
||||
if (!id) return;
|
||||
const event = {
|
||||
type: 'agent_phase',
|
||||
id,
|
||||
phase,
|
||||
at: Date.now(),
|
||||
...details,
|
||||
};
|
||||
state.sessionStore?.appendEvent(event);
|
||||
broadcast(event);
|
||||
}
|
||||
|
||||
function recordGenerationCheckpoint(event) {
|
||||
if (!event?.id || event.type !== 'checkpoint') return;
|
||||
if (generationIsFenced(event.id)) return;
|
||||
const arrived = Number(event.arrivedVariants) || 0;
|
||||
const expected = Number(event.expectedVariants) || 0;
|
||||
if (arrived <= 0 || expected <= 0) return;
|
||||
const previewMode = event.previewMode || 'source';
|
||||
const previewFile = event.previewFile || event.file;
|
||||
if (previewFile) {
|
||||
broadcast({
|
||||
type: 'variant_progress',
|
||||
id: event.id,
|
||||
file: previewFile,
|
||||
sourceFile: event.sourceFile || (previewMode === 'source' ? previewFile : undefined),
|
||||
previewFile,
|
||||
previewMode,
|
||||
arrivedVariants: arrived,
|
||||
expectedVariants: expected,
|
||||
publicationKind: event.publicationKind || 'variants',
|
||||
});
|
||||
}
|
||||
const details = {
|
||||
arrivedVariants: arrived,
|
||||
expectedVariants: expected,
|
||||
checkpointReason: event.reason || null,
|
||||
};
|
||||
const at = Date.now();
|
||||
if (!generationPhaseAlreadyRecorded(event.id, 'first_reviewable')) {
|
||||
recordAgentPhase(event.id, 'first_reviewable', { ...details, at });
|
||||
}
|
||||
if (arrived >= 2 && expected >= 3 && !generationPhaseAlreadyRecorded(event.id, 'second_reviewable')) {
|
||||
recordAgentPhase(event.id, 'second_reviewable', { ...details, at });
|
||||
}
|
||||
if (arrived >= expected && !generationPhaseAlreadyRecorded(event.id, 'all_variants_ready')) {
|
||||
recordAgentPhase(event.id, 'all_variants_ready', { ...details, at });
|
||||
}
|
||||
}
|
||||
|
||||
function generationIsFenced(id) {
|
||||
if (!state.sessionStore || !id) return false;
|
||||
try {
|
||||
const snapshot = state.sessionStore.getSnapshot(id, { includeCompleted: true });
|
||||
return snapshot?.generationCanceled === true;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
function generationPhaseAlreadyRecorded(id, phase) {
|
||||
if (!state.sessionStore) return false;
|
||||
try {
|
||||
const snapshot = state.sessionStore.getSnapshot(id, { includeCompleted: true });
|
||||
return !!snapshot?.generationTimings?.[phase];
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
function acknowledgePendingEvent(id, sourceEventType) {
|
||||
if (!id) return false;
|
||||
const idx = state.pendingEvents.findIndex((entry) => entry.event?.id === id);
|
||||
const idx = state.pendingEvents.findIndex((entry) => (
|
||||
entry.event?.id === id
|
||||
&& (!sourceEventType || entry.event?.type === sourceEventType)
|
||||
));
|
||||
if (idx === -1) return false;
|
||||
const acknowledged = state.pendingEvents[idx].event;
|
||||
state.pendingEvents.splice(idx, 1);
|
||||
@@ -187,9 +297,39 @@ function acknowledgePendingEvent(id) {
|
||||
return acknowledged;
|
||||
}
|
||||
|
||||
function findPendingEventById(id) {
|
||||
function releasePendingEvent(id, sourceEventType) {
|
||||
const entry = state.pendingEvents.find((item) => (
|
||||
item.event?.id === id
|
||||
&& (!sourceEventType || item.event?.type === sourceEventType)
|
||||
));
|
||||
if (!entry) return null;
|
||||
entry.leaseUntil = 0;
|
||||
scheduleLeaseFlush();
|
||||
return entry.event;
|
||||
}
|
||||
|
||||
function retirePendingGeneration(id) {
|
||||
if (!id) return 0;
|
||||
let retired = 0;
|
||||
for (let index = state.pendingEvents.length - 1; index >= 0; index -= 1) {
|
||||
const event = state.pendingEvents[index]?.event;
|
||||
if (event?.id !== id || event.type !== 'generate') continue;
|
||||
state.pendingEvents.splice(index, 1);
|
||||
retired += 1;
|
||||
}
|
||||
if (retired > 0) {
|
||||
scheduleLeaseFlush();
|
||||
broadcastAgentPollingIfChanged();
|
||||
}
|
||||
return retired;
|
||||
}
|
||||
|
||||
function findPendingEventById(id, sourceEventType) {
|
||||
if (!id) return null;
|
||||
const entry = state.pendingEvents.find((item) => item.event?.id === id);
|
||||
const entry = state.pendingEvents.find((item) => (
|
||||
item.event?.id === id
|
||||
&& (!sourceEventType || item.event?.type === sourceEventType)
|
||||
));
|
||||
return entry?.event || null;
|
||||
}
|
||||
|
||||
@@ -224,7 +364,13 @@ function summarizeActiveSessionForClient(snapshot = {}) {
|
||||
arrivedVariants: snapshot.arrivedVariants ?? 0,
|
||||
visibleVariant: snapshot.visibleVariant ?? null,
|
||||
checkpointRevision: snapshot.checkpointRevision ?? 0,
|
||||
browserCheckpointRevision: snapshot.browserCheckpointRevision ?? snapshot.checkpointRevision ?? 0,
|
||||
publicationCheckpointRevision: snapshot.publicationCheckpointRevision ?? 0,
|
||||
paramValues: snapshot.paramValues || {},
|
||||
paramsPublished: snapshot.paramsPublished === true,
|
||||
generationPhase: snapshot.generationPhase ?? null,
|
||||
generationCanceled: snapshot.generationCanceled === true,
|
||||
cancelReason: snapshot.cancelReason ?? null,
|
||||
};
|
||||
}
|
||||
|
||||
@@ -269,13 +415,21 @@ function scheduleLeaseFlush() {
|
||||
function flushPendingPolls() {
|
||||
let changed = false;
|
||||
while (state.pendingPolls.length > 0) {
|
||||
const entry = findAvailablePendingEvent();
|
||||
let pollIndex = -1;
|
||||
let entry = null;
|
||||
for (let index = 0; index < state.pendingPolls.length; index += 1) {
|
||||
const candidate = findAvailablePendingEvent(Date.now(), state.pendingPolls[index].types);
|
||||
if (!candidate) continue;
|
||||
pollIndex = index;
|
||||
entry = candidate;
|
||||
break;
|
||||
}
|
||||
if (!entry) {
|
||||
scheduleLeaseFlush();
|
||||
broadcastAgentPollingIfChanged();
|
||||
return;
|
||||
}
|
||||
const poll = state.pendingPolls.shift();
|
||||
const [poll] = state.pendingPolls.splice(pollIndex, 1);
|
||||
poll.resolve(leaseEvent(entry, poll.leaseMs));
|
||||
changed = true;
|
||||
}
|
||||
@@ -284,9 +438,10 @@ function flushPendingPolls() {
|
||||
}
|
||||
|
||||
function agentPollingConnected() {
|
||||
const now = Date.now();
|
||||
return state.pendingPolls.length > 0
|
||||
|| state.pendingEvents.some((entry) => entry.leaseUntil && entry.leaseUntil > now);
|
||||
// A leased event only proves that a poll returned once. The foreground task
|
||||
// may have ended immediately afterward, so only an actively waiting poll is
|
||||
// evidence that steering can wake the task right now.
|
||||
return state.pendingPolls.length > 0;
|
||||
}
|
||||
|
||||
function broadcastAgentPollingIfChanged() {
|
||||
@@ -339,6 +494,58 @@ function getManualEditStatus() {
|
||||
}
|
||||
}
|
||||
|
||||
function getCodexWorkerStatus() {
|
||||
let worker;
|
||||
try {
|
||||
worker = JSON.parse(fs.readFileSync(getLiveCodexWorkerStatePath(process.cwd()), 'utf-8'));
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
if (!worker || typeof worker !== 'object') return null;
|
||||
|
||||
const processActive = Number.isInteger(worker.pid) && worker.pid > 0 && pidReachable(worker.pid);
|
||||
const activeStatus = ['starting', 'ready', 'working'].includes(worker.status);
|
||||
const unavailable = activeStatus && !processActive;
|
||||
const error = unavailable ? 'codex_worker_unavailable' : stringOrNull(worker.error);
|
||||
const status = unavailable ? 'unavailable' : stringOrNull(worker.status) || 'unknown';
|
||||
return {
|
||||
status,
|
||||
mode: stringOrNull(worker.mode)
|
||||
|| (activeStatus && processActive ? 'dedicated-app-server' : 'foreground'),
|
||||
reachable: processActive,
|
||||
error,
|
||||
message: worker.error === 'codex_cli_unavailable'
|
||||
? 'Codex CLI not found. Live is using the main agent for generation.'
|
||||
: error
|
||||
? 'Background generation is unavailable. Live is using the main agent.'
|
||||
: null,
|
||||
command: stringOrNull(worker.command),
|
||||
setup: worker.error === 'codex_cli_unavailable' && worker.setup
|
||||
? {
|
||||
docsUrl: stringOrNull(worker.setup.docsUrl),
|
||||
afterInstall: stringOrNull(worker.setup.afterInstall),
|
||||
}
|
||||
: null,
|
||||
model: stringOrNull(worker.model),
|
||||
profile: stringOrNull(worker.profile),
|
||||
delivery: stringOrNull(worker.delivery),
|
||||
updatedAt: stringOrNull(worker.updatedAt),
|
||||
};
|
||||
}
|
||||
|
||||
function stringOrNull(value) {
|
||||
return typeof value === 'string' && value.trim() ? value : null;
|
||||
}
|
||||
|
||||
function pidReachable(pid) {
|
||||
try {
|
||||
process.kill(pid, 0);
|
||||
return true;
|
||||
} catch (error) {
|
||||
return error?.code === 'EPERM';
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Load scripts
|
||||
// ---------------------------------------------------------------------------
|
||||
@@ -521,6 +728,7 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
|
||||
connectedClients: state.sseClients.size,
|
||||
pendingEvents: state.pendingEvents.map((entry) => summarizePendingEventForStatus(entry)),
|
||||
agentPolling: agentPollingConnected(),
|
||||
codexWorker: getCodexWorkerStatus(),
|
||||
activeSessions: sessions,
|
||||
manualEdits: getManualEditStatus(),
|
||||
}));
|
||||
@@ -630,6 +838,7 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
|
||||
type: 'connected',
|
||||
hasProjectContext: hasProjectContext(),
|
||||
agentPolling: agentPollingConnected(),
|
||||
codexWorker: getCodexWorkerStatus(),
|
||||
activeSessions: activeSessionSummaries(),
|
||||
}) + '\n\n');
|
||||
|
||||
@@ -689,6 +898,15 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
|
||||
res.end(JSON.stringify({ error }));
|
||||
return;
|
||||
}
|
||||
if (msg.type === 'agent_phase') {
|
||||
recordAgentPhase(msg.id, msg.phase, {
|
||||
...(Number.isFinite(msg.durationMs) ? { durationMs: msg.durationMs } : {}),
|
||||
owner: typeof msg.owner === 'string' ? msg.owner : undefined,
|
||||
});
|
||||
res.writeHead(200, { 'Content-Type': 'application/json' });
|
||||
res.end(JSON.stringify({ ok: true }));
|
||||
return;
|
||||
}
|
||||
if (state.sessionStore && msg.id) {
|
||||
try {
|
||||
state.sessionStore.appendEvent(msg);
|
||||
@@ -698,6 +916,10 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
|
||||
return;
|
||||
}
|
||||
}
|
||||
if (msg.type === 'accept' || msg.type === 'discard') {
|
||||
retirePendingGeneration(msg.id);
|
||||
}
|
||||
recordGenerationCheckpoint(msg);
|
||||
if (msg.type === 'exit') {
|
||||
cleanupSvelteComponentSessionsBeforeExit();
|
||||
}
|
||||
@@ -738,6 +960,12 @@ function createRequestHandler({ detectScript, liveScriptParts }) {
|
||||
// Agent poll endpoints (unchanged from WS version)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
function parsePollTypes(value) {
|
||||
if (!value) return null;
|
||||
const types = String(value).split(',').map((type) => type.trim()).filter(Boolean);
|
||||
return types.length > 0 ? new Set(types) : null;
|
||||
}
|
||||
|
||||
function handlePollGet(req, res, url) {
|
||||
const token = url.searchParams.get('token');
|
||||
if (token !== state.token) {
|
||||
@@ -748,13 +976,14 @@ function handlePollGet(req, res, url) {
|
||||
state.lastPollAt = Date.now();
|
||||
const timeout = parseInt(url.searchParams.get('timeout') || DEFAULT_POLL_TIMEOUT, 10);
|
||||
const leaseMs = parseInt(url.searchParams.get('leaseMs') || '30000', 10);
|
||||
const available = findAvailablePendingEvent();
|
||||
const types = parsePollTypes(url.searchParams.get('types'));
|
||||
const available = findAvailablePendingEvent(Date.now(), types);
|
||||
if (available) {
|
||||
res.writeHead(200, { 'Content-Type': 'application/json' });
|
||||
res.end(JSON.stringify(leaseEvent(available, leaseMs)));
|
||||
return;
|
||||
}
|
||||
const poll = { resolve, leaseMs };
|
||||
const poll = { resolve, leaseMs, types };
|
||||
const timer = setTimeout(() => {
|
||||
const idx = state.pendingPolls.indexOf(poll);
|
||||
if (idx !== -1) state.pendingPolls.splice(idx, 1);
|
||||
@@ -783,12 +1012,20 @@ function sessionFileMetadataFromPollReply(file) {
|
||||
if (!file || typeof file !== 'string') return { file };
|
||||
const normalized = file.split(path.sep).join('/');
|
||||
const base = { file: normalized };
|
||||
if (!normalized.endsWith('/manifest.json') && normalized !== 'manifest.json') return base;
|
||||
if (!normalized.includes('node_modules/.impeccable-live/') && !normalized.includes('src/lib/impeccable/')) return base;
|
||||
const sourceArtifactPreview = normalized.includes('.impeccable/live/previews/')
|
||||
&& !normalized.endsWith('/manifest.json');
|
||||
const metadataFile = sourceArtifactPreview
|
||||
? normalized.slice(0, normalized.lastIndexOf('/') + 1) + 'manifest.json'
|
||||
: normalized;
|
||||
if (!metadataFile.endsWith('/manifest.json') && metadataFile !== 'manifest.json') return base;
|
||||
if (!metadataFile.includes('node_modules/.impeccable-live/')
|
||||
&& !metadataFile.includes('src/lib/impeccable/')
|
||||
&& !metadataFile.includes('/.impeccable-live/')
|
||||
&& !metadataFile.includes('.impeccable/live/previews/')) return base;
|
||||
|
||||
let full;
|
||||
try {
|
||||
full = path.resolve(process.cwd(), normalized);
|
||||
full = path.resolve(process.cwd(), metadataFile);
|
||||
const rel = path.relative(process.cwd(), full);
|
||||
if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return base;
|
||||
} catch {
|
||||
@@ -797,18 +1034,40 @@ function sessionFileMetadataFromPollReply(file) {
|
||||
|
||||
try {
|
||||
const manifest = JSON.parse(fs.readFileSync(full, 'utf-8'));
|
||||
if (manifest?.previewMode !== 'svelte-component' || !manifest.sourceFile) return base;
|
||||
if (!['svelte-component', 'vue-component', 'source-artifact'].includes(manifest?.previewMode)
|
||||
|| !manifest.sourceFile) return base;
|
||||
const previewFile = manifest.previewMode === 'source-artifact'
|
||||
? String(manifest.previewFile || normalized).split(path.sep).join('/')
|
||||
: normalized;
|
||||
return {
|
||||
file: String(manifest.sourceFile).split(path.sep).join('/'),
|
||||
sourceFile: String(manifest.sourceFile).split(path.sep).join('/'),
|
||||
previewFile: normalized,
|
||||
previewMode: 'svelte-component',
|
||||
previewFile,
|
||||
previewMode: manifest.previewMode,
|
||||
};
|
||||
} catch {
|
||||
return base;
|
||||
}
|
||||
}
|
||||
|
||||
function inferSourceEventType(msg = {}, pendingEvents = state.pendingEvents) {
|
||||
const pendingTypes = new Set(
|
||||
pendingEvents
|
||||
.filter((entry) => entry.event?.id === msg.id)
|
||||
.map((entry) => entry.event?.type),
|
||||
);
|
||||
if (msg.type === 'discarded' || msg.type === 'discard') return 'discard';
|
||||
if (msg.type === 'complete') {
|
||||
if (pendingTypes.has('carbonize_cleanup')) return 'carbonize_cleanup';
|
||||
return pendingTypes.has('accept') ? 'accept' : (pendingTypes.has('generate') ? 'generate' : undefined);
|
||||
}
|
||||
if (msg.type === 'steer_done') return 'steer';
|
||||
// `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.
|
||||
return msg.type === 'agent_done' || msg.type === 'done' ? 'generate' : undefined;
|
||||
}
|
||||
|
||||
function handlePollPost(req, res) {
|
||||
let body = '';
|
||||
req.on('data', (c) => { body += c; });
|
||||
@@ -869,7 +1128,23 @@ function handlePollPost(req, res) {
|
||||
res.end(JSON.stringify({ error: 'stale_manual_edit_apply_reply', ...rollback }));
|
||||
return;
|
||||
}
|
||||
const pendingEventBeforeAck = findPendingEventById(msg.id);
|
||||
const sourceEventType = msg.sourceEventType || inferSourceEventType(msg);
|
||||
if (msg.type === 'retry') {
|
||||
const releasedEvent = releasePendingEvent(msg.id, sourceEventType);
|
||||
if (!releasedEvent) {
|
||||
res.writeHead(msg.id ? 404 : 400, { 'Content-Type': 'application/json' });
|
||||
res.end(JSON.stringify({
|
||||
error: msg.id ? 'unknown_poll_retry_id' : 'missing_poll_retry_id',
|
||||
id: msg.id,
|
||||
}));
|
||||
return;
|
||||
}
|
||||
flushPendingPolls();
|
||||
res.writeHead(200, { 'Content-Type': 'application/json' });
|
||||
res.end(JSON.stringify({ ok: true, released: true }));
|
||||
return;
|
||||
}
|
||||
const pendingEventBeforeAck = findPendingEventById(msg.id, sourceEventType);
|
||||
if (pendingEventBeforeAck?.type === 'steer' && msg.type === 'steer_done'
|
||||
&& !msg.file && !(typeof msg.message === 'string' && msg.message.trim())) {
|
||||
res.writeHead(400, { 'Content-Type': 'application/json' });
|
||||
@@ -879,7 +1154,7 @@ function handlePollPost(req, res) {
|
||||
}));
|
||||
return;
|
||||
}
|
||||
const acknowledgedEvent = acknowledgePendingEvent(msg.id);
|
||||
const acknowledgedEvent = acknowledgePendingEvent(msg.id, sourceEventType);
|
||||
let skipJournalReply = false;
|
||||
let existingSession = null;
|
||||
if (!acknowledgedEvent && state.sessionStore && msg.id) {
|
||||
@@ -971,6 +1246,11 @@ function cleanupSvelteComponentSessionsBeforeExit() {
|
||||
} catch (err) {
|
||||
console.warn('[impeccable] Svelte component session cleanup failed:', err.message);
|
||||
}
|
||||
try {
|
||||
removeAllVueComponentSessions(process.cwd());
|
||||
} catch (err) {
|
||||
console.warn('[impeccable] Vue component session cleanup failed:', err.message);
|
||||
}
|
||||
}
|
||||
|
||||
function applyLegacyDeferredAcceptsOnStartup() {
|
||||
@@ -1083,7 +1363,10 @@ if (args.includes('--background')) {
|
||||
process.exit(0);
|
||||
}
|
||||
} catch { /* not ready yet */ }
|
||||
await new Promise(r => setTimeout(r, 200));
|
||||
// The detached child is typically listening in 35-45ms. A 200ms polling
|
||||
// floor dominated configured cold Live startup; poll cheaply and return
|
||||
// as soon as the child has written its ready record.
|
||||
await new Promise(r => setTimeout(r, 5));
|
||||
}
|
||||
console.error('Timed out waiting for live server to start.');
|
||||
process.exit(1);
|
||||
|
||||
@@ -36,16 +36,24 @@ export async function statusCli() {
|
||||
agentPolling: server.agentPolling,
|
||||
pendingEvents: server.pendingEvents,
|
||||
} : null,
|
||||
codexWorker: server?.codexWorker || null,
|
||||
activeSessions: server?.activeSessions || activeSessions,
|
||||
recoveryHint: manualApply
|
||||
? manualApplyResumeHint(manualApply)
|
||||
: server
|
||||
? 'Run live-poll.mjs to continue pending work, or live-complete.mjs --id <session> after manual cleanup.'
|
||||
: 'Start live-server.mjs to requeue pending durable events, then run live-poll.mjs.',
|
||||
recoveryHint: recoveryHint({ server, manualApply }),
|
||||
};
|
||||
console.log(JSON.stringify(payload, null, 2));
|
||||
}
|
||||
|
||||
function recoveryHint({ server, manualApply }) {
|
||||
if (manualApply) return manualApplyResumeHint(manualApply);
|
||||
if (server?.codexWorker?.error === 'codex_cli_unavailable') {
|
||||
return `Install Codex CLI (${server.codexWorker.setup?.docsUrl}), run ${server.codexWorker.setup?.afterInstall || 'codex login'}, then restart Live. The current session can continue through live-poll.mjs.`;
|
||||
}
|
||||
if (server) {
|
||||
return 'Run live-poll.mjs to continue pending work, or live-complete.mjs --id <session> after manual cleanup.';
|
||||
}
|
||||
return 'Start live-server.mjs to requeue pending durable events, then run live-poll.mjs.';
|
||||
}
|
||||
|
||||
function findPendingManualApply(server, activeSessions) {
|
||||
const fromServer = server?.pendingEvents?.find((event) => event?.type === 'manual_edit_apply');
|
||||
if (fromServer) return fromServer;
|
||||
|
||||
@@ -20,6 +20,15 @@ import {
|
||||
scaffoldSvelteComponentSession,
|
||||
shouldUseSvelteComponentInjection,
|
||||
} from './live/svelte-component.mjs';
|
||||
import {
|
||||
buildVueComponentCssAuthoring,
|
||||
scaffoldVueComponentSession,
|
||||
shouldUseVueComponentInjection,
|
||||
} from './live/vue-component.mjs';
|
||||
import {
|
||||
SOURCE_ARTIFACT_PREVIEW_MODE,
|
||||
scaffoldSourceArtifactSession,
|
||||
} from './live/source-artifact.mjs';
|
||||
|
||||
const EXTENSIONS = ['.html', '.jsx', '.tsx', '.vue', '.svelte', '.astro'];
|
||||
|
||||
@@ -50,6 +59,8 @@ Optional:
|
||||
--page-url URL Current page URL. Required when pending manual edits may
|
||||
affect the picked source block. Pending edits are filtered
|
||||
to this page so an edit on /a doesn't bleed into /b.
|
||||
--isolated Keep ordinary HTML/JSX/Astro source untouched during
|
||||
preview; write the wrapper to an isolated Live artifact.
|
||||
--help Show this help message
|
||||
|
||||
Output (JSON):
|
||||
@@ -68,6 +79,7 @@ The agent should insert variant HTML at insertLine.`);
|
||||
const filePath = argVal(args, '--file');
|
||||
const text = argVal(args, '--text');
|
||||
const pageUrl = argVal(args, '--page-url');
|
||||
const isolated = args.includes('--isolated');
|
||||
|
||||
if (!id) { console.error('Missing --id'); process.exit(1); }
|
||||
if (!elementId && !classes && !query) {
|
||||
@@ -160,11 +172,29 @@ The agent should insert variant HTML at insertLine.`);
|
||||
if (filtered.length === 1) {
|
||||
match = filtered[0];
|
||||
} else if (filtered.length === 0) {
|
||||
// Source uses dynamic content (`<h1>{title}</h1>` etc.) so the
|
||||
// browser-side textContent doesn't appear literally in source. Fall
|
||||
// back to first-match rather than refusing — this is the same
|
||||
// behavior unmodified callers see, just preserved.
|
||||
match = candidates[0];
|
||||
const normalizedText = String(text).replace(/\s+/g, ' ').trim();
|
||||
if (normalizedText.length < 8) {
|
||||
// Very short labels cannot disambiguate siblings reliably. Preserve
|
||||
// the legacy behavior for these low-information picker events.
|
||||
match = candidates[0];
|
||||
} else {
|
||||
// Rendered text that is absent from every candidate usually means
|
||||
// the source uses expressions or component props. Picking the first
|
||||
// same-class sibling silently edits the wrong instance (observed on
|
||||
// Astro result cards), so stop and surface every candidate instead.
|
||||
console.error(JSON.stringify({
|
||||
error: 'element_ambiguous',
|
||||
fallback: 'agent-driven',
|
||||
reason: 'rendered_text_not_in_source',
|
||||
file: path.relative(process.cwd(), targetFile),
|
||||
candidates: candidates.map((c) => ({
|
||||
startLine: c.startLine + 1,
|
||||
endLine: c.endLine + 1,
|
||||
})),
|
||||
hint: 'Rendered text does not occur in any matching source branch. The element may use dynamic props or expressions; inspect the candidates and wrap the intended instance manually.',
|
||||
}));
|
||||
process.exit(1);
|
||||
}
|
||||
} else {
|
||||
// Multiple candidates ALSO match the text. Truly ambiguous — refuse
|
||||
// rather than pick wrong, and hand the agent the candidate locations
|
||||
@@ -207,6 +237,7 @@ The agent should insert variant HTML at insertLine.`);
|
||||
// Strip only the COMMON minimum leading whitespace across the picked lines;
|
||||
// `deindentContent` on the accept side already mirrors this convention.
|
||||
let originalLines = lines.slice(startLine, endLine + 1);
|
||||
const sourceOriginalLines = [...originalLines];
|
||||
|
||||
// Buffer-aware "original" content: if the user has pending manual edits for
|
||||
// this page whose originalText appears in the picked source range, apply
|
||||
@@ -269,6 +300,9 @@ The agent should insert variant HTML at insertLine.`);
|
||||
const originalIndented = reindentOriginal(' ');
|
||||
const relTargetFile = path.relative(process.cwd(), targetFile).split(path.sep).join('/');
|
||||
const useSvelteComponent = shouldUseSvelteComponentInjection(targetFile);
|
||||
const useVueComponent = !useSvelteComponent && shouldUseVueComponentInjection(targetFile);
|
||||
const useFrameworkComponent = useSvelteComponent || useVueComponent;
|
||||
const useSourceArtifact = isolated && !useFrameworkComponent;
|
||||
|
||||
// Wrapper attributes differ by syntax. HTML allows plain string attrs;
|
||||
// JSX requires object-literal style and parses string attrs as HTML (which
|
||||
@@ -287,8 +321,11 @@ The agent should insert variant HTML at insertLine.`);
|
||||
// tuck both marker comments INSIDE it. accept/discard then expands its
|
||||
// replacement range to include the wrapper's `<div>` open / close lines
|
||||
// so the entire scaffold gets removed cleanly.
|
||||
const sourceArtifactAttr = useSourceArtifact
|
||||
? ' data-impeccable-preview="' + SOURCE_ARTIFACT_PREVIEW_MODE + '"'
|
||||
: '';
|
||||
const wrapperLines = isJsx ? [
|
||||
indent + '<div data-impeccable-variants="' + id + '" data-impeccable-variant-count="' + count + '" ' + styleContents + '>',
|
||||
indent + '<div data-impeccable-variants="' + id + '" data-impeccable-variant-count="' + count + '"' + sourceArtifactAttr + ' ' + styleContents + '>',
|
||||
indent + ' ' + commentSyntax.open + ' impeccable-variants-start ' + id + ' ' + commentSyntax.close,
|
||||
indent + ' ' + commentSyntax.open + ' Original ' + commentSyntax.close,
|
||||
indent + ' <div data-impeccable-variant="original">',
|
||||
@@ -299,7 +336,7 @@ The agent should insert variant HTML at insertLine.`);
|
||||
indent + '</div>',
|
||||
] : [
|
||||
indent + commentSyntax.open + ' impeccable-variants-start ' + id + ' ' + commentSyntax.close,
|
||||
indent + '<div data-impeccable-variants="' + id + '" data-impeccable-variant-count="' + count + '" ' + styleContents + '>',
|
||||
indent + '<div data-impeccable-variants="' + id + '" data-impeccable-variant-count="' + count + '"' + sourceArtifactAttr + ' ' + styleContents + '>',
|
||||
indent + ' ' + commentSyntax.open + ' Original ' + commentSyntax.close,
|
||||
indent + ' <div data-impeccable-variant="original">',
|
||||
originalIndented,
|
||||
@@ -315,6 +352,8 @@ The agent should insert variant HTML at insertLine.`);
|
||||
let outputEndLine = startLine + wrapperLines.length + (originalLines.length - 1);
|
||||
let insertLine;
|
||||
let svelteSession = null;
|
||||
let vueSession = null;
|
||||
let sourceArtifactSession = null;
|
||||
|
||||
if (useSvelteComponent) {
|
||||
// Svelte/SvelteKit resets component-local state on markup HMR updates.
|
||||
@@ -334,6 +373,38 @@ The agent should insert variant HTML at insertLine.`);
|
||||
outputStartLine = 1;
|
||||
outputEndLine = 1;
|
||||
insertLine = 1;
|
||||
} else if (useVueComponent) {
|
||||
// Nuxt route-module HMR can invalidate the active page while a generated
|
||||
// wrapper is only partially written. Stage real Vue SFCs in an app-local
|
||||
// dev module tree and leave the route untouched until Accept.
|
||||
vueSession = scaffoldVueComponentSession({
|
||||
id,
|
||||
count,
|
||||
sourceFile: relTargetFile,
|
||||
sourceStartLine: startLine + 1,
|
||||
sourceEndLine: endLine + 1,
|
||||
originalLines,
|
||||
cwd: process.cwd(),
|
||||
});
|
||||
outputFile = path.resolve(process.cwd(), vueSession.manifestFile);
|
||||
outputStartLine = 1;
|
||||
outputEndLine = 1;
|
||||
insertLine = 1;
|
||||
} else if (useSourceArtifact) {
|
||||
sourceArtifactSession = scaffoldSourceArtifactSession({
|
||||
id,
|
||||
count,
|
||||
sourceFile: relTargetFile,
|
||||
sourceStartLine: startLine + 1,
|
||||
sourceEndLine: endLine + 1,
|
||||
originalSource: sourceOriginalLines.join('\n'),
|
||||
previewContent: wrapperLines.join('\n'),
|
||||
cwd: process.cwd(),
|
||||
});
|
||||
outputFile = path.resolve(process.cwd(), sourceArtifactSession.previewFile);
|
||||
outputStartLine = 1;
|
||||
outputEndLine = wrapperLines.length + (originalLines.length - 1);
|
||||
insertLine = 6 + (originalLines.length - 1) + 1;
|
||||
} else {
|
||||
// Replace the original element with the wrapper
|
||||
const newLines = [
|
||||
@@ -356,15 +427,20 @@ 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 vueComponentAuthoring = useVueComponent ? buildVueComponentCssAuthoring(count) : null;
|
||||
const componentSession = svelteSession || vueSession;
|
||||
const componentPreviewMode = useSvelteComponent ? 'svelte-component' : useVueComponent ? 'vue-component' : undefined;
|
||||
const previewMode = componentPreviewMode || (useSourceArtifact ? SOURCE_ARTIFACT_PREVIEW_MODE : undefined);
|
||||
|
||||
console.log(JSON.stringify({
|
||||
file: outputRelFile,
|
||||
sourceFile: useSvelteComponent ? relTargetFile : undefined,
|
||||
previewMode: useSvelteComponent ? 'svelte-component' : undefined,
|
||||
componentDir: svelteSession?.componentDir,
|
||||
propContract: svelteSession?.propContract,
|
||||
sourceStartLine: useSvelteComponent ? startLine + 1 : undefined,
|
||||
sourceEndLine: useSvelteComponent ? endLine + 1 : undefined,
|
||||
sourceFile: useFrameworkComponent || useSourceArtifact ? relTargetFile : undefined,
|
||||
previewMode,
|
||||
previewManifest: sourceArtifactSession?.manifestFile,
|
||||
componentDir: componentSession?.componentDir,
|
||||
propContract: componentSession?.propContract,
|
||||
sourceStartLine: useFrameworkComponent ? startLine + 1 : undefined,
|
||||
sourceEndLine: useFrameworkComponent ? 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
|
||||
@@ -374,10 +450,10 @@ The agent should insert variant HTML at insertLine.`);
|
||||
endLine: outputEndLine, // 1-indexed
|
||||
insertLine, // 1-indexed: where variants go
|
||||
commentSyntax: commentSyntax,
|
||||
styleMode: useSvelteComponent ? 'svelte-component' : styleMode.mode,
|
||||
styleTag: useSvelteComponent ? null : styleMode.styleTag,
|
||||
cssSelectorPrefixExamples: useSvelteComponent ? [] : buildCssSelectorPrefixExamples(styleMode.mode, count),
|
||||
cssAuthoring: useSvelteComponent ? svelteComponentAuthoring : buildCssAuthoring(styleMode, count),
|
||||
styleMode: componentPreviewMode || styleMode.mode,
|
||||
styleTag: useFrameworkComponent ? null : styleMode.styleTag,
|
||||
cssSelectorPrefixExamples: useFrameworkComponent ? [] : buildCssSelectorPrefixExamples(styleMode.mode, count),
|
||||
cssAuthoring: svelteComponentAuthoring || vueComponentAuthoring || buildCssAuthoring(styleMode, count),
|
||||
originalLineCount: originalLines.length,
|
||||
}));
|
||||
}
|
||||
|
||||
@@ -25,6 +25,7 @@ import { loadContext, resolveTargetSelection } from './context.mjs';
|
||||
import { resolveFiles } from './live-inject.mjs';
|
||||
import { readLiveServerInfo } from './lib/impeccable-paths.mjs';
|
||||
import { resolveLiveTarget } from './live-target.mjs';
|
||||
import { resolveCodexWorkerConfig } from './live/codex-worker.mjs';
|
||||
|
||||
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
||||
|
||||
@@ -40,6 +41,7 @@ Prepare everything for live variant mode in a single command:
|
||||
- Starts (or reuses) the live server in the background
|
||||
- Injects the browser script tag
|
||||
- Reads PRODUCT.md / DESIGN.md for project context
|
||||
- Starts the dedicated app-server worker by default in Codex
|
||||
- In monorepos, choose a child app first; --target <path> is the fallback/manual path
|
||||
|
||||
On success, prints a JSON blob with:
|
||||
@@ -129,6 +131,10 @@ The agent should then:
|
||||
const resolvedFiles = resolveFiles(activeCwd, checkResult.config);
|
||||
const drift = scanForDrift(activeCwd, resolvedFiles, checkResult.config);
|
||||
|
||||
// Codex-only and default-on in Codex. A failed app-server startup never takes
|
||||
// ownership of the poll queue; the foreground portable path remains active.
|
||||
const codexWorker = ensureCodexWorker(activeCwd, checkResult.config);
|
||||
|
||||
// 5. Emit everything the agent needs
|
||||
console.log(JSON.stringify({
|
||||
ok: true,
|
||||
@@ -137,6 +143,7 @@ The agent should then:
|
||||
pageFiles: resolvedFiles,
|
||||
liveConfigPath: checkResult.path,
|
||||
configDrift: drift,
|
||||
codexWorker,
|
||||
targetPath: outputTargetPath,
|
||||
projectRoot: ctx.projectRoot,
|
||||
repoRoot: ctx.repoRoot,
|
||||
@@ -287,6 +294,50 @@ function ensureServerRunning(cwd = process.cwd()) {
|
||||
return safeParse(out);
|
||||
}
|
||||
|
||||
function ensureCodexWorker(cwd, liveConfig) {
|
||||
const config = resolveCodexWorkerConfig({ env: process.env, liveConfig });
|
||||
if (!config.enabled) {
|
||||
return { enabled: false, mode: 'foreground', codexOnly: true };
|
||||
}
|
||||
const out = runScript('live-codex-worker.mjs', ['--background', '--no-wait'], { cwd });
|
||||
const result = safeParse(out);
|
||||
if (!result?.ok) {
|
||||
const safeFallback = result?.fallback === 'foreground' && result?.terminated !== false;
|
||||
return {
|
||||
enabled: !safeFallback,
|
||||
mode: safeFallback ? 'foreground' : 'startup-failed-stop-required',
|
||||
codexOnly: true,
|
||||
fallback: safeFallback,
|
||||
error: result?.error || 'codex_worker_start_failed',
|
||||
message: result?.message || (safeFallback
|
||||
? 'Dedicated Codex generation is unavailable. Live is using the main agent.'
|
||||
: 'The dedicated Codex worker did not stop cleanly.'),
|
||||
command: result?.command || config.codexPath,
|
||||
setup: result?.setup || null,
|
||||
childPid: result?.childPid || null,
|
||||
logPath: result?.logPath || null,
|
||||
foregroundTypes: safeFallback
|
||||
? ['generate', 'accept', 'discard', 'prefetch', 'steer', 'manual_edit_apply', 'carbonize_cleanup', 'exit']
|
||||
: [],
|
||||
foregroundPoll: safeFallback ? 'live-poll.mjs' : null,
|
||||
};
|
||||
}
|
||||
return {
|
||||
enabled: true,
|
||||
mode: result.starting ? 'prewarming-app-server' : 'dedicated-app-server',
|
||||
codexOnly: true,
|
||||
pid: result.pid,
|
||||
threadId: result.threadId,
|
||||
model: result.model,
|
||||
effort: result.effort,
|
||||
profile: result.profile,
|
||||
delivery: result.delivery,
|
||||
foregroundTypes: ['steer', 'manual_edit_apply', 'carbonize_cleanup', 'exit'],
|
||||
foregroundPoll: 'live-poll.mjs --stream --types=steer,manual_edit_apply,carbonize_cleanup,exit --codex-worker-fallback',
|
||||
logPath: result.logPath || null,
|
||||
};
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Auto-execute
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
@@ -0,0 +1,559 @@
|
||||
import { spawn } from 'node:child_process';
|
||||
import { performance } from 'node:perf_hooks';
|
||||
|
||||
const DEFAULT_CLIENT_INFO = {
|
||||
name: 'impeccable_live',
|
||||
title: 'Impeccable Live',
|
||||
version: '0.0.1',
|
||||
};
|
||||
|
||||
function modelSearchText(model) {
|
||||
return [model?.id, model?.model, model?.displayName]
|
||||
.filter(Boolean)
|
||||
.join(' ')
|
||||
.toLowerCase();
|
||||
}
|
||||
|
||||
/**
|
||||
* Pick a low-latency visible model without depending on a particular catalog
|
||||
* version. The caller still owns the model list and may override this choice.
|
||||
*/
|
||||
export function selectFastCodexModel(models = []) {
|
||||
const visible = models.filter((model) => model && !model.hidden);
|
||||
const preferences = [
|
||||
(model) => /codex/.test(modelSearchText(model)) && /spark/.test(modelSearchText(model)),
|
||||
(model) => /codex/.test(modelSearchText(model)) && /mini/.test(modelSearchText(model)),
|
||||
(model) => /mini/.test(modelSearchText(model)),
|
||||
(model) => model.isDefault,
|
||||
];
|
||||
|
||||
for (const preference of preferences) {
|
||||
const match = visible.find(preference);
|
||||
if (match) return match;
|
||||
}
|
||||
return visible[0] || null;
|
||||
}
|
||||
|
||||
/** Pick the strongest visible general Codex model for design-sensitive work. */
|
||||
export function selectQualityCodexModel(models = []) {
|
||||
const visible = models.filter((model) => model && !model.hidden);
|
||||
const preferences = [
|
||||
(model) => /5\.6/.test(modelSearchText(model)) && /sol/.test(modelSearchText(model)),
|
||||
(model) => model.isDefault && !/(?:spark|mini)/.test(modelSearchText(model)),
|
||||
(model) => !/(?:spark|mini)/.test(modelSearchText(model)),
|
||||
(model) => model.isDefault,
|
||||
];
|
||||
|
||||
for (const preference of preferences) {
|
||||
const match = visible.find(preference);
|
||||
if (match) return match;
|
||||
}
|
||||
return visible[0] || null;
|
||||
}
|
||||
|
||||
/** Pick the least expensive supported effort, falling back to the catalog default. */
|
||||
export function selectLowestReasoningEffort(model = {}) {
|
||||
const efforts = (model.supportedReasoningEfforts || [])
|
||||
.map((option) => typeof option === 'string' ? option : option?.reasoningEffort)
|
||||
.filter(Boolean);
|
||||
for (const candidate of ['none', 'minimal', 'low']) {
|
||||
if (efforts.includes(candidate)) return candidate;
|
||||
}
|
||||
return model.defaultReasoningEffort || efforts[0] || 'low';
|
||||
}
|
||||
|
||||
export const selectFastModel = selectFastCodexModel;
|
||||
export const selectLowestEffort = selectLowestReasoningEffort;
|
||||
|
||||
export class CodexAppServerError extends Error {
|
||||
constructor(message, { code, data, cause } = {}) {
|
||||
super(message, { cause });
|
||||
this.name = 'CodexAppServerError';
|
||||
if (code !== undefined) this.code = code;
|
||||
if (data !== undefined) this.data = data;
|
||||
}
|
||||
}
|
||||
|
||||
function requireString(value, name) {
|
||||
if (typeof value !== 'string' || !value.trim()) {
|
||||
throw new TypeError(`${name} must be a non-empty string`);
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
function asError(error, fallback) {
|
||||
if (error instanceof Error) return error;
|
||||
return new CodexAppServerError(fallback, { data: error });
|
||||
}
|
||||
|
||||
export class CodexAppServerClient {
|
||||
constructor({
|
||||
command = 'codex',
|
||||
args = ['app-server', '--stdio'],
|
||||
cwd = process.cwd(),
|
||||
env = process.env,
|
||||
spawnFactory = spawn,
|
||||
clock = () => performance.now(),
|
||||
clientInfo = DEFAULT_CLIENT_INFO,
|
||||
initializeParams = {},
|
||||
requestTimeoutMs = 30_000,
|
||||
turnTimeoutMs = 120_000,
|
||||
} = {}) {
|
||||
this.command = command;
|
||||
this.args = [...args];
|
||||
this.cwd = cwd;
|
||||
this.env = env;
|
||||
this.spawnFactory = spawnFactory;
|
||||
this.clock = clock;
|
||||
this.clientInfo = { ...DEFAULT_CLIENT_INFO, ...clientInfo };
|
||||
this.initializeParams = { ...initializeParams };
|
||||
this.requestTimeoutMs = requestTimeoutMs;
|
||||
this.turnTimeoutMs = turnTimeoutMs;
|
||||
|
||||
this.process = null;
|
||||
this.state = 'disconnected';
|
||||
this.connectionGeneration = 0;
|
||||
this.lastExit = null;
|
||||
this.stderr = '';
|
||||
this.initializeResult = null;
|
||||
this.connectedAt = null;
|
||||
|
||||
this._nextRequestId = 1;
|
||||
this._pending = new Map();
|
||||
this._notificationListeners = new Set();
|
||||
this._disconnectListeners = new Set();
|
||||
this._dedicatedThreadIds = new Set();
|
||||
this._connectPromise = null;
|
||||
this._stdoutBuffer = '';
|
||||
this._failedGeneration = 0;
|
||||
}
|
||||
|
||||
get connected() {
|
||||
return this.state === 'connected';
|
||||
}
|
||||
|
||||
get dedicatedThreadIds() {
|
||||
return [...this._dedicatedThreadIds];
|
||||
}
|
||||
|
||||
async connect() {
|
||||
if (this.connected) return this;
|
||||
if (this._connectPromise) return this._connectPromise;
|
||||
|
||||
this._connectPromise = this._connect();
|
||||
try {
|
||||
return await this._connectPromise;
|
||||
} finally {
|
||||
this._connectPromise = null;
|
||||
}
|
||||
}
|
||||
|
||||
async _connect() {
|
||||
if (this.state !== 'disconnected') {
|
||||
throw new CodexAppServerError(`cannot connect while client is ${this.state}`);
|
||||
}
|
||||
|
||||
this.state = 'connecting';
|
||||
this.lastExit = null;
|
||||
this.stderr = '';
|
||||
this._stdoutBuffer = '';
|
||||
const generation = ++this.connectionGeneration;
|
||||
const startedAt = this.clock();
|
||||
let child;
|
||||
try {
|
||||
child = this.spawnFactory(this.command, this.args, {
|
||||
cwd: this.cwd,
|
||||
env: this.env,
|
||||
stdio: ['pipe', 'pipe', 'pipe'],
|
||||
});
|
||||
this._bindProcess(child, generation);
|
||||
this.process = child;
|
||||
|
||||
this.initializeResult = await this.request('initialize', {
|
||||
...this.initializeParams,
|
||||
clientInfo: this.clientInfo,
|
||||
});
|
||||
this._send({ method: 'initialized', params: {} });
|
||||
this.connectedAt = this.clock();
|
||||
this.startupMs = this.connectedAt - startedAt;
|
||||
this.state = 'connected';
|
||||
return this;
|
||||
} catch (error) {
|
||||
this._failConnection(asError(error, 'failed to connect to Codex app-server'), generation);
|
||||
child?.stdin?.end?.();
|
||||
child?.kill?.('SIGTERM');
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
_bindProcess(child, generation) {
|
||||
if (!child?.stdin || !child?.stdout) {
|
||||
throw new TypeError('spawnFactory must return a child process with stdin and stdout');
|
||||
}
|
||||
|
||||
child.stdout.setEncoding?.('utf8');
|
||||
child.stderr?.setEncoding?.('utf8');
|
||||
child.stdout.on('data', (chunk) => this._onStdout(chunk, generation));
|
||||
child.stderr?.on('data', (chunk) => {
|
||||
if (generation === this.connectionGeneration) this.stderr += String(chunk);
|
||||
});
|
||||
child.stdin.on?.('error', (error) => this._failConnection(
|
||||
new CodexAppServerError(`Codex app-server stdin error: ${error.message}`, { cause: error }),
|
||||
generation,
|
||||
));
|
||||
child.once('error', (error) => this._failConnection(
|
||||
new CodexAppServerError(`Codex app-server process error: ${error.message}`, { cause: error }),
|
||||
generation,
|
||||
));
|
||||
child.once('exit', (code, signal) => {
|
||||
const suffix = signal ? `signal ${signal}` : `code ${code}`;
|
||||
this._failConnection(new CodexAppServerError(`Codex app-server exited with ${suffix}`), generation, {
|
||||
code,
|
||||
signal,
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
_onStdout(chunk, generation) {
|
||||
if (generation !== this.connectionGeneration || this.state === 'disconnected' || this.state === 'closing') {
|
||||
return;
|
||||
}
|
||||
this._stdoutBuffer += String(chunk);
|
||||
let newline;
|
||||
while ((newline = this._stdoutBuffer.indexOf('\n')) !== -1) {
|
||||
const line = this._stdoutBuffer.slice(0, newline).trim();
|
||||
this._stdoutBuffer = this._stdoutBuffer.slice(newline + 1);
|
||||
if (!line) continue;
|
||||
try {
|
||||
this._onMessage(JSON.parse(line));
|
||||
} catch (error) {
|
||||
this._emitNotification({
|
||||
method: 'client/protocol-error',
|
||||
params: { line, error: error.message },
|
||||
receivedAt: this.clock(),
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
_onMessage(message) {
|
||||
if (message?.id !== undefined && message?.id !== null && this._pending.has(message.id)) {
|
||||
const pending = this._pending.get(message.id);
|
||||
this._pending.delete(message.id);
|
||||
if (pending.timer) clearTimeout(pending.timer);
|
||||
if (message.error) {
|
||||
const detail = typeof message.error.message === 'string'
|
||||
? message.error.message
|
||||
: JSON.stringify(message.error);
|
||||
pending.reject(new CodexAppServerError(`${pending.method}: ${detail}`, {
|
||||
code: message.error.code,
|
||||
data: message.error.data,
|
||||
}));
|
||||
} else {
|
||||
pending.resolve(message.result);
|
||||
}
|
||||
return;
|
||||
}
|
||||
|
||||
if (message?.method) {
|
||||
this._emitNotification({ ...message, receivedAt: this.clock() });
|
||||
}
|
||||
}
|
||||
|
||||
_emitNotification(notification) {
|
||||
for (const entry of [...this._notificationListeners]) {
|
||||
if (entry.method && entry.method !== notification.method) continue;
|
||||
try {
|
||||
entry.listener(notification);
|
||||
} catch {
|
||||
// A consumer exception must not break protocol dispatch for other listeners.
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
_send(message) {
|
||||
if (!this.process || this.state === 'disconnected' || this.state === 'closing') {
|
||||
throw new CodexAppServerError('Codex app-server is not connected');
|
||||
}
|
||||
try {
|
||||
this.process.stdin.write(`${JSON.stringify(message)}\n`);
|
||||
} catch (error) {
|
||||
throw new CodexAppServerError('failed to write to Codex app-server', { cause: error });
|
||||
}
|
||||
}
|
||||
|
||||
request(method, params = {}, { timeoutMs = this.requestTimeoutMs } = {}) {
|
||||
requireString(method, 'method');
|
||||
if (!this.process || this.state === 'disconnected' || this.state === 'closing') {
|
||||
return Promise.reject(new CodexAppServerError('Codex app-server is not connected'));
|
||||
}
|
||||
|
||||
const id = this._nextRequestId++;
|
||||
return new Promise((resolve, reject) => {
|
||||
let timer = null;
|
||||
if (Number.isFinite(timeoutMs) && timeoutMs > 0) {
|
||||
timer = setTimeout(() => {
|
||||
this._pending.delete(id);
|
||||
reject(new CodexAppServerError(`${method} timed out after ${timeoutMs}ms`));
|
||||
}, timeoutMs);
|
||||
timer.unref?.();
|
||||
}
|
||||
this._pending.set(id, { method, resolve, reject, timer, sentAt: this.clock() });
|
||||
try {
|
||||
this._send({ method, id, params });
|
||||
} catch (error) {
|
||||
this._pending.delete(id);
|
||||
if (timer) clearTimeout(timer);
|
||||
reject(error);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
notify(method, params = {}) {
|
||||
requireString(method, 'method');
|
||||
this._send({ method, params });
|
||||
}
|
||||
|
||||
onNotification(method, listener) {
|
||||
if (typeof method === 'function') {
|
||||
listener = method;
|
||||
method = null;
|
||||
}
|
||||
if (typeof listener !== 'function') throw new TypeError('listener must be a function');
|
||||
const entry = { method, listener };
|
||||
this._notificationListeners.add(entry);
|
||||
return () => this._notificationListeners.delete(entry);
|
||||
}
|
||||
|
||||
async listModels(params = {}) {
|
||||
const result = await this.request('model/list', {
|
||||
includeHidden: false,
|
||||
limit: 100,
|
||||
...params,
|
||||
});
|
||||
return result?.data || [];
|
||||
}
|
||||
|
||||
async selectFastModel(params = {}) {
|
||||
return selectFastCodexModel(await this.listModels(params));
|
||||
}
|
||||
|
||||
async startDedicatedThread(params) {
|
||||
if (!params || typeof params !== 'object' || Array.isArray(params)) {
|
||||
throw new TypeError('dedicated thread parameters are required');
|
||||
}
|
||||
const result = await this.request('thread/start', { ...params });
|
||||
const threadId = requireString(result?.thread?.id, 'thread/start result.thread.id');
|
||||
this._dedicatedThreadIds.add(threadId);
|
||||
return result.thread;
|
||||
}
|
||||
|
||||
async resumeDedicatedThread(threadId, params = {}) {
|
||||
requireString(threadId, 'threadId');
|
||||
if (params.history !== undefined || params.path !== undefined) {
|
||||
throw new TypeError('dedicated threads may only be resumed by explicit threadId');
|
||||
}
|
||||
const result = await this.request('thread/resume', { ...params, threadId });
|
||||
const resumedId = requireString(result?.thread?.id || threadId, 'thread/resume result.thread.id');
|
||||
if (resumedId !== threadId) {
|
||||
throw new CodexAppServerError(`thread/resume returned unexpected thread ${resumedId}`);
|
||||
}
|
||||
this._dedicatedThreadIds.add(threadId);
|
||||
return result.thread;
|
||||
}
|
||||
|
||||
_requireDedicatedThread(threadId) {
|
||||
requireString(threadId, 'threadId');
|
||||
if (!this._dedicatedThreadIds.has(threadId)) {
|
||||
throw new CodexAppServerError(
|
||||
`thread ${threadId} is not owned by this client; start or explicitly resume a dedicated thread first`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
async startTurn({ threadId, input, timeoutMs = this.turnTimeoutMs, onStarted, onAgentMessage, ...params }) {
|
||||
this._requireDedicatedThread(threadId);
|
||||
const normalizedInput = typeof input === 'string'
|
||||
? [{ type: 'text', text: input }]
|
||||
: input;
|
||||
if (!Array.isArray(normalizedInput) || normalizedInput.length === 0) {
|
||||
throw new TypeError('input must be a non-empty string or input array');
|
||||
}
|
||||
|
||||
const requestedAt = this.clock();
|
||||
let turnId = null;
|
||||
let started = null;
|
||||
let completed = null;
|
||||
let tokenUsage = null;
|
||||
const agentMessages = [];
|
||||
const agentMessageCallbacks = [];
|
||||
let firstAgentMessageAt = null;
|
||||
const buffered = [];
|
||||
let completionResolve;
|
||||
let completionReject;
|
||||
let completionTimer = null;
|
||||
const completionPromise = new Promise((resolve, reject) => {
|
||||
completionResolve = resolve;
|
||||
completionReject = reject;
|
||||
});
|
||||
completionPromise.catch(() => {});
|
||||
|
||||
const consider = (notification) => {
|
||||
const notificationThreadId = notification.params?.threadId;
|
||||
const notificationTurnId = notification.params?.turnId || notification.params?.turn?.id;
|
||||
if (notificationThreadId !== threadId) return;
|
||||
if (!turnId) {
|
||||
buffered.push(notification);
|
||||
return;
|
||||
}
|
||||
if (notificationTurnId !== turnId) return;
|
||||
if (notification.method === 'turn/started') started = notification;
|
||||
if (notification.method === 'thread/tokenUsage/updated') {
|
||||
tokenUsage = notification.params?.tokenUsage || tokenUsage;
|
||||
}
|
||||
if (notification.method === 'item/completed'
|
||||
&& notification.params?.item?.type === 'agentMessage'
|
||||
&& typeof notification.params.item.text === 'string') {
|
||||
const message = notification.params.item.text;
|
||||
agentMessages.push(message);
|
||||
if (firstAgentMessageAt == null) firstAgentMessageAt = notification.receivedAt ?? this.clock();
|
||||
if (typeof onAgentMessage === 'function') {
|
||||
agentMessageCallbacks.push(Promise.resolve().then(() => onAgentMessage(message, {
|
||||
threadId,
|
||||
turnId,
|
||||
notification,
|
||||
})));
|
||||
}
|
||||
}
|
||||
if (notification.method === 'turn/completed') {
|
||||
completed = notification;
|
||||
completionResolve(notification);
|
||||
}
|
||||
};
|
||||
|
||||
const unsubscribe = this.onNotification(consider);
|
||||
const onDisconnect = (error) => completionReject(error);
|
||||
this._disconnectListeners.add(onDisconnect);
|
||||
if (Number.isFinite(timeoutMs) && timeoutMs > 0) {
|
||||
completionTimer = setTimeout(() => {
|
||||
completionReject(new CodexAppServerError(`turn completion timed out after ${timeoutMs}ms`));
|
||||
}, timeoutMs);
|
||||
completionTimer.unref?.();
|
||||
}
|
||||
|
||||
try {
|
||||
const result = await this.request('turn/start', {
|
||||
...params,
|
||||
threadId,
|
||||
input: normalizedInput,
|
||||
}, { timeoutMs });
|
||||
turnId = requireString(result?.turn?.id, 'turn/start result.turn.id');
|
||||
if (typeof onStarted === 'function') onStarted(turnId, result.turn);
|
||||
for (const notification of buffered.splice(0)) consider(notification);
|
||||
await completionPromise;
|
||||
await Promise.all(agentMessageCallbacks);
|
||||
const completedAt = completed?.receivedAt ?? this.clock();
|
||||
const status = completed?.params?.turn?.status || result.turn?.status || null;
|
||||
if (status !== 'completed') {
|
||||
const interrupted = status === 'interrupted' || status === 'cancelled' || status === 'canceled';
|
||||
throw new CodexAppServerError(`turn ${turnId} completed with status ${status || 'unknown'}`, {
|
||||
code: interrupted ? 'TURN_INTERRUPTED' : 'TURN_FAILED',
|
||||
data: completed?.params?.turn || result.turn || null,
|
||||
});
|
||||
}
|
||||
return {
|
||||
threadId,
|
||||
turnId,
|
||||
turn: completed?.params?.turn || result.turn,
|
||||
startResponse: result,
|
||||
started,
|
||||
completed,
|
||||
tokenUsage,
|
||||
status,
|
||||
agentMessages,
|
||||
message: agentMessages.at(-1) || null,
|
||||
requestedAt,
|
||||
firstAgentMessageAt,
|
||||
firstAgentMessageMs: firstAgentMessageAt == null ? null : firstAgentMessageAt - requestedAt,
|
||||
completedAt,
|
||||
durationMs: completedAt - requestedAt,
|
||||
};
|
||||
} finally {
|
||||
unsubscribe();
|
||||
this._disconnectListeners.delete(onDisconnect);
|
||||
if (completionTimer) clearTimeout(completionTimer);
|
||||
}
|
||||
}
|
||||
|
||||
interruptTurn(threadId, turnId) {
|
||||
this._requireDedicatedThread(threadId);
|
||||
requireString(turnId, 'turnId');
|
||||
return this.request('turn/interrupt', { threadId, turnId });
|
||||
}
|
||||
|
||||
async unsubscribeThread(threadId) {
|
||||
this._requireDedicatedThread(threadId);
|
||||
return this.request('thread/unsubscribe', { threadId });
|
||||
}
|
||||
|
||||
async archiveThread(threadId) {
|
||||
this._requireDedicatedThread(threadId);
|
||||
const result = await this.request('thread/archive', { threadId });
|
||||
this._dedicatedThreadIds.delete(threadId);
|
||||
return result;
|
||||
}
|
||||
|
||||
async reconnect({ threadId, resumeParams = {} } = {}) {
|
||||
if (threadId !== undefined) requireString(threadId, 'threadId');
|
||||
await this.disconnect();
|
||||
await this.connect();
|
||||
if (threadId !== undefined) return this.resumeDedicatedThread(threadId, resumeParams);
|
||||
return this;
|
||||
}
|
||||
|
||||
async disconnect() {
|
||||
if (this.state === 'disconnected') return;
|
||||
const child = this.process;
|
||||
const generation = this.connectionGeneration;
|
||||
this.state = 'closing';
|
||||
this.process = null;
|
||||
try {
|
||||
child?.stdin?.end?.();
|
||||
} finally {
|
||||
child?.kill?.('SIGTERM');
|
||||
this._failConnection(new CodexAppServerError('Codex app-server connection closed'), generation);
|
||||
}
|
||||
}
|
||||
|
||||
async close({ threadId, archive = false, unsubscribe = false } = {}) {
|
||||
if (threadId !== undefined && this.connected) {
|
||||
if (archive) await this.archiveThread(threadId);
|
||||
else if (unsubscribe) await this.unsubscribeThread(threadId);
|
||||
}
|
||||
await this.disconnect();
|
||||
this._notificationListeners.clear();
|
||||
this._dedicatedThreadIds.clear();
|
||||
}
|
||||
|
||||
_failConnection(error, generation, exit = null) {
|
||||
if (generation !== this.connectionGeneration) return;
|
||||
if (this._failedGeneration === generation) {
|
||||
if (exit && !this.lastExit) this.lastExit = { ...exit, at: this.clock() };
|
||||
return;
|
||||
}
|
||||
this._failedGeneration = generation;
|
||||
if (exit) this.lastExit = { ...exit, at: this.clock() };
|
||||
this.state = 'disconnected';
|
||||
this.process = null;
|
||||
for (const pending of this._pending.values()) {
|
||||
if (pending.timer) clearTimeout(pending.timer);
|
||||
pending.reject(error);
|
||||
}
|
||||
this._pending.clear();
|
||||
for (const listener of [...this._disconnectListeners]) listener(error);
|
||||
}
|
||||
}
|
||||
|
||||
export function createCodexAppServerClient(options) {
|
||||
return new CodexAppServerClient(options);
|
||||
}
|
||||
@@ -0,0 +1,962 @@
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { execFileSync, spawnSync } from 'node:child_process';
|
||||
import { randomBytes } from 'node:crypto';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
|
||||
import {
|
||||
selectLowestReasoningEffort,
|
||||
selectQualityCodexModel,
|
||||
} from './codex-app-server-client.mjs';
|
||||
import { loadContext } from '../context.mjs';
|
||||
import { reconcilePublishedSourceVariants } from './generation-publisher.mjs';
|
||||
|
||||
import {
|
||||
CODEX_WORKER_OWNER,
|
||||
applyCodexWorkerOutput,
|
||||
buildCodexWorkerInstructions,
|
||||
buildCodexWorkerTurnInputs,
|
||||
buildGenerationTurnInput,
|
||||
codexWorkerDetectorRepairSchema,
|
||||
codexWorkerOutputSchemaForPhase,
|
||||
codexWorkerStateIsOwned,
|
||||
generationIsCanceled,
|
||||
isCodexComponentPreviewMode,
|
||||
prepareCodexWorkerPhase,
|
||||
publishCodexWorkerPhase,
|
||||
readPreparedArtifact,
|
||||
resolveCodexWorkerSkillPath,
|
||||
} from './codex-worker.mjs';
|
||||
import {
|
||||
augmentEventWithAcceptHandling,
|
||||
completeAcceptHandling,
|
||||
fetchNextEvent,
|
||||
postReply,
|
||||
requiresAgentReply,
|
||||
} from '../live-poll.mjs';
|
||||
import { createLiveSessionStore } from './session-store.mjs';
|
||||
|
||||
export const CODEX_WORKER_EVENT_TYPES = Object.freeze(['generate', 'accept', 'discard', 'prefetch']);
|
||||
export const CODEX_WORKER_EVENT_LEASE_MS = 15_000;
|
||||
const LOCAL_SCRIPTS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
|
||||
|
||||
export class CodexLiveWorkerSupervisor {
|
||||
constructor({
|
||||
cwd,
|
||||
base,
|
||||
token,
|
||||
client,
|
||||
config,
|
||||
statePath,
|
||||
scriptsDir,
|
||||
fetchEvent = fetchNextEvent,
|
||||
handleAccept = augmentEventWithAcceptHandling,
|
||||
completeAccept = completeAcceptHandling,
|
||||
reply = postReply,
|
||||
publishCheckpoint = postVariantCheckpoint,
|
||||
publishPhase = postAgentPhase,
|
||||
postCleanup = postCarbonizeCleanup,
|
||||
detectCandidate = detectPreparedArtifact,
|
||||
sessionStore = null,
|
||||
log = () => {},
|
||||
}) {
|
||||
this.cwd = path.resolve(cwd);
|
||||
this.base = base;
|
||||
this.token = token;
|
||||
this.client = client;
|
||||
this.config = config;
|
||||
this.statePath = statePath;
|
||||
this.scriptsDir = scriptsDir;
|
||||
this.fetchEvent = fetchEvent;
|
||||
this.handleAccept = handleAccept;
|
||||
this.completeAccept = completeAccept;
|
||||
this.reply = reply;
|
||||
this.publishCheckpoint = publishCheckpoint;
|
||||
this.publishPhase = publishPhase;
|
||||
this.postCleanup = postCleanup;
|
||||
this.detectCandidate = detectCandidate;
|
||||
this.sessionStore = sessionStore || createLiveSessionStore({ cwd: this.cwd });
|
||||
this.log = log;
|
||||
this.running = false;
|
||||
this.queue = Promise.resolve();
|
||||
this.active = null;
|
||||
this.canceled = new Set();
|
||||
this.queuedGenerationIds = new Set();
|
||||
this.pollAbortController = null;
|
||||
this.activePoll = null;
|
||||
this.failure = null;
|
||||
this.thread = null;
|
||||
this.threadReady = Promise.resolve(null);
|
||||
this.model = null;
|
||||
this.liveSpec = '';
|
||||
this.threadPrimed = false;
|
||||
}
|
||||
|
||||
async initialize() {
|
||||
this.liveSpec = readOptional(path.join(this.scriptsDir, '..', 'reference', 'live-generation.md'));
|
||||
await this.client.connect();
|
||||
const models = await this.client.listModels();
|
||||
this.model = this.config.model
|
||||
? models.find((model) => model.id === this.config.model || model.model === this.config.model)
|
||||
: this.config.profile === 'fast'
|
||||
? selectFastCodexModel(models)
|
||||
: selectQualityCodexModel(models);
|
||||
if (!this.model) throw supervisorError('codex_worker_model_unavailable');
|
||||
|
||||
const prior = readJson(this.statePath);
|
||||
if (codexWorkerStateIsOwned(prior, this.cwd) && prior.status !== 'archived') {
|
||||
try {
|
||||
this.thread = await this.client.resumeDedicatedThread(prior.threadId, {
|
||||
model: this.model.model || this.model.id,
|
||||
cwd: this.cwd,
|
||||
approvalPolicy: 'never',
|
||||
sandbox: 'read-only',
|
||||
baseInstructions: buildCodexWorkerInstructions(this.liveSpec),
|
||||
});
|
||||
this.threadPrimed = prior.threadPrimed === true;
|
||||
} catch (error) {
|
||||
this.log(`resume failed; creating replacement worker thread: ${error.message}`);
|
||||
}
|
||||
}
|
||||
if (!this.thread) {
|
||||
this.thread = await this.startWorkerThread();
|
||||
}
|
||||
this.threadReady = Promise.resolve(this.thread);
|
||||
this.writeState('ready');
|
||||
return this.status();
|
||||
}
|
||||
|
||||
async run() {
|
||||
if (!this.thread) await this.initialize();
|
||||
this.running = true;
|
||||
this.pollAbortController = new AbortController();
|
||||
while (this.running) {
|
||||
let event;
|
||||
try {
|
||||
const poll = this.fetchEvent(this.base, this.token, {
|
||||
types: CODEX_WORKER_EVENT_TYPES,
|
||||
leaseMs: CODEX_WORKER_EVENT_LEASE_MS,
|
||||
signal: this.pollAbortController.signal,
|
||||
});
|
||||
this.activePoll = poll;
|
||||
event = await poll;
|
||||
} catch (error) {
|
||||
if (!this.running && (error?.name === 'AbortError' || this.pollAbortController.signal.aborted)) break;
|
||||
throw error;
|
||||
} finally {
|
||||
this.activePoll = null;
|
||||
}
|
||||
if (!this.running) break;
|
||||
if (!event || event.type === 'timeout') continue;
|
||||
if (event.type === 'exit') {
|
||||
await this.cancelActive('live_exit');
|
||||
this.running = false;
|
||||
break;
|
||||
}
|
||||
if (event.type === 'accept' || event.type === 'discard') {
|
||||
this.canceled.add(event.id);
|
||||
const replaceBusyThread = this.active?.eventId === event.id;
|
||||
// Cancellation fences publication synchronously. Do not make the
|
||||
// deterministic Accept/Discard path wait on a slow app-server
|
||||
// interrupt round trip before it can update source and reply.
|
||||
void this.cancelActive(event.type, event.id);
|
||||
if (replaceBusyThread) this.rotateWorkerThread(event.type);
|
||||
const handled = await this.handleAccept(event, this.base, this.token, {
|
||||
deferReply: event.type === 'accept',
|
||||
});
|
||||
if (handled?._acceptResult?.handled !== true) {
|
||||
this.log(`${event.type} ${event.id} source update failed: ${handled?._acceptResult?.error || 'unhandled'}`);
|
||||
}
|
||||
if (event.type === 'accept' && handled?._acceptResult?.carbonize === true) {
|
||||
await this.postCleanup(this.base, this.token, {
|
||||
id: event.id,
|
||||
sessionId: event.id,
|
||||
file: handled._acceptResult.file,
|
||||
variantId: event.variantId,
|
||||
acceptResult: handled._acceptResult,
|
||||
});
|
||||
}
|
||||
if (handled?._completionAck?.deferred === true) {
|
||||
await this.completeAccept(handled, this.base, this.token);
|
||||
}
|
||||
continue;
|
||||
}
|
||||
if (event.type === 'generate') {
|
||||
if (this.queuedGenerationIds.has(event.id)) continue;
|
||||
this.queuedGenerationIds.add(event.id);
|
||||
this.queue = this.queue
|
||||
.then(() => this.processGeneration(event))
|
||||
.catch((error) => this.handleGenerationFailure(event, error))
|
||||
.finally(() => this.queuedGenerationIds.delete(event.id));
|
||||
continue;
|
||||
}
|
||||
if (event.type === 'prefetch') continue;
|
||||
if (requiresAgentReply(event)) {
|
||||
await this.reply(this.base, this.token, {
|
||||
id: event.id,
|
||||
type: 'error',
|
||||
sourceEventType: event.type,
|
||||
message: `Dedicated Codex worker does not handle ${event.type}; disable IMPECCABLE_LIVE_CODEX_WORKER for the portable foreground path.`,
|
||||
});
|
||||
}
|
||||
}
|
||||
await this.queue.catch(() => {});
|
||||
await this.shutdown({ archive: !this.failure });
|
||||
}
|
||||
|
||||
async processGeneration(event) {
|
||||
if (this.isCanceled(event.id)) return;
|
||||
await this.threadReady;
|
||||
if (this.isCanceled(event.id)) return;
|
||||
if (!event.scaffold?.file) event.scaffold = runDeterministicScaffold(event, {
|
||||
cwd: this.cwd,
|
||||
scriptsDir: this.scriptsDir,
|
||||
});
|
||||
this.active = { eventId: event.id, turnId: null, threadId: this.thread.id };
|
||||
this.writeState('working', { eventId: event.id });
|
||||
try {
|
||||
const expectedVariants = Number(event.count || 1);
|
||||
const snapshot = this.sessionStore.getSnapshot(event.id, { includeCompleted: true });
|
||||
const sameEpoch = Number(snapshot?.generationEpoch || 1) === Number(event.generationEpoch || 1);
|
||||
let arrivedVariants = sameEpoch ? Number(snapshot?.arrivedVariants || 0) : 0;
|
||||
let completedRemainder = false;
|
||||
if (this.config.delivery === 'progressive' && expectedVariants > 1) {
|
||||
if (arrivedVariants < 1) {
|
||||
await this.runGenerationPhase(event, 'first', 1);
|
||||
arrivedVariants = 1;
|
||||
}
|
||||
if (this.isCanceled(event.id)) return;
|
||||
if (arrivedVariants < expectedVariants) {
|
||||
await this.runGenerationPhase(event, 'remainder', expectedVariants);
|
||||
arrivedVariants = expectedVariants;
|
||||
completedRemainder = true;
|
||||
}
|
||||
if (this.isCanceled(event.id)) return;
|
||||
const latest = this.sessionStore.getSnapshot(event.id, { includeCompleted: true });
|
||||
if (!completedRemainder && arrivedVariants >= expectedVariants && latest?.paramsPublished !== true) {
|
||||
await this.runGenerationPhase(event, 'params', expectedVariants);
|
||||
}
|
||||
} else if (arrivedVariants < expectedVariants) {
|
||||
await this.runGenerationPhase(event, 'atomic', expectedVariants);
|
||||
}
|
||||
if (this.isCanceled(event.id)) return;
|
||||
await this.reply(this.base, this.token, {
|
||||
id: event.id,
|
||||
type: 'done',
|
||||
sourceEventType: event.type,
|
||||
file: event.scaffold.file,
|
||||
});
|
||||
} finally {
|
||||
if (this.active?.eventId === event.id) {
|
||||
this.active = null;
|
||||
this.writeState('ready');
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
startWorkerThread() {
|
||||
this.threadPrimed = false;
|
||||
return this.client.startDedicatedThread({
|
||||
model: this.model.model || this.model.id,
|
||||
cwd: this.cwd,
|
||||
approvalPolicy: 'never',
|
||||
sandbox: 'read-only',
|
||||
ephemeral: false,
|
||||
serviceName: 'impeccable_live_codex_worker',
|
||||
baseInstructions: buildCodexWorkerInstructions(this.liveSpec),
|
||||
});
|
||||
}
|
||||
|
||||
rotateWorkerThread(reason) {
|
||||
const priorThread = this.thread;
|
||||
const drainingQueue = this.queue;
|
||||
this.queue = Promise.resolve();
|
||||
this.thread = null;
|
||||
this.threadReady = this.startWorkerThread().then((thread) => {
|
||||
this.thread = thread;
|
||||
this.writeState('ready', {
|
||||
rotatedAt: new Date().toISOString(),
|
||||
rotationReason: reason,
|
||||
});
|
||||
return thread;
|
||||
});
|
||||
void this.threadReady.catch((error) => {
|
||||
this.writeState('error', { error: error.message, rotationReason: reason });
|
||||
this.log(`replacement worker thread failed: ${error.message}`);
|
||||
});
|
||||
if (priorThread) {
|
||||
void drainingQueue.finally(async () => {
|
||||
await this.client.archiveThread(priorThread.id).catch((error) => {
|
||||
this.log(`retired worker thread archive failed: ${error.message}`);
|
||||
});
|
||||
});
|
||||
}
|
||||
return this.threadReady;
|
||||
}
|
||||
|
||||
async runGenerationPhase(event, phase, arrivedVariants) {
|
||||
for (let attempt = 0; attempt < 2; attempt += 1) {
|
||||
try {
|
||||
return await this.runGenerationPhaseOnce(event, phase, arrivedVariants);
|
||||
} catch (error) {
|
||||
const sourceChangedDuringGeneration = error?.code === 'publish_source_hash_mismatch';
|
||||
if (!sourceChangedDuringGeneration || attempt > 0 || this.isCanceled(event.id)) throw error;
|
||||
this.log(`source changed during ${event.id} ${phase}; re-preparing once before publication`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
async runGenerationPhaseOnce(event, phase, arrivedVariants) {
|
||||
if (this.isCanceled(event.id)) return;
|
||||
const phaseStartedAt = Date.now();
|
||||
await this.publishPhase(this.base, this.token, {
|
||||
eventId: event.id,
|
||||
phase: generationPhaseName(phase, 'generating'),
|
||||
});
|
||||
const prepared = prepareCodexWorkerPhase({
|
||||
id: event.id,
|
||||
sourceFile: event.scaffold.file,
|
||||
cwd: this.cwd,
|
||||
});
|
||||
const artifact = readPreparedArtifact(prepared, {
|
||||
cwd: this.cwd,
|
||||
maxBytes: this.config.maxArtifactBytes,
|
||||
});
|
||||
const contexts = readGenerationContexts(this.cwd, this.scriptsDir, event, {
|
||||
includeStable: !this.threadPrimed,
|
||||
});
|
||||
const prompt = buildGenerationTurnInput({
|
||||
event,
|
||||
phase,
|
||||
prepared,
|
||||
artifact,
|
||||
variantPlan: this.sessionStore.getSnapshot(event.id, { includeCompleted: true })?.variantPlan || null,
|
||||
...contexts,
|
||||
});
|
||||
const input = buildCodexWorkerTurnInputs({
|
||||
prompt,
|
||||
skillPath: this.threadPrimed ? null : resolveCodexWorkerSkillPath(this.scriptsDir),
|
||||
screenshotPath: event.screenshotPath,
|
||||
cwd: this.cwd,
|
||||
});
|
||||
if (this.isCanceled(event.id)) return;
|
||||
const outputSchema = codexWorkerOutputSchemaForPhase(
|
||||
phase,
|
||||
Number(event.count || arrivedVariants),
|
||||
{ sourceDelta: (phase === 'first' || phase === 'remainder' || phase === 'params') && !isCodexComponentPreviewMode(prepared.previewMode) },
|
||||
);
|
||||
let result = await this.runTurnWithReconnect({
|
||||
input,
|
||||
outputSchema,
|
||||
eventId: event.id,
|
||||
effort: phase === 'params' ? 'low' : undefined,
|
||||
});
|
||||
this.threadPrimed = true;
|
||||
this.writeState('working', { eventId: event.id });
|
||||
if (this.isCanceled(event.id)) return;
|
||||
await this.publishPhase(this.base, this.token, {
|
||||
eventId: event.id,
|
||||
phase: generationPhaseName(phase, 'validating'),
|
||||
durationMs: Date.now() - phaseStartedAt,
|
||||
});
|
||||
|
||||
const baselineFindings = this.detectCandidate(prepared, {
|
||||
cwd: this.cwd,
|
||||
scriptsDir: this.scriptsDir,
|
||||
});
|
||||
let applied;
|
||||
let newFindings;
|
||||
let acceptedDetectorWaivers = [];
|
||||
for (let repairAttempt = 0; repairAttempt <= 1; repairAttempt += 1) {
|
||||
restorePreparedArtifact(prepared, artifact, { cwd: this.cwd });
|
||||
applied = applyCodexWorkerOutput({
|
||||
output: result.answer,
|
||||
prepared,
|
||||
phase,
|
||||
expectedVariants: Number(event.count || arrivedVariants),
|
||||
sessionId: event.id,
|
||||
scaffold: event.scaffold,
|
||||
cwd: this.cwd,
|
||||
maxBytes: this.config.maxArtifactBytes,
|
||||
});
|
||||
reconcileCandidateIfNeeded({
|
||||
applied,
|
||||
artifact,
|
||||
prepared,
|
||||
phase,
|
||||
arrivedVariants,
|
||||
cwd: this.cwd,
|
||||
});
|
||||
newFindings = diffDetectorFindings(
|
||||
baselineFindings,
|
||||
this.detectCandidate(prepared, { cwd: this.cwd, scriptsDir: this.scriptsDir }),
|
||||
);
|
||||
const waiverResolution = resolveDetectorFindingWaivers(
|
||||
newFindings,
|
||||
extractDetectorWaivers(result.answer),
|
||||
);
|
||||
newFindings = waiverResolution.unresolved;
|
||||
acceptedDetectorWaivers = waiverResolution.accepted;
|
||||
if (newFindings.length === 0) break;
|
||||
if (repairAttempt === 1) {
|
||||
const error = supervisorError('worker_output_detector_findings');
|
||||
error.findings = newFindings;
|
||||
throw error;
|
||||
}
|
||||
restorePreparedArtifact(prepared, artifact, { cwd: this.cwd });
|
||||
result = await this.runTurnWithReconnect({
|
||||
input: buildCodexWorkerTurnInputs({
|
||||
prompt: buildDetectorRepairPrompt(phase, newFindings),
|
||||
cwd: this.cwd,
|
||||
}),
|
||||
outputSchema: codexWorkerDetectorRepairSchema(outputSchema),
|
||||
eventId: event.id,
|
||||
});
|
||||
if (this.isCanceled(event.id)) return;
|
||||
}
|
||||
|
||||
if (applied.plan) {
|
||||
this.sessionStore.appendEvent({
|
||||
type: 'variant_plan',
|
||||
id: event.id,
|
||||
plan: applied.plan,
|
||||
});
|
||||
}
|
||||
if (acceptedDetectorWaivers.length > 0) {
|
||||
this.sessionStore.appendEvent({
|
||||
type: 'detector_waivers',
|
||||
id: event.id,
|
||||
phase,
|
||||
waivers: acceptedDetectorWaivers.map(({ waiver }) => waiver),
|
||||
});
|
||||
}
|
||||
if (this.isCanceled(event.id)) return;
|
||||
const published = publishCodexWorkerPhase({ event, prepared, arrivedVariants, phase, cwd: this.cwd });
|
||||
let checkpointError;
|
||||
for (let attempt = 0; attempt < 2; attempt += 1) {
|
||||
try {
|
||||
await this.publishCheckpoint(this.base, this.token, {
|
||||
event,
|
||||
published,
|
||||
scaffold: event.scaffold,
|
||||
arrivedVariants,
|
||||
});
|
||||
checkpointError = null;
|
||||
break;
|
||||
} catch (error) {
|
||||
checkpointError = error;
|
||||
}
|
||||
}
|
||||
if (checkpointError) throw checkpointError;
|
||||
if (['remainder', 'params', 'atomic'].includes(phase)) {
|
||||
await this.publishPhase(this.base, this.token, {
|
||||
eventId: event.id,
|
||||
phase: 'parameters_ready',
|
||||
durationMs: Date.now() - phaseStartedAt,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
async runTurnWithReconnect({
|
||||
input,
|
||||
outputSchema,
|
||||
onAgentMessage,
|
||||
eventId = this.active?.eventId,
|
||||
effort,
|
||||
}) {
|
||||
let firstError;
|
||||
for (let attempt = 0; attempt < 2; attempt += 1) {
|
||||
try {
|
||||
const threadId = this.thread.id;
|
||||
if (this.active?.eventId === eventId) this.active.threadId = threadId;
|
||||
const turn = await this.client.startTurn({
|
||||
threadId,
|
||||
input,
|
||||
cwd: this.cwd,
|
||||
model: this.model.model || this.model.id,
|
||||
effort: preferredEffort(this.model, effort || this.config.effort),
|
||||
summary: 'none',
|
||||
approvalPolicy: 'never',
|
||||
sandboxPolicy: { type: 'readOnly' },
|
||||
outputSchema,
|
||||
onAgentMessage,
|
||||
onStarted: (turnId) => {
|
||||
if (this.active?.eventId === eventId) this.active.turnId = turnId;
|
||||
if (eventId && this.isCanceled(eventId)) {
|
||||
this.client.interruptTurn(threadId, turnId).catch(() => {});
|
||||
}
|
||||
},
|
||||
});
|
||||
return { ...turn, answer: turn.message };
|
||||
} catch (error) {
|
||||
if (!firstError) firstError = error;
|
||||
if (eventId && this.isCanceled(eventId)) throw error;
|
||||
if (attempt > 0 || error.code === 'TURN_INTERRUPTED') throw error;
|
||||
this.log(`app-server turn failed; reconnecting once: ${error.message}`);
|
||||
await this.reconnect();
|
||||
}
|
||||
}
|
||||
throw firstError;
|
||||
}
|
||||
|
||||
async reconnect() {
|
||||
this.thread = await this.reconnectThread(this.thread, this.model);
|
||||
this.writeState('ready', { reconnectedAt: new Date().toISOString() });
|
||||
}
|
||||
|
||||
async reconnectThread(thread, model = this.model) {
|
||||
const resumed = await this.client.reconnect({
|
||||
threadId: thread.id,
|
||||
resumeParams: {
|
||||
model: model.model || model.id,
|
||||
cwd: this.cwd,
|
||||
approvalPolicy: 'never',
|
||||
sandbox: 'read-only',
|
||||
baseInstructions: buildCodexWorkerInstructions(this.liveSpec),
|
||||
},
|
||||
});
|
||||
if (thread === this.thread) {
|
||||
this.thread = resumed;
|
||||
this.writeState('ready', { reconnectedAt: new Date().toISOString() });
|
||||
}
|
||||
return resumed;
|
||||
}
|
||||
|
||||
async cancelActive(reason, eventId = null) {
|
||||
if (!this.active) return;
|
||||
if (eventId && this.active.eventId !== eventId) return;
|
||||
this.canceled.add(this.active.eventId);
|
||||
const threadId = this.active.threadId || this.thread?.id;
|
||||
if (threadId && this.active.turnId) {
|
||||
await this.client.interruptTurn(threadId, this.active.turnId).catch(() => {});
|
||||
}
|
||||
this.log(`interrupted ${this.active.eventId}: ${reason}`);
|
||||
}
|
||||
|
||||
async handleGenerationFailure(event, error) {
|
||||
if (this.isCanceled(event.id) || error.code === 'TURN_INTERRUPTED') return;
|
||||
this.log(`generation ${event.id} failed: ${error.stack || error.message}`);
|
||||
this.failure = {
|
||||
eventId: event.id,
|
||||
error: error.message,
|
||||
failedAt: new Date().toISOString(),
|
||||
};
|
||||
this.running = false;
|
||||
this.pollAbortController?.abort();
|
||||
if (this.activePoll) {
|
||||
await Promise.race([
|
||||
this.activePoll.catch(() => null),
|
||||
new Promise((resolve) => {
|
||||
const timer = setTimeout(resolve, 250);
|
||||
timer.unref?.();
|
||||
}),
|
||||
]);
|
||||
}
|
||||
await this.reply(this.base, this.token, {
|
||||
id: event.id,
|
||||
type: 'retry',
|
||||
sourceEventType: event.type,
|
||||
}).catch(() => {});
|
||||
this.writeState('failed', this.failure);
|
||||
}
|
||||
|
||||
isCanceled(eventId) {
|
||||
return this.canceled.has(eventId) || generationIsCanceled(eventId, { cwd: this.cwd });
|
||||
}
|
||||
|
||||
async shutdown({ archive = false } = {}) {
|
||||
this.running = false;
|
||||
await this.cancelActive('shutdown');
|
||||
await Promise.race([
|
||||
this.threadReady.catch(() => null),
|
||||
new Promise((resolve) => {
|
||||
const timer = setTimeout(resolve, 1_000);
|
||||
timer.unref?.();
|
||||
}),
|
||||
]);
|
||||
let archived = false;
|
||||
if (archive && this.thread) {
|
||||
try {
|
||||
await this.client.archiveThread(this.thread.id);
|
||||
archived = true;
|
||||
} catch (error) {
|
||||
if (/no rollout found/i.test(String(error?.message || ''))) {
|
||||
archived = true;
|
||||
this.log('empty worker thread had no persisted rollout; treating it as archived');
|
||||
} else {
|
||||
this.log(`thread archive failed: ${error.message}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
await this.client.close().catch(() => {});
|
||||
this.writeState(
|
||||
this.failure ? 'failed' : archived ? 'archived' : 'stopped',
|
||||
{ archived, ...(this.failure || {}) },
|
||||
);
|
||||
}
|
||||
|
||||
status() {
|
||||
return {
|
||||
ok: true,
|
||||
owner: CODEX_WORKER_OWNER,
|
||||
cwd: this.cwd,
|
||||
pid: process.pid,
|
||||
status: this.active ? 'working' : 'ready',
|
||||
threadId: this.thread?.id || null,
|
||||
model: this.model?.model || this.model?.id || null,
|
||||
effort: this.model ? preferredEffort(this.model, this.config.effort) : this.config.effort,
|
||||
profile: this.config.profile,
|
||||
delivery: this.config.delivery,
|
||||
threadPrimed: this.threadPrimed,
|
||||
eventId: this.active?.eventId || null,
|
||||
};
|
||||
}
|
||||
|
||||
writeState(status, extra = {}) {
|
||||
const state = {
|
||||
...this.status(),
|
||||
...extra,
|
||||
status,
|
||||
updatedAt: new Date().toISOString(),
|
||||
};
|
||||
atomicWriteJson(this.statePath, state);
|
||||
return state;
|
||||
}
|
||||
}
|
||||
|
||||
function generationPhaseName(phase, state) {
|
||||
if (phase === 'first') return `first_variant_${state}`;
|
||||
if (phase === 'params') return `variant_parameters_${state}`;
|
||||
return `remaining_variants_${state}`;
|
||||
}
|
||||
|
||||
function preferredEffort(model, requested) {
|
||||
const supported = (model?.supportedReasoningEfforts || [])
|
||||
.map((option) => typeof option === 'string' ? option : option?.reasoningEffort)
|
||||
.filter(Boolean);
|
||||
if (requested && supported.includes(requested)) return requested;
|
||||
return selectLowestReasoningEffort(model);
|
||||
}
|
||||
|
||||
export async function postVariantCheckpoint(base, token, {
|
||||
event,
|
||||
published,
|
||||
scaffold,
|
||||
arrivedVariants,
|
||||
}) {
|
||||
const response = await fetch(`${base}/events`, {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({
|
||||
token,
|
||||
type: 'checkpoint',
|
||||
id: event.id,
|
||||
revision: published.revision,
|
||||
revisionDomain: 'publication',
|
||||
phase: 'cycling',
|
||||
reason: 'variants_progress',
|
||||
arrivedVariants,
|
||||
expectedVariants: event.count,
|
||||
sourceFile: scaffold.sourceFile || scaffold.file,
|
||||
previewFile: scaffold.file,
|
||||
previewMode: scaffold.previewMode || 'source',
|
||||
publicationKind: published.publicationKind || 'variants',
|
||||
}),
|
||||
});
|
||||
if (!response.ok) throw supervisorError(`checkpoint_${response.status}`);
|
||||
}
|
||||
|
||||
export async function postAgentPhase(base, token, {
|
||||
eventId,
|
||||
phase,
|
||||
durationMs,
|
||||
}) {
|
||||
const response = await fetch(`${base}/events`, {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({
|
||||
token,
|
||||
type: 'agent_phase',
|
||||
id: eventId,
|
||||
phase,
|
||||
owner: CODEX_WORKER_OWNER,
|
||||
...(Number.isFinite(durationMs) ? { durationMs } : {}),
|
||||
}),
|
||||
});
|
||||
if (!response.ok) throw supervisorError(`agent_phase_${response.status}`);
|
||||
}
|
||||
|
||||
export async function postCarbonizeCleanup(base, token, {
|
||||
sessionId,
|
||||
file,
|
||||
variantId,
|
||||
acceptResult,
|
||||
id = randomBytes(4).toString('hex'),
|
||||
}) {
|
||||
const response = await fetch(`${base}/events`, {
|
||||
method: 'POST',
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
body: JSON.stringify({
|
||||
token,
|
||||
type: 'carbonize_cleanup',
|
||||
id,
|
||||
sessionId,
|
||||
file,
|
||||
variantId,
|
||||
acceptResult,
|
||||
}),
|
||||
});
|
||||
if (!response.ok) throw supervisorError(`carbonize_cleanup_${response.status}`);
|
||||
return { id, ...(await response.json()) };
|
||||
}
|
||||
|
||||
export function buildDeterministicScaffoldCommand(event, scriptsDir) {
|
||||
const insert = event.mode === 'insert';
|
||||
const script = path.join(scriptsDir, insert ? 'live-insert.mjs' : 'live-wrap.mjs');
|
||||
const args = ['--id', String(event.id), '--count', String(event.count || 3)];
|
||||
const target = insert ? event.insert?.anchor || {} : event.element || {};
|
||||
if (!insert) args.push('--isolated');
|
||||
if (insert) args.push('--position', String(event.insert?.position || 'after'));
|
||||
if (target.id) args.push('--element-id', String(target.id));
|
||||
const classes = Array.isArray(target.classes) ? target.classes.join(',') : target.className;
|
||||
if (classes) args.push('--classes', String(classes));
|
||||
if (target.tagName || target.tag) args.push('--tag', String(target.tagName || target.tag).toLowerCase());
|
||||
const text = String(target.textContent || target.text || '').trim().replace(/\s+/g, ' ').slice(0, 80);
|
||||
if (!target.id && !classes && text) args.push('--query', text);
|
||||
if (text) args.push('--text', text);
|
||||
return { script, args };
|
||||
}
|
||||
|
||||
export function runDeterministicScaffold(event, {
|
||||
cwd = process.cwd(),
|
||||
scriptsDir,
|
||||
exec = execFileSync,
|
||||
} = {}) {
|
||||
const command = buildDeterministicScaffoldCommand(event, scriptsDir);
|
||||
let output;
|
||||
try {
|
||||
output = exec(process.execPath, [command.script, ...command.args], {
|
||||
cwd,
|
||||
encoding: 'utf-8',
|
||||
timeout: 30_000,
|
||||
});
|
||||
} catch (error) {
|
||||
throw supervisorError(`codex_worker_scaffold_failed:${error.stderr || error.message}`);
|
||||
}
|
||||
let scaffold;
|
||||
try { scaffold = JSON.parse(String(output).trim()); } catch { throw supervisorError('codex_worker_scaffold_invalid'); }
|
||||
if (!scaffold?.file || scaffold.error) {
|
||||
throw supervisorError(`codex_worker_scaffold_${scaffold?.error || 'missing_file'}`);
|
||||
}
|
||||
return scaffold;
|
||||
}
|
||||
|
||||
function restorePreparedArtifact(prepared, artifact, { cwd }) {
|
||||
if (!isCodexComponentPreviewMode(prepared.previewMode)) {
|
||||
fs.writeFileSync(path.resolve(cwd, prepared.artifactFile), artifact.content, 'utf-8');
|
||||
return;
|
||||
}
|
||||
const componentDir = path.resolve(cwd, prepared.componentDir);
|
||||
fs.mkdirSync(componentDir, { recursive: true });
|
||||
for (const name of fs.readdirSync(componentDir)) {
|
||||
if (/^(?:v\d+\.(?:svelte|vue)|params\.json)$/.test(name)) {
|
||||
fs.unlinkSync(path.join(componentDir, name));
|
||||
}
|
||||
}
|
||||
for (const [name, content] of Object.entries(artifact.files || {})) {
|
||||
fs.writeFileSync(path.join(componentDir, name), content, 'utf-8');
|
||||
}
|
||||
fs.writeFileSync(
|
||||
path.resolve(cwd, prepared.artifactFile),
|
||||
JSON.stringify(artifact.manifest, null, 2) + '\n',
|
||||
'utf-8',
|
||||
);
|
||||
}
|
||||
|
||||
function reconcileCandidateIfNeeded({ applied, artifact, prepared, phase, arrivedVariants, cwd }) {
|
||||
if (isCodexComponentPreviewMode(prepared.previewMode) || applied.sourceDelta || phase !== 'remainder') return;
|
||||
const candidatePath = path.resolve(cwd, prepared.artifactFile);
|
||||
const reconciled = reconcilePublishedSourceVariants({
|
||||
current: artifact.content,
|
||||
candidate: fs.readFileSync(candidatePath, 'utf-8'),
|
||||
priorArrived: Math.max(1, arrivedVariants - 1),
|
||||
});
|
||||
if (!reconciled.ok) throw supervisorError(`reconcile_${reconciled.error}`);
|
||||
fs.writeFileSync(candidatePath, reconciled.content, 'utf-8');
|
||||
}
|
||||
|
||||
export function detectPreparedArtifact(prepared, {
|
||||
cwd = process.cwd(),
|
||||
scriptsDir = LOCAL_SCRIPTS_DIR,
|
||||
spawn = spawnSync,
|
||||
} = {}) {
|
||||
const targets = detectorTargets(prepared, cwd);
|
||||
if (targets.length === 0) return [];
|
||||
const detectorScript = [
|
||||
path.join(scriptsDir, 'detect.mjs'),
|
||||
path.join(LOCAL_SCRIPTS_DIR, 'detect.mjs'),
|
||||
].find((candidate) => fs.existsSync(candidate));
|
||||
if (!detectorScript) throw supervisorError('codex_worker_detector_unavailable');
|
||||
const result = spawn(process.execPath, [detectorScript, '--json', ...targets], {
|
||||
cwd,
|
||||
encoding: 'utf-8',
|
||||
maxBuffer: 8 * 1024 * 1024,
|
||||
});
|
||||
if (result.error) throw supervisorError(`codex_worker_detector_failed:${result.error.message}`);
|
||||
try {
|
||||
const findings = JSON.parse(String(result.stdout || '[]'));
|
||||
if (!Array.isArray(findings)) throw new Error('expected findings array');
|
||||
return findings;
|
||||
} catch (error) {
|
||||
throw supervisorError(`codex_worker_detector_invalid:${error.message}`);
|
||||
}
|
||||
}
|
||||
|
||||
function detectorTargets(prepared, cwd) {
|
||||
if (!isCodexComponentPreviewMode(prepared.previewMode)) {
|
||||
return [path.resolve(cwd, prepared.artifactFile)];
|
||||
}
|
||||
const componentDir = path.resolve(cwd, prepared.componentDir);
|
||||
try {
|
||||
return fs.readdirSync(componentDir)
|
||||
.filter((name) => /\.(?:vue|svelte)$/.test(name))
|
||||
.map((name) => path.join(componentDir, name));
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
}
|
||||
|
||||
export function diffDetectorFindings(before, after) {
|
||||
const remaining = new Map();
|
||||
for (const finding of before || []) {
|
||||
const key = detectorFindingKey(finding);
|
||||
remaining.set(key, (remaining.get(key) || 0) + 1);
|
||||
}
|
||||
const added = [];
|
||||
for (const finding of after || []) {
|
||||
const key = detectorFindingKey(finding);
|
||||
const count = remaining.get(key) || 0;
|
||||
if (count > 0) remaining.set(key, count - 1);
|
||||
else added.push(finding);
|
||||
}
|
||||
return added;
|
||||
}
|
||||
|
||||
function detectorFindingKey(finding) {
|
||||
return [
|
||||
path.basename(String(finding?.file || '')),
|
||||
finding?.antipattern || finding?.id || '',
|
||||
finding?.snippet || '',
|
||||
finding?.ignoreValue || '',
|
||||
].join('\u0000');
|
||||
}
|
||||
|
||||
export function buildDetectorRepairPrompt(phase, findings) {
|
||||
return [
|
||||
`The candidate for Live phase ${phase} has new Impeccable detector findings.`,
|
||||
'Use design judgment on every finding. Fix real defects. If a finding is contextually intentional or a detector false positive, leave that design intact and add one narrow detectorWaivers entry copied from the finding with a concrete reason. Return detectorWaivers as an empty array when every finding was fixed. Every finding must either disappear on the next scan or match an explicit waiver; unresolved findings still block publication.',
|
||||
'Return the complete replacement JSON for the same phase and schema. Do not explain, call tools, persist project detector config, add inline ignore comments, or alter immutable variants.',
|
||||
'<detector_findings>',
|
||||
JSON.stringify((findings || []).slice(0, 40).map((finding) => ({
|
||||
rule: finding.antipattern || finding.id,
|
||||
name: finding.name,
|
||||
description: finding.description,
|
||||
severity: finding.severity,
|
||||
snippet: finding.snippet,
|
||||
file: path.basename(String(finding.file || '')),
|
||||
ignoreValue: finding.ignoreValue || '',
|
||||
})), null, 2),
|
||||
'</detector_findings>',
|
||||
].join('\n');
|
||||
}
|
||||
|
||||
export function resolveDetectorFindingWaivers(findings, waivers) {
|
||||
const candidates = (Array.isArray(waivers) ? waivers : [])
|
||||
.map(normalizeDetectorWaiver)
|
||||
.filter(Boolean);
|
||||
const accepted = [];
|
||||
const unresolved = [];
|
||||
for (const finding of findings || []) {
|
||||
const waiver = candidates.find((candidate) => detectorWaiverMatches(candidate, finding));
|
||||
if (waiver) accepted.push({ finding, waiver });
|
||||
else unresolved.push(finding);
|
||||
}
|
||||
return { accepted, unresolved };
|
||||
}
|
||||
|
||||
function extractDetectorWaivers(output) {
|
||||
try {
|
||||
const parsed = typeof output === 'string' ? JSON.parse(output) : output;
|
||||
return Array.isArray(parsed?.detectorWaivers) ? parsed.detectorWaivers : [];
|
||||
} catch {
|
||||
return [];
|
||||
}
|
||||
}
|
||||
|
||||
function normalizeDetectorWaiver(waiver) {
|
||||
if (!waiver || typeof waiver !== 'object') return null;
|
||||
const normalized = {
|
||||
rule: String(waiver.rule || '').trim().toLowerCase(),
|
||||
file: path.basename(String(waiver.file || '').trim()),
|
||||
snippet: String(waiver.snippet || '').trim(),
|
||||
ignoreValue: String(waiver.ignoreValue || '').trim(),
|
||||
reason: String(waiver.reason || '').trim(),
|
||||
};
|
||||
return normalized.rule && normalized.reason && (normalized.snippet || normalized.ignoreValue)
|
||||
? normalized
|
||||
: null;
|
||||
}
|
||||
|
||||
function detectorWaiverMatches(waiver, finding) {
|
||||
const rule = String(finding?.antipattern || finding?.id || '').trim().toLowerCase();
|
||||
const file = path.basename(String(finding?.file || '').trim());
|
||||
const snippet = String(finding?.snippet || '').trim();
|
||||
const ignoreValue = String(finding?.ignoreValue || '').trim();
|
||||
if (waiver.rule !== rule) return false;
|
||||
if (waiver.file && waiver.file !== file) return false;
|
||||
if (waiver.ignoreValue) return waiver.ignoreValue === ignoreValue;
|
||||
return Boolean(waiver.snippet && waiver.snippet === snippet);
|
||||
}
|
||||
|
||||
function readGenerationContexts(cwd, scriptsDir, event, { includeStable = true } = {}) {
|
||||
const context = loadContext(cwd);
|
||||
const action = event?.action;
|
||||
const safeAction = typeof action === 'string' && /^[a-z-]+$/.test(action) && action !== 'impeccable'
|
||||
? action
|
||||
: null;
|
||||
return {
|
||||
product: includeStable ? context.product || '' : '',
|
||||
design: includeStable ? context.design || '' : '',
|
||||
actionReference: safeAction
|
||||
? readOptional(path.join(scriptsDir, '..', 'reference', `${safeAction}.md`))
|
||||
: '',
|
||||
contextMetadata: includeStable ? {
|
||||
productPath: context.productPath,
|
||||
designPath: context.designPath,
|
||||
projectRoot: context.projectRoot,
|
||||
repoRoot: context.repoRoot,
|
||||
isMonorepo: context.isMonorepo,
|
||||
} : {},
|
||||
};
|
||||
}
|
||||
|
||||
function readOptional(file) {
|
||||
try { return fs.readFileSync(file, 'utf-8'); } catch { return ''; }
|
||||
}
|
||||
|
||||
function readJson(file) {
|
||||
try { return JSON.parse(fs.readFileSync(file, 'utf-8')); } catch { return null; }
|
||||
}
|
||||
|
||||
function atomicWriteJson(file, value) {
|
||||
fs.mkdirSync(path.dirname(file), { recursive: true });
|
||||
const temporary = `${file}.${process.pid}.${Date.now()}.tmp`;
|
||||
fs.writeFileSync(temporary, JSON.stringify(value, null, 2) + '\n', 'utf-8');
|
||||
fs.renameSync(temporary, file);
|
||||
}
|
||||
|
||||
function supervisorError(code) {
|
||||
const error = new Error(code);
|
||||
error.code = code;
|
||||
return error;
|
||||
}
|
||||
@@ -0,0 +1,975 @@
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import {
|
||||
prepareGenerationArtifact,
|
||||
publishGenerationArtifact,
|
||||
} from './generation-publisher.mjs';
|
||||
import { createLiveSessionStore } from './session-store.mjs';
|
||||
|
||||
export const CODEX_WORKER_OWNER = 'impeccable-live-codex-worker-v1';
|
||||
export const CODEX_CLI_SETUP_URL = 'https://learn.chatgpt.com/docs/codex/cli';
|
||||
const VARIANT_PLAN_SCHEMA = Object.freeze({
|
||||
type: 'object',
|
||||
properties: {
|
||||
identityLock: {
|
||||
type: 'array',
|
||||
minItems: 1,
|
||||
maxItems: 8,
|
||||
items: { type: 'string', minLength: 1, maxLength: 240 },
|
||||
},
|
||||
directions: {
|
||||
type: 'array',
|
||||
minItems: 1,
|
||||
maxItems: 6,
|
||||
items: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
variantId: { type: 'integer', minimum: 1, maximum: 6 },
|
||||
name: { type: 'string', minLength: 1, maxLength: 80 },
|
||||
axis: { type: 'string', minLength: 1, maxLength: 120 },
|
||||
intent: { type: 'string', minLength: 1, maxLength: 300 },
|
||||
},
|
||||
required: ['variantId', 'name', 'axis', 'intent'],
|
||||
additionalProperties: false,
|
||||
},
|
||||
},
|
||||
},
|
||||
required: ['identityLock', 'directions'],
|
||||
additionalProperties: false,
|
||||
});
|
||||
export const CODEX_WORKER_OUTPUT_SCHEMA = Object.freeze({
|
||||
type: 'object',
|
||||
properties: {
|
||||
files: {
|
||||
type: 'array',
|
||||
minItems: 1,
|
||||
items: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
path: { type: 'string', minLength: 1 },
|
||||
content: { type: 'string' },
|
||||
},
|
||||
required: ['path', 'content'],
|
||||
additionalProperties: false,
|
||||
},
|
||||
},
|
||||
},
|
||||
required: ['files'],
|
||||
additionalProperties: false,
|
||||
});
|
||||
const DETECTOR_WAIVER_SCHEMA = Object.freeze({
|
||||
type: 'array',
|
||||
maxItems: 40,
|
||||
items: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
rule: { type: 'string', minLength: 1 },
|
||||
file: { type: 'string' },
|
||||
snippet: { type: 'string' },
|
||||
ignoreValue: { type: 'string' },
|
||||
reason: { type: 'string', minLength: 1, maxLength: 500 },
|
||||
},
|
||||
required: ['rule', 'file', 'snippet', 'ignoreValue', 'reason'],
|
||||
additionalProperties: false,
|
||||
},
|
||||
});
|
||||
export function codexWorkerOutputSchemaForPhase(
|
||||
phase,
|
||||
expectedVariants = 3,
|
||||
{ sourceDelta = false } = {},
|
||||
) {
|
||||
const requirePlan = Number(expectedVariants) > 1 && (phase === 'first' || phase === 'atomic');
|
||||
if (sourceDelta) return codexSourceDeltaOutputSchema(phase, requirePlan, expectedVariants);
|
||||
return {
|
||||
...CODEX_WORKER_OUTPUT_SCHEMA,
|
||||
properties: requirePlan
|
||||
? { ...CODEX_WORKER_OUTPUT_SCHEMA.properties, plan: VARIANT_PLAN_SCHEMA }
|
||||
: CODEX_WORKER_OUTPUT_SCHEMA.properties,
|
||||
required: requirePlan ? ['files', 'plan'] : ['files'],
|
||||
};
|
||||
}
|
||||
|
||||
export function codexWorkerDetectorRepairSchema(outputSchema) {
|
||||
return {
|
||||
...outputSchema,
|
||||
properties: {
|
||||
...outputSchema.properties,
|
||||
detectorWaivers: DETECTOR_WAIVER_SCHEMA,
|
||||
},
|
||||
required: [...outputSchema.required, 'detectorWaivers'],
|
||||
};
|
||||
}
|
||||
|
||||
function codexSourceDeltaOutputSchema(phase, requirePlan, expectedVariants) {
|
||||
const variantDelta = (minimum, maximum = minimum) => ({
|
||||
type: 'object',
|
||||
properties: {
|
||||
variantId: { type: 'integer', minimum, maximum },
|
||||
markup: { type: 'string', minLength: 1 },
|
||||
css: { type: 'string', minLength: 1 },
|
||||
},
|
||||
required: ['variantId', 'markup', 'css'],
|
||||
additionalProperties: false,
|
||||
});
|
||||
let phaseProperties;
|
||||
let phaseRequired;
|
||||
if (phase === 'first') {
|
||||
phaseProperties = { sourceDelta: variantDelta(1) };
|
||||
phaseRequired = ['sourceDelta'];
|
||||
} else if (phase === 'remainder') {
|
||||
phaseProperties = {
|
||||
sourceDeltas: {
|
||||
type: 'array',
|
||||
minItems: Math.max(1, Number(expectedVariants) - 1),
|
||||
maxItems: Math.max(1, Number(expectedVariants) - 1),
|
||||
items: variantDelta(2, Number(expectedVariants)),
|
||||
},
|
||||
parameterCss: { type: 'string' },
|
||||
paramsJson: { type: 'string', minLength: 2 },
|
||||
};
|
||||
phaseRequired = ['sourceDeltas', 'parameterCss', 'paramsJson'];
|
||||
} else if (phase === 'params') {
|
||||
phaseProperties = {
|
||||
parameterCss: { type: 'string' },
|
||||
paramsJson: { type: 'string', minLength: 2 },
|
||||
};
|
||||
phaseRequired = ['parameterCss', 'paramsJson'];
|
||||
} else {
|
||||
phaseProperties = { sourceDelta: variantDelta(Number(expectedVariants)) };
|
||||
phaseRequired = ['sourceDelta'];
|
||||
}
|
||||
return {
|
||||
type: 'object',
|
||||
properties: requirePlan
|
||||
? { ...phaseProperties, plan: VARIANT_PLAN_SCHEMA }
|
||||
: phaseProperties,
|
||||
required: requirePlan ? [...phaseRequired, 'plan'] : phaseRequired,
|
||||
additionalProperties: false,
|
||||
};
|
||||
}
|
||||
|
||||
export function resolveCodexWorkerConfig({ env = process.env, liveConfig = {} } = {}) {
|
||||
const configured = liveConfig.experimentalCodexWorker || liveConfig.codexWorker || {};
|
||||
const envEnabled = parseBoolean(env.IMPECCABLE_LIVE_CODEX_WORKER);
|
||||
// Activation remains process-local. Codex gets the worker by default, while
|
||||
// committed project settings can never switch another harness onto Codex.
|
||||
const enabled = envEnabled == null ? isCodexRuntime(env) : envEnabled;
|
||||
const profile = nonEmpty(env.IMPECCABLE_LIVE_CODEX_PROFILE)
|
||||
|| nonEmpty(configured.profile)
|
||||
|| 'quality';
|
||||
const requestedDelivery = nonEmpty(env.IMPECCABLE_LIVE_CODEX_DELIVERY)
|
||||
|| nonEmpty(configured.delivery)
|
||||
|| 'progressive';
|
||||
return {
|
||||
enabled,
|
||||
model: nonEmpty(env.IMPECCABLE_LIVE_CODEX_MODEL) || nonEmpty(configured.model) || null,
|
||||
codexPath: nonEmpty(env.IMPECCABLE_CODEX_PATH) || nonEmpty(configured.codexPath) || 'codex',
|
||||
effort: nonEmpty(env.IMPECCABLE_LIVE_CODEX_EFFORT)
|
||||
|| nonEmpty(configured.effort)
|
||||
|| (profile === 'fast' ? 'low' : 'medium'),
|
||||
profile: profile === 'fast' ? 'fast' : 'quality',
|
||||
delivery: requestedDelivery === 'atomic' ? 'atomic' : 'progressive',
|
||||
maxArtifactBytes: positiveInteger(configured.maxArtifactBytes, 2_000_000),
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve the executable exactly as Node's spawn path would: explicit paths
|
||||
* stay project-relative, while bare commands are searched on PATH. This is a
|
||||
* filesystem-only preflight so Live can fall back synchronously without
|
||||
* adding another Codex process to the initialization critical path.
|
||||
*/
|
||||
export function resolveCodexExecutable(command = 'codex', {
|
||||
cwd = process.cwd(),
|
||||
env = process.env,
|
||||
platform = process.platform,
|
||||
} = {}) {
|
||||
const requested = String(command || '').trim();
|
||||
if (!requested) {
|
||||
return { available: false, error: 'codex_cli_unavailable', command: 'codex' };
|
||||
}
|
||||
|
||||
const pathApi = platform === 'win32' ? path.win32 : path;
|
||||
const pathLike = pathApi.isAbsolute(requested)
|
||||
|| requested.includes('/')
|
||||
|| requested.includes('\\');
|
||||
const extensions = executableExtensions(requested, env, platform);
|
||||
const candidates = [];
|
||||
|
||||
if (pathLike) {
|
||||
const base = pathApi.isAbsolute(requested) ? requested : pathApi.resolve(cwd, requested);
|
||||
for (const extension of extensions) candidates.push(base + extension);
|
||||
} else {
|
||||
const pathValue = env.PATH || env.Path || env.path
|
||||
|| (platform === 'win32' ? '' : '/usr/bin:/bin');
|
||||
for (const rawEntry of String(pathValue).split(pathApi.delimiter)) {
|
||||
const entry = rawEntry.replace(/^"|"$/g, '') || cwd;
|
||||
for (const extension of extensions) candidates.push(pathApi.join(entry, requested + extension));
|
||||
}
|
||||
}
|
||||
|
||||
for (const candidate of candidates) {
|
||||
try {
|
||||
fs.accessSync(candidate, platform === 'win32' ? fs.constants.F_OK : fs.constants.X_OK);
|
||||
if (!fs.statSync(candidate).isFile()) continue;
|
||||
return { available: true, command: requested, resolvedPath: candidate };
|
||||
} catch {
|
||||
// Keep searching PATH. Shell aliases are intentionally ignored because
|
||||
// child_process.spawn cannot resolve them either.
|
||||
}
|
||||
}
|
||||
|
||||
return { available: false, error: 'codex_cli_unavailable', command: requested };
|
||||
}
|
||||
|
||||
function executableExtensions(command, env, platform) {
|
||||
if (platform !== 'win32') return [''];
|
||||
if (path.win32.extname(command)) return [''];
|
||||
const value = env.PATHEXT || env.Pathext || '.COM;.EXE;.BAT;.CMD';
|
||||
return String(value)
|
||||
.split(';')
|
||||
.map((extension) => extension.trim())
|
||||
.filter(Boolean)
|
||||
.map((extension) => extension.startsWith('.') ? extension : `.${extension}`);
|
||||
}
|
||||
|
||||
export function isCodexRuntime(env = process.env) {
|
||||
return Boolean(
|
||||
nonEmpty(env.CODEX_THREAD_ID)
|
||||
|| nonEmpty(env.CODEX_INTERNAL_ORIGINATOR_OVERRIDE)
|
||||
|| parseBoolean(env.CODEX_CI) === true,
|
||||
);
|
||||
}
|
||||
|
||||
export function buildCodexWorkerInstructions(liveSpec) {
|
||||
return [
|
||||
'You are a dedicated Impeccable Live variant producer, never the foreground desktop task.',
|
||||
'The Impeccable skill is attached on the first turn of this persistent Live thread. Its Setup context is already resolved in the user message; do not rerun setup.',
|
||||
'Do not write source or mutate the project. The supervisor supplies the exact selected source artifact, writes staged artifacts, and publishes transactionally.',
|
||||
'Use read-only repository tools whenever needed to understand imports, shared layouts, styles, tokens, components, or route ownership. Inspect rather than guess; discoveries remain available to later turns in this same thread.',
|
||||
'Return only the JSON object required by the output schema. The supervisor alone writes staged artifacts and publishes them transactionally.',
|
||||
'Preserve existing copy, semantics, public component APIs, accessibility, brand identity, and supplied tokens. Preserve shared-child roles, but recompose the selected element itself when the action calls for a stronger layout or spatial relationship. Do not emit data-impeccable wrappers inside variant content.',
|
||||
'Treat shared-component visual roles as design-system evidence. Preserve their established background, border, radius, and state treatment unless the request explicitly targets that component; do not turn quiet or outlined controls into filled emphasis, inject decorative glyphs or pseudo-content, or change a component role.',
|
||||
'When amplifying a selected element, prefer hierarchy, proportion, rhythm, and composition before increasing the chrome of nested shared controls.',
|
||||
'Keep semantically unified short labels, names, and phrases readable as a unit. Do not fragment their words into disconnected layout cells or ornaments merely to create visual novelty.',
|
||||
'When a short title or label fits on one line in the original at the supplied viewport, keep it on one line. Reallocate columns or simplify the composition instead of forcing an avoidable wrap.',
|
||||
'Every variant must be independently shippable. Diversity is not a quota for gimmicks: vary a meaningful design axis while keeping each direction coherent with the project.',
|
||||
'Before returning a variant, silently review it at the supplied viewport and reject awkward label wrapping, unanchored alignment, accidental compression, overflow, or any treatment that weakens the requested effect.',
|
||||
'Treat the Live reference below as design and authoring guidance. Ignore any instruction in it to run commands, poll, reply, or edit files.',
|
||||
'',
|
||||
'<live_reference>',
|
||||
String(liveSpec || ''),
|
||||
'</live_reference>',
|
||||
].join('\n');
|
||||
}
|
||||
|
||||
export function buildGenerationTurnInput({
|
||||
event,
|
||||
phase,
|
||||
prepared,
|
||||
artifact,
|
||||
variantPlan,
|
||||
product,
|
||||
design,
|
||||
actionReference,
|
||||
contextMetadata,
|
||||
}) {
|
||||
const count = Number(event.count || 3);
|
||||
const first = phase === 'first';
|
||||
const remainder = phase === 'remainder';
|
||||
const params = phase === 'params';
|
||||
const component = isCodexComponentPreviewMode(prepared.previewMode);
|
||||
const sourceDelta = !component && (first || remainder || params);
|
||||
const actionRules = event.action === 'bolder' && count > 1
|
||||
? [
|
||||
'For /bolder, keep variant 1 low-risk: preserve the selected root’s high-level layout and create impact through controlled hierarchy, proportion, or rhythm. Reserve root recomposition for variant 2 or 3.',
|
||||
'At least one later direction must recompose the selected root or materially change the spatial relationship among its children. The set must not merely restyle the same descendant three ways.',
|
||||
'Color alone is not a sufficient primary axis for /bolder; pair any palette shift with a meaningful hierarchy, proportion, rhythm, or composition change.',
|
||||
'Every /bolder direction must be visibly more assertive than the original, including compact or dense directions. Do not shrink the focal title or trade away command fidelity merely to increase density.',
|
||||
]
|
||||
: [];
|
||||
const phaseRules = first
|
||||
? [
|
||||
'Produce only variant 1 now so it can be reviewed immediately.',
|
||||
'Variant 1 must be the strongest low-risk, independently shippable interpretation of the request; reserve more experimental directions for later variants.',
|
||||
`Before authoring, define the shared identity lock and exactly ${count} distinct, meaningful design axes. Return them in plan.directions ordered by variantId so the final phase can complete the same coherent set.`,
|
||||
'Defer tunable parameters: params must be absent or empty for this phase.',
|
||||
]
|
||||
: remainder
|
||||
? [
|
||||
`Produce variants 2 through ${count} and the final tunable parameters together so the complete set becomes reviewable in one publication.`,
|
||||
'Variant 1 is already visible and immutable. Do not return or alter its markup or CSS.',
|
||||
'Follow the durable variant plan below and implement every remaining direction as an independently shippable option.',
|
||||
'Return the parameter manifest and wiring CSS for all variants, including immutable variant 1. Parameters may only expose meaningful axes already present in the designs and must not change any default appearance.',
|
||||
'Parameter schema examples: range = {"id":"scale","kind":"range","label":"Scale","min":0.8,"max":1.2,"step":0.1,"default":1}; steps = {"id":"density","kind":"steps","label":"Density","options":[{"value":"compact","label":"Compact"},{"value":"roomy","label":"Roomy"}]}; toggle = {"id":"accent","kind":"toggle","label":"Accent","default":false}.',
|
||||
'Range wiring sets --p-<id>. Steps and toggles use data-p-<id> on the variant wrapper. Return an empty array for a variant only when no meaningful coarse axis exists.',
|
||||
]
|
||||
: params
|
||||
? [
|
||||
`All ${count} variants are already reviewable and immutable. Return only their parameter manifest and parameter wiring CSS.`,
|
||||
'Do not return markup or restyle any default appearance. Parameters may only expose meaningful axes already present in the designs.',
|
||||
'The staged artifact and schema below are complete. Do not call tools or inspect the repository during this phase.',
|
||||
'Parameter schema examples: range = {"id":"scale","kind":"range","label":"Scale","min":0.8,"max":1.2,"step":0.1,"default":1}; steps = {"id":"density","kind":"steps","label":"Density","options":[{"value":"compact","label":"Compact"},{"value":"roomy","label":"Roomy"}]}; toggle = {"id":"accent","kind":"toggle","label":"Accent","default":false}.',
|
||||
'Range wiring sets --p-<id>. Steps and toggles use data-p-<id> on the variant wrapper. Return an empty array for a variant only when no meaningful coarse axis exists.',
|
||||
]
|
||||
: [
|
||||
`Produce the complete set of ${count} variants and final parameters atomically.`,
|
||||
`Before authoring, define the shared identity lock and exactly ${count} distinct, meaningful design axes and return them in plan.directions ordered by variantId.`,
|
||||
];
|
||||
const contextBlocks = [];
|
||||
if (product) contextBlocks.push('<product_context>', String(product), '</product_context>');
|
||||
if (design) contextBlocks.push('<design_context>', String(design), '</design_context>');
|
||||
if (actionReference) contextBlocks.push('<action_reference>', String(actionReference), '</action_reference>');
|
||||
if (contextMetadata && Object.keys(contextMetadata).length > 0) {
|
||||
contextBlocks.push('<context_metadata>', JSON.stringify(contextMetadata, null, 2), '</context_metadata>');
|
||||
}
|
||||
|
||||
return [
|
||||
`LIVE GENERATION PHASE: ${phase}`,
|
||||
...phaseRules,
|
||||
...actionRules,
|
||||
sourceDelta
|
||||
? first
|
||||
? 'Return exactly sourceDelta for variant 1 plus the complete variant plan. markup is only the selected root replacement, without an outer data-impeccable wrapper. css is only the complete fenced base CSS for variant 1, following event.scaffold.cssAuthoring.'
|
||||
: remainder
|
||||
? `Return exactly sourceDeltas with one entry for each variant 2 through ${count}, ordered by variantId, plus parameterCss and paramsJson. Each markup value is only the selected root replacement; each css value is the complete fenced base CSS for that variant. parameterCss contains tuning rules for variants 1 through ${count}. paramsJson is a JSON-encoded object with exactly the keys ${Array.from({ length: count }, (_, index) => JSON.stringify(String(index + 1))).join(', ')}, each containing an array of 0-4 range, steps, or toggle parameter specs.`
|
||||
: `Return only parameterCss and paramsJson. parameterCss contains deferred tuning rules for variants 1 through ${count}. paramsJson is a JSON-encoded object with exactly the keys ${Array.from({ length: count }, (_, index) => JSON.stringify(String(index + 1))).join(', ')}, each containing an array of 0-4 range, steps, or toggle parameter specs.`
|
||||
: component
|
||||
? first
|
||||
? `Return only v1.${artifact.componentExtension} relative to componentDir. The supervisor updates manifest.json.`
|
||||
: remainder
|
||||
? `Return exactly v2.${artifact.componentExtension} through v${count}.${artifact.componentExtension} plus params.json relative to componentDir.`
|
||||
: params
|
||||
? 'Return only params.json relative to componentDir, keyed by variant number.'
|
||||
: `Return v1.${artifact.componentExtension} through v${count}.${artifact.componentExtension} plus params.json relative to componentDir.`
|
||||
: `Return exactly one file whose path is ${JSON.stringify(prepared.artifactFile)} and whose content is the complete staged source artifact.`,
|
||||
sourceDelta
|
||||
? `Do not repeat the staged artifact${remainder || params ? ', prior variants' : ''}, style tags, wrapper comments, or any data-impeccable attributes. The supervisor merges and validates this output transactionally.${remainder || params ? ' parameterCss may only wire explicit data-p-* states or --p-* variables; it must not restyle default appearance.' : ''}`
|
||||
: component
|
||||
? 'Never include manifest.json or paths outside componentDir. Never repeat an immutable variant in a later phase.'
|
||||
: 'Keep the existing session wrapper and markers intact. Add only valid variant blocks and preview CSS inside that wrapper.',
|
||||
'',
|
||||
'<event>',
|
||||
JSON.stringify(sanitizeEvent(event), null, 2),
|
||||
'</event>',
|
||||
'<variant_plan>',
|
||||
JSON.stringify(variantPlan || null, null, 2),
|
||||
'</variant_plan>',
|
||||
'',
|
||||
...contextBlocks,
|
||||
'<staged_artifact>',
|
||||
JSON.stringify(artifact, null, 2),
|
||||
'</staged_artifact>',
|
||||
].join('\n');
|
||||
}
|
||||
|
||||
export function buildCodexWorkerTurnInputs({ prompt, skillPath, screenshotPath, cwd = process.cwd() }) {
|
||||
const inputs = [];
|
||||
if (skillPath && fs.existsSync(skillPath)) {
|
||||
inputs.push({ type: 'skill', name: 'impeccable', path: path.resolve(skillPath) });
|
||||
}
|
||||
const screenshot = resolveInside(cwd, screenshotPath);
|
||||
if (screenshot && fs.existsSync(screenshot)) {
|
||||
inputs.push({ type: 'localImage', path: screenshot, detail: 'high' });
|
||||
}
|
||||
inputs.push({ type: 'text', text: String(prompt) });
|
||||
return inputs;
|
||||
}
|
||||
|
||||
export function resolveCodexWorkerSkillPath(scriptsDir) {
|
||||
const candidates = [
|
||||
path.join(scriptsDir, '..', 'SKILL.md'),
|
||||
path.join(scriptsDir, '..', 'SKILL.src.md'),
|
||||
];
|
||||
return candidates.find((candidate) => fs.existsSync(candidate)) || null;
|
||||
}
|
||||
|
||||
export function readPreparedArtifact(prepared, { cwd = process.cwd(), maxBytes = 2_000_000 } = {}) {
|
||||
if (isCodexComponentPreviewMode(prepared.previewMode)) {
|
||||
const componentDir = resolveInside(cwd, prepared.componentDir);
|
||||
const manifestPath = resolveInside(cwd, prepared.artifactFile);
|
||||
if (!componentDir || !manifestPath) throw workerError('artifact_path_outside_project');
|
||||
const manifest = readBounded(manifestPath, maxBytes);
|
||||
const parsed = JSON.parse(manifest);
|
||||
const componentExtension = parsed.componentExtension
|
||||
|| (prepared.previewMode === 'vue-component' ? 'vue' : 'svelte');
|
||||
const files = {};
|
||||
for (const name of fs.readdirSync(componentDir)) {
|
||||
if (!new RegExp(`^(?:v\\d+\\.${escapeRegExp(componentExtension)}|params\\.json)$`).test(name)) continue;
|
||||
files[name] = readBounded(path.join(componentDir, name), maxBytes);
|
||||
}
|
||||
return {
|
||||
previewMode: prepared.previewMode,
|
||||
componentDir: prepared.componentDir,
|
||||
componentExtension,
|
||||
manifest: parsed,
|
||||
files,
|
||||
};
|
||||
}
|
||||
const artifactPath = resolveInside(cwd, prepared.artifactFile);
|
||||
if (!artifactPath) throw workerError('artifact_path_outside_project');
|
||||
return {
|
||||
previewMode: prepared.previewMode || 'source',
|
||||
path: prepared.artifactFile,
|
||||
content: readBounded(artifactPath, maxBytes),
|
||||
};
|
||||
}
|
||||
|
||||
export function applyCodexWorkerOutput({
|
||||
output,
|
||||
prepared,
|
||||
phase,
|
||||
expectedVariants,
|
||||
sessionId,
|
||||
scaffold,
|
||||
cwd = process.cwd(),
|
||||
maxBytes = 2_000_000,
|
||||
}) {
|
||||
const parsed = typeof output === 'string' ? parseWorkerJson(output) : output;
|
||||
const requirePlan = Number(expectedVariants) > 1 && (phase === 'first' || phase === 'atomic');
|
||||
if (requirePlan && !parsed?.plan) throw workerError('worker_output_plan_missing');
|
||||
const plan = parsed?.plan ? normalizeVariantPlan(parsed.plan, expectedVariants) : null;
|
||||
if (!isCodexComponentPreviewMode(prepared.previewMode) && (phase === 'first' || phase === 'remainder' || phase === 'params')) {
|
||||
const artifactPath = resolveInside(cwd, prepared.artifactFile);
|
||||
if (!artifactPath) throw workerError('artifact_path_outside_project');
|
||||
const common = {
|
||||
sessionId,
|
||||
expectedVariants: Number(expectedVariants),
|
||||
styleMode: scaffold?.styleMode || scaffold?.cssAuthoring?.mode || 'scoped',
|
||||
styleTag: scaffold?.styleTag,
|
||||
jsx: scaffold?.commentSyntax?.open === '{/*',
|
||||
};
|
||||
let content = fs.readFileSync(artifactPath, 'utf-8');
|
||||
if (phase === 'first') {
|
||||
content = applyCodexSourceDelta({ ...common, source: content, delta: parsed?.sourceDelta, expectedVariantId: 1 });
|
||||
} else if (phase === 'remainder') {
|
||||
const deltas = Array.isArray(parsed?.sourceDeltas) ? parsed.sourceDeltas : [];
|
||||
const expectedIds = Array.from({ length: Math.max(0, Number(expectedVariants) - 1) }, (_, index) => index + 2);
|
||||
const ids = deltas.map((delta) => Number(delta?.variantId));
|
||||
if (ids.length !== expectedIds.length || ids.some((id, index) => id !== expectedIds[index])) {
|
||||
throw workerError('worker_output_source_delta_variant_invalid');
|
||||
}
|
||||
for (const delta of deltas) {
|
||||
content = applyCodexSourceDelta({ ...common, source: content, delta, expectedVariantId: Number(delta.variantId) });
|
||||
}
|
||||
content = applyCodexSourceParameters({
|
||||
...common,
|
||||
source: content,
|
||||
parameterCss: parsed?.parameterCss,
|
||||
paramsJson: parsed?.paramsJson,
|
||||
});
|
||||
} else {
|
||||
content = applyCodexSourceParameters({
|
||||
...common,
|
||||
source: content,
|
||||
parameterCss: parsed?.parameterCss,
|
||||
paramsJson: parsed?.paramsJson,
|
||||
});
|
||||
}
|
||||
if (Buffer.byteLength(content) > maxBytes) throw workerError('worker_output_too_large');
|
||||
fs.writeFileSync(artifactPath, content, 'utf-8');
|
||||
return { files: [prepared.artifactFile], plan, sourceDelta: true };
|
||||
}
|
||||
if (!Array.isArray(parsed?.files) || parsed.files.length === 0) {
|
||||
throw workerError('worker_output_files_missing');
|
||||
}
|
||||
const seen = new Set();
|
||||
let totalBytes = 0;
|
||||
for (const file of parsed.files) {
|
||||
if (!file || typeof file.path !== 'string' || typeof file.content !== 'string') {
|
||||
throw workerError('worker_output_file_invalid');
|
||||
}
|
||||
if (seen.has(file.path)) throw workerError('worker_output_file_duplicate');
|
||||
seen.add(file.path);
|
||||
totalBytes += Buffer.byteLength(file.content);
|
||||
}
|
||||
if (totalBytes > maxBytes) throw workerError('worker_output_too_large');
|
||||
if (!isCodexComponentPreviewMode(prepared.previewMode)) {
|
||||
if (parsed.files.length !== 1 || parsed.files[0].path !== prepared.artifactFile) {
|
||||
throw workerError('worker_output_source_path_invalid');
|
||||
}
|
||||
const artifactPath = resolveInside(cwd, prepared.artifactFile);
|
||||
if (!artifactPath) throw workerError('artifact_path_outside_project');
|
||||
fs.writeFileSync(artifactPath, parsed.files[0].content, 'utf-8');
|
||||
return { files: [prepared.artifactFile], plan };
|
||||
}
|
||||
|
||||
const componentDir = resolveInside(cwd, prepared.componentDir);
|
||||
const manifestPath = resolveInside(cwd, prepared.artifactFile);
|
||||
if (!componentDir || !manifestPath) throw workerError('artifact_path_outside_project');
|
||||
const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
|
||||
const extension = manifest.componentExtension
|
||||
|| (prepared.previewMode === 'vue-component' ? 'vue' : 'svelte');
|
||||
const variantPattern = new RegExp(`^v(\\d+)\\.${escapeRegExp(extension)}$`);
|
||||
const allowed = new Set();
|
||||
const firstVariant = phase === 'first' ? 1 : phase === 'remainder' ? 2 : phase === 'atomic' ? 1 : null;
|
||||
const lastVariant = phase === 'first' ? 1 : phase === 'remainder' || phase === 'atomic' ? expectedVariants : null;
|
||||
if (firstVariant != null) {
|
||||
for (let variant = firstVariant; variant <= lastVariant; variant += 1) allowed.add(`v${variant}.${extension}`);
|
||||
}
|
||||
if (phase === 'remainder' || phase === 'params' || phase === 'atomic') allowed.add('params.json');
|
||||
|
||||
for (const file of parsed.files) {
|
||||
if (!allowed.has(file.path)) {
|
||||
const attemptedVariant = Number(variantPattern.exec(file.path)?.[1] || 0);
|
||||
if (phase === 'remainder' && attemptedVariant > 0 && attemptedVariant < firstVariant) {
|
||||
throw workerError('published_variant_changed');
|
||||
}
|
||||
throw workerError('worker_output_component_path_invalid');
|
||||
}
|
||||
const target = resolveInside(componentDir, file.path);
|
||||
if (!target || path.dirname(target) !== componentDir) {
|
||||
throw workerError('worker_output_component_path_invalid');
|
||||
}
|
||||
fs.writeFileSync(target, file.content, 'utf-8');
|
||||
}
|
||||
for (const required of allowed) {
|
||||
if (!seen.has(required)) {
|
||||
throw workerError('worker_output_component_file_missing', { file: required });
|
||||
}
|
||||
}
|
||||
manifest.arrivedVariants = phase === 'first' ? 1 : expectedVariants;
|
||||
fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
|
||||
return { files: [...seen], plan };
|
||||
}
|
||||
|
||||
export function applyCodexSourceDelta({
|
||||
source,
|
||||
delta,
|
||||
sessionId,
|
||||
expectedVariantId = 2,
|
||||
expectedVariants = 3,
|
||||
styleMode = 'scoped',
|
||||
styleTag = null,
|
||||
jsx = false,
|
||||
parameterCss = null,
|
||||
paramsJson = null,
|
||||
}) {
|
||||
if (!delta || typeof delta !== 'object' || Array.isArray(delta)) {
|
||||
throw workerError('worker_output_source_delta_missing');
|
||||
}
|
||||
const variantId = Number(expectedVariantId);
|
||||
const variantCount = Number(expectedVariants);
|
||||
if (!Number.isInteger(variantId) || variantId < 1 || variantId > variantCount
|
||||
|| Number(delta.variantId) !== variantId) {
|
||||
throw workerError('worker_output_source_delta_variant_invalid');
|
||||
}
|
||||
const markup = String(delta.markup || '').trim();
|
||||
const css = String(delta.css || '').trim();
|
||||
if (!markup || !css) throw workerError('worker_output_source_delta_empty');
|
||||
if (/data-impeccable-(?:variant|variants|css)|impeccable-variants-(?:start|end)/i.test(markup)) {
|
||||
throw workerError('worker_output_source_delta_wrapper_forbidden');
|
||||
}
|
||||
if (/<\/?style\b|`|\$\{/i.test(css)) {
|
||||
throw workerError('worker_output_source_delta_css_unsafe');
|
||||
}
|
||||
validateSourceDeltaCss(css, { variantIds: [variantId], styleMode, requireVariantId: variantId });
|
||||
const normalizedParameterCss = String(parameterCss || '').trim();
|
||||
const params = paramsJson == null ? null : normalizeSourceParams(paramsJson, variantCount);
|
||||
if (params) {
|
||||
if (normalizedParameterCss) {
|
||||
if (/<\/?style\b|`|\$\{/i.test(normalizedParameterCss)) {
|
||||
throw workerError('worker_output_source_delta_css_unsafe');
|
||||
}
|
||||
validateSourceDeltaCss(normalizedParameterCss, {
|
||||
variantIds: Array.from({ length: variantCount }, (_, index) => index + 1),
|
||||
styleMode,
|
||||
});
|
||||
}
|
||||
} else if (parameterCss != null || paramsJson != null) {
|
||||
throw workerError('worker_output_source_delta_params_invalid');
|
||||
}
|
||||
|
||||
const id = String(sessionId || '');
|
||||
if (!id) throw workerError('worker_output_source_delta_session_missing');
|
||||
const wrapper = findSessionWrapper(source, id);
|
||||
if (!wrapper) throw workerError('worker_output_source_delta_wrapper_missing');
|
||||
const wrapperSource = source.slice(wrapper.openStart, wrapper.closeEnd);
|
||||
if (extractSourceVariantBlock(wrapperSource, variantId)) throw workerError('worker_output_source_delta_variant_exists');
|
||||
|
||||
const escapedId = escapeRegExp(id);
|
||||
const styleOpen = new RegExp(`<style\\b[^>]*\\bdata-impeccable-css=(?:"${escapedId}"|'${escapedId}')[^>]*>`, 'i');
|
||||
const styleMatch = styleOpen.exec(source);
|
||||
let merged = source;
|
||||
let newStyleBlock = null;
|
||||
if (styleMatch) {
|
||||
const styleContentStart = styleMatch.index + styleMatch[0].length;
|
||||
const styleClose = source.indexOf('</style>', styleContentStart);
|
||||
if (styleClose < 0 || styleClose > wrapper.closeEnd) {
|
||||
throw workerError('worker_output_source_delta_style_invalid');
|
||||
}
|
||||
const styleContent = source.slice(styleContentStart, styleClose);
|
||||
let nextStyleContent;
|
||||
const firstTick = styleContent.indexOf('`');
|
||||
const lastTick = styleContent.lastIndexOf('`');
|
||||
if (firstTick >= 0 || lastTick >= 0) {
|
||||
if (firstTick < 0 || lastTick <= firstTick) {
|
||||
throw workerError('worker_output_source_delta_style_invalid');
|
||||
}
|
||||
nextStyleContent = styleContent.slice(0, lastTick).trimEnd()
|
||||
+ '\n' + [css, normalizedParameterCss].filter(Boolean).join('\n') + '\n'
|
||||
+ styleContent.slice(lastTick);
|
||||
} else {
|
||||
nextStyleContent = styleContent.trimEnd()
|
||||
+ '\n' + [css, normalizedParameterCss].filter(Boolean).join('\n') + '\n';
|
||||
}
|
||||
merged = source.slice(0, styleContentStart) + nextStyleContent + source.slice(styleClose);
|
||||
} else {
|
||||
if (variantId !== 1) throw workerError('worker_output_source_delta_style_missing');
|
||||
const openingTag = String(styleTag || `<style data-impeccable-css="${id}">`)
|
||||
.replaceAll('SESSION_ID', id);
|
||||
newStyleBlock = jsx
|
||||
? [openingTag + '{`', css, '`}</style>'].join('\n')
|
||||
: [openingTag, css, '</style>'].join('\n');
|
||||
}
|
||||
|
||||
const nextWrapper = findSessionWrapper(merged, id);
|
||||
if (!nextWrapper) throw workerError('worker_output_source_delta_wrapper_missing');
|
||||
const endMarker = findSessionEndMarker(merged, id, nextWrapper);
|
||||
const closeLineStart = merged.lastIndexOf('\n', nextWrapper.closeStart) + 1;
|
||||
const closeLinePrefix = merged.slice(closeLineStart, nextWrapper.closeStart);
|
||||
const childIndent = endMarker?.indent || nextWrapper.indent + ' ';
|
||||
const contentIndent = childIndent + ' ';
|
||||
const indentedMarkup = markup.split('\n')
|
||||
.map((line) => line.trim() ? contentIndent + line : '')
|
||||
.join('\n');
|
||||
const variantBlock = [
|
||||
...(newStyleBlock
|
||||
? newStyleBlock.split('\n').map((line) => childIndent + line)
|
||||
: []),
|
||||
`${childIndent}<div data-impeccable-variant="${variantId}">`,
|
||||
indentedMarkup,
|
||||
`${childIndent}</div>`,
|
||||
].join('\n');
|
||||
if (endMarker) {
|
||||
merged = merged.slice(0, endMarker.lineStart) + variantBlock + '\n' + merged.slice(endMarker.lineStart);
|
||||
} else if (/^\s*$/.test(closeLinePrefix)) {
|
||||
merged = merged.slice(0, closeLineStart) + variantBlock + '\n' + merged.slice(closeLineStart);
|
||||
} else {
|
||||
merged = merged.slice(0, nextWrapper.closeStart)
|
||||
+ '\n' + variantBlock + '\n' + nextWrapper.indent
|
||||
+ merged.slice(nextWrapper.closeStart);
|
||||
}
|
||||
if (params) merged = applySourceParams(merged, id, params, variantCount);
|
||||
return merged;
|
||||
}
|
||||
|
||||
export function applyCodexSourceParameters({
|
||||
source,
|
||||
sessionId,
|
||||
expectedVariants = 3,
|
||||
styleMode = 'scoped',
|
||||
parameterCss = '',
|
||||
paramsJson,
|
||||
}) {
|
||||
const variantCount = Number(expectedVariants);
|
||||
const params = normalizeSourceParams(paramsJson, variantCount);
|
||||
const css = String(parameterCss || '').trim();
|
||||
if (/<\/?style\b|`|\$\{/i.test(css)) {
|
||||
throw workerError('worker_output_source_delta_css_unsafe');
|
||||
}
|
||||
if (css) {
|
||||
validateSourceDeltaCss(css, {
|
||||
variantIds: Array.from({ length: variantCount }, (_, index) => index + 1),
|
||||
styleMode,
|
||||
});
|
||||
}
|
||||
|
||||
const id = String(sessionId || '');
|
||||
if (!id) throw workerError('worker_output_source_delta_session_missing');
|
||||
let merged = String(source || '');
|
||||
if (css) {
|
||||
const escapedId = escapeRegExp(id);
|
||||
const styleOpen = new RegExp(`<style\\b[^>]*\\bdata-impeccable-css=(?:"${escapedId}"|'${escapedId}')[^>]*>`, 'i');
|
||||
const styleMatch = styleOpen.exec(merged);
|
||||
if (!styleMatch) throw workerError('worker_output_source_delta_style_missing');
|
||||
const contentStart = styleMatch.index + styleMatch[0].length;
|
||||
const styleClose = merged.indexOf('</style>', contentStart);
|
||||
if (styleClose < 0) throw workerError('worker_output_source_delta_style_invalid');
|
||||
const styleContent = merged.slice(contentStart, styleClose);
|
||||
const lastTick = styleContent.lastIndexOf('`');
|
||||
const nextStyleContent = lastTick >= 0
|
||||
? styleContent.slice(0, lastTick).trimEnd() + '\n' + css + '\n' + styleContent.slice(lastTick)
|
||||
: styleContent.trimEnd() + '\n' + css + '\n';
|
||||
merged = merged.slice(0, contentStart) + nextStyleContent + merged.slice(styleClose);
|
||||
}
|
||||
return applySourceParams(merged, id, params, variantCount);
|
||||
}
|
||||
|
||||
function validateSourceDeltaCss(css, { variantIds, styleMode, requireVariantId = null }) {
|
||||
const allowed = new Set(variantIds.map(String));
|
||||
const refs = [...String(css).matchAll(/\[data-impeccable-variant=(?:"([^"]+)"|'([^']+)')\]/g)]
|
||||
.map((match) => match[1] || match[2]);
|
||||
if ((requireVariantId != null && !refs.includes(String(requireVariantId)))
|
||||
|| refs.some((variant) => !allowed.has(variant))) {
|
||||
throw workerError('worker_output_source_delta_css_unfenced');
|
||||
}
|
||||
if (!String(css).trim()) return;
|
||||
const astroGlobal = styleMode === 'astro-global-prefixed';
|
||||
if (astroGlobal ? /@scope\b/.test(css) : !/@scope\s*\(/.test(css)) {
|
||||
throw workerError('worker_output_source_delta_css_strategy_invalid');
|
||||
}
|
||||
}
|
||||
|
||||
function normalizeSourceParams(paramsJson, expectedVariants) {
|
||||
if (!Number.isInteger(expectedVariants) || expectedVariants < 1
|
||||
|| Buffer.byteLength(String(paramsJson)) > 20_000) {
|
||||
throw workerError('worker_output_source_delta_params_invalid');
|
||||
}
|
||||
let parsed;
|
||||
try {
|
||||
parsed = JSON.parse(String(paramsJson));
|
||||
} catch {
|
||||
throw workerError('worker_output_source_delta_params_invalid');
|
||||
}
|
||||
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
|
||||
throw workerError('worker_output_source_delta_params_invalid');
|
||||
}
|
||||
const expectedKeys = Array.from({ length: expectedVariants }, (_, index) => String(index + 1));
|
||||
if (Object.keys(parsed).sort().join(',') !== expectedKeys.join(',')) {
|
||||
throw workerError('worker_output_source_delta_params_invalid');
|
||||
}
|
||||
for (const key of expectedKeys) {
|
||||
if (!Array.isArray(parsed[key]) || parsed[key].length > 4) {
|
||||
throw workerError('worker_output_source_delta_params_invalid');
|
||||
}
|
||||
const ids = new Set();
|
||||
for (const spec of parsed[key]) {
|
||||
const id = String(spec?.id || '');
|
||||
const kind = String(spec?.kind || '');
|
||||
if (!/^[a-z][a-z0-9-]{0,31}$/.test(id) || ids.has(id)
|
||||
|| !['range', 'steps', 'toggle'].includes(kind)
|
||||
|| typeof spec?.label !== 'string' || !spec.label.trim()) {
|
||||
throw workerError('worker_output_source_delta_params_invalid');
|
||||
}
|
||||
ids.add(id);
|
||||
if (kind === 'range'
|
||||
&& !['min', 'max', 'step', 'default'].every((field) => Number.isFinite(spec[field]))) {
|
||||
throw workerError('worker_output_source_delta_params_invalid');
|
||||
}
|
||||
if (kind === 'steps' && (!Array.isArray(spec.options) || spec.options.length < 2
|
||||
|| spec.options.some((option) => (
|
||||
typeof option?.value !== 'string' || typeof option?.label !== 'string'
|
||||
)))) {
|
||||
throw workerError('worker_output_source_delta_params_invalid');
|
||||
}
|
||||
if (kind === 'toggle' && typeof spec.default !== 'boolean') {
|
||||
throw workerError('worker_output_source_delta_params_invalid');
|
||||
}
|
||||
}
|
||||
}
|
||||
return parsed;
|
||||
}
|
||||
|
||||
function applySourceParams(source, sessionId, params, expectedVariants) {
|
||||
const wrapper = findSessionWrapper(source, sessionId);
|
||||
if (!wrapper) throw workerError('worker_output_source_delta_wrapper_missing');
|
||||
let body = source.slice(wrapper.openStart, wrapper.closeEnd);
|
||||
for (let variant = 1; variant <= expectedVariants; variant += 1) {
|
||||
const attr = escapeRegExp(String(variant));
|
||||
const open = new RegExp(`<div\\b[^>]*\\bdata-impeccable-variant=(?:"${attr}"|'${attr}')[^>]*>`, 'i');
|
||||
const match = open.exec(body);
|
||||
if (!match) throw workerError('worker_output_source_delta_variant_missing', { variant });
|
||||
const json = JSON.stringify(params[String(variant)])
|
||||
.replaceAll('&', '&')
|
||||
.replaceAll("'", ''');
|
||||
const nextOpen = match[0]
|
||||
.replace(/\sdata-impeccable-params=(?:"[^"]*"|'[^']*')/i, '')
|
||||
.replace(/>$/, ` data-impeccable-params='${json}'>`);
|
||||
body = body.slice(0, match.index) + nextOpen + body.slice(match.index + match[0].length);
|
||||
}
|
||||
return source.slice(0, wrapper.openStart) + body + source.slice(wrapper.closeEnd);
|
||||
}
|
||||
|
||||
function findSessionEndMarker(source, sessionId, wrapper) {
|
||||
const marker = `impeccable-variants-end ${sessionId}`;
|
||||
const markerAt = source.indexOf(marker, wrapper.openStart);
|
||||
if (markerAt < 0 || markerAt >= wrapper.closeStart) return null;
|
||||
const lineStart = source.lastIndexOf('\n', markerAt) + 1;
|
||||
const indent = source.slice(lineStart, markerAt).match(/^\s*/)?.[0] || '';
|
||||
return { lineStart, indent };
|
||||
}
|
||||
|
||||
function normalizeVariantPlan(plan, expectedVariants) {
|
||||
if (!plan || typeof plan !== 'object' || Array.isArray(plan)) {
|
||||
throw workerError('worker_output_plan_invalid');
|
||||
}
|
||||
const identityLock = Array.isArray(plan.identityLock)
|
||||
? plan.identityLock.map((item) => String(item || '').trim()).filter(Boolean)
|
||||
: [];
|
||||
const directions = Array.isArray(plan.directions) ? plan.directions : [];
|
||||
if (identityLock.length < 1 || identityLock.length > 8 || directions.length !== Number(expectedVariants)) {
|
||||
throw workerError('worker_output_plan_invalid');
|
||||
}
|
||||
const normalizedDirections = directions.map((direction) => ({
|
||||
variantId: Number(direction?.variantId),
|
||||
name: String(direction?.name || '').trim(),
|
||||
axis: String(direction?.axis || '').trim(),
|
||||
intent: String(direction?.intent || '').trim(),
|
||||
}));
|
||||
const expectedIds = Array.from({ length: Number(expectedVariants) }, (_, index) => index + 1);
|
||||
const sortedIds = normalizedDirections.map((direction) => direction.variantId).sort((a, b) => a - b);
|
||||
if (normalizedDirections.some((direction) => (
|
||||
!Number.isInteger(direction.variantId)
|
||||
|| !direction.name
|
||||
|| !direction.axis
|
||||
|| !direction.intent
|
||||
)) || sortedIds.some((id, index) => id !== expectedIds[index])) {
|
||||
throw workerError('worker_output_plan_invalid');
|
||||
}
|
||||
return { identityLock, directions: normalizedDirections };
|
||||
}
|
||||
|
||||
export function prepareCodexWorkerPhase({ id, sourceFile, cwd = process.cwd() }) {
|
||||
const prepared = prepareGenerationArtifact({ id, sourceFile, cwd });
|
||||
if (!prepared.ok) throw workerError(`prepare_${prepared.error}`, prepared);
|
||||
return prepared;
|
||||
}
|
||||
|
||||
export function publishCodexWorkerPhase({
|
||||
event,
|
||||
prepared,
|
||||
arrivedVariants,
|
||||
phase,
|
||||
cwd = process.cwd(),
|
||||
}) {
|
||||
const published = publishGenerationArtifact({
|
||||
id: event.id,
|
||||
epoch: prepared.epoch,
|
||||
sourceFile: event.scaffold.file,
|
||||
artifactFile: prepared.artifactFile,
|
||||
expectedSourceHash: prepared.expectedSourceHash,
|
||||
arrivedVariants,
|
||||
expectedVariants: Number(event.count || arrivedVariants),
|
||||
publicationKind: ['remainder', 'params', 'atomic'].includes(phase) ? 'params' : 'variants',
|
||||
cwd,
|
||||
});
|
||||
if (!published.ok) throw workerError(`publish_${published.error}`, published);
|
||||
return published;
|
||||
}
|
||||
|
||||
export function generationIsCanceled(eventId, { cwd = process.cwd() } = {}) {
|
||||
const snapshot = createLiveSessionStore({ cwd, sessionId: eventId }).getSnapshot(eventId, { includeCompleted: true });
|
||||
return snapshot?.generationCanceled === true;
|
||||
}
|
||||
|
||||
export function codexWorkerStateIsOwned(state, cwd) {
|
||||
return codexWorkerOwnerMatches(state, cwd)
|
||||
&& typeof state?.threadId === 'string'
|
||||
&& state.threadId.length > 0;
|
||||
}
|
||||
|
||||
export function isCodexComponentPreviewMode(value) {
|
||||
return value === 'svelte-component' || value === 'vue-component';
|
||||
}
|
||||
|
||||
export function codexWorkerProcessStateIsOwned(state, cwd) {
|
||||
return codexWorkerOwnerMatches(state, cwd)
|
||||
&& Number.isInteger(state?.pid)
|
||||
&& state.pid > 0;
|
||||
}
|
||||
|
||||
function codexWorkerOwnerMatches(state, cwd) {
|
||||
return state?.owner === CODEX_WORKER_OWNER
|
||||
&& canonicalPath(state?.cwd) === canonicalPath(cwd);
|
||||
}
|
||||
|
||||
function canonicalPath(value) {
|
||||
if (!value || typeof value !== 'string') return null;
|
||||
const resolved = path.resolve(value);
|
||||
try { return fs.realpathSync.native(resolved); } catch { return resolved; }
|
||||
}
|
||||
|
||||
function sanitizeEvent(event) {
|
||||
const copy = { ...event };
|
||||
delete copy.agentAction;
|
||||
delete copy._acceptResult;
|
||||
delete copy._completionAck;
|
||||
return copy;
|
||||
}
|
||||
|
||||
function findSessionWrapper(source, sessionId) {
|
||||
const escapedId = escapeRegExp(sessionId);
|
||||
const open = new RegExp(`<div\\b[^>]*\\bdata-impeccable-variants=(?:"${escapedId}"|'${escapedId}')[^>]*>`, 'i');
|
||||
const wrapperOpen = open.exec(source);
|
||||
if (!wrapperOpen) return null;
|
||||
const token = /<div\b[^>]*\/\s*>|<div\b[^>]*>|<\/div\s*>/gi;
|
||||
token.lastIndex = wrapperOpen.index;
|
||||
let depth = 0;
|
||||
let match;
|
||||
while ((match = token.exec(source))) {
|
||||
if (/^<\/div/i.test(match[0])) {
|
||||
depth -= 1;
|
||||
if (depth === 0) {
|
||||
const lineStart = source.lastIndexOf('\n', wrapperOpen.index) + 1;
|
||||
const indent = source.slice(lineStart, wrapperOpen.index).match(/^\s*/)?.[0] || '';
|
||||
return {
|
||||
openStart: wrapperOpen.index,
|
||||
closeStart: match.index,
|
||||
closeEnd: token.lastIndex,
|
||||
indent,
|
||||
};
|
||||
}
|
||||
} else if (!/\/\s*>$/.test(match[0])) {
|
||||
depth += 1;
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function extractSourceVariantBlock(source, variantId) {
|
||||
const attr = escapeRegExp(String(variantId));
|
||||
return new RegExp(`<div\\b[^>]*\\bdata-impeccable-variant=(?:"${attr}"|'${attr}')[^>]*>`, 'i').test(source);
|
||||
}
|
||||
|
||||
function parseWorkerJson(value) {
|
||||
const text = String(value || '').trim().replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/, '');
|
||||
try {
|
||||
return JSON.parse(text);
|
||||
} catch (error) {
|
||||
throw workerError('worker_output_json_invalid', { message: error.message });
|
||||
}
|
||||
}
|
||||
|
||||
function parseBoolean(value) {
|
||||
if (value == null || value === '') return null;
|
||||
if (/^(?:1|true|yes|on)$/i.test(String(value))) return true;
|
||||
if (/^(?:0|false|no|off)$/i.test(String(value))) return false;
|
||||
return null;
|
||||
}
|
||||
|
||||
function nonEmpty(value) {
|
||||
return typeof value === 'string' && value.trim() ? value.trim() : null;
|
||||
}
|
||||
|
||||
function positiveInteger(value, fallback) {
|
||||
const parsed = Number(value);
|
||||
return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
|
||||
}
|
||||
|
||||
function resolveInside(root, value) {
|
||||
if (!value || typeof value !== 'string') return null;
|
||||
const resolvedRoot = path.resolve(root);
|
||||
const resolved = path.resolve(resolvedRoot, value);
|
||||
const relative = path.relative(resolvedRoot, resolved);
|
||||
if (!relative || (!relative.startsWith('..') && !path.isAbsolute(relative))) return resolved;
|
||||
return null;
|
||||
}
|
||||
|
||||
function readBounded(file, maxBytes) {
|
||||
const stat = fs.statSync(file);
|
||||
if (stat.size > maxBytes) throw workerError('artifact_too_large', { bytes: stat.size });
|
||||
return fs.readFileSync(file, 'utf-8');
|
||||
}
|
||||
|
||||
function workerError(code, detail = {}) {
|
||||
const error = new Error(code);
|
||||
error.code = code;
|
||||
Object.assign(error, detail);
|
||||
return error;
|
||||
}
|
||||
|
||||
function escapeRegExp(value) {
|
||||
return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
||||
}
|
||||
@@ -118,6 +118,15 @@ export function validateEvent(msg) {
|
||||
return 'checkpoint: paramValues must be an object';
|
||||
}
|
||||
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 (msg.durationMs !== undefined && (!Number.isFinite(msg.durationMs) || msg.durationMs < 0)) {
|
||||
return 'agent_phase: durationMs must be a non-negative number';
|
||||
}
|
||||
return null;
|
||||
case 'exit':
|
||||
return null;
|
||||
case 'prefetch':
|
||||
@@ -131,6 +140,12 @@ export function validateEvent(msg) {
|
||||
if (msg.message.length > 4000) return 'steer: message too long';
|
||||
if (msg.pageUrl !== undefined && typeof msg.pageUrl !== 'string') return 'steer: pageUrl must be string';
|
||||
return null;
|
||||
case 'carbonize_cleanup':
|
||||
if (!isValidId(msg.id)) return 'carbonize_cleanup: missing or malformed id';
|
||||
if (!isValidId(msg.sessionId)) return 'carbonize_cleanup: missing or malformed sessionId';
|
||||
if (!msg.file || typeof msg.file !== 'string') return 'carbonize_cleanup: missing file';
|
||||
if (!isValidVariantId(String(msg.variantId))) return 'carbonize_cleanup: missing or malformed variantId';
|
||||
return null;
|
||||
default:
|
||||
return 'Unknown event type: ' + msg.type;
|
||||
}
|
||||
|
||||
@@ -0,0 +1,93 @@
|
||||
import { execFileSync } from 'node:child_process';
|
||||
import path from 'node:path';
|
||||
|
||||
const PREFLIGHT_TIMEOUT_MS = 15_000;
|
||||
|
||||
export function buildGenerationPreflight(event, scriptsDir, { isolated = false } = {}) {
|
||||
if (!event || event.type !== 'generate' || !event.id) return null;
|
||||
|
||||
const isInsert = event.mode === 'insert';
|
||||
const target = isInsert ? insertTarget(event) : replaceTarget(event);
|
||||
if (!target.elementId && !target.classes) return null;
|
||||
|
||||
const script = path.join(scriptsDir, isInsert ? 'live-insert.mjs' : 'live-wrap.mjs');
|
||||
const args = [script, '--id', event.id, '--count', String(event.count || 3)];
|
||||
if (!isInsert && isolated) args.push('--isolated');
|
||||
if (isInsert) args.push('--position', target.position);
|
||||
if (target.elementId) args.push('--element-id', target.elementId);
|
||||
if (target.classes) args.push('--classes', target.classes);
|
||||
if (target.tag) args.push('--tag', target.tag);
|
||||
if (target.text) args.push('--text', target.text);
|
||||
if (!isInsert && event.pageUrl) args.push('--page-url', event.pageUrl);
|
||||
return { script, args, mode: isInsert ? 'insert' : 'replace' };
|
||||
}
|
||||
|
||||
export function runGenerationPreflight(event, {
|
||||
cwd = process.cwd(),
|
||||
scriptsDir,
|
||||
execFileSyncImpl = execFileSync,
|
||||
timeoutMs = PREFLIGHT_TIMEOUT_MS,
|
||||
isolated = false,
|
||||
} = {}) {
|
||||
const command = buildGenerationPreflight(event, scriptsDir, { isolated });
|
||||
if (!command) {
|
||||
return { ok: false, skipped: true, reason: 'insufficient_locator' };
|
||||
}
|
||||
|
||||
const startedAt = performance.now();
|
||||
try {
|
||||
const stdout = execFileSyncImpl(process.execPath, command.args, {
|
||||
cwd,
|
||||
encoding: 'utf-8',
|
||||
timeout: timeoutMs,
|
||||
stdio: ['ignore', 'pipe', 'pipe'],
|
||||
});
|
||||
const line = String(stdout).trim().split('\n').filter(Boolean).pop();
|
||||
if (!line) throw new Error('preflight returned no scaffold metadata');
|
||||
return {
|
||||
ok: true,
|
||||
mode: command.mode,
|
||||
durationMs: performance.now() - startedAt,
|
||||
scaffold: JSON.parse(line),
|
||||
};
|
||||
} catch (error) {
|
||||
return {
|
||||
ok: false,
|
||||
mode: command.mode,
|
||||
durationMs: performance.now() - startedAt,
|
||||
error: compactError(error),
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
function replaceTarget(event) {
|
||||
return normalizeTarget(event.element || {});
|
||||
}
|
||||
|
||||
function insertTarget(event) {
|
||||
return {
|
||||
...normalizeTarget(event.insert?.anchor || {}),
|
||||
position: event.insert?.position === 'before' ? 'before' : 'after',
|
||||
};
|
||||
}
|
||||
|
||||
function normalizeTarget(target) {
|
||||
const classes = Array.isArray(target.classes)
|
||||
? target.classes.join(' ')
|
||||
: String(target.classes || '').trim();
|
||||
const text = typeof target.textContent === 'string'
|
||||
? target.textContent.trim().slice(0, 80)
|
||||
: '';
|
||||
return {
|
||||
elementId: target.id || target.elementId || undefined,
|
||||
classes: classes || undefined,
|
||||
tag: target.tagName || target.tag || undefined,
|
||||
text: text || undefined,
|
||||
};
|
||||
}
|
||||
|
||||
function compactError(error) {
|
||||
const stderr = error?.stderr ? String(error.stderr).trim() : '';
|
||||
const message = stderr.split('\n').filter(Boolean).pop() || error?.message || 'preflight failed';
|
||||
return String(message).slice(0, 500);
|
||||
}
|
||||
@@ -0,0 +1,617 @@
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { createHash } from 'node:crypto';
|
||||
import { createLiveSessionStore } from './session-store.mjs';
|
||||
import { withSourceLockSync } from './source-lock.mjs';
|
||||
import { getLiveDir } from '../lib/impeccable-paths.mjs';
|
||||
import {
|
||||
SOURCE_ARTIFACT_PREVIEW_MODE,
|
||||
findSourceArtifactManifest,
|
||||
} from './source-artifact.mjs';
|
||||
|
||||
export function sha256(value) {
|
||||
return createHash('sha256').update(value).digest('hex');
|
||||
}
|
||||
|
||||
export function reconcilePublishedSourceVariants({ current, candidate, priorArrived = 0 } = {}) {
|
||||
let reconciled = String(candidate || '');
|
||||
const stable = String(current || '');
|
||||
for (let variant = 1; variant <= Number(priorArrived || 0); variant += 1) {
|
||||
const stableBlock = extractVariantBlock(stable, variant);
|
||||
const candidateBlock = extractVariantBlock(reconciled, variant);
|
||||
if (!stableBlock || !candidateBlock) {
|
||||
return failure('published_variant_missing', { variant });
|
||||
}
|
||||
const offset = reconciled.indexOf(candidateBlock);
|
||||
reconciled = reconciled.slice(0, offset) + stableBlock + reconciled.slice(offset + candidateBlock.length);
|
||||
}
|
||||
return { ok: true, content: reconciled };
|
||||
}
|
||||
|
||||
export function prepareGenerationArtifact({ id, sourceFile, cwd = process.cwd() } = {}) {
|
||||
if (!id) return failure('missing_session_id');
|
||||
if (!sourceFile) return failure('missing_file');
|
||||
const requestedPath = resolveInside(cwd, sourceFile);
|
||||
if (!requestedPath || !fs.existsSync(requestedPath)) return failure(requestedPath ? 'source_missing' : 'path_outside_project');
|
||||
|
||||
const componentTarget = readComponentPublicationTarget(requestedPath, cwd, id);
|
||||
if (componentTarget?.error) return componentTarget;
|
||||
const sourceArtifactTarget = componentTarget ? null : readSourceArtifactPublicationTarget(requestedPath, cwd, id);
|
||||
if (sourceArtifactTarget?.error) return sourceArtifactTarget;
|
||||
const sourcePath = componentTarget?.sourcePath || sourceArtifactTarget?.sourcePath || requestedPath;
|
||||
|
||||
try {
|
||||
return withSourceLockSync(sourcePath, 'generation-prepare:' + id, () => {
|
||||
const store = createLiveSessionStore({ cwd, sessionId: id });
|
||||
const snapshot = store.getSnapshot(id, { includeCompleted: true });
|
||||
if (!snapshot?.updatedAt) return failure('session_missing');
|
||||
if (snapshot.generationCanceled === true) {
|
||||
return failure('stale_generation_epoch', { canceled: true, phase: snapshot.phase });
|
||||
}
|
||||
const source = fs.readFileSync(sourcePath, 'utf-8');
|
||||
const artifactBase = sourceArtifactTarget
|
||||
? fs.readFileSync(sourceArtifactTarget.previewPath, 'utf-8')
|
||||
: source;
|
||||
const revision = Number(snapshot.publishedRevision || 0) + 1;
|
||||
const artifactDir = path.join(getLiveDir(cwd), 'artifacts');
|
||||
if (componentTarget) {
|
||||
return prepareComponentArtifact({
|
||||
id,
|
||||
revision,
|
||||
snapshot,
|
||||
source,
|
||||
sourcePath,
|
||||
requestedPath,
|
||||
target: componentTarget,
|
||||
artifactDir,
|
||||
cwd,
|
||||
});
|
||||
}
|
||||
const extension = path.extname(sourcePath) || '.html';
|
||||
const artifactPath = path.join(artifactDir, id + '-r' + revision + extension);
|
||||
fs.mkdirSync(artifactDir, { recursive: true });
|
||||
fs.writeFileSync(artifactPath, artifactBase, 'utf-8');
|
||||
return {
|
||||
ok: true,
|
||||
id,
|
||||
epoch: Number(snapshot.generationEpoch || 1),
|
||||
revision,
|
||||
sourceFile: relative(cwd, sourcePath),
|
||||
...(sourceArtifactTarget ? {
|
||||
previewFile: relative(cwd, sourceArtifactTarget.previewPath),
|
||||
previewMode: SOURCE_ARTIFACT_PREVIEW_MODE,
|
||||
} : {}),
|
||||
artifactFile: relative(cwd, artifactPath),
|
||||
expectedSourceHash: sha256(source),
|
||||
};
|
||||
}, { cwd });
|
||||
} catch (error) {
|
||||
if (error?.code === 'SOURCE_LOCKED') return failure('source_locked');
|
||||
return failure('prepare_failed', { message: error?.message || String(error) });
|
||||
}
|
||||
}
|
||||
|
||||
export function publishGenerationArtifact({
|
||||
id,
|
||||
epoch,
|
||||
sourceFile,
|
||||
artifactFile,
|
||||
expectedSourceHash,
|
||||
arrivedVariants,
|
||||
expectedVariants,
|
||||
publicationKind,
|
||||
cwd = process.cwd(),
|
||||
} = {}) {
|
||||
if (!id) return failure('missing_session_id');
|
||||
if (!Number.isInteger(epoch) || epoch < 1) return failure('invalid_generation_epoch');
|
||||
if (!sourceFile || !artifactFile) return failure('missing_file');
|
||||
if (publicationKind && !['variants', 'params'].includes(publicationKind)) {
|
||||
return failure('invalid_publication_kind');
|
||||
}
|
||||
|
||||
const requestedPath = resolveInside(cwd, sourceFile);
|
||||
const artifactPath = resolveInside(cwd, artifactFile);
|
||||
if (!requestedPath || !artifactPath) return failure('path_outside_project');
|
||||
if (!fs.existsSync(requestedPath)) return failure('source_missing');
|
||||
if (!fs.existsSync(artifactPath)) return failure('artifact_missing');
|
||||
|
||||
const componentTarget = readComponentPublicationTarget(requestedPath, cwd, id);
|
||||
if (componentTarget?.error) return componentTarget;
|
||||
const sourceArtifactTarget = componentTarget ? null : readSourceArtifactPublicationTarget(requestedPath, cwd, id);
|
||||
if (sourceArtifactTarget?.error) return sourceArtifactTarget;
|
||||
const artifactManifest = readJson(artifactPath);
|
||||
const isComponentArtifact = isComponentPreviewMode(artifactManifest?.previewMode);
|
||||
if (Boolean(componentTarget) !== isComponentArtifact) {
|
||||
return failure('artifact_preview_mode_mismatch');
|
||||
}
|
||||
if (componentTarget && componentTarget.manifest.previewMode !== artifactManifest?.previewMode) {
|
||||
return failure('artifact_preview_mode_mismatch');
|
||||
}
|
||||
const sourcePath = componentTarget?.sourcePath || sourceArtifactTarget?.sourcePath || requestedPath;
|
||||
|
||||
try {
|
||||
return withSourceLockSync(sourcePath, 'generation:' + id + ':' + epoch, () => {
|
||||
const store = createLiveSessionStore({ cwd, sessionId: id });
|
||||
const snapshot = store.getSnapshot(id, { includeCompleted: true });
|
||||
if (!snapshot?.updatedAt) return failure('session_missing');
|
||||
if (snapshot.generationCanceled === true) {
|
||||
return failure('stale_generation_epoch', { canceled: true, phase: snapshot.phase });
|
||||
}
|
||||
if (Number(snapshot.generationEpoch || 1) !== epoch) {
|
||||
return failure('stale_generation_epoch', { expectedEpoch: snapshot.generationEpoch || 1 });
|
||||
}
|
||||
|
||||
const current = fs.readFileSync(sourcePath, 'utf-8');
|
||||
const currentHash = sha256(current);
|
||||
if (!expectedSourceHash || currentHash !== expectedSourceHash) {
|
||||
return failure('source_hash_mismatch', { actualSourceHash: currentHash });
|
||||
}
|
||||
|
||||
if (componentTarget) {
|
||||
return publishComponentArtifact({
|
||||
id,
|
||||
epoch,
|
||||
snapshot,
|
||||
target: componentTarget,
|
||||
artifactManifest,
|
||||
artifactPath,
|
||||
sourcePath,
|
||||
arrivedVariants,
|
||||
expectedVariants,
|
||||
publicationKind,
|
||||
store,
|
||||
cwd,
|
||||
});
|
||||
}
|
||||
|
||||
const stablePreview = sourceArtifactTarget
|
||||
? fs.readFileSync(sourceArtifactTarget.previewPath, 'utf-8')
|
||||
: current;
|
||||
const artifact = fs.readFileSync(artifactPath, 'utf-8');
|
||||
if (!artifact.includes('data-impeccable-variants="' + id + '"')) {
|
||||
return failure('artifact_missing_session_wrapper');
|
||||
}
|
||||
const delivered = countDeliveredVariants(artifact);
|
||||
if (delivered < 1) return failure('artifact_has_no_variants');
|
||||
if (Number.isInteger(arrivedVariants) && delivered < arrivedVariants) {
|
||||
return failure('artifact_variant_count_mismatch', { delivered });
|
||||
}
|
||||
const priorArrived = Math.max(0, Number(snapshot.arrivedVariants || 0));
|
||||
for (let variant = 1; variant <= priorArrived; variant++) {
|
||||
const currentVariant = extractVariantBlock(stablePreview, variant);
|
||||
const artifactVariant = extractVariantBlock(artifact, variant);
|
||||
if (!currentVariant || !artifactVariant) {
|
||||
return failure('published_variant_missing', { variant });
|
||||
}
|
||||
if (sha256(withoutVariantParams(currentVariant)) !== sha256(withoutVariantParams(artifactVariant))) {
|
||||
return failure('published_variant_changed', { variant });
|
||||
}
|
||||
}
|
||||
const currentPreviewCss = extractPreviewCss(stablePreview, id);
|
||||
const artifactPreviewCss = extractPreviewCss(artifact, id);
|
||||
if (priorArrived > 0 && currentPreviewCss && !artifactPreviewCss.startsWith(currentPreviewCss)) {
|
||||
return failure('published_variant_css_changed');
|
||||
}
|
||||
|
||||
const commitSnapshot = store.getSnapshot(id, { includeCompleted: true });
|
||||
if (commitSnapshot?.generationCanceled === true) {
|
||||
return failure('stale_generation_epoch', { canceled: true, phase: commitSnapshot.phase });
|
||||
}
|
||||
if (Number(commitSnapshot?.generationEpoch || 1) !== epoch) {
|
||||
return failure('stale_generation_epoch', { expectedEpoch: commitSnapshot?.generationEpoch || 1 });
|
||||
}
|
||||
const artifactHash = sha256(artifact);
|
||||
const publishPath = sourceArtifactTarget?.previewPath || sourcePath;
|
||||
atomicReplace(publishPath, artifact);
|
||||
const revision = Number(commitSnapshot.publishedRevision || 0) + 1;
|
||||
store.appendEvent({
|
||||
type: 'variant_published',
|
||||
id,
|
||||
generationEpoch: epoch,
|
||||
revision,
|
||||
digest: artifactHash,
|
||||
sourceFile: relative(cwd, sourcePath),
|
||||
...(sourceArtifactTarget ? {
|
||||
previewFile: relative(cwd, publishPath),
|
||||
previewMode: SOURCE_ARTIFACT_PREVIEW_MODE,
|
||||
} : {}),
|
||||
arrivedVariants: delivered,
|
||||
expectedVariants: Number(expectedVariants || snapshot.expectedVariants || delivered),
|
||||
publicationKind: publicationKind || 'variants',
|
||||
at: Date.now(),
|
||||
});
|
||||
return {
|
||||
ok: true,
|
||||
id,
|
||||
epoch,
|
||||
revision,
|
||||
digest: artifactHash,
|
||||
sourceFile: relative(cwd, sourcePath),
|
||||
...(sourceArtifactTarget ? {
|
||||
previewFile: relative(cwd, publishPath),
|
||||
previewMode: SOURCE_ARTIFACT_PREVIEW_MODE,
|
||||
} : {}),
|
||||
arrivedVariants: delivered,
|
||||
expectedVariants: Number(expectedVariants || snapshot.expectedVariants || delivered),
|
||||
publicationKind: publicationKind || 'variants',
|
||||
};
|
||||
}, { cwd });
|
||||
} catch (error) {
|
||||
if (error?.code === 'SOURCE_LOCKED') return failure('source_locked');
|
||||
return failure('publish_failed', { message: error?.message || String(error) });
|
||||
}
|
||||
}
|
||||
|
||||
function prepareComponentArtifact({
|
||||
id,
|
||||
revision,
|
||||
snapshot,
|
||||
source,
|
||||
sourcePath,
|
||||
requestedPath,
|
||||
target,
|
||||
artifactDir,
|
||||
cwd,
|
||||
}) {
|
||||
const artifactComponentDir = path.join(
|
||||
artifactDir,
|
||||
id + '-r' + revision + '-' + target.manifest.previewMode + '-' + process.pid + '-' + Date.now(),
|
||||
);
|
||||
fs.mkdirSync(artifactComponentDir, { recursive: true });
|
||||
copyDirectoryFiles(target.componentPath, artifactComponentDir);
|
||||
const artifactPath = path.join(artifactComponentDir, 'manifest.json');
|
||||
const artifactManifest = {
|
||||
...target.manifest,
|
||||
componentDir: relative(cwd, artifactComponentDir),
|
||||
};
|
||||
fs.writeFileSync(artifactPath, JSON.stringify(artifactManifest, null, 2) + '\n', 'utf-8');
|
||||
return {
|
||||
ok: true,
|
||||
id,
|
||||
epoch: Number(snapshot.generationEpoch || 1),
|
||||
revision,
|
||||
sourceFile: relative(cwd, requestedPath),
|
||||
targetSourceFile: relative(cwd, sourcePath),
|
||||
artifactFile: relative(cwd, artifactPath),
|
||||
componentDir: relative(cwd, artifactComponentDir),
|
||||
previewMode: target.manifest.previewMode,
|
||||
expectedSourceHash: sha256(source),
|
||||
};
|
||||
}
|
||||
|
||||
function publishComponentArtifact({
|
||||
id,
|
||||
epoch,
|
||||
snapshot,
|
||||
target,
|
||||
artifactManifest,
|
||||
artifactPath,
|
||||
sourcePath,
|
||||
arrivedVariants,
|
||||
expectedVariants,
|
||||
publicationKind,
|
||||
store,
|
||||
cwd,
|
||||
}) {
|
||||
if (!artifactManifest || typeof artifactManifest !== 'object') {
|
||||
return failure('artifact_manifest_invalid');
|
||||
}
|
||||
if (artifactManifest.id !== id || target.manifest.id !== id) {
|
||||
return failure('artifact_session_mismatch');
|
||||
}
|
||||
const artifactComponentPath = resolveInside(cwd, artifactManifest.componentDir);
|
||||
if (!artifactComponentPath || path.resolve(artifactComponentPath) !== path.dirname(artifactPath)) {
|
||||
return failure('artifact_component_dir_mismatch');
|
||||
}
|
||||
if (!isDescendant(path.join(getLiveDir(cwd), 'artifacts'), artifactComponentPath)) {
|
||||
return failure('artifact_not_staged');
|
||||
}
|
||||
const immutableMismatch = componentManifestMismatch(target.manifest, artifactManifest);
|
||||
if (immutableMismatch) {
|
||||
return failure('artifact_manifest_changed', { field: immutableMismatch });
|
||||
}
|
||||
|
||||
const expected = Number(expectedVariants || target.manifest.count || snapshot.expectedVariants || 0);
|
||||
const declared = optionalPositiveInteger(artifactManifest.arrivedVariants);
|
||||
const delivered = Number.isInteger(arrivedVariants) ? arrivedVariants : declared;
|
||||
if (!Number.isInteger(delivered) || delivered < 1) return failure('artifact_has_no_variants');
|
||||
if (expected > 0 && delivered > expected) {
|
||||
return failure('artifact_variant_count_mismatch', { delivered, expected });
|
||||
}
|
||||
if (declared !== null && declared !== delivered) {
|
||||
return failure('artifact_variant_count_mismatch', { delivered: declared, expected: delivered });
|
||||
}
|
||||
|
||||
const priorArrived = Math.max(
|
||||
optionalPositiveInteger(target.manifest.arrivedVariants) || 0,
|
||||
Number(snapshot.arrivedVariants || 0),
|
||||
);
|
||||
if (delivered < priorArrived) {
|
||||
return failure('artifact_variant_count_regressed', { delivered, priorArrived });
|
||||
}
|
||||
|
||||
const componentExtension = target.manifest.componentExtension
|
||||
|| (target.manifest.previewMode === 'vue-component' ? 'vue' : 'svelte');
|
||||
const variantContents = [];
|
||||
for (let variant = 1; variant <= delivered; variant++) {
|
||||
const artifactVariantPath = path.join(artifactComponentPath, 'v' + variant + '.' + componentExtension);
|
||||
if (!regularFileInside(artifactComponentPath, artifactVariantPath)) {
|
||||
return failure('artifact_variant_missing', { variant });
|
||||
}
|
||||
const content = fs.readFileSync(artifactVariantPath, 'utf-8');
|
||||
if (!content.trim()) return failure('artifact_variant_empty', { variant });
|
||||
const targetVariantPath = path.join(target.componentPath, 'v' + variant + '.' + componentExtension);
|
||||
if (variant <= priorArrived && !regularFileInside(target.componentPath, targetVariantPath)) {
|
||||
return failure('published_variant_missing', { variant });
|
||||
}
|
||||
if (variant <= priorArrived) {
|
||||
const prior = fs.readFileSync(targetVariantPath, 'utf-8');
|
||||
if (sha256(prior) !== sha256(content)) {
|
||||
return failure('published_variant_changed', { variant });
|
||||
}
|
||||
}
|
||||
variantContents.push({ variant, content, targetPath: targetVariantPath });
|
||||
}
|
||||
|
||||
const artifactParamsPath = path.join(artifactComponentPath, 'params.json');
|
||||
let paramsContent = null;
|
||||
if (fs.existsSync(artifactParamsPath)) {
|
||||
if (!regularFileInside(artifactComponentPath, artifactParamsPath)) {
|
||||
return failure('artifact_params_invalid');
|
||||
}
|
||||
paramsContent = fs.readFileSync(artifactParamsPath, 'utf-8');
|
||||
const params = parseJson(paramsContent);
|
||||
if (!params || typeof params !== 'object' || Array.isArray(params)) {
|
||||
return failure('artifact_params_invalid');
|
||||
}
|
||||
}
|
||||
|
||||
// Components and optional params become reachable before the manifest
|
||||
// advertises them. Committing the manifest last makes publication atomic
|
||||
// from the browser's point of view while the source lock excludes Accept.
|
||||
fs.mkdirSync(target.componentPath, { recursive: true });
|
||||
for (const variant of variantContents) {
|
||||
if (variant.variant > priorArrived) atomicReplace(variant.targetPath, variant.content);
|
||||
}
|
||||
if (paramsContent !== null) {
|
||||
atomicReplace(path.join(target.componentPath, 'params.json'), paramsContent);
|
||||
}
|
||||
const commitSnapshot = store.getSnapshot(id, { includeCompleted: true });
|
||||
if (commitSnapshot?.generationCanceled === true) {
|
||||
return failure('stale_generation_epoch', { canceled: true, phase: commitSnapshot.phase });
|
||||
}
|
||||
if (Number(commitSnapshot?.generationEpoch || 1) !== epoch) {
|
||||
return failure('stale_generation_epoch', { expectedEpoch: commitSnapshot?.generationEpoch || 1 });
|
||||
}
|
||||
const publishedManifest = {
|
||||
...target.manifest,
|
||||
componentDir: relative(cwd, target.componentPath),
|
||||
arrivedVariants: delivered,
|
||||
};
|
||||
delete publishedManifest.manifestPath;
|
||||
const manifestContent = JSON.stringify(publishedManifest, null, 2) + '\n';
|
||||
atomicReplace(target.manifestPath, manifestContent);
|
||||
|
||||
const digest = digestComponentPublication(manifestContent, variantContents, paramsContent);
|
||||
const revision = Number(snapshot.publishedRevision || 0) + 1;
|
||||
const sourceFile = relative(cwd, sourcePath);
|
||||
const previewFile = relative(cwd, target.manifestPath);
|
||||
store.appendEvent({
|
||||
type: 'variant_published',
|
||||
id,
|
||||
generationEpoch: epoch,
|
||||
revision,
|
||||
digest,
|
||||
sourceFile,
|
||||
previewFile,
|
||||
previewMode: target.manifest.previewMode,
|
||||
arrivedVariants: delivered,
|
||||
expectedVariants: expected || delivered,
|
||||
publicationKind: publicationKind || 'variants',
|
||||
at: Date.now(),
|
||||
});
|
||||
return {
|
||||
ok: true,
|
||||
id,
|
||||
epoch,
|
||||
revision,
|
||||
digest,
|
||||
sourceFile,
|
||||
previewFile,
|
||||
previewMode: target.manifest.previewMode,
|
||||
componentDir: relative(cwd, target.componentPath),
|
||||
arrivedVariants: delivered,
|
||||
expectedVariants: expected || delivered,
|
||||
publicationKind: publicationKind || 'variants',
|
||||
};
|
||||
}
|
||||
|
||||
const COMPONENT_MANIFEST_FIELDS = [
|
||||
'id',
|
||||
'mode',
|
||||
'previewMode',
|
||||
'sourceFile',
|
||||
'sourceStartLine',
|
||||
'sourceEndLine',
|
||||
'insertLine',
|
||||
'position',
|
||||
'anchorStartLine',
|
||||
'anchorEndLine',
|
||||
'count',
|
||||
'propContract',
|
||||
'originalMarkup',
|
||||
'anchorMarkup',
|
||||
'runtimeModule',
|
||||
'componentModuleBase',
|
||||
'framework',
|
||||
'componentExtension',
|
||||
];
|
||||
|
||||
function readComponentPublicationTarget(manifestPath, cwd, id) {
|
||||
if (path.basename(manifestPath) !== 'manifest.json') return null;
|
||||
const manifest = readJson(manifestPath);
|
||||
if (!manifest || !isComponentPreviewMode(manifest.previewMode)) return null;
|
||||
if (manifest.id !== id) return failure('artifact_session_mismatch');
|
||||
const sourcePath = resolveInside(cwd, manifest.sourceFile);
|
||||
const componentPath = resolveInside(cwd, manifest.componentDir);
|
||||
if (!sourcePath || !componentPath) return failure('path_outside_project');
|
||||
if (!fs.existsSync(sourcePath)) return failure('source_missing');
|
||||
if (path.resolve(componentPath) !== path.dirname(manifestPath)) {
|
||||
return failure('manifest_component_dir_mismatch');
|
||||
}
|
||||
return { manifest, manifestPath, sourcePath, componentPath };
|
||||
}
|
||||
|
||||
function readSourceArtifactPublicationTarget(requestedPath, cwd, id) {
|
||||
const manifest = findSourceArtifactManifest(id, cwd);
|
||||
if (!manifest) return null;
|
||||
if (path.resolve(requestedPath) !== path.resolve(manifest.previewPath)) {
|
||||
return failure('source_artifact_preview_mismatch');
|
||||
}
|
||||
return manifest;
|
||||
}
|
||||
|
||||
function componentManifestMismatch(target, artifact) {
|
||||
for (const field of COMPONENT_MANIFEST_FIELDS) {
|
||||
if (JSON.stringify(target[field] ?? null) !== JSON.stringify(artifact[field] ?? null)) return field;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function isComponentPreviewMode(value) {
|
||||
return value === 'svelte-component' || value === 'vue-component';
|
||||
}
|
||||
|
||||
function copyDirectoryFiles(sourceDir, targetDir) {
|
||||
for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
|
||||
if (!entry.isFile() || entry.isSymbolicLink()) continue;
|
||||
fs.copyFileSync(path.join(sourceDir, entry.name), path.join(targetDir, entry.name));
|
||||
}
|
||||
}
|
||||
|
||||
function regularFileInside(root, file) {
|
||||
const rel = path.relative(root, file);
|
||||
if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return false;
|
||||
try {
|
||||
return fs.lstatSync(file).isFile();
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
function isDescendant(root, candidate) {
|
||||
const rel = path.relative(root, candidate);
|
||||
return Boolean(rel) && !rel.startsWith('..') && !path.isAbsolute(rel);
|
||||
}
|
||||
|
||||
function digestComponentPublication(manifestContent, variants, paramsContent) {
|
||||
const hash = createHash('sha256');
|
||||
hash.update(manifestContent);
|
||||
for (const variant of variants) {
|
||||
hash.update('\0v' + variant.variant + '\0');
|
||||
hash.update(variant.content);
|
||||
}
|
||||
if (paramsContent !== null) hash.update('\0params\0' + paramsContent);
|
||||
return hash.digest('hex');
|
||||
}
|
||||
|
||||
function readJson(file) {
|
||||
try {
|
||||
return JSON.parse(fs.readFileSync(file, 'utf-8'));
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function parseJson(value) {
|
||||
try {
|
||||
return JSON.parse(value);
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function optionalPositiveInteger(value) {
|
||||
const number = Number(value);
|
||||
return Number.isInteger(number) && number > 0 ? number : null;
|
||||
}
|
||||
|
||||
function countDeliveredVariants(source) {
|
||||
const matches = source.match(/<div\b[^>]*\bdata-impeccable-variant=(?:"|')(?!original(?:"|'))[^"']+(?:"|')[^>]*>/g);
|
||||
return matches?.length || 0;
|
||||
}
|
||||
|
||||
function extractVariantBlock(source, variant) {
|
||||
const open = /<div\b[^>]*>/gi;
|
||||
let match;
|
||||
let start = -1;
|
||||
const attr = new RegExp("\\bdata-impeccable-variant=(?:\"" + variant + "\"|'" + variant + "')");
|
||||
while ((match = open.exec(source))) {
|
||||
if (attr.test(match[0])) {
|
||||
start = match.index;
|
||||
break;
|
||||
}
|
||||
}
|
||||
if (start < 0) return null;
|
||||
|
||||
const token = /<div\b[^>]*\/\s*>|<div\b[^>]*>|<\/div\s*>/gi;
|
||||
token.lastIndex = start;
|
||||
let depth = 0;
|
||||
while ((match = token.exec(source))) {
|
||||
if (/^<\/div/i.test(match[0])) {
|
||||
depth -= 1;
|
||||
if (depth === 0) return source.slice(start, token.lastIndex);
|
||||
} else if (!/\/\s*>$/.test(match[0])) {
|
||||
depth += 1;
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function withoutVariantParams(block) {
|
||||
return String(block || '').replace(
|
||||
/\sdata-impeccable-params=(?:"[^"]*"|'[^']*')/i,
|
||||
'',
|
||||
);
|
||||
}
|
||||
|
||||
function extractPreviewCss(source, id) {
|
||||
const escapedId = String(id).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
||||
const open = new RegExp("<style\\b[^>]*\\bdata-impeccable-css=(?:\"" + escapedId + "\"|'" + escapedId + "')[^>]*>", 'i');
|
||||
const match = open.exec(source);
|
||||
if (!match) return '';
|
||||
const start = match.index + match[0].length;
|
||||
const end = source.indexOf('</style>', start);
|
||||
if (end < 0) return '';
|
||||
return source.slice(start, end)
|
||||
.replace(/^\s*\{\s*`\s*/, '')
|
||||
.replace(/\s*`\s*\}\s*$/, '')
|
||||
.trim();
|
||||
}
|
||||
|
||||
function atomicReplace(target, content) {
|
||||
let mode = 0o666;
|
||||
try { mode = fs.statSync(target).mode; } catch {}
|
||||
const temp = target + '.impeccable-publish-' + process.pid + '-' + Date.now();
|
||||
try {
|
||||
fs.writeFileSync(temp, content, { encoding: 'utf-8', mode });
|
||||
fs.renameSync(temp, target);
|
||||
} finally {
|
||||
try { fs.unlinkSync(temp); } catch {}
|
||||
}
|
||||
}
|
||||
|
||||
function resolveInside(cwd, value) {
|
||||
const resolved = path.resolve(cwd, value);
|
||||
const rel = path.relative(cwd, resolved);
|
||||
if (rel.startsWith('..') || path.isAbsolute(rel)) return null;
|
||||
return resolved;
|
||||
}
|
||||
|
||||
function relative(cwd, value) {
|
||||
return path.relative(cwd, value).split(path.sep).join('/');
|
||||
}
|
||||
|
||||
function failure(error, details = {}) {
|
||||
return { ok: false, error, ...details };
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
export function eventPriority(event = {}) {
|
||||
if (event.type === 'accept' || event.type === 'discard' || event.type === 'exit') return 0;
|
||||
if (event.type === 'manual_edit_apply' || event.type === 'steer' || event.type === 'carbonize_cleanup') return 1;
|
||||
if (event.type === 'generate') return 2;
|
||||
return 3;
|
||||
}
|
||||
|
||||
export function selectAvailablePendingEvent(entries, { now = Date.now(), types = null } = {}) {
|
||||
const allowed = types instanceof Set ? types : (Array.isArray(types) ? new Set(types) : null);
|
||||
return entries
|
||||
.filter((entry) => !(entry.leaseUntil && entry.leaseUntil > now))
|
||||
.filter((entry) => !allowed || allowed.has(entry.event?.type))
|
||||
.sort((a, b) => eventPriority(a.event) - eventPriority(b.event) || a.seq - b.seq)[0] || null;
|
||||
}
|
||||
@@ -3,6 +3,13 @@ import path from 'node:path';
|
||||
import { getLegacyLiveSessionsDir, getLiveSessionsDir } from '../lib/impeccable-paths.mjs';
|
||||
|
||||
const COMPLETED_PHASES = new Set(['completed', 'discarded']);
|
||||
const GENERATION_FENCED_PHASES = new Set([
|
||||
'accept_requested',
|
||||
'discard_requested',
|
||||
'carbonize_required',
|
||||
'completed',
|
||||
'discarded',
|
||||
]);
|
||||
|
||||
export function createLiveSessionStore({ cwd = process.cwd(), sessionId } = {}) {
|
||||
const rootDir = getLiveSessionsDir(cwd);
|
||||
@@ -38,7 +45,10 @@ export function createLiveSessionStore({ cwd = process.cwd(), sessionId } = {})
|
||||
if (!fs.existsSync(journalPath) && fs.existsSync(legacyJournalPath)) {
|
||||
fs.copyFileSync(legacyJournalPath, journalPath);
|
||||
}
|
||||
const prior = loadCachedOrRebuild(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;
|
||||
const entry = {
|
||||
seq,
|
||||
@@ -116,9 +126,21 @@ function baseSnapshot(id) {
|
||||
pendingEvent: null,
|
||||
deliveryLease: null,
|
||||
checkpointRevision: 0,
|
||||
browserCheckpointRevision: 0,
|
||||
publicationCheckpointRevision: 0,
|
||||
activeOwner: null,
|
||||
sourceMarkers: {},
|
||||
fallbackMode: null,
|
||||
generationPhase: null,
|
||||
generationTimings: {},
|
||||
generationEpoch: 1,
|
||||
publishedRevision: 0,
|
||||
deliveredVariants: {},
|
||||
variantPlan: null,
|
||||
paramsPublished: false,
|
||||
generationCanceled: false,
|
||||
generationCanceledAt: null,
|
||||
cancelReason: null,
|
||||
annotationArtifacts: [],
|
||||
diagnostics: [],
|
||||
updatedAt: null,
|
||||
@@ -158,6 +180,9 @@ function applyEvent(snapshot, entry, inheritedDiagnostics = []) {
|
||||
...snapshot,
|
||||
paramValues: { ...(snapshot.paramValues || {}) },
|
||||
sourceMarkers: { ...(snapshot.sourceMarkers || {}) },
|
||||
generationTimings: { ...(snapshot.generationTimings || {}) },
|
||||
deliveredVariants: { ...(snapshot.deliveredVariants || {}) },
|
||||
variantPlan: snapshot.variantPlan || null,
|
||||
annotationArtifacts: [...(snapshot.annotationArtifacts || [])],
|
||||
diagnostics: [...(snapshot.diagnostics || [])],
|
||||
updatedAt: entry.ts || new Date().toISOString(),
|
||||
@@ -170,14 +195,81 @@ function applyEvent(snapshot, entry, inheritedDiagnostics = []) {
|
||||
switch (event.type) {
|
||||
case 'generate':
|
||||
next.phase = 'generate_requested';
|
||||
next.generationEpoch = Number(event.generationEpoch || next.generationEpoch || 1);
|
||||
next.pageUrl = event.pageUrl ?? next.pageUrl;
|
||||
next.expectedVariants = event.count ?? next.expectedVariants;
|
||||
next.pendingEventSeq = entry.seq ?? next.pendingEventSeq;
|
||||
next.pendingEvent = toPendingEvent(event);
|
||||
next.variantPlan = null;
|
||||
if (event.screenshotPath) upsertArtifact(next.annotationArtifacts, { type: 'screenshot', path: event.screenshotPath });
|
||||
break;
|
||||
case 'variant_plan':
|
||||
if (!next.generationCanceled && !GENERATION_FENCED_PHASES.has(next.phase)) {
|
||||
next.variantPlan = event.plan ?? next.variantPlan;
|
||||
}
|
||||
break;
|
||||
case 'detector_waivers':
|
||||
if (!next.generationCanceled && !GENERATION_FENCED_PHASES.has(next.phase)) {
|
||||
next.detectorWaivers = [
|
||||
...(next.detectorWaivers || []),
|
||||
...(Array.isArray(event.waivers) ? event.waivers : []),
|
||||
];
|
||||
}
|
||||
break;
|
||||
case 'variant_published':
|
||||
if (next.generationCanceled || GENERATION_FENCED_PHASES.has(next.phase)) {
|
||||
next.diagnostics.push({
|
||||
error: 'late_generation_event_ignored',
|
||||
type: event.type,
|
||||
phase: next.phase,
|
||||
revision: event.revision ?? null,
|
||||
});
|
||||
break;
|
||||
}
|
||||
if (Number(event.generationEpoch || 0) !== Number(next.generationEpoch || 1)) {
|
||||
next.diagnostics.push({
|
||||
error: 'stale_generation_epoch_ignored',
|
||||
epoch: event.generationEpoch ?? null,
|
||||
expectedEpoch: next.generationEpoch || 1,
|
||||
});
|
||||
break;
|
||||
}
|
||||
next.phase = 'variants_progress';
|
||||
next.publishedRevision = Math.max(next.publishedRevision || 0, Number(event.revision || 0));
|
||||
next.arrivedVariants = Math.max(next.arrivedVariants || 0, Number(event.arrivedVariants || 0));
|
||||
next.expectedVariants = Number(event.expectedVariants || next.expectedVariants || 0);
|
||||
if (event.publicationKind === 'params') next.paramsPublished = true;
|
||||
next.sourceFile = event.sourceFile ?? next.sourceFile;
|
||||
next.previewFile = event.previewFile ?? next.previewFile;
|
||||
next.previewMode = event.previewMode ?? next.previewMode;
|
||||
if (event.revision) {
|
||||
next.deliveredVariants[String(event.revision)] = {
|
||||
digest: event.digest || null,
|
||||
arrivedVariants: Number(event.arrivedVariants || 0),
|
||||
publishedAt: event.at || null,
|
||||
};
|
||||
}
|
||||
break;
|
||||
case 'agent_phase':
|
||||
next.generationPhase = event.phase ?? next.generationPhase;
|
||||
if (event.phase) {
|
||||
next.generationTimings[event.phase] = {
|
||||
at: event.at ?? (Date.parse(entry.ts || '') || null),
|
||||
durationMs: event.durationMs ?? null,
|
||||
};
|
||||
}
|
||||
break;
|
||||
case 'variants_ready':
|
||||
case 'agent_done':
|
||||
if ((next.generationCanceled || GENERATION_FENCED_PHASES.has(next.phase))
|
||||
&& !(event.type === 'agent_done' && event.carbonize === true && next.phase === 'accept_requested')) {
|
||||
next.diagnostics.push({
|
||||
error: 'late_generation_event_ignored',
|
||||
type: event.type,
|
||||
phase: next.phase,
|
||||
});
|
||||
break;
|
||||
}
|
||||
next.phase = event.carbonize === true ? 'carbonize_required' : 'variants_ready';
|
||||
next.sourceFile = event.sourceFile ?? event.file ?? next.sourceFile;
|
||||
next.previewFile = event.previewFile ?? next.previewFile;
|
||||
@@ -194,27 +286,45 @@ function applyEvent(snapshot, entry, inheritedDiagnostics = []) {
|
||||
}
|
||||
break;
|
||||
case 'checkpoint':
|
||||
if (COMPLETED_PHASES.has(next.phase)) {
|
||||
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 });
|
||||
break;
|
||||
}
|
||||
if ((event.revision ?? 0) >= (next.checkpointRevision ?? 0)) {
|
||||
next.phase = event.phase ?? next.phase;
|
||||
next.checkpointRevision = event.revision ?? next.checkpointRevision;
|
||||
next.activeOwner = event.owner ?? next.activeOwner;
|
||||
next.arrivedVariants = event.arrivedVariants ?? next.arrivedVariants;
|
||||
next.visibleVariant = event.visibleVariant ?? next.visibleVariant;
|
||||
next.sourceFile = event.sourceFile ?? next.sourceFile;
|
||||
next.previewFile = event.previewFile ?? next.previewFile;
|
||||
next.previewMode = event.previewMode ?? next.previewMode;
|
||||
if (event.paramValues) next.paramValues = { ...event.paramValues };
|
||||
} else {
|
||||
next.diagnostics.push({ error: 'stale_checkpoint_ignored', revision: event.revision });
|
||||
{
|
||||
const revisionDomain = event.revisionDomain === 'publication'
|
||||
|| (event.reason === 'variants_progress' && !event.owner)
|
||||
? 'publication'
|
||||
: 'browser';
|
||||
const revisionField = revisionDomain === 'publication'
|
||||
? 'publicationCheckpointRevision'
|
||||
: 'browserCheckpointRevision';
|
||||
const currentRevision = next[revisionField]
|
||||
?? (revisionDomain === 'browser' ? next.checkpointRevision : 0)
|
||||
?? 0;
|
||||
if ((event.revision ?? 0) >= currentRevision) {
|
||||
next.phase = event.phase ?? next.phase;
|
||||
next[revisionField] = event.revision ?? currentRevision;
|
||||
if (revisionDomain === 'browser') {
|
||||
next.checkpointRevision = event.revision ?? next.checkpointRevision;
|
||||
next.activeOwner = event.owner ?? next.activeOwner;
|
||||
}
|
||||
next.arrivedVariants = event.arrivedVariants ?? next.arrivedVariants;
|
||||
if (revisionDomain === 'browser') next.visibleVariant = event.visibleVariant ?? next.visibleVariant;
|
||||
next.sourceFile = event.sourceFile ?? next.sourceFile;
|
||||
next.previewFile = event.previewFile ?? next.previewFile;
|
||||
next.previewMode = event.previewMode ?? next.previewMode;
|
||||
if (revisionDomain === 'browser' && event.paramValues) next.paramValues = { ...event.paramValues };
|
||||
} else {
|
||||
next.diagnostics.push({ error: 'stale_checkpoint_ignored', revision: event.revision, revisionDomain });
|
||||
}
|
||||
}
|
||||
break;
|
||||
case 'accept':
|
||||
case 'accept_intent':
|
||||
next.phase = 'accept_requested';
|
||||
next.generationCanceled = true;
|
||||
next.generationCanceledAt = event.at ?? (Date.parse(entry.ts || '') || Date.now());
|
||||
next.cancelReason = 'accept';
|
||||
next.visibleVariant = Number(event.variantId ?? next.visibleVariant);
|
||||
if (event.paramValues) next.paramValues = { ...event.paramValues };
|
||||
next.pendingEventSeq = entry.seq ?? next.pendingEventSeq;
|
||||
@@ -232,6 +342,12 @@ function applyEvent(snapshot, entry, inheritedDiagnostics = []) {
|
||||
next.pendingEventSeq = entry.seq ?? next.pendingEventSeq;
|
||||
next.pendingEvent = toPendingEvent(event);
|
||||
break;
|
||||
case 'carbonize_cleanup':
|
||||
next.phase = 'carbonize_cleanup_requested';
|
||||
next.sourceFile = event.file ?? next.sourceFile;
|
||||
next.pendingEventSeq = entry.seq ?? next.pendingEventSeq;
|
||||
next.pendingEvent = toPendingEvent(event);
|
||||
break;
|
||||
case 'steer_done':
|
||||
next.phase = 'steer_done';
|
||||
next.sourceFile = event.sourceFile ?? event.file ?? next.sourceFile;
|
||||
@@ -243,6 +359,9 @@ function applyEvent(snapshot, entry, inheritedDiagnostics = []) {
|
||||
break;
|
||||
case 'discard':
|
||||
next.phase = 'discard_requested';
|
||||
next.generationCanceled = true;
|
||||
next.generationCanceledAt = event.at ?? (Date.parse(entry.ts || '') || Date.now());
|
||||
next.cancelReason = 'discard';
|
||||
next.pendingEventSeq = entry.seq ?? next.pendingEventSeq;
|
||||
next.pendingEvent = toPendingEvent(event);
|
||||
break;
|
||||
@@ -260,6 +379,10 @@ function applyEvent(snapshot, entry, inheritedDiagnostics = []) {
|
||||
next.pendingEvent = null;
|
||||
break;
|
||||
case 'agent_error':
|
||||
if (next.generationCanceled && event.sourceEventType === 'generate') {
|
||||
next.diagnostics.push({ error: 'late_generation_event_ignored', type: event.type, phase: next.phase });
|
||||
break;
|
||||
}
|
||||
next.phase = 'agent_error';
|
||||
next.pendingEventSeq = null;
|
||||
next.pendingEvent = null;
|
||||
|
||||
@@ -0,0 +1,76 @@
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import { getLiveDir } from '../lib/impeccable-paths.mjs';
|
||||
|
||||
export const SOURCE_ARTIFACT_PREVIEW_MODE = 'source-artifact';
|
||||
|
||||
export function scaffoldSourceArtifactSession({
|
||||
id,
|
||||
count,
|
||||
sourceFile,
|
||||
sourceStartLine,
|
||||
sourceEndLine,
|
||||
originalSource,
|
||||
previewContent,
|
||||
cwd = process.cwd(),
|
||||
} = {}) {
|
||||
if (!/^[A-Za-z0-9_-]{1,128}$/.test(String(id || ''))) {
|
||||
throw new Error('invalid source artifact session id');
|
||||
}
|
||||
const sourcePath = resolveInside(cwd, sourceFile);
|
||||
if (!sourcePath || !fs.existsSync(sourcePath)) throw new Error('source artifact target missing');
|
||||
|
||||
const sessionDir = path.join(getLiveDir(cwd), 'previews', id);
|
||||
const extension = path.extname(sourcePath) || '.html';
|
||||
const previewPath = path.join(sessionDir, 'preview' + extension);
|
||||
const manifestPath = path.join(sessionDir, 'manifest.json');
|
||||
fs.mkdirSync(sessionDir, { recursive: true });
|
||||
|
||||
const manifest = {
|
||||
id,
|
||||
count: Number(count || 1),
|
||||
previewMode: SOURCE_ARTIFACT_PREVIEW_MODE,
|
||||
sourceFile: relative(cwd, sourcePath),
|
||||
previewFile: relative(cwd, previewPath),
|
||||
sourceStartLine: Number(sourceStartLine),
|
||||
sourceEndLine: Number(sourceEndLine),
|
||||
originalSource: String(originalSource || ''),
|
||||
};
|
||||
fs.writeFileSync(previewPath, String(previewContent || ''), 'utf-8');
|
||||
fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
|
||||
return { ...manifest, manifestFile: relative(cwd, manifestPath), sessionDir: relative(cwd, sessionDir) };
|
||||
}
|
||||
|
||||
export function findSourceArtifactManifest(id, cwd = process.cwd()) {
|
||||
if (!/^[A-Za-z0-9_-]{1,128}$/.test(String(id || ''))) return null;
|
||||
const manifestPath = path.join(getLiveDir(cwd), 'previews', id, 'manifest.json');
|
||||
let manifest;
|
||||
try { manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8')); } catch { return null; }
|
||||
if (manifest?.id !== id || manifest?.previewMode !== SOURCE_ARTIFACT_PREVIEW_MODE) return null;
|
||||
const sourcePath = resolveInside(cwd, manifest.sourceFile);
|
||||
const previewPath = resolveInside(cwd, manifest.previewFile);
|
||||
if (!sourcePath || !previewPath || !fs.existsSync(sourcePath) || !fs.existsSync(previewPath)) return null;
|
||||
return { ...manifest, manifestPath, sourcePath, previewPath };
|
||||
}
|
||||
|
||||
export function removeSourceArtifactSession(id, cwd = process.cwd()) {
|
||||
if (!/^[A-Za-z0-9_-]{1,128}$/.test(String(id || ''))) return false;
|
||||
const sessionDir = path.join(getLiveDir(cwd), 'previews', id);
|
||||
if (!fs.existsSync(sessionDir)) return false;
|
||||
fs.rmSync(sessionDir, { recursive: true, force: true });
|
||||
return true;
|
||||
}
|
||||
|
||||
function resolveInside(cwd, value) {
|
||||
if (!value || typeof value !== 'string') return null;
|
||||
const root = path.resolve(cwd);
|
||||
const resolved = path.resolve(root, value);
|
||||
const rel = path.relative(root, resolved);
|
||||
if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return null;
|
||||
return resolved;
|
||||
}
|
||||
|
||||
function relative(cwd, value) {
|
||||
return path.relative(cwd, value).split(path.sep).join('/');
|
||||
}
|
||||
@@ -0,0 +1,56 @@
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
import { createHash } from 'node:crypto';
|
||||
import { getLiveDir } from '../lib/impeccable-paths.mjs';
|
||||
|
||||
const STALE_LOCK_MS = 60_000;
|
||||
|
||||
export function sourceLockPath(file, cwd = process.cwd()) {
|
||||
const digest = createHash('sha256').update(path.resolve(cwd, file)).digest('hex').slice(0, 24);
|
||||
return path.join(getLiveDir(cwd), 'locks', digest + '.lock');
|
||||
}
|
||||
|
||||
export function withSourceLockSync(file, owner, fn, {
|
||||
cwd = process.cwd(),
|
||||
waitMs = 0,
|
||||
retryMs = 5,
|
||||
} = {}) {
|
||||
const lockPath = sourceLockPath(file, cwd);
|
||||
fs.mkdirSync(path.dirname(lockPath), { recursive: true });
|
||||
const deadline = Date.now() + Math.max(0, Number(waitMs) || 0);
|
||||
let fd;
|
||||
while (fd === undefined) {
|
||||
clearStaleLock(lockPath);
|
||||
try {
|
||||
fd = fs.openSync(lockPath, 'wx');
|
||||
fs.writeFileSync(fd, JSON.stringify({ owner, pid: process.pid, at: Date.now(), file: path.resolve(cwd, file) }) + '\n');
|
||||
} catch (error) {
|
||||
if (error?.code !== 'EEXIST') throw error;
|
||||
if (Date.now() >= deadline) {
|
||||
const locked = new Error('source_locked');
|
||||
locked.code = 'SOURCE_LOCKED';
|
||||
locked.lockPath = lockPath;
|
||||
throw locked;
|
||||
}
|
||||
sleepSync(Math.max(1, Math.min(Number(retryMs) || 5, deadline - Date.now())));
|
||||
}
|
||||
}
|
||||
|
||||
try {
|
||||
return fn();
|
||||
} finally {
|
||||
try { if (fd !== undefined) fs.closeSync(fd); } catch {}
|
||||
try { fs.unlinkSync(lockPath); } catch {}
|
||||
}
|
||||
}
|
||||
|
||||
function sleepSync(ms) {
|
||||
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
|
||||
}
|
||||
|
||||
function clearStaleLock(lockPath) {
|
||||
try {
|
||||
const stat = fs.statSync(lockPath);
|
||||
if (Date.now() - stat.mtimeMs > STALE_LOCK_MS) fs.unlinkSync(lockPath);
|
||||
} catch {}
|
||||
}
|
||||
@@ -0,0 +1,343 @@
|
||||
/**
|
||||
* Nuxt/Vue live-mode component previews.
|
||||
*
|
||||
* Generation writes real Vue SFCs into a generated app-local module tree.
|
||||
* Nuxt/Vite compiles those modules without touching the active route; Accept
|
||||
* is the only operation that writes the user's .vue source.
|
||||
*/
|
||||
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
const NUXT_CONFIG_RE = /^nuxt\.config\.(?:js|mjs|cjs|ts|mts|cts)$/;
|
||||
|
||||
export function detectNuxtVueProject(cwd = process.cwd()) {
|
||||
const configFile = fs.readdirSync(cwd, { withFileTypes: true })
|
||||
.find((entry) => entry.isFile() && NUXT_CONFIG_RE.test(entry.name))?.name;
|
||||
if (!configFile) return null;
|
||||
const config = fs.readFileSync(path.join(cwd, configFile), 'utf-8');
|
||||
const srcDirMatch = config.match(/\bsrcDir\s*:\s*(['"])([^'"]+)\1/);
|
||||
let appDir = fs.existsSync(path.join(cwd, 'app')) ? 'app' : '';
|
||||
if (srcDirMatch) {
|
||||
const candidate = path.posix.normalize(srcDirMatch[2].replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, ''));
|
||||
if (candidate !== '..' && !candidate.startsWith('../') && !path.isAbsolute(candidate)) {
|
||||
appDir = candidate === '.' ? '' : candidate;
|
||||
}
|
||||
}
|
||||
const componentRoot = [appDir, '.impeccable-live'].filter(Boolean).join('/');
|
||||
return { configFile, appDir, componentRoot };
|
||||
}
|
||||
|
||||
export function shouldUseVueComponentInjection(filePath, cwd = process.cwd()) {
|
||||
if (/^(0|false|no)$/i.test(process.env.IMPECCABLE_LIVE_VUE_COMPONENT || '')) return false;
|
||||
return path.extname(filePath).toLowerCase() === '.vue' && !!detectNuxtVueProject(cwd);
|
||||
}
|
||||
|
||||
export function vueComponentSessionDir(id, cwd = process.cwd()) {
|
||||
const project = detectNuxtVueProject(cwd);
|
||||
if (!project) throw new Error('Nuxt project not found');
|
||||
return path.join(cwd, project.componentRoot, id);
|
||||
}
|
||||
|
||||
export function vueManifestPathForSession(id, cwd = process.cwd()) {
|
||||
return path.join(vueComponentSessionDir(id, cwd), 'manifest.json');
|
||||
}
|
||||
|
||||
function ensureVueRuntime(cwd = process.cwd()) {
|
||||
const project = detectNuxtVueProject(cwd);
|
||||
if (!project) throw new Error('Nuxt project not found');
|
||||
const rel = `${project.componentRoot}/__runtime.js`;
|
||||
const file = path.join(cwd, rel);
|
||||
fs.mkdirSync(path.dirname(file), { recursive: true });
|
||||
const source = `import { createApp } from 'vue';\n\nexport function mount(Component, options = {}) {\n const app = createApp(Component, options.props || {});\n app.mount(options.target);\n return app;\n}\n\nexport async function unmount(app) {\n app?.unmount?.();\n}\n`;
|
||||
if (!fs.existsSync(file) || fs.readFileSync(file, 'utf-8') !== source) fs.writeFileSync(file, source, 'utf-8');
|
||||
return nuxtViteFsModulePath(file, cwd);
|
||||
}
|
||||
|
||||
/**
|
||||
* Nuxt mounts Vite beneath its build-assets base (normally `/_nuxt/`).
|
||||
* Keep the manifest path base-agnostic and let the browser prepend the
|
||||
* runtime's actual buildAssetsDir. A page-route URL such as
|
||||
* `/app/.impeccable-live/x.vue` is handled by Nitro and returns HTML.
|
||||
*/
|
||||
export function nuxtViteFsModulePath(file, cwd = process.cwd()) {
|
||||
const absolute = path.resolve(cwd, file).split(path.sep).join('/');
|
||||
const relative = path.relative(cwd, absolute);
|
||||
if (relative.startsWith('..') || path.isAbsolute(relative)) {
|
||||
throw new Error('Nuxt live module must stay inside the project root');
|
||||
}
|
||||
return '/@fs/' + absolute.replace(/^\/+/, '');
|
||||
}
|
||||
|
||||
export function extractVueExpressions(markup) {
|
||||
const out = [];
|
||||
const seen = new Set();
|
||||
const re = /\{\{\s*([^{}]+?)\s*\}\}/g;
|
||||
let match;
|
||||
while ((match = re.exec(String(markup || '')))) {
|
||||
const expr = match[1].trim();
|
||||
if (!expr || seen.has(expr)) continue;
|
||||
seen.add(expr);
|
||||
out.push({ expr, token: match[0] });
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function buildVuePropContract(expressions) {
|
||||
return expressions.map(({ expr, token }, index) => ({
|
||||
prop: derivePropName(expr, index),
|
||||
expr,
|
||||
placeholder: token,
|
||||
// DOMParser sees Vue interpolation `{{ user.name }}` as text containing
|
||||
// the inner `{ user.name }` token; preserve its whitespace for the
|
||||
// browser's source-text → rendered-text map.
|
||||
previewToken: token.slice(1, -1),
|
||||
}));
|
||||
}
|
||||
|
||||
function derivePropName(expr, index) {
|
||||
const tail = expr.match(/(?:^|\.|\[)([A-Za-z_$][\w$]*)\s*\]?$/);
|
||||
return tail?.[1] || `prop${index}`;
|
||||
}
|
||||
|
||||
function substituteVueExpressions(markup, contract) {
|
||||
let out = String(markup || '');
|
||||
for (const entry of contract) out = out.split(entry.placeholder).join(`{{ ${entry.prop} }}`);
|
||||
return out;
|
||||
}
|
||||
|
||||
function buildVueVariantStub(variant, markup, contract) {
|
||||
const props = contract.length > 0
|
||||
? `<script setup>\ndefineProps({\n${contract.map((entry) => ` ${entry.prop}: { default: '' },`).join('\n')}\n});\n</script>\n\n`
|
||||
: '';
|
||||
return `${props}<template>\n${markup.trim()}\n</template>\n\n<style scoped>\n/* Variant ${variant}: add scoped CSS here */\n</style>\n`;
|
||||
}
|
||||
|
||||
export function scaffoldVueComponentSession({
|
||||
id,
|
||||
count,
|
||||
sourceFile,
|
||||
sourceStartLine,
|
||||
sourceEndLine,
|
||||
originalLines,
|
||||
cwd = process.cwd(),
|
||||
}) {
|
||||
const runtimeModule = ensureVueRuntime(cwd);
|
||||
const dir = vueComponentSessionDir(id, cwd);
|
||||
fs.mkdirSync(dir, { recursive: true });
|
||||
const originalMarkup = originalLines.join('\n');
|
||||
const propContract = buildVuePropContract(extractVueExpressions(originalMarkup));
|
||||
const previewMarkup = substituteVueExpressions(originalMarkup, propContract);
|
||||
const manifest = {
|
||||
id,
|
||||
previewMode: 'vue-component',
|
||||
framework: 'vue',
|
||||
componentExtension: 'vue',
|
||||
sourceFile: sourceFile.split(path.sep).join('/'),
|
||||
sourceStartLine,
|
||||
sourceEndLine,
|
||||
count,
|
||||
propContract,
|
||||
originalMarkup,
|
||||
componentDir: path.relative(cwd, dir).split(path.sep).join('/'),
|
||||
componentModuleBase: nuxtViteFsModulePath(dir, cwd),
|
||||
runtimeModule,
|
||||
};
|
||||
fs.writeFileSync(path.join(dir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
|
||||
for (let variant = 1; variant <= count; variant++) {
|
||||
const file = path.join(dir, `v${variant}.vue`);
|
||||
if (!fs.existsSync(file)) fs.writeFileSync(file, buildVueVariantStub(variant, previewMarkup, propContract), 'utf-8');
|
||||
}
|
||||
return {
|
||||
manifest,
|
||||
manifestFile: path.relative(cwd, path.join(dir, 'manifest.json')).split(path.sep).join('/'),
|
||||
componentDir: manifest.componentDir,
|
||||
propContract,
|
||||
};
|
||||
}
|
||||
|
||||
export function findVueComponentManifest(id, cwd = process.cwd()) {
|
||||
let direct;
|
||||
try { direct = vueManifestPathForSession(id, cwd); } catch { return null; }
|
||||
if (!fs.existsSync(direct)) return null;
|
||||
try {
|
||||
const manifest = JSON.parse(fs.readFileSync(direct, 'utf-8'));
|
||||
return manifest?.id === id && manifest?.previewMode === 'vue-component'
|
||||
? { ...manifest, manifestPath: direct }
|
||||
: null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function parseVueSfc(source) {
|
||||
const text = String(source || '');
|
||||
const template = text.match(/<template\b[^>]*>([\s\S]*?)<\/template\s*>/i)?.[1]?.trim() || '';
|
||||
const style = text.match(/<style\b[^>]*>([\s\S]*?)<\/style\s*>/i)?.[1]?.trim() || '';
|
||||
return { template, cssLines: style ? style.split('\n').map((line) => line.trimEnd()) : [] };
|
||||
}
|
||||
|
||||
function restoreVueExpressions(markup, contract) {
|
||||
let out = String(markup || '');
|
||||
for (const entry of contract || []) {
|
||||
out = out.replace(new RegExp(`\\{\\{\\s*${escapeRegExp(entry.prop)}\\s*\\}\\}`, 'g'), entry.placeholder);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
export function inlineVueComponentAccept(manifest, variantNum, cwd = process.cwd()) {
|
||||
const sourcePath = resolveInside(cwd, manifest.sourceFile);
|
||||
const componentDir = resolveInside(cwd, manifest.componentDir);
|
||||
const variantPath = componentDir && path.join(componentDir, `v${variantNum}.vue`);
|
||||
const resultBase = {
|
||||
file: manifest.sourceFile,
|
||||
sourceFile: manifest.sourceFile,
|
||||
previewMode: 'vue-component',
|
||||
componentDir: manifest.componentDir,
|
||||
carbonize: false,
|
||||
};
|
||||
if (!sourcePath || !componentDir || !variantPath || !fs.existsSync(sourcePath) || !fs.existsSync(variantPath)) {
|
||||
return { handled: false, error: `Variant ${variantNum} not found`, ...resultBase };
|
||||
}
|
||||
const { template, cssLines } = parseVueSfc(fs.readFileSync(variantPath, 'utf-8'));
|
||||
if (!template) return { handled: false, error: 'Accepted Vue variant has no template', ...resultBase };
|
||||
if (/\bdata-impeccable-[\w-]*\s*=/.test(template)) {
|
||||
return { handled: false, error: 'Accepted Vue variant contains preview-only attributes', ...resultBase };
|
||||
}
|
||||
|
||||
const sourceLines = fs.readFileSync(sourcePath, 'utf-8').split('\n');
|
||||
const start = Number(manifest.sourceStartLine) - 1;
|
||||
const end = Number(manifest.sourceEndLine) - 1;
|
||||
if (!Number.isInteger(start) || !Number.isInteger(end) || start < 0 || end < start || end >= sourceLines.length) {
|
||||
return { handled: false, error: 'Invalid source line range for ' + manifest.sourceFile, ...resultBase };
|
||||
}
|
||||
const indent = sourceLines[start].match(/^(\s*)/)?.[1] || '';
|
||||
const mergedTemplate = mergeOriginalVueAttrs(template, manifest.originalMarkup || '');
|
||||
const markupLines = restoreVueExpressions(mergedTemplate, manifest.propContract)
|
||||
.split('\n')
|
||||
.map((line) => line.trim() ? indent + line.trimStart() : '');
|
||||
let next = [...sourceLines.slice(0, start), ...markupLines, ...sourceLines.slice(end + 1)];
|
||||
const meaningfulCss = cssLines.filter((line) => line.trim() && !/^\/\*\s*Variant \d+:/.test(line.trim()));
|
||||
if (meaningfulCss.length > 0) next = appendVueStyle(next, meaningfulCss);
|
||||
fs.writeFileSync(sourcePath, next.join('\n'), 'utf-8');
|
||||
retireVueComponentSession(manifest.id, cwd);
|
||||
return { handled: true, ...resultBase };
|
||||
}
|
||||
|
||||
function appendVueStyle(lines, cssLines) {
|
||||
let close = -1;
|
||||
for (let index = lines.length - 1; index >= 0; index--) {
|
||||
if (/<\/style\s*>/.test(lines[index])) { close = index; break; }
|
||||
}
|
||||
const block = ['', ...cssLines.map((line) => line.trim() ? ' ' + line.trimStart() : '')];
|
||||
if (close < 0) return [...lines, '', '<style scoped>', ...block.slice(1), '</style>'];
|
||||
return [...lines.slice(0, close), ...block, ...lines.slice(close)];
|
||||
}
|
||||
|
||||
function mergeOriginalVueAttrs(markup, originalMarkup) {
|
||||
const variant = matchOpeningTag(markup);
|
||||
const original = matchOpeningTag(originalMarkup);
|
||||
if (!variant || !original || variant.tag.toLowerCase() !== original.tag.toLowerCase()) return markup;
|
||||
const variantAttrs = parseStaticAttrs(variant.attrs);
|
||||
const originalAttrs = parseStaticAttrs(original.attrs);
|
||||
const additions = [];
|
||||
let attrs = variant.attrs;
|
||||
|
||||
const originalClass = originalAttrs.get('class');
|
||||
const variantClass = variantAttrs.get('class');
|
||||
if (originalClass && variantClass) {
|
||||
const classes = [
|
||||
...variantClass.value.split(/\s+/),
|
||||
...originalClass.value.split(/\s+/),
|
||||
].filter(Boolean);
|
||||
const replacement = `class=${variantClass.quote}${[...new Set(classes)].join(' ')}${variantClass.quote}`;
|
||||
attrs = attrs.slice(0, variantClass.start) + replacement + attrs.slice(variantClass.end);
|
||||
} else if (originalClass) {
|
||||
additions.push(originalClass.raw);
|
||||
}
|
||||
for (const [name, attr] of originalAttrs) {
|
||||
if (name === 'class' || variantAttrs.has(name)) continue;
|
||||
additions.push(attr.raw);
|
||||
}
|
||||
const open = `<${variant.tag}${attrs}${additions.map((attr) => ' ' + attr.trim()).join('')}${variant.close}`;
|
||||
return markup.slice(0, variant.index) + open + markup.slice(variant.index + variant.raw.length);
|
||||
}
|
||||
|
||||
function matchOpeningTag(markup) {
|
||||
const match = String(markup || '').match(/<([A-Za-z][\w:-]*)([^>]*?)(\/?>)/);
|
||||
return match ? {
|
||||
raw: match[0],
|
||||
tag: match[1],
|
||||
attrs: match[2] || '',
|
||||
close: match[3],
|
||||
index: match.index || 0,
|
||||
} : null;
|
||||
}
|
||||
|
||||
function parseStaticAttrs(attrs) {
|
||||
const out = new Map();
|
||||
const re = /([A-Za-z_:][\w:.-]*)\s*=\s*(["'])(.*?)\2/g;
|
||||
let match;
|
||||
while ((match = re.exec(attrs))) {
|
||||
out.set(match[1], {
|
||||
raw: match[0],
|
||||
value: match[3],
|
||||
quote: match[2],
|
||||
start: match.index,
|
||||
end: match.index + match[0].length,
|
||||
});
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
export function removeVueComponentSession(id, cwd = process.cwd()) {
|
||||
try { fs.rmSync(vueComponentSessionDir(id, cwd), { recursive: true, force: true }); } catch { /* best effort */ }
|
||||
}
|
||||
|
||||
/**
|
||||
* Make an accepted/discarded session undiscoverable immediately while keeping
|
||||
* Vue modules that Vite has in its graph alive until Live shuts down. Deleting
|
||||
* an imported SFC mid-session makes Nuxt's HMR client attempt to reload a
|
||||
* missing module and emit a console error. The generated directory remains
|
||||
* ignored and removeAllVueComponentSessions removes it on server shutdown.
|
||||
*/
|
||||
export function retireVueComponentSession(id, cwd = process.cwd()) {
|
||||
let dir;
|
||||
try { dir = vueComponentSessionDir(id, cwd); } catch { return; }
|
||||
for (const name of ['manifest.json', 'params.json']) {
|
||||
try { fs.rmSync(path.join(dir, name), { force: true }); } catch { /* best effort */ }
|
||||
}
|
||||
}
|
||||
|
||||
export function removeAllVueComponentSessions(cwd = process.cwd()) {
|
||||
const project = detectNuxtVueProject(cwd);
|
||||
if (!project) return;
|
||||
const root = path.join(cwd, project.componentRoot);
|
||||
if (!fs.existsSync(root)) return;
|
||||
fs.rmSync(root, { recursive: true, force: true });
|
||||
}
|
||||
|
||||
export function buildVueComponentCssAuthoring(count) {
|
||||
return {
|
||||
mode: 'vue-component',
|
||||
count,
|
||||
requirements: [
|
||||
'Write each variant as a real Vue SFC in componentDir/vN.vue.',
|
||||
'Keep one root element inside <template> and put variant CSS in <style scoped>.',
|
||||
'Keep propContract bindings as {{ propName }} instead of snapshot text.',
|
||||
'Do not add data-impeccable-* attributes.',
|
||||
],
|
||||
forbidden: ['Rewriting sourceFile during preview', 'data-impeccable-* attributes', 'Off-brand replacement content'],
|
||||
};
|
||||
}
|
||||
|
||||
function resolveInside(cwd, value) {
|
||||
if (!value || path.isAbsolute(value)) return null;
|
||||
const full = path.resolve(cwd, value);
|
||||
const rel = path.relative(cwd, full);
|
||||
return !rel || rel.startsWith('..') || path.isAbsolute(rel) ? null : full;
|
||||
}
|
||||
|
||||
function escapeRegExp(value) {
|
||||
return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
||||
}
|
||||
@@ -372,9 +372,6 @@ const SEEDS = [
|
||||
{ id: "seed-133", oklch: [0.500, 0.160, 280.0],
|
||||
mood: "study at blue hour — the considered violet of a room where thinking happens",
|
||||
strategy: "Seed becomes a measured indigo primary on pure white; accent shifts to a cooler blue-violet to create hierarchy without nightclub saturation, letting the brand color do all the emotional work." },
|
||||
{ id: "seed-094", oklch: [0.533, 0.125, 294.3],
|
||||
mood: "twilight atelier violet — calm authority for a working studio, focused and unhurried",
|
||||
strategy: "Pure white canvas lets the indigo-violet primary carry the entire brand voice; accent shifts hue slightly toward blue for a cool, disciplined duotone rather than warm decorative pairing." },
|
||||
{ id: "seed-137", oklch: [0.700, 0.120, 290.0],
|
||||
mood: "violet ink at last light — late-evening focus, the desk of someone who cares about craft",
|
||||
strategy: "Pure black surface lets a single restrained indigo-violet carry the brand, with a cooler periwinkle accent providing hierarchy without competing — lights-off discipline." },
|
||||
@@ -620,9 +617,8 @@ if WCAG says dark technically passes. The Helmholtz-Kohlrausch effect
|
||||
makes saturated colors appear brighter than their luminance suggests,
|
||||
and dark text on a warm-or-cool-saturated fill reads as muddy.
|
||||
|
||||
Convention: Stripe orange CTAs, McDonald's red, every fintech orange
|
||||
button, Vercel's filled badges, Linear's status pills — all use white
|
||||
text on saturated bg fills.
|
||||
Convention: saturated action fills in the wild, from fast-food reds to
|
||||
status pills to filled badges, near-universally carry white text.
|
||||
|
||||
Dark text is correct only on PALE fills (L > 0.85) or PURE-NEUTRAL fills
|
||||
(chroma near 0). Everything else: white text.
|
||||
|
||||
Reference in New Issue
Block a user