Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
130 changes: 130 additions & 0 deletions .agents/skills/update-t3code/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,130 @@
---
name: update-t3code
description: Update the T3 Code Flatpak to a new upstream release. Refresh the patches, check that the package still works the way it should, bring new upstream features into the Flatpak where they fit, and flag anything that needs a product decision.
---

# Update T3 Code

Handle the patch work and routine checks without asking. Ask only about
product decisions, and explain them in terms of what users see, not the code.

## What the package should be

This is upstream T3 Code, repackaged to be a good Flatpak citizen.

- **Stay close to upstream.** Follow upstream's behavior wherever it works in
the Flatpak. Patch only what the Flatpak needs, and keep each patch as small
as it can be. Leave upstream bugs to upstream.
- **Keep the system clean.** The Flatpak is a packaging mechanism, not a strict
security boundary. T3 Code's own components and data stay where removing the
Flatpak with its data cleans them up. It never installs things onto the host,
changes system configuration or sets up host software for the user. Work the
user asks for, such as agents editing projects or files saved to Downloads,
is fine.
- **Users own their system.** When a feature needs something on the host,
document the requirement instead of building workarounds or setting it up
for them.
- **Flatpak owns updates.** The desktop app and the local server it starts are
updated through Flatpak, never by themselves. Remote servers managed
separately keep upstream's update behavior.
- **Use the desktop's own facilities.** Prefer portals and the user's normal
desktop options over custom integrations.
- **Don't quietly lose features.** If something can't work as upstream built
it, find the simplest way to keep what users actually get from it, often
through the app's UI. If the feature isn't worth keeping, hide it so users
never reach a broken option.
- **Prefer simple.** Choose the option with the least patch to maintain, unless
a slightly bigger change clearly serves users better.

## Workflow

### 1. Start from the update PR

The **Check for T3 Code releases** workflow opens a draft PR on
`automation/update-t3code-vX`. If there isn't one yet, run that workflow. Work
on the PR branch.

### 2. Refresh the patches

Rebase the patch series in `patches/` onto the new upstream tag, using an
upstream checkout in the gitignored `build-flatpak/` directory. Keep one commit
per patch so the files can be regenerated from them. Follow each conflicting
upstream change's intent:

- Drop what upstream now does itself or no longer needs, including whole
patches. Remove a retired patch's file and its manifest entry.
- Keep the Flatpak's behavior where both apply.
- Make sure the regenerated files reproduce the tree you tested.

### 3. Review the release

A clean rebase doesn't mean the package still works. Read the upstream changes
and check each of these.

- **Existing patches still hold.** Check that each patch's behavior still works,
not just that it applies. Upstream often adds a new path next to the one a
patch covers.
- **New features that need Flatpak support.** These are things users should
get that break across the sandbox and host boundary. The desktop UI runs in
the sandbox and the server runs on the host, so look at what crosses between
them: environment, paths, files, startup arguments, and host tools the desktop
calls. Check new settings, notices and recovery screens too, by tracing what
they actually do.
- **Features that don't fit.** These are things that conflict with what the
package should be, such as installing onto the host, setting up host
software or self-updating. Judge each by what it does for users and what it
does to the host, not by how upstream exposes it. Recommend keeping, adapting
or hiding it.
- **Build requirements.** Compare upstream's toolchain needs, such as Node,
pnpm and Electron, with the manifest's SDK extensions and build commands.

Also note existing gaps you come across, even if the release didn't cause them,
and anything worth testing on the currently installed version.

### 4. Report and get decisions

- Summarize the patch refresh briefly, in plain terms. Say what changed and why.
- Raise only the items that need a decision. Go one at a time, with the user
impact, your recommendation and what it costs to maintain. Don't report
things that need no action.
- Don't make product changes until they're approved.

### 5. Implement and verify

- Make the agreed changes in the style of the existing patches.
- Run `./scripts/build-flatpak build` from the repo root. It runs the desktop
tests, the server tests listed in `flatpak/modules/t3code.yml` and both
typechecks, but no web tests. Check web changes directly. Make sure the test
files the manifest lists still exist.
- Run `./scripts/test-packaged` to check the built package where the sandbox
and host meet. When the release changes a flow these checks don't cover,
add a check to `tests/packaged/` or test it by hand with isolated data. Say
what you tested, what you only checked by reading code, and what's
unverified.
- Update the user documentation when host requirements, setup or supported
behavior change.
- Before handing off, do a final review pass over the whole change set for
bloat, leftovers and anything outside what was agreed.
- Ask before replacing the installed copy of the app to test a build. It shares
data with the instance that's running.

