opendevbrowser 0.0.15 → 0.0.17

package/skills/opendevbrowser-best-practices/assets/templates/canvas-handshake-example.json

@@ -0,0 +1,126 @@
+{
+  "canvasSessionId": "canvas_session_01",
+  "browserSessionId": "browser_session_01",
+  "documentId": "dc_01",
+  "leaseId": "lease_01",
+  "preflightState": "handshake_read",
+  "attachModes": [
+    "observer",
+    "lease_reclaim"
+  ],
+  "governanceRequirements": {
+    "requiredBeforeMutation": [
+      "intent",
+      "generationPlan",
+      "designLanguage",
+      "contentModel",
+      "layoutSystem",
+      "typographySystem",
+      "motionSystem",
+      "responsiveSystem",
+      "accessibilityPolicy"
+    ],
+    "requiredBeforeSave": [
+      "intent",
+      "generationPlan",
+      "designLanguage",
+      "contentModel",
+      "layoutSystem",
+      "typographySystem",
+      "colorSystem",
+      "surfaceSystem",
+      "iconSystem",
+      "motionSystem",
+      "responsiveSystem",
+      "accessibilityPolicy",
+      "libraryPolicy",
+      "runtimeBudgets"
+    ],
+    "optionalInherited": [
+      "colorSystem",
+      "surfaceSystem",
+      "iconSystem",
+      "libraryPolicy",
+      "runtimeBudgets"
+    ]
+  },
+  "generationPlanRequirements": {
+    "requiredBeforeMutation": [
+      "targetOutcome",
+      "visualDirection",
+      "layoutStrategy",
+      "contentStrategy",
+      "componentStrategy",
+      "motionPosture",
+      "responsivePosture",
+      "accessibilityPosture",
+      "validationTargets"
+    ]
+  },
+  "allowedLibraries": {
+    "icons": [
+      "3dicons",
+      "tabler",
+      "microsoft-fluent-ui-system-icons",
+      "@lobehub/fluent-emoji-3d"
+    ],
+    "components": [
+      "shadcn"
+    ],
+    "styling": [
+      "tailwindcss"
+    ],
+    "motion": [],
+    "threeD": []
+  },
+  "warningAuditIds": [
+    "CANVAS-01",
+    "CANVAS-02",
+    "CANVAS-03",
+    "CANVAS-04",
+    "CANVAS-05",
+    "CANVAS-06",
+    "CANVAS-07"
+  ],
+  "allowedBeforePlan": [
+    "canvas.capabilities.get",
+    "canvas.plan.get",
+    "canvas.plan.set",
+    "canvas.document.load",
+    "canvas.session.attach",
+    "canvas.session.status"
+  ],
+  "projectionModes": [
+    "canvas_html",
+    "bound_app_runtime"
+  ],
+  "annotationDispatch": {
+    "popupAndCanvasSend": "storage_backed_retrieval",
+    "retrievalCommand": "annotate --stored"
+  },
+  "documentContext": {
+    "status": "existing",
+    "existingGovernanceBlocks": [
+      "colorSystem",
+      "surfaceSystem",
+      "iconSystem",
+      "libraryPolicy",
+      "runtimeBudgets"
+    ],
+    "missingGovernanceBlocks": [
+      "intent",
+      "generationPlan",
+      "designLanguage",
+      "contentModel",
+      "layoutSystem",
+      "typographySystem",
+      "motionSystem",
+      "responsiveSystem",
+      "accessibilityPolicy"
+    ],
+    "tokensPresent": true,
+    "themesPresent": true,
+    "viewportsPresent": true,
+    "componentInventoryPresent": false
+  }
+}

package/skills/opendevbrowser-best-practices/assets/templates/cdp-forward-envelope.json

@@ -0,0 +1,11 @@
+{
+  "id": 1,
+  "method": "forwardCDPCommand",
+  "params": {
+    "method": "Runtime.evaluate",
+    "params": {
+      "expression": "document.title"
+    },
+    "sessionId": "optional-flat-session-id"
+  }
+}

package/skills/opendevbrowser-best-practices/assets/templates/mode-flag-matrix.json

