Multi-Agent Collaboration for Team and Friends
Contributing to Alook
Thanks for your interest in contributing to Alook. This guide covers everything you need to get started.
Android release and Play draft upload
Mobile Release keeps the mobile-version marker trigger and existing iOS upload path. Android builds signed APK and AAB files together, using the shared release version and GITHUB_RUN_NUMBER as their version code. The Android artifact contains both files and the verified AAB receipt. Automatic marker pushes also attach the APK to the GitHub Release. Manual runs leave the public APK and Release body unchanged.
For an Android-only manual run, disable ios and enable android. Leave play_upload false for the first build-only bundle needed by Play Console. After the first website upload, matching Play final signing key and API permissions are established, enable play_upload to build and upload an internal-track draft. Automatic mobile release pushes request the same draft upload. This does not publish a production release. No product version bump is needed for a manual workflow check.
Configure repository variables GOOGLE_PLAY_WORKLOAD_IDENTITY_PROVIDER and GOOGLE_PLAY_SERVICE_ACCOUNT for GitHub OIDC through the Play service account. Restrict WIF to this repository's immutable IDs, refs/heads/main, and the Mobile Release workflow; grant only the required Alook testing-track permissions in Play. A short-lived androidpublisher access token is obtained after building. Missing configuration fails a requested upload. Never commit credentials or upload gha-creds-*.json.
The AAB must pass official bundletool validation, trusted JDK signature verification, and package/version/ARM/certificate checks. Upload consumes the same hashed bytes, checks the Play-returned version/hash, commits only an internal draft and confirms it through a new read edit. Existing in-review changes cause an error instead of review cancellation. A failed commit can have an unknown external outcome; inspect its receipt and Play Console before starting another operation. A rerun retains its version code, so start a new workflow run after that code has already been uploaded. Offline tests do not establish actual signing, upload, account readiness or the final Play signing certificate.
Prerequisites
- Node.js ≥ 18
- pnpm ≥ 9
- Bun (for CLI development)
Setup
git clone https://github.com/alookai/alook.git
cd alook
pnpm install
pnpm db:migrate
pnpm dev
This starts the web app and workers locally. To work on the CLI separately:
pnpm dev:app
Frontend telemetry build configuration
NEXT_PUBLIC_FARO_COLLECTOR_URL is the only manual Faro setting. Supply it to the Web and Blog build environments when enabling their existing consent-controlled telemetry.
Both apps derive environment from NODE_ENV and source release from the first valid full Git SHA in WORKERS_CI_COMMIT_SHA, CF_PAGES_COMMIT_SHA, then GITHUB_SHA. Next embeds these values at build time. Worker runtime variables do not change an existing browser bundle.
NEXT_PUBLIC_FARO_RELEASE and NEXT_PUBLIC_FARO_ENVIRONMENT are generated build outputs for the browser and the Web Worker's first-request snapshot. Do not configure them: both Next configs overwrite them from the native build inputs. Missing or invalid source identity remains release_status=missing; package versions and Worker version IDs do not replace a Git SHA. Environment validation keeps the existing telemetry allowlist.
Project Structure
Alook is a monorepo with nine packages:
| Package | Location | What it does |
|---|---|---|
@alook/web |
src/web |
Next.js dashboard, REST API, auth, database |
@alook/shared |
src/shared |
Types, constants, DB schema, validation |
@alook/email-worker |
src/email-worker |
Inbound email parsing and storage |
@alook/ws-do |
src/ws-do |
Real-time WebSocket channels |
@alook/app |
src/app |
One-command local bootstrap (npx @alook/app onboard) |
@alook/daemon |
src/daemon |
Host-side runtime backend, process manager, credential proxy |
@alook/desktop |
src/desktop |
Desktop app (Tauri) |
@alook/queue-worker |
src/queue-worker |
Handles versioned bot-wake and mobile-push tasks |
Making Changes
1. Branch off main
git checkout -b feat/your-feature
2. Write your code
A few ground rules:
- Scope DB queries by workspace ID — every query must be scoped. This is a security boundary.
- Services are stateless — all state belongs in the database or on disk, never in memory.
- Use Drizzle ORM — no raw SQL unless there's no ORM equivalent.
- Write tests — only skip if the change is already covered by existing tests.
3. Validate before pushing
pnpm check # canonical affected checks; shared Turbo cache
pnpm check --plan # inspect source scope and commands without running them
pnpm check:full # explicit complete six-check contract
The normal pre-commit hook runs pnpm check too. Both entries use the existing impact closure and normal package scripts; Turbo may replay identical tasks. Policy, unknown paths and unresolved Git inputs fall back to the full contract. The local entry includes branch commits, staged/unstaged changes and untracked source. It keeps driver builds/tests ordered and stops at the first failed child. Individual pnpm typecheck, pnpm lint and pnpm test commands remain available.
Report the checks actually selected and run, including cache replay, skipped groups and original failures. Do not rerun a full suite only to obtain another copy of the same result.
4. Open a PR
- Target the
mainbranch - Fill out the PR template — link the issue, describe what changed, check the impact areas
- CI follows the trigger and impact matrix below; stable CI/UI gates must finish for their applicable jobs
Commit Messages
We use Conventional Commits:
TYPE(SCOPE): description
Types: feat, fix, docs, style, refactor, perf, test, chore, ci, build, revert
Scopes: shared, web, cli, email-worker, ws-do, deps, config
Examples:
feat(web): add agent creation page
fix(cli): resolve auth token refresh race condition
chore(deps): update dependencies
Use the body to explain what and why, not how. Reference issues with Closes #123.
Community conversation maintenance contract
Forums are channels with a different presentation. Share account/access qualification, canonical entities, message commands and reading ownership. Keep post ID windows, tag filters and retained view lifetimes where their consumers require them.
State owners and cache coverage
| State | Owner and contract |
|---|---|
| Canonical channel, message, membership and read facts | community DB. HTTP and WS publish through the same qualified writers. Transport windows contain IDs, cursors and page boundaries. |
| Entry qualification and selected window | conversation-entry and use-conversation-entry. Bind account, channel/server, access generation, original request and Query identity. A cached entity or anchor parameter alone does not prove target coverage. |
| Local reading and PUT confirmation | read-coordinator. Keep exact accepted message ID/sequence and original authority. Normal viewport progress survives release, ACK and failed canonical readback; cancel-uncommitted opener handoff does not supply a viewport position. |
| Initial viewport and active user input | use-scroll-anchor. A fresh ordinary entry can consume a newer qualified local target once. Explicit message/sequence navigation wins; active entries and retained parent resume keep their original position ownership. |
| Navigation completion and role display | navigation controller, shell frame, channel route and member VM. The existing navigation owner completes URL publication plus structural frame; the existing server-role authority supplies display facts. |
Use a qualified cached display window only when its IDs and complete canonical entities are locally readable for the current account and access generation. Reveal it after the existing list owner completes its first local placement, while entry refresh, target coverage and repair continue separately. Target positioning, reading and pagination retain their original coverage, snapshot and geometry requirements; revealing cached content does not grant those qualifications. A missing ordinary-entry key does not retire another valid entry's qualification. Otherwise obtain coverage through the existing entry/window request. Preserve valid older windows and the actual selected Query's pages/page parameters. Landing reconciliation carries its sequence high waterline through the existing reconnect owner, including a newer requirement that arrives during an older read.
Freshness and retention are different. Entry and message-window options own stale/GC policy; query-persister owns the bounded persisted closure and restore eligibility. A prior visit, restored entity or fresh metadata does not establish an available, qualified landing window. Account retirement and channel/parent access generation changes retire original authority before reuse; never recapture new permission for old work or carry an old generation's maximum into the new one.
Presence revisions protect confirmed rows from older snapshot omissions. An existing row may accept an in-flight snapshot when only its presence revision is newer; a real newer field update retains the existing whole-row protection.
Request, merge and action boundaries
Capture account, target and allowed lifetime before an async command. Keep that qualification through transport, authentication effects and canonical publication. View-dependent actions also keep their original view guard. An accepted send has its existing account/target lifetime across view changes; that does not authorize old UI completion or a stale retry.
| Action | Required merge/display boundary |
|---|---|
| Entry, pagination, explicit jump, present | Existing Query/window owner reads and reconciles IDs. Keep the selected window and captured canonical read snapshot; do not wait for all background synchronization or clear unrelated caches. |
| Read | Real visible reading admits the intent. Local progress, server-confirmed sequence and canonical read snapshot are separate. Local and confirmed progress each advance monotonically within a valid generation; jumping to older content changes the viewport only. |
| Send, edit, reaction, pin, mark, tags and thread actions | Existing command/transaction owners publish their qualified result. Preserve field revisions, original optimistic rollback and newer WS facts; one command's completion cannot settle another view or overwrite a newer field. |
| First-body edit and forum preview | The shared accepted content writer mirrors full content only for exact child firstMessageId. Mirror optimistic content in the same native transaction. HTTP acceptance of another field does not authorize rejected content. Title/opener, later replies and missing first-body identity do not grant preview ownership. Keep the forum ID window. |
| Back and resumed-parent role display | hasPendingParentReturn derives the accepted return from the original resume intent and exact pending target/state. Repeated Back merges until URL and structural frame both complete; the next Back then goes higher. Ordinary forward cancellation remains. roleDisplayAllowed can use qualified cached own role for a ready/hydrated resumed forum; member reads and action source guards still require their original access/current view. |
Preserve each action's existing confirmation model: Pin/Mark update after ACK; forum posting uses two HTTP commands and does not promise an atomic post transaction. Ordinary message deletion is not a supported action. Post archive/deletion keep their existing qualified command and retirement paths.
Display evidence and regressions
use-messages exposes historyStartKnown only when the selected qualified page explicitly confirms no older history. Leading and empty heroes require that evidence. No selected page means unknown history, even if live rows are visible. Content visibility and read-position readiness remain separate; showing content alone does not acknowledge reading. initialPositionMessageId supplies only the one-shot local landing, without rewriting canonical snapshot/NEW or fabricating server confirmation.
The target root in CommunityPendingFrame paints the theme background over retained content during cross-scope loading. Preserve old DOM/inert and drawer-exit ownership. Opaque coverage does not require another MobilePage, transition state, request or fixed animation wait.
Keep these existing regression entry points when changing the contract:
- Reading/coverage and canonical roles:
use-conversation-entry.dom.test.tsx,read-coordinator.test.ts,use-read-observer.dom.test.ts,use-messages.window.dom.test.tsx,use-scroll-anchor.repin.dom.test.ts,use-servers.dom.test.tsundersrc/web/src/hooks/community/. - Boundary display:
message-list-row.dom.test.ts,message-list-view.dom.test.ts,message-list.older-load.dom.test.tsundersrc/web/src/components/community/messages/. - Content/commands:
forum-preview-live-edit.dom.test.ts,accepted-send-lifecycle.dom.test.tsandmutations/message-field-owner.dom.test.tsxundersrc/web/src/hooks/community/. - Navigation/role/target container:
shell-frame.dom.test.ts,use-community-navigation-controller.dom.test.ts,community-pending-frame.dom.test.ts,channel-route.text-scroll-target.dom.test.tsandchannel-member-view-model.dom.test.tsin their corresponding component directories.
Use the normal Web Vitest configs and repository gates. Real QA must also bind target/scope, actual input, visible landing and backend read/message evidence. HTTP body completion, canonical publication and final viewport are different events; component/system-event controls do not establish native bridge behavior.
Testing
- Framework: Vitest
- E2E: Playwright (web package)
- Run all:
pnpm test - Run by package:
pnpm test:shared,pnpm test:daemon,pnpm test:web,pnpm test:e2e
Affected platform-specific contracts run on their relevant CI platforms. A Windows process or installed-package test is not replaced by a Linux mock.
CI trigger and test responsibilities
| Trigger | Checks |
|---|---|
| PR / merge group | Native Turbo affected tasks, Vitest related files, key browser paths and matched feature groups |
| Ordinary main | Small existing behavior smoke set plus relevant build/artifact checks |
Release main (release: commit) |
Full package/platform, API/browser and artifact regression |
Manual CI full |
Full regression; diagnostic dispatch keeps its existing exact-source guard |
| Docs / benchmark only | No unrelated product checks; stable gates report applicable skips |
| Policy, core/unknown classification or unresolved diff | Conservative full fallback; no silent narrowing |
Turbo owns task inputs, dependencies and cache outputs. Web, Blog and Auth are separate tasks/projects inside the Web package. The unit entry uses Vitest's native related analysis, unions directly changed tests, and runs the complete selected project for structural contracts, nonmodule/configuration inputs or analysis errors. Selection receipts distinguish discovered, selected and executed files; a graph failure cannot become an empty success. Full commands remain available through pnpm check:full and pnpm test.
Package boundaries, smoke files and UI feature paths/specs live in scripts/ci/change-scope-manifest.json. All consumers use the same validated execution plan. A localized rule applies only when every relevant runtime path is covered; shared helpers and unclassified runtime changes expand to the full browser inventory. Renames include both sides, and deleted specs do not silently disappear. Full manual/release runs retain every discovered browser spec. No daily schedule is added.
Keep production permission, session, persistence, message replay and process-authority tests. Test observable outcomes at the layer that owns the risk; do not require a second implementation-text snapshot for behavior already tested through the real component. A source-reading test can still guard an actual architecture, package or native-code boundary. Each deletion or merge must name its remaining executable guard and its limits.
Codecov project and patch statuses and the optional node scripts/ci/report-changed-patch-coverage.mjs --base <ref> --report <coverage-json> output are review information. No coverage percentage is a minimum gate, including in the repository verifier; valid zero-coverage reports still retain their actual counts and percentages. Failed tests, invalid reports, missing required instrumentation and failed uploads remain errors. Named project path groups and report completeness remain checked. Browser E2E is not part of Vitest coverage.
The Web/Blog OpenNext producer builds each required zone once. Blog dry-run and browser jobs verify source, native task hashes, toolchain, environment and archived output identity before consuming it. Web-only browser jobs omit Blog build/start. Lighthouse, Auth, packed artifacts and native platforms keep their own contracts.
Playwright owns discovery and file sharding. The signed plan freezes actual case identities and native partition pairs; each job runs the complete selected file set with its native --shard pair. Empty native partitions create no job. One worker, zero retries and existing case/expect limits remain. The 240-second target is measured separately from the command/job deadlines; no duration table or predicted bound is used. An always-run teardown restores the existing service owner before report collection.
The browser workflow reuses one exact-source build across selected shards and verifies their reports. Stable CI Gate and UI E2E Gate checks are the integration boundary; individual out-of-scope shards may be skipped. Selection and discovery do not prove execution. Release CI also does not gate an independent Cloudflare Git deployment or imply that a store accepted a build.
UI browser E2E and formal local QA
Run pnpm test:e2e-ui from the repository root. Local runs and CI use the
same built Worker graph: one pinned Wrangler loads Web, WS and the real
queue worker; Blog runs separately with its own storage when selected. Local full runs select both Web and Blog. The public ingress
is http://localhost:3000, with Web on port 3001 and Blog on port 3002. Stop other dev
stacks before this run. The runner does not reuse a stack based on health
responses and does not stop listeners owned by another worktree.
Prepare local Worker variables before running. If the files do not exist,
copy src/web/.dev.vars.example to src/web/.dev.vars and
src/queue-worker/.dev.vars.example to src/queue-worker/.dev.vars.
Fill in local BETTER_AUTH_SECRET and ENCRYPTION_KEY; the queue worker
must use the same encryption key as Web. Keep these files private. The Web
Worker variables must also include:
BETTER_AUTH_URL=http://localhost:3000
NODE_ENV=development
DEV_WS_DO_URL=http://localhost:3000
NODE_ENV here is a local Worker variable used by authentication through
env.NODE_ENV; it is not a build command override or a queue transport
switch. Next compiles the built Web producer's process.env.NODE_ENV as
production, so this entry uses TASK_QUEUE.sendBatch. The auth URL,
browser origin and WS ingress must agree. The browser's token
response can override its compiled WS port, so changing only a test URL is
insufficient. The test process also honors ALOOK_SERVER_URL and
DEV_WS_DO_URL; both must describe this graph's public ingress. A stale
split WS override such as http://localhost:8789 is rejected. An override does not reconfigure
the launcher's fixed ports. Machines connect through
/api/ws/community-machine at the same ingress.
Both Web and Blog are built before startup. Set ALOOK_E2E_PREBUILT=1 only
after building both from the exact source under test; setup checks that
both Worker entrypoints exist, but does not prove their freshness. This
entry does not provide Next source hot reload: rebuild for source changes.
With the checkout's local state users stopped, local setup moves existing
Web .wrangler/state to its sibling .wrangler/state.e2e-backup before
either build. This preserves the original bytes, file types and permission
modes, including under a restrictive umask. Startup then resets the test
database and creates fresh actors without replacing that original backup.
Teardown stops the owned process groups before moving the original state
back; build and startup failures use the same cleanup. An unresolved backup
blocks preparation and remains available for recovery; do not delete it
or start another run over it.
Do not set CI=1 to select the Worker graph: CI also disables the local
state backup. Formal QA probes must use the same managed setup and teardown.
Verify actual shared D1 reads/writes, browser and machine WS events, and
task execution rather than health alone. In this built Worker graph, Web
publishes to the local alook-queue binding and the queue worker's queue()
consumer runs the existing task handler. Verify send, consumption, D1 state
and the resulting machine wake; health alone is insufficient. This is local
Queue simulation, not proof of production durability or restart recovery.
The separate Next development mode retains its HTTP task transport. Record
the built artifact and transport that actually ran. Worker count, retries,
timeouts and the CI matrix retain their existing settings.
This entry covers UI Playwright and QA using its lifecycle. The separate
Vitest API/integration pnpm test:e2e job, root pnpm dev, Email topology
and full-stack hot reload retain their existing entrypoints and remain
outside this change.
Scripts Reference
| Command | What it does |
|---|---|
pnpm dev |
Start all dev servers (except CLI) |
pnpm dev:web |
Next.js on :3000 |
pnpm dev:app |
CLI daemon |
pnpm dev:email |
Email worker on :8787 |
pnpm typecheck |
Typecheck all packages |
pnpm lint |
Lint all packages |
pnpm test |
Run all tests |
pnpm db:migrate |
Run D1 migrations locally |
pnpm db:reset |
Wipe local D1 and re-migrate |
pnpm clean |
Remove node_modules, build artifacts, local D1 |
Reporting Issues
Use GitHub Issues. We have templates for:
- Bug reports — reproduction steps, expected vs actual behavior
- Feature requests — problem statement, proposed solution
Community
- Discord — questions, discussion, help
License
By contributing, you agree that your contributions will be licensed under the Apache-2.0 License.