pi-agent-browser-native 0.9.3 → 0.9.5

package/docs/CODE_QUALITY.md

@@ -0,0 +1,267 @@
+# Code quality
+
+Oxlint owns maintained-code linting, Oxfmt owns supported formatting, and TypeScript,
+tests, builds, and generated-document checks remain independent gates. Use the pinned
+Node runtime and npm version in `package.json`, then `npm ci --ignore-scripts`.
+
+Correctness, long-term maintainability, and reliable enforcement are equal
+requirements. Keep production complexity, size, readonly, and safety checks even
+when satisfying them requires substantial restructuring. A maintainability finding
+does not need to identify a current runtime bug. Refactors must improve responsibility
+boundaries, explicit ownership, failure/cancellation flow, and localized changes—not
+just move lines, add forwarding layers, or pass a giant mutable context everywhere.
+Use already authorized exceptions when their conditions are demonstrated; further
+relaxations require concrete evidence and explicit approval.
+
+## Commands
+
+| Command                            | Purpose                                                                                                                                                                                                |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `npm run quality`                  | Canonical non-modifying acceptance: clean build, checker preparation, scope/suppression policy, lint, formatting, compiler checks, tests with real-tool probes, and generated-doc/upstream-help checks |
+| `npm run lint`                     | Policy checks followed by strict Oxlint over the complete maintained-code inventory                                                                                                                    |
+| `npm run lint:agent`               | Identical coverage with Oxlint agent diagnostics                                                                                                                                                       |
+| `npm run lint:fix`                 | Identical policy and coverage; apply ordinary safe Oxlint fixes                                                                                                                                        |
+| `npm run format`                   | Format supported maintained files using Oxfmt                                                                                                                                                          |
+| `npm run format:check`             | Check formatting without modifying files                                                                                                                                                               |
+| `npm run quality:policy`           | Validate language coverage and parsed suppression comments; emit the current exception inventory                                                                                                       |
+| `npm run quality:scope -- --write` | Regenerate the final exact unchecked-JavaScript override after an intentional scope/tool change                                                                                                        |
+| `npm run quality:probes`           | Run the focused `node:test` real-CLI regression suite                                                                                                                                                  |
+| `npm run quality:mutations`        | Require clean acceptance, then prove the real workflow rejects syntax, semantic, compiler, formatting, and allowance-isolation mutations in disposable copies                                          |
+
+Review fixes before committing; dangerous fixes and suggestion fixes are not part of
+`lint:fix`. Run formatting after reviewed lint fixes and rerun acceptance. Failures
+are never converted to success by these commands.
+
+### Test scheduling
+
+`npm test` builds once and prepares the corrected checker once, then runs
+`tsx --test "test/**/!(*.serial).test.ts"` with Node's default file concurrency, followed by
+`tsx --test --test-concurrency=1 "test/**/*.serial.test.ts"`.
+The default/quality verification gates use the same two stages. File isolation
+keeps environment patches process-local; the shared browser harness supplies a
+private short socket directory unless `PI_AGENT_BROWSER_SOCKET_DIR` is already set.
+The harness also clears inherited Pi/delegation identity variables; root-default
+tests set their identities explicitly after import. No in-file concurrency is enabled.
+
+The serial lane contains `test/agent-browser.startup.serial.test.ts` and
+`test/agent-browser.prompt-policy.serial.test.ts` for wall-clock budgets, plus
+`test/agent-browser.managed-session-policy-lock.serial.test.ts` for fixtures in
+the shared policy collector directory. Their timing and global-GC contracts must
+not compete with the parallel lane. Build/pack fixtures must use disposable source trees rather
+than rewriting this checkout's `dist/` while other files consume it.
+`platform-target` retains its explicit serial subset; `quality:probes` remains a
+focused serial checker suite. The allowance-isolation mutation must fail in the
+parallel stage with its named `code-quality.test.ts` diagnostic.
+
+## Language and role scope
+
+The root `.oxlintrc.json` enables type-aware rules and compiler diagnostics. The
+canonical `tsconfig.json` includes maintained extension TypeScript, TypeScript
+scripts, tests, and explicitly checked configuration-policy JavaScript; build configuration
+continues to own emitted extension files.
+
+`scripts/code-quality-policy.mjs` discovers maintained code and effective compiler
+projects using the installed TypeScript CLI. It reads inherited settings with
+`tsc --showConfig` and actual project/import membership with `tsc --listFilesOnly`.
+Oxc's parser identifies genuine leading `@ts-check` comments without mistaking
+strings or documentation for directives.
+
+| Source                            | Syntactic lint | Semantic lint | Compiler | Formatting/tests |
+| --------------------------------- | -------------- | ------------- | -------- | ---------------- |
+| TypeScript                        | Yes            | Yes           | Yes      | Yes              |
+| JS with effective `checkJs: true` | Yes            | Yes           | Yes      | Yes              |
+| JS with leading `@ts-check`       | Yes            | Yes           | Yes      | Yes              |
+| Other maintained JS               | Yes            | No            | No       | Yes              |
+
+Unchecked JavaScript is **not ignored**. The final root override lists its exact
+paths and disables only the installed metadata's type-dependent rules plus the
+TypeScript-only module-boundary annotation requirement. It is generated explicitly,
+not dynamically weakened during a lint run. The policy gate rejects drift in files,
+projects, checking directives, metadata, or root lint inventory. Checked files must
+be explicit compiler-project inputs: imported-only checked JS can otherwise fall
+through Oxlint's compiler project assignment. Imported unchecked JS remains available for resolution
+and its TypeScript consumers retain safety checks.
+
+There are no extra lint-only JavaScript semantic opt-ins. Test role and language
+scope are separate: unchecked JS tests keep ordinary lint and test checks without
+accidentally inheriting type-dependent test rules. Production limits are complexity
+10, depth 3, four parameters, 40 statements, 80 nonblank/noncomment function lines,
+and 500 nonblank/noncomment file lines. Tests and verified `test/helpers` use
+complexity 15, depth 4, six parameters, and no size/statement limits. Handwritten
+declarations retain type/API checks without structural metrics.
+
+## Responsibility and ownership changes
+
+The major decompositions preserve the tool surface and lifecycle contracts; they
+separate operations and owners rather than creating a new execution framework.
+
+| Before                                                                                                                                                                                 | After and change locality                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `index.ts` combined registration, prompt caching, command execution, branch replay, and browser/recording/Electron cleanup in one closure.                                             | The entrypoint composes registration. `extension-command-run.ts` makes preparation, durable admission, dispatch, reconciliation, and finish publication explicit. Prompt, artifacts, recording reservations, Electron resources, managed identities, page resources, branch generations, and in-flight code have distinct owners. `BrowserRuntime` is readonly composition, not an exempt mutable bag; leaf helpers receive operations, readonly views, or primitives. |
+| Browser preparation and output mixed input guards, observations, native lifecycle state, artifact handling, and presentation.                                                          | `prepare.ts` orders focused validation and preparation. `process-output.ts` exposes native observation, page observation, lifecycle commit, and publication, with owned stdout-spool cleanup in `finally`. Readonly phase results carry evidence; only the existing command, page, restore, probe, and presentation owners receive exact mutation allowances.                                                                                                          |
+| Presentation assembled diagnostics, artifact verification/images, notices, output compaction, and redaction together.                                                                  | `results/presentation.ts` retains the visible assembly order; diagnostic families and artifact verification, image handling, and compaction live at their respective boundaries. Mutable presentation identity is retained only at assembly operations; successful data still passes through redaction.                                                                                                                                                                |
+| `runtime.ts` combined argv planning, identity/replay, launch compatibility, timeout rules, and credential redaction. Storage conversion combined decoding, streaming, and publication. | Planning remains pre-spawn and filesystem-free, with focused planning/replay/redaction modules and preserved exports. Journal read/replay/projection and legacy conversion are separate responsibilities; conversion still verifies the unchanged source before exclusive separate-copy publication and releases only its owned resources.                                                                                                                             |
+
+Ordering, branch-generation guards, cancellation, append-failure behavior, native
+argument presence, and cleanup ownership remain independent behavioral contracts.
+The real-CLI probes also reject mutable additions to qualified owners and verify
+that ordinary runtime records and parameter-property writes remain checked.
+
+## Corrected checker and allowance integrity
+
+The locked baseline is Oxlint **1.87.0**, `oxlint-tsgolint` **7.0.2003**, Oxfmt
+**0.72.0**, TypeScript **7.0.2**, and `oxc-parser` **0.153.0**. Framework rules use
+`eslint-node-test` **1.0.1** through Oxlint's supported JS-plugin mechanism; ESLint
+is its required runtime API dependency, not another configured lint owner.
+
+The original backend has reproduced file-safe-call origin and readonly
+intersection/container defects. `scripts/prepare-quality-checker.mjs` builds the
+pinned backend revision `eb9339115edde6811ca94c3433adf69ea9852880` and compiler
+submodule `2bd066d87f5bafd315be9f40889d0a60b9e58e0b`, applies
+`patches/oxlint-tsgolint.patch`, and verifies the cached binary's fingerprint/hash.
+It selects Go **1.27.1**. A clean install needs Git, Go, and network access for this
+first build; no manual installed-package edits or install lifecycle hooks are needed.
+
+All semantic lint goes through `scripts/oxlint.mjs`, which forces the verified
+binary through upstream's `OXLINT_TSGOLINT_PATH`. CLI, probes, fixes, and the editor
+must use this same launcher. The checked-in VS Code setting `oxc.path.oxlint` points
+to `./scripts/oxlint.mjs`; the Oxc extension starts `.mjs` launchers with Node.
+Keep Node 24.21.0+ available to the editor. Oxc normally resolves `node` from its
+environment; an editor launched without that PATH can use its user-level
+`oxc.path.node` setting to select the supported executable. Oxc 1.63+ also supports
+`oxc.useExecPath: true` when the editor's bundled Node meets that floor. Do not
+enable it blindly on an editor with an older bundled runtime.
+For another editor, start the language server with `node scripts/oxlint.mjs --lsp`
+using its documented executable mechanism. Do not substitute an independently
+installed global Oxlint or the uncorrected raw backend. Root configuration is shared,
+including JS scope and the actual Node test rules.
+
+Oxlint 1.87's language server reports lint diagnostics but does not expose its CLI
+compiler-diagnostic pass. Keep the editor's native TypeScript/JavaScript validation
+enabled (the workspace settings do so), and retain `npm run typecheck` and the
+canonical CLI as independent compiler gates. A successful lint-server handshake
+does not establish compiler coverage. Oxlint 1.87 also does not merge unsaved
+cross-file editor overlays into a dependent file's semantic project. Save referenced
+files and reanalyze the dependent document; the canonical launcher diagnoses and
+clears cross-module ownership at that save/re-pull boundary. This is an upstream
+limitation shared by the unpatched backend, not a persistent native-checker cache.
+
+`allowForKnownSafePromises` stays empty. The only safe-call registration group is
+the declaration-qualified `node:test` package's `test`, `it`, `describe`, and `suite`.
+Ordinary floating work, local shadows, and unrelated exports/packages retain
+floating-Promise checking. The complete policy also requires owned native `t.test`
+subtests; do not assume a diagnostic came from `no-floating-promises` when it came
+from `node-test/no-unawaited-subtest`. `node-test/no-nested-tests` additionally rejects
+imported test registration inside a test body; use an owned `t.test` subtest instead.
+The repository uses direct imports, not custom registration reexports; requalify
+framework scope before adopting a different registration pattern. Suite callbacks
+receive an exemption only when their value uses establish exclusive native suite
+ownership. Borrowing a native callable or namespace type does not establish native
+value identity. Opaque module loading or native VM code execution withholds that
+claim for exported callbacks, including when module resolution supplies only a
+declaration or external-library target instead of maintained runtime code. The
+Require analysis uses a precise target only for an explicit relative file operand
+whose native resolved path equals the runtime operand; package conditions and
+extension substitution remain opaque. The checker does not interpret code strings
+or promise a runtime security boundary.
+
+Native readonly allowances are declaration-qualified, not shape/name-only. They
+accept the actual native contract, not mutable application additions or runtime
+freezing. Generic `Map`, `Record`, `Readonly`, and callable shapes are not blanket
+allowances. The correction checks native readonly map/set elements recursively
+while preserving mutable-container and mutable-nested-value counterexamples.
+Non-generic TS/JSDoc array aliases retain exact declared identity without introducing
+wrapper types. Built-in browser `URL` and Node's `node:url` `URL` have distinct
+origins; the filesystem `PathLike` contract requires the Node-qualified allowance.
+
+The real-CLI probes are split by contract: `test/code-quality.test.ts` covers
+framework diagnostics and qualified registration isolation;
+`test/code-quality-scope.test.ts` covers language/compiler scope, consumer resolution,
+test-role boundaries, suppression policy, and formatting idempotence;
+`test/code-quality-subtests.test.ts` covers subtest promise ownership and nested
+registration; `test/code-quality-readonly.test.ts` covers declaration isolation and
+mutable additions/intersections. `npm run quality:probes` runs all four files. Probes
+check expected rule identities; setup/configuration/parser failures are not valid
+negative evidence. Keep minimal unsuppressed checker reproductions when upgrading
+the backend and retire the patch only after the same controls pass.
+
+## Semantic exceptions
+
+Native directives must be exact, single-rule `oxlint-disable-next-line` comments
+with a specific adjacent explanation. Supported semantic rules are:
+
+- `no-await-in-loop`: journals, dependency ordering, retries, backpressure, locks,
+  and ordered cleanup.
+- `no-control-regex`: intentionally escaped field/protocol control-character
+  validation.
+- `typescript/no-unnecessary-condition`: necessary live lifecycle checks whose
+  state can change during an awaited operation.
+- `typescript/prefer-readonly-parameter-types`: reproduced plain generic callback
+  false positives, never mutable callable properties.
+- `node-test/no-conditional-assertion`, **only in tests/test helpers**: exhaustive
+  variant validation or independently proven fail-closed narrowing.
+
+An explanation is not semantic proof. Review the actual ownership/ordering/guard
+contract and retain boundary tests, including interrupted and uninterrupted paths.
+Do not suppress floating-Promise protection to compensate for a matcher defect.
+Blanket disables, multi-rule disables, ESLint directives, `@ts-ignore`, and
+`@ts-nocheck` are forbidden. Described `@ts-expect-error` is accepted only in
+dedicated `*.test-d.ts` negative type tests with at least ten explanation characters.
+Unused native disables remain errors.
+
+The policy command prints current paths, locations, rules, and reasons for every
+comment exception. Exact configuration exceptions are reviewable in root config:
+
+`scripts/code-quality-boundaries.mjs` is the canonical inventory of exact local
+declaration and mutation boundaries, including their reasons. `quality:scope -- --write`
+generates their complete rule options immediately before the final JS override;
+overlapping boundaries retain all allowed declarations and the entire strict native
+baseline. Never hand-edit those generated overrides or turn generic maps/sets into
+blanket allowances. The inventory covers diagnostics collectors, next-action
+accumulators, replay fixtures, canonical runtime/resource owners, presentation
+assembly, and the browser-run reducer—not arbitrary input records or read-only views.
+
+Reviewed native-resource readonly exceptions remain single-site directives:
+`browser-journal-projection.ts` receives its native async cursor in `projectJson`;
+`browser-session-conversion-stream.ts` receives native async cursors in `writeBytes`
+and `inject`; `recording-reservations.ts` deliberately mutates its existing index
+only in `applyRecordingArtifactsToReservations` and `retireRecordingReservation`.
+These contracts do not exempt generic `AsyncIterable` or `Map` inputs elsewhere.
+
+The exact site-policy map in `code-quality-policy.mjs` additionally permits only
+the reviewed native `promisify` callback contracts, sanitized secret-error propagation,
+native cancellation reason identity, and the private numeric generation-token
+constructor. Their unused directives remain errors and their actual locations and
+reasons appear in the emitted inventory.
+
+| Scope                                                                                                                                                                                                                            | Exception                                               | Contract/verification                                                                           |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Tests and test-only helpers                                                                                                                                                                                                      | `no-useless-undefined.checkArguments: false`            | Preserve argument presence and negative input fixtures; other rule checks remain active         |
+| `test/agent-browser.tool-surface.test.ts`, `test/verify-package.test.ts`, `test/doctor.test.ts`                                                                                                                                  | Additionally `checkArrowFunctionBody: false`            | Preserve required undefined-returning fixture callbacks                                         |
+| `managed-session-policy-lock.ts`, `browser-execution-claims.ts`, `browser-execution-claim-storage.ts`, `temp-mutation-queue.ts`, `temp-artifact-budget.ts`, `temp-root-ownership.ts`, `temp-root.ts` under the extension library | `checkArrowFunctionBody: false` only                    | Required undefined-returning release/error callbacks; argument checking remains active          |
+| `test/agent-browser.batch-fidelity.test.ts`, `test/agent-browser.native-lifecycle.test.mjs`                                                                                                                                      | `no-await-in-loop: off`                                 | Cohesive inherently ordered native lifecycle suites; original behavior tests retained           |
+| `scripts/verify-recording-native.mjs`, `scripts/verify-agent-browser-dogfood.ts`                                                                                                                                                 | Exact test role, including `checkTypePredicates: false` | Actual nonpackaged assertion harnesses, not production helpers                                  |
+| `tool-surface.ts`, `web-search.ts`, `orchestration/extension-tool-boundary.ts`, `config-validation.js`, `redaction-fields.ts` under the extension library                                                                        | `max-params: 5`                                         | Fixed SDK/public config/regex replacement callback arity; other production limits remain active |
+
+## Formatting, generation, and CI
+
+Oxfmt preserves the repository's tabs, LF endings, semicolons, and existing import
+order. Optional sorting and JSDoc rewriting remain off. The package manager owns
+`package-lock.json`; compiled output and task artifact directories are excluded.
+Generator-owned documentation must converge with Oxfmt through its generator,
+not by hand-editing generated blocks or ignoring maintained documents.
+
+`.github/workflows/code-quality.yml` installs locked dependencies, the selected Go
+toolchain, and the separately installed command-reference upstream target. It runs
+the real acceptance and mutation controls without modifying maintained artifacts.
+The release workflow requires this job before publishing. Existing official/fork
+Pi qualification and lifecycle checks remain separate and are not replaced by
+quality acceptance.
+
+Classify findings accurately: scope/configuration reductions, checker-integrity
+fixes, genuine source improvements, fixture corrections, and production runtime
+bugs are different outcomes. Zero diagnostics is meaningful only with scope,
+suppression, allowance, typecheck, test, build, generation, and formatting gates
+all passing on the exact integrated revision. Major refactors also require review
+of their resulting responsibilities, ownership, API surface, asynchronous phases,
+and before/after change locality. Green checks do not substitute for that review.