Skip to content

fix: enforce the self-host production contract - #1841

Merged
jan-kubica merged 19 commits into
mainfrom
fix/selfhost-production-contract
Aug 9, 2026
Merged

jan-kubica merged 19 commits into
mainfrom
fix/selfhost-production-contract

Conversation

@jan-kubica

@jan-kubica jan-kubica commented Aug 9, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • generate the production Compose file, environment profile, and contract-bound documentation from a typed service contract
  • validate production environment, immutable image, service inventory, scheduler ownership, and readiness invariants
  • expose separate liveness and dependency-readiness endpoints

Validation

  • bun run selfhost:check
  • bun test scripts/selfhost-contract.test.ts scripts/env-tool.test.ts
  • bun test --preload ./src/tests/setup-env.ts src/env.test.ts src/lib/health/readiness.test.ts src/handlers/health/routes.test.ts (from apps/api)
  • bun packages/scripts/src/tsc-native.ts --noEmit -p tsconfig.scripts.json
  • pre-commit format, lint, and staged-secret checks

Summary by CodeRabbit

  • New Features

    • Added /live and /ready health endpoints with dependency-aware readiness checks.
    • Added tools to generate, validate and diagnose self-hosting configuration.
    • Consolidated scheduled jobs into the API service.
  • Bug Fixes

    • Strengthened validation for secure service URLs, storage credentials and database permissions.
    • Updated deployment checks to verify API readiness and scheduler startup.
  • Documentation

    • Expanded self-hosting, environment configuration and release guidance.
    • Added a generated self-hosting environment template.

@github-actions github-actions Bot added bug Something is not working size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. labels Aug 9, 2026
@github-actions

github-actions Bot commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

@coderabbitai

coderabbitai Bot commented Aug 9, 2026 •

Copy link
Copy Markdown

Review Change Stack

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

The change hardens production configuration, validates the application RLS role, adds dependency-aware API readiness, removes the standalone scheduler deployment path, and introduces generated self-hosting contracts with workflow checks.

Changes

Production readiness and self-hosting

Layer / File(s) Summary
Secure environment validation
apps/api/src/env-*.ts, apps/api/src/lib/*, scripts/env-*.ts
Production validation now checks secure URLs, S3 credentials, mock AI settings, and authenticated Gotenberg access.
Database role and test environment
apps/api/src/db-*.ts, apps/api/src/lib/db/*, apps/api/src/tests/*
The reserved stella role is rejected for application connections. Migration startup validates its RLS posture. Test database setup is centralised.
API readiness and scheduler signalling
apps/api/src/lib/health/*, apps/api/src/handlers/health/*, apps/api/src/server.ts
The API provides /live, /ready, and /health. Readiness checks runtime dependencies and scheduled-job startup.
Self-host contract and generated artefacts
scripts/selfhost-*.ts, docker-compose.selfhost.yml, deploy/selfhost/.env.example
Generated artefacts define the three-service Compose deployment, immutable images, readiness checks, environment validation, and release documentation.
Deployment integration
.github/workflows/*, .github/actions/*, packages/scripts/src/dev-runner.*, docs/*
Workflows use the new database login and probe paths. The standalone scheduler bundle and development process are removed.

Estimated code review effort: 5 (Critical) | ~120 minutes

Sequence Diagram(s)

sequenceDiagram
  participant ProbeClient
  participant HealthRoute
  participant ReadinessProbes
  participant Dependencies
  ProbeClient->>HealthRoute: GET /ready
  HealthRoute->>ReadinessProbes: probeApiReadiness()
  ReadinessProbes->>Dependencies: Run dependency probes
  Dependencies-->>ReadinessProbes: Return readiness results
  ReadinessProbes-->>HealthRoute: Return ready or not-ready
  HealthRoute-->>ProbeClient: Return HTTP 200 or HTTP 503
Loading

Possibly related PRs

Suggested labels: chore

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly summarises the main change: enforcing the self-host production contract.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch fix/selfhost-production-contract

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 62ad421c4d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread apps/api/src/lib/health/readiness.ts Resolved
@jan-kubica
jan-kubica force-pushed the fix/selfhost-production-contract branch from 62ad421 to 6cca2c4 Compare August 9, 2026 14:47
@jan-kubica

Copy link
Copy Markdown
Contributor Author

@codex review

CC on behalf of jan-kubica

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 58e24ad52d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread scripts/selfhost-tool.ts Resolved
Comment thread apps/api/src/server.ts Resolved
Comment thread apps/api/src/env-base-schema.ts Resolved

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a53964b05f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread scripts/selfhost-tool.ts Resolved
Comment thread scripts/selfhost-tool.ts Resolved
Comment thread .github/dependabot.yml Resolved
@jan-kubica

Copy link
Copy Markdown
Contributor Author

@codex review

CC on behalf of jan-kubica

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 150ec603d4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread apps/api/src/db-url.ts Resolved
Comment thread apps/api/src/lib/health/readiness.ts Resolved
Comment thread .github/workflows/release.yml Resolved
@jan-kubica

Copy link
Copy Markdown
Contributor Author

@codex review

CC on behalf of jan-kubica

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: af2c01b2be

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread scripts/selfhost-tool.ts Resolved
Comment thread scripts/selfhost-tool.ts Resolved
@jan-kubica
jan-kubica force-pushed the fix/selfhost-production-contract branch from c6d8d34 to bc42a43 Compare August 9, 2026 15:59
@jan-kubica

Copy link
Copy Markdown
Contributor Author

@codex review

CC on behalf of jan-kubica

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bc42a43a51

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread scripts/selfhost-tool.ts Resolved
@jan-kubica
jan-kubica force-pushed the fix/selfhost-production-contract branch from bc42a43 to 7dfe662 Compare August 9, 2026 16:18
@jan-kubica

Copy link
Copy Markdown
Contributor Author

@codex review

CC on behalf of jan-kubica

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7dfe662681

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread apps/api/src/handlers/health/routes.ts Resolved

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 6

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
scripts/env-catalog.ts (1)

309-318: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Correct the S3 credential guidance for the auto provider.

The text says to omit both credentials unless the provider is "env". However, this generated example uses S3_CREDENTIALS_PROVIDER="auto" with a complete credential pair, and the invariant only requires the pair for "env".

  • scripts/env-catalog.ts#L309-L318: state that "env" requires both usable credentials, and that any supplied static credentials must be supplied as a pair.
  • apps/api/.env.example#L183-L190: regenerate or update the matching comments after correcting the catalogue text.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@scripts/env-catalog.ts` around lines 309 - 318, The S3 credential comments
incorrectly imply credentials must be omitted for every provider except "env".
Update the S3 credential descriptions in scripts/env-catalog.ts lines 309-318 to
state that "env" requires both usable credentials and that any supplied static
credentials must be provided as a complete pair; then regenerate or update the
corresponding comments in apps/api/.env.example lines 183-190 to match.
🧹 Nitpick comments (4)
apps/api/src/lib/health/readiness.ts (2)

124-132: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Make the readiness probe map immutable.

Use as const satisfies ReadinessProbes for this union-backed object literal.

Proposed fix
-} satisfies ReadinessProbes;
+} as const satisfies ReadinessProbes;
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/api/src/lib/health/readiness.ts` around lines 124 - 132, Update the
runtimeReadinessProbes object literal to use `as const satisfies
ReadinessProbes`, preserving its existing probe entries while making the
union-backed map immutable.

Source: Coding guidelines


83-88: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚖️ Poor tradeoff

Use an options object for the S3 write call.

putS3ObjectWithSignal receives four positional arguments. Convert this local API and its callers to a typed options object so the key, body, content type, and signal cannot be interchanged.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/api/src/lib/health/readiness.ts` around lines 83 - 88, Update
putS3ObjectWithSignal and every caller to accept a typed options object
containing the S3 key, body, content type, and signal instead of positional
arguments. Adjust the readiness flow around S3_READINESS_KEY,
S3_READINESS_BYTES, S3_READINESS_CONTENT_TYPE, and signal to pass the
corresponding named properties, preserving existing behavior.

Source: Coding guidelines

apps/api/src/lib/health/readiness.test.ts (1)

40-42: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Use tagged errors for expected health-check failures.

These test fixtures model expected probe failures. Use HealthCheckError instead of bare Error so the tests follow the API error contract.

  • apps/api/src/lib/health/readiness.test.ts#L40-L42: Replace the marker-read failure with HealthCheckError.
  • apps/api/src/lib/health/readiness.test.ts#L85-L88: Replace the failed dependency error with HealthCheckError.
  • apps/api/src/handlers/health/routes.test.ts#L49-L52: Replace the rejected readiness probe error with HealthCheckError.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/api/src/lib/health/readiness.test.ts` around lines 40 - 42, Replace the
expected probe-failure fixtures with HealthCheckError instances instead of bare
Error objects, preserving their existing failure messages and metadata. Apply
this to the marker-read failure and failed dependency error in
apps/api/src/lib/health/readiness.test.ts (lines 40-42 and 85-88), and the
rejected readiness probe in apps/api/src/handlers/health/routes.test.ts (lines
49-52).

Source: Coding guidelines

scripts/selfhost-tool.ts (1)

170-182: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Use an options object for replaceGeneratedBlock.

This helper accepts three positional arguments, including two string values. Use a named options object so each call identifies document and generated explicitly.

As per coding guidelines, use named options or arguments objects for functions with three or more arguments.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@scripts/selfhost-tool.ts` around lines 170 - 182, Update
replaceGeneratedBlock to accept a single named options object containing
document, markers, and generated, then adjust every call site to pass those
properties explicitly. Preserve the existing marker validation and replacement
behavior.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/api/src/db-url.ts`:
- Around line 30-35: Update hasSecureDatabaseTransport to inspect all sslmode
query values and reject any URL containing duplicate sslmode parameters,
regardless of their ordering. Preserve loopback-hostname acceptance, but require
a single sslmode value to be one of the allowed secure modes when transport
security depends on sslmode.

In `@apps/api/src/lib/db/assert-migrations-applied.ts`:
- Around line 19-20: Remove the duplicate AppliedMigrationRow type alias in the
module, retaining a single declaration with the existing hash: string shape so
TypeScript can compile the file.

In `@apps/api/src/lib/http-basic-auth.ts`:
- Around line 1-5: Add direct tests for basicAuthorizationHeader covering normal
username/password credentials and a password containing a colon, asserting each
exact returned Basic Base64 header. Keep these tests independent of Gotenberg
request tests and follow the repository’s existing test conventions.

In `@deploy/selfhost/.env.example`:
- Around line 351-353: Update the source metadata for SELFHOST_BOOTSTRAP_TOKEN
to describe it as required before initial provisioning and removable afterward,
rather than optional. Regenerate the deploy/selfhost/.env.example output so its
generated comments reflect the updated requirement.

In `@docs/self-hosting.md`:
- Around line 236-246: Update the startup command block in the self-hosting
instructions to add the documented migration command using the Compose
environment and file options, with `run --rm --no-deps api bun
/app/apps/api/src/db/migrate.js`, between `config --quiet` and `up -d`.

In `@scripts/selfhost-tool.ts`:
- Around line 271-277: Update releaseContractIssues to validate each
RELEASE_ARTIFACT manifest field is a string containing a digest-qualified image
reference, not merely present. Reject mutable tag-based values and add negative
coverage for tag references while preserving the existing missing-field checks
and immutable-image contract.

---

Outside diff comments:
In `@scripts/env-catalog.ts`:
- Around line 309-318: The S3 credential comments incorrectly imply credentials
must be omitted for every provider except "env". Update the S3 credential
descriptions in scripts/env-catalog.ts lines 309-318 to state that "env"
requires both usable credentials and that any supplied static credentials must
be provided as a complete pair; then regenerate or update the corresponding
comments in apps/api/.env.example lines 183-190 to match.

---

Nitpick comments:
In `@apps/api/src/lib/health/readiness.test.ts`:
- Around line 40-42: Replace the expected probe-failure fixtures with
HealthCheckError instances instead of bare Error objects, preserving their
existing failure messages and metadata. Apply this to the marker-read failure
and failed dependency error in apps/api/src/lib/health/readiness.test.ts (lines
40-42 and 85-88), and the rejected readiness probe in
apps/api/src/handlers/health/routes.test.ts (lines 49-52).

In `@apps/api/src/lib/health/readiness.ts`:
- Around line 124-132: Update the runtimeReadinessProbes object literal to use
`as const satisfies ReadinessProbes`, preserving its existing probe entries
while making the union-backed map immutable.
- Around line 83-88: Update putS3ObjectWithSignal and every caller to accept a
typed options object containing the S3 key, body, content type, and signal
instead of positional arguments. Adjust the readiness flow around
S3_READINESS_KEY, S3_READINESS_BYTES, S3_READINESS_CONTENT_TYPE, and signal to
pass the corresponding named properties, preserving existing behavior.

In `@scripts/selfhost-tool.ts`:
- Around line 170-182: Update replaceGeneratedBlock to accept a single named
options object containing document, markers, and generated, then adjust every
call site to pass those properties explicitly. Preserve the existing marker
validation and replacement behavior.
🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 95e44a07-4ea9-4c62-af7b-1d3b16b8193e

📥 Commits

Reviewing files that changed from the base of the PR and between b4b7cae and 7dfe662.

📒 Files selected for processing (56)
  • .github/actions/setup-e2e-stack/action.yml
  • .github/dependabot.yml
  • .github/workflows/ci.yml
  • .github/workflows/db-migrations.yml
  • .github/workflows/nightly-test.yml
  • .github/workflows/release.yml
  • apps/api/.env.example
  • apps/api/Dockerfile
  • apps/api/package.json
  • apps/api/scripts/run-postgres-tests.ts
  • apps/api/src/db-url.test.ts
  • apps/api/src/db-url.ts
  • apps/api/src/db/migrate.ts
  • apps/api/src/db/role-names.ts
  • apps/api/src/env-base-schema.ts
  • apps/api/src/env-document-processing-worker-schema.ts
  • apps/api/src/env-document-processing-worker.ts
  • apps/api/src/env-schema.ts
  • apps/api/src/env.test.ts
  • apps/api/src/handlers/health/routes.test.ts
  • apps/api/src/handlers/health/routes.ts
  • apps/api/src/lib/db/assert-migrations-applied.ts
  • apps/api/src/lib/db/rls-role-posture.db.test.ts
  • apps/api/src/lib/db/rls-role-posture.test.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • apps/api/src/lib/document-processing-automatic-request.test.ts
  • apps/api/src/lib/files/gotenberg.ts
  • apps/api/src/lib/health/readiness.test.ts
  • apps/api/src/lib/health/readiness.ts
  • apps/api/src/lib/http-basic-auth.ts
  • apps/api/src/lib/s3-credentials.ts
  • apps/api/src/lib/s3.test.ts
  • apps/api/src/lib/s3.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/lib/secure-service-url.ts
  • apps/api/src/scheduler/scheduler.ts
  • apps/api/src/server.ts
  • apps/api/src/tests/setup-env.ts
  • apps/api/src/tests/test-database-environment.test.ts
  • apps/api/src/tests/test-database-environment.ts
  • deploy/selfhost/.env.example
  • docker-compose.selfhost.yml
  • docs/releases.md
  • docs/self-hosting.md
  • package.json
  • packages/scripts/src/dev-runner.test.ts
  • packages/scripts/src/dev-runner.ts
  • scripts/check-api-deployment.test.ts
  • scripts/env-catalog.ts
  • scripts/env-tool.test.ts
  • scripts/env-tool.ts
  • scripts/ratchet-baseline.json
  • scripts/selfhost-contract.test.ts
  • scripts/selfhost-contract.ts
  • scripts/selfhost-tool.ts
  • scripts/verify.sh
💤 Files with no reviewable changes (5)
  • apps/api/src/scheduler/scheduler.ts
  • apps/api/src/lib/document-processing-automatic-request.test.ts
  • apps/api/package.json
  • packages/scripts/src/dev-runner.ts
  • apps/api/Dockerfile
📜 Review details
⏰ Context from checks skipped due to timeout. (12)
  • GitHub Check: e2e-vite-canary
  • GitHub Check: landing-build
  • GitHub Check: mobile-build
  • GitHub Check: windows-scripts
  • GitHub Check: legal-atlas-image
  • GitHub Check: e2e-production-shard (1)
  • GitHub Check: e2e-production-shard (2)
  • GitHub Check: code-quality
  • GitHub Check: ci-checks
  • GitHub Check: typecheck-baseline
  • GitHub Check: web-build
  • GitHub Check: analyze (javascript)
🧰 Additional context used
📓 Path-based instructions (10)
apps/api/**/*.{ts,tsx}

