Skip to content

Commit c603b86

Browse files
authored
Merge branch 'main' into fix/browse-symlinked-directories
2 parents 2d3c920 + 5e1c23d commit c603b86

310 files changed

Lines changed: 15729 additions & 12160 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitattributes‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,5 @@
11
# git autocrlf=true converts LF to CRLF on Windows, causing issues with oxfmt
22
* text=auto eol=lf
3+
# Batch files need CRLF for cmd.exe to parse them reliably.
4+
*.cmd text eol=crlf
5+
*.bat text eol=crlf

‎AGENTS.md‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ The most common defect in this repo is a change that works on the path you teste
7272
- **Contracts.** Anything crossing the wire is typed in `packages/contracts`. Change the schema and the server, web, mobile, and desktop all follow.
7373
- **Reverse states.** If you added a way in, add the way out and the way to see it. Snooze needs unsnooze. Close needs reopen. A one-way door is a bug.
7474
- **Connection modes.** Local, remote/relay, and tunnel behave differently. Multi-device and multi-environment cases are real.
75-
- **Docs.** `docs/` splits by audience. Behavior changes that a user would notice belong in `docs/user/` (shipped-product voice, no repo tooling or source paths); architecture and contributor changes in `docs/internals/`; runbooks in `docs/operations/`; new vocabulary in `docs/internals/glossary.md`.
75+
- **Docs.** Check whether the change makes existing guidance inaccurate. Apply the [documentation rules](#documentation) before adding anything.
7676

7777
## Dev servers
7878

@@ -120,11 +120,22 @@ An empty database is a bad test. Seed your worktree's `.t3` with a copy of real
120120
- One concern per PR. If the description says "also", split it.
121121
- When babysitting: poll checks and comments newer than the last push, verify each bot finding against the source, fix real ones, dismiss false positives with a written reason. Stay quiet when nothing is new. Stop when the bots are green on the latest commit.
122122

123+
## Documentation
124+
125+
Most code changes do not need an internal documentation change. Agents can read the code.
126+
127+
- `docs/internals/` is for architectural decisions and their reasons, constraints that span components, and implementation traps that are hard to discover from the source. Before adding a paragraph, ask what a maintainer would get wrong without it. If reading the relevant code answers the question, leave it out.
128+
- Do not document every feature, enumerate fields or methods, narrate control flow, maintain file catalogs, or append PR summaries. Types, tests, and code already record the implementation. The glossary defines shared vocabulary; it is not a feature index.
129+
- Keep a local implementation explanation in a nearby code comment. Use an internal doc when the reasoning crosses boundaries or needs context the code cannot carry well. Link to the relevant source instead of copying it.
130+
- When a documented decision or constraint changes, rewrite or remove the affected text. Do not append another account of the new behavior. A new internal page needs a distinct, durable reason to exist.
131+
- `docs/user/` helps users accomplish tasks. Give each major feature a concise section explaining what it does, how to start, and anything unintuitive. A settings path is useful; descriptions of visible buttons, icons, layouts, animations, or every UI state are not. Before adding text, ask what task or decision it helps the user with.
132+
- Keep user docs in the shipped product's voice, without implementation details or contributor tooling. Update the relevant feature section when how to use it changes. A UI tweak does not need a documentation entry, and a new control does not need its own page.
133+
- `docs/operations/` holds maintainer setup, release, and debugging procedures. Keep instructions for operating an installed T3 Code server in the user guides.
134+
123135
## Plans and work artifacts
124136

125137
- Do not commit implementation plans, research notes, or agent scratch files. Keep temporary working material outside the worktree. `.plans/` is gitignored only as a safety net for legacy tooling.
126138
- Track active maintainer work in the GitHub issue or project item that owns it. External proposals follow `CONTRIBUTING.md` and belong in Ideas discussions.
127-
- Put durable architecture, constraints, and decisions in `docs/internals/`. Update those docs when the product changes so agents find current facts instead of abandoned intentions.
128139
- A merged PR is the implementation record. Close or update its tracking item when the work lands; do not preserve a second checklist in the repository.
129140

130141
## How it works

‎CONTRIBUTING.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
## Developer Setup
44

5-
See the [maintainer scripts guide](docs/internals/scripts.md#first-checkout) for the initial checkout,
5+
See the [development runbook](docs/operations/development.md#first-checkout) for the initial checkout,
66
development commands, tests, and platform-specific desktop packaging prerequisites.
77

88
## Read This First
@@ -49,6 +49,10 @@ Explain exactly what changed.
4949

5050
Explain exactly why the change should exist.
5151

52+
Follow the [documentation rules](AGENTS.md#documentation). Keep internal docs for decisions and
53+
hard-to-discover constraints. Update user guides when how to use a feature changes; skip descriptions
54+
of obvious controls and cosmetic changes.
55+
5256
Do not mix unrelated fixes together.
5357

5458
If the PR makes anything resembling a UI change, include clear before/after images.

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -79,12 +79,12 @@ Full docs live in [docs/](./docs). There's no docs site yet.
7979
- [Install and first run](./docs/user/install.md)
8080
- [Permission modes](./docs/user/permission-modes.md)
8181
- [Keyboard shortcuts](./docs/user/keybindings.md)
82-
- [Customize a project icon](./docs/user/project-settings.md)
82+
- [Project settings](./docs/user/project-settings.md)
8383
- [Remote access from a phone or another machine](./docs/user/remote-access.md)
8484
- [Keeping app and server in sync](./docs/user/updating.md)
8585
- [Source control integrations](./docs/user/source-control.md)
8686
- Multiple accounts: [Codex](./docs/user/providers-codex.md) · [Claude](./docs/user/providers-claude.md)
87-
- Linux: [run T3 Code as a background service](./docs/user/background-service.md)
87+
- [Run T3 Code as a background service](./docs/user/background-service.md)
8888

8989
Building from source? Start at [docs/internals/overview.md](./docs/internals/overview.md).
9090

‎apps/desktop/scripts/electron-launcher.mjs‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -165,10 +165,14 @@ function registerMacLauncherBundle(appBundlePath) {
165165
}
166166
}
167167

168+
// Bundle-internal paths are macOS paths whatever host builds them.
168169
export function resolveMacLauncherIconPaths(runtimeDir, development = isDevelopment) {
169170
return {
170171
sourceIconPath: development ? developmentMacIconPngPath : productionMacIconPngPath,
171-
generatedIconPath: NodePath.join(runtimeDir, development ? "icon-dev.icns" : "icon-prod.icns"),
172+
generatedIconPath: NodePath.posix.join(
173+
runtimeDir,
174+
development ? "icon-dev.icns" : "icon-prod.icns",
175+
),
172176
};
173177
}
174178

@@ -280,12 +284,12 @@ function readJson(path) {
280284
}
281285

282286
export function resolveMacLauncherPaths(appBundlePath, displayName = APP_DISPLAY_NAME) {
283-
const executableDir = NodePath.join(appBundlePath, "Contents", "MacOS");
287+
const executableDir = NodePath.posix.join(appBundlePath, "Contents", "MacOS");
284288
const launcherExecutableName = `${displayName} Launcher`;
285289
return {
286290
launcherExecutableName,
287-
launcherBinaryPath: NodePath.join(executableDir, launcherExecutableName),
288-
runtimeElectronBinaryPath: NodePath.join(executableDir, "Electron"),
291+
launcherBinaryPath: NodePath.posix.join(executableDir, launcherExecutableName),
292+
runtimeElectronBinaryPath: NodePath.posix.join(executableDir, "Electron"),
289293
};
290294
}
291295

‎apps/desktop/scripts/electron-launcher.test.mjs‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -84,9 +84,10 @@ describe("electron development launcher", () => {
8484
const development = resolveMacLauncherIconPaths("/runtime", true);
8585
const production = resolveMacLauncherIconPaths("/runtime", false);
8686

87-
assert.match(development.sourceIconPath, /assets\/dev\/blueprint-macos-1024\.png$/);
87+
// The source icons are real repo paths, joined for the host.
88+
assert.match(development.sourceIconPath, /assets[\\/]dev[\\/]blueprint-macos-1024\.png$/);
8889
assert.equal(development.generatedIconPath, "/runtime/icon-dev.icns");
89-
assert.match(production.sourceIconPath, /assets\/prod\/black-macos-1024\.png$/);
90+
assert.match(production.sourceIconPath, /assets[\\/]prod[\\/]black-macos-1024\.png$/);
9091
assert.equal(production.generatedIconPath, "/runtime/icon-prod.icns");
9192
});
9293
});

‎apps/desktop/src/app/DesktopAppIdentity.test.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import * as NodePath from "@effect/platform-node/NodePath";
12
import * as NodeServices from "@effect/platform-node/NodeServices";
23
import { assert, describe, it } from "@effect/vitest";
34
import * as Effect from "effect/Effect";
@@ -88,6 +89,7 @@ const makeEnvironmentLayer = (overrides: TestEnvironmentInput = {}) => {
8889
Layer.provide(
8990
Layer.mergeAll(
9091
NodeServices.layer,
92+
NodePath.layerPosix,
9193
DesktopConfig.layerTest({
9294
...env,
9395
}),

‎apps/desktop/src/app/DesktopAssets.test.ts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import * as NodePath from "@effect/platform-node/NodePath";
12
import * as NodeServices from "@effect/platform-node/NodeServices";
23
import { assert, describe, it } from "@effect/vitest";
34
import * as Effect from "effect/Effect";
@@ -20,7 +21,11 @@ const environmentLayer = DesktopEnvironment.layer({
2021
isPackaged: true,
2122
resourcesPath: "/Applications/T3 Code.app/Contents/Resources",
2223
runningUnderArm64Translation: false,
23-
}).pipe(Layer.provide(Layer.mergeAll(NodeServices.layer, DesktopConfig.layerTest({}))));
24+
}).pipe(
25+
Layer.provide(
26+
Layer.mergeAll(NodeServices.layer, NodePath.layerPosix, DesktopConfig.layerTest({})),
27+
),
28+
);
2429

2530
describe("DesktopAssets", () => {
2631
it.effect("uses canonical source-tree icons for unpackaged development", () =>
@@ -39,6 +44,7 @@ describe("DesktopAssets", () => {
3944
Layer.provide(
4045
Layer.mergeAll(
4146
NodeServices.layer,
47+
NodePath.layerPosix,
4248
DesktopConfig.layerTest({ VITE_DEV_SERVER_URL: "http://localhost:5733" }),
4349
),
4450
),

‎apps/desktop/src/app/DesktopConnectionCatalogStore.test.ts‎

Lines changed: 19 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import { ConnectionCatalogDocument } from "@t3tools/client-runtime/platform";
44
import { EnvironmentId, type PersistedSavedEnvironmentRecord } from "@t3tools/contracts";
55
import * as Effect from "effect/Effect";
66
import * as FileSystem from "effect/FileSystem";
7+
import * as Path from "effect/Path";
78
import * as Layer from "effect/Layer";
89
import * as Option from "effect/Option";
910
import * as PlatformError from "effect/PlatformError";
@@ -226,10 +227,11 @@ describe("DesktopConnectionCatalogStore", () => {
226227
it.effect("surfaces malformed catalog documents without deleting them", () =>
227228
withStore(
228229
Effect.gen(function* () {
230+
const path = yield* Path.Path;
229231
const environment = yield* DesktopEnvironment.DesktopEnvironment;
230232
const fileSystem = yield* FileSystem.FileSystem;
231233
const store = yield* DesktopConnectionCatalogStore.DesktopConnectionCatalogStore;
232-
const catalogPath = `${environment.stateDir}/connection-catalog.json`;
234+
const catalogPath = path.join(environment.stateDir, "connection-catalog.json");
233235
yield* fileSystem.makeDirectory(environment.stateDir, { recursive: true });
234236
yield* fileSystem.writeFileString(catalogPath, "{not-json");
235237

@@ -247,6 +249,7 @@ describe("DesktopConnectionCatalogStore", () => {
247249

248250
it.effect("surfaces catalog filesystem failures instead of treating them as missing", () =>
249251
Effect.gen(function* () {
252+
const path = yield* Path.Path;
250253
const baseFileSystem = yield* FileSystem.FileSystem;
251254
const baseDir = yield* baseFileSystem.makeTempDirectoryScoped({
252255
prefix: "t3-desktop-connection-catalog-test-",
@@ -255,7 +258,7 @@ describe("DesktopConnectionCatalogStore", () => {
255258
_tag: "PermissionDenied",
256259
module: "FileSystem",
257260
method: "readFileString",
258-
pathOrDescriptor: `${baseDir}/userdata/connection-catalog.json`,
261+
pathOrDescriptor: path.join(baseDir, "userdata", "connection-catalog.json"),
259262
});
260263
const fileSystemLayer = Layer.succeed(
261264
FileSystem.FileSystem,
@@ -272,11 +275,11 @@ describe("DesktopConnectionCatalogStore", () => {
272275
error,
273276
DesktopConnectionCatalogStore.DesktopConnectionCatalogStoreReadError,
274277
);
275-
assert.equal(error.catalogPath, `${baseDir}/userdata/connection-catalog.json`);
278+
assert.equal(error.catalogPath, path.join(baseDir, "userdata", "connection-catalog.json"));
276279
assert.strictEqual(error.cause, permissionError);
277280
assert.equal(
278281
error.message,
279-
`Failed to read the desktop connection catalog at ${baseDir}/userdata/connection-catalog.json.`,
282+
`Failed to read the desktop connection catalog at ${path.join(baseDir, "userdata", "connection-catalog.json")}.`,
280283
);
281284
assert.notEqual(error.message, permissionError.message);
282285
}).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
@@ -285,14 +288,15 @@ describe("DesktopConnectionCatalogStore", () => {
285288
it.effect("reports the failed catalog write operation and path", () =>
286289
Effect.gen(function* () {
287290
const baseFileSystem = yield* FileSystem.FileSystem;
291+
const path = yield* Path.Path;
288292
const baseDir = yield* baseFileSystem.makeTempDirectoryScoped({
289293
prefix: "t3-desktop-connection-catalog-test-",
290294
});
291295
const permissionError = PlatformError.systemError({
292296
_tag: "PermissionDenied",
293297
module: "FileSystem",
294298
method: "makeDirectory",
295-
pathOrDescriptor: `${baseDir}/userdata`,
299+
pathOrDescriptor: path.join(baseDir, "userdata"),
296300
});
297301
const fileSystemLayer = Layer.succeed(
298302
FileSystem.FileSystem,
@@ -310,11 +314,11 @@ describe("DesktopConnectionCatalogStore", () => {
310314
DesktopConnectionCatalogStore.DesktopConnectionCatalogStoreWriteError,
311315
);
312316
assert.equal(error.operation, "create-directory");
313-
assert.equal(error.path, `${baseDir}/userdata`);
317+
assert.equal(error.path, path.join(baseDir, "userdata"));
314318
assert.strictEqual(error.cause, permissionError);
315319
assert.equal(
316320
error.message,
317-
`Desktop connection catalog write failed during create-directory at ${baseDir}/userdata.`,
321+
`Desktop connection catalog write failed during create-directory at ${path.join(baseDir, "userdata")}.`,
318322
);
319323
assert.notEqual(error.message, permissionError.message);
320324
}).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
@@ -323,6 +327,7 @@ describe("DesktopConnectionCatalogStore", () => {
323327
it.effect("reports the legacy migration stage", () =>
324328
withStore(
325329
Effect.gen(function* () {
330+
const path = yield* Path.Path;
326331
const environment = yield* DesktopEnvironment.DesktopEnvironment;
327332
const fileSystem = yield* FileSystem.FileSystem;
328333
const store = yield* DesktopConnectionCatalogStore.DesktopConnectionCatalogStore;
@@ -335,7 +340,7 @@ describe("DesktopConnectionCatalogStore", () => {
335340
DesktopConnectionCatalogStore.DesktopConnectionCatalogStoreMigrationError,
336341
);
337342
assert.equal(error.operation, "read-legacy-registry");
338-
assert.equal(error.catalogPath, `${environment.stateDir}/connection-catalog.json`);
343+
assert.equal(error.catalogPath, path.join(environment.stateDir, "connection-catalog.json"));
339344
assert.instanceOf(
340345
error.cause,
341346
DesktopSavedEnvironments.DesktopSavedEnvironmentsDocumentDecodeError,
@@ -345,7 +350,7 @@ describe("DesktopConnectionCatalogStore", () => {
345350
assert.exists(registryError.cause);
346351
assert.equal(
347352
error.message,
348-
`Legacy desktop saved-environment migration failed during read-legacy-registry into ${environment.stateDir}/connection-catalog.json.`,
353+
`Legacy desktop saved-environment migration failed during read-legacy-registry into ${path.join(environment.stateDir, "connection-catalog.json")}.`,
349354
);
350355
assert.notEqual(error.message, registryError.message);
351356
}),
@@ -355,10 +360,11 @@ describe("DesktopConnectionCatalogStore", () => {
355360
it.effect("reports invalid encrypted catalog data without exposing it", () =>
356361
withStore(
357362
Effect.gen(function* () {
363+
const path = yield* Path.Path;
358364
const environment = yield* DesktopEnvironment.DesktopEnvironment;
359365
const fileSystem = yield* FileSystem.FileSystem;
360366
const store = yield* DesktopConnectionCatalogStore.DesktopConnectionCatalogStore;
361-
const catalogPath = `${environment.stateDir}/connection-catalog.json`;
367+
const catalogPath = path.join(environment.stateDir, "connection-catalog.json");
362368
yield* fileSystem.makeDirectory(environment.stateDir, { recursive: true });
363369
yield* fileSystem.writeFileString(catalogPath, '{"version":1,"encryptedCatalog":"%%%"}\n');
364370

@@ -381,6 +387,7 @@ describe("DesktopConnectionCatalogStore", () => {
381387

382388
it.effect("surfaces a catalog that can no longer be decrypted without deleting it", () =>
383389
Effect.gen(function* () {
390+
const path = yield* Path.Path;
384391
const fileSystem = yield* FileSystem.FileSystem;
385392
const baseDir = yield* fileSystem.makeTempDirectoryScoped({
386393
prefix: "t3-desktop-connection-catalog-test-",
@@ -399,14 +406,14 @@ describe("DesktopConnectionCatalogStore", () => {
399406
DesktopConnectionCatalogStore.DesktopConnectionCatalogStoreProtectionError,
400407
);
401408
assert.equal(error.operation, "decrypt-catalog");
402-
assert.equal(error.catalogPath, `${baseDir}/userdata/connection-catalog.json`);
409+
assert.equal(error.catalogPath, path.join(baseDir, "userdata", "connection-catalog.json"));
403410
assert.instanceOf(error.cause, ElectronSafeStorage.ElectronSafeStorageDecryptError);
404411
const decryptError = error.cause as ElectronSafeStorage.ElectronSafeStorageDecryptError;
405412
assert.instanceOf(decryptError.cause, Error);
406413
assert.equal(decryptError.cause.message, "invalid encrypted catalog");
407414
assert.equal(
408415
error.message,
409-
`Desktop connection catalog protection failed during decrypt-catalog at ${baseDir}/userdata/connection-catalog.json.`,
416+
`Desktop connection catalog protection failed during decrypt-catalog at ${path.join(baseDir, "userdata", "connection-catalog.json")}.`,
410417
);
411418
assert.notEqual(error.message, decryptError.message);
412419
yield* Ref.set(failDecrypt, false);

‎apps/desktop/src/app/DesktopEnvironment.test.ts‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import * as NodePath from "@effect/platform-node/NodePath";
12
import * as NodeServices from "@effect/platform-node/NodeServices";
23
import { assert, describe, it } from "@effect/vitest";
34
import * as Effect from "effect/Effect";
@@ -26,7 +27,11 @@ const makeEnvironmentLayer = (
2627
DesktopEnvironment.layer({
2728
...defaultInput,
2829
...overrides,
29-
}).pipe(Layer.provide(Layer.mergeAll(NodeServices.layer, DesktopConfig.layerTest(env))));
30+
}).pipe(
31+
Layer.provide(
32+
Layer.mergeAll(NodeServices.layer, NodePath.layerPosix, DesktopConfig.layerTest(env)),
33+
),
34+
);
3035

3136
const makeEnvironment = (
3237
overrides: Partial<DesktopEnvironment.MakeDesktopEnvironmentInput> = {},

0 commit comments

Comments
 (0)