The installer is unsigned, so latest.yml is now signed with an Ed25519 key and the app verifies the downloaded installer against it before installing. npm run release -- patch|minor bumps, gates, tags, builds, signs, publishes, re-verifies the public feed and pushes; --resume continues after a failure. The retired GitLab registry publisher is removed.
198 lines
10 KiB
Markdown
198 lines
10 KiB
Markdown
# AGENTS.md — D3RO Voice
|
||
|
||
Operating guide for any AI agent (or human) working in this repository.
|
||
Read this first. It tells you where the infrastructure map lives and what you
|
||
must update when you change the product.
|
||
|
||
---
|
||
|
||
## 1. What this repo is
|
||
|
||
`D3RO Voice` is a multi-platform AI voice assistant monorepo:
|
||
|
||
- `apps/desktop` — Electron desktop app (local-first: SoX + faster-whisper sidecar + Ollama + SQLite)
|
||
- `apps/web` — Next.js cloud console
|
||
- `apps/mobile-rn` — React Native product mobile app (cloud-first; **active**)
|
||
- `apps/api-server` — ASP.NET Core 10 AI proxy + back office backend
|
||
- `apps/admin` — Next.js admin back office
|
||
- `server/supabase` — Postgres + RLS + Auth + Storage + ~27 Deno Edge Functions (canonical product backend)
|
||
- `server/cloudflare-worker` — edge gateway
|
||
- `site/` — landing/marketing/legal site
|
||
- `packages/*` — shared `@d3ro/core`, `ui`, `ui-native`, `i18n`, `api-client`
|
||
|
||
Full detail: [`docs/map/01-system-overview.md`](./docs/map/01-system-overview.md).
|
||
|
||
---
|
||
|
||
## 2. The map — read before you work
|
||
|
||
**`docs/map/` is the authoritative feature & infrastructure map.** Use it to learn
|
||
what infrastructure exists and how far each feature is developed before writing code.
|
||
|
||
Start at [`docs/map/00-index.md`](./docs/map/00-index.md). Key files:
|
||
|
||
| Need | File |
|
||
|---|---|
|
||
| Map index + status legend + how to use | `docs/map/00-index.md` |
|
||
| Product / IA / identity / pipeline | `docs/map/01-system-overview.md` |
|
||
| Repo layout, build, CI/CD, Docker, deploy | `docs/map/02-infrastructure.md` |
|
||
| Shared packages | `docs/map/03-shared-packages.md` |
|
||
| Desktop services/IPC/pages | `docs/map/04-desktop-app.md` |
|
||
| Web routes/components | `docs/map/05-web-app.md` |
|
||
| Mobile screens/features | `docs/map/06-mobile-app.md` |
|
||
| .NET API | `docs/map/07-api-server.md` |
|
||
| Admin console | `docs/map/08-admin-console.md` |
|
||
| Supabase + Cloudflare | `docs/map/09-supabase-backend.md` |
|
||
| **Feature map (per platform, with status)** | `docs/map/10-feature-catalog.md` |
|
||
| **Gaps / backlog / external blockers** | `docs/map/11-gap-backlog.md` |
|
||
| **How to keep the map current** | `docs/map/12-update-protocol.md` |
|
||
|
||
Recommended sequence for a new task:
|
||
1. Read the surface doc for the area you will touch (`04`–`09`).
|
||
2. Find the feature in `10-feature-catalog.md` and check its status per platform.
|
||
3. Check `11-gap-backlog.md` so you do not re-plan tracked work.
|
||
4. Do the work.
|
||
5. Update the map **before** declaring done (see §4).
|
||
|
||
Mobile status is authoritative in `docs/v3/MOBILE_APP_COMPLETION_SSOT.md`; the map
|
||
mirrors and rolls it up. When they disagree, fix the SSOT first, then the map.
|
||
|
||
---
|
||
|
||
## 3. Non-negotiable repo rules
|
||
|
||
These come from [`CLAUDE.md`](./CLAUDE.md) and are enforced here too:
|
||
|
||
- TypeScript strict, no `any`, no `console.log` (use `logger`).
|
||
- Services are singletons + `EventEmitter`. IPC channels are `${feature}:${action}` from the SSOT `packages/core/src/ipc-channels.ts`; wrap errors in `D3ROError`/`ErrorCode` and `IPCResult`.
|
||
- Theme SSOT: only `d3roPalette`/`d3roShadow`/`d3roTypo`/`d3roRadius`; no hardcoded hex outside `theme.ts`.
|
||
- i18n: use `t()`; no hardcoded Korean/English strings in UI.
|
||
- No `Co-Authored-By` or Claude-related wording in commits. Follow the commit format in the shell tool instructions.
|
||
- **Desktop GUI**: do not background-launch Electron from an agent subshell (virtual desktop). Tell the user to run `run-desktop.bat` or an external terminal.
|
||
- **Audio device discovery**: never `execSync` (use async `exec`).
|
||
- **GPU**: keep `app.disableHardwareAcceleration()` and `--disable-gpu`.
|
||
- Desktop: keep `app.setName('d3ro-voice')` + `app.setAppUserModelId` at the top; prevent dev silent exit.
|
||
- Never hardcode secrets; production secrets are injected at build/CI time. Fail closed, never fake success.
|
||
- Security-first: only defensive security work.
|
||
|
||
Build/test commands: [`docs/map/02-infrastructure.md`](./docs/map/02-infrastructure.md) §3. Root: `npm run typecheck`, `npm run test`, `npm run lint`. Mobile: `npm --prefix apps/mobile-rn run lint|typecheck|test`.
|
||
|
||
---
|
||
|
||
## 4. MANDATORY: keep the map updated
|
||
|
||
> **Feature change ⇒ map change, in the same commit / PR.**
|
||
> A feature is not done until the map reflects it.
|
||
|
||
Whenever you **add, remove, change, or defer** a feature, or touch infrastructure,
|
||
you MUST update the map:
|
||
|
||
1. Edit `docs/map/10-feature-catalog.md` (status per surface + notes/anchors).
|
||
2. Edit the relevant surface doc (`04`–`09`) if you changed services, routes, screens, IPC channels, tables, Edge Functions, or build/CI.
|
||
3. Edit `docs/map/11-gap-backlog.md`:
|
||
- resolved gap → `[x]` + date + evidence;
|
||
- newly deferred item → new row + next step;
|
||
- cleared external blocker → `[x]` + evidence.
|
||
4. Reconcile with `docs/v3/MOBILE_APP_COMPLETION_SSOT.md` for mobile changes.
|
||
5. Update `docs/map/02-infrastructure.md` and the `00-index.md` header dates when build/release/CI or the product version changes.
|
||
|
||
Full procedure and templates: [`docs/map/12-update-protocol.md`](./docs/map/12-update-protocol.md).
|
||
|
||
**Status semantics:** `[x]` verified · `[~]` partial/unverified · `[ ]` planned/absent · `[!]` blocked externally · `[-]` N/A. Never mark `[x]` on typecheck alone.
|
||
|
||
---
|
||
|
||
## 5. Definition of done (feature work)
|
||
|
||
- [ ] Code implemented, wired end-to-end (no TODOs / placeholders / fake success).
|
||
- [ ] Tests added/updated and passing; lint/typecheck clean on the touched scope.
|
||
- [ ] Relevant surface doc (`04`–`09`) updated if interfaces changed.
|
||
- [ ] `10-feature-catalog.md` row updated (status per platform + anchors).
|
||
- [ ] `11-gap-backlog.md` updated (closed/opened/external).
|
||
- [ ] Mobile SSOT reconciled if mobile was touched.
|
||
- [ ] No secrets committed; fail-closed preserved.
|
||
|
||
---
|
||
|
||
## 6. Update & release system
|
||
|
||
Desktop auto-update runs `electron-updater` against the **Forgejo feed**
|
||
`https://git.chanpaca.net/api/packages/yunchan/generic/d3ro-voice/latest`.
|
||
The installer is unsigned (no Authenticode yet), so `latest.yml` is signed with an
|
||
**Ed25519 key** and the app verifies the downloaded installer against it before
|
||
installing (`apps/desktop/src/main/update-signature.ts`). The GitLab registry mirror
|
||
was retired in 2026-10. Full evaluation:
|
||
[`docs/deployment/update-system-assessment.md`](./docs/deployment/update-system-assessment.md).
|
||
|
||
**To ship a desktop release, run one command on `main` with a clean tree:**
|
||
|
||
```bash
|
||
npm run release -- patch # fix → 1.9.0 → 1.9.1
|
||
npm run release -- minor # feat → 1.9.0 → 1.10.0
|
||
npm run release -- --resume # continue after a failed build/publish/push
|
||
```
|
||
|
||
It bumps the version, drafts the CHANGELOG section if missing (write it by hand first
|
||
for user-facing notes), runs the gates, commits + tags, builds, signs, publishes,
|
||
re-verifies the public feed, then pushes. Existing installs pick it up on their next
|
||
check (15 s after launch, then every 4 h).
|
||
|
||
These files move together and are enforced by `npm run release:metadata:test`:
|
||
|
||
| Concern | SSOT |
|
||
|---|---|
|
||
| runtime feed + channels | `apps/desktop/src/main/update-feed.ts` |
|
||
| builder publish URL | `apps/desktop/electron-builder.yml` |
|
||
| update policy (channels, min version, force, delta/full, rollout, kill switch) | `release/update-policy.json` |
|
||
| policy runtime logic | `apps/desktop/src/main/update-policy.ts` |
|
||
| one-command release | `scripts/ci/release-desktop.mjs` (`npm run release`) |
|
||
| installer build | `scripts/ci/build-desktop-installer.mjs` |
|
||
| publisher (sign + upload + verify) | `scripts/ci/publish-forgejo-release.mjs` |
|
||
| update signing key | `.env` `D3RO_UPDATE_SIGNING_KEY` (private) · `release/desktop-update-public.pem` == `update-signature.ts` |
|
||
| version SSOT | `release/product-version.json` |
|
||
|
||
Rules:
|
||
|
||
- **Tag-only, immutable releases.** Publish runs only on annotated `vX.Y.Z` tags.
|
||
Tags are never moved or deleted; a bad release is fixed forward with a higher
|
||
patch. Same-version re-release is forbidden by SemVer.
|
||
- **Feed contract.** `UPDATE_FEED_URL` == builder `publish.url` == Forgejo URL.
|
||
The app verifies against the immutable `<version>/latest.yml` + `.sig`, never the
|
||
mutable `latest` alias.
|
||
- **Never rotate or lose the update signing key.** Installs that embed its public key
|
||
reject releases signed by any other key; the only recovery is a manual reinstall.
|
||
Back up `.env`.
|
||
- **Version discipline.** SemVer: `feat`=MINOR, `fix`=PATCH, breaking=MAJOR. Run
|
||
`npm run version:sync` when syncing surfaces; `npm run version:check` must be clean.
|
||
- **Channels.** `latest` (stable), `beta`, `alpha`. Stable clients never receive a
|
||
prerelease unless their channel allows it.
|
||
- **Major vs incremental.** `release/update-policy.json` decides whether an update
|
||
is mandatory (`minimumSupportedVersion`, `forceInstallBelow`) and whether to use a
|
||
full installer instead of a blockmap delta (`fullInstallOnMajorChange`,
|
||
`fullInstallVersionGap`). `stagingPercentage` limits rollout; `killSwitch` stops
|
||
update checks remotely.
|
||
- **Secrets stay fail-closed.** Publishing needs `FORGEJO_TOKEN`
|
||
(`write:package` + `write:repository`) and `D3RO_UPDATE_SIGNING_KEY`; a missing or
|
||
mismatched signing key fails before any upload. `WIN_CSC_*` Authenticode material is
|
||
optional — when present electron-builder also signs the installer.
|
||
- **CI is the backup path.** `.forgejo/workflows/release.yml` runs on the pushed tag
|
||
with the same build/publish scripts and skips when the feed already has the version
|
||
(the normal case after `npm run release`). Sync secrets with `npm run release:secrets`.
|
||
|
||
Other commands: `npm run release -- minor --dry-run`, `npm run release:build`,
|
||
`npm run release:metadata:test`, `npm run release:forgejo:check`.
|
||
|
||
---
|
||
|
||
## 7. Where deeper context lives (optional)
|
||
|
||
- Design (historical desktop architecture): `docs/design/*`
|
||
- Build-out phases: `docs/phases/*`
|
||
- Multi-platform plan: `docs/v2/*`
|
||
- Mobile SSOT + Play package: `docs/v3/*`
|
||
- Monetization: `docs/monetization-plan.md`
|
||
- Deployment/release: `docs/deployment/*`, `release/*`, `scripts/ci/*`
|
||
- Refactor policy + reports: `docs/REFACTOR_POLICY.md`, `docs/REFACTOR_WAVE*_REPORT.md`
|
||
- Project log/handoffs: `memory/*`, `CHANGELOG.md`
|
||
|
||
Treat those as history; treat `docs/map/*` and the code as current.
|