📄 CodeRabbit inference engine (apps/api/AGENTS.md)

apps/api/**/*.{ts,tsx}: In the Elysia backend, do not export types that have no consumer; rely on Eden-inferred handler types unless a schema type is explicitly imported elsewhere.
Prefer Bun-native APIs such as Bun.CryptoHasher, Bun.file, and Bun.S3Client over Web Crypto or manual implementations; backend code targets the Bun runtime rather than browsers.
Do not use ?. or ?? [] to silently handle relations that are structural data-model invariants; use panic() instead.
Provide timeouts on all external calls, such as fetch(url, { signal: AbortSignal.timeout(10_000) }).
Validate inputs at the boundary with Valibot or Elysia schemas.
Use Elysia t for HTTP route contracts, Valibot for web and general runtime validation, and Zod only when an explicit dependency requires it.
For Valibot objects at untrusted boundaries, prefer v.strictObject() over v.object() unless stripping unknown keys is intentional.
Derive related Valibot schemas with v.pick(), v.omit(), and v.partial() instead of manually rewriting sibling schemas.
For cross-field form rules, use v.partialCheck() with v.forward() so issues are assigned to the relevant field.
Put normalization inside Valibot schemas, such as v.trim() and v.toLowerCase(), and use v.InferInput for raw values and v.InferOutput after normalization.
Prefer declarative or built-in validators such as t.File({ maxSize }), v.isoDate(), and v.email() over manual checks.
Do not add fallback values for properties guaranteed by the framework or trusted internal code; add defensive fallbacks only at true system boundaries.
Because Elysia may coerce absent optional UnionEnum fields to the first enum value, clients must explicitly send all such fields, including unchanged values.
Define Elysia macros in a separate plugin rather than using chained inline function-form macros, which break type propagation.

Files:

  • apps/api/src/lib/db/rls-role-posture.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/env-document-processing-worker.ts
  • apps/api/src/lib/http-basic-auth.ts
  • apps/api/src/tests/test-database-environment.test.ts
  • apps/api/src/db/role-names.ts
  • apps/api/scripts/run-postgres-tests.ts
  • apps/api/src/lib/files/gotenberg.ts
  • apps/api/src/lib/secure-service-url.ts
  • apps/api/src/tests/test-database-environment.ts
  • apps/api/src/lib/s3-credentials.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • apps/api/src/handlers/health/routes.test.ts
  • apps/api/src/lib/health/readiness.test.ts
  • apps/api/src/lib/s3.ts
  • apps/api/src/tests/setup-env.ts
  • apps/api/src/db/migrate.ts
  • apps/api/src/db-url.test.ts
  • apps/api/src/lib/db/rls-role-posture.db.test.ts
  • apps/api/src/db-url.ts
  • apps/api/src/env-document-processing-worker-schema.ts
  • apps/api/src/lib/s3.test.ts
  • apps/api/src/lib/db/assert-migrations-applied.ts
  • apps/api/src/env-base-schema.ts
  • apps/api/src/server.ts
  • apps/api/src/env-schema.ts
  • apps/api/src/lib/health/readiness.ts
  • apps/api/src/handlers/health/routes.ts
  • apps/api/src/env.test.ts
apps/api/src/**/*.{ts,tsx}

📄 CodeRabbit inference engine (apps/api/AGENTS.md)

apps/api/src/**/*.{ts,tsx}: Use Drizzle ORM for all database access.
Endpoint modules should default-export exactly one { config, handler } object. Handler-level concerns belong in config; reusable helpers belong in separate modules.
Create backend handlers with createSafeHandler for workspace scope or createSafeRootHandler for root scope from apps/api/src/lib/api-handlers.ts; use Result.gen(), Result.await(safeDb(...)), and Result.err(new HandlerError(...)), and do not export raw handlers accepting plain WorkspaceContext.
Declare permission requirements next to the schema and business logic in the handler file; every workspace-scoped mutation must declare permissions in config and use createSafeHandler.
Ownership IDs must come from server-validated sources: workspaceId from SafeId via validateWorkspaceAccess, and organizationId from ctx.session.activeOrganizationId; never accept these ownership IDs from body or query input.

Files:

  • apps/api/src/lib/db/rls-role-posture.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/env-document-processing-worker.ts
  • apps/api/src/lib/http-basic-auth.ts
  • apps/api/src/tests/test-database-environment.test.ts
  • apps/api/src/db/role-names.ts
  • apps/api/src/lib/files/gotenberg.ts
  • apps/api/src/lib/secure-service-url.ts
  • apps/api/src/tests/test-database-environment.ts
  • apps/api/src/lib/s3-credentials.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • apps/api/src/handlers/health/routes.test.ts
  • apps/api/src/lib/health/readiness.test.ts
  • apps/api/src/lib/s3.ts
  • apps/api/src/tests/setup-env.ts
  • apps/api/src/db/migrate.ts
  • apps/api/src/db-url.test.ts
  • apps/api/src/lib/db/rls-role-posture.db.test.ts
  • apps/api/src/db-url.ts
  • apps/api/src/env-document-processing-worker-schema.ts
  • apps/api/src/lib/s3.test.ts
  • apps/api/src/lib/db/assert-migrations-applied.ts
  • apps/api/src/env-base-schema.ts
  • apps/api/src/server.ts
  • apps/api/src/env-schema.ts
  • apps/api/src/lib/health/readiness.ts
  • apps/api/src/handlers/health/routes.ts
  • apps/api/src/env.test.ts
**/*.{ts,tsx}

📄 CodeRabbit inference engine (CONTRIBUTING.md)

Use strict TypeScript mode, prefer type over interface, and do not use any or non-null assertions.

**/*.{ts,tsx}: In TypeScript, do not use enums; use as const objects or union types.
Model mutually exclusive states as discriminated unions with a stable discriminator; avoid boolean flag sets with optional payload fields.
Construct discriminated-union transitions explicitly instead of spreading the previous branch; read unions with exhaustive switch statements and a never check.
Avoid unnecessary TypeScript casts and annotations; narrow properly, preserve inference, and add a // SAFETY: comment for unavoidable casts.
Validate large-union object literals with as const satisfies T rather than a : T annotation.
Companion maps over a union must be total, using as const satisfies Record<Union, T> rather than Partial<Record<...>>; derive the union from its source map.
Use .at(0) when an element may be absent; use [0] only when existence is established or documented with // SAFETY:.
Do not use barrel files such as index.ts; import from explicit module paths.
Prefer arrow functions over function expressions.
Use named options or arguments objects for functions with three or more arguments, or for interchangeable same-type positional arguments.
Use discriminated-union narrowing such as obj.type === "x"; use in only when no discriminator exists.
Keep helper-local type aliases immediately above the helper; hoist noisy return types into nearby aliases when this improves readability.
Do not import test-only types into production code; use structural constraints when both production and test instances are accepted.
Avoid module-level side effects in shared modules; split reusable utilities from side-effecting singleton initialization.
Defer eager initialization that depends on another module's export by using a lazy getX() singleton getter.
Use better-result for typed error handling; do not use try/catch for control flow, except at bounda...

