Skip to content

Commit 2654583

Browse files
committed
Keep worktree dev state isolated
1 parent 5719e8a commit 2654583

7 files changed

Lines changed: 148 additions & 6 deletions

File tree

‎.agents/skills/test-t3-app/SKILL.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,13 @@ Use this skill for the web client. For iOS Simulator, Android Emulator, or physi
1313
2. Choose a base directory that belongs only to the current worktree or test:
1414
- Use the repository's ignored `.t3` directory for reusable worktree-local state.
1515
- Use `mktemp -d /tmp/t3code-test.XXXXXX` for disposable state and retain the printed absolute path.
16-
3. Start the full web stack with `vp run dev --home-dir <base-dir>`.
16+
3. Start the full web stack with `vp run dev`. In a linked worktree it defaults to that worktree's gitignored `.t3`; pass `--home-dir <base-dir>` only when the test needs a different isolated directory.
1717
4. Keep the terminal session alive and read the selected server port, web port, base directory, and pairing URL from its output.
1818

1919
Treat a base directory as disposable only when it was created or deliberately selected for the current test. Never delete or directly seed the shared `~/.t3` directory. Prefer starting with a new temporary base directory over clearing state of uncertain ownership.
2020

21+
The worktree-local default deliberately outranks an ambient `T3CODE_HOME`; do not pass the shared home through to a worktree dev server.
22+
2123
The dev runner disables browser auto-open by default. Do not pass `--browser` during automated testing: an automatically opened page can consume the one-time bootstrap token before the controlled browser uses it.
2224

2325
## Preserve the environment while iterating

‎AGENTS.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,10 @@
1313
- Subagents must not independently launch dev servers or repeat integrated client verification unless their delegated task explicitly requires it.
1414
- Stop dev servers, watchers, and other long-running verification processes when the focused verification is complete.
1515

16+
## Dev Servers
17+
18+
- In a linked git worktree, dev state defaults to that worktree's gitignored `.t3`. This deliberately outranks an ambient `T3CODE_HOME`, which could otherwise select the installed app's live `~/.t3/userdata` database. An explicit `--home-dir` still wins.
19+
1620
## Package Roles
1721

1822
- `apps/server`: Node.js WebSocket server. Wraps Codex app-server (JSON-RPC over stdio), serves the React web app, and manages provider sessions.

‎docs/reference/scripts.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,8 @@
33
- `vp run dev` — Starts contracts, server, and web in watch mode.
44
- `vp run dev:server` — Starts just the WebSocket server. The server process runs on Bun (`@effect/platform-bun` + `BunPtyAdapter`), but task running uses `vp run`.
55
- `vp run dev:web` — Starts just the Vite dev server for the web app.
6-
- Dev commands implicitly use `~/.t3/dev`, keeping development state separate from `~/.t3/userdata`. An explicit `--home-dir <path>` stores state under `<path>/userdata`; the base directory remains available for caches, worktrees, and other shared data.
6+
- Dev commands run from a linked **git worktree** default to that worktree's gitignored `.t3`, even when `T3CODE_HOME` is set. Pass `--home-dir <path>` to choose another isolated directory explicitly.
7+
- From the **main checkout**, dev commands implicitly use `~/.t3/dev`, keeping development state separate from `~/.t3/userdata`. An explicit `--home-dir <path>` stores state under `<path>/userdata`; the base directory remains available for caches, worktrees, and other shared data.
78
- Web dev commands do not auto-open a browser. Open the one-time pairing URL printed by the server so the first browser navigation is authenticated. Set `T3CODE_NO_BROWSER=0` only when interactive auto-open is intentional.
89
- Pass dev-runner flags directly after the root task name, for example:
910
`vp run dev --home-dir /tmp/t3code-dev`

