Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -712,6 +712,31 @@ structure drift, fixture evals, package dry-run, and high-severity dependency
audit. Use `npm run test:mcp`, `npm run test:source-audit`, and
`npm run test:release-gates` when checking those surfaces directly.

Phase 22 also wires single-name release gates that fold those checks into one
runner (`scripts/release-gates.mjs`):

```bash
npm run gate:all # run every named gate
npm run gate:typecheck # node --check + structure drift
npm run gate:tests # unit + MCP + source-audit + trace-policy
npm run gate:truth-table-fresh # CAPABILITY_TRUTH_TABLE.md ≤ 7 days old
npm run gate:mcp-scope-frozen # only the 2 frozen browser_* tools
npm run gate:no-experimental-in-readme-ready-section
```

The capability/claim truth table for both `agbrowse` and the `cli-jaw` mirror
lives at [`structure/CAPABILITY_TRUTH_TABLE.md`](structure/CAPABILITY_TRUTH_TABLE.md);
update that file in the same commit as any capability or claim change.

Strict-migration baseline checks shipped alongside the gates:

```bash
npm run check:strict-baseline # JSDoc opt-in regression guard
npm run check:module-graph # module dependency graph regression
npm run smoke:bins # published bin entrypoints boot
npm run typecheck # tsc --noEmit on the strict surface
```

For npm trusted publishing through GitHub Actions, configure npm's trusted
publisher for:

Expand Down
1 change: 1 addition & 0 deletions structure/INDEX.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,5 +82,6 @@ graph LR

## 변경 기록

- 2026-05-06: strict-migration P02–P51 + Phase 22 머지 이후 `str_func.md` 스냅샷, `commands.md` root command 표(`new-tab`, `tab-close`), `release_gates.md`의 `gate:*` named release gate 표를 동기화했다. capability/claim 진실은 [CAPABILITY_TRUTH_TABLE.md](CAPABILITY_TRUTH_TABLE.md)에 모았다.
- 2026-05-05: Phase 11+ claim status를 [phase_status.md](phase_status.md)에 분리해 partial/deferred phase가 완료로 오해되지 않게 했다.
- 2026-05-05: `cli-jaw/structure` 패턴을 `agbrowse`에 맞게 축소하지 않고 drift/count 검증 스크립트까지 포함한 source-of-truth 허브로 추가했다.
3 changes: 2 additions & 1 deletion structure/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ aliases: [agbrowse commands, agbrowse CLI 표면, web-ai commands]
| Lifecycle | `start`, `stop`, `status`, `reset` | Chrome CDP lifecycle |
| Observe | `snapshot`, `screenshot`, `text`, `get-dom` | DOM/ref/text/screenshot 관찰 |
| Act | `click`, `type`, `press`, `hover`, `select`, `check`, `uncheck`, `drag`, `mouse-click`, `move-mouse`, `mouse-down`, `mouse-up` | ref 기반 또는 coordinate 기반 mutation |
| Navigate | `navigate`, `reload`, `resize`, `tabs`, `tab-switch`, `select-tab`, `tab-cleanup`, `scroll` | navigation, viewport, tab 관리 |
| Navigate | `navigate`, `reload`, `resize`, `tabs`, `tab-switch`, `select-tab`, `new-tab`, `tab-close`, `tab-cleanup`, `scroll` | navigation, viewport, tab 관리 (multi-tab create/close 포함) |
| Wait | `wait`, `wait-for-selector`, `wait-for-text`, `wait-for` | time, selector, text, legacy ref wait |
| Diagnostics | `console`, `network`, `evaluate` | console/network capture와 explicit unsafe JS evaluation |
| Web AI | `web-ai` | provider workflow subcommand |
Expand Down Expand Up @@ -106,4 +106,5 @@ JSON 모드에서는 실패가 parseable envelope로 나온다. 이 shape는 MCP

## 변경 기록

