✨🧑‍💻 - Browser extension H1 portable workspace target builds and architecture gates #702

Is there an existing issue or feature request for this?

• I have searched the existing issues and feature requests.

What area does this improvement affect?

New Feature

What actions does this improvement affect?

Issue, Pull Request, Commit

Description of the idea or improvement

Implement H1 — extension engineering foundation, the first dependency-sized increment of the complete product accepted in PR #699. This is not a reduced product or a public release. All 150 capabilities and the 803-case product acceptance floor remain required in the five owning SDDs:

• specs/github-browser-extension.md
• specs/github-browser-extension-functional-catalog.md
• specs/github-browser-extension-platforms-and-delivery.md
• specs/github-browser-extension-action-integration.md
• specs/github-browser-extension-control-center-and-setup.md

Follow specs/README.md and the template. Add specs/github-browser-extension-foundation.md as an engineering companion in the existing github-browser-extension catalog entry; preserve the proposed full-product status and honest distinction between build evidence and actual loaded-browser evidence. No material product decision is open for this increment.

Closed implementation decisions and deliverables

1. Add a private, independently versioned extension pnpm workspace package. Preserve both existing workspace/root dependency overrides, existing Action/CLI/web builds, root coverage gates and root npm package contents. Use locked Node 24/pnpm 10.12.4, TypeScript, Vite and extension-specific Vitest selected/locked against official compatibility documentation.
2. Create the actual domain/application/adapters/infrastructure/presentation boundaries from platforms §8. Introduce src/domain/browser_extension_contract/index.ts as the only permitted root source entrypoint for the extension. Initially export browser-safe repository connection-manifest v1 types and a pure validation function accepting an already-decoded unknown value, conforming exactly to the existing specs/browser-extension/manifest-v1.schema.json and example. Raw JSON duplicate-key parsing, status-v1/request-v2 decoding and producer integration belong to subsequent milestones; do not claim them here.
3. Generate and build three development artifacts, from typed allowlisted target differences: Chrome 140 MV3 module service worker; Firefox 140/ESR MV3 nonpersistent background scripts; Safari 18.2/macOS 15.2 MV3 nonpersistent background scripts. Bundle target-compatible content/background entries; top frame only, isolated static content script on https://github.com/*; required storage only, no optional grants or remote code in this foundation. Optional API/alerts/setup grants are added with the features that require them. No options or toolbar control may point at a nonexistent page.
4. Add a pure URL eligibility guard before any future mount work: exact HTTPS github.com host, no credentials/ports/other origins, exclude protected account/auth/settings/billing/security paths per the owning SDD. The content entry is inert after eligibility; no DOM manipulation, GitHub requests, credential handling, storage writes, observers, automatic operation or product-feature completion claims in H1. Development package identity/version must be explicitly distinct from future store identity; do not reserve or invent published accounts/signing metadata.
5. Enforce import/dependency direction using structured TypeScript AST/import resolution, including negative fixtures: no Node/browser globals in pure code, application imports domain/ports only, no SDK/runtime/deep root imports, no network/mutation/credential authority in presentation, no cycles. Parse generated manifests and inspect built bundles/package contents for forbidden permission/host/remote executable/Node drift. Rebuild into two clean temporary directories and compare deterministic outputs; report target hashes and source revision without secrets.
6. Expose explicit root build/typecheck/test/validate commands for this package and invoke the relevant new gates in CI without removing existing checks. Keep executable source modules at most 220 lines; pure decisions need 100% branches, other new executable modules at least 95% statements/90% branches, with changed executable lines covered. Generated output is ignored and never shipped in the root npm package.
7. Add discoverable contributor documentation covering development build/check commands, target differences, architecture/shared contract, permissions, clean rebuild/recovery and planned versus delivered scope. Update owning SDD/catalog evidence and generated CATALOG together. Document that three-browser loading, real Safari containing-app evidence, lifecycle/settings/connection/UI, store signing/publication and full product acceptance belong to later issues.

Numeric H1 test budget: at least 28 distinct observable cases: 8 connection-manifest value contract cases (valid/disabled/bounds/unknown/duplicate/invalid types and safe IDs), 8 eligibility and target-manifest cases (exact origins/protected paths plus distinct target/background/permission requirements), 6 architecture negative/positive graph cases, 6 build/package/reproducibility/failure-recovery integration cases. A test counts once; browser matrix repetitions do not add cases. Increase this floor to cover all schema boundaries and actual branches. These engineering cases do not replace any of the 803 full-product cases or count as actual browser-loading proof. Root tests, hooks and thresholds remain mandatory.

Acceptance

