chore: import upstream snapshot with attribution

2026-07-13 12:23:40 +08:00
commit 3a28426bf4
1399 changed files with 257375 additions and 0 deletions
@@ -0,0 +1,46 @@
+---
+title: "Backend branching"
+sidebarTitle: "Branching"
+description: "Spin up an isolated copy of your project to test schema and config changes"
+---
+
+A branch is a child project with its own Postgres, auth config, storage, edge functions, email templates, realtime channels, and schedules. Merge back when ready or reset and retry. Available on InsForge OSS 2.1.0+.
+
+## Concepts
+
+Each branch runs on its own EC2 instance, restored from the parent at create time. `merge` runs a three-way diff against the parent's create-time state. The branch shares the parent's `JWT_SECRET` but gets its own `API_KEY`. Compute services and frontend deployments do not branch.
+
+## Usage
+
+Create a branch with `full` (schema + data) or `schema-only` (faster, empty user tables).
+
+```bash
+npx @insforge/cli branch create feat-billing --mode full
+npx @insforge/cli branch list
+```
+
+Preview the merge SQL before applying.
+
+```bash
+npx @insforge/cli branch merge feat-billing --dry-run --save-sql ./preview.sql
+npx @insforge/cli branch merge feat-billing
+```
+
+Roll back to the create-time snapshot, or delete the branch.
+
+```bash
+npx @insforge/cli branch reset feat-billing
+npx @insforge/cli branch delete feat-billing
+```
+
+## Specific usage cases
+
+Use a branch for risky schema migrations, RLS rewrites, OAuth provider swaps, and edge function refactors. Skip it for trivial changes and data backfills (user-data rows are not auto-merged).
+
+Merges block on conflicts. Resolve on the branch or reset and retry. Quotas: 3 parent projects per org, 2 active branches per parent, no nesting. A successful merge does not auto-delete the branch.
+
+## More resources
+
+- [Database migrations](/core-concepts/database/migrations) for forward-only SQL files.
+- [Database overview](/core-concepts/database/overview) for what runs under each branch.
+- [CLI reference](https://github.com/InsForge/InsForge) for the full `branch` flag set.
@@ -0,0 +1,62 @@
+---
+title: "CLI harness"
+sidebarTitle: "CLI harness"
+description: "The InsForge CLI is the agent's hands: one terminal interface for schema, config, deploys, and diagnostics."
+---
+
+The `@insforge/cli` is the interface a coding agent uses to operate your backend. Where a human reaches for the dashboard, the agent reaches for the terminal: it runs a command, reads the output, and decides what to do next. Every command speaks `--json`, so the agent works from structured data instead of scraping a screen.
+
+<Note>
+  Run the CLI with `npx @insforge/cli`. Do not install it globally, so the agent always uses the version pinned to the project.
+</Note>
+
+## Why a CLI for agents
+
+A dashboard is built for a human pointer; a CLI is built for anything that can write text. Pass `--json` to any command and the agent gets a structured result it can parse; pass `--yes` and it runs without stopping for a confirmation prompt. Schema, auth config, storage, functions, deploys, branches, and diagnostics are all subcommands of the same tool, so there is one surface to learn instead of a dashboard to navigate. It runs in any terminal, any editor, or CI, with no integration to set up. And after a change, the agent can run [`npx @insforge/cli diagnose`](/agent-native/diagnostics) and read back exactly what broke.
+
+## Command surface
+
+| Area | Commands |
+|------|----------|
+| Auth & context | `login`, `logout`, `whoami`, `current`, `list` |
+| Project | `create`, `link` |
+| Schema | `db migrations new`, `db migrations up`, `db migrations list` |
+| Config as code | `config plan`, `config apply`, `config export` |
+| Branching | `branch create`, `branch merge`, `branch reset`, `branch delete` |
+| Build | `functions`, `storage`, `deployments`, `secrets`, `schedules`, `ai` |
+| Diagnose | `diagnose`, `diagnose advisor`, `diagnose db`, `diagnose logs`, `metadata` |
+
+Run `npx @insforge/cli help <command>` for the flags on any of these.
+
+## A typical agent run
+
+```bash
+# connect
+npx @insforge/cli login
+npx @insforge/cli link
+
+# read current state
+npx @insforge/cli --json metadata
+
+# change schema, safely
+npx @insforge/cli db migrations new add-orders-table
+npx @insforge/cli db migrations up --all
+
+# check the result
+npx @insforge/cli diagnose --json
+```
+
+## Let the agent interpret the output
+
+Diagnostics ships an AI flag so the agent can hand its own backend data to a model and get back an explanation:
+
+```bash
+npx @insforge/cli diagnose --ai "why are auth requests failing after the last migration?"
+```
+
+This pairs the raw signals (advisor findings, DB health, error logs) with a plain-language read, which is what turns "here is a stack trace" into "here is the fix." See [Diagnostics & advisor](/agent-native/diagnostics).
+
+## Next steps
+
+- Put auth, SMTP, storage, retention, and deployment settings in version control with [config as code](/agent-native/config-as-code).
+- Test risky changes on a [backend branch](/agent-native/branching) before touching production.
@@ -0,0 +1,224 @@
+---
+title: Config as code
+description: Manage InsForge auth, SMTP, storage, retention, and deployment settings declaratively from a single insforge.toml using the CLI's plan, apply, and export workflow.
+---
+
+## Overview
+
+`insforge.toml` is a declarative, version-controlled snapshot of a subset of your project's config: auth policy, allowed redirect URLs, password rules, SMTP, storage upload size, realtime and schedule retention, and the deployment subdomain. The CLI provides three commands that work against this file:
+
+- **`config plan`**: diff `insforge.toml` against the linked project. Shows what would change.
+- **`config apply`**: push the diff to the live project. Per-change capability gating, env-resolved secrets, dry-run mode.
+- **`config export`**: pull current project state and write a fresh `insforge.toml`. Useful for bootstrapping from an existing project.
+
+You keep **one** `insforge.toml` in your repo. To apply it to a different environment (staging, prod, a teammate's local backend, or a self-hosted instance), point the CLI at a different project (re-link or use `--project-id`). Secrets are read from environment variables via `env(...)` references, so the file itself stays free of credentials and can be committed safely.
+
+This works the same way on InsForge Cloud projects and on self-hosted OSS deployments.
+
+<Note>
+  All examples use `npx @insforge/cli`. Do not install the CLI globally.
+</Note>
+
+## Command summary
+
+| Command | Purpose |
+|---------|---------|
+| `config plan` | Show diff between `insforge.toml` and live project state |
+| `config apply` | Apply `insforge.toml` to the live project |
+| `config apply --dry-run` | Print the plan without applying |
+| `config apply --auto-approve` | Skip the interactive confirmation prompt (required in `--json` mode) |
+| `config export` | Pull live config and write `insforge.toml` |
+| `config export --force` | Overwrite an existing `insforge.toml` without confirmation |
+
+`config plan` and `config apply` read `insforge.toml`; pass `--file <path>` if it lives somewhere other than `./insforge.toml`. `config export` writes the file; pass `--out <path>` to write it to a custom location.
+
+## Recommended workflow
+
+<Steps>
+  <Step title="Bootstrap from an existing project">
+    If you already configured the project through the dashboard, export it once to get a working file:
+
+    ```bash
+    npx @insforge/cli config export
+    ```
+
+    This writes `insforge.toml` reflecting the current backend state.
+  </Step>
+
+  <Step title="Commit it">
+    Check `insforge.toml` into version control. Secrets are referenced via `env(...)`, so the file is safe to commit.
+  </Step>
+
+  <Step title="Edit and plan">
+    Change the TOML, then preview the diff before applying:
+
+    ```bash
+    npx @insforge/cli config plan
+    ```
+  </Step>
+
+  <Step title="Apply">
+    ```bash
+    npx @insforge/cli config apply
+    ```
+
+    Review the rendered plan and confirm. In CI, pass `--auto-approve` and `--json`.
+  </Step>
+
+  <Step title="Apply the same file elsewhere">
+    To push the same config to staging or a self-hosted backend, point the CLI at the other project and re-run apply:
+
+    ```bash
+    npx @insforge/cli --project-id <staging-project-id> config apply
+    ```
+
+    Secrets that differ between environments (SMTP password, etc.) are resolved per-environment from the local shell, so the TOML doesn't need to change.
+  </Step>
+</Steps>
+
+## What `insforge.toml` covers
+
+The file mirrors a curated subset of project config, the parts that are useful to manage declaratively. Anything not in this list still lives on the dashboard and the API.
+
+| Section | Keys |
+|---------|------|
+| `[auth]` | `allowed_redirect_urls`, `require_email_verification`, `verify_email_method`, `reset_password_method`, `disable_signup` |
+| `[auth.password]` | `min_length`, `require_number`, `require_lowercase`, `require_uppercase`, `require_special_char` |
+| `[auth.smtp]` | `enabled`, `host`, `port`, `username`, `password`, `sender_email`, `sender_name`, `min_interval_seconds` |
+| `[storage]` | `max_file_size_mb` |
+| `[realtime]` | `retention_days` |
+| `[schedules]` | `retention_days` |
+| `[deployments]` | `subdomain` |
+
+Because TOML has no `null` literal, use `retention_days = 0` to disable retention cleanup for realtime messages or schedule execution logs; `config apply` sends `null` to the backend for that value. Email templates, OAuth provider app credentials, buckets, realtime channels, functions, deployment environment variables, and secrets are not managed through this file.
+
+A complete example:
+
+```toml
+[auth]
+require_email_verification = true
+verify_email_method = "code"
+reset_password_method = "code"
+disable_signup = false
+allowed_redirect_urls = [
+  "https://app.example.com/auth/callback",
+  "http://localhost:3000/auth/callback",
+]
+
+[auth.password]
+min_length = 12
+require_number = true
+require_lowercase = true
+require_uppercase = true
+require_special_char = false
+
+[auth.smtp]
+enabled = true
+host = "smtp.sendgrid.net"
+port = 587
+username = "apikey"
+password = "env(SENDGRID_API_KEY)"
+sender_email = "noreply@example.com"
+sender_name = "Acme"
+
+[storage]
+max_file_size_mb = 100
+
+[realtime]
+retention_days = 7
+
+[schedules]
+retention_days = 0
+
+[deployments]
+subdomain = "acme-prod"
+```
+
+## `config plan`
+
+```bash
+npx @insforge/cli config plan
+npx @insforge/cli config plan --file ./config/insforge.toml
+npx @insforge/cli --json config plan
+```
+
+`plan` reads `insforge.toml`, fetches live state via `/api/metadata` and the optional config endpoints for storage, realtime, and schedules, then prints a rendered diff. It also tags any section the live backend doesn't expose yet (older self-hosted versions, etc.). Apply will skip those instead of failing the whole run.
+
+Use `plan` before every `apply` in interactive sessions, and as a CI gate to catch unintended drift.
+
+## `config apply`
+
+```bash
+npx @insforge/cli config apply
+npx @insforge/cli config apply --dry-run
+npx @insforge/cli config apply --auto-approve
+npx @insforge/cli --json config apply --auto-approve
+```
+
+`apply` runs the same diff as `plan`, then walks the change set:
+
+1. **Per-change capability gate.** Each change is checked against the backend's metadata or the section's config endpoint. If the backend doesn't support a section (e.g. an older self-hosted instance without SMTP exposed), that section is skipped with a named warning, and the rest of the changes still apply.
+2. **Secret resolution.** `env(...)` references in the TOML are resolved at apply time from the local environment. If a referenced variable is missing, the command aborts before sending any update, so the backend isn't left half-configured.
+3. **Per-section dispatch.** Each change is sent to the appropriate backend endpoint (`/api/auth/config`, `/api/auth/smtp-config`, `/api/storage/config`, `/api/realtime/config`, `/api/schedules/config`, `/api/deployments/slug`, etc.). Changes are independent, so a failure on one section won't roll back earlier successful sections.
+
+Flags:
+
+- `--dry-run` prints the plan and exits without applying.
+- `--auto-approve` skips the interactive confirmation. Required when `--json` is set, since there's no TTY for the prompt.
+- `--file <path>` overrides the default `./insforge.toml` location.
+
+## `config export`
+
+```bash
+npx @insforge/cli config export
+npx @insforge/cli config export --out ./config/insforge.toml
+npx @insforge/cli config export --force
+```
+
+`export` pulls the live project's configurable surface and writes it to a TOML file. Use it to:
+
+- Bootstrap an `insforge.toml` from a project you've been configuring through the dashboard.
+- Diff hand-edits against current backend state by exporting to a temporary file and comparing.
+- Snapshot config before a risky change so you can re-apply the snapshot if you need to roll back.
+
+The file written by `export` is the same shape the CLI expects from `apply`, so round-tripping is supported.
+
+Without `--force`, `export` refuses to overwrite an existing file in interactive mode and surfaces an `OUTPUT_EXISTS` error in `--json` mode.
+
+## Secret references
+
+`auth.smtp.password` and any other sensitive field can be expressed as `env(VAR_NAME)` instead of a literal value:
+
+```toml
+[auth.smtp]
+password = "env(SENDGRID_API_KEY)"
+```
+
+At apply time the CLI reads `SENDGRID_API_KEY` from the local environment, validates it's present, and sends the resolved value to the backend. The TOML itself never contains the secret, so it can be committed.
+
+This is what lets one `insforge.toml` apply cleanly to multiple environments: the dev and prod backends differ only in *which* `SENDGRID_API_KEY` is in scope when you run `apply`.
+
+`env(...)` refs in a TOML that's the target of `apply` re-send the resolved password on every run. That is the only way the CLI can tell the backend "the secret may have rotated, please update." Fields without an `env(...)` ref are treated as preserve-existing.
+
+## When to use this
+
+- **Version control for project config.** Redirect URLs, sign-up policy, password policy, email verification mode, SMTP, storage upload size, and retention windows live in a file your team reviews via PR.
+- **Multi-environment parity.** One TOML, applied to dev, staging, and prod, keeps the supported project settings aligned everywhere. Environment-specific values (subdomain, SMTP credentials) flow through `--project-id` overrides and `env(...)` refs.
+- **CI-driven config changes.** Run `config apply --auto-approve --json` from your deploy pipeline. Combine with `config plan` as a PR check so reviewers see what the merge will change in prod.
+- **Disaster recovery.** A committed `insforge.toml` is a known-good config snapshot. Re-apply it after restoring a project to bring auth, SMTP, storage, retention, and deployment settings back to the expected shape in seconds.
+- **Self-hosted and local OSS development.** Run `npx @insforge/cli link --api-base-url http://localhost:7130 --api-key <local-key>` against a docker-compose stack, then point the CLI's config commands at your local OSS instance the same way you'd point at cloud.
+
+## Troubleshooting
+
+**`Refusing to apply in --json mode without --auto-approve or --yes`.** The CLI never silently applies changes in non-interactive runs. Pass `--auto-approve` (or `-y`) explicitly.
+
+**`your backend doesn't expose <section>`.** The linked backend is on a version that doesn't have the relevant API yet. The rest of your changes still applied. Upgrade the backend (or wait for the next release) to apply that section.
+
+**`env(...)` reference resolves to nothing.** The CLI aborts before any API call when a referenced env var is missing. Set the variable in your shell or your CI's secret store and re-run.
+
+**`Slug is already taken`.** `deployments.subdomain` conflicts with another project's subdomain on the same backend. Pick a different value.
+
+## Related
+
+- [CLI harness](/agent-native/cli-harness): the full command surface an agent drives
+- [Deployment security guide](/deployment/deployment-security-guide): hardening a self-hosted backend after deploy
@@ -0,0 +1,69 @@
+---
+title: "Diagnostics & advisor"
+sidebarTitle: "Diagnostics & advisor"
+description: "The agent reads backend health, advisor findings, and error logs, then applies the fix."
+---
+
+When something breaks, an agent should not have to guess. `npx @insforge/cli diagnose` turns the backend's own signals into something an agent can fetch and act on directly: advisor findings with remediations, database health checks, instance metrics, and aggregated error logs. Each finding comes with a fix, so "what is wrong" and "what to do about it" arrive together. The agent pulls all of this itself, with no dashboard in the loop, which is what lets it close security gaps like a permissive RLS policy before they leak data.
+
+<Frame caption="A Backend Advisor finding: the problem, the affected table, and a remediation the agent can copy and apply.">
+  <img src="/images/backend-advisor.png" alt="Backend Advisor finding: a permissive RLS policy on public.messages with a Copy Remediation button" />
+</Frame>
+
+## Full health report
+
+Run `diagnose` with no subcommand for everything at once:
+
+```bash
+npx @insforge/cli diagnose
+npx @insforge/cli diagnose --json
+```
+
+The report bundles the advisor scan, database health, instance metrics, and recent error logs into one output. In `--json` mode the agent gets it all as structured data.
+
+## Backend Advisor
+
+The advisor scans for security, performance, and health issues and writes a remediation for each one. The dashboard shows the findings with a "Copy Remediation" button, but the agent does not need the dashboard: it fetches the same scan directly with `--json` and applies the fix itself, so a security issue gets closed without waiting for a human to notice it.
+
+```bash
+npx @insforge/cli diagnose advisor
+npx @insforge/cli diagnose advisor --json
+```
+
+A typical finding is a permissive RLS policy that exposes a table to anonymous users. The advisor names the table, the severity, and the SQL to fix it. The agent reads the finding, applies the remediation as a [migration](/core-concepts/database/migrations), and re-scans to confirm it cleared.
+
+## Targeted checks
+
+Each part of the report is also available on its own:
+
+| Command | What it checks |
+|---------|----------------|
+| `diagnose advisor` | Latest advisor scan: security, performance, and health issues |
+| `diagnose db` | Database health: connections, table bloat, index usage |
+| `diagnose metrics` | Instance metrics: CPU, memory, disk, and network |
+| `diagnose logs` | Error-level logs aggregated across every backend source |
+
+For raw logs from a single source, use the top-level command:
+
+```bash
+npx @insforge/cli logs function.logs
+npx @insforge/cli logs postgres.logs
+```
+
+Sources include `insforge.logs`, `postgREST.logs`, `postgres.logs`, `function.logs`, and `function-deploy.logs`.
+
+## Let the agent interpret it
+
+`diagnose --ai` hands the collected diagnostic data to a model and returns a plain-language analysis:
+
+```bash
+npx @insforge/cli diagnose --ai "why did write latency spike after the last deploy?"
+```
+
+This is the difference between dumping a stack trace and explaining the fix. The agent asks a question about the live backend and gets an answer grounded in the actual signals.
+
+## Next steps
+
+- Apply advisor remediations as [migrations](/core-concepts/database/migrations) so the fix is versioned.
+- Rehearse a risky fix on a [backend branch](/agent-native/branching) before it touches production.
+- Read the [CLI harness](/agent-native/cli-harness) for the rest of the command surface.
@@ -0,0 +1,50 @@
+---
+title: "Agent-Native Initiatives"
+sidebarTitle: "Overview"
+description: "The primitives that let a coding agent operate your backend, not just a human clicking a dashboard."
+---
+
+Most backends assume a human in a dashboard. InsForge assumes a coding agent at a terminal. The products (Database, Auth, Storage, and the rest) are the building blocks; the primitives on this page are how an agent operates them: as files it can edit, branches it can test on, and a backend it can diagnose and fix on its own.
+
+<Note>
+  New here? Start with [Connect via CLI](/quickstart) to link your project. This section is about how an agent *works* with the backend once it is connected.
+</Note>
+
+## The primitives
+
+<CardGroup cols={2}>
+  <Card title="CLI harness" icon="terminal" href="/agent-native/cli-harness">
+    The agent's hands. One terminal interface for login, schema, deploys, config, and diagnostics.
+  </Card>
+  <Card title="Diagnostics & advisor" icon="stethoscope" href="/agent-native/diagnostics">
+    Pull advisor findings, DB health, metrics, and error logs the agent can read and fix.
+  </Card>
+  <Card title="Config as code" icon="file-code" href="/agent-native/config-as-code">
+    Auth, SMTP, storage, retention, and deployment settings live in `insforge.toml`. Plan and apply like infrastructure.
+  </Card>
+  <Card title="Branching" icon="code-branch" href="/agent-native/branching">
+    Clone the whole backend into an isolated branch to test risky changes, then merge or reset.
+  </Card>
+</CardGroup>
+
+## Why it matters
+
+A person and an agent want different things from a backend. A person wants a UI to click. An agent wants a stable text interface it can drive, read back, and reason about. That shows up everywhere in InsForge.
+
+Schema changes are [migrations](/core-concepts/database/migrations) in your repo, and project config is an [`insforge.toml`](/agent-native/config-as-code) file, so the agent edits text, commits it, and reviews it in a PR instead of clicking through forms. When it wants to try something risky, it spins up a [backend branch](/agent-native/branching), runs the change against a copy, and throws the branch away if it goes wrong. When something looks off, it fetches [diagnostics and advisor findings](/agent-native/diagnostics) directly with `npx @insforge/cli diagnose`, no dashboard in the loop, and applies the fix itself. That last part is also how the backend gets more secure: the agent reads a security finding like a permissive RLS policy and remediates it on its own, instead of waiting for a human to remember to check. And it reads current schemas, logs, and metadata straight from the backend with `npx @insforge/cli metadata`, so it works from real state rather than guessing.
+
+## The loop
+
+These chain together. A session usually goes:
+
+1. Read the current state with `npx @insforge/cli metadata`.
+2. Branch the backend, write a [migration](/core-concepts/database/migrations) and check what is pending with `npx @insforge/cli db migrations list`, or edit `insforge.toml` and preview the config diff with `npx @insforge/cli config plan`.
+3. Apply it with `npx @insforge/cli db migrations up --all` or `config apply`, against the branch first, then the parent.
+4. Run `npx @insforge/cli diagnose` to check advisor findings and error logs, and ask `diagnose --ai` to interpret them.
+5. Apply the remediation, re-run diagnose, and merge the branch.
+
+## Next steps
+
+- Read the [CLI harness](/agent-native/cli-harness) to see the full command surface an agent drives.
+- Set up [config as code](/agent-native/config-as-code) so project settings live in version control.
+- Use [diagnostics](/agent-native/diagnostics) to let the agent find and fix backend issues.
@@ -0,0 +1,74 @@
+---
+title: "VS Code extension"
+description: "Sign in to InsForge from VS Code, pick an org and project, and install the InsForge MCP server into your AI coding assistant with one click."
+---
+
+## Overview
+
+The InsForge VS Code extension:
+
+- Logs you in to InsForge (OAuth + PKCE)
+- Lets you pick an org/project
+- Installs InsForge MCP for your AI client
+
+It launches the MCP installer (`npx @insforge/install`) with your project’s API key and API base URL.
+
+## Links
+
+- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=InsForge.insforge)
+- [Open VSX](https://open-vsx.org/extension/InsForge/insforge)
+
+## Install
+
+1. Open VS Code
+2. Go to **Extensions**
+3. Search for **InsForge**
+4. Install the extension published by **insforge**
+
+## Use the extension
+
+<Steps>
+  <Step title="Open the InsForge panel">
+    Click the **InsForge** icon in the Activity Bar (left sidebar).
+  </Step>
+
+  <Step title="Login">
+    Click **Login with InsForge** and complete the login flow in your browser.
+
+    <Note>The callback is <code>http://127.0.0.1:54321/callback</code>.</Note>
+  </Step>
+
+  <Step title="Select a project">
+    Pick an organization and project from the InsForge tree view, or run <code>InsForge: Select Project</code> from the Command Palette.
+  </Step>
+
+  <Step title="Install MCP">
+    Run <code>InsForge: Install MCP</code> (or right-click a project and choose **Install MCP**), then pick the AI client you want to configure.
+
+    The installer runs in a VS Code terminal.
+  </Step>
+</Steps>
+
+## Supported AI clients
+
+The extension supports the following MCP “clients” (the value passed to `@insforge/install`):
+
+| Client | Typical config location |
+|---|---|
+| `cursor` | `~/.cursor/mcp.json` |
+| `claude-code` | `.mcp.json` in your workspace (project-local) |
+| `copilot` | `.vscode/mcp.json` in your workspace (project-local) |
+| `windsurf` | `~/.codeium/windsurf/` |
+| `cline` | Cline VS Code extension config |
+| `roocode` | Roo Code VS Code extension config |
+| `codex` | OpenAI Codex CLI config |
+| `trae` | Trae IDE config |
+| `qoder` | Qoder IDE config |
+
+If your client isn’t listed, run the installer manually (see <a href="/quickstart">Quickstart</a>).
+
+## Notes
+
+- **Project-local installs**: `claude-code` and `copilot` require an open workspace folder.
+- **Port in use**: free up `54321` and retry login.
+