generated from coulomb/repo-seed
Complete State Hub bootstrap workplans (WP-0001)
- Review integration files; fill SCOPE where templated - Document dev workflow in stack-and-commands.md - Seed WP-0002 implementation workplan; mark bootstrap finished - Hub sync via fix-consistency
This commit is contained in:
@@ -1,19 +1,7 @@
|
||||
## Architecture
|
||||
|
||||
Chrome MV3 extension; all state in `chrome.storage.local`, nothing relies on
|
||||
in-memory background state surviving service-worker suspension. Full operational
|
||||
boundary is in `SCOPE.md`; inviolable principles in `INTENT.md`.
|
||||
|
||||
**Key modules**
|
||||
- `src/background/service-worker.ts` — MV3 service worker; message router for all popup ↔ background calls; `chrome.alarms` for credential-expiry and queue-cleanup ticks.
|
||||
- `src/utils/pdf-detector.ts` — detect completed PDF downloads (Chrome Downloads API), scan recent downloads, best-effort current-tab detection, re-fetch PDF bytes from the original URL with `credentials: 'include'`.
|
||||
- `src/utils/pdf-queue.ts` — `DocumentProxy` lifecycle queue (`pending → uploading → in_basket → ordering → in_production → sent`, + `failed`/`canceled`); metadata-only (never PDF content); dedup by filename + content hash; live vs. archived views; server sync/reconciliation.
|
||||
- `src/utils/binect-api.ts` — thin wrapper over `@binect/js` (upload, ship, status, list, delete, testConnection) with extension-friendly types and error mapping. **All Binect access delegated 1:1 to the SDK** — no API logic reimplemented here.
|
||||
- `src/utils/crypto.ts` / `storage.ts` — AES-GCM (256-bit) credential encryption at rest via Web Crypto; key in `chrome.storage.local`; decrypted only in memory; 60-day inactivity expiry; manual wipe; self-deleting corrupted ciphertext.
|
||||
- `src/popup/` — login + lifecycle-grouped document list with send/order/refresh/archive/restore/delete actions, badge.
|
||||
- `src/tracking/` — local-only append-only transfer log (~500 cap), summary counts, CSV export, email-draft feedback; tracking/help page.
|
||||
|
||||
**Design invariants** (see `INTENT.md`): zero document retention, explicit user intent for every dispatch (upload ≠ send — ordering is a separate confirmed step), no server-side component, minimal-but-`<all_urls>` host permission (a known Chrome Web Store review cost).
|
||||
<!-- TODO: Describe the key design decisions and component structure.
|
||||
Key modules, data flows, external integrations, state machines, etc. -->
|
||||
|
||||
## Quick Reference
|
||||
|
||||
|
||||
@@ -20,7 +20,7 @@ Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run wa
|
||||
| Agent runtime | How to orient |
|
||||
| --- | --- |
|
||||
| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=binect-chrome` is for coordination, not secret vending |
|
||||
| **Claude Code** (MCP when available) | `get_domain_summary("communication")` for workstreams; **still** use `warden route` for credential ownership |
|
||||
| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workstreams; **still** use `warden route` for credential ownership |
|
||||
| **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` |
|
||||
|
||||
### Quick routing table
|
||||
@@ -47,4 +47,4 @@ Non-credential capabilities are usually discovered through **reuse-surface** fed
|
||||
every repo's agent instructions because it is high-frequency, high-risk, and easy to
|
||||
get wrong.
|
||||
|
||||
**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml`
|
||||
**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml`
|
||||
@@ -17,7 +17,7 @@ roadmap phase. **Wait for approval before creating.**
|
||||
|
||||
**Step 4 — Create workplan file first, then DB record (ADR-001)**
|
||||
```
|
||||
workplans/BCHROME-WP-NNNN-<slug>.md ← write this first
|
||||
workplans/BINECT-CHROME-WP-NNNN-<slug>.md ← write this first
|
||||
```
|
||||
Then register in the hub:
|
||||
```
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
## Repo boundary
|
||||
|
||||
This repo owns **BinectChrome** (the Chrome extension) only. It does not own:
|
||||
This repo owns **BinectChrome** only. It does not own:
|
||||
|
||||
- Binect REST API access / SDK logic → `binect-js` (`@binect/js`). New API coverage belongs upstream there, surfaced through the thin `src/utils/binect-api.ts` wrapper — never reimplemented here.
|
||||
- The Binect backend service itself → external (Binect).
|
||||
- State hub code → `state-hub/`.
|
||||
- Credential issuance / routing → see `credential-routing.md` (ops-warden, OpenBao, etc.).
|
||||
<!-- TODO: List what belongs in adjacent repos, e.g.:
|
||||
- SSH key management → railiance-infra/
|
||||
- State hub code → state-hub/
|
||||
-->
|
||||
|
||||
@@ -1,29 +1,19 @@
|
||||
## Stack
|
||||
|
||||
- **Language:** TypeScript (Chrome Extension, Manifest V3)
|
||||
- **Key deps:** `@binect/js` (local `file:../binect-js` SDK — sibling repo must be present to build); Web Crypto API (AES-GCM credentials); Chrome APIs (`downloads`, `storage`, `alarms`, `activeTab`)
|
||||
- **Build/test tooling:** Webpack, Jest, ESLint, `tsc` (type-check only)
|
||||
<!-- TODO: Fill in language, frameworks, and key dependencies -->
|
||||
- **Language:**
|
||||
- **Key deps:**
|
||||
|
||||
## Dev Commands
|
||||
|
||||
```bash
|
||||
# TODO: Fill in the standard commands for this repo
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Build (production bundle → dist/)
|
||||
npm run build
|
||||
|
||||
# Watch build for development
|
||||
npm run dev
|
||||
|
||||
# Run tests
|
||||
npm test # jest
|
||||
npm run test:watch # jest --watch
|
||||
|
||||
# Lint / type check
|
||||
npm run lint # eslint src/**/*.{js,ts}
|
||||
npm run lint:fix # eslint --fix
|
||||
npm run type-check # tsc --noEmit
|
||||
```
|
||||
|
||||
Load the unpacked extension from `dist/` via `chrome://extensions` (Developer mode) to test in-browser.
|
||||
# Build / package (if applicable)
|
||||
```
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
## Workplan Convention (ADR-001)
|
||||
|
||||
File location: `workplans/BCHROME-WP-NNNN-<slug>.md`
|
||||
ID prefix: `BCHROME-WP-`
|
||||
File location: `workplans/BINECT-CHROME-WP-NNNN-<slug>.md`
|
||||
ID prefix: `BINECT-CHROME-WP-`
|
||||
|
||||
Work items originate as files in this repo **before** being registered in the hub.
|
||||
|
||||
@@ -12,7 +12,7 @@ repo state, and `finished` when implementation is complete. `stalled` and
|
||||
`needs_review` are derived health labels, not stored statuses.
|
||||
|
||||
Closed workplans may be moved to `workplans/archived/` with a completion-date
|
||||
prefix: `YYMMDD-BCHROME-WP-NNNN-<slug>.md`. The frontmatter id remains
|
||||
prefix: `YYMMDD-BINECT-CHROME-WP-NNNN-<slug>.md`. The frontmatter id remains
|
||||
unchanged; the prefix is only for quick visual reference.
|
||||
|
||||
Small opportunistic tasks discovered during another session use **Ad Hoc Tasks**:
|
||||
@@ -28,7 +28,7 @@ the workstream.
|
||||
Task blocks use this shape:
|
||||
|
||||
```task
|
||||
id: BCHROME-WP-NNNN-T01
|
||||
id: BINECT-CHROME-WP-NNNN-T01
|
||||
status: wait | todo | progress | done | cancel
|
||||
priority: high | medium | low
|
||||
state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit
|
||||
|
||||
Reference in New Issue
Block a user