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
15 changes: 14 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,10 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
with:
# A PR builds GitHub's merge commit; its parents are the base and the
# PR head, which the changelog check compares.
fetch-depth: 2

- uses: pnpm/action-setup@v6

Expand All @@ -30,6 +34,13 @@ jobs:
# Fails loudly if the lockfile has drifted, which is the point of pnpm here.
- run: pnpm install --frozen-lockfile

# A branch cut before a release commit landed merges its [Unreleased]
# lines into the section that release created, so the merge releases
# nothing (#19 did exactly this to 0.9.0).
- name: Check changelog entries stay under [Unreleased]
if: github.event_name == 'pull_request'
run: pnpm exec vite-node scripts/check-changelog.ts

# Builds @fadeltd/devtools-core first: the app imports its compiled dist/.
- name: Typecheck
run: pnpm typecheck
Expand All @@ -52,7 +63,9 @@ jobs:
pnpm pack --pack-destination "$RUNNER_TEMP" >/dev/null
LIST=$(tar -tzf "$RUNNER_TEMP"/fadeltd-devtools-core-*.tgz)
for sub in base64 diff hash html-text id-gen json jwt list number random slug text text-bytes text-stats timestamp unicode url; do
echo "$LIST" | grep -qx "package/dist/$sub/index.d.ts" || { echo "::error::Missing dist/$sub/index.d.ts"; exit 1; }
# A here-string, not `echo | grep -q`: grep -q stops reading at the
# first match, and under pipefail the writer's SIGPIPE fails the step.
grep -qx "package/dist/$sub/index.d.ts" <<< "$LIST" || { echo "::error::Missing dist/$sub/index.d.ts"; exit 1; }
done
if echo "$LIST" | grep -E '\.test\.|fixture'; then
echo "::error::Tests or fixtures would be published."
Expand Down
163 changes: 103 additions & 60 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ jobs:
--package packages/core/package.json
--tag-prefix core-v

- name: Commit the changelogs and tag
- name: Commit the changelogs
if: steps.cut.outputs.released == 'true' || steps.cut_core.outputs.released == 'true'
env:
SITE_TAG: ${{ steps.cut.outputs.tag }}
Expand All @@ -78,8 +78,8 @@ jobs:
FILES="CHANGELOG.md package.json packages/core/CHANGELOG.md packages/core/package.json"
TAGS=$(echo "${SITE_TAG} ${CORE_TAG}" | xargs)

# Each push is guarded, so a partially-completed earlier attempt can
# be resumed rather than blocking every retry.
# Guarded, so a partially-completed earlier attempt can be resumed
# rather than blocking every retry.
if git diff --quiet -- $FILES; then
echo "::notice::Changelogs and versions already committed."
else
Expand All @@ -90,71 +90,111 @@ jobs:
git push origin HEAD:main
fi

for TAG in $TAGS; do
# Tag the release commit itself -- the one whose subject names this
# tag -- not whatever main points at, so a re-run after a later
# merge still tags the right commit.
RELEASE_COMMIT=$(git log -n 50 --format='%H %s' | awk -v t="$TAG" '$2 == "Release" { for (i = 3; i <= NF; i++) if ($i == t) { print $1; exit } }')
if [ -z "$RELEASE_COMMIT" ]; then
echo "::error::Could not find the release commit for ${TAG}."
exit 1
fi

# An existing tag is only "already done" if it points at the
# release commit. core-v0.1.0 was once pushed by hand onto the merge
# commit seconds before this step; trusting it silently attached
# the release to code that still said version 0.0.0.
REMOTE=$(git ls-remote --tags origin "refs/tags/${TAG}" "refs/tags/${TAG}^{}" | awk '{ print $1 }' | tail -n 1)
if [ -z "$REMOTE" ]; then
git tag -a "${TAG}" "${RELEASE_COMMIT}" -m "${TAG}"
git push origin "${TAG}"
elif [ "$REMOTE" = "$RELEASE_COMMIT" ]; then
echo "::notice::${TAG} already exists on the release commit."
else
echo "::error::${TAG} exists but points at ${REMOTE}, not the release commit ${RELEASE_COMMIT}. Tags are created only by this workflow: delete the stray tag (and its GitHub release, if any) and re-run."
exit 1
fi
done

