feat(verify): fixture-based value validation + skill docs for COOKIE pitfalls

[jackwener]

Summary

Addresses the three P0/P1 items from the 1point3acres adapter retro:

Runtime — opencli browser verify now validates values, not just "ran":

• Reads ~/.opencli/sites/<site>/verify/<cmd>.json when present and checks row count / columns / types / patterns / notEmpty against live adapter output.
• New flags --write-fixture / --update-fixture / --no-fixture.
• Backward-compatible: no fixture ⇒ same behavior as today (runs the adapter, prints the output, exits 0 on success).

$ opencli browser verify 1point3acres/hot
  → 3 rows

  ✗ Adapter output does not match fixture:
    - [pattern] row[0] "url"="https://…thread-..." does not match /^https://EXPECTED-BOGUS-HOST//

Skill — opencli-adapter-author captures the gotchas that bit me writing the 1p3a COOKIE adapters:

• adapter-template.md — new "COOKIE adapter 骨架" section:
  • Dual-domain page.getCookies({ domain: '.x' }) + ({ domain: 'www.x' }) merge, so HttpOnly auth cookies on the root domain don't silently drop
  • Why Node-side fetch(url, { headers: { Cookie } }) + TextDecoder('gbk') is the right shape for HTML / non-UTF-8 / navigateBefore: false adapters (vs page.evaluate(fetch(...)), which blows up with "Failed to fetch" under cross-origin or GBK)
  • Empty-state sentinel row over return []
• api-discovery.md §4 — note that Discuz/phpBB/vBulletin engines set auth on the root domain, so a single-domain getCookies call comes up empty
• SKILL.md runbook — Step 10 folds --write-fixture into the adapter-author loop; Step 12 adds the verify/<cmd>.json deliverable and forbids .dbg-* / raw HTML dumps in the repo tree

Fixture schema

{
  "args": { "limit": 3 },
  "expect": {
    "rowCount": { "min": 1, "max": 3 },
    "columns": ["rank", "tid", "title", "url"],
    "types":   { "rank": "number", "tid": "string|number", "url": "string" },
    "patterns": { "url": "^https://www\\\\.example\\\\.com/" },
    "notEmpty": ["title", "url"]
  }
}

• types supports unions ("number|string") and "any" wildcard
• patterns skip null/undefined values so optional fields don't false-positive
• Derived fixtures from --write-fixture omit patterns/notEmpty — author hand-tunes

Test plan

• npx vitest run src/ — 58 files / 820 passed / 2 skipped (same as main + new tests across verify-fixture.test.ts and cli.test.ts)
• npx tsc --noEmit clean
• opencli browser verify 1point3acres/hot — no fixture → prints rows + hint
• --write-fixture → seeds ~/.opencli/sites/1point3acres/verify/hot.json with derived schema
• Hand-tune patterns + notEmpty → re-verify → ✓ matches fixture
• Flip pattern to wrong host → exit 1 + per-row failure list
• --no-fixture → bypasses validation even when fixture exists
• --write-fixture with existing fixture → no-op with hint to use --update-fixture

Non-goals

• Exact-value equality match (BBS / market / news data is too volatile — shape-based checks catch the bugs that actually ship).
• Recording HTTP request/response fixtures for offline replay (covered separately by ~/.opencli/sites/<site>/fixtures/<cmd>-<timestamp>.json, existing convention).