- 2026-05-06: Phase 9.1 multi-tab의 `new-tab`, `tab-close` 명령을 root command 표에 추가해 README와 일치시켰다.
- 2026-05-05: root CLI, web-ai, MCP tool, provider alias, failure envelope, drift 검사 기준을 source-of-truth 문서로 추가했다.
16 changes: 16 additions & 0 deletions structure/release_gates.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,10 @@ aliases: [agbrowse release gates, agbrowse 릴리즈 게이트, production readi
- [ ] `npm run test:mcp`
- [ ] `npm run test:source-audit`
- [ ] `npm run test:release-gates`
- [ ] `npm run gate:all` (named release gates: typecheck, tests, truth-table-fresh, mcp-scope-frozen, no-experimental-in-readme-ready-section)
- [ ] `node scripts/check-strict-baseline.mjs`
- [ ] `npm run check:module-graph`
- [ ] `npm run smoke:bins`
- [ ] `npm run benchmark:trajectory -- --help`
- [ ] `npm pack --dry-run`
- [ ] `npm publish --dry-run --access public` 또는 preview면 `--tag preview`
Expand All @@ -63,6 +67,17 @@ aliases: [agbrowse release gates, agbrowse 릴리즈 게이트, production readi
| `npm run test:mcp` | MCP protocol/schema/policy tests | Phase 18 ready claim이 실제 tool surface와 일치하는지 확인 |
| `npm run test:source-audit` | answer artifact + source audit tests | Phase 17 research/source claim 차단 |
| `npm run test:release-gates` | structure drift + count checks | Phase status, command, release claim drift 차단 |
| `npm run gate:all` | Phase 22 named release gates (`gate:typecheck`, `gate:tests`, `gate:truth-table-fresh`, `gate:mcp-scope-frozen`, `gate:no-experimental-in-readme-ready-section`) | capability table freshness, frozen MCP scope, README 라벨 일치를 단일 명령으로 검증 |
| `npm run gate:typecheck` | `node --check` + `check-doc-drift.sh` | 공개 .mjs 진입점 syntax + 구조 문서 일치 |
| `npm run gate:tests` | unit + MCP + source-audit + trace-policy 통합 실행 | 핵심 회귀 suite 한 번에 |
| `npm run gate:truth-table-fresh` | `structure/CAPABILITY_TRUTH_TABLE.md` 7일 이내 갱신 또는 코드 ref 일치 | capability claim drift 차단 |
| `npm run gate:mcp-scope-frozen` | MCP `browser_*` tool 등록 범위가 frozen scope (`browser_snapshot`, `browser_click_ref`)에 머무는지 확인 | 미구현 browser MCP tool 노출 차단 |
| `npm run gate:no-experimental-in-readme-ready-section` | README ready 섹션이 external CDP 등 experimental 표면을 광고하지 않는지 검사 | 라벨 drift 차단 |
| `npm run check:strict-baseline` (`node scripts/check-strict-baseline.mjs`) | strict-migration JSDoc opt-in baseline 회귀 차단 | 이미 strict로 옮긴 파일이 다시 untyped로 돌아가지 않게 한다 |
| `npm run check:module-graph` | `scripts/check-module-graph.mjs` 모듈 의존성 그래프 회귀 검사 | leaf/utility layer 경계 보존 |
| `npm run smoke:bins` | published bin entrypoint smoke (`agbrowse`, `agbrowse-vision-click`) | 패키징 후 bin shim이 부팅하는지 확인 |
| `npm run typecheck` / `typecheck:checkjs` / `typecheck:checkjs-dom` | `tsc --noEmit` (root, JSDoc opt-in, DOM-aware JSDoc opt-in) | strict-migration 진행 표면이 깨지지 않는지 확인 |
| `npm run pack:dry` | `npm pack --dry-run --json` | 패키징 manifest 회귀 확인 |
| `npm run benchmark:trajectory` | offline trajectory bundle writer | score가 아니라 sanitized trajectory artifact 생성만 허용 |
| `npm run release` | latest release script | clean tree, install, audit, tests, structure gates, fixture evals, diff check, pack, publish dry-run, tag/publish |
| `npm run release:preview` | preview release script | preview version, audit, tests, structure gates, fixture evals, diff check, pack, publish dry-run, tag/publish |
Expand All @@ -80,5 +95,6 @@ aliases: [agbrowse release gates, agbrowse 릴리즈 게이트, production readi

## 변경 기록

- 2026-05-06: Phase 22 named release gates (`gate:all`, `gate:typecheck`, `gate:tests`, `gate:truth-table-fresh`, `gate:mcp-scope-frozen`, `gate:no-experimental-in-readme-ready-section`)와 strict-baseline / module-graph / bin smoke / pack dry-run 명령을 release path에 추가했다. capability 주장은 [CAPABILITY_TRUTH_TABLE.md](CAPABILITY_TRUTH_TABLE.md)가 단일 source of truth다.
- 2026-05-05: MCP/source-audit/release-gate named scripts를 release path에 추가해 public claim gate가 `npm test` 안에 묻히지 않게 했다.
- 2026-05-05: Phase 21 release gate 요구를 현재 npm scripts, package dry-run, support label 기준으로 정리했다.
70 changes: 38 additions & 32 deletions structure/str_func.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,52 +16,57 @@ aliases: [agbrowse source map, agbrowse str_func, agbrowse 파일 구조]

## 현재 구조 스냅샷

마지막 측정: 2026-05-05.
마지막 측정: 2026-05-06.

| 경로 | 파일 수 | 라인 수 | 역할 |
| --- | ---: | ---: | --- |
| `bin/` | 2 | 6 | published bin wrapper |
| `skills/browser/` | 8 | 3472 | Chrome lifecycle, CDP connection, refs, tabs, diagnostics |
| `skills/vision-click/` | 3 | 680 | screenshot to coordinate click helper |
| `skills/browser/` | 8 | 4116 | Chrome lifecycle, CDP connection, refs, tabs, diagnostics |
| `skills/vision-click/` | 3 | 831 | screenshot to coordinate click helper |
| `skills/web-ai/` | 1 | 365 | bundled agent workflow skill |
| `web-ai/` | 69 | 10899 | provider automation, sessions, MCP, eval, policy, trace |
| `web-ai/context-pack/` | 8 | 583 | file selection, token budget, context rendering |
| `web-ai/eval/` | 5 | 362 | offline provider DOM fixture harness |
| `web-ai/policy/` | 4 | 121 | mutation and content-boundary guardrails |
| `web-ai/trace/` | 4 | 202 | trace ID, redaction, report, writer helpers |
| `scripts/` | 4 | 279 | eval runner and release scripts |
| `test/unit/` | 54 | 5681 | deterministic module tests |
| `test/integration/` | 14 | 1485 | CLI, MCP, policy, provider fixture tests |
| `web-ai/` | 69 | 14783 | provider automation, sessions, MCP, eval, policy, trace |
| `web-ai/context-pack/` | 8 | 802 | file selection, token budget, context rendering |
| `web-ai/eval/` | 5 | 552 | offline provider DOM fixture harness |
| `web-ai/policy/` | 4 | 204 | mutation and content-boundary guardrails |
| `web-ai/trace/` | 4 | 299 | trace ID, redaction, report, writer helpers |
| `scripts/` | 8 | 877 | eval runner, release scripts, named release gates, strict-baseline / module-graph / bin smoke checks |
| `test/unit/` | 55 | 5775 | deterministic module tests |
| `test/integration/` | 15 | 1571 | CLI, MCP, policy, provider fixture tests |
| `test/e2e/` | 1 | 50 | browser smoke coverage |
| `test/spec/` | 2 | 35 | high-level contract specs |
| `docs/` | 5 | 252 | adoption, trace, production-readiness, comparison, benchmark docs |
| `devlog/` | 61 | 13231 | phased plan, research, implementation notes |
| `docs/` | 8 | 1407 | adoption, trace, production-readiness, comparison, benchmark, EXTERNAL_CDP, migration docs |
| `devlog/` | 104 | 16008 | phased plan, research, implementation notes (incl. strict-migration phases) |

`structure/` 자체는 이 문서가 검증 대상으로 삼는 source tree 밖의 문서 허브라서 위 집계에서 제외한다. `verify-counts.sh`는 이 표의 경로별 파일 수와 라인 수를 live source 기준으로 비교한다.

## 주요 파일

| 파일 | 라인 수 | 설명 |
| --- | ---: | --- |
| `skills/browser/browser.mjs` | 2088 | root CLI parser, Chrome lifecycle, browser primitive commands |
| `skills/browser/tab-manager.mjs` | 371 | CDP target list, create, close, switch |
| `skills/browser/tab-lifecycle.mjs` | 191 | idle cleanup, pinned target, duration parsing |
| `skills/browser/skill-install.mjs` | 280 | bundled skill list/get/install |
| `web-ai/cli.mjs` | 1008 | `web-ai` subcommand parser and command orchestration |
| `web-ai/chatgpt.mjs` | 618 | ChatGPT provider send/poll/query/status |
| `web-ai/gemini-live.mjs` | 620 | Gemini provider send/poll/query/status |
| `web-ai/grok-live.mjs` | 487 | Grok provider send/poll/query/status |
| `web-ai/mcp-server.mjs` | 255 | stdio JSON-RPC MCP bridge |
| `web-ai/tool-schema.mjs` | 114 | MCP and AI SDK schema source |
| `web-ai/answer-artifact.mjs` | 86 | provider poll result artifact normalization |
| `web-ai/source-audit.mjs` | 127 | claim/source coverage audit helper |
| `web-ai/ax-snapshot.mjs` | 235 | compact accessibility snapshot and refs |
| `web-ai/self-heal.mjs` | 384 | deterministic target resolution and validation |
| `web-ai/action-intent.mjs` | 66 | serializable semantic action intent contracts |
| `web-ai/target-resolver.mjs` | 32 | explainable target resolver wrapper |
| `scripts/run-web-ai-eval.mjs` | 51 | provider fixture eval CLI wrapper |
| `scripts/release.sh` | 113 | latest release gate and publish script |
| `scripts/release-preview.sh` | 97 | preview release gate and publish script |
| `skills/browser/browser.mjs` | 2341 | root CLI parser, Chrome lifecycle, browser primitive commands |
| `skills/browser/tab-manager.mjs` | 446 | CDP target list, create, close, switch |
| `skills/browser/tab-lifecycle.mjs` | 273 | idle cleanup, pinned target, duration parsing |
| `skills/browser/skill-install.mjs` | 372 | bundled skill list/get/install |
| `web-ai/cli.mjs` | 1151 | `web-ai` subcommand parser and command orchestration |
| `web-ai/chatgpt.mjs` | 709 | ChatGPT provider send/poll/query/status |
| `web-ai/gemini-live.mjs` | 722 | Gemini provider send/poll/query/status |
| `web-ai/grok-live.mjs` | 558 | Grok provider send/poll/query/status |
| `web-ai/mcp-server.mjs` | 321 | stdio JSON-RPC MCP bridge |
| `web-ai/tool-schema.mjs` | 148 | MCP and AI SDK schema source |
| `web-ai/answer-artifact.mjs` | 153 | provider poll result artifact normalization |
| `web-ai/source-audit.mjs` | 183 | claim/source coverage audit helper |
| `web-ai/ax-snapshot.mjs` | 376 | compact accessibility snapshot and refs |
| `web-ai/self-heal.mjs` | 489 | deterministic target resolution and validation |
| `web-ai/action-intent.mjs` | 99 | serializable semantic action intent contracts |
| `web-ai/target-resolver.mjs` | 45 | explainable target resolver wrapper |
| `scripts/run-web-ai-eval.mjs` | 59 | provider fixture eval CLI wrapper |
| `scripts/release.sh` | 116 | latest release gate and publish script |
| `scripts/release-preview.sh` | 100 | preview release gate and publish script |
| `scripts/release-gates.mjs` | 178 | Phase 22 named release gates (`gate:typecheck`, `gate:tests`, `gate:truth-table-fresh`, `gate:mcp-scope-frozen`, `gate:no-experimental-in-readme-ready-section`) |
| `scripts/check-strict-baseline.mjs` | 135 | strict-mode baseline guard for `tsc --noEmit` JSDoc opt-in surface |
| `scripts/check-module-graph.mjs` | 210 | module dependency graph regression check |
| `scripts/smoke-bins.mjs` | 60 | published bin smoke check used in release gate |
| `scripts/render-trace-report.mjs` | 19 | offline trace report renderer |

## Runtime Flow

Expand Down Expand Up @@ -107,4 +112,5 @@ sequenceDiagram

## 변경 기록

- 2026-05-06: 파일 수/라인 수 스냅샷을 strict-migration P02–P51 + Phase 22 머지 이후 기준으로 갱신했고, 새로 추가된 release-gate / strict-baseline / module-graph / bin smoke 스크립트와 EXTERNAL_CDP·migration·traces 문서를 source map에 포함했다.
- 2026-05-05: 현재 repo 기준 파일 수, 라인 수, 주요 runtime flow, cli-jaw mirror 기준을 추가했다.
Loading