Skip to main content

Common Tasks

These recipes were checked against the non-GPU repositories on 2026-07-23. Run commands from the repository named in each section.

Validate a Flutter change​

cd acesense-frontend
flutter pub get
dart format --output=none --set-exit-if-changed lib test
flutter analyze
flutter test

The app uses Flutter 3.41.9 through mise.toml and Dart ^3.10.3. Use mise install first when your local Flutter version differs.

Exercise the upload flow locally​

The current app uploads one video object; it does not split the video on the client. A valid request follows this sequence:

  1. Sign in and accept the durable AI-processing consent.
  2. Call requestUploadPath in europe-west1 with the video metadata.
  3. Upload the file to the returned Storage path.
  4. Observe jobs/{jobId} until it reaches done or failed.
  5. If the Storage upload fails, call reportUploadFailure so the reserved concurrency slot is released.

Use the Firebase emulators for destructive or quota-boundary tests. Never create a job document directly from a client; Firestore rules make job creation server-only.

Validate Cloud Functions​

cd acesense-auth-function
pnpm install --frozen-lockfile
pnpm lint
pnpm build
pnpm test

The functions package targets Node.js 22. Deploy from this repository only after the checks pass:

pnpm exec firebase deploy --project acesense-prod --only functions

Validate Firestore and Storage rules​

cd acesense-frontend
npm install
npm run test:rules:emulator

Deploy rules separately so a function release cannot conceal a rules change:

pnpm exec firebase deploy --project acesense-prod --only firestore:rules,storage

Build a web repository​

Use the scripts declared by each repository instead of a workspace-wide command:

cd acesense-admin       # or acesense-landing
pnpm install --frozen-lockfile
pnpm lint
pnpm test
pnpm build

For acesense-annotate, use pnpm typecheck, pnpm test, and pnpm build. For acesense-launchpad, use pnpm lint, pnpm test, and pnpm build:hosting.

Build and validate the docs​

cd acesense-docs/website
pnpm install --frozen-lockfile
pnpm test
cd ..
node scripts/check-links.mjs
node scripts/check-freshness.mjs
cd functions
pnpm test

The private docs deployment serves the Docusaurus build through docsServer. Copy website/build to functions/site before deploying that function and the Hosting rewrite; see Deployment.

Investigate a job without changing it​

Prefer the admin panel's Jobs and Operations pages. Check:

  • status, progress, errorCode, and errorMessage;
  • owner and source (app, api, or mcp);
  • quotaSlotReserved and quotaSlotReleased;
  • input/result paths and timestamps;
  • dispatch-provider fields when escalation reaches the external inference boundary.

Do not repair a job by editing status fields in the Firebase console. Use adminRetryJob for a deliberate retry. The scheduled reconcileStuckJobs sweep handles stale pending/uploaded jobs after two hours and stale processing jobs after six hours.

Grant or repair admin access​

Use Admin → Settings → Admin Claims to bootstrap the admin: true custom claim. The current migration fallback accepts only a verified address in the canonical allowlist. The user must refresh the ID token (normally sign out and back in) after a claim change. See Admin sign-in.

Add a documentation page​

  1. Add a .md or .mdx file under acesense-docs.
  2. Include title, sidebar metadata, and last_verified in front matter.
  3. Link it from website/sidebars.ts when it is not autogenerated.
  4. Run the docs build, link checker, and freshness checker above.
  5. Update last_verified only after checking claims against source or an authoritative external system.

GPU implementation and provider operations are outside this page's audit scope. Use the provider-specific runbooks when that boundary is the confirmed source of an incident.