# The notes go through env, never through ${{ }} in the script. Expression
# substitution pastes the text into the script BEFORE bash parses it, so
# every backtick in the changelog (`display: flex`) was run as a command
# and the step died -- after the tag was pushed, so Deploy never started.
- name: Create the site's GitHub release
if: steps.cut.outputs.released == 'true'
# Runs on every merge, not only when this run cut something, and tags
# every release commit that is still missing its tags: this run's, and
# any an earlier run committed but failed to tag. Tags go on the release
# commit itself -- the one whose subject names them -- never on whatever
# main points at.
#
# It walks back from main to the newest release commit whose tags and
# GitHub releases all exist, then works oldest first, so tags and GitHub releases are created
# in version order and history before that point is left alone.
#
# No pipeline here may stop reading early (`awk '{ ...; exit }'`,
# `grep -q`, `head`): under pipefail the writer then dies of SIGPIPE,
# exit 141 fails the step, and that is how v0.8.0 to v0.9.0 were left
# untagged and undeployed.
- id: tag
name: Tag and publish GitHub releases
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
TAG: ${{ steps.cut.outputs.tag }}
NOTES: ${{ steps.cut.outputs.notes }}
run: |
gh release create "$TAG" --verify-tag --title "$TAG" --notes "$NOTES" \
|| echo "::notice::Release already exists."
set -euo pipefail
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git fetch --quiet origin main
git ls-remote --tags origin > "$RUNNER_TEMP/remote-tags"

remote_sha() {
local tag=$1 sha="" ref_sha ref
# The peeled ^{} line, when present, is the commit an annotated
# tag points at; it is listed after the tag object itself.
while read -r ref_sha ref; do
if [ "$ref" = "refs/tags/${tag}" ] || [ "$ref" = "refs/tags/${tag}^{}" ]; then sha=$ref_sha; fi
done < "$RUNNER_TEMP/remote-tags"
echo "$sha"
}

# Release tags named in a commit subject, minus "[skip ci]".
tags_of() {
local word
for word in $1; do
case "$word" in v[0-9]*|core-v[0-9]*) echo "$word" ;; esac
done
}

# A file, not a pipe or process substitution: the loop stops early.
git log -n 100 --format='%H %s' origin/main > "$RUNNER_TEMP/log"
PENDING=()
while read -r SHA WORD REST; do
[ "$WORD" = "Release" ] || continue
DONE=true
for TAG in $(tags_of "$REST"); do
[ -n "$(remote_sha "$TAG")" ] || DONE=false
gh release view "$TAG" > /dev/null 2>&1 || DONE=false
done
[ "$DONE" = false ] || break
PENDING=("$SHA" "${PENDING[@]}")
done < "$RUNNER_TEMP/log"

DEPLOY_TAG=""
for SHA in "${PENDING[@]}"; do
SUBJECT=$(git log -n 1 --format=%s "$SHA")
for TAG in $(tags_of "${SUBJECT#Release }"); do
REMOTE=$(remote_sha "$TAG")
if [ -z "$REMOTE" ]; then
git tag -a "$TAG" "$SHA" -m "$TAG"
git push origin "refs/tags/${TAG}"
echo "Tagged ${TAG} on ${SHA}" >> "$GITHUB_STEP_SUMMARY"
elif [ "$REMOTE" != "$SHA" ]; then
# core-v0.1.0 was once pushed by hand onto the merge commit;
# trusting it attached the release to code still at 0.0.0.
echo "::error::${TAG} exists but points at ${REMOTE}, not the release commit ${SHA}. Tags are created only by this workflow: delete the stray tag (and its GitHub release, if any) and re-run."
exit 1
fi

case "$TAG" in
core-v*) FILE=packages/core/CHANGELOG.md; TITLE="@fadeltd/devtools-core ${TAG#core-v}" ;;
*) FILE=CHANGELOG.md; TITLE="$TAG" ;;
esac
if ! gh release view "$TAG" > /dev/null 2>&1; then
# Notes come from the changelog as it was at that release
# commit, and go through a file, never an Actions expression:
# expressions are pasted into the script before bash parses
# it, so a backtick in the notes would run as a command.
git show "${SHA}:${FILE}" > "$RUNNER_TEMP/changelog.md"
pnpm exec vite-node scripts/release-notes.ts "$RUNNER_TEMP/changelog.md" "${TAG#*v}" > "$RUNNER_TEMP/notes.md"
gh release create "$TAG" --verify-tag --title "$TITLE" --notes-file "$RUNNER_TEMP/notes.md"
fi
case "$TAG" in v*) DEPLOY_TAG=$TAG ;; esac
done
done
echo "deploy_tag=${DEPLOY_TAG}" >> "$GITHUB_OUTPUT"

