From fb78ea13f77198f8cb2dffaebeec15d0dc525d7f Mon Sep 17 00:00:00 2001 From: huyplb Date: Thu, 15 Oct 2026 22:05:02 -0600 Subject: [PATCH] docs: one file per topic, and one page for every release Living guides use the same names as the rest of the docs. Finished plans sit under docs/plans. Homebrew and Docker Hub pages that repeated the install guide are gone. Every shipped version is summarized in docs/releases/SUMMARY.md. Co-authored-by: Cursor --- .gitignore | 1 - AGENTS.md | 4 +- CONTRIBUTING.md | 7 +- README.md | 12 +- apps/cli/README.md | 4 +- docs/ARCHITECTURE.md | 2 +- docs/CODE_MAP.md | 6 +- docs/DEPLOYMENT.md | 12 +- docs/README.md | 75 +++++++++++++ docs/docker-hub-overview.md | 37 ------ docs/homebrew.md | 41 ------- docs/{INSTALL.md => install.md} | 6 +- .../api-restructure.md} | 2 +- .../backend-extraction.md} | 0 .../frontend-refactor.md} | 0 .../{restructure.md => package-split.md} | 0 docs/plans/sql-editor.md | 2 +- docs/{PUBLISH.md => publish.md} | 2 +- docs/releases/README.md | 2 + docs/releases/RELEASE_0.2.10.md | 2 +- docs/releases/RELEASE_0.2.16.md | 2 +- docs/releases/RELEASE_0.2.33.md | 2 +- docs/releases/RELEASE_0.2.36.md | 2 +- docs/releases/RELEASE_0.2.49_50.md | 2 +- docs/releases/SUMMARY.md | 106 ++++++++++++++++++ docs/releases/UNRELEASED.md | 2 +- docs/{USER_GUIDE.md => user-guide.md} | 8 +- docs/{WORKFLOW.md => workflow.md} | 2 +- .../features/compare/compare.controller.ts | 2 +- packages/shared/src/doc-paths.test.ts | 4 +- packaging/homebrew/README.md | 13 +-- 31 files changed, 228 insertions(+), 134 deletions(-) create mode 100644 docs/README.md delete mode 100644 docs/docker-hub-overview.md delete mode 100644 docs/homebrew.md rename docs/{INSTALL.md => install.md} (89%) rename docs/{API_RESTRUCTURE_PLAN.md => plans/api-restructure.md} (99%) rename docs/{BACKEND_EXTRACTION_PLAN.md => plans/backend-extraction.md} (100%) rename docs/{FRONTEND_REFACTOR_REVIEW.md => plans/frontend-refactor.md} (100%) rename docs/plans/{restructure.md => package-split.md} (100%) rename docs/{PUBLISH.md => publish.md} (98%) create mode 100644 docs/releases/SUMMARY.md rename docs/{USER_GUIDE.md => user-guide.md} (99%) rename docs/{WORKFLOW.md => workflow.md} (99%) diff --git a/.gitignore b/.gitignore index f4115019e..28b5ffd60 100644 --- a/.gitignore +++ b/.gitignore @@ -65,7 +65,6 @@ packages/db/npm-pack/ # Homebrew formula docs (tracked) !packaging/homebrew/README.md !apps/cli/README.md -!docs/homebrew.md # The workflow engine's SQLite DB, created at the repo root by default diff --git a/AGENTS.md b/AGENTS.md index a00e196e9..27e3d1c4f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,7 +3,7 @@ Fox Schema (`foxschema`) is a database schema diff & migration tool: an npm-workspaces monorepo delivered as a web app (`apps/web` = React/Vite UI + `packages/server` Fastify API), a CLI (`apps/cli`), and the dialect engine (`packages/sql` + -`packages/db`). Optional workflow engine: `apps/workflow-server` ([docs/WORKFLOW.md](docs/WORKFLOW.md)). +`packages/db`). Optional workflow engine: `apps/workflow-server` ([docs/workflow.md](docs/workflow.md)). See `README.md` and `CONTRIBUTING.md` for the product overview and the canonical dev/test/build commands. @@ -48,7 +48,7 @@ Standard commands live in `CONTRIBUTING.md` and `package.json` scripts (`npm run UI at http://localhost:5173. API liveness: `GET http://localhost:3210/api/health` → `{"ok":true}`. Every install requires sign-in; first open runs admin setup. Workflow engine: `npm run dev:with-workflow` (needs `WORKFLOW_ENGINE_TOKEN` and - `FOXFLOW_ENCRYPTION_KEY` — [docs/WORKFLOW.md](docs/WORKFLOW.md)). + `FOXFLOW_ENCRYPTION_KEY` — [docs/workflow.md](docs/workflow.md)). - Vite is configured with `server.host: true`, `server.strictPort: true`, and `server.allowedHosts: true` so `http://127.0.0.1:5173` works (not only IPv6 localhost), the port does not silently hop to 5174+, and Cursor/cloud diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f8b7c07a7..d813c45bb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,8 +13,9 @@ fresh clone to a running app with a passing test suite. develop on). - **Docker** — for the test databases and the end-to-end suite. -User install channels: [docs/INSTALL.md](docs/INSTALL.md). Release publish: -[docs/PUBLISH.md](docs/PUBLISH.md). +User install channels: [docs/install.md](docs/install.md). Release publish: +[docs/publish.md](docs/publish.md). The rest of the docs, one file per topic: +[docs/README.md](docs/README.md). ## First-time setup @@ -41,7 +42,7 @@ export FOXFLOW_ENCRYPTION_KEY="$(openssl rand -hex 32)" npm run dev:with-workflow ``` -Then **Workflow → Engine → Enabled**. Runbook: [docs/WORKFLOW.md](docs/WORKFLOW.md). +Then **Workflow → Engine → Enabled**. Runbook: [docs/workflow.md](docs/workflow.md). For the advanced test schemas (`demo_c` / `demo_d` — FK chains, cross-dialect type matrix, materialized views, etc.): `bash scripts/seed/seed-advanced.sh all`. diff --git a/README.md b/README.md index a9c894062..920ac1fbc 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ Install once, then open the local web UI (`foxschema`) for **Compare**, the **SQL Editor**, **Utils**, **Snapshots**, and optional **Workflow**. Self-host with Docker when you need a server. -[foxschema.com](https://foxschema.com) · [Install](docs/INSTALL.md) · [User guide](docs/USER_GUIDE.md) · [Workflow](docs/WORKFLOW.md) · [Publish](docs/PUBLISH.md) · [Contributing](CONTRIBUTING.md) +[foxschema.com](https://foxschema.com) · [Install](docs/install.md) · [User guide](docs/user-guide.md) · [Workflow](docs/workflow.md) · [Docs](docs/README.md) · [Contributing](CONTRIBUTING.md)

