Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

23.4 KB
Raw Blame

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 main branch
  • 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.ts under src/web/src/hooks/community/.
  • Boundary display: message-list-row.dom.test.ts, message-list-view.dom.test.ts, message-list.older-load.dom.test.ts under src/web/src/components/community/messages/.
  • Content/commands: forum-preview-live-edit.dom.test.ts, accepted-send-lifecycle.dom.test.ts and mutations/message-field-owner.dom.test.tsx under src/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.ts and channel-member-view-model.dom.test.ts in 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.