Files:

  • apps/api/src/lib/db/rls-role-posture.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/env-document-processing-worker.ts
  • scripts/check-api-deployment.test.ts
  • apps/api/src/lib/http-basic-auth.ts
  • apps/api/src/tests/test-database-environment.test.ts
  • apps/api/src/db/role-names.ts
  • apps/api/scripts/run-postgres-tests.ts
  • apps/api/src/lib/files/gotenberg.ts
  • apps/api/src/lib/secure-service-url.ts
  • apps/api/src/tests/test-database-environment.ts
  • apps/api/src/lib/s3-credentials.ts
  • packages/scripts/src/dev-runner.test.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • apps/api/src/handlers/health/routes.test.ts
  • apps/api/src/lib/health/readiness.test.ts
  • apps/api/src/lib/s3.ts
  • scripts/selfhost-contract.test.ts
  • apps/api/src/tests/setup-env.ts
  • apps/api/src/db/migrate.ts
  • apps/api/src/db-url.test.ts
  • apps/api/src/lib/db/rls-role-posture.db.test.ts
  • apps/api/src/db-url.ts
  • apps/api/src/env-document-processing-worker-schema.ts
  • apps/api/src/lib/s3.test.ts
  • scripts/env-catalog.ts
  • apps/api/src/lib/db/assert-migrations-applied.ts
  • scripts/selfhost-contract.ts
  • apps/api/src/env-base-schema.ts
  • apps/api/src/server.ts
  • apps/api/src/env-schema.ts
  • apps/api/src/lib/health/readiness.ts
  • apps/api/src/handlers/health/routes.ts
  • scripts/selfhost-tool.ts
  • scripts/env-tool.test.ts
  • scripts/env-tool.ts
  • apps/api/src/env.test.ts
**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (CONTRIBUTING.md)

Follow the repository's oxlint configuration using the Ultracite preset.

Files:

  • apps/api/src/lib/db/rls-role-posture.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/env-document-processing-worker.ts
  • scripts/check-api-deployment.test.ts
  • apps/api/src/lib/http-basic-auth.ts
  • apps/api/src/tests/test-database-environment.test.ts
  • apps/api/src/db/role-names.ts
  • apps/api/scripts/run-postgres-tests.ts
  • apps/api/src/lib/files/gotenberg.ts
  • apps/api/src/lib/secure-service-url.ts
  • apps/api/src/tests/test-database-environment.ts
  • apps/api/src/lib/s3-credentials.ts
  • packages/scripts/src/dev-runner.test.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • apps/api/src/handlers/health/routes.test.ts
  • apps/api/src/lib/health/readiness.test.ts
  • apps/api/src/lib/s3.ts
  • scripts/selfhost-contract.test.ts
  • apps/api/src/tests/setup-env.ts
  • apps/api/src/db/migrate.ts
  • apps/api/src/db-url.test.ts
  • apps/api/src/lib/db/rls-role-posture.db.test.ts
  • apps/api/src/db-url.ts
  • apps/api/src/env-document-processing-worker-schema.ts
  • apps/api/src/lib/s3.test.ts
  • scripts/env-catalog.ts
  • apps/api/src/lib/db/assert-migrations-applied.ts
  • scripts/selfhost-contract.ts
  • apps/api/src/env-base-schema.ts
  • apps/api/src/server.ts
  • apps/api/src/env-schema.ts
  • apps/api/src/lib/health/readiness.ts
  • apps/api/src/handlers/health/routes.ts
  • scripts/selfhost-tool.ts
  • scripts/env-tool.test.ts
  • scripts/env-tool.ts
  • apps/api/src/env.test.ts
**/*.{ts,tsx,js,jsx,json,md,css}

📄 CodeRabbit inference engine (CONTRIBUTING.md)

Format files with the repository's oxfmt configuration.

Files:

  • apps/api/src/lib/db/rls-role-posture.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • package.json
  • apps/api/src/env-document-processing-worker.ts
  • scripts/check-api-deployment.test.ts
  • apps/api/src/lib/http-basic-auth.ts
  • apps/api/src/tests/test-database-environment.test.ts
  • apps/api/src/db/role-names.ts
  • apps/api/scripts/run-postgres-tests.ts
  • apps/api/src/lib/files/gotenberg.ts
  • apps/api/src/lib/secure-service-url.ts
  • apps/api/src/tests/test-database-environment.ts
  • apps/api/src/lib/s3-credentials.ts
  • packages/scripts/src/dev-runner.test.ts
  • scripts/ratchet-baseline.json
  • apps/api/src/lib/db/rls-role-posture.ts
  • apps/api/src/handlers/health/routes.test.ts
  • apps/api/src/lib/health/readiness.test.ts
  • apps/api/src/lib/s3.ts
  • scripts/selfhost-contract.test.ts
  • apps/api/src/tests/setup-env.ts
  • docs/releases.md
  • apps/api/src/db/migrate.ts
  • apps/api/src/db-url.test.ts
  • apps/api/src/lib/db/rls-role-posture.db.test.ts
  • apps/api/src/db-url.ts
  • apps/api/src/env-document-processing-worker-schema.ts
  • apps/api/src/lib/s3.test.ts
  • scripts/env-catalog.ts
  • apps/api/src/lib/db/assert-migrations-applied.ts
  • scripts/selfhost-contract.ts
  • apps/api/src/env-base-schema.ts
  • apps/api/src/server.ts
  • apps/api/src/env-schema.ts
  • docs/self-hosting.md
  • apps/api/src/lib/health/readiness.ts
  • apps/api/src/handlers/health/routes.ts
  • scripts/selfhost-tool.ts
  • scripts/env-tool.test.ts
  • scripts/env-tool.ts
  • apps/api/src/env.test.ts
**/*.{test,spec}.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (CONTRIBUTING.md)

Write tests for new functionality when applicable.

Files:

  • apps/api/src/lib/db/rls-role-posture.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • scripts/check-api-deployment.test.ts
  • apps/api/src/tests/test-database-environment.test.ts
  • packages/scripts/src/dev-runner.test.ts
  • apps/api/src/handlers/health/routes.test.ts
  • apps/api/src/lib/health/readiness.test.ts
  • scripts/selfhost-contract.test.ts
  • apps/api/src/db-url.test.ts
  • apps/api/src/lib/db/rls-role-posture.db.test.ts
  • apps/api/src/lib/s3.test.ts
  • scripts/env-tool.test.ts
  • apps/api/src/env.test.ts
**/*

📄 CodeRabbit inference engine (CONTRIBUTING.md)

**/*: Run the repository verification checks before pushing changes; bun run verify mirrors the required CI checks.
Use Conventional Commits such as feat:, fix:, chore:, and docs:.
Do not open public issues for security vulnerabilities; report them to security@stll.app.
Contributors must review and understand AI-generated code and have the legal right to submit it.

Files:

  • apps/api/src/lib/db/rls-role-posture.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • package.json
  • scripts/verify.sh
  • apps/api/src/env-document-processing-worker.ts
  • scripts/check-api-deployment.test.ts
  • apps/api/src/lib/http-basic-auth.ts
  • apps/api/src/tests/test-database-environment.test.ts
  • apps/api/src/db/role-names.ts
  • apps/api/scripts/run-postgres-tests.ts
  • apps/api/src/lib/files/gotenberg.ts
  • apps/api/src/lib/secure-service-url.ts
  • apps/api/src/tests/test-database-environment.ts
  • apps/api/src/lib/s3-credentials.ts
  • packages/scripts/src/dev-runner.test.ts
  • scripts/ratchet-baseline.json
  • apps/api/src/lib/db/rls-role-posture.ts
  • apps/api/src/handlers/health/routes.test.ts
  • apps/api/src/lib/health/readiness.test.ts
  • apps/api/src/lib/s3.ts
  • scripts/selfhost-contract.test.ts
  • apps/api/src/tests/setup-env.ts
  • docs/releases.md
  • apps/api/src/db/migrate.ts
  • apps/api/src/db-url.test.ts
  • apps/api/src/lib/db/rls-role-posture.db.test.ts
  • apps/api/src/db-url.ts
  • apps/api/src/env-document-processing-worker-schema.ts
  • apps/api/src/lib/s3.test.ts
  • scripts/env-catalog.ts
  • apps/api/src/lib/db/assert-migrations-applied.ts
  • scripts/selfhost-contract.ts
  • apps/api/src/env-base-schema.ts
  • apps/api/src/server.ts
  • apps/api/src/env-schema.ts
  • docker-compose.selfhost.yml
  • docs/self-hosting.md
  • apps/api/src/lib/health/readiness.ts
  • apps/api/src/handlers/health/routes.ts
  • scripts/selfhost-tool.ts
  • scripts/env-tool.test.ts
  • scripts/env-tool.ts
  • apps/api/src/env.test.ts
apps/api/src/**/*.ts

📄 CodeRabbit inference engine (AGENTS.md)

apps/api/src/**/*.ts: List endpoints must use cursor pagination and return the standard Page<T> envelope { items, nextCursor, limit }; offset pagination, totalCount, and unbounded lists require explicit justification.
Filter database queries by tenant ID and never return unbounded result sets; keep the API stateless.

Files:

  • apps/api/src/lib/db/rls-role-posture.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/env-document-processing-worker.ts
  • apps/api/src/lib/http-basic-auth.ts
  • apps/api/src/tests/test-database-environment.test.ts
  • apps/api/src/db/role-names.ts
  • apps/api/src/lib/files/gotenberg.ts
  • apps/api/src/lib/secure-service-url.ts
  • apps/api/src/tests/test-database-environment.ts
  • apps/api/src/lib/s3-credentials.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • apps/api/src/handlers/health/routes.test.ts
  • apps/api/src/lib/health/readiness.test.ts
  • apps/api/src/lib/s3.ts
  • apps/api/src/tests/setup-env.ts
  • apps/api/src/db/migrate.ts
  • apps/api/src/db-url.test.ts
  • apps/api/src/lib/db/rls-role-posture.db.test.ts
  • apps/api/src/db-url.ts
  • apps/api/src/env-document-processing-worker-schema.ts
  • apps/api/src/lib/s3.test.ts
  • apps/api/src/lib/db/assert-migrations-applied.ts
  • apps/api/src/env-base-schema.ts
  • apps/api/src/server.ts
  • apps/api/src/env-schema.ts
  • apps/api/src/lib/health/readiness.ts
  • apps/api/src/handlers/health/routes.ts
  • apps/api/src/env.test.ts
**/*.{test,spec}.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

Test meaningful failure cases and prefer invariant-based tests for large input spaces; detector tests must use production-shaped inputs that the detector can actually match.

Files:

  • apps/api/src/lib/db/rls-role-posture.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • scripts/check-api-deployment.test.ts
  • apps/api/src/tests/test-database-environment.test.ts
  • packages/scripts/src/dev-runner.test.ts
  • apps/api/src/handlers/health/routes.test.ts
  • apps/api/src/lib/health/readiness.test.ts
  • scripts/selfhost-contract.test.ts
  • apps/api/src/db-url.test.ts
  • apps/api/src/lib/db/rls-role-posture.db.test.ts
  • apps/api/src/lib/s3.test.ts
  • scripts/env-tool.test.ts
  • apps/api/src/env.test.ts
apps/api/src/**/routes.ts

📄 CodeRabbit inference engine (apps/api/AGENTS.md)

Keep routes.ts thin: define route structure, attach macros, select HTTP methods and paths, wire handlers, and keep route-only concerns such as invalidateQuery there. Pass something.handler directly when the handler accepts context directly.

Files:

  • apps/api/src/handlers/health/routes.ts
🧠 Learnings (11)
📚 Learning: 2026-06-30T14:05:30.529Z
Learnt from: jan-kubica
Repo: stella/stella PR: 927
File: packages/folio/src/core/ai-edits/aiEdits.test.ts:1379-1379
Timestamp: 2026-06-30T14:05:30.529Z
Learning: When reviewing TypeScript/JavaScript, do not treat reuse of the same local variable name (e.g., `const runs`) as a duplicate declaration if each instance is declared in a different lexical/function scope—such as separate `test()` callback bodies. Only flag duplicate declarations when they occur within the same lexical scope/block (where redeclaration is actually illegal or confusing), e.g., two `const` declarations for the same identifier in the same `{ ... }` block or same function scope.