@@ -0,0 +1,56 @@
+{
+  "schemaVersion": "1.0",
+  "modes": [
+    {
+      "name": "managed",
+      "launch": "npx opendevbrowser launch --no-extension",
+      "statusProbe": "npx opendevbrowser status --session-id <session-id>",
+      "requiredFlags": [
+        "--no-extension"
+      ],
+      "statusExpectations": {
+        "mode": "managed"
+      }
+    },
+    {
+      "name": "extension",
+      "launch": "npx opendevbrowser launch --extension-only --wait-for-extension",
+      "statusProbe": "npx opendevbrowser status --daemon",
+      "requiredFlags": [
+        "--extension-only",
+        "--wait-for-extension"
+      ],
+      "statusExpectations": {
+        "extensionConnected": true,
+        "extensionHandshakeComplete": true,
+        "opsConnected": true
+      }
+    },
+    {
+      "name": "extension-legacy",
+      "launch": "npx opendevbrowser launch --extension-only --extension-legacy --wait-for-extension",
+      "statusProbe": "npx opendevbrowser status --daemon",
+      "requiredFlags": [
+        "--extension-only",
+        "--extension-legacy",
+        "--wait-for-extension"
+      ],
+      "statusExpectations": {
+        "extensionConnected": true,
+        "extensionHandshakeComplete": true,
+        "cdpConnected": true
+      }
+    },
+    {
+      "name": "cdpConnect",
+      "connect": "npx opendevbrowser connect --ws-endpoint ws://127.0.0.1:9222/devtools/browser/<id>",
+      "statusProbe": "npx opendevbrowser status --session-id <session-id>",
+      "requiredFlags": [
+        "--ws-endpoint"
+      ],
+      "statusExpectations": {
+        "mode": "cdpConnect"
+      }
+    }
+  ]
+}

package/skills/opendevbrowser-best-practices/assets/templates/ops-request-envelope.json

@@ -0,0 +1,9 @@
+{
+  "type": "ops_request",
+  "requestId": "req-session-status-001",
+  "clientId": "ops-client-1",
+  "opsSessionId": "ops-session-123",
+  "leaseId": "lease-123",
+  "command": "session.status",
+  "payload": {}
+}

package/skills/opendevbrowser-best-practices/assets/templates/robustness-checklist.json

@@ -0,0 +1,136 @@
+{
+  "schemaVersion": "1.0",
+  "skill": "",
+  "run_id": "",
+  "canvas": {
+    "enabled": false,
+    "canvasSessionId": "",
+    "documentId": "",
+    "targetIds": [],
+    "issueClasses": [
+      {
+        "auditId": "CANVAS-01",
+        "status": "pending",
+        "command": "canvas.document.patch",
+        "evidence": [],
+        "notes": ""
+      },
+      {
+        "auditId": "CANVAS-02",
+        "status": "pending",
+        "command": "canvas.document.save",
+        "evidence": [],
+        "notes": ""
+      },
+      {
+        "auditId": "CANVAS-03",
+        "status": "pending",
+        "command": "canvas.plan.set",
+        "evidence": [],
+        "notes": ""
+      },
+      {
+        "auditId": "CANVAS-04",
+        "status": "pending",
+        "command": "canvas.document.patch",
+        "evidence": [],
+        "notes": ""
+      },
+      {
+        "auditId": "CANVAS-05",
+        "status": "pending",
+        "command": "canvas.overlay.mount",
+        "evidence": [],
+        "notes": ""
+      },
+      {
+        "auditId": "CANVAS-06",
+        "status": "pending",
+        "command": "canvas.preview.render",
+        "evidence": [],
+        "notes": ""
+      },
+      {
+        "auditId": "CANVAS-07",
+        "status": "pending",
+        "command": "canvas.feedback.poll",
+        "evidence": [],
+        "notes": ""
+      }
+    ]
+  },
+  "issues": [
+    {
+      "id": "ISSUE-01",
+      "status": "pending",
+      "evidence": [],
+      "notes": ""
+    },
+    {
+      "id": "ISSUE-02",
+      "status": "pending",
+      "evidence": [],
+      "notes": ""
+    },
+    {
+      "id": "ISSUE-03",
+      "status": "pending",
+      "evidence": [],
+      "notes": ""
+    },
+    {
+      "id": "ISSUE-04",
+      "status": "pending",
+      "evidence": [],
+      "notes": ""
+    },
+    {
+      "id": "ISSUE-05",
+      "status": "pending",
+      "evidence": [],
+      "notes": ""
+    },
+    {
+      "id": "ISSUE-06",
+      "status": "pending",
+      "evidence": [],
+      "notes": ""
+    },
+    {
+      "id": "ISSUE-07",
+      "status": "pending",
+      "evidence": [],
+      "notes": ""
+    },
+    {
+      "id": "ISSUE-08",
+      "status": "pending",
+      "evidence": [],
+      "notes": ""
+    },
+    {
+      "id": "ISSUE-09",
+      "status": "pending",
+      "evidence": [],
+      "notes": ""
+    },
+    {
+      "id": "ISSUE-10",
+      "status": "pending",
+      "evidence": [],
+      "notes": ""
+    },
+    {
+      "id": "ISSUE-11",
+      "status": "pending",
+      "evidence": [],
+      "notes": ""
+    },
+    {
+      "id": "ISSUE-12",
+      "status": "pending",
+      "evidence": [],
+      "notes": ""
+    }
+  ]
+}