npm @@ -45,7 +45,7 @@ winget install OpenJS.NodeJS.LTS npm install -g foxschema ``` -Full matrix: **[docs/INSTALL.md](docs/INSTALL.md)**. +Full matrix: **[docs/install.md](docs/install.md)**. ## Use the app @@ -83,7 +83,7 @@ A full query workbench next to Schema Sync — not a thin prompt. | **Safe mode** | Confirm writes; bookmarks & samples included | | **Access control** | Optional `admin` / `editor` / `viewer` roles when multi-user login is on | -Walkthrough: [User guide → SQL Editor](docs/USER_GUIDE.md#sql-editor). +Walkthrough: [User guide → SQL Editor](docs/user-guide.md#sql-editor). ## Workflow @@ -97,8 +97,8 @@ export FOXFLOW_ENCRYPTION_KEY="$(openssl rand -hex 32)" npm run dev:with-workflow ``` -Then **Workflow → Engine → Enabled**. Runbook: [docs/WORKFLOW.md](docs/WORKFLOW.md). -User steps: [User guide → Workflow](docs/USER_GUIDE.md#workflow). +Then **Workflow → Engine → Enabled**. Runbook: [docs/workflow.md](docs/workflow.md). +User steps: [User guide → Workflow](docs/user-guide.md#workflow). ## Schema Sync @@ -155,7 +155,7 @@ CommonJS at runtime. Requires **Node ≥ 22.5**. | `apps/workflow-server` | Workflow engine HTTP process (`:8081`) | | `apps/e2e` | Playwright tests against dockerized databases | -Maintainers: [docs/PUBLISH.md](docs/PUBLISH.md) · [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). +Maintainers: [docs/publish.md](docs/publish.md) · [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). ## License diff --git a/apps/cli/README.md b/apps/cli/README.md index fb57e269c..2110974a7 100644 --- a/apps/cli/README.md +++ b/apps/cli/README.md @@ -71,8 +71,8 @@ foxschema tui ## Docs -- [User guide](https://github.com/tedious-code/foxschema/blob/main/docs/USER_GUIDE.md) -- [Install](https://github.com/tedious-code/foxschema/blob/main/docs/INSTALL.md) +- [User guide](https://github.com/tedious-code/foxschema/blob/main/docs/user-guide.md) +- [Install](https://github.com/tedious-code/foxschema/blob/main/docs/install.md) - [Site](https://foxschema.com) ## License diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index ed18881e2..b9c130556 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,7 +1,7 @@ # Architecture reference Stable orientation for FoxSchema. For where a change belongs see -[CODE_MAP.md](CODE_MAP.md). Workflow engine runbook: [WORKFLOW.md](WORKFLOW.md). +[CODE_MAP.md](CODE_MAP.md). Workflow engine runbook: [workflow.md](workflow.md). ## What this is diff --git a/docs/CODE_MAP.md b/docs/CODE_MAP.md index cdde76221..795666e47 100644 --- a/docs/CODE_MAP.md +++ b/docs/CODE_MAP.md @@ -41,7 +41,7 @@ apps/workflow-server The workflow engine's HTTP process (port 8081), plus the server's engine proxy (WORKFLOW_ENGINE_TOKEN); trigger ingress can take a port of its own (INGRESS_PORT). Pulls engine settings from the server. - Runbook: docs/WORKFLOW.md. + Runbook: docs/workflow.md. apps/e2e Browser tests that drive the running application. ``` @@ -156,7 +156,7 @@ database/ The metadata store and its migrations. | `sql-editor` | SQL editor, code cells, sandboxed execution | | `users` | Profile, preferences, first-run wizard | | `workspaces` | Shared workspaces: create, switch, members, invites, public or private (`/api/workspaces`). Which workspace a request acts in is `platform/workspaces`. Admins list every workspace (`GET /all`) and open one only by joining. | -| `workflow` | Workflow engine settings and health; the engine proxy (an allowlist of engine routes, each behind a `workflow.*` permission); saved-connection grants; and the token-guarded internal routes the engine calls to resolve a granted connection and read its settings. Runbook: [WORKFLOW.md](WORKFLOW.md). | +| `workflow` | Workflow engine settings and health; the engine proxy (an allowlist of engine routes, each behind a `workflow.*` permission); saved-connection grants; and the token-guarded internal routes the engine calls to resolve a granted connection and read its settings. Runbook: [workflow.md](workflow.md). | Every feature folder has an `index.ts` exporting its `ServerFeatureModule` and its public API; other features import only that @@ -270,7 +270,7 @@ the page-epoch guard, bookmarks and recents, SQL variables. | Guard or cross-cutting HTTP concern | `packages/server/src/platform/` | | How a dialect lexes SQL (permission gates, splitter) | `packages/sql/src/modules/sql-text/sql-readings.ts` + `sql-tokens.ts`. Do not add a second scanner. | | Workspace membership, invites, public / private | `packages/server/src/features/workspaces/`; request scope is `platform/workspaces`. Services take `WorkspaceScope` (`scopeOf(req)`). | -| Workflow pipe, runtime, or store | `packages/workflow-engine/` — HTTP process in `apps/workflow-server/` ([WORKFLOW.md](WORKFLOW.md)) | +| Workflow pipe, runtime, or store | `packages/workflow-engine/` — HTTP process in `apps/workflow-server/` ([workflow.md](workflow.md)) | ## Checks to run diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index afc6a176a..9e260319e 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -1,7 +1,7 @@ # Deploying Fox Schema **Day-to-day on a laptop:** install the CLI, open the UI in your browser, optionally add a -desktop shortcut (`foxschema shortcut`). See **[INSTALL.md](INSTALL.md)**. +desktop shortcut (`foxschema shortcut`). See **[install.md](install.md)**. ```bash npm install -g foxschema @@ -12,7 +12,7 @@ foxschema # http://localhost:3210 foxschema shortcut ``` -Maintainers: **[PUBLISH.md](PUBLISH.md)**. +Maintainers: **[publish.md](publish.md)**. ### Sign-in + RBAC @@ -47,15 +47,15 @@ and the desktop app alike. Roles are `admin` / `editor` / `owner` / `viewer`. **Admins: One / Several** lives there (`FOX_ADMIN_POLICY` overrides it). Saved connections, snapshots, runs and secrets belong to a **workspace**; every account has a personal one. Admins see every workspace and open one only by - joining. [USER_GUIDE — Workspaces](USER_GUIDE.md#workspaces). + joining. [USER_GUIDE — Workspaces](user-guide.md#workspaces). - Permissions cover Schema Sync (browse / compare / migrate), SQL Editor (sidebar, variables, writes, Data grid insert/update/delete, code cells), Utilities, Secrets, Access, Workflow (`workflow.access` / `design` / `run` / `admin`), and Workspaces (`workspace.members` / `settings` / `create`). Code cells, Git, workflow and `workspace.create` are install-wide (account role); the rest follow the member’s role in the current workspace. - **Database Access** catalog (`POST /schema/db-access`) is an OR gate: **Use utilities** *or* any Access-workspace permission (`access.access`, Users, builder, diff, inspector, report) may load it. GRANT / REVOKE still needs **Grant privileges**. **Servers / teams:** Fox Schema ships as a **single Docker image** (all dialects including Db2) that serves both the UI and the API on one configurable port (default **3210**). -- [Install (all channels)](INSTALL.md) -- [CLI / Homebrew](homebrew.md) +- [Install (all channels)](install.md) +- [CLI / Homebrew](install.md#homebrew-macos) - [Quick start (Docker)](#quick-start) - [Configuration (environment variables)](#configuration-environment-variables) - [The encryption key](#the-encryption-key) @@ -200,7 +200,7 @@ npm -w @foxschema/workflow-server run start:worker # claim queued runs **The published Docker image does not start the engine.** `Dockerfile` / `docker-compose.app.yml` run FoxSchema only. Deploy `apps/workflow-server` beside it (same token on both). Local checkout: `npm run dev:with-workflow`. Full -runbook: [WORKFLOW.md](WORKFLOW.md). +runbook: [workflow.md](workflow.md). ### First-open email subscriber wizard diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..c2f697741 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,75 @@ +# Documentation + +One file per topic. If two pages used to say the same thing, this list names the one to read. + +Living documents describe the tree as it is. Plans and release notes are history: they record why a change was made, and their paths can be stale. + +## Start here + +| Topic | Document | +| --- | --- | +| What the product is and how to install it | [README](../README.md), [install.md](install.md) | +| How to use the app | [user-guide.md](user-guide.md) | +| Where code lives | [CODE_MAP.md](CODE_MAP.md) | +| How the system is put together | [ARCHITECTURE.md](ARCHITECTURE.md) | +| File and symbol names | [CONVENTIONS.md](CONVENTIONS.md) | +| How to work in this repo | [CONTRIBUTING.md](../CONTRIBUTING.md), [AGENTS.md](../AGENTS.md) | + +## Run and ship + +| Topic | Document | +| --- | --- | +| Install channels (npm, Homebrew, Windows, Docker) | [install.md](install.md) | +| Server deploy, env, encryption, SSO | [DEPLOYMENT.md](DEPLOYMENT.md) | +| Workflow engine | [workflow.md](workflow.md) | +| Cutting a release | [publish.md](publish.md) | +| Refresh the Homebrew formula after npm publish | [packaging/homebrew/README.md](../packaging/homebrew/README.md) | +| Dependency updates | [DEPENDENCY_POLICY.md](DEPENDENCY_POLICY.md) | +| Security process | [security/security-process.md](security/security-process.md) | +| Db2 OS user example | [examples/db2-os-user.md](examples/db2-os-user.md) | +| SQL editor examples | [examples/sql-editor/README.md](examples/sql-editor/README.md) | + +Homebrew install steps live only in [install.md](install.md#homebrew-macos). The packaging readme does not repeat them. + +## Architecture (current) + +| Topic | Document | +| --- | --- | +| Repo layout, dialects, migration flow | [ARCHITECTURE.md](ARCHITECTURE.md) | +| HTTP server, logging, what is never logged | [BACKEND_ARCHITECTURE.md](BACKEND_ARCHITECTURE.md) | +| Feature folders and how to add one | [architecture/FEATURE-MODULE-GUIDE.md](architecture/FEATURE-MODULE-GUIDE.md) | +| Which feature may import which | [architecture/FEATURE-DEPENDENCY-RULES.md](architecture/FEATURE-DEPENDENCY-RULES.md) | +| Dialect hooks | [packages/sql/src/providers/DIALECTS.md](../packages/sql/src/providers/DIALECTS.md) | + +## Testing + +| Topic | Document | +| --- | --- | +| How to write an end-to-end test | [testing/WRITING_E2E.md](testing/WRITING_E2E.md) | +| Generated test-id catalog | [testing/TEST_IDS.md](testing/TEST_IDS.md) | + +## Plans (history) + +Finished or in-progress design notes. Do not treat them as the map of the code. The current map is [CODE_MAP.md](CODE_MAP.md). + +| Topic | Document | +| --- | --- | +| Package split (`packages/core` → sql + db) | [plans/package-split.md](plans/package-split.md) | +| Backend moved out of the web app; Express removed | [plans/backend-extraction.md](plans/backend-extraction.md) | +| API layout and the decisions still open | [plans/api-restructure.md](plans/api-restructure.md) | +| Frontend moved to `app/` + `features/` + `shared/` | [plans/frontend-refactor.md](plans/frontend-refactor.md) | +| Feature-module schedule | [plans/2026-10-10-feature-architecture.md](plans/2026-10-10-feature-architecture.md) | +| Workspaces and admin policy | [plans/2026-10-09-workspaces-and-admin-policy.md](plans/2026-10-09-workspaces-and-admin-policy.md) | +| SQL editor | [plans/sql-editor.md](plans/sql-editor.md) | +| Test ids | [plans/2026-10-03-test-ids.md](plans/2026-10-03-test-ids.md) | +| Migrations in Git | [plans/2026-10-02-migrations-in-git.md](plans/2026-10-02-migrations-in-git.md) | +| Seed and migration ordering | [plans/2026-07-01-seed-test-matrix.md](plans/2026-07-01-seed-test-matrix.md), [plans/2026-07-01-migration-ordering-bugs.md](plans/2026-07-01-migration-ordering-bugs.md) | +| Diff colors and safety gates | [plans/2026-06-30-diff-colors-and-safety-gates.md](plans/2026-06-30-diff-colors-and-safety-gates.md) | +| Schema versioning | [plans/schema-versioning-and-revert.md](plans/schema-versioning-and-revert.md) | +| Server beam | [plans/server-beam.md](plans/server-beam.md) | +| Excel and Sheets import | [plans/excel-and-sheets-import.md](plans/excel-and-sheets-import.md) | +| Feature review test plan | [plans/2026-10-06-review-features-test-plan.md](plans/2026-10-06-review-features-test-plan.md) | + +## Releases + +Every shipped version in one page: [releases/SUMMARY.md](releases/SUMMARY.md). The per-version files, listed in [releases/README.md](releases/README.md), are the GitHub Release bodies and are not updated after the version ships. diff --git a/docs/docker-hub-overview.md b/docs/docker-hub-overview.md deleted file mode 100644 index 63cb0b5c8..000000000 --- a/docs/docker-hub-overview.md +++ /dev/null @@ -1,37 +0,0 @@ -# Docker Hub — Fox Schema - -Public image: [5nickels/foxschema](https://hub.docker.com/repository/docker/5nickels/foxschema/tags) - -**Schema Sync + SQL Editor** in one container (compare/migrate schemas, run -multi-destination SQL, Data Peek, FoxScript notebook cells). - -Demo: https://raw.githubusercontent.com/tedious-code/foxschema/main/docs/demo/sql-editor.gif - -## Tags (single image) - -| Tag | Notes | -|-----|--------| -| `latest` | Current release — UI + API, **all dialects including Db2** | -| `vX.Y.Z` | Immutable version pin | - -**Platform:** `linux/amd64` only (`ibm_db` has no linux/arm64 build). On Apple -Silicon, Docker Desktop runs it under emulation, or use the npm/Homebrew CLI. - -There is **no** separate `db2-latest` image anymore. - -## Run - -```bash -docker pull 5nickels/foxschema:latest -docker run -d --name foxschema \ - -p 3210:3210 \ - -v foxschema_data:/data \ - 5nickels/foxschema:latest -``` - -Open http://localhost:3210 — use **SQL Editor** in the top toolbar next to Schema Sync. - -Also on GHCR: `ghcr.io/tedious-code/foxschema:latest` - -Laptop install (npm / Homebrew): [INSTALL.md](INSTALL.md). -Maintainers: [PUBLISH.md](PUBLISH.md). diff --git a/docs/homebrew.md b/docs/homebrew.md deleted file mode 100644 index f6ac6398c..000000000 --- a/docs/homebrew.md +++ /dev/null @@ -1,41 +0,0 @@ -# Homebrew (Fox Schema CLI) - -Formula lives in the **same** GitHub repo (`Formula/foxschema.rb`) — no separate tap repo. - -Homebrew 6+ will not load third-party formulas until you **trust** the tap once -(official `homebrew/core` packages do not need this). - -## Install - -```bash -brew tap tedious-code/foxschema https://github.com/tedious-code/foxschema -brew trust tedious-code/foxschema -brew install foxschema -foxschema # http://localhost:3210 -foxschema shortcut # Fox icon on your Desktop -foxschema stop -``` - -One-liner: - -```bash -brew tap tedious-code/foxschema https://github.com/tedious-code/foxschema \ - && brew trust tedious-code/foxschema \ - && brew install foxschema -``` - -Requires Node.js 22.5+ (the formula depends on Homebrew `node@22`). - -`brew search foxschema` / bare `brew info foxschema` only work **after** the tap -(and trust). Until then Homebrew only knows core formulas. - -One formula / one npm package. Db2 (`ibm_db`) is an optional dependency (installs on -supported platforms). Docker `5nickels/foxschema:latest` includes Db2 on linux/amd64. - -See also: [INSTALL.md](INSTALL.md) · maintainers: [PUBLISH.md](PUBLISH.md). - -## Maintainers - -After each npm release, refresh checksums with -[`packaging/homebrew/update-formula.sh`](../packaging/homebrew/update-formula.sh) -and commit `Formula/foxschema.rb` on `main`. diff --git a/docs/INSTALL.md b/docs/install.md similarity index 89% rename from docs/INSTALL.md rename to docs/install.md index 8381eba3a..557f0843f 100644 --- a/docs/INSTALL.md +++ b/docs/install.md @@ -51,7 +51,7 @@ foxschema foxschema shortcut # Desktop app with fox icon ``` -Details: [homebrew.md](homebrew.md). +`brew search foxschema` works only after the tap and the one-time trust. There is one formula and one npm package. Db2 is optional on npm and included in the Docker image. After an npm release, maintainers refresh the formula with [packaging/homebrew/update-formula.sh](../packaging/homebrew/update-formula.sh). --- @@ -149,10 +149,10 @@ foxschema tui # terminal UI ``` In the UI: **Schema Sync** (compare / migrate) or **SQL Editor** (ad-hoc SQL against -saved connections). Editor walkthrough: [USER_GUIDE.md § SQL Editor](USER_GUIDE.md#sql-editor). +saved connections). Editor walkthrough: [user guide — SQL Editor](user-guide.md#sql-editor). --- ## Publishing (maintainers) -See [PUBLISH.md](PUBLISH.md) for npm, Homebrew, Docker Hub/GHCR, and release tags. +See [publish.md](publish.md) for npm, Homebrew, Docker Hub/GHCR, and release tags. diff --git a/docs/API_RESTRUCTURE_PLAN.md b/docs/plans/api-restructure.md similarity index 99% rename from docs/API_RESTRUCTURE_PLAN.md rename to docs/plans/api-restructure.md index ec325560d..78c6fc9fe 100644 --- a/docs/API_RESTRUCTURE_PLAN.md +++ b/docs/plans/api-restructure.md @@ -14,7 +14,7 @@ in place; the layering is not. Last reconciled against the tree 2026-09-21. | Resource-level authorization (§6) | Not started — highest remaining security value | | Async stores for locks / idempotency / rate limit | Not started — multi-instance prep | | Scope-aware cache (§4) | Not started, deliberately last | -| Remove Express entirely | **Done** — see `docs/BACKEND_EXTRACTION_PLAN.md` §8 | +| Remove Express entirely | **Done** — see `docs/plans/backend-extraction.md` §8 | **Paths below are as-written and now stale.** The tree has moved twice since: out of `apps/web/src/backend/` into `packages/server/src/`, and through a diff --git a/docs/BACKEND_EXTRACTION_PLAN.md b/docs/plans/backend-extraction.md similarity index 100% rename from docs/BACKEND_EXTRACTION_PLAN.md rename to docs/plans/backend-extraction.md diff --git a/docs/FRONTEND_REFACTOR_REVIEW.md b/docs/plans/frontend-refactor.md similarity index 100% rename from docs/FRONTEND_REFACTOR_REVIEW.md rename to docs/plans/frontend-refactor.md diff --git a/docs/plans/restructure.md b/docs/plans/package-split.md similarity index 100% rename from docs/plans/restructure.md rename to docs/plans/package-split.md diff --git a/docs/plans/sql-editor.md b/docs/plans/sql-editor.md index 0f0282dd3..7034d711f 100644 --- a/docs/plans/sql-editor.md +++ b/docs/plans/sql-editor.md @@ -4,7 +4,7 @@ > stale: `packages/core` is now `packages/sql` + `packages/db`; the API lives in > `packages/server` (not `apps/web/src/backend`); SQLite is read-write; ports are > **3210** / **5173**. Current map: [CODE_MAP.md](../CODE_MAP.md). User walkthrough: -> [USER_GUIDE.md](../USER_GUIDE.md#sql-editor). Agent notes: +> [user-guide.md](../user-guide.md#sql-editor). Agent notes: > `.cursor/rules/sql-editor-agent-memory.mdc`. ## Context diff --git a/docs/PUBLISH.md b/docs/publish.md similarity index 98% rename from docs/PUBLISH.md rename to docs/publish.md index 1eba363f5..50f9c8dc8 100644 --- a/docs/PUBLISH.md +++ b/docs/publish.md @@ -1,6 +1,6 @@ # Publishing Fox Schema -How maintainers ship a release. **Users** should follow [INSTALL.md](INSTALL.md). +How maintainers ship a release. **Users** should follow [install.md](install.md). Distribution channels (one product, no separate Db2 edition): diff --git a/docs/releases/README.md b/docs/releases/README.md index bd10f6400..edce006ae 100644 --- a/docs/releases/README.md +++ b/docs/releases/README.md @@ -10,3 +10,5 @@ that, start at [`docs/CODE_MAP.md`](../CODE_MAP.md). They live in their own directory because twelve of them had accumulated in `docs/`, where they outnumbered the documents people actually need to find. + +Every version on one page: [SUMMARY.md](SUMMARY.md). diff --git a/docs/releases/RELEASE_0.2.10.md b/docs/releases/RELEASE_0.2.10.md index 5d4054b8c..6809aad0d 100644 --- a/docs/releases/RELEASE_0.2.10.md +++ b/docs/releases/RELEASE_0.2.10.md @@ -61,7 +61,7 @@ Docker: restart with the **same** `/data` volume. ## Publish checklist (maintainers) -See [PUBLISH.md](PUBLISH.md). Short path: +See [publish.md](../publish.md). Short path: ```bash git fetch origin main && git checkout main && git pull diff --git a/docs/releases/RELEASE_0.2.16.md b/docs/releases/RELEASE_0.2.16.md index c9e390cb2..381012ef6 100644 --- a/docs/releases/RELEASE_0.2.16.md +++ b/docs/releases/RELEASE_0.2.16.md @@ -65,7 +65,7 @@ Docker: restart with the **same** `/data` volume. ## Publish checklist (maintainers) -See [PUBLISH.md](PUBLISH.md). Short path: +See [publish.md](../publish.md). Short path: ```bash git fetch origin main && git checkout main && git pull diff --git a/docs/releases/RELEASE_0.2.33.md b/docs/releases/RELEASE_0.2.33.md index 093c138a7..21976856b 100644 --- a/docs/releases/RELEASE_0.2.33.md +++ b/docs/releases/RELEASE_0.2.33.md @@ -57,7 +57,7 @@ foxschema doctor ## Publish checklist (maintainers) -See [PUBLISH.md](PUBLISH.md). Short path: +See [publish.md](../publish.md). Short path: ```bash git fetch origin main && git checkout main && git pull diff --git a/docs/releases/RELEASE_0.2.36.md b/docs/releases/RELEASE_0.2.36.md index 5cd889348..769d8694e 100644 --- a/docs/releases/RELEASE_0.2.36.md +++ b/docs/releases/RELEASE_0.2.36.md @@ -68,7 +68,7 @@ foxschema doctor ## Publish checklist (maintainers) -See [PUBLISH.md](PUBLISH.md). Short path: +See [publish.md](../publish.md). Short path: ```bash git fetch origin main && git checkout main && git pull diff --git a/docs/releases/RELEASE_0.2.49_50.md b/docs/releases/RELEASE_0.2.49_50.md index b27bc9d7c..187b21f58 100644 --- a/docs/releases/RELEASE_0.2.49_50.md +++ b/docs/releases/RELEASE_0.2.49_50.md @@ -129,7 +129,7 @@ Or: brew update && brew upgrade foxschema ## Maintainers This file is the **GitHub Release body** (`gh release create … --notes-file`). After -publish, the in-app **What's new** link opens that release page. See [PUBLISH.md](PUBLISH.md). +publish, the in-app **What's new** link opens that release page. See [publish.md](../publish.md). ```bash git tag v0.2.49 diff --git a/docs/releases/SUMMARY.md b/docs/releases/SUMMARY.md new file mode 100644 index 000000000..e4c65ee1d --- /dev/null +++ b/docs/releases/SUMMARY.md @@ -0,0 +1,106 @@ +# Release summary + +One page for every version that has ship notes. The full text of a version stays in its own file; those files are history and are not rewritten after the version ships. + +Current map of the product: [CODE_MAP.md](../CODE_MAP.md). How to install: [install.md](../install.md). + +## Not yet shipped + +[UNRELEASED.md](UNRELEASED.md) + +- Snapshots (schema history) and Applies (migration runs) are separate rail items. Utils is its own view. +- Connections, snapshots, secrets, and migration history belong to a workspace. One workspace is active at a time. +- Every install requires sign-in. `foxschema open` on a personal machine can start with a one-time launch link, then asks you to create an account. +- Invites, forgot-password, and Google / GitHub / Microsoft sign-in. SSO accepts only verified emails. +- Migrations in Git, and Utils → Backup & Restore. +- Send feedback opens a pre-filled GitHub issue. Fox Schema does not post it. +- Schema history uses the same definition comparison as Compare. + +## 0.2.111 + +[RELEASE_0.2.111.md](RELEASE_0.2.111.md) — since 0.2.73 + +- Schema History in Schema Sync: snapshot one database, compare versions, revert only the current database after a new snapshot. +- One table blueprint in Compare, Browse, History, and Edit table. Browse is its own pane. +- SQL Editor: copy from result grids, routines stay one cell, Safe mode does not confirm plain reads. +- Db2 reorg after `DROP COLUMN`. Oracle number and sequence generation fixes. +- MongoDB and Redis listed with the other dialects. + +## 0.2.81 + +[RELEASE_0.2.81.md](RELEASE_0.2.81.md) — since 0.2.73 + +- Lokee Weave: schema version graph, capture from a saved credential, name and describe a version. +- Node code cells block `import()` / `eval` breakouts. +- Compare Data can back up and restore when a migrate fails part way. + +## 0.2.73 + +[RELEASE_0.2.73.md](RELEASE_0.2.73.md) — patch on 0.2.72 + +- The credential dialect filter lists every engine, including MongoDB and Redis. +- New credentials default to PostgreSQL. + +## 0.2.72 + +[RELEASE_0.2.72.md](RELEASE_0.2.72.md) — patch on 0.2.71 + +- MongoDB and Redis appear on the credential form and in `foxschema drivers list`. +- Redis honours WHERE on UPDATE/DELETE. MongoDB refuses `WHERE col = NULL` matches on missing fields. + +## 0.2.71 + +[RELEASE_0.2.71.md](RELEASE_0.2.71.md) — since 0.2.50 + +- Maximize, copy, and JSON export on SQL Editor result grids. +- Index renames no longer mark the whole table modified. +- Db2 driver install runs where `require('ibm_db')` actually loads. +- Streaming CSV and incremental NDJSON import. + +## 0.2.49 and 0.2.50 + +[RELEASE_0.2.49_50.md](RELEASE_0.2.49_50.md) — since 0.2.36 + +- Compare data side by side, align rows by key, sync scroll, and export every grid as one CSV. +- Edit rows in SQL Editor result grids when the key is in the result. +- Default port is **3210**. In-app **Update now** installs the latest npm package and restarts. + +## 0.2.36 + +[RELEASE_0.2.36.md](RELEASE_0.2.36.md) — since 0.2.33 + +- The last active admin cannot be demoted or deactivated. +- `packages/core` split into `@foxschema/sql` (dialect knowledge) and `@foxschema/db` (drivers). No change in how the app behaves. + +## 0.2.33 + +[RELEASE_0.2.33.md](RELEASE_0.2.33.md) — since 0.2.31 + +- SQL Editor column picker and automatic table aliases. +- Access control: active flag, admin password change, press-and-hold to show a password. + +## 0.2.16 + +[RELEASE_0.2.16.md](RELEASE_0.2.16.md) — since 0.2.10 + +- `foxschema open` restarts a server that is still the previous version. +- Owner role. Editor write permission split into DML, DDL, and grant. +- CI scans installed packages for dangerous install scripts. + +## 0.2.10 + +[RELEASE_0.2.10.md](RELEASE_0.2.10.md) — ship of 0.2.5 through 0.2.9, since 0.2.4 + +[RELEASE_0.2.9.md](RELEASE_0.2.9.md) describes the same feature set. 0.2.10 is the published cut. + +- Utilities: Query files and Server Insights. +- Editable Data Peek. Roles: admin, editor, viewer. +- CockroachDB migrations drop and recreate dependents around a structural ALTER. +- Desktop Tauri app retired. Use the CLI or Docker. +- Upgrade keeps `/data` and `APP_ENCRYPTION_KEY`. + +## 0.2.0 + +[RELEASE_0.2.0.md](RELEASE_0.2.0.md) + +- SQL Editor next to schema compare: multi-destination run, notebook cells, FoxScript, and Data Peek. diff --git a/docs/releases/UNRELEASED.md b/docs/releases/UNRELEASED.md index 40a41b26b..dc7e49f25 100644 --- a/docs/releases/UNRELEASED.md +++ b/docs/releases/UNRELEASED.md @@ -225,7 +225,7 @@ for the credential at the top of the workspace. backups they recorded; pick one and the restore reads it. Restores still only open in the SQL Editor. -See [USER_GUIDE.md](../USER_GUIDE.md#utilities). +See [user-guide.md](../user-guide.md#utilities). ## Access: Grants show what is held diff --git a/docs/USER_GUIDE.md b/docs/user-guide.md similarity index 99% rename from docs/USER_GUIDE.md rename to docs/user-guide.md index e4933e309..e4c050d7e 100644 --- a/docs/USER_GUIDE.md +++ b/docs/user-guide.md @@ -45,7 +45,7 @@ foxschema # http://localhost:3210 foxschema shortcut # optional Fox icon on your Desktop ``` -Full install matrix (npm, Homebrew, Winget, Docker, curl/wget): [INSTALL.md](INSTALL.md). +Full install matrix (npm, Homebrew, Winget, Docker, curl/wget): [install.md](install.md). **Option B — Docker (shared/team server):** @@ -68,7 +68,7 @@ Fox Schema checks npm for a newer `foxschema` version when you open the UI. You can also use **User Preference → Update now**. Docker / Homebrew / locked-down servers get **Copy command** (or use -`brew upgrade foxschema` / `docker pull …:latest` — see [INSTALL.md](INSTALL.md)). +`brew upgrade foxschema` / `docker pull …:latest` — see [install.md](install.md)). ## First run @@ -626,7 +626,7 @@ Optional workspace for scheduled and triggered jobs (SQL, HTTP, files, email/SMS beside Compare and the SQL Editor. The designer lives in the Fox Schema UI; a **separate engine process** runs the jobs. -Developer / ops runbook: [WORKFLOW.md](WORKFLOW.md). Env vars: +Developer / ops runbook: [workflow.md](workflow.md). Env vars: [DEPLOYMENT.md](DEPLOYMENT.md#workflow-engine). 1. Start the engine beside Fox Schema (`npm run dev:with-workflow` in a checkout, @@ -875,6 +875,6 @@ separate process. Check **Workflow → Engine** health. New installs default to engine boot. Saved connections need both `WORKFLOW_ENGINE_TOKEN` (same value on FoxSchema and the engine) and an explicit grant (pick the connection on a SQL pipe). The published Docker image does not start the engine. See -[WORKFLOW.md](WORKFLOW.md). +[workflow.md](workflow.md). Still stuck? Open a GitHub issue with what you did and the error you saw. diff --git a/docs/WORKFLOW.md b/docs/workflow.md similarity index 99% rename from docs/WORKFLOW.md rename to docs/workflow.md index 1359b87fb..e10794f64 100644 --- a/docs/WORKFLOW.md +++ b/docs/workflow.md @@ -4,7 +4,7 @@ FoxSchema designs and administers workflows in the web UI. A **separate process* (`apps/workflow-server`) runs them, so a slow or failing job never shares a process with Schema Sync or the SQL Editor. -User walkthrough: [USER_GUIDE.md](USER_GUIDE.md#workflow). Deploy env vars: +User walkthrough: [user-guide.md](user-guide.md#workflow). Deploy env vars: [DEPLOYMENT.md](DEPLOYMENT.md#workflow-engine). Folder map: [CODE_MAP.md](CODE_MAP.md). ## Architecture diff --git a/packages/server/src/features/compare/compare.controller.ts b/packages/server/src/features/compare/compare.controller.ts index 2bfd0a452..e5158c00b 100644 --- a/packages/server/src/features/compare/compare.controller.ts +++ b/packages/server/src/features/compare/compare.controller.ts @@ -29,7 +29,7 @@ export function makeCompareController(deps: { * This layer exists as the place where cross-cutting work runs before the * service: resource-level authorization and the scope-aware cache both * attach here, so an endpoint cannot skip them. See - * docs/API_RESTRUCTURE_PLAN.md §4 and §6. + * docs/plans/api-restructure.md §4 and §6. */ compare(input, actor) { return deps.compareService.compare(input, actor); diff --git a/packages/shared/src/doc-paths.test.ts b/packages/shared/src/doc-paths.test.ts index 09b38051a..71fc0f66a 100644 --- a/packages/shared/src/doc-paths.test.ts +++ b/packages/shared/src/doc-paths.test.ts @@ -23,7 +23,7 @@ * and drifted twice). * * Scope is deliberately the *navigational* docs only. Plan and release - * documents are history — `docs/API_RESTRUCTURE_PLAN.md` says in its own header + * documents are history — `docs/plans/api-restructure.md` says in its own header * that its paths are stale and kept as the record of why, which is a legitimate * thing for a document to be. Those are not scanned. */ @@ -165,7 +165,7 @@ describe('navigational docs point at paths that exist', () => { describe('Express is gone and the docs say so', () => { /** - * Express was removed wholesale (see `docs/BACKEND_EXTRACTION_PLAN.md` §8). + * Express was removed wholesale (see `docs/plans/backend-extraction.md` §8). * The navigational docs described it as the running server for months * afterwards. This fails if that language comes back while no workspace * actually depends on Express — the combination that misleads. diff --git a/packaging/homebrew/README.md b/packaging/homebrew/README.md index 3d9c774a7..c6491aee5 100644 --- a/packaging/homebrew/README.md +++ b/packaging/homebrew/README.md @@ -5,18 +5,7 @@ There is **no** separate `homebrew-foxschema` tap. ## Install (users) -```bash -brew tap tedious-code/foxschema https://github.com/tedious-code/foxschema -brew trust tedious-code/foxschema # required once on Homebrew 6+ -brew install foxschema -foxschema -foxschema shortcut # optional Fox icon on Desktop -``` - -Requires Homebrew’s `node@22` (or newer Node 22+ on PATH after link). - -Same npm package as `npm i -g foxschema`. Docker image: -`5nickels/foxschema:latest` (linux/amd64, includes Db2). +User install for every channel, including Homebrew, is [docs/install.md](../../docs/install.md). This file is only how to refresh the formula after a release. ## Updating after an npm release