### 6. Ship within the request

Do only as much as the current request asks. Merge and release only when
asked to.

- **PR:** push to the PR branch, rewrite the description to cover the update and
any packaging changes, mark it ready, and wait for **Validate Flatpak
update**. Bot-created runs need approval in the PR.
- **Metainfo:** keep the release checker's formatting. Leave the release
description empty for a plain upstream update. Write a short, specific note
when the package itself changes. Packaging-only releases append a revision,
such as `0.1.7-1`. If a release ships upstream and packaging changes
together, use one entry for it, not two.
- **Merge:** squash-merge and delete the branch. **Publish Flatpak repository**
then runs on `main` by itself. Check that it succeeds. A "release" means
publishing the Flatpak repository, not creating a GitHub Release.
- **After release:** clean up the local and remote branches. The published
update then gets tested on a real install. Fix regressions as the next `-N`
revision. The app's server logs are under
`~/.var/app/com.t3tools.t3code/data/t3/userdata/logs/`.
1 change: 1 addition & 0 deletions .claude/skills
13 changes: 13 additions & 0 deletions .github/workflows/validate-flatpak.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ on:
- flatpak/**
- '!flatpak/pages/**'
- patches/**
- tests/packaged/**
workflow_dispatch:

permissions:
Expand Down Expand Up @@ -40,3 +41,15 @@ jobs:
repo-dir: build-flatpak/validation-repo
state-dir: build-flatpak/builder-state
cache-key: flatpak-builder-x86_64-${{ hashFiles('flatpak/**', '!flatpak/pages/**', 'patches/**') }}

# Launches the built package and checks the sandbox and host still work together.
- name: Test the packaged app
run: tests/packaged/run.sh --repo build-flatpak/validation-repo

- name: Upload packaged app test results
if: failure()
uses: actions/upload-artifact@v7
with:
name: packaged-app-test-results
path: build-flatpak/packaged-test-artifacts
if-no-files-found: ignore
21 changes: 21 additions & 0 deletions docs/building.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,3 +24,24 @@ To build and install the package for your user, then launch it:
```

Build state and output stay in `build-flatpak/`.

## Testing the packaged app

The packaged app checks install a build in a throwaway container, launch it
headless, and check the places where the sandbox and host meet: the host
server, agent CLIs found through the login shell, downloads, terminals,
editors, SSH, Tailscale, managed policy, database maintenance, and the recovery
screen when the host is out of reach. Docker runs them by default; set
`CONTAINER_ENGINE=podman` to use Podman.

```sh
./scripts/test-packaged # the build from ./scripts/build-flatpak build
./scripts/test-packaged published <commit> # a build from the published repository
```

The container stands in for a user's machine, so nothing is installed on yours.
A run needs network access to fetch runtimes and upstream test fixtures. The
fixtures come from the upstream release in the manifest, so an older published
commit is checked against the current fixtures. The app logs, plus screenshots
from failed checks, are written to `build-flatpak/packaged-test-artifacts/`. The
checks live in `tests/packaged/` and are typechecked before each run.
5 changes: 4 additions & 1 deletion docs/publishing.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,10 @@ skip package validation and do not change the build cache key.
The workflow applies the patches, builds the Flatpak, runs desktop tests and
the editor launcher test, and typechecks the desktop and server. The WSL test
file is excluded because some of its tests inspect host processes that the
Flatpak build sandbox cannot see.
Flatpak build sandbox cannot see. It then installs the build in the CI
container and runs the packaged app checks described in
[Building](building.md#testing-the-packaged-app). Failed checks upload their
screenshots and logs as a workflow artifact.

## Publishing

Expand Down
7 changes: 3 additions & 4 deletions patches/0001-flatpak-desktop-integration.patch
Original file line number Diff line number Diff line change
Expand Up @@ -33,21 +33,20 @@ index 3c571bcf02..4f1cf91396 100644
preference,
env: input.env,
diff --git a/apps/desktop/src/app/DesktopEnvironment.test.ts b/apps/desktop/src/app/DesktopEnvironment.test.ts
index 200745f111..2b9aa94ef0 100644
index 200745f111..b0f21ccc7d 100644
--- a/apps/desktop/src/app/DesktopEnvironment.test.ts
+++ b/apps/desktop/src/app/DesktopEnvironment.test.ts
@@ -38,6 +38,18 @@ const makeEnvironment = (
@@ -38,6 +38,17 @@ const makeEnvironment = (
) => DesktopEnvironment.DesktopEnvironment.pipe(Effect.provide(layerEnvironment(overrides, env)));

describe("DesktopEnvironment", () => {
+ it.effect("uses a distinct Flatpak display name", () =>
+ it.effect("names the Flatpak desktop entry after the app ID", () =>
+ Effect.gen(function* () {
+ const environment = yield* makeEnvironment(
+ { platform: "linux" },
+ { FLATPAK_ID: "com.t3tools.t3code" },
+ );
+
+ assert.equal(environment.displayName, "T3 Code (Flatpak)");
+ assert.equal(environment.linuxDesktopEntryName, "com.t3tools.t3code.desktop");
+ }),
+ );
Expand Down
12 changes: 2 additions & 10 deletions patches/0002-flatpak-host-backend.patch
Original file line number Diff line number Diff line change
Expand Up @@ -38,10 +38,10 @@ index 69a70b68a4..bcf48615be 100644

diff --git a/apps/desktop/src/backend/flatpakBackend.test.ts b/apps/desktop/src/backend/flatpakBackend.test.ts
new file mode 100644
index 0000000000..cfc536d2e7
index 0000000000..229b483064
--- /dev/null
+++ b/apps/desktop/src/backend/flatpakBackend.test.ts
@@ -0,0 +1,86 @@
@@ -0,0 +1,78 @@
+import { assert, describe, it } from "@effect/vitest";
+import * as Option from "effect/Option";
+
Expand Down Expand Up @@ -104,20 +104,12 @@ index 0000000000..cfc536d2e7
+ `${runtime}/host-server.sh`,
+ ]);
+ assert.equal(result.cwd, "/app/t3code");
+ assert.equal(result.entryPath, config.entryPath);
+ assert.deepEqual(result.env, {});
+ assert.equal(result.bootstrapDelivery, "fd3");
+ assert.equal(result.bootstrap.desktopBootstrapToken, "test-token");
+ assert.equal(result.bootstrap.desktopTelemetryFd, 4);
+ assert.equal(result.bootstrap.desktopTelemetryControlFd, 5);
+ assert.isFalse(result.bootstrap.shellEnvironmentPrepared);
+ assert.equal(result.bootstrap.desktopBrowserFd, 6);
+ assert.equal(result.bootstrap.desktopBrowserControlFd, 7);
+ assert.equal(
+ result.bootstrap.resourceMonitorPath,
+ `${runtime}/resources/resource-monitor/t3-resource-monitor`,
+ );
+ assert.equal(result.httpBaseUrl, config.httpBaseUrl);
+ });
+
+ it("fails preflight instead of falling back to a sandbox backend when the deployment path is missing", () => {
Expand Down
38 changes: 38 additions & 0 deletions scripts/test-packaged
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
#!/usr/bin/env bash
set -euo pipefail

PROJECT_ROOT="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)"
readonly PROJECT_ROOT
readonly IMAGE="ghcr.io/flathub-infra/flatpak-github-actions:freedesktop-25.08"
readonly ENGINE="${CONTAINER_ENGINE:-docker}"
readonly ARTIFACTS="$PROJECT_ROOT/build-flatpak/packaged-test-artifacts"

# The container gets a read-only checkout; only test artifacts come back out.
run() {
local owner=()
# Root in a rootless Podman container is already you; Docker needs the files handed back.
if [ "$ENGINE" = docker ]; then
owner=(-e "HOST_UID=$(id -u)")
fi
rm -rf "$ARTIFACTS"
mkdir -p "$ARTIFACTS"
"$ENGINE" run --rm --privileged \
-v "$PROJECT_ROOT:/src:ro" \
-v "$ARTIFACTS:/artifacts:Z" \
-e T3_TEST_ARTIFACTS=/artifacts \
"${owner[@]}" \
"$IMAGE" /src/tests/packaged/run.sh "$@"
}

case "${1:-local}" in
local)
run --repo /src/build-flatpak/repo
;;
published)
run --commit "${2:?Usage: $0 published <commit>}"
;;
*)
echo "Usage: $0 [local | published <commit>]" >&2
exit 2
;;
esac
Loading