# Always dispatch, unconditionally.
# Always dispatch when a site tag was made or completed, for the newest
# one only: it contains every earlier release.
#
# This previously only ran when no PAT was configured, on the assumption
# that a PAT-pushed tag would trigger Deploy natively via `on: push:
# tags`. With a PAT present that assumption silently took over and no
# deploy ever happened: the tag was pushed, Release reported success, and
# Deploy had zero runs. Dispatching every time removes the dependency on
# how GitHub attributes the push. Deploy is idempotent -- it builds and
# uploads the same tag -- so a duplicate run is harmless, whereas a
# missed one is invisible.
# Never left to `on: push: tags`. With a PAT present that path silently
# took over once and no deploy ever happened: the tag was pushed, Release
# reported success, and Deploy had zero runs. Dispatching removes the
# dependency on how GitHub attributes the push. Deploy is idempotent, so a
# duplicate run is harmless, whereas a missed one is invisible.
- name: Start Deploy
if: steps.cut.outputs.released == 'true'
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: gh workflow run deploy.yml --ref main -f tag="${{ steps.cut.outputs.tag }}"

- name: Create the devtools-core GitHub release
if: steps.cut_core.outputs.released == 'true'
if: steps.tag.outputs.deploy_tag != ''
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
TAG: ${{ steps.cut_core.outputs.tag }}
NOTES: ${{ steps.cut_core.outputs.notes }}
run: |
gh release create "$TAG" --verify-tag --title "@fadeltd/devtools-core ${TAG#core-v}" --notes "$NOTES" \
|| echo "::notice::Release already exists."
TAG: ${{ steps.tag.outputs.deploy_tag }}
run: gh workflow run deploy.yml --ref main -f tag="$TAG"

# Trusted publishing (OIDC): npm verifies that this workflow, in this
# repo, is the one allowed to publish. No npm token is stored anywhere,
Expand Down Expand Up @@ -193,6 +233,9 @@ jobs:

- name: Summary
run: |
if [ -n "${{ steps.tag.outputs.deploy_tag }}" ]; then
echo "Deploying ${{ steps.tag.outputs.deploy_tag }}" >> "$GITHUB_STEP_SUMMARY"
fi
if [ "${{ steps.cut.outputs.released }}" = "true" ]; then
echo "Released ${{ steps.cut.outputs.tag }}" >> "$GITHUB_STEP_SUMMARY"
fi
Expand Down
4 changes: 2 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,13 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and

## [Unreleased]

Nothing yet.
### Added
- JSON Formatter: narrow the output to one part of the document. Select a node in Tree view and press Filter, or type a path into the new Filter field as `.items[0].id`, `items[0].id`, `$.items[0].id` or `/items/0/id`. Both the text output and the tree show just that node, and Copy copies just that node. Copied paths still point into the whole document. A path that doesn't match says where it stopped (`.items has 3 items; there is no [5]`), and the ↑ button moves up one level.

## [0.9.0] — 2026-10-29

### Added
- Pin your favourite tools to the top. Use the pin next to any tool's name, or Pin in the ⌘K palette, and the tool appears in a Pinned section at the top of the sidebar and the home page, in order, with its ⌘1–⌘9 shortcut shown beside it. Up to nine tools can be pinned.
- JSON Formatter: narrow the output to one part of the document. Select a node in Tree view and press Filter, or type a path into the new Filter field as `.items[0].id`, `items[0].id`, `$.items[0].id` or `/items/0/id`. Both the text output and the tree show just that node, and Copy copies just that node. Copied paths still point into the whole document. A path that doesn't match says where it stopped (`.items has 3 items; there is no [5]`), and the ↑ button moves up one level.

