Skip to content

Commit 0863e90

Browse files
radroidclaude
authored andcommitted
feat(coil): put the real install steps on the download page, from one source (#72)
Someone who has never seen this repo could go from the landing page to a Mac that says the app is damaged, with nothing on screen to explain it. The steps existed — they were just unfindable. Three gaps, all closed here. `download.astro` said "the release notes carry the commands to get past it". It did not link them, and the buttons hand you a dmg straight from the relay manifest, so nothing makes you pass a release note on the way. The steps are now rendered inline next to the button that produced the file, with copy buttons. The copy is also corrected. "Will warn on first launch" undersold it: Gatekeeper does not say *unidentified developer* for this bundle, it says the app **is damaged and should be moved to the Trash** — because the bundle carries Electron's inherited ad-hoc signature with no sealed resources — and right-click → Open does not bypass that. A reader told to expect a warning reasonably concludes the download is corrupt and gives up. The page and the release notes now both say damaged, and both say right-click → Open will not help. A test asserts that wording, so softening it fails rather than quietly regressing. macOS leads with *drag to /Applications first*, because App Translocation is invisible when it happens and later breaks self-updates. The platform matrix is stated plainly: macOS arm64 only, Windows x64 only, no Linux. `scripts/t3x/install-instructions.json` is the single source, consumed by: - `apps/coil-home/src/lib/install.ts`, imported at build time so the steps are on the page even when the relay is unreachable and there is nothing else to show; - `scripts/t3x/render-release-notes.mjs`, which the release workflow renders to a file and passes as `body_path`, replacing the inline YAML the notes lived in. The fallback `gh release create` path now uses the same file. It used to say "see any earlier release on this repo" because the action's inline body was not reachable from the retry step — a release that landed via the fallback was a second-class one. It no longer is. A rendering failure cannot cost a release: by the time that step runs, both matrix legs have finished and ~22 minutes of macOS and Windows compute is spent, so a non-zero exit degrades to a minimal body that still links the download page, and warns. `.mjs`, not `.ts`, deliberately — the publish job has no `setup-node` step, so it runs on whatever Node the runner image ships, and type stripping needs 22.18+. Types come from a hand-written `.d.mts` so the test still typechecks. Its sibling `build-update-manifest.mjs` is `.mjs` for the same reason. The bundle name is the one thing that has to be duplicated — the renderers should not reach into the desktop app's package.json, and the download page cannot read it at runtime. So it is cached in the JSON and a test asserts it equals `apps/desktop/package.json`'s `productName`. That turns #71's rename from silent drift — every published `xattr` command pointing at a bundle that no longer exists — into a failing test. Both still sent readers to `pingdotgg/t3code` releases, `winget install T3Tools.T3Code` and `brew install --cask t3-code`. None of those install this fork. Both now carry a callout saying so and pointing at the download page. Upstream's text is untouched — the callouts are inserted above it, so both rows stay +N/-0 and the additive-seam invariant holds. They are rows 39 and 40 in SEAMS.md (README.md +15/-0 churn 5 risk 75; docs/user/install.md +17/-0 churn 1 risk 17). Regenerating the ledger to add them also found the `pnpm-lock.yaml` row 13 lines stale: `apps/coil-home`'s workspace entry landed across `99b83bf55` (+16), `2a6053745` (-3) and `7197fa589`, and none of them moved the row — exactly the failure the note above the ledger warns about. Corrected here, with the header total, to a measured 40 files / +2037 / -913 — the row itself was still `+317` on main even after #40 moved the header to match the recipe, so this closes the drift on both sides. Closes #72 Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent 8184981 commit 0863e90

10 files changed

Lines changed: 750 additions & 54 deletions

File tree

‎.github/workflows/t3x-release.yml‎

Lines changed: 39 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -592,6 +592,32 @@ jobs:
592592
CHANGES: ${{ needs.resolve.outputs.changes }}
593593
run: node scripts/t3x/build-update-manifest.mjs staged staged/t3x-latest.json
594594

595+
# The install steps used to live inline in this file, which made the release body the only
596+
# place they existed — and the download page pointed at "the release notes" without linking
597+
# them, so a first-time reader could go from the landing page to an app macOS calls damaged
598+
# having never seen one (issue #72). Both surfaces now render
599+
# scripts/t3x/install-instructions.json.
600+
#
601+
# A rendering failure must not cost a release: by the time this step runs, both matrix legs
602+
# have finished and ~22 minutes of macOS and Windows compute is already spent. So a failure
603+
# here degrades to a minimal body that still points at the download page, and warns.
604+
- name: Render the release notes
605+
id: notes
606+
shell: bash
607+
env:
608+
FULL_SHA: ${{ needs.resolve.outputs.sha }}
609+
SHORT_SHA: ${{ needs.resolve.outputs.short_sha }}
610+
NOTES_PATH: ${{ runner.temp }}/release-notes.md
611+
run: |
612+
set -uo pipefail
613+
if ! node scripts/t3x/render-release-notes.mjs \
614+
--sha "$FULL_SHA" --short-sha "$SHORT_SHA" > "$NOTES_PATH"; then
615+
echo "::warning::Could not render the install notes; publishing a minimal body. This is a bug in scripts/t3x/render-release-notes.mjs — the release itself is fine."
616+
printf 'Automated fork build of `%s`.\n\nInstall instructions: https://coil.curlycloud.dev/download\n' \
617+
"$FULL_SHA" > "$NOTES_PATH"
618+
fi
619+
echo "path=$NOTES_PATH" >> "$GITHUB_OUTPUT"
620+
595621
- name: Create release
596622
id: create_release
597623
uses: softprops/action-gh-release@v2
@@ -607,40 +633,7 @@ jobs:
607633
staged/T3Code-*
608634
staged/t3x-latest.json
609635
fail_on_unmatched_files: true
610-
# The manual-install commands are here rather than in a doc because this page is where
611-
# someone stands when they need them. Both platforms' in-app updaters already handle
612-
# this — macAttachCommands/macCopyCommands strip quarantine from the dmg and the staged
613-
# bundle — so ONLY a hand-downloaded copy hits it, which is exactly the bootstrap case:
614-
# the first install on a machine, and any install after the updater itself breaks.
615-
body: |
616-
Automated fork build of `${{ needs.resolve.outputs.sha }}`.
617-
618-
Unsigned. In-app updates strip quarantine themselves; a **manually downloaded** copy
619-
does not go through that path and needs one command by hand.
620-
621-
**macOS** — drag the app to `/Applications` FIRST. Launching from the mounted dmg
622-
triggers App Translocation, and the updater refuses to replace a translocated app.
623-
Then:
624-
625-
```
626-
xattr -dr com.apple.quarantine "/Applications/T3 Code (Alpha).app"
627-
```
628-
629-
Without this, Gatekeeper calls the app *damaged* rather than merely unsigned — the
630-
bundle carries Electron's inherited ad-hoc linker signature with no sealed resources —
631-
and right-click → Open does NOT bypass that.
632-
633-
**Windows** — clear Mark-of-the-Web, then choose *More info → Run anyway* at the
634-
SmartScreen prompt:
635-
636-
```
637-
Unblock-File -Path .\T3Code-${{ needs.resolve.outputs.short_sha }}-x64.exe
638-
```
639-
640-
Windows x64 only; there is no arm64 asset. SHA-256 for every asset is in
641-
`t3x-latest.json` above.
642-
643-
Design: `docs/superpowers/specs/2026-08-03-update-delivery-design.md`.
636+
body_path: ${{ steps.notes.outputs.path }}
644637

645638
# Build 9 (run 31244161522) died here: both matrix legs green, both artifacts uploaded, and
646639
# then ~22 minutes of macOS and Windows compute discarded by one 14-second API call that
@@ -684,18 +677,21 @@ jobs:
684677
RELEASE_TAG: ${{ needs.resolve.outputs.tag }}
685678
RELEASE_NAME: ${{ needs.resolve.outputs.version }}
686679
TARGET_SHA: ${{ needs.resolve.outputs.sha }}
680+
NOTES_FILE: ${{ steps.notes.outputs.path }}
687681
run: |
688682
set -uo pipefail
689683
echo "::warning::action-gh-release failed and does not retry; falling back to gh."
690684
691-
# The notes the action would have published are not reachable from here, so the fallback
692-
# release points at the one place that always carries them rather than duplicating the
693-
# text and letting the two copies drift.
694-
notes="Automated fork build of \`${TARGET_SHA}\`.
695-
696-
Published by the fallback path after \`action-gh-release\` returned a transient error.
697-
Install notes: see any earlier release on this repo, or the design doc at
698-
\`docs/superpowers/specs/2026-08-03-update-delivery-design.md\`."
685+
# The fallback publishes the SAME notes the action would have. It used to say "see any
686+
# earlier release" instead, because the action's inline body was not reachable from
687+
# here — now that the notes are rendered to a file before either path runs, a release
688+
# that lands via the fallback is no longer a second-class one.
689+
if [[ ! -s "${NOTES_FILE:-}" ]]; then
690+
echo "::warning::No rendered notes at '${NOTES_FILE:-}'; writing a minimal body."
691+
NOTES_FILE="$RUNNER_TEMP/fallback-release-notes.md"
692+
printf 'Automated fork build of `%s`.\n\nInstall instructions: https://coil.curlycloud.dev/download\n' \
693+
"$TARGET_SHA" > "$NOTES_FILE"
694+
fi
699695
700696
# Five attempts at 0s, 30s, 90s, 210s and 450s. The empty final element is what makes the
701697
# last attempt run without a trailing sleep.
@@ -715,7 +711,7 @@ jobs:
715711
--target "$TARGET_SHA" \
716712
--title "$RELEASE_NAME" \
717713
--prerelease \
718-
--notes "$notes" \
714+
--notes-file "$NOTES_FILE" \
719715
staged/T3Code-* staged/t3x-latest.json; then
720716
exit 0
721717
fi

‎README.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,21 @@ We wanted something performant, remote-ready, and truly open. If we ever go the
1212

1313
## Installation
1414

15+
> [!IMPORTANT]
16+
> **This repository is `radroid/t3code`, a fork. It builds an app called Coil, and the package-registry commands further down do not install it.**
17+
>
18+
> `winget install T3Tools.T3Code`, `brew install --cask t3-code` and `yay -S t3code-bin` all install upstream's T3 Code — a different app, from a different repository, that updates from a different place. They are correct if upstream is what you want; they are the wrong thing if you got here looking for this fork's build.
19+
>
20+
> **Fork builds live at [coil.curlycloud.dev/download](https://coil.curlycloud.dev/download).** That page carries the per-platform first-launch steps inline, and you will need them: these builds are not code-signed, so macOS calls the app _damaged_ on first launch rather than merely unsigned, and right-click → Open does not get past that. The same steps are in the body of every [GitHub release](https://github.com/radroid/t3code/releases) — both are rendered from `scripts/t3x/install-instructions.json`, so they cannot drift.
21+
>
22+
> | Platform | Built | Notes |
23+
> | -------- | --------------------- | ----------------- |
24+
> | macOS | Apple Silicon (arm64) | No Intel build |
25+
> | Windows | x64 | No arm64 build |
26+
> | Linux | Not built | Build from source |
27+
>
28+
> Everything else in this README is upstream's and applies unchanged — the fork's own docs are under [`docs/t3x/`](docs/t3x/).
29+
1530
> [!WARNING]
1631
> T3 Code currently supports Codex, Claude, Cursor, Grok Build and OpenCode. Install and authenticate at least one provider before use:
1732
>

‎apps/coil-home/src/lib/install.ts‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
/*
2+
* First-run install instructions for the download page.
3+
*
4+
* The data is NOT defined here. It lives in scripts/t3x/install-instructions.json, which the
5+
* release workflow also renders into every GitHub release body via
6+
* scripts/t3x/render-release-notes.mjs. Two surfaces, one source — before issue #72 the release
7+
* body was the only copy, and this page merely said the release notes "carry the commands to get
8+
* past it" without linking them, so a reader could arrive here, download a build, and meet a
9+
* Gatekeeper dialog calling it damaged with nothing on screen to explain it.
10+
*
11+
* The JSON is imported rather than fetched, on purpose: these steps have to be on the page when
12+
* it renders, including when the update relay is down and there is nothing else to show. The
13+
* types come from the import — hand-written interfaces here would be a third copy of the shape.
14+
*/
15+
import instructions from "../../../../scripts/t3x/install-instructions.json";
16+
17+
export const APP_BUNDLE_NAME = instructions.appBundleName;
18+
export const UNSIGNED_NOTE = instructions.unsignedNote;
19+
export const INSTALL_PLATFORMS = instructions.platforms;
20+
21+
export type InstallPlatform = (typeof INSTALL_PLATFORMS)[number];
22+
23+
/**
24+
* Fills a command template for display. `{file}` is the asset the reader is about to download,
25+
* so the page renders the example name and the client script swaps in the real one once the
26+
* manifest arrives. Passing `"{file}"` back in leaves the placeholder intact, which is how the
27+
* template is handed to the browser.
28+
*/
29+
export function fillCommand(template: string, file: string): string {
30+
return template.replace(/\{app\}/gu, APP_BUNDLE_NAME).replace(/\{file\}/gu, file);
31+
}
32+
33+
/**
34+
* Marks up the small amount of `**bold**` the instruction copy uses, and nothing else. The text
35+
* is ours rather than user input, but it is interpolated with `set:html`, so it is escaped first
36+
* — the alternative is a rule that only holds until someone pastes a Gatekeeper message
37+
* containing a `<` into the JSON.
38+
*/
39+
export function renderEmphasis(text: string): string {
40+
const escaped = text.replace(/&/gu, "&amp;").replace(/</gu, "&lt;").replace(/>/gu, "&gt;");
41+
return escaped.replace(/\*\*([^*]+)\*\*/gu, "<strong>$1</strong>");
42+
}

0 commit comments

Comments
 (0)