package/skills/opendevbrowser-best-practices/assets/templates/surface-audit-checklist.json

@@ -0,0 +1,28 @@
+{
+  "schemaVersion": "1.0",
+  "expectedCounts": {
+    "cliCommands": 56,
+    "tools": 49,
+    "opsCommands": 38,
+    "canvasCommands": 26
+  },
+  "docsMustCover": [
+    "README.md",
+    "docs/CLI.md",
+    "docs/ARCHITECTURE.md",
+    "docs/SURFACE_REFERENCE.md",
+    "AGENTS.md",
+    "skills/opendevbrowser-best-practices/SKILL.md"
+  ],
+  "checks": [
+    "CLI command names documented by category",
+    "Tool names documented by category",
+    "Ops command namespaces documented",
+    "Canvas command names documented",
+    "Canvas code-sync surface documented",
+    "Annotation send/copy semantics documented",
+    "CDP envelope contract documented",
+    "Global and command-specific flags documented",
+    "Mode semantics documented"
+  ]
+}

package/skills/opendevbrowser-best-practices/scripts/odb-workflow.sh

@@ -0,0 +1,170 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+print_help() {
+  cat <<'EOF'
+OpenDevBrowser workflow router
+
+Usage:
+  ./skills/opendevbrowser-best-practices/scripts/odb-workflow.sh <workflow>
+
+Workflows:
+  provider-search
+  provider-crawl
+  parallel-multipage-safe
+  qa-debug
+  social-readonly-check
+  canvas-preflight
+  canvas-feedback-eval
+  parity-check
+  surface-audit
+  ops-channel-check
+  cdp-channel-check
+  mode-flag-matrix
+  robustness-audit
+  list
+EOF
+}
+
+workflow="${1:-list}"
+
+case "$workflow" in
+  list)
+    print_help
+    ;;
+  provider-search)
+    cat <<'EOF'
+opendevbrowser_launch noExtension=true
+opendevbrowser_goto sessionId="<session-id>" url="<provider-search-url>"
+opendevbrowser_wait sessionId="<session-id>" until="networkidle"
+opendevbrowser_snapshot sessionId="<session-id>" format="actionables"
+opendevbrowser_network_poll sessionId="<session-id>" max=50
+EOF
+    ;;
+  provider-crawl)
+    cat <<'EOF'
+opendevbrowser_launch noExtension=true
+opendevbrowser_goto sessionId="<session-id>" url="<seed-url>"
+opendevbrowser_wait sessionId="<session-id>" until="networkidle"
+opendevbrowser_snapshot sessionId="<session-id>" format="actionables"
+opendevbrowser_scroll sessionId="<session-id>" dy=1000
+opendevbrowser_wait sessionId="<session-id>" until="networkidle"
+EOF
+    ;;
+  parallel-multipage-safe)
+    cat <<'EOF'
+# Reliable parallel pattern (as-is):
+# - Worker A owns session-a
+# - Worker B owns session-b
+# - Keep each session serial (snapshot -> action -> snapshot)
+# - Do NOT interleave independent target-use streams in one session
+# - Managed + persisted profiles: use unique profile paths per session
+
+opendevbrowser_launch noExtension=true
+opendevbrowser_launch noExtension=true
+
+# Worker A loop
+opendevbrowser_goto sessionId="<session-a>" url="<url-a1>"
+opendevbrowser_wait sessionId="<session-a>" until="networkidle"
+opendevbrowser_snapshot sessionId="<session-a>" format="actionables"
+
+# Worker B loop
+opendevbrowser_goto sessionId="<session-b>" url="<url-b1>"
+opendevbrowser_wait sessionId="<session-b>" until="networkidle"
+opendevbrowser_snapshot sessionId="<session-b>" format="actionables"
+EOF
+    ;;
+  qa-debug)
+    cat <<'EOF'
+opendevbrowser_snapshot sessionId="<session-id>" format="outline"
+opendevbrowser_console_poll sessionId="<session-id>" max=100
+opendevbrowser_network_poll sessionId="<session-id>" max=100
+opendevbrowser_screenshot sessionId="<session-id>"
+EOF
+    ;;
+  social-readonly-check)
+    cat <<'EOF'
+# Read-only social validation (default, no posting).
+opendevbrowser_snapshot sessionId="<session-id>" format="actionables"
+opendevbrowser_debug_trace_snapshot sessionId="<session-id>" maxEvents=50
+opendevbrowser_network_poll sessionId="<session-id>" max=100
+EOF
+    ;;
+  canvas-preflight)
+    cat <<'EOF'
+cat skills/opendevbrowser-best-practices/assets/templates/canvas-handshake-example.json
+cat skills/opendevbrowser-best-practices/assets/templates/canvas-generation-plan.v1.json
+npx opendevbrowser canvas --command canvas.session.open --params '{"requestId":"req_open_01","browserSessionId":"<browser-session-id>","documentId":null,"repoPath":null,"mode":"dual-track"}'
+# Read handshake before any mutation. Require preflightState=handshake_read.
+npx opendevbrowser canvas --command canvas.plan.set --params-file skills/opendevbrowser-best-practices/assets/templates/canvas-generation-plan.v1.json
+# Replace placeholders in the plan file with canvasSessionId, leaseId, and documentId from the open response.
+npx opendevbrowser canvas --command canvas.plan.get --params '{"requestId":"req_plan_get_01","canvasSessionId":"<canvas-session-id>","leaseId":"<lease-id>","documentId":"<document-id>"}'
+# Require planStatus=accepted or preflightState=plan_accepted before canvas.document.patch.
+EOF
+    ;;
+  canvas-feedback-eval)
+    cat <<'EOF'
+cat skills/opendevbrowser-best-practices/artifacts/canvas-governance-playbook.md
+cat skills/opendevbrowser-best-practices/assets/templates/canvas-feedback-eval.json
+cat skills/opendevbrowser-best-practices/assets/templates/canvas-blocker-checklist.json
+npx opendevbrowser canvas --command canvas.feedback.poll --params '{"requestId":"req_feedback_01","canvasSessionId":"<canvas-session-id>","documentId":"<document-id>","targetId":"<target-id>","afterCursor":null}'
+# Verify every feedback item is target-attributed and uses approved categories.
+npx opendevbrowser canvas --command canvas.preview.refresh --params '{"requestId":"req_refresh_01","canvasSessionId":"<canvas-session-id>","leaseId":"<lease-id>","targetId":"<target-id>","refreshMode":"full"}'
+npx opendevbrowser canvas --command canvas.document.save --params '{"requestId":"req_save_01","canvasSessionId":"<canvas-session-id>","leaseId":"<lease-id>","documentId":"<document-id>","repoPath":null}'
+# Save should fail or warn when requiredBeforeSave governance blocks remain unresolved.
+EOF
+    ;;
+  parity-check)
+    cat <<'EOF'
+npm run test -- tests/parity-matrix.test.ts
+npm run test -- tests/tools.test.ts tests/daemon-commands.integration.test.ts
+./skills/opendevbrowser-best-practices/scripts/validate-skill-assets.sh
+EOF
+    ;;
+  surface-audit)
+    cat <<'EOF'
+cat docs/SURFACE_REFERENCE.md
+cat skills/opendevbrowser-best-practices/artifacts/command-channel-reference.md
+cat skills/opendevbrowser-best-practices/assets/templates/surface-audit-checklist.json
+./skills/opendevbrowser-best-practices/scripts/validate-skill-assets.sh
+EOF
+    ;;
+  ops-channel-check)
+    cat <<'EOF'
+npx opendevbrowser serve
+npx opendevbrowser launch --extension-only --wait-for-extension --output-format json
+npx opendevbrowser status --daemon --output-format json
+# Verify opsConnected=true and extensionHandshakeComplete=true
+cat skills/opendevbrowser-best-practices/assets/templates/ops-request-envelope.json
+EOF
+    ;;
+  cdp-channel-check)
+    cat <<'EOF'
+npx opendevbrowser serve
+npx opendevbrowser launch --extension-only --extension-legacy --wait-for-extension --output-format json
+npx opendevbrowser status --daemon --output-format json
+# Verify cdpConnected=true while legacy session is active
+cat skills/opendevbrowser-best-practices/assets/templates/cdp-forward-envelope.json
+EOF
+    ;;
+  mode-flag-matrix)
+    cat <<'EOF'
+cat skills/opendevbrowser-best-practices/assets/templates/mode-flag-matrix.json
+npx opendevbrowser launch --no-extension --output-format json
+npx opendevbrowser launch --extension-only --wait-for-extension --output-format json
+npx opendevbrowser launch --extension-only --extension-legacy --wait-for-extension --output-format json
+EOF
+    ;;
+  robustness-audit)
+    cat <<'EOF'
+cat skills/opendevbrowser-best-practices/artifacts/browser-agent-known-issues-matrix.md
+cat skills/opendevbrowser-best-practices/assets/templates/robustness-checklist.json
+./skills/opendevbrowser-best-practices/scripts/run-robustness-audit.sh
+EOF
+    ;;
+  *)
+    echo "Unknown workflow: $workflow" >&2
+    print_help
+    exit 2
+    ;;
+esac