### Fixed
- On phones, the GitHub and Settings icons at the top right no longer have a wide empty gap between them.
Expand Down
7 changes: 6 additions & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ Inside the package, relative imports carry a `.ts` extension; `rewriteRelativeIm

This is what makes ~30 tools maintainable, what lets any phase stop and still ship something correct, and what lets the engines be reused in other apps and a CLI.

**Two changelogs, two versions.** The site (`CHANGELOG.md`, tags `v*`) and the package (`packages/core/CHANGELOG.md`, tags `core-v*`) release independently. A change to an engine's API or behaviour needs an entry in the package changelog; if it also changes what a site visitor sees, it needs one in the site changelog too. Before 1.0, a breaking package change is a minor bump — call it out under `### Breaking`. Tags (`v*`, `core-v*`) are created only by the Release workflow, on the release commit; never tell anyone to create, push or check out a release tag before Release has made it. The package is published only by CI, through npm trusted publishing (OIDC, no token).
**Two changelogs, two versions.** The site (`CHANGELOG.md`, tags `v*`) and the package (`packages/core/CHANGELOG.md`, tags `core-v*`) release independently. A change to an engine's API or behaviour needs an entry in the package changelog; if it also changes what a site visitor sees, it needs one in the site changelog too. Before 1.0, a breaking package change is a minor bump — call it out under `### Breaking`. If a release lands on `main` while a branch is open, merge `main` and keep the branch's entries under `[Unreleased]`; CI (`scripts/check-changelog.ts`) fails a PR whose merge would put them in a released section. Tags (`v*`, `core-v*`) are created only by the Release workflow, on the release commit; never tell anyone to create, push or check out a release tag before Release has made it. The package is published only by CI, through npm trusted publishing (OIDC, no token).

## Design system

Expand Down Expand Up @@ -106,6 +106,11 @@ Each of these is a silent data-corruption bug, not a style preference:
- **The same goes for commit message bodies and PR descriptions.** Keep the subject line short, then write each body paragraph or bullet as one line; GitHub and `git log` wrap it for display.
- **Never write the skip marker (`[skip ci]`, `[ci skip]`, `[no ci]`) in a commit message unless you mean it** — not even to describe the release commit. GitHub skips *every* workflow for that push if it appears anywhere in the message, and squash merges here reuse the commit body, so it would also silently skip Release on `main`. Say "the release commit" instead.

### Workflows

- **Under `set -o pipefail`, never pipe into a reader that stops early** (`awk '{ …; exit }'`, `grep -q`, `head`). The writer dies of SIGPIPE, exit 141 fails the step, and it happens on most runs, not just occasionally. That is how v0.8.0 to v0.9.0 were committed but never tagged or deployed. Write to a file or use a here-string instead.
- **Never write `${{ }}` in a `run:` script, not even in a comment.** GitHub expands expressions everywhere in the script before bash runs it. Run `actionlint` on workflow changes.

## Toolchain notes

- TypeScript 7 (Go-native). `tsc -v` works, `tsc --version` does not. `baseUrl` was **removed** — `paths` resolve relative to `tsconfig.json`.
Expand Down
8 changes: 6 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,8 +65,12 @@ Merging to `main` then does the rest, automatically:

1. Reads `[Unreleased]` and derives the semver bump from its headings — `### Breaking` → major, `### Added` → minor, anything else (`Fixed`, `Changed`, `Security`, `Removed`) → patch.
2. Rewrites `CHANGELOG.md`, moving `[Unreleased]` into a dated `## [x.y.z]` section and leaving a fresh empty `[Unreleased]` behind.
3. Bumps `version` in `package.json`, commits that back to `main`, and pushes the tag `vx.y.z`.
4. **The tag** triggers the deploy to Cloudflare. Merging alone never deploys.
3. Bumps `version` in `package.json`, commits that back to `main`, and tags that release commit `vx.y.z` with a GitHub release.
4. Starts the deploy to Cloudflare for that tag. Merging alone never deploys.

If a run commits the release but fails before tagging it, the next run finishes the job: Release tags every release commit on `main` that is still missing its tags or GitHub release, oldest first, and deploys the newest.

If a release lands on `main` while your branch is open, merge `main` in and make sure your entries are still under `## [Unreleased]`. A plain merge keeps a new line next to its old neighbours, which may now sit under the new version heading, and then your merge releases nothing. CI fails the PR when that happens.

**Never create or push a `v*` or `core-v*` tag yourself.** Release tags the release commit, the one that bumps the version. A hand-made tag on the merge commit points at code whose `package.json` still has the old version, and Release now refuses to continue when it finds one. To look at or publish a release locally, wait for the tag to appear (`git fetch --tags`).

Expand Down
Loading
Loading