From 79042f18d9df6e8815236ddfd37ba6b2fa1fa529 Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Sun, 15 Nov 2026 18:18:52 +0000 Subject: [PATCH 1/2] docs(fork): list fork changes and settings, pinned to the defaults table FORK_CHANGES.md lists each fork change (what, why, setting, default, PR). docs/fork/README.md lists each fork setting (what it does, default, how to switch it on) and how to install the fork today. forkDocs.test.ts reads FORK_SETTING_DEFAULTS (one source) and fails when a fork setting has no README row or section, a row names no setting or differs from its pin, or FORK_CHANGES.md misses or invents a setting. Co-Authored-By: Claude Opus 5.5 --- FORK_CHANGES.md | 58 ++++++++ docs/fork/README.md | 203 +++++++++++++++++++++++++++ docs/fork/updates.md | 3 + packages/shared/src/forkDocs.test.ts | 101 +++++++++++++ 4 files changed, 365 insertions(+) create mode 100644 FORK_CHANGES.md create mode 100644 docs/fork/README.md create mode 100644 packages/shared/src/forkDocs.test.ts diff --git a/FORK_CHANGES.md b/FORK_CHANGES.md new file mode 100644 index 0000000000000..83ae5032ac685 --- /dev/null +++ b/FORK_CHANGES.md @@ -0,0 +1,58 @@ +# Fork changes + +This repository is a fork of [T3 Code](https://github.com/pingdotgg/t3code). This page lists every +change the fork makes, one line each: what it does, why, its setting and default, and the pull +requests. The fork's settings are explained in [docs/fork/README.md](docs/fork/README.md), which also +says how to install the fork today. + +The rule for every change: a machine that never names a fork setting behaves as upstream's T3 Code. +A setting is written as `server.` (the server's `settings.json`) or `projectOverride.` +(one project's overrides). A test (`packages/shared/src/forkDocs.test.ts`) fails when a fork setting +is missing here or a setting named here does not exist. + +## In T3 Code itself + +| Change | Why | Setting | Default | PR | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| The server, the CLI and the desktop app look for updates in this fork's releases, not upstream's. | A fork build must never "update" to an upstream build and lose the fork's changes. | none | always | [#1](https://github.com/scuttletoby/t3code/pull/1) | +| A server installed as a boot service can update itself once no thread is working, after an optional "is it quiet?" command agrees. | Updates without someone watching, and without cutting off running work. | `server.automaticUpdates`, `server.automaticUpdatesQuietCommand` | off | [#5](https://github.com/scuttletoby/t3code/pull/5) | +| Every fork setting has a pinned default, and lives in the fork's own file (`forkSettings.ts`). | An upstream sync can never switch a fork feature on, and a new setting touches no upstream file. | none | always | [#171](https://github.com/scuttletoby/t3code/pull/171), [#185](https://github.com/scuttletoby/t3code/pull/185) | +| The server keeps a history of each provider account's usage-limit readings. | Pacing needs to know how fast a limit is being used, not only where it stands. | none | always (read only) | [#24](https://github.com/scuttletoby/t3code/pull/24) | +| The server reads usage limits every 10 minutes while no app is open. | Pacing has current numbers on a machine nobody is looking at. | `server.headlessUsageRefreshInterval` | on (10 minutes); read only | [#42](https://github.com/scuttletoby/t3code/pull/42) | +| Usage pacing: a reserve of each limit window kept free for the person, and an even pace for agents. | Agents should not use up a subscription before its owner needs it. | `server.usagePacing` | off | [#52](https://github.com/scuttletoby/t3code/pull/52) | +| The pacing gate on `delegate_task`: advise only, or move, lower the effort of, or hold a task on an account that is ahead of pace. | Delegated work follows the pace without the agent having to check. | `server.usagePacingGate`, `server.usagePacingLowerEffort` | off | [#73](https://github.com/scuttletoby/t3code/pull/73) | +| Agent slots: `delegate_task` is refused above a number of running agents per machine or account, or below a memory floor. | Too many agents at once can overload a small machine. | `server.agentSlots` | off | [#84](https://github.com/scuttletoby/t3code/pull/84), [#89](https://github.com/scuttletoby/t3code/pull/89) | +| Waits: agents can wait for a pull request, a file, a system unit, a named check command or a free agent slot (`wait_for`, `wait_list`, `wait_cancel`), and are woken when it happens. | An agent no longer polls or sleeps while it waits. | `server.waitFor`, `server.waitChecks`, `projectOverride.waitChecks` | off | [#84](https://github.com/scuttletoby/t3code/pull/84), [#90](https://github.com/scuttletoby/t3code/pull/90), [#91](https://github.com/scuttletoby/t3code/pull/91), [#103](https://github.com/scuttletoby/t3code/pull/103), [#106](https://github.com/scuttletoby/t3code/pull/106), [#109](https://github.com/scuttletoby/t3code/pull/109), [#110](https://github.com/scuttletoby/t3code/pull/110), [#116](https://github.com/scuttletoby/t3code/pull/116), [#119](https://github.com/scuttletoby/t3code/pull/119) | +| Settings pages for waits, wait checks and agent slots. | Switch these on without editing a file. | `server.waitFor`, `server.waitChecks`, `server.agentSlots` | off | [#104](https://github.com/scuttletoby/t3code/pull/104) | +| The fork's checks on `delegate_task` (pacing, slots) sit behind one fork module. | Fewer fork lines in upstream's code, so syncs conflict less. No change in behaviour. | none | always | [#174](https://github.com/scuttletoby/t3code/pull/174) | +| A pure capacity rule for "dynamic slots" (one budget per machine), with shared test cases. Not wired into anything yet. | A later step replaces fixed agent counts with what the machine can take. | none | not used | [#203](https://github.com/scuttletoby/t3code/pull/203) | +| File links in chat open in the files viewer, full size, or in an editor on a remote machine, and can be downloaded, from their menu. | File links were only copyable on remote machines and had no menu on touch screens. | none | always | [#17](https://github.com/scuttletoby/t3code/pull/17) | +| A hidden read-only command, `t3 __fork-report --base-dir `, prints what a T3 home holds and which fork features are on. | The go-live kit checks a build and a home before switching, without writing anything. | none | only when run | [#172](https://github.com/scuttletoby/t3code/pull/172), [#184](https://github.com/scuttletoby/t3code/pull/184) | +| `t3 serve --hold-work` starts a server on a copy of a T3 home with all agent work held. | Look at a new build's threads and migrations on a copy before it replaces a running T3. | none | only with the flag | [#175](https://github.com/scuttletoby/t3code/pull/175) | +| Docs: one machine for new work through upstream's load-balancing weights; settings saved with an early draft's client setting for it still load. | Upstream already has the feature, so the fork's own setting was removed. | none | - | [#25](https://github.com/scuttletoby/t3code/pull/25) | + +## Repository, CI and releases + +These change only how this repository is built, tested and released, not the app. + +| Change | Why | Setting | Default | PR | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Fork release workflow: builds `v.fork.` with the Linux and Windows CLI archives and unsigned desktop apps. | The fork needs its own releases to install and update from. | none | run by hand or by fork-follow | [#2](https://github.com/scuttletoby/t3code/pull/2) | +| fork-follow: once a day, rebase the fork onto upstream's newest tag, test, and release only when green; on trouble, open one issue. | Stay close to upstream without manual work. | repository variable `FORK_FOLLOW_CHANNEL` | `nightly` | [#4](https://github.com/scuttletoby/t3code/pull/4), [#22](https://github.com/scuttletoby/t3code/pull/22), [#66](https://github.com/scuttletoby/t3code/pull/66) | +| Fork tests: upstream's test jobs, run on GitHub-hosted runners or on the repository's own machines chosen per run. | Fast CI that does not need upstream's runner labels. | repository variable `CI_RUNNERS` | `auto` | [#6](https://github.com/scuttletoby/t3code/pull/6), [#8](https://github.com/scuttletoby/t3code/pull/8), [#13](https://github.com/scuttletoby/t3code/pull/13) | +| Fleet runners: one-job runners started on demand on the repository's own machines, each behind walls, plus a link from a desktop machine. | Use spare machines for CI without letting a job reach the host. | repository variable `CI_RUNNERS` | `auto` | [#53](https://github.com/scuttletoby/t3code/pull/53), [#74](https://github.com/scuttletoby/t3code/pull/74), [#191](https://github.com/scuttletoby/t3code/pull/191), [#192](https://github.com/scuttletoby/t3code/pull/192), [#194](https://github.com/scuttletoby/t3code/pull/194), [#195](https://github.com/scuttletoby/t3code/pull/195), [#196](https://github.com/scuttletoby/t3code/pull/196), [#197](https://github.com/scuttletoby/t3code/pull/197), [#198](https://github.com/scuttletoby/t3code/pull/198), [#205](https://github.com/scuttletoby/t3code/pull/205), [#208](https://github.com/scuttletoby/t3code/pull/208) | +| Checks that refuse database schema and migration changes, fork changes to some upstream files, and fork lines outside the pinned seams. | Keep the fork thin, so upstream syncs stay easy and a database never needs a fork step. | none | always | [#3](https://github.com/scuttletoby/t3code/pull/3), [#97](https://github.com/scuttletoby/t3code/pull/97), [#185](https://github.com/scuttletoby/t3code/pull/185) | +| Pull requests from outside run nothing; four outside-started upstream workflows and `issue-vouch.yml` are deleted and kept deleted. | No code from an outside pull request runs with this repository's runners or tokens. | none | always | [#12](https://github.com/scuttletoby/t3code/pull/12), [#14](https://github.com/scuttletoby/t3code/pull/14), [#23](https://github.com/scuttletoby/t3code/pull/23) | +| A weekly check that the repository's interaction limit never lapses. | Outsiders cannot post while the limit holds. | none | always | [#30](https://github.com/scuttletoby/t3code/pull/30) | +| Secret scan on every push and pull request. | The fork is public: no token or key may land in it. | none | always | [#75](https://github.com/scuttletoby/t3code/pull/75), [#206](https://github.com/scuttletoby/t3code/pull/206), [#207](https://github.com/scuttletoby/t3code/pull/207), [#212](https://github.com/scuttletoby/t3code/pull/212) | +| fork-ci: CI actions any repository can pin (docs-scope, gradle-cache, job-changed, fleet-route, ci-demand, pinned), with their own releases. | Shared CI building blocks, kept general. | none | only where pinned | [#15](https://github.com/scuttletoby/t3code/pull/15), [#16](https://github.com/scuttletoby/t3code/pull/16), [#27](https://github.com/scuttletoby/t3code/pull/27), [#35](https://github.com/scuttletoby/t3code/pull/35), [#55](https://github.com/scuttletoby/t3code/pull/55), [#94](https://github.com/scuttletoby/t3code/pull/94), [#113](https://github.com/scuttletoby/t3code/pull/113), [#141](https://github.com/scuttletoby/t3code/pull/141) | +| fork-ci PR queue: merges armed pull requests in order once their reviews and checks pass. | Merges without someone watching each pull request. | none | only where used | [#18](https://github.com/scuttletoby/t3code/pull/18), [#19](https://github.com/scuttletoby/t3code/pull/19), [#20](https://github.com/scuttletoby/t3code/pull/20), [#21](https://github.com/scuttletoby/t3code/pull/21), [#32](https://github.com/scuttletoby/t3code/pull/32), [#61](https://github.com/scuttletoby/t3code/pull/61), [#70](https://github.com/scuttletoby/t3code/pull/70), [#71](https://github.com/scuttletoby/t3code/pull/71) | +| fork-ci head check and head gate: the queue's required check, posted by a GitHub App and judged by the default branch's code. | A pull request cannot fake its own required check. See [gate trust](docs/fork/gate-trust.md). | none | only where used | [#33](https://github.com/scuttletoby/t3code/pull/33), [#85](https://github.com/scuttletoby/t3code/pull/85), [#87](https://github.com/scuttletoby/t3code/pull/87) | +| Host kits (`fork-kit/`): `gh-apps` (GitHub App tokens for agents), `heavy` (run builds in a capped slice), `golive` (move a boot service to a new build; core and `check` so far). | Things the fork installs on a machine, each with an installer, a self-check and tests. | none | only when installed | [#86](https://github.com/scuttletoby/t3code/pull/86), [#173](https://github.com/scuttletoby/t3code/pull/173), [#182](https://github.com/scuttletoby/t3code/pull/182), [#183](https://github.com/scuttletoby/t3code/pull/183) | +| Design notes: host tools (agents on a person's own computer). | Design for review; no code yet. | none | - | [#26](https://github.com/scuttletoby/t3code/pull/26) | + +## Adding a line + +A pull request that adds or changes a fork feature adds or changes its line here. A new fork setting +also needs its row in `packages/contracts/src/forkDefaults.ts` and its row and section in +[docs/fork/README.md](docs/fork/README.md) (steps in [updates.md](docs/fork/updates.md#adding-a-fork-setting)). diff --git a/docs/fork/README.md b/docs/fork/README.md new file mode 100644 index 0000000000000..01bbed717faa5 --- /dev/null +++ b/docs/fork/README.md @@ -0,0 +1,203 @@ +# The fork: settings and install + +Fork only. This fork is T3 Code with a thin set of changes on top; every change is listed in +[FORK_CHANGES.md](../../FORK_CHANGES.md). This page lists every fork setting: what it does, its +default, and how to switch it on. Then it says how to install the fork today. + +The rule: a machine whose settings never name a fork setting behaves as upstream's T3 Code. Every +fork switch is off by default, except one read-only refresh of usage limits. + +## Where settings live + +Server settings are in `settings.json` in the server's `userdata` folder (by default +`~/.t3/userdata/settings.json`). The server reads the file again when it changes; no restart is +needed. Some fork settings also have a row in the app's **Settings** pages (named below). A +project's overrides are set in **Settings** with that project chosen at the top ("Applying settings +for …", see [project settings](../user/project-settings.md)). An agent's tools cannot change any +fork setting. + +To check what a T3 home has switched on without changing anything, the fork's hidden command +`t3 __fork-report --base-dir ` prints it as JSON. + +## Settings + +The defaults, "off" and "decided in" below come from one table in the code, +[`packages/contracts/src/forkDefaults.ts`](../../packages/contracts/src/forkDefaults.ts). A test +(`packages/shared/src/forkDocs.test.ts`) fails when this table and that one differ, or a setting has +no section below. "Off" means the default leaves the machine as upstream's would be. + +| Setting | Default | Off | Decided in | +| ---------------------------------------------------------------------------- | ------------------- | --- | ------------------------------------------------------ | +| [`server.automaticUpdates`](#serverautomaticupdates) | `false` | yes | [#41](https://github.com/scuttletoby/t3code/issues/41) | +| [`server.automaticUpdatesQuietCommand`](#serverautomaticupdatesquietcommand) | `""` | yes | [#5](https://github.com/scuttletoby/t3code/issues/5) | +| [`server.usagePacing`](#serverusagepacing) | `{}` | yes | [#52](https://github.com/scuttletoby/t3code/issues/52) | +| [`server.usagePacingGate`](#serverusagepacinggate) | `"off"` | yes | [#73](https://github.com/scuttletoby/t3code/issues/73) | +| [`server.usagePacingLowerEffort`](#serverusagepacinglowereffort) | `{}` | yes | [#73](https://github.com/scuttletoby/t3code/issues/73) | +| [`server.waitFor`](#serverwaitfor) | `{"enabled":false}` | yes | [#84](https://github.com/scuttletoby/t3code/issues/84) | +| [`server.waitChecks`](#serverwaitchecks) | `{}` | yes | [#84](https://github.com/scuttletoby/t3code/issues/84) | +| [`server.agentSlots`](#serveragentslots) | `{"enabled":false}` | yes | [#84](https://github.com/scuttletoby/t3code/issues/84) | +| [`server.headlessUsageRefreshInterval`](#serverheadlessusagerefreshinterval) | `600000` | no | [#42](https://github.com/scuttletoby/t3code/issues/42) | +| [`projectOverride.waitChecks`](#projectoverridewaitchecks) | not set | yes | [#84](https://github.com/scuttletoby/t3code/issues/84) | + +For `waitFor` and `agentSlots` only the `enabled` switch is pinned; their other fields are tuning +that does nothing while the switch is off. + +## Each setting + +### `server.automaticUpdates` + +A server installed as a boot service (`t3 service install`) updates itself to the newest fork release +once no thread is working. Off: it updates only when someone runs `t3 update` or presses **Update**. +Upstream has a setting of the same name that defaults on; the fork keeps `false` through every sync. + +Switch on in `settings.json`: `"automaticUpdates": true`. There is no Settings row for it yet. An +admin policy with updates `"off"` still wins. Details: [updates.md](updates.md). + +### `server.automaticUpdatesQuietCommand` + +An optional program asked before each automatic update; a non-zero exit means "not now". Used only +while `automaticUpdates` is on. Empty: no program is asked. + +Set in `settings.json`: `"automaticUpdatesQuietCommand": "/path/to/quiet-check"`. Details: +[updates.md](updates.md). + +### `server.usagePacing` + +Per provider instance (account): `reservePercent` keeps that many points of each limit window free +for the person, released over the window's last 12 hours; `burnFirst` spends this account first; +`noLimits` says the account has no usage limits (an API key). An account without an entry has no +reserve. Only the pacing gate (`usagePacingGate`) acts on it. + +Set in `settings.json`: + +```json +{ "usagePacing": { "": { "reservePercent": 20 } } } +``` + +The key is the provider instance id, for example `codex` or `codex_work`. There is no Settings row for it yet. + +### `server.usagePacingGate` + +What happens when an agent starts a task with `delegate_task`. `"off"`: nothing, as upstream. +`"advise"`: the task starts as asked and the reply carries a note about the pace. `"enforce"`: a task +on an account that is ahead of its pace moves to another account of the same provider, runs at a +lower effort (`usagePacingLowerEffort`), or is refused for now and the agent asks again later. + +Switch on in `settings.json`: `"usagePacingGate": "advise"` (try `advise` before `enforce`). There +is no Settings row for it yet. + +### `server.usagePacingLowerEffort` + +For `"enforce"`: what each effort level turns into while an account is ahead of pace and no other +account has room, for example `{ "high": "medium", "medium": "medium" }`. A task at a level not +listed is held instead. Empty: no effort is ever lowered. + +Set in `settings.json`: `"usagePacingLowerEffort": { "high": "medium" }`. + +### `server.waitFor` + +Waits: an agent calls `wait_for` to wait for a pull request (checks done or merged), a file (there or +gone), a system unit, a named check command (`waitChecks`) or a free agent slot, and its thread is +woken with the result. `wait_list` and `wait_cancel` list and end them. While off, waits are neither +judged nor delivered; listing and cancelling still work. Other fields set deadlines, limits per +thread and how often each kind is checked. + +Switch on: **Settings → Waits**, "Let agents wait for events", or in `settings.json`: +`"waitFor": { "enabled": true }`. + +### `server.waitChecks` + +Named commands an agent can wait on by name (`wait_for` with a check). Each runs as a program with +fixed arguments, no shell; exit 0 means the event happened. It runs unsandboxed in the project folder +with the server's environment, so use fixed programs that run no files from the repository (no test +runners or build scripts). Only the person can add one; agents cannot. + +Add one: **Settings → Wait checks → Add check**, or in `settings.json`: + +```json +{ "waitChecks": { "build-done": { "argv": ["test", "-f", "/tmp/build.done"] } } } +``` + +Used only while `waitFor` is on. + +### `server.agentSlots` + +Limits on running agents: `delegate_task` is refused above `maxPerMachine` agents on this server, +above `maxPerAccount` per provider account, or below `minFreeMemoryMb` of free memory. Threads +started in other ways are counted but never refused. With `waitFor` on, an agent can wait for a slot +instead of retrying. + +Switch on: **Settings → Agent slots**, "Limit running agents", or in `settings.json`: +`"agentSlots": { "enabled": true, "maxPerMachine": 4 }`. With `enabled` and no limits set, nothing is +refused. + +### `server.headlessUsageRefreshInterval` + +How often the server reads usage limits while no app is open, in milliseconds. On by default every +10 minutes, so pacing has current numbers on a machine nobody is looking at. Read only: it changes no +thread, setting or install. Never more often than the provider status refresh. + +Switch off in `settings.json`: `"headlessUsageRefreshInterval": 0`. + +### `projectOverride.waitChecks` + +A project's own list of wait checks. It replaces the server's list for that project as a whole (a +project lists every check it uses). Not set: the project uses the server's checks. + +Set: **Settings**, choose the project at the top, then **Wait checks**. + +### A setting the fork removed + +An early draft had a client setting for one "anchor machine" for new work. It was removed before it +shipped: upstream's load balancing does the same. Settings saved with it still load. See +[anchor-machine.md](anchor-machine.md). + +## Install the fork today + +There is no one-line installer for the fork yet: `t3.codes/install.sh` and upstream's docs install +upstream's T3 Code. Two ways work today. + +**From a fork release (Linux x64).** The [fork's releases](https://github.com/scuttletoby/t3code/releases) +have the CLI archive for Linux x64 and Windows x64, and desktop apps for Linux, Windows and macOS. +The desktop apps are not signed, so macOS and Windows warn before they open. On Linux, the +installer script takes a mirror and an exact version: + +```sh +curl -fsSL https://raw.githubusercontent.com/scuttletoby/t3code/main/scripts/install.sh \ + | T3CODE_VERSION= \ + T3CODE_RELEASE_BASE_URL=https://github.com/scuttletoby/t3code/releases/download sh +``` + +`t3 update` on a fork build then looks only at the fork's releases. Every fork switch starts off. + +**From source.** Same as upstream's [development setup](../operations/development.md#first-checkout), +with this repository: + +```sh +git clone https://github.com/scuttletoby/t3code +cd t3code && vp i && vp run build:desktop +node apps/server/dist/bin.mjs +``` + +A server run this way is not updated by `t3 update` or a boot service; update it with `git pull` and +a rebuild. + +**A machine that already runs T3 as a boot service.** Do not switch it by hand. The go-live kit +([fork-kit/golive](../../fork-kit/golive/README.md)) is for this: today it has only its read-only +`check`. Its copy, rehearsal on the copy, switch and way back are not written yet, and the kits are +not yet installable from the release branch. Until then, try a build on a copy with +`t3 serve --hold-work --base-dir ` ([updates.md](updates.md#trying-a-build-on-a-copy-serve---hold-work)). + +Not there yet: a fork installer URL, a macOS CLI archive, signed desktop apps, and the go-live +switch. + +## Other fork pages + +- [updates.md](updates.md): update defaults, how a test pins them, the nightly sync runbook, + `serve --hold-work`. +- [anchor-machine.md](anchor-machine.md): one machine for new work, with upstream load balancing. +- [gate-trust.md](gate-trust.md): what the head gate proves, and the owner's steps. +- [host-tools.md](host-tools.md): design for agents on a person's own computer (no code yet). +- [`.github/fork-fleet.md`](../../.github/fork-fleet.md): the fleet runners and `CI_RUNNERS`. +- [`fork-ci/README.md`](../../fork-ci/README.md) and [`fork-kit/README.md`](../../fork-kit/README.md): + CI actions and host kits. diff --git a/docs/fork/updates.md b/docs/fork/updates.md index a98e2931ec6a2..bc32839597fbf 100644 --- a/docs/fork/updates.md +++ b/docs/fork/updates.md @@ -57,6 +57,9 @@ watches; it changes nothing on the machine, and `0` turns it off. that decision as `decidedIn`. 4. An agent tool may not write it: `FORK_AGENT_WRITABLE_KEYS` stays empty unless a pull request gives the reason. +5. Add its row and section to [README.md](README.md) and name it in + [FORK_CHANGES.md](../../FORK_CHANGES.md); `packages/shared/src/forkDocs.test.ts` fails until both + match the row in `forkDefaults.ts`. A key written straight into `settings.ts` is refused by the seam check, whatever its comment says. diff --git a/packages/shared/src/forkDocs.test.ts b/packages/shared/src/forkDocs.test.ts new file mode 100644 index 0000000000000..4c87ea8056581 --- /dev/null +++ b/packages/shared/src/forkDocs.test.ts @@ -0,0 +1,101 @@ +// @effect-diagnostics nodeBuiltinImport:off - reads the fork's docs from the repository. +/// + +// Fork: the fork's settings docs follow the one pin table (forkDefaults.ts), so a new fork setting +// without a docs row, or a docs row for a setting that does not exist, fails here. +import { FORK_SETTING_DEFAULTS, type ForkSettingDefault } from "@t3tools/contracts/forkDefaults"; +import * as NodeFS from "node:fs"; +import { describe, expect, it } from "vite-plus/test"; + +const repoFile = (path: string) => + NodeFS.readFileSync(new URL(`../../../${path}`, import.meta.url), "utf8"); + +const README = repoFile("docs/fork/README.md"); +const CHANGES = repoFile("FORK_CHANGES.md"); + +const rowId = (row: ForkSettingDefault) => `${row.scope}.${row.key}`; +const pinned = FORK_SETTING_DEFAULTS.map(rowId).toSorted(); +const byId = new Map(FORK_SETTING_DEFAULTS.map((row) => [rowId(row), row] as const)); + +/** A setting as the docs write it: `server.`, `projectOverride.` or `client.`. */ +const SETTING_ID = /`((?:server|projectOverride|client)\.[A-Za-z0-9]+)`/gu; + +/** The lines of one `## ` section, without its heading. */ +function section(markdown: string, heading: string): ReadonlyArray { + const lines = markdown.split("\n"); + const start = lines.indexOf(`## ${heading}`); + if (start === -1) throw new Error(`docs/fork/README.md has no "## ${heading}" section`); + const end = lines.findIndex((line, index) => index > start && line.startsWith("## ")); + return lines.slice(start + 1, end === -1 ? undefined : end); +} + +interface TableRow { + readonly line: string; + readonly cells: ReadonlyArray; +} + +/** Body rows of the first table in `lines` (no header, no separator). */ +function tableRows(lines: ReadonlyArray): ReadonlyArray { + const first = lines.findIndex((line) => line.startsWith("|")); + if (first === -1) return []; + const table = lines.slice(first); + const last = table.findIndex((line) => !line.startsWith("|")); + return table.slice(2, last === -1 ? undefined : last).map((line) => ({ + line, + cells: line + .split("|") + .slice(1, -1) + .map((cell) => cell.trim()), + })); +} + +/** The default cell as the README writes it: the settings file's JSON, or "not set". */ +const defaultCell = (row: ForkSettingDefault) => + row.default === undefined ? "not set" : `\`${JSON.stringify(row.default)}\``; + +const settingRows = tableRows(section(README, "Settings")); + +describe("fork settings docs (docs/fork/README.md)", () => { + it("has one table row for each fork setting and none for anything else", () => { + // A row whose first cell names no setting counts as "(no setting)" and fails the comparison. + const ids = settingRows.map( + (row) => [...row.cells[0]!.matchAll(SETTING_ID)][0]?.[1] ?? row.line, + ); + expect(ids.toSorted()).toEqual(pinned); + }); + + it.each(settingRows.map((row) => [row.cells[0]!, row] as const))( + "row %s matches its pin", + (_label, { cells }) => { + const id = [...cells[0]!.matchAll(SETTING_ID)][0]?.[1] ?? ""; + const row = byId.get(id); + expect(row, `no fork setting ${id}`).toBeDefined(); + if (row === undefined) return; + expect(cells[0]).toBe(`[\`${id}\`](#${id.toLowerCase().replace(".", "")})`); + expect(cells[1]).toBe(defaultCell(row)); + expect(cells[2]).toBe(row.off ? "yes" : "no"); + expect(cells[3]).toBe( + `[${row.decidedIn}](https://github.com/scuttletoby/t3code/issues/${row.decidedIn.slice(1)})`, + ); + }, + ); + + it("has one section for each fork setting", () => { + const headings = section(README, "Each setting") + .map((line) => /^### `([^`]+)`$/u.exec(line)?.[1]) + .filter((id) => id !== undefined); + expect(headings.toSorted()).toEqual(pinned); + }); +}); + +describe("fork changes list (FORK_CHANGES.md)", () => { + const named = new Set([...CHANGES.matchAll(SETTING_ID)].map((match) => match[1]!)); + + it("names every fork setting", () => { + expect(pinned.filter((id) => !named.has(id))).toEqual([]); + }); + + it("names no setting that does not exist", () => { + expect([...named].filter((id) => !byId.has(id))).toEqual([]); + }); +}); From 1e5794de50c572c61910c7d1ecfd8c59e3bb290a Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Sun, 15 Nov 2026 18:42:26 +0000 Subject: [PATCH 2/2] docs(fork): fix three README statements from review Upstream's automaticUpdates is pending, not on main; the wait and slot settings are sections of Settings > Threads; a source build fetches upstream releases, so do not use update or service install on it. Co-Authored-By: Claude Opus 5.5 --- docs/fork/README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/fork/README.md b/docs/fork/README.md index 01bbed717faa5..f54dc66bc8859 100644 --- a/docs/fork/README.md +++ b/docs/fork/README.md @@ -48,7 +48,7 @@ that does nothing while the switch is off. A server installed as a boot service (`t3 service install`) updates itself to the newest fork release once no thread is working. Off: it updates only when someone runs `t3 update` or presses **Update**. -Upstream has a setting of the same name that defaults on; the fork keeps `false` through every sync. +Upstream has a setting of this name pending (not on its `main` yet); the fork keeps `false` through every sync. Switch on in `settings.json`: `"automaticUpdates": true`. There is no Settings row for it yet. An admin policy with updates `"off"` still wins. Details: [updates.md](updates.md). @@ -102,7 +102,7 @@ woken with the result. `wait_list` and `wait_cancel` list and end them. While of judged nor delivered; listing and cancelling still work. Other fields set deadlines, limits per thread and how often each kind is checked. -Switch on: **Settings → Waits**, "Let agents wait for events", or in `settings.json`: +Switch on: **Settings → Threads**, section Waits (shown while a server is connected), "Let agents wait for events", or in `settings.json`: `"waitFor": { "enabled": true }`. ### `server.waitChecks` @@ -112,7 +112,7 @@ fixed arguments, no shell; exit 0 means the event happened. It runs unsandboxed with the server's environment, so use fixed programs that run no files from the repository (no test runners or build scripts). Only the person can add one; agents cannot. -Add one: **Settings → Wait checks → Add check**, or in `settings.json`: +Add one: **Settings → Threads**, section Wait checks, **Add check**, or in `settings.json`: ```json { "waitChecks": { "build-done": { "argv": ["test", "-f", "/tmp/build.done"] } } } @@ -127,7 +127,7 @@ above `maxPerAccount` per provider account, or below `minFreeMemoryMb` of free m started in other ways are counted but never refused. With `waitFor` on, an agent can wait for a slot instead of retrying. -Switch on: **Settings → Agent slots**, "Limit running agents", or in `settings.json`: +Switch on: **Settings → Threads**, section Agent slots, "Limit running agents", or in `settings.json`: `"agentSlots": { "enabled": true, "maxPerMachine": 4 }`. With `enabled` and no limits set, nothing is refused. @@ -179,8 +179,8 @@ cd t3code && vp i && vp run build:desktop node apps/server/dist/bin.mjs ``` -A server run this way is not updated by `t3 update` or a boot service; update it with `git pull` and -a rebuild. +A build made this way does not know it is the fork: its `t3 update` and `t3 service install` would +fetch upstream's releases. Do not use them on it; update it with `git pull` and a rebuild. **A machine that already runs T3 as a boot service.** Do not switch it by hand. The go-live kit ([fork-kit/golive](../../fork-kit/golive/README.md)) is for this: today it has only its read-only