‎packages/shared/package.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -194,6 +194,10 @@
194194
"./httpReadiness": {
195195
"types": "./src/httpReadiness.ts",
196196
"import": "./src/httpReadiness.ts"
197+
},
198+
"./devHome": {
199+
"types": "./src/devHome.ts",
200+
"import": "./src/devHome.ts"
197201
}
198202
},
199203
"scripts": {
Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
// @effect-diagnostics nodeBuiltinImport:off - builds real worktree layouts on disk.
2+
import * as NodeServices from "@effect/platform-node/NodeServices";
3+
import { assert, describe, it } from "@effect/vitest";
4+
import * as NodeFS from "node:fs";
5+
import * as NodeOS from "node:os";
6+
import * as NodePath from "node:path";
7+
import * as Effect from "effect/Effect";
8+
9+
import { resolveGitWorktreePath, resolveWorktreeT3Home } from "./devHome.ts";
10+
11+
const makeRepo = (kind: "worktree" | "checkout" | "bare") =>
12+
Effect.acquireRelease(
13+
Effect.sync(() => {
14+
const root = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-devhome-"));
15+
if (kind === "worktree") {
16+
NodeFS.writeFileSync(NodePath.join(root, ".git"), "gitdir: /elsewhere/.git/worktrees/x\n");
17+
} else if (kind === "checkout") {
18+
NodeFS.mkdirSync(NodePath.join(root, ".git"));
19+
}
20+
const nested = NodePath.join(root, "apps", "web", "src");
21+
NodeFS.mkdirSync(nested, { recursive: true });
22+
return { root, nested };
23+
}),
24+
({ root }) => Effect.sync(() => NodeFS.rmSync(root, { recursive: true, force: true })),
25+
);
26+
27+
describe("resolveGitWorktreePath", () => {
28+
it.effect("finds a worktree root from a nested directory", () =>
29+
Effect.gen(function* () {
30+
const { root, nested } = yield* makeRepo("worktree");
31+
assert.equal(yield* resolveGitWorktreePath(nested), NodePath.resolve(root));
32+
}).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
33+
);
34+
35+
it.effect("reports a main checkout as not a linked worktree", () =>
36+
Effect.gen(function* () {
37+
const { nested } = yield* makeRepo("checkout");
38+
assert.equal(yield* resolveGitWorktreePath(nested), undefined);
39+
}).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
40+
);
41+
42+
it.effect("reports a directory outside a repository", () =>
43+
Effect.gen(function* () {
44+
const { nested } = yield* makeRepo("bare");
45+
assert.equal(yield* resolveGitWorktreePath(nested), undefined);
46+
}).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
47+
);
48+
});
49+
50+
describe("resolveWorktreeT3Home", () => {
51+
it.effect("answers with .t3 before the dev runner creates it", () =>
52+
Effect.gen(function* () {
53+
const { root, nested } = yield* makeRepo("worktree");
54+
const home = yield* resolveWorktreeT3Home(nested);
55+
assert.equal(home, NodePath.join(NodePath.resolve(root), ".t3"));
56+
assert.isFalse(NodeFS.existsSync(home ?? ""));
57+
}).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
58+
);
59+
});

‎packages/shared/src/devHome.ts‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
/**
2+
* Where development state lives, and how to keep it away from the shared
3+
* `~/.t3` that a user's installed T3 Code runs against.
4+
*
5+
* A linked git worktree gets its own (gitignored) `.t3`: feature work in a
6+
* throwaway branch must not share a database with the real app, and an ambient
7+
* `T3CODE_HOME` counts as an explicit base dir — flipping the state directory
8+
* from `<base>/dev` to `<base>/userdata`, the live production database.
9+
*/
10+
11+
import * as Effect from "effect/Effect";
12+
import * as FileSystem from "effect/FileSystem";
13+
import * as Option from "effect/Option";
14+
import * as Path from "effect/Path";
15+
16+
/**
17+
* The path of the linked git worktree containing `cwd`, or undefined when
18+
* `cwd` is not inside one. Git marks a linked worktree by making `.git` a file
19+
* (`gitdir: …`) rather than a directory.
20+
*
21+
* Walks up to the repository root, so running from a subdirectory resolves the
22+
* same worktree as running from the top.
23+
*/
24+
export const resolveGitWorktreePath = (
25+
cwd: string,
26+
): Effect.Effect<string | undefined, never, FileSystem.FileSystem | Path.Path> =>
27+
Effect.gen(function* () {
28+
const fileSystem = yield* FileSystem.FileSystem;
29+
const path = yield* Path.Path;
30+
31+
let directory = path.resolve(cwd);
32+
for (;;) {
33+
const info = yield* fileSystem.stat(path.join(directory, ".git")).pipe(Effect.option);
34+
if (Option.isSome(info)) {
35+
// A directory means the main checkout. Stop either way: nesting one
36+
// repository inside another does not make the outer one this root.
37+
return info.value.type === "File" ? directory : undefined;
38+
}
39+
const parent = path.dirname(directory);
40+
if (parent === directory) {
41+
return undefined;
42+
}
43+
directory = parent;
44+
}
45+
});
46+
47+
/**
48+
* The worktree-local data directory for `cwd`, or undefined outside a linked
49+
* worktree. Deliberately does not require the directory to exist yet: falling
50+
* back because it is missing would send callers at the shared home.
51+
*/
52+
export const resolveWorktreeT3Home = (
53+
cwd: string,
54+
): Effect.Effect<string | undefined, never, FileSystem.FileSystem | Path.Path> =>
55+
Effect.gen(function* () {
56+
const worktreePath = yield* resolveGitWorktreePath(cwd);
57+
if (worktreePath === undefined) {
58+
return undefined;
59+
}
60+
const path = yield* Path.Path;
61+
return path.join(worktreePath, ".t3");
62+
});

‎scripts/dev-runner.ts‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import * as NodeOS from "node:os";
55
import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
66
import * as NodeServices from "@effect/platform-node/NodeServices";
77
import * as NetService from "@t3tools/shared/Net";
8+
import { resolveWorktreeT3Home } from "@t3tools/shared/devHome";
89
import { HostProcessEnvironment } from "@t3tools/shared/hostProcess";
910
import { resolveSpawnCommand } from "@t3tools/shared/shell";
1011
import * as Config from "effect/Config";
@@ -245,7 +246,9 @@ export function createDevRunnerEnv({
245246
return Effect.gen(function* () {
246247
const serverPort = port ?? BASE_SERVER_PORT + serverOffset;
247248
const webPort = BASE_WEB_PORT + webOffset;
248-
const configuredBaseDir = t3Home?.trim() || baseEnv.T3CODE_HOME?.trim() || undefined;
249+
// Precedence is resolved by the caller. An unset t3Home here genuinely
250+
// means "use the default" rather than inheriting an ambient value.
251+
const configuredBaseDir = t3Home?.trim() || undefined;
249252
const resolvedBaseDir = yield* resolveBaseDir(configuredBaseDir);
250253
const isDesktopMode = mode === "dev:desktop";
251254

@@ -505,12 +508,18 @@ export function runDevRunnerWithInput(input: DevRunnerCliInput) {
505508
});
506509

507510
const hostEnvironment = yield* HostProcessEnvironment;
511+
// A worktree defaults to its own gitignored `.t3`. This deliberately
512+
// outranks ambient T3CODE_HOME, which otherwise selects the installed
513+
// app's live userdata database. An explicit --home-dir still wins.
514+
const worktreeHome = yield* resolveWorktreeT3Home(process.cwd());
515+
const resolvedT3Home =
516+
input.t3Home ?? worktreeHome ?? (hostEnvironment.T3CODE_HOME?.trim() || undefined);
508517
const env = yield* createDevRunnerEnv({
509518
mode: input.mode,
510519
baseEnv: hostEnvironment,
511520
serverOffset,
512521
webOffset,
513-
t3Home: input.t3Home,
522+
t3Home: resolvedT3Home,
514523
browser: input.browser,
515524
autoBootstrapProjectFromCwd: input.autoBootstrapProjectFromCwd,
516525
logWebSocketEvents: input.logWebSocketEvents,
@@ -592,9 +601,10 @@ const devRunnerCli = Command.make("dev-runner", {
592601
),
593602
t3Home: Flag.string("home-dir").pipe(
594603
Flag.withDescription(
595-
"Explicit T3 Code data directory; runtime state is stored under userdata (equivalent to T3CODE_HOME).",
604+
"Explicit T3 Code data directory; runtime state is stored under userdata. Inside a git worktree this defaults to that worktree's own .t3.",
596605
),
597-
Flag.withFallbackConfig(optionalStringConfig("T3CODE_HOME")),
606+
Flag.optional,
607+
Flag.map(Option.getOrUndefined),
598608
),
599609
browser: Flag.boolean("browser").pipe(
600610
Flag.withDescription("Open a browser automatically (disabled by default for web dev)."),

0 commit comments

Comments
 (0)