alook AGENTS.md

Alook

Alook's main purpose is to make the cli agent always on, and give it a email address.

Navigation

• plans/: place your dev plans (gitignored, local only)
• src/shared: shared types, schema, queries, validators
• src/web: Next.js app on Cloudflare Workers (D1 + R2)
• src/cli: CLI + daemon
• src/email-worker: inbound email Cloudflare Worker
• src/ws-do: WebSocket Durable Object worker

MUST

• Don't write comment: comment may be outdated, code never. Unless the comment are specs and rules.
• run pnpm typecheck, pnpm test as the final check when you think the code is ready.
• service must be STATELESS! All the state must be in DB or local, never put important states in memory.
• scope the queries before, not check the ownership after. don't query data then check if the data belongs to a workspace, use workspace id ahead to query the data.
• respect others' works, don't reset any other git changes just because it's not done by you, others may working at the same time, never revert anything without asking the user.
  • don't stash others' works, you can wait, but stash others' work will cause many problems.

Release — Unified Version Bump

All workspace packages share one version. Use pnpm bump to release:

pnpm bump 0.0.11      # explicit version (v prefix optional)
pnpm bump patch        # auto-increment patch/minor/major
pnpm bump patch --min-cli  # also update MIN_CLI_VERSION in src/web/wrangler.toml
pnpm bump patch --desktop  # trigger desktop build

This updates every src/*/package.json and commits release: vX.Y.Z. Add --min-cli when the release contains breaking changes that require users to update their CLI. Add --desktop when the release includes desktop app changes that need a new build. Mobile store releases are not configured; add current signing accounts and rebuild the release workflow before exposing a mobile release flag.

After reviewing the commit:

git push origin main

This triggers:

• CI — typecheck, lint, tests, coverage (uploaded to Codecov)
• Auto-Tag & Release — CI detects the release: vX.Y.Z commit message, creates the git tag, and creates a GitHub Release with generated changelog (auto-tag-release.yml)
• @alook/cli → auto-published to npm via publish-cli.yml (watches src/cli/package.json)
• @alook/app → auto-published to npm via publish-app.yml (watches src/app/package.json)
• @alook/daemon → auto-published to npm via publish-daemon.yml (watches src/daemon/package.json)
• CF Workers → each module redeploys when its own package.json changes