Applied to files:

  • apps/api/src/lib/db/rls-role-posture.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/env-document-processing-worker.ts
  • scripts/check-api-deployment.test.ts
  • apps/api/src/lib/http-basic-auth.ts
  • apps/api/src/tests/test-database-environment.test.ts
  • apps/api/src/db/role-names.ts
  • apps/api/scripts/run-postgres-tests.ts
  • apps/api/src/lib/files/gotenberg.ts
  • apps/api/src/lib/secure-service-url.ts
  • apps/api/src/tests/test-database-environment.ts
  • apps/api/src/lib/s3-credentials.ts
  • packages/scripts/src/dev-runner.test.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • apps/api/src/handlers/health/routes.test.ts
  • apps/api/src/lib/health/readiness.test.ts
  • apps/api/src/lib/s3.ts
  • scripts/selfhost-contract.test.ts
  • apps/api/src/tests/setup-env.ts
  • apps/api/src/db/migrate.ts
  • apps/api/src/db-url.test.ts
  • apps/api/src/lib/db/rls-role-posture.db.test.ts
  • apps/api/src/db-url.ts
  • apps/api/src/env-document-processing-worker-schema.ts
  • apps/api/src/lib/s3.test.ts
  • scripts/env-catalog.ts
  • apps/api/src/lib/db/assert-migrations-applied.ts
  • scripts/selfhost-contract.ts
  • apps/api/src/env-base-schema.ts
  • apps/api/src/server.ts
  • apps/api/src/env-schema.ts
  • apps/api/src/lib/health/readiness.ts
  • apps/api/src/handlers/health/routes.ts
  • scripts/selfhost-tool.ts
  • scripts/env-tool.test.ts
  • scripts/env-tool.ts
  • apps/api/src/env.test.ts
📚 Learning: 2026-07-20T08:56:12.738Z
Learnt from: jan-kubica
Repo: stella/stella PR: 746
File: .agents/plans/046-ai-memory.md:0-0
Timestamp: 2026-07-20T08:56:12.738Z
Learning: Firm-wide AI memory write operations (creating/updating firm memory) must be authorized using the dedicated `firmMemory` permission with `create` and `update` actions. In the authorization logic, `firmMemory` should be mapped to the `owner` and `admin` roles. Do not treat `organizationSettings.update` as an authorization fallback for any firm-memory `create`/`update` checks; authorization for firm-memory writes should fail unless `firmMemory` is present with the required action.

Applied to files:

  • apps/api/src/lib/db/rls-role-posture.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/env-document-processing-worker.ts
  • scripts/check-api-deployment.test.ts
  • apps/api/src/lib/http-basic-auth.ts
  • apps/api/src/tests/test-database-environment.test.ts
  • apps/api/src/db/role-names.ts
  • apps/api/scripts/run-postgres-tests.ts
  • apps/api/src/lib/files/gotenberg.ts
  • apps/api/src/lib/secure-service-url.ts
  • apps/api/src/tests/test-database-environment.ts
  • apps/api/src/lib/s3-credentials.ts
  • packages/scripts/src/dev-runner.test.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • apps/api/src/handlers/health/routes.test.ts
  • apps/api/src/lib/health/readiness.test.ts
  • apps/api/src/lib/s3.ts
  • scripts/selfhost-contract.test.ts
  • apps/api/src/tests/setup-env.ts
  • apps/api/src/db/migrate.ts
  • apps/api/src/db-url.test.ts
  • apps/api/src/lib/db/rls-role-posture.db.test.ts
  • apps/api/src/db-url.ts
  • apps/api/src/env-document-processing-worker-schema.ts
  • apps/api/src/lib/s3.test.ts
  • scripts/env-catalog.ts
  • apps/api/src/lib/db/assert-migrations-applied.ts
  • scripts/selfhost-contract.ts
  • apps/api/src/env-base-schema.ts
  • apps/api/src/server.ts
  • apps/api/src/env-schema.ts
  • apps/api/src/lib/health/readiness.ts
  • apps/api/src/handlers/health/routes.ts
  • scripts/selfhost-tool.ts
  • scripts/env-tool.test.ts
  • scripts/env-tool.ts
  • apps/api/src/env.test.ts
📚 Learning: 2026-07-10T10:03:48.996Z
Learnt from: jan-kubica
Repo: stella/stella PR: 1076
File: .oxlint-plugins/__fixtures__/require-use-shallow.fixture.tsx:95-103
Timestamp: 2026-07-10T10:03:48.996Z
Learning: In the stella/stella repo, `unicorn/prefer-at` is configured without `checkAllIndexAccess`, so it only flags from-the-end indexing patterns (e.g., `arr[arr.length - 1]`) and not literal zero-index reads like `arr[0]`. During reviews, do not suggest converting `arr[0]` to `arr.at(0)` solely based on this rule; only recommend `at()` conversions when the existing rule would actually report an issue.

Applied to files:

  • apps/api/src/lib/db/rls-role-posture.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/env-document-processing-worker.ts
  • scripts/check-api-deployment.test.ts
  • apps/api/src/lib/http-basic-auth.ts
  • apps/api/src/tests/test-database-environment.test.ts
  • apps/api/src/db/role-names.ts
  • apps/api/scripts/run-postgres-tests.ts
  • apps/api/src/lib/files/gotenberg.ts
  • apps/api/src/lib/secure-service-url.ts
  • apps/api/src/tests/test-database-environment.ts
  • apps/api/src/lib/s3-credentials.ts
  • packages/scripts/src/dev-runner.test.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • apps/api/src/handlers/health/routes.test.ts
  • apps/api/src/lib/health/readiness.test.ts
  • apps/api/src/lib/s3.ts
  • scripts/selfhost-contract.test.ts
  • apps/api/src/tests/setup-env.ts
  • apps/api/src/db/migrate.ts
  • apps/api/src/db-url.test.ts
  • apps/api/src/lib/db/rls-role-posture.db.test.ts
  • apps/api/src/db-url.ts
  • apps/api/src/env-document-processing-worker-schema.ts
  • apps/api/src/lib/s3.test.ts
  • scripts/env-catalog.ts
  • apps/api/src/lib/db/assert-migrations-applied.ts
  • scripts/selfhost-contract.ts
  • apps/api/src/env-base-schema.ts
  • apps/api/src/server.ts
  • apps/api/src/env-schema.ts
  • apps/api/src/lib/health/readiness.ts
  • apps/api/src/handlers/health/routes.ts
  • scripts/selfhost-tool.ts
  • scripts/env-tool.test.ts
  • scripts/env-tool.ts
  • apps/api/src/env.test.ts
📚 Learning: 2026-07-31T11:15:37.094Z
Learnt from: jan-kubica
Repo: stella/stella PR: 1500
File: apps/api/src/handlers/chat/tools/create-workspace-document-tools.ts:85-89
Timestamp: 2026-07-31T11:15:37.094Z
Learning: In user-facing text, always style the Stella project brand as lowercase “stella,” including possessive forms such as “stella's.” Do not flag lowercase “stella's” as a capitalization issue.

Applied to files:

  • apps/api/src/lib/db/rls-role-posture.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/env-document-processing-worker.ts
  • scripts/check-api-deployment.test.ts
  • apps/api/src/lib/http-basic-auth.ts
  • apps/api/src/tests/test-database-environment.test.ts
  • apps/api/src/db/role-names.ts
  • apps/api/scripts/run-postgres-tests.ts
  • apps/api/src/lib/files/gotenberg.ts
  • apps/api/src/lib/secure-service-url.ts
  • apps/api/src/tests/test-database-environment.ts
  • apps/api/src/lib/s3-credentials.ts
  • packages/scripts/src/dev-runner.test.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • apps/api/src/handlers/health/routes.test.ts
  • apps/api/src/lib/health/readiness.test.ts
  • apps/api/src/lib/s3.ts
  • scripts/selfhost-contract.test.ts
  • apps/api/src/tests/setup-env.ts
  • apps/api/src/db/migrate.ts
  • apps/api/src/db-url.test.ts
  • apps/api/src/lib/db/rls-role-posture.db.test.ts
  • apps/api/src/db-url.ts
  • apps/api/src/env-document-processing-worker-schema.ts
  • apps/api/src/lib/s3.test.ts
  • scripts/env-catalog.ts
  • apps/api/src/lib/db/assert-migrations-applied.ts
  • scripts/selfhost-contract.ts
  • apps/api/src/env-base-schema.ts
  • apps/api/src/server.ts
  • apps/api/src/env-schema.ts
  • apps/api/src/lib/health/readiness.ts
  • apps/api/src/handlers/health/routes.ts
  • scripts/selfhost-tool.ts
  • scripts/env-tool.test.ts
  • scripts/env-tool.ts
  • apps/api/src/env.test.ts
📚 Learning: 2026-07-14T22:02:31.658Z
Learnt from: jan-kubica
Repo: stella/stella PR: 1175
File: apps/api/src/handlers/style-sets/replace.ts:38-41
Timestamp: 2026-07-14T22:02:31.658Z
Learning: In the Bun/Elysia backend under apps/api (Drizzle ORM using Relational Query Builder v2 via defineRelations), object-form `where` filters in RQBv2 queries are valid and should not be flagged. Specifically, for `db.query.<table>.findFirst()` / `findMany()`, use (and reviewers should accept) `where` shaped like `{ id: { eq: value }, organizationId: { eq: value } }`. Do not confuse this with the older v1 callback-style `where` API (e.g., `where: (table, { eq }) => ...`).

Applied to files:

  • apps/api/src/lib/db/rls-role-posture.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/env-document-processing-worker.ts
  • apps/api/src/lib/http-basic-auth.ts
  • apps/api/src/tests/test-database-environment.test.ts
  • apps/api/src/db/role-names.ts
  • apps/api/src/lib/files/gotenberg.ts
  • apps/api/src/lib/secure-service-url.ts
  • apps/api/src/tests/test-database-environment.ts
  • apps/api/src/lib/s3-credentials.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • apps/api/src/handlers/health/routes.test.ts
  • apps/api/src/lib/health/readiness.test.ts
  • apps/api/src/lib/s3.ts
  • apps/api/src/tests/setup-env.ts
  • apps/api/src/db/migrate.ts
  • apps/api/src/db-url.test.ts
  • apps/api/src/lib/db/rls-role-posture.db.test.ts
  • apps/api/src/db-url.ts
  • apps/api/src/env-document-processing-worker-schema.ts
  • apps/api/src/lib/s3.test.ts
  • apps/api/src/lib/db/assert-migrations-applied.ts
  • apps/api/src/env-base-schema.ts
  • apps/api/src/server.ts
  • apps/api/src/env-schema.ts
  • apps/api/src/lib/health/readiness.ts
  • apps/api/src/handlers/health/routes.ts
  • apps/api/src/env.test.ts
📚 Learning: 2026-07-14T22:02:32.634Z
Learnt from: jan-kubica
Repo: stella/stella PR: 1175
File: apps/api/src/lib/style-sets.ts:94-97
Timestamp: 2026-07-14T22:02:32.634Z
Learning: In this codebase’s Drizzle ORM usage (Relational Queries v2 via `defineRelations`, typically `db.query.<table>.findFirst(...)`), allow object-form `where` filters like `where: { id: { eq: value }, organizationId: { eq: value } }`. Do not flag this as an invalid Drizzle/Prisma-incompatible pattern—this object+`eq` syntax is supported by Drizzle’s v2 relational query API and should be treated as correct.

Applied to files:

  • apps/api/src/lib/db/rls-role-posture.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/env-document-processing-worker.ts
  • apps/api/src/lib/http-basic-auth.ts
  • apps/api/src/tests/test-database-environment.test.ts
  • apps/api/src/db/role-names.ts
  • apps/api/src/lib/files/gotenberg.ts
  • apps/api/src/lib/secure-service-url.ts
  • apps/api/src/tests/test-database-environment.ts
  • apps/api/src/lib/s3-credentials.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • apps/api/src/handlers/health/routes.test.ts
  • apps/api/src/lib/health/readiness.test.ts
  • apps/api/src/lib/s3.ts
  • apps/api/src/tests/setup-env.ts
  • apps/api/src/db/migrate.ts
  • apps/api/src/db-url.test.ts
  • apps/api/src/lib/db/rls-role-posture.db.test.ts
  • apps/api/src/db-url.ts
  • apps/api/src/env-document-processing-worker-schema.ts
  • apps/api/src/lib/s3.test.ts
  • apps/api/src/lib/db/assert-migrations-applied.ts
  • apps/api/src/env-base-schema.ts
  • apps/api/src/server.ts
  • apps/api/src/env-schema.ts
  • apps/api/src/lib/health/readiness.ts
  • apps/api/src/handlers/health/routes.ts
  • apps/api/src/env.test.ts