• A clean locked install builds all three inspectable development artifacts; repeated clean builds are byte-identical and contain only declared packaged assets.
• Invalid repository manifests and ineligible/protected URLs are rejected before any future effect; code import/bundle violations fail automatically with actionable file/target diagnostics.
• Injected invalid manifests, forbidden imports/globals/cycles and package-content drift each fail the corresponding gate; cleanup/retry never leaves a partially advertised target set.
• Root Action/CLI/web behavior and npm package contract remain supported; existing plus new verification gates pass; docs and catalog describe the engineering foundation accurately.
• PR links this issue, records exact verification and remaining product gates, and awaits maintainer review. No merge, deployment, store submission or stable-release authorization is implied.

Current limitations or challenges

PR #699 defines the complete original product but introduces no extension runtime/package. Root workspace configuration currently supplies overrides only. Implementing UI or connected writes before an enforceable portable boundary and reproducible target manifests would make browser parity and privilege separation harder to verify.

Expected impact

Contributors can implement each complete feature family against a tested shared foundation while preserving the existing Action and CLI. Reviewers can inspect three deterministic target artifacts and enforce architectural/security invariants from the first code increment, without confusing build success with actual Safari/Firefox/Chrome product acceptance.

Alternatives considered

A Chrome-only scaffold followed by guessed compatibility, copying an existing extension, importing Node setup/runtime modules into the browser, or weakening existing root gates are rejected. A complete product delivered through dependency-sized reviewable increments follows the already merged SDDs.

Version of copilot

Published Action 3.10.5; implementation baseline develop after PR #699 (b4b06be). Independent private extension development version starts at 0.1.0; it is not a public product release.

Additional context or comments

Part of milestone “GitHub browser extension — complete product”. H1 has no implementation dependency beyond merged #699. Next: runtime/lifecycle/protected sessions plus real browser harnesses, complete center, every catalog family, Action producer/consumer contracts, shared setup presentation/broker and full acceptance. Action owns issue admission, pre-branch SDD and the exact remote ref. Start only this first issue now; other milestones remain backlog.

H1 SDD publication clarification

The first attempt (run 40220870653) failed closed before publishing a draft because its requirement-mapping table format was inconsistent. This clarification changes no product scope. Generate the companion using the existing canonical src/domain/sdd_draft_consistency.ts contract, not a four/five-column legacy traceability table. In the generated SDD §4 use exactly Requirement | Behavior; §14 use exactly Area | Minimum distinct cases | Behaviors/risks covered and Case ID | Area | Requirements | Scenario; §17 use exactly Requirement | Cases; §15 use exactly Path | Change. Keep architecture/docs traceability in adjacent prose or another differently headed table. Do not wrap these canonical tables in code fences.

For the 28-case minimum, use four closed requirements: BEXH1-CONTRACT (8 cases), BEXH1-TARGET (8 cases), BEXH1-BOUNDARY (6 cases), BEXH1-PACKAGE (6 cases). Use fully qualified unique IDs bexh1-foundation-C01 through bexh1-foundation-C28, expanded literally once per row; §17 must list every exact ID with comma separators and identical reverse links to §14. No ranges, shorthand, undefined requirements, generic documentation-only case or retained-case redefinition in the candidate. Add more fully defined distinct cases if required by a genuine risk. The existing 803 full-product cases are retained baseline references, not this new inventory.

Every repository path in the draft must exist at the immutable base or be explicitly listed as create in §15. Use update/reference for existing package/workspace/lock/CI/spec/catalog/nav files, create for the companion and new extension/shared-domain/test/doc files. Do not invent current files or cite nonexistent proposed directory/package paths as retained evidence. Finalize exact paths against the repository inventory. A failed candidate does not authorize a manual replacement branch or weaker validation; retry this same managed issue after producing a valid candidate.

H1 literal acceptance inventory

Use these literal new case rows and exact reverse links in the generated candidate. The selected owning documents and their baseline case IDs remain unchanged; do not copy their retained inventory into the new-candidate table. These are engineering cases only.

H1 explicit repository-path inventory

Run 40220871269 passed the earlier table checks and failed closed on repository-path validation (reference 43a62e61-928b-41fe-b9c6-7573ef04778e). For the next candidate, use the following exact file inventory for §15. It was checked against develop after merged #699. Select the requested new foundation companion, classified create. Preserve the existing five owner SDDs as the accepted complete-product baseline. These are planned change classifications, not claims that the files already exist or are implemented.

Important: the path checker accepts exact current/proposed files, not a reference to a missing parent directory inferred from a proposed child file. Outside fenced architecture trees, cite only exact files below. Do not add bare future directory paths, glob paths, invented filenames or a parent-directory create row alongside child-file rows. Describe layers in words. Any genuinely needed additional new file must have its own exact create row after checking the immutable inventory. Optional future package/feature paths belong to later milestones, not retained current evidence.