diff --git a/docs/CLI.md b/docs/CLI.md index 63b4915f..70cc2a16 100644 --- a/docs/CLI.md +++ b/docs/CLI.md @@ -518,7 +518,7 @@ Notes: - Raw audit surfaces stay separate: `offers.json` preserves structured offers, `comparison.csv` preserves the tabular comparison with appended currency and total-status audit fields, `meta.json` preserves workflow diagnostics, and `deals-context.json` preserves `query`, report-derived `highlights`, raw `offers`, and `meta` for agent handoff. - `compact` and `context` modes summarize the same report guidance as `deals.md`; `json` mode still returns raw offers and meta. - Expect warnings for stale, inferred, or missing price freshness; unknown or out-of-stock availability; weak query relevance; suspicious titles; duplicate same-title or same-product pressure; workflow alerts; and advisory region handling. -- Treat `--region` as advisory unless `meta.selection.region_authoritative=true`. If `meta.alerts` includes `reasonCode=region_unenforced`, do not present the output as a trustworthy regional comparison. +- Treat `--region` as advisory unless `meta.selection.region_authoritative=true`. If `meta.alerts` includes `reasonCode=region_unenforced`, do not present the output as a trustworthy regional comparison. The alert is emitted only for selected provider diagnostics that did not enforce the requested region; enforced-region diagnostics do not create that warning. - The Market Baseline section is computed only from deterministic same-currency evidence. If sample size or currency coverage is insufficient, the report says `market baseline unavailable` instead of inventing savings. - Seller trust, return policy, warranty, condition, shipping certainty, and price history are not guaranteed fields. Treat them as unavailable unless the raw offer attributes and report text explicitly include them. - When a run returns no final offers, inspect `meta.primaryConstraintSummary` first. @@ -618,7 +618,7 @@ Notes: - Workflow outputs can include typed `nextStepGuidance` with `readiness`, `reasonCode`, `primaryAction`, command examples, `paramsExamples`, `validationChecks`, `fallbackPolicy`, and `doNotProceedIf` blockers. - Harvest outputs separate operational completion, guidance readiness, and product readiness. `success:true` or `ok:true` means the command completed and wrote artifacts; top-level `ready` is product-ready only when `productSuccess=true`, `artifactAuthority=product_ready`, and `evidenceAuthority` is non-diagnostic. `readiness` and `guidanceReadiness` expose the next-step guidance state. - Treat product readiness as the gate between artifact completion and design readiness. Continue to Canvas only when top-level `ready=true`, `productSuccess=true`, `artifactAuthority=product_ready`, ranked references are non-empty, manifest-backed authority evidence exists, and no `doNotProceedIf` condition applies. For canonical Pinterest pin-media harvests, Canvas continuation requires `evidenceAuthority=pin_media_ready` and manifest-backed `pin-media-index.json`; `snapshot_ready` and `motion_ready` are not substitutes for pin-media readiness. -- Pinterest product readiness is pin-media-first: canonical pin URLs become product-ready only when their first-party pin-media artifact is captured, persisted, present in its manifest-backed index, and free of blocking warnings. Screenshot and screencast artifacts can inform diagnostics or motion design, but they do not satisfy required Pinterest pin-media readiness. The exact `login_or_challenge_state` and strict byte-backed `interface_chrome_shell` diagnostics are non-blocking only for trusted first-party manifest-backed pin-media bytes; broader login, challenge, captcha, search-shell, promoted, ad, blank, tiny, or chrome-only blockers still demote readiness unless query-discovered canonical pins also produce complete pin-media authority. Screenshot failure after pin-media success is a non-blocking caveat when pin-media authority is complete. `pin-media-index.json` remains Pinterest authority, `media-analysis.json` remains advisory, and `motion-evidence.json` remains browser replay authority. Multimodal agents reason over those artifacts directly. +- Pinterest product readiness is pin-media-first: canonical pin URLs become product-ready only when their first-party pin-media artifact is captured, persisted, present in its manifest-backed index, and free of blocking warnings. Screenshot and screencast artifacts can inform diagnostics or motion design, but they do not satisfy required Pinterest pin-media readiness. The exact `login_or_challenge_state` and strict byte-backed `interface_chrome_shell` diagnostics are non-blocking only for trusted first-party manifest-backed pin-media bytes; broader login, challenge, captcha, search-shell, promoted, ad, blank, tiny, or chrome-only blockers still demote readiness unless query-discovered canonical pins also produce complete pin-media authority. When pin-media authority is complete, unavailable supplemental viewport screenshot evidence is recorded as skipped and satisfied by pin media, not as product-readiness failure. `pin-media-index.json` remains Pinterest authority, `media-analysis.json` remains advisory, and `motion-evidence.json` remains browser replay authority. Multimodal agents reason over those artifacts directly. - CLI completion text includes `guidanceReadiness= productSuccess=false artifactAuthority= evidenceAuthority=` when guidance readiness exists but product readiness is false. Product-ready runs can still emit `readiness=`. - For `needs_recovery`, `blocked`, or `diagnostic_only`, follow the primary recovery action first. Common blockers are zero references, empty ranked references, failed required screenshot, screencast, or pin-media evidence, provider unavailability, login or challenge screens, and diagnostic-only captures. - The ready follow-through path is explicit: read `advanced-brief.md`, `meta-prompt.md`, `evidence.json`, `ranked-references.json`, `bundle-manifest.json`, `media-analysis.json` when present, and screenshot, screencast, or pin-media evidence first; load `opendevbrowser_skill_load opendevbrowser-best-practices "quick start"`, `opendevbrowser_skill_load opendevbrowser-design-agent "canvas-contract"`, and `opendevbrowser_skill_load opendevbrowser-motion-design "quick start"`; continue only if `canvas-plan.request.json` exists; open a Canvas session; fill the session ids in `canvas-plan.request.json`; run `opendevbrowser canvas --command canvas.plan.set --params-file ./canvas-plan.request.json`; confirm `planStatus=accepted`; then patch only the governance blocks called out by `design-agent-handoff.json`. diff --git a/docs/SURFACE_REFERENCE.md b/docs/SURFACE_REFERENCE.md index 0bb829bc..fe266e7e 100644 --- a/docs/SURFACE_REFERENCE.md +++ b/docs/SURFACE_REFERENCE.md @@ -578,6 +578,7 @@ Auth and policy: - Workflow and macro execute browser options: `research run`, `shopping run`, `product-video run`, `inspiredesign run`, `inspiredesign harvest`, and `macro-resolve --execute` accept `--browser-mode auto|extension|managed`; `extension` reuses relay-backed browser state, while `managed` runs a deterministic managed browser. Workflow `--profile ` selects a named managed profile for provider browser fallback; registry-backed explicit CDP profiles use `cdp-profile start` plus `connect --profile` for browser/session primitives until workflows expose an explicit-CDP transport selector. - Workflow and macro execute cookie options: `research run`, `shopping run`, `product-video run`, `inspiredesign run`, `inspiredesign harvest`, and `macro-resolve --execute` accept `--use-cookies` and `--cookie-policy-override off|auto|required` (`--cookie-policy` alias) so provider macros can require observable cookie-backed browser sessions. - Workflow and macro execute override flags: `research run`, `shopping run`, `product-video run`, `inspiredesign run`, `inspiredesign harvest`, and `macro-resolve --execute` accept `--challenge-automation-mode off|browser|browser_with_helper`, which maps to `challengeAutomationMode` with `run > session > config` precedence. +- Shopping `--region` remains advisory unless workflow output reports `region_authoritative=true`. The `region_unenforced` alert is emitted only for selected provider diagnostics that did not enforce the requested region; enforced-region diagnostics do not create that warning. - Inspiredesign harvest flags: `--query`, repeatable `--provider`, `--max-references 1..10`, and `--visual-evidence off|auto|required`. Harvest requires `--query` or at least one `--url`, keeps the daemon method as `inspiredesign.run`, defaults to `mode=path`, `visualEvidence=required`, and `maxReferences=5`, and keeps explicit `--url` references before discovered references. - Before trusting daemon-backed `inspiredesign harvest` results, run `npx opendevbrowser status --daemon --output-format json` and require `data.fingerprintCurrent === true`; restart or isolate the daemon when it is false or missing. - Inspiredesign harvest supports browser-native site recipes for visually driven sites. `--provider social/pinterest` selects the Pinterest recipe and should use a dedicated managed headed profile with cookies and `--cookie-policy required` for non-Google logged-in search; use extension `/ops` when live active-tab reuse is required. Registry-backed explicit CDP profiles are available for browser/session primitives, but provider workflows do not yet expose an explicit-CDP transport selector. Query-based Pinterest harvests become product-ready only through query-discovered canonical `/pin/{id}/` references plus manifest-backed first-party pin-media bytes; login/challenge and search-shell diagnostics are recovery paths, not product-ready evidence. Compatible Pinterest URL recovery can run as `--provider social/pinterest --url ` without `--query`; use one canonical `/pin/{id}/` URL per harvest when validating design-ready pin media. Generic provider plus URL recovery without query remains rejected. Pinterest is not registered as a default full social provider. @@ -595,7 +596,7 @@ Auth and policy: - Workflow response keys: artifact-bearing workflow success payloads use `artifact_path`; provider follow-up summaries use `meta.primaryConstraintSummary`; typed recovery and handoff payloads use `nextStepGuidance.readiness`, `reasonCode`, `primaryAction`, `paramsExamples`, `validationChecks`, `fallbackPolicy`, and `doNotProceedIf` when available. Inspiredesign harvest also reports product `ready`, `guidanceReady`, `guidanceReadiness`, `productSuccess`, `harvestReadiness`, `readiness`, `rankedReferenceCount`, `evidenceAuthority`, and `artifactAuthority` so wrapper success is not confused with design readiness. Product `ready` is true only when authority gates pass. - `design-contract.json.colorSystem.tokens` and `implementation-plan.json.tokenStrategy.colors` use explicit `{ light, dark }` semantic token maps. `design-agent-handoff.json.implementationContext.tokenStrategy` carries the same dual-mode token strategy for implementation agents. - Continue to Canvas only when top-level `ready=true`, `productSuccess=true`, `artifactAuthority=product_ready`, ranked references are non-empty, no matching `doNotProceedIf` blockers remain active, and manifest-backed authority evidence exists. Strict proof reviews should inspect `evidence.json`, `ranked-references.json`, `pin-media-index.json`, `motion-evidence.json`, `media-analysis.json`, and `bundle-manifest.json` directly before accepting release or Canvas follow-through evidence. For canonical Pinterest pin-media harvests, Canvas continuation requires `evidenceAuthority=pin_media_ready` and manifest-backed `pin-media-index.json`; `snapshot_ready` and `motion_ready` are not substitutes for pin-media readiness. For `needs_recovery`, `blocked`, or `diagnostic_only`, follow recovery-first guidance and do not treat emitted artifacts as design-ready. -- Pinterest product readiness is pin-media-first: canonical pin URLs become product-ready only when their first-party pin-media artifact is captured, persisted, present in its manifest-backed index, and free of blocking warnings. `pin-media-index.json` remains the only pin-media readiness and provenance authority for persisted first-party bytes. Screenshot and screencast artifacts can inform diagnostics or motion design, but they do not satisfy required Pinterest pin-media readiness. The exact `login_or_challenge_state` and strict byte-backed `interface_chrome_shell` diagnostics are non-blocking only for trusted first-party manifest-backed pin-media bytes; broader login, challenge, captcha, search-shell, promoted, ad, blank, tiny, or chrome-only blockers still demote readiness unless query-discovered canonical pins also produce complete pin-media authority. Screenshot failure after pin-media success is a non-blocking caveat when pin-media authority is complete. `media-analysis.json` remains advisory, and `motion-evidence.json` remains browser replay authority. +- Pinterest product readiness is pin-media-first: canonical pin URLs become product-ready only when their first-party pin-media artifact is captured, persisted, present in its manifest-backed index, and free of blocking warnings. `pin-media-index.json` remains the only pin-media readiness and provenance authority for persisted first-party bytes. Screenshot and screencast artifacts can inform diagnostics or motion design, but they do not satisfy required Pinterest pin-media readiness. The exact `login_or_challenge_state` and strict byte-backed `interface_chrome_shell` diagnostics are non-blocking only for trusted first-party manifest-backed pin-media bytes; broader login, challenge, captcha, search-shell, promoted, ad, blank, tiny, or chrome-only blockers still demote readiness unless query-discovered canonical pins also produce complete pin-media authority. When pin-media authority is complete, unavailable supplemental viewport screenshot evidence is recorded as skipped and satisfied by pin media, not as product-readiness failure. `media-analysis.json` remains advisory, and `motion-evidence.json` remains browser replay authority. - Routine workflow bundles should omit output roots and inspect the returned `artifact_path` first. When output roots are omitted, persisted bundles use `.opendevbrowser//` and include `bundle-manifest.json`. CLI invocations resolve omitted roots from cwd before daemon dispatch; direct daemon RPC uses `core.workspaceRoot/.opendevbrowser`; direct OpenCode workflow tools use `deps.workspaceRoot/.opendevbrowser`. If a wrapper must pass an explicit workflow root, prefer `.opendevbrowser`; explicit external output roots remain caller-controlled for intentional temp, release, debug, audit, screenshot, and screencast lanes. - `artifacts cleanup --expired-only` without `--output-dir` targets the current working directory's `.opendevbrowser` root. Use `--output-dir /tmp/opendevbrowser` only when intentionally cleaning an explicit temp artifact root. - Browser evidence omitted outputs use workspace-local artifact roots: screenshots write `.opendevbrowser/screenshot//capture.png` with `path` and `artifact_path`, and screencasts write `.opendevbrowser/screencast/` with replay files. Explicit `--path` and `--output-dir` remain caller-controlled. Browser screenshot, screencast, Canvas, annotation, desktop audit, and release proof outputs are intentional non-bundle lanes, do not promise `bundle-manifest.json`, and are not targets for bundle manifest cleanup. diff --git a/scripts/product-video-fixture-live-probe.mjs b/scripts/product-video-fixture-live-probe.mjs index ec33d46d..8fd05aa7 100644 --- a/scripts/product-video-fixture-live-probe.mjs +++ b/scripts/product-video-fixture-live-probe.mjs @@ -29,6 +29,22 @@ const PNG_BYTES = Buffer.from( "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jX1QAAAAASUVORK5CYII=", "base64" ); +const PRODUCT_VIDEO_PASS_STATUS = "pass"; +const PRODUCT_VIDEO_READINESS_GATES = [ + { file: "manifest.json", path: ["readiness", "presentation", "status"], label: "manifest.readiness.presentation.status" }, + { file: "manifest.json", path: ["readiness", "productVideo", "status"], label: "manifest.readiness.productVideo.status" }, + { file: "presentation-readiness.json", path: ["summary", "status"], label: "presentation-readiness.json.summary.status" }, + { file: "presentation-readiness.json", path: ["presentationReadiness", "status"], label: "presentation-readiness.json.presentationReadiness.status" }, + { file: "presentation-readiness.json", path: ["productVideoReadiness", "status"], label: "presentation-readiness.json.productVideoReadiness.status" }, + { file: "product.json", path: ["presentationReadiness", "status"], label: "product.json.presentationReadiness.status" }, + { file: "product.json", path: ["productVideoReadiness", "status"], label: "product.json.productVideoReadiness.status" } +]; +const PRODUCT_VIDEO_REQUIRED_BUNDLE_FILES = [ + "manifest.json", + "presentation-readiness.json", + "product.json", + "bundle-manifest.json" +]; function parseArgs(argv) { const options = { @@ -65,9 +81,17 @@ function parseArgs(argv) { return options; } -function createProductFixtureServer() { +function resolveFixtureRequestOrigin(request) { + const host = typeof request.headers.host === "string" && request.headers.host.length > 0 + ? request.headers.host + : "127.0.0.1"; + return `http://${host}`; +} + +export function createProductFixtureServer() { return http.createServer((request, response) => { - const url = new URL(request.url ?? "/", "http://127.0.0.1"); + const requestOrigin = resolveFixtureRequestOrigin(request); + const url = new URL(request.url ?? "/", requestOrigin); if (url.pathname.startsWith("/assets/")) { response.writeHead(200, { "content-type": "image/png", @@ -84,12 +108,13 @@ function createProductFixtureServer() { } response.writeHead(200, { "content-type": "text/html; charset=utf-8" }); + const productDescription = "Type Desk Organizer. Connectivity Wireless charging and magnetic cable routing. Widget Pro keeps your desk clear with integrated charging and storage."; response.end(` Widget Pro | Acme Labs - +