📚 Learning: 2026-07-29T10:59:41.806Z
Learnt from: jan-kubica
Repo: stella/stella PR: 1450
File: apps/web/src/routes/_protected.knowledge/-components/import-skill-dialog.tsx:95-110
Timestamp: 2026-07-29T10:59:41.806Z
Learning: When reviewing Elysia route handlers that use the `invalidateQuery: true` option, treat `queryKey` as a legitimate required handler body field. The `invalidateQuery` macro composes the macro’s body schema (from `apps/api/src/lib/invalidate-query-macro.ts`) with the handler’s local body schema, and the macro’s `afterHandle` reads `queryKey` to broadcast cache invalidation. Therefore, do not flag `queryKey` as an unsupported handler-body field; instead, verify that callers provide the required `queryKey` value.

Applied to files:

  • apps/api/src/lib/db/rls-role-posture.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/env-document-processing-worker.ts
  • apps/api/src/lib/http-basic-auth.ts
  • apps/api/src/tests/test-database-environment.test.ts
  • apps/api/src/db/role-names.ts
  • apps/api/src/lib/files/gotenberg.ts
  • apps/api/src/lib/secure-service-url.ts
  • apps/api/src/tests/test-database-environment.ts
  • apps/api/src/lib/s3-credentials.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • apps/api/src/handlers/health/routes.test.ts
  • apps/api/src/lib/health/readiness.test.ts
  • apps/api/src/lib/s3.ts
  • apps/api/src/tests/setup-env.ts
  • apps/api/src/db/migrate.ts
  • apps/api/src/db-url.test.ts
  • apps/api/src/lib/db/rls-role-posture.db.test.ts
  • apps/api/src/db-url.ts
  • apps/api/src/env-document-processing-worker-schema.ts
  • apps/api/src/lib/s3.test.ts
  • apps/api/src/lib/db/assert-migrations-applied.ts
  • apps/api/src/env-base-schema.ts
  • apps/api/src/server.ts
  • apps/api/src/env-schema.ts
  • apps/api/src/lib/health/readiness.ts
  • apps/api/src/handlers/health/routes.ts
  • apps/api/src/env.test.ts
📚 Learning: 2026-08-01T04:30:28.948Z
Learnt from: jan-kubica
Repo: stella/stella PR: 1524
File: apps/api/src/lib/ocr-searchable-pdf-worker.ts:0-0
Timestamp: 2026-08-01T04:30:28.948Z
Learning: In TypeScript OCR and document-processing parsers under apps/api/src/lib, use the shared isUnknownArray guard before destructuring values that may be arrays. Prefer this guard over Array.isArray() alone because Array.isArray() can widen unknown values to any[], weakening type safety.

Applied to files:

  • apps/api/src/lib/db/rls-role-posture.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/lib/http-basic-auth.ts
  • apps/api/src/lib/files/gotenberg.ts
  • apps/api/src/lib/secure-service-url.ts
  • apps/api/src/lib/s3-credentials.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • apps/api/src/lib/health/readiness.test.ts
  • apps/api/src/lib/s3.ts
  • apps/api/src/lib/db/rls-role-posture.db.test.ts
  • apps/api/src/lib/s3.test.ts
  • apps/api/src/lib/db/assert-migrations-applied.ts
  • apps/api/src/lib/health/readiness.ts
📚 Learning: 2026-07-18T08:39:56.674Z
Learnt from: jan-kubica
Repo: stella/stella PR: 1227
File: apps/api/src/handlers/entities/delete-version.test.ts:0-0
Timestamp: 2026-07-18T08:39:56.674Z
Learning: In the TypeScript API, a `ScopedDb` created via `createMembershipScopedDb` runs in its own short-lived RLS transaction per invocation. Do not use a “validation” query in one `scopedDb` call to authorize a read performed in a later `scopedDb` call—concurrent state changes (e.g., an entity-version tombstone) can make the later read invalid. Instead, combine the dependent reads into a single `scopedDb` invocation/transaction, or enforce the required state predicate in the content query itself (so RLS filtering and correctness are applied in the same transaction/read).

Applied to files:

  • apps/api/src/db/role-names.ts
  • apps/api/src/handlers/health/routes.test.ts
  • apps/api/src/db/migrate.ts
  • apps/api/src/handlers/health/routes.ts
📚 Learning: 2026-07-13T01:02:46.608Z
Learnt from: jan-kubica
Repo: stella/stella PR: 728
File: packages/business-registries/src/denue/client.test.ts:0-0
Timestamp: 2026-07-13T01:02:46.608Z
Learning: In the stella/stella repo’s Bun test files, avoid awaiting Bun rejection matcher assertions like `await expect(promise).rejects.toBeInstanceOf(...)` (or other `.rejects` matcher calls). The repo’s type-aware ESLint rules (`await-thenable`, `no-confusing-void-expression`) flag these because Bun intentionally types rejection matcher calls as returning `void`. Follow the established convention: call the `.rejects.*` matcher without `await`; the assertion still runs correctly.

Applied to files:

  • packages/scripts/src/dev-runner.test.ts
📚 Learning: 2026-07-02T10:14:12.496Z
Learnt from: jan-kubica
Repo: stella/stella PR: 958
File: apps/api/Dockerfile:20-20
Timestamp: 2026-07-02T10:14:12.496Z
Learning: When reviewing Dockerfiles and CI workflow/config files, avoid hardcoding `bun install -g turbox.y.z` with a specific `x.y.z`. Any `turbo` version used in build stages/CI image-guard logic must be sourced from (and stay in sync with) the root `package.json` `turbo` version. This aligns with the repo’s workspace-hygiene invariant implemented in `packages/scripts/src/workspace-hygiene.ts` (and covered by `packages/scripts/src/workspace-hygiene.test.ts`), which rejects hardcoded/between-file `turbo` version drift.

Applied to files:

  • .github/workflows/nightly-test.yml
  • .github/workflows/ci.yml
  • .github/workflows/db-migrations.yml
  • .github/workflows/release.yml
🪛 ast-grep (0.45.0)
scripts/selfhost-contract.test.ts

[warning] 89-89: Regular expression constructed from variable input detected. This can lead to Regular Expression Denial of Service (ReDoS) attacks if the variable contains malicious patterns. Use libraries like 'recheck' to validate regex safety or use static patterns.
Context: new RegExp(^#? ?${entry.name}=, "gmu")
Note: [CWE-1333] Inefficient Regular Expression Complexity

(regexp-from-variable)

scripts/selfhost-tool.ts

[warning] 237-237: Regular expression constructed from variable input detected. This can lead to Regular Expression Denial of Service (ReDoS) attacks if the variable contains malicious patterns. Use libraries like 'recheck' to validate regex safety or use static patterns.
Context: new RegExp(^${name}=, "mu")
Note: [CWE-1333] Inefficient Regular Expression Complexity

(regexp-from-variable)


[warning] 39-42: Do not use variable for regular expressions
Context: new RegExp(
String.raw(?:\bPOSTGRES_USER:\s*["']?${APPLICATION_RLS_ROLE_NAME}["']?(?:\s|$)|postgres(?:ql)?:\/\/${APPLICATION_RLS_ROLE_NAME}(?=[:@])|\b(?:pg_isready|psql)\b[^\n]*\s-U\s+${APPLICATION_RLS_ROLE_NAME}(?=\s|$)),
"imu",
)
Note: [CWE-1333] Inefficient Regular Expression Complexity. Security best practice.

(regexp-non-literal-typescript)

🪛 Checkov (3.3.9)
.github/workflows/nightly-test.yml

[medium] 320-321: Basic Auth Credentials

(CKV_SECRET_4)

.github/workflows/ci.yml

[medium] 963-964: Basic Auth Credentials

(CKV_SECRET_4)

.github/workflows/db-migrations.yml

[medium] 108-109: Basic Auth Credentials

(CKV_SECRET_4)

🪛 dotenv-linter (4.0.0)
apps/api/.env.example

[warning] 186-186: [QuoteCharacter] The value has quote characters (', ")

(QuoteCharacter)

deploy/selfhost/.env.example

[warning] 7-7: [QuoteCharacter] The value has quote characters (', ")

(QuoteCharacter)


[warning] 9-9: [QuoteCharacter] The value has quote characters (', ")

(QuoteCharacter)


[warning] 9-9: [UnorderedKey] The STELLA_API_ENV_FILE key should go before the STELLA_API_IMAGE key

(UnorderedKey)


[warning] 23-23: [QuoteCharacter] The value has quote characters (', ")

(QuoteCharacter)


[warning] 176-176: [QuoteCharacter] The value has quote characters (', ")

(QuoteCharacter)


[warning] 180-180: [QuoteCharacter] The value has quote characters (', ")

(QuoteCharacter)


[warning] 183-183: [QuoteCharacter] The value has quote characters (', ")

(QuoteCharacter)


[warning] 187-187: [QuoteCharacter] The value has quote characters (', ")

(QuoteCharacter)


[warning] 192-192: [QuoteCharacter] The value has quote characters (', ")

(QuoteCharacter)


[warning] 197-197: [QuoteCharacter] The value has quote characters (', ")

(QuoteCharacter)


[warning] 200-200: [QuoteCharacter] The value has quote characters (', ")

(QuoteCharacter)


[warning] 322-322: [QuoteCharacter] The value has quote characters (', ")

(QuoteCharacter)


[warning] 326-326: [QuoteCharacter] The value has quote characters (', ")

(QuoteCharacter)


[warning] 334-334: [QuoteCharacter] The value has quote characters (', ")

(QuoteCharacter)


[warning] 338-338: [QuoteCharacter] The value has quote characters (', ")

(QuoteCharacter)


[warning] 349-349: [QuoteCharacter] The value has quote characters (', ")

(QuoteCharacter)


[warning] 353-353: [QuoteCharacter] The value has quote characters (', ")

(QuoteCharacter)


[warning] 425-425: [QuoteCharacter] The value has quote characters (', ")

(QuoteCharacter)


[warning] 433-433: [QuoteCharacter] The value has quote characters (', ")

(QuoteCharacter)


[warning] 437-437: [QuoteCharacter] The value has quote characters (', ")

(QuoteCharacter)


[warning] 441-441: [QuoteCharacter] The value has quote characters (', ")

(QuoteCharacter)


[warning] 453-453: [QuoteCharacter] The value has quote characters (', ")

(QuoteCharacter)

🪛 LanguageTool
docs/self-hosting.md

[uncategorized] ~31-~31: Loose punctuation mark.
Context: ...ontains exactly these services: - api: HTTP API and the authoritative schedule...

(UNLIKELY_OPENING_PUNCTUATION)


[uncategorized] ~32-~32: Loose punctuation mark.
Context: .../ready. - document-processing-worker: Durable document-processing queue consu...

(UNLIKELY_OPENING_PUNCTUATION)


[uncategorized] ~33-~33: Loose punctuation mark.
Context: ...er; readiness api-ready. - gotenberg: Private authenticated document-conversi...

(UNLIKELY_OPENING_PUNCTUATION)


[uncategorized] ~182-~182: Possible missing comma found.
Context: ...OCR_BATCH_INTERVAL_MINUTES` (minimum 5, maximum 10080); there is no standalone schedule...

(AI_HYDRA_LEO_MISSING_COMMA)

🔇 Additional comments (34)
apps/api/src/env-base-schema.ts (1)

12-20: LGTM!

Also applies to: 96-96, 181-224

apps/api/src/env-document-processing-worker-schema.ts (1)

4-10: LGTM!

Also applies to: 44-60

apps/api/src/env-document-processing-worker.ts (1)

20-20: LGTM!

apps/api/src/env-schema.ts (1)

3-5: LGTM!

Also applies to: 429-483

scripts/env-catalog.ts (1)

64-166: LGTM!

Also applies to: 380-381, 566-567, 637-637

scripts/env-tool.test.ts (1)

241-241: LGTM!

Also applies to: 350-427

scripts/env-tool.ts (1)

64-64: LGTM!

Also applies to: 115-166, 726-726

scripts/ratchet-baseline.json (1)

215-215: LGTM!

apps/api/.env.example (1)

318-319: LGTM!

Also applies to: 425-426

apps/api/src/lib/secure-service-url.ts (1)

1-20: LGTM!

apps/api/src/lib/secure-service-url.test.ts (1)

1-26: LGTM!

apps/api/src/lib/s3-credentials.ts (1)

1-33: LGTM!

apps/api/src/lib/s3.ts (1)

14-17: LGTM!

Also applies to: 267-271

apps/api/src/lib/s3.test.ts (1)

10-10: LGTM!

apps/api/src/lib/files/gotenberg.ts (1)

6-6: LGTM!

Also applies to: 50-51

apps/api/src/env.test.ts (1)

56-68: LGTM!

Also applies to: 94-168

apps/api/src/handlers/health/routes.ts (1)

3-13: LGTM!

Also applies to: 24-85

apps/api/src/server.ts (1)

113-113: LGTM!

Also applies to: 142-142, 194-194, 746-753

packages/scripts/src/dev-runner.test.ts (1)

616-616: LGTM!

Also applies to: 635-635

.github/workflows/release.yml (1)

279-279: LGTM!

Also applies to: 317-318, 340-340

scripts/check-api-deployment.test.ts (1)

143-146: LGTM!

.github/actions/setup-e2e-stack/action.yml (1)

128-128: LGTM!

.github/workflows/ci.yml (1)

935-941: LGTM!

Also applies to: 963-969

.github/workflows/db-migrations.yml (1)

69-75: LGTM!

Also applies to: 108-116, 133-133, 142-155, 165-171, 186-186, 215-215

.github/workflows/nightly-test.yml (1)

204-204: LGTM!

Also applies to: 289-295, 320-320, 329-329

apps/api/src/db/role-names.ts (1)

1-1: LGTM!

apps/api/src/db/migrate.ts (1)

13-13: LGTM!

Also applies to: 51-67

apps/api/src/lib/db/rls-role-posture.ts (1)

1-24: LGTM!

apps/api/src/lib/db/rls-role-posture.db.test.ts (1)

1-57: LGTM!

apps/api/src/lib/db/rls-role-posture.test.ts (1)

1-56: LGTM!

apps/api/scripts/run-postgres-tests.ts (1)

3-4: LGTM!

apps/api/src/tests/test-database-environment.ts (1)

1-13: LGTM!

apps/api/src/tests/test-database-environment.test.ts (1)

1-33: LGTM!

apps/api/src/tests/setup-env.ts (1)

3-4: LGTM!

Also applies to: 14-14

Comment thread apps/api/src/db-url.ts Resolved
Comment thread apps/api/src/lib/http-basic-auth.ts Resolved
Comment thread deploy/selfhost/.env.example Resolved
Comment thread docs/self-hosting.md Resolved
Comment thread scripts/selfhost-tool.ts Resolved
@jan-kubica

Copy link
Copy Markdown
Contributor Author

@codex review

CC on behalf of jan-kubica

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5dc5371132

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread scripts/selfhost-tool.ts Resolved
Comment thread apps/api/src/lib/health/readiness.ts Resolved

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 78a153cc8d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread scripts/selfhost-tool.ts Resolved

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3e585441a5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread apps/api/src/env-base-schema.ts Resolved
Comment thread apps/api/src/handlers/health/routes.ts Resolved
Comment thread apps/api/src/db-url.ts Resolved
@jan-kubica
jan-kubica force-pushed the fix/selfhost-production-contract branch from 3e58544 to 0e6054d Compare August 9, 2026 18:25

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0e6054d02d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread apps/api/src/db/migrate.ts Resolved

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 446924fdf9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread apps/api/src/handlers/health/routes.ts Resolved
Comment thread scripts/selfhost-tool.ts Resolved

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 5

🧹 Nitpick comments (4)
scripts/selfhost-contract.ts (2)

125-134: 🩺 Stability & Availability | 🔵 Trivial | 🏗️ Heavy lift

The worker healthcheck reports the API status, not the worker status.

The document-processing-worker healthcheck fetches http://api:3001/ready. That command succeeds while the API is ready, even if the worker loop has stopped. The container then reports healthy for a dead consumer.

The depends_on block already gates start-up on API readiness, so the healthcheck duplicates that gate. Consider probing a worker-owned signal instead, for example a local liveness file or a small worker HTTP port.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@scripts/selfhost-contract.ts` around lines 125 - 134, Update the
document-processing-worker healthcheck to probe a worker-owned liveness signal
instead of the API readiness endpoint referenced by WORKER_READINESS_COMMAND.
Reuse an existing local worker signal if available, or add the minimal
worker-owned check needed to ensure a stopped worker reports unhealthy while
preserving the existing startup dependency on API readiness.

71-74: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Generated output repeats values that already exist as constants in the same file. The file exports SELFHOST_SERVICE_CONTRACT, SELFHOST_ENV_PATH, and SELFHOST_COMPOSE_PATH, but two renderers hardcode the same values. A change to any constant leaves the generated Compose probe and the generated operator commands stale, and no check detects the drift. The repository guideline requires deriving one structure from the other when they must mirror each other.

  • scripts/selfhost-contract.ts#L71-L74: build API_READINESS_COMMAND and WORKER_READINESS_COMMAND from SELFHOST_SERVICE_CONTRACT[SELFHOST_SERVICE.api].readiness instead of repeating the /ready literal.
  • scripts/selfhost-contract.ts#L302-L316: interpolate SELFHOST_ENV_PATH, SELFHOST_COMPOSE_PATH, and SELFHOST_SERVICE.api into the generated docker compose commands instead of repeating deploy/selfhost/.env, docker-compose.selfhost.yml, and api.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@scripts/selfhost-contract.ts` around lines 71 - 74, The readiness command
constants at scripts/selfhost-contract.ts lines 71-74 must derive their endpoint
paths from SELFHOST_SERVICE_CONTRACT[SELFHOST_SERVICE.api].readiness instead of
hardcoding /ready. Update the generated docker compose commands at
scripts/selfhost-contract.ts lines 302-316 to interpolate SELFHOST_ENV_PATH,
SELFHOST_COMPOSE_PATH, and SELFHOST_SERVICE.api rather than repeating their
literal values.

Source: Coding guidelines

scripts/check-api-deployment.test.ts (2)

177-219: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Exercise the readiness and commit payloads.

The new test checks literal ready configuration only. It does not verify the response consumed by readDeployedCommit, so it can approve a release gate that cannot extract API_DEPLOYMENT_EXPECTED_COMMIT. Add production-shaped tests for ready, not-ready, and commit extraction cases, or keep commit verification on /health.

As per coding guidelines, test files must cover meaningful failure cases for new functionality.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@scripts/check-api-deployment.test.ts` around lines 177 - 219, Expand the test
covering “gates API releases on readiness” to exercise the deployment script’s
response handling, including production-shaped ready and not-ready payloads and
extraction of API_DEPLOYMENT_EXPECTED_COMMIT by readDeployedCommit. Ensure the
tests cover meaningful failure behavior and either validate commit extraction
for the ready probe or preserve commit verification on /health; do not only
assert literal workflow configuration.

Source: Coding guidelines


49-49: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Assert the /ready response contract.

The changed assertion checks only the URL. It does not catch the staging workflow’s existing .status == "ok" check. Add an assertion for .status == "ready" so this test fails when the endpoint migration is incomplete.

As per coding guidelines, tests for new functionality must cover meaningful failure cases.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@scripts/check-api-deployment.test.ts` at line 49, Add an assertion in the
deployment test for the `/ready` endpoint response status, requiring `.status`
to equal `"ready"` alongside the existing `STAGING_HEALTH_URL` assertion. Ensure
the test fails if the endpoint still returns the legacy `"ok"` status.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/api/src/db/migrate.ts`:
- Around line 70-73: Update the migration containing the GRANT statement to
establish PostgreSQL 16+ as the supported minimum, documenting that requirement
before using WITH SET TRUE; alternatively, replace this grant with a PostgreSQL
15-compatible membership grant if older versions must remain supported.

In `@scripts/check-api-deployment.ts`:
- Line 5: Use /health, not the /ready endpoint, for commit extraction in
readDeployedCommit and the DEFAULT_PROBE_PATH configuration. Update
scripts/check-api-deployment.ts lines 5 and 92,
.github/workflows/deploy-staging.yml line 51, .github/workflows/publish-npm.yml
line 276, and the corresponding fixtures/assertions in
scripts/check-api-deployment.test.ts lines 49 and 177-219 so all commit checks
consistently target /health; no /ready/commit contract is needed.

In `@scripts/selfhost-tool.ts`:
- Around line 402-420: Update check so the SELFHOST_COMPOSE_PATH content is read
only when the Compose file exists, reusing the existing absolute-path existence
check pattern. Preserve recording the missing Compose artifact as stale and
ensure selfhostComposeViolations receives a safe empty or equivalent input when
the file is absent, allowing the final actionable issues output to be reached.
- Around line 226-247: Update productionEnvironmentIssues to accumulate
validation failures in a single issues array rather than returning immediately
for STELLA_API_IMAGE or GOTENBERG_URL. Preserve the existing invalid
validateDoctorEnvironment result behavior, append each applicable image and URL
message, and return the complete collected issues after both checks.
- Around line 150-158: Guard URL construction in isSecureSelfhostGotenbergUrl so
malformed values return false instead of throwing, while preserving the existing
TLS/loopback and SELFHOST_GOTENBERG_URL checks for valid URLs. Apply the same
guarded-construction fix to the corresponding unguarded URL parsing in the
secure-service URL validation logic.

---

Nitpick comments:
In `@scripts/check-api-deployment.test.ts`:
- Around line 177-219: Expand the test covering “gates API releases on
readiness” to exercise the deployment script’s response handling, including
production-shaped ready and not-ready payloads and extraction of
API_DEPLOYMENT_EXPECTED_COMMIT by readDeployedCommit. Ensure the tests cover
meaningful failure behavior and either validate commit extraction for the ready
probe or preserve commit verification on /health; do not only assert literal
workflow configuration.
- Line 49: Add an assertion in the deployment test for the `/ready` endpoint
response status, requiring `.status` to equal `"ready"` alongside the existing
`STAGING_HEALTH_URL` assertion. Ensure the test fails if the endpoint still
returns the legacy `"ok"` status.

In `@scripts/selfhost-contract.ts`:
- Around line 125-134: Update the document-processing-worker healthcheck to
probe a worker-owned liveness signal instead of the API readiness endpoint
referenced by WORKER_READINESS_COMMAND. Reuse an existing local worker signal if
available, or add the minimal worker-owned check needed to ensure a stopped
worker reports unhealthy while preserving the existing startup dependency on API
readiness.
- Around line 71-74: The readiness command constants at
scripts/selfhost-contract.ts lines 71-74 must derive their endpoint paths from
SELFHOST_SERVICE_CONTRACT[SELFHOST_SERVICE.api].readiness instead of hardcoding
/ready. Update the generated docker compose commands at
scripts/selfhost-contract.ts lines 302-316 to interpolate SELFHOST_ENV_PATH,
SELFHOST_COMPOSE_PATH, and SELFHOST_SERVICE.api rather than repeating their
literal values.
🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 2ba5a1a2-f75b-4f9c-8092-a0225bb8abed

📥 Commits

Reviewing files that changed from the base of the PR and between 7dfe662 and 233080c.

📒 Files selected for processing (27)
  • .github/workflows/deploy-staging.yml
  • .github/workflows/publish-npm.yml
  • .github/workflows/release.yml
  • apps/api/src/db-url.test.ts
  • apps/api/src/db-url.ts
  • apps/api/src/db/migrate.ts
  • apps/api/src/env-base-schema.ts
  • apps/api/src/env-document-processing-worker-schema.ts
  • apps/api/src/env-document-processing-worker.test.ts
  • apps/api/src/env.test.ts
  • apps/api/src/lib/db/assert-migrations-applied.ts
  • apps/api/src/lib/db/rls-role-posture.test.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/lib/secure-service-url.ts
  • docs/railway.md
  • docs/self-hosting.md
  • railway/api.railway.json
  • railway/template-readme.md
  • scripts/check-api-deployment.test.ts
  • scripts/check-api-deployment.ts
  • scripts/check-railway-smoke.ts
  • scripts/check-railway-template-shape.ts
  • scripts/env-tool.test.ts
  • scripts/selfhost-contract.test.ts
  • scripts/selfhost-contract.ts
  • scripts/selfhost-tool.ts
🚧 Files skipped from review as they are similar to previous changes (9)
  • apps/api/src/lib/db/assert-migrations-applied.ts
  • apps/api/src/env.test.ts
  • apps/api/src/db-url.ts
  • .github/workflows/release.yml
  • scripts/env-tool.test.ts
  • apps/api/src/db-url.test.ts
  • apps/api/src/env-document-processing-worker-schema.ts
  • apps/api/src/lib/db/rls-role-posture.test.ts
  • apps/api/src/env-base-schema.ts
📜 Review details
⏰ Context from checks skipped due to timeout. (7)
  • GitHub Check: e2e-vite-canary
  • GitHub Check: e2e-production-shard (2)
  • GitHub Check: e2e-production-shard (1)
  • GitHub Check: code-quality
  • GitHub Check: web-build
  • GitHub Check: ci-checks
  • GitHub Check: analyze (javascript)
🧰 Additional context used
📓 Path-based instructions (9)
**/*.{ts,tsx,js,jsx,json,md,css}

📄 CodeRabbit inference engine (CONTRIBUTING.md)

Format files with the repository's oxfmt configuration.

Files:

  • railway/template-readme.md
  • apps/api/src/env-document-processing-worker.test.ts
  • scripts/check-api-deployment.ts
  • scripts/check-railway-smoke.ts
  • railway/api.railway.json
  • scripts/check-api-deployment.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/lib/secure-service-url.ts
  • scripts/check-railway-template-shape.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • docs/railway.md
  • docs/self-hosting.md
  • scripts/selfhost-contract.ts
  • apps/api/src/db/migrate.ts
  • scripts/selfhost-tool.ts
  • scripts/selfhost-contract.test.ts
**/*

📄 CodeRabbit inference engine (CONTRIBUTING.md)

**/*: Run the repository verification checks before pushing changes; bun run verify mirrors the required CI checks.
Use Conventional Commits such as feat:, fix:, chore:, and docs:.
Do not open public issues for security vulnerabilities; report them to security@stll.app.
Contributors must review and understand AI-generated code and have the legal right to submit it.

Files:

  • railway/template-readme.md
  • apps/api/src/env-document-processing-worker.test.ts
  • scripts/check-api-deployment.ts
  • scripts/check-railway-smoke.ts
  • railway/api.railway.json
  • scripts/check-api-deployment.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/lib/secure-service-url.ts
  • scripts/check-railway-template-shape.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • docs/railway.md
  • docs/self-hosting.md
  • scripts/selfhost-contract.ts
  • apps/api/src/db/migrate.ts
  • scripts/selfhost-tool.ts
  • scripts/selfhost-contract.test.ts
apps/api/**/*.{ts,tsx}

📄 CodeRabbit inference engine (apps/api/AGENTS.md)

apps/api/**/*.{ts,tsx}: In the Elysia backend, do not export types that have no consumer; rely on Eden-inferred handler types unless a schema type is explicitly imported elsewhere.
Prefer Bun-native APIs such as Bun.CryptoHasher, Bun.file, and Bun.S3Client over Web Crypto or manual implementations; backend code targets the Bun runtime rather than browsers.
Do not use ?. or ?? [] to silently handle relations that are structural data-model invariants; use panic() instead.
Provide timeouts on all external calls, such as fetch(url, { signal: AbortSignal.timeout(10_000) }).
Validate inputs at the boundary with Valibot or Elysia schemas.
Use Elysia t for HTTP route contracts, Valibot for web and general runtime validation, and Zod only when an explicit dependency requires it.
For Valibot objects at untrusted boundaries, prefer v.strictObject() over v.object() unless stripping unknown keys is intentional.
Derive related Valibot schemas with v.pick(), v.omit(), and v.partial() instead of manually rewriting sibling schemas.
For cross-field form rules, use v.partialCheck() with v.forward() so issues are assigned to the relevant field.
Put normalization inside Valibot schemas, such as v.trim() and v.toLowerCase(), and use v.InferInput for raw values and v.InferOutput after normalization.
Prefer declarative or built-in validators such as t.File({ maxSize }), v.isoDate(), and v.email() over manual checks.
Do not add fallback values for properties guaranteed by the framework or trusted internal code; add defensive fallbacks only at true system boundaries.
Because Elysia may coerce absent optional UnionEnum fields to the first enum value, clients must explicitly send all such fields, including unchanged values.
Define Elysia macros in a separate plugin rather than using chained inline function-form macros, which break type propagation.

Files:

  • apps/api/src/env-document-processing-worker.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/lib/secure-service-url.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • apps/api/src/db/migrate.ts
apps/api/src/**/*.{ts,tsx}

📄 CodeRabbit inference engine (apps/api/AGENTS.md)

apps/api/src/**/*.{ts,tsx}: Use Drizzle ORM for all database access.
Endpoint modules should default-export exactly one { config, handler } object. Handler-level concerns belong in config; reusable helpers belong in separate modules.
Create backend handlers with createSafeHandler for workspace scope or createSafeRootHandler for root scope from apps/api/src/lib/api-handlers.ts; use Result.gen(), Result.await(safeDb(...)), and Result.err(new HandlerError(...)), and do not export raw handlers accepting plain WorkspaceContext.
Declare permission requirements next to the schema and business logic in the handler file; every workspace-scoped mutation must declare permissions in config and use createSafeHandler.
Ownership IDs must come from server-validated sources: workspaceId from SafeId via validateWorkspaceAccess, and organizationId from ctx.session.activeOrganizationId; never accept these ownership IDs from body or query input.

Files:

  • apps/api/src/env-document-processing-worker.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/lib/secure-service-url.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • apps/api/src/db/migrate.ts
**/*.{ts,tsx}

📄 CodeRabbit inference engine (CONTRIBUTING.md)

Use strict TypeScript mode, prefer type over interface, and do not use any or non-null assertions.

**/*.{ts,tsx}: In TypeScript, do not use enums; use as const objects or union types.
Model mutually exclusive states as discriminated unions with a stable discriminator; avoid boolean flag sets with optional payload fields.
Construct discriminated-union transitions explicitly instead of spreading the previous branch; read unions with exhaustive switch statements and a never check.
Avoid unnecessary TypeScript casts and annotations; narrow properly, preserve inference, and add a // SAFETY: comment for unavoidable casts.
Validate large-union object literals with as const satisfies T rather than a : T annotation.
Companion maps over a union must be total, using as const satisfies Record<Union, T> rather than Partial<Record<...>>; derive the union from its source map.
Use .at(0) when an element may be absent; use [0] only when existence is established or documented with // SAFETY:.
Do not use barrel files such as index.ts; import from explicit module paths.
Prefer arrow functions over function expressions.
Use named options or arguments objects for functions with three or more arguments, or for interchangeable same-type positional arguments.
Use discriminated-union narrowing such as obj.type === "x"; use in only when no discriminator exists.
Keep helper-local type aliases immediately above the helper; hoist noisy return types into nearby aliases when this improves readability.
Do not import test-only types into production code; use structural constraints when both production and test instances are accepted.
Avoid module-level side effects in shared modules; split reusable utilities from side-effecting singleton initialization.
Defer eager initialization that depends on another module's export by using a lazy getX() singleton getter.
Use better-result for typed error handling; do not use try/catch for control flow, except at bounda...

Files:

  • apps/api/src/env-document-processing-worker.test.ts
  • scripts/check-api-deployment.ts
  • scripts/check-railway-smoke.ts
  • scripts/check-api-deployment.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/lib/secure-service-url.ts
  • scripts/check-railway-template-shape.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • scripts/selfhost-contract.ts
  • apps/api/src/db/migrate.ts
  • scripts/selfhost-tool.ts
  • scripts/selfhost-contract.test.ts
**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (CONTRIBUTING.md)

Follow the repository's oxlint configuration using the Ultracite preset.

Files:

  • apps/api/src/env-document-processing-worker.test.ts
  • scripts/check-api-deployment.ts
  • scripts/check-railway-smoke.ts
  • scripts/check-api-deployment.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/lib/secure-service-url.ts
  • scripts/check-railway-template-shape.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • scripts/selfhost-contract.ts
  • apps/api/src/db/migrate.ts
  • scripts/selfhost-tool.ts
  • scripts/selfhost-contract.test.ts
**/*.{test,spec}.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (CONTRIBUTING.md)

Write tests for new functionality when applicable.

Files:

  • apps/api/src/env-document-processing-worker.test.ts
  • scripts/check-api-deployment.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • scripts/selfhost-contract.test.ts
apps/api/src/**/*.ts

📄 CodeRabbit inference engine (AGENTS.md)

apps/api/src/**/*.ts: List endpoints must use cursor pagination and return the standard Page<T> envelope { items, nextCursor, limit }; offset pagination, totalCount, and unbounded lists require explicit justification.
Filter database queries by tenant ID and never return unbounded result sets; keep the API stateless.

Files:

  • apps/api/src/env-document-processing-worker.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/lib/secure-service-url.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • apps/api/src/db/migrate.ts
**/*.{test,spec}.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

Test meaningful failure cases and prefer invariant-based tests for large input spaces; detector tests must use production-shaped inputs that the detector can actually match.

Files:

  • apps/api/src/env-document-processing-worker.test.ts
  • scripts/check-api-deployment.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • scripts/selfhost-contract.test.ts
🧠 Learnings (10)
📚 Learning: 2026-07-02T10:14:12.496Z
Learnt from: jan-kubica
Repo: stella/stella PR: 958
File: apps/api/Dockerfile:20-20
Timestamp: 2026-07-02T10:14:12.496Z
Learning: When reviewing Dockerfiles and CI workflow/config files, avoid hardcoding `bun install -g turbox.y.z` with a specific `x.y.z`. Any `turbo` version used in build stages/CI image-guard logic must be sourced from (and stay in sync with) the root `package.json` `turbo` version. This aligns with the repo’s workspace-hygiene invariant implemented in `packages/scripts/src/workspace-hygiene.ts` (and covered by `packages/scripts/src/workspace-hygiene.test.ts`), which rejects hardcoded/between-file `turbo` version drift.

Applied to files:

  • .github/workflows/deploy-staging.yml
  • .github/workflows/publish-npm.yml
📚 Learning: 2026-06-30T14:05:30.529Z
Learnt from: jan-kubica
Repo: stella/stella PR: 927
File: packages/folio/src/core/ai-edits/aiEdits.test.ts:1379-1379
Timestamp: 2026-06-30T14:05:30.529Z
Learning: When reviewing TypeScript/JavaScript, do not treat reuse of the same local variable name (e.g., `const runs`) as a duplicate declaration if each instance is declared in a different lexical/function scope—such as separate `test()` callback bodies. Only flag duplicate declarations when they occur within the same lexical scope/block (where redeclaration is actually illegal or confusing), e.g., two `const` declarations for the same identifier in the same `{ ... }` block or same function scope.

Applied to files:

  • apps/api/src/env-document-processing-worker.test.ts
  • scripts/check-api-deployment.ts
  • scripts/check-railway-smoke.ts
  • scripts/check-api-deployment.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/lib/secure-service-url.ts
  • scripts/check-railway-template-shape.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • scripts/selfhost-contract.ts
  • apps/api/src/db/migrate.ts
  • scripts/selfhost-tool.ts
  • scripts/selfhost-contract.test.ts
📚 Learning: 2026-07-20T08:56:12.738Z
Learnt from: jan-kubica
Repo: stella/stella PR: 746
File: .agents/plans/046-ai-memory.md:0-0
Timestamp: 2026-07-20T08:56:12.738Z
Learning: Firm-wide AI memory write operations (creating/updating firm memory) must be authorized using the dedicated `firmMemory` permission with `create` and `update` actions. In the authorization logic, `firmMemory` should be mapped to the `owner` and `admin` roles. Do not treat `organizationSettings.update` as an authorization fallback for any firm-memory `create`/`update` checks; authorization for firm-memory writes should fail unless `firmMemory` is present with the required action.

Applied to files:

  • apps/api/src/env-document-processing-worker.test.ts
  • scripts/check-api-deployment.ts
  • scripts/check-railway-smoke.ts
  • scripts/check-api-deployment.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/lib/secure-service-url.ts
  • scripts/check-railway-template-shape.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • scripts/selfhost-contract.ts
  • apps/api/src/db/migrate.ts
  • scripts/selfhost-tool.ts
  • scripts/selfhost-contract.test.ts
📚 Learning: 2026-07-10T10:03:48.996Z
Learnt from: jan-kubica
Repo: stella/stella PR: 1076
File: .oxlint-plugins/__fixtures__/require-use-shallow.fixture.tsx:95-103
Timestamp: 2026-07-10T10:03:48.996Z
Learning: In the stella/stella repo, `unicorn/prefer-at` is configured without `checkAllIndexAccess`, so it only flags from-the-end indexing patterns (e.g., `arr[arr.length - 1]`) and not literal zero-index reads like `arr[0]`. During reviews, do not suggest converting `arr[0]` to `arr.at(0)` solely based on this rule; only recommend `at()` conversions when the existing rule would actually report an issue.

Applied to files:

  • apps/api/src/env-document-processing-worker.test.ts
  • scripts/check-api-deployment.ts
  • scripts/check-railway-smoke.ts
  • scripts/check-api-deployment.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/lib/secure-service-url.ts
  • scripts/check-railway-template-shape.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • scripts/selfhost-contract.ts
  • apps/api/src/db/migrate.ts
  • scripts/selfhost-tool.ts
  • scripts/selfhost-contract.test.ts
📚 Learning: 2026-07-31T11:15:37.094Z
Learnt from: jan-kubica
Repo: stella/stella PR: 1500
File: apps/api/src/handlers/chat/tools/create-workspace-document-tools.ts:85-89
Timestamp: 2026-07-31T11:15:37.094Z
Learning: In user-facing text, always style the Stella project brand as lowercase “stella,” including possessive forms such as “stella's.” Do not flag lowercase “stella's” as a capitalization issue.

Applied to files:

  • apps/api/src/env-document-processing-worker.test.ts
  • scripts/check-api-deployment.ts
  • scripts/check-railway-smoke.ts
  • scripts/check-api-deployment.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/lib/secure-service-url.ts
  • scripts/check-railway-template-shape.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • scripts/selfhost-contract.ts
  • apps/api/src/db/migrate.ts
  • scripts/selfhost-tool.ts
  • scripts/selfhost-contract.test.ts
📚 Learning: 2026-07-14T22:02:31.658Z
Learnt from: jan-kubica
Repo: stella/stella PR: 1175
File: apps/api/src/handlers/style-sets/replace.ts:38-41
Timestamp: 2026-07-14T22:02:31.658Z
Learning: In the Bun/Elysia backend under apps/api (Drizzle ORM using Relational Query Builder v2 via defineRelations), object-form `where` filters in RQBv2 queries are valid and should not be flagged. Specifically, for `db.query.<table>.findFirst()` / `findMany()`, use (and reviewers should accept) `where` shaped like `{ id: { eq: value }, organizationId: { eq: value } }`. Do not confuse this with the older v1 callback-style `where` API (e.g., `where: (table, { eq }) => ...`).

Applied to files:

  • apps/api/src/env-document-processing-worker.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/lib/secure-service-url.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • apps/api/src/db/migrate.ts
📚 Learning: 2026-07-14T22:02:32.634Z
Learnt from: jan-kubica
Repo: stella/stella PR: 1175
File: apps/api/src/lib/style-sets.ts:94-97
Timestamp: 2026-07-14T22:02:32.634Z
Learning: In this codebase’s Drizzle ORM usage (Relational Queries v2 via `defineRelations`, typically `db.query.<table>.findFirst(...)`), allow object-form `where` filters like `where: { id: { eq: value }, organizationId: { eq: value } }`. Do not flag this as an invalid Drizzle/Prisma-incompatible pattern—this object+`eq` syntax is supported by Drizzle’s v2 relational query API and should be treated as correct.

Applied to files:

  • apps/api/src/env-document-processing-worker.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/lib/secure-service-url.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • apps/api/src/db/migrate.ts
📚 Learning: 2026-07-29T10:59:41.806Z
Learnt from: jan-kubica
Repo: stella/stella PR: 1450
File: apps/web/src/routes/_protected.knowledge/-components/import-skill-dialog.tsx:95-110
Timestamp: 2026-07-29T10:59:41.806Z
Learning: When reviewing Elysia route handlers that use the `invalidateQuery: true` option, treat `queryKey` as a legitimate required handler body field. The `invalidateQuery` macro composes the macro’s body schema (from `apps/api/src/lib/invalidate-query-macro.ts`) with the handler’s local body schema, and the macro’s `afterHandle` reads `queryKey` to broadcast cache invalidation. Therefore, do not flag `queryKey` as an unsupported handler-body field; instead, verify that callers provide the required `queryKey` value.

Applied to files:

  • apps/api/src/env-document-processing-worker.test.ts
  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/lib/secure-service-url.ts
  • apps/api/src/lib/db/rls-role-posture.ts
  • apps/api/src/db/migrate.ts
📚 Learning: 2026-08-01T04:30:28.948Z
Learnt from: jan-kubica
Repo: stella/stella PR: 1524
File: apps/api/src/lib/ocr-searchable-pdf-worker.ts:0-0
Timestamp: 2026-08-01T04:30:28.948Z
Learning: In TypeScript OCR and document-processing parsers under apps/api/src/lib, use the shared isUnknownArray guard before destructuring values that may be arrays. Prefer this guard over Array.isArray() alone because Array.isArray() can widen unknown values to any[], weakening type safety.

Applied to files:

  • apps/api/src/lib/secure-service-url.test.ts
  • apps/api/src/lib/secure-service-url.ts
  • apps/api/src/lib/db/rls-role-posture.ts
📚 Learning: 2026-07-18T08:39:56.674Z
Learnt from: jan-kubica
Repo: stella/stella PR: 1227
File: apps/api/src/handlers/entities/delete-version.test.ts:0-0
Timestamp: 2026-07-18T08:39:56.674Z
Learning: In the TypeScript API, a `ScopedDb` created via `createMembershipScopedDb` runs in its own short-lived RLS transaction per invocation. Do not use a “validation” query in one `scopedDb` call to authorize a read performed in a later `scopedDb` call—concurrent state changes (e.g., an entity-version tombstone) can make the later read invalid. Instead, combine the dependent reads into a single `scopedDb` invocation/transaction, or enforce the required state predicate in the content query itself (so RLS filtering and correctness are applied in the same transaction/read).

Applied to files:

  • apps/api/src/db/migrate.ts
🪛 ast-grep (0.45.0)
scripts/selfhost-tool.ts

[warning] 43-46: Do not use variable for regular expressions
Context: new RegExp(
String.raw(?:\bPOSTGRES_USER:\s*["']?${APPLICATION_RLS_ROLE_NAME}["']?(?:\s|$)|postgres(?:ql)?:\/\/${APPLICATION_RLS_ROLE_NAME}(?=[:@])|\b(?:pg_isready|psql)\b[^\n]*\s-U\s+${APPLICATION_RLS_ROLE_NAME}(?=\s|$)),
"imu",
)
Note: [CWE-1333] Inefficient Regular Expression Complexity. Security best practice.

(regexp-non-literal-typescript)


[warning] 281-281: Regular expression constructed from variable input detected. This can lead to Regular Expression Denial of Service (ReDoS) attacks if the variable contains malicious patterns. Use libraries like 'recheck' to validate regex safety or use static patterns.
Context: new RegExp(^${name}=, "mu")
Note: [CWE-1333] Inefficient Regular Expression Complexity

(regexp-from-variable)

scripts/selfhost-contract.test.ts

[warning] 93-93: Regular expression constructed from variable input detected. This can lead to Regular Expression Denial of Service (ReDoS) attacks if the variable contains malicious patterns. Use libraries like 'recheck' to validate regex safety or use static patterns.
Context: new RegExp(^#? ?${entry.name}=, "gmu")
Note: [CWE-1333] Inefficient Regular Expression Complexity

(regexp-from-variable)

🪛 LanguageTool
docs/self-hosting.md

[uncategorized] ~31-~31: Loose punctuation mark.
Context: ...ontains exactly these services: - api: HTTP API and the authoritative schedule...

(UNLIKELY_OPENING_PUNCTUATION)


[uncategorized] ~32-~32: Loose punctuation mark.
Context: .../ready. - document-processing-worker: Durable document-processing queue consu...

(UNLIKELY_OPENING_PUNCTUATION)


[uncategorized] ~33-~33: Loose punctuation mark.
Context: ...er; readiness api-ready. - gotenberg: Private authenticated document-conversi...

(UNLIKELY_OPENING_PUNCTUATION)


[uncategorized] ~182-~182: Possible missing comma found.
Context: ...OCR_BATCH_INTERVAL_MINUTES` (minimum 5, maximum 10080); there is no standalone schedule...

(AI_HYDRA_LEO_MISSING_COMMA)

🔇 Additional comments (21)
scripts/selfhost-contract.test.ts (1)

1-296: LGTM!

apps/api/src/lib/secure-service-url.ts (1)

1-30: LGTM!

apps/api/src/lib/secure-service-url.test.ts (1)

1-38: LGTM!

apps/api/src/env-document-processing-worker.test.ts (1)

121-130: LGTM!

apps/api/src/lib/db/rls-role-posture.ts (1)

1-28: LGTM!

scripts/selfhost-contract.ts (4)

1-69: LGTM!


165-191: LGTM!


193-268: LGTM!


146-153: 🔒 Security & Privacy

No change needed.

API_ENABLE_BASIC_AUTH is the correct Gotenberg environment variable for --api-enable-basic-auth, and the credentials use the matching GOTENBERG_API_BASIC_AUTH_USERNAME / _PASSWORD names.

			> Likely an incorrect or invalid review comment.
scripts/selfhost-tool.ts (4)

36-47: LGTM!


49-125: LGTM!


160-224: LGTM!


291-357: LGTM!

railway/api.railway.json (1)

19-19: LGTM!

railway/template-readme.md (1)

81-81: LGTM!

docs/self-hosting.md (2)

264-270: Repeat the migration step for the alternate env-file path.

The standard command runs migrate.js, but this alternate command starts the services directly. If an operator uses this path for a new deployment or upgrade, the API can start against an old schema. Add the same migration command, or state that this snippet is only for an already-migrated restart.


27-37: LGTM!

Also applies to: 118-165, 179-183, 209-218, 222-232, 236-258, 281-295, 337-337

scripts/check-api-deployment.test.ts (1)

143-146: LGTM!

scripts/check-railway-smoke.ts (1)

70-73: LGTM!

Also applies to: 139-141

scripts/check-railway-template-shape.ts (1)

119-124: LGTM!

Also applies to: 144-145, 169-169, 180-180, 226-229, 264-267, 346-346

docs/railway.md (1)

212-212: LGTM!

Also applies to: 283-287

Comment thread apps/api/src/db/migrate.ts Resolved
Comment thread scripts/check-api-deployment.ts Resolved
Comment thread scripts/selfhost-tool.ts Resolved
Comment thread scripts/selfhost-tool.ts Resolved
Comment thread scripts/selfhost-tool.ts Resolved

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5398720a26

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread .github/workflows/db-migrations.yml Resolved
@jan-kubica
jan-kubica force-pushed the fix/selfhost-production-contract branch from ec31858 to 42d13bf Compare August 9, 2026 20:08
@jan-kubica
jan-kubica merged commit 785081a into main Aug 9, 2026
46 of 49 checks passed
@jan-kubica
jan-kubica deleted the fix/selfhost-production-contract branch August 9, 2026 21:01
@github-actions github-actions Bot locked and limited conversation to collaborators Aug 9, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

bug Something is not working size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant