Adopt this repository into the paranext organization

[tjcouch-sil]

Seeds this repo as the paranext organization's source of truth for the editor packages, and documents what that means for everyone who works here or consumes it.

Part of PT-4500.

What this does

Ownership and provenance. Adds a Where this repository lives section: this is a standalone copy of eten-tech-foundation/scripture-editors carrying full history, MIT license, and attribution — deliberately not a GitHub fork, because while a repo is a fork GitHub always defaults new PRs to the parent and offers no setting to change that. Adds a SIL Global / United Bible Societies copyright line alongside ETEN Tech Foundation's; the license stays MIT.

Relationship to paranext-core. Documents that paranext-core does not install these from npm — its preinstall builds them from source and stages them, and its package.json files reference the staged folders with file: specifiers. The consequence worth knowing: this repo's package.json files are authoritative for its own dependencies, so adding or bumping one here flows into paranext-core with nothing to restate on the consuming side.

The platform-yalc branch. Explains why it still exists — the name is historical (paranext-core no longer uses yalc), but its coordination role is real: a breaking change lands on main first and platform-yalc moves forward only once the consuming side is ready.

The eten-tech-foundation remote. How to add it (named eten-tech-foundation, not upstream — we don't track it), pull from it, and contribute back. We may never use it, but the option is deliberately kept open.

Transferring work. docs/transferring-work-from-eten-tech-foundation.md — this repo was seeded with a curated ref set (main, platform-yalc, release-prep, and all 80 release tags), so feature branches were left behind. The guide covers moving branches, tags, and open PRs across, plus re-pointing an existing clone non-destructively.

Release process

Replaces the npm-publishing machinery with a process modeled on paranext-core's. Consumers pin a revision of this repository, not a published version, so a release is a repository tag and one tag pins both packages. Tags are v<platform-editor version>.

• scripts/bump-versions.ts + bump-versions workflow and composite action — sets both package versions on a bump-versions-<version> branch. Tested locally; it moves both manifests and correctly leaves the workspace: specifier alone.
• publish workflow — verifies the requested version matches packages/platform/package.json before tagging (a tag disagreeing with the manifest would pin consumers to a build claiming a different version), creates the release, and can open the follow-up bump branch.
• Removes the scribe publish workflow, the tag-triggered npm publish steps, and the auto-bump-after-publish job. test-publish.yml becomes test.yml, a pure CI workflow.

Nx Cloud references are dropped — no account for this org, and the caching doesn't earn standing one up. It was already commented out in the test workflow ("credits exhausted").

Notes for review

• Nothing here changes the editor's architecture, public API, or package names. Package names stay @eten-tech-foundation/*; renaming was explicitly out of scope.
• packages/scribe removal is a separate PR so the diff against upstream stays easy to reason about.
• The release process is the piece I'd most like a second opinion on — in particular the choice to tag v<platform-editor version> at the repo level rather than keeping per-package platform_v* / utilities_v* tags. Since consumption pins one repo revision, one tag pinning both packages seemed the honest unit, but it's a judgment call.
• The workflows are not exercised by this PR. bump-versions and publish are workflow_dispatch-only and want a real dispatch before anyone relies on them.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VCWPCf35QD5sTkFghsTfUX

---

This change is 

Merge order

This is step 1 of eleven PRs that cannot all be green at once.

Immediately after this merges, move platform-yalc onto the new main
(npm run move-platform-yalc) — it currently carries no committed dist/, and until it does,
paranext-core's staging falls back to a pnpm/nx build that no consumer runner can perform.

In that window verify-platform-yalc.yml fails by design: it reads dev-packages.json from
paranext-core's main, which still predates staged consumption, so there is no lockfile contract to
compare against. npm run move-platform-yalc -- --skip-verify is the intended way through, and this
is the one window it is for. Then merge
paranext-core#2745, then the nine consumer
PRs. Full sequence is in core#2745.

[tjcouch-sil]

Added: the built dist/ is now committed (closes #4, brought into this round rather than deferred).

packages/platform/dist and packages/utilities/dist are tracked, so paranext-core consumes these packages by copying rather than building — no pnpm, no nx, no build during its npm install. Measured on a checkout that has the committed dist: ~7 seconds instead of several minutes, and the whole Volta/pnpm class of install failures leaves the consumer path entirely.

Guarding the obvious risk (a stale dist is invisible in review):

• scripts/verify-committed-dist.mjs + a CI step that rebuilds and fails on any drift.
• Determinism verified before relying on it — rebuilt and compared hashes; every published artifact is byte-identical.
• The one non-deterministic file was dist/*.tsbuildinfo, which turned out to be TypeScript's incremental cache being packed into consumers as though it were a shipped artifact. Now excluded from both git and files.
• README documents the rebuild-and-commit obligation.

Two things reviewers should know:

1. nx caches dist as a target output, so a cache hit restores nx's copy over the committed one and can delete files the cache predates — I hit exactly that (17 spurious deletions). paranext-core's staging builds with --skip-nx-cache. If you see unexplained dist deletions locally, git checkout -- packages/*/dist.
2. Until this merges and platform-yalc rebases past it, core still builds via its fallback path — verified working, so there is no window where core breaks.

[rolfheij-sil]

🤖 Claude: Scope note first, for Matt and TJ: this PR got one AI review pass plus a handful of spot checks by Rolf, not the adversarial re-verification we gave paranext-core#2745, studio#179 and the eight extension PRs — so weight it accordingly, and please don't read "no blockers" as "thoroughly proven". The one thing I did verify mechanically: the committed dist (5 + 6 files, ~4 MB) matches files/.gitignore exactly with no .tsbuildinfo, verify-committed-dist.mjs is byte-exact and runs on every PR and before tagging, bump-versions.ts leaves the workspace:~ specifier alone (that path is live), move-platform-yalc.mjs refuses dirty trees/local-only commits and uses --force-with-lease, and CI is green on the tip.

No blockers. Notes, most useful first:

1. Tag scheme — keep yours. One repo-level v<platform-editor version> is the honest unit because consumers (core's dev-packages.json, studio's productInfo.json) pin one repository revision for both packages; per-package tags would imply an independence the consumption model doesn't have, and the publish event that justified platform_v*/utilities_v* is gone. One gap: the tag doesn't disclose the utilities version — have publish.yml put it in the release body (read packages/utilities/package.json in the workflow).
2. move-platform-yalc locally hits the anonymous rate limit. verify-consumer-lockfile-sync.mjs sizes its 7-day window against the 60 req/h unauthenticated budget (its own comment says ~51 PRs), but npm run move-platform-yalc is the documented local command and GITHUB_TOKEN isn't set outside Actions. A 403 currently surfaces as a bare GET … -> 403 Forbidden (fetchJson, L52–56). Suggest catching 403 and telling the caller to export GITHUB_TOKEN=$(gh auth token), and saying so in the README section.
3. #1 and #2 conflict with each other (confirmed with git merge-tree): README.md (the link-reference block you edit vs the scribe lines #2 deletes) and pnpm-lock.yaml. Whichever merges second needs a manual resolve + lock regeneration — not a rebase-clean situation.
4. Manual npm-publish path is still fully wired: .npmrc (_authToken=${NODE_AUTH_TOKEN}, always-auth), both packages' publishConfig + prepublishOnly/postpublish, and scripts/prepare-publish.ts. CI no longer calls it, but anyone with scope rights could still pnpm publish by hand. Given the "no npm publishing" decision, either remove it or note in the README that it's deliberately kept.
5. README "Releasing" steps 2/4 say "merge the bump-versions-<version> branch" — main is protected, so that's "open a PR from it"; the old flow auto-opened one, the new composite action only pushes the branch.
6. Repo hygiene vs the ticket (not this PR's job, but unowned today): no CODEOWNERS (named in PT-4500 item 3), delete_branch_on_merge is off (core has it on), rulesets empty (classic protection is on; details need an admin), the Reviewable badge is in the PR body but the app isn't installed on this repo, and the _nxCloudAccessToken you remove from nx.json has been in upstream's public history for a long time — worth a quick "is it inert?" with whoever owns that Nx Cloud account.
7. The workflows are unexercised, as you say — a single workflow_dispatch of bump-versions and publish on a test tag (or a fork) before the first real release would be the actual test.

One design question that spans both repos (also raised on paranext-core#2745): this PR mints v<version> tags, but the consumers still pin the force-pushed platform-yalc branch, and this repo carries the machinery to keep that branch in sync with core (verify-consumer-lockfile-sync.mjs, move-platform-yalc). If consumers pinned the tags this release process creates, that machinery and the branch itself could retire — a bump would be a core PR changing the pin and the lockfile together. Asking here because it changes what this repo's release process needs to guarantee (nothing more than "tag = built dist matches source", which publish.yml already checks).

[tjcouch-sil]

Thanks — and the scope note is fair, so I've treated the notes as leads rather than as a clean bill.

Pushed in 1b073fb3:

• Utilities version in the release body (note 1). publish.yml now reads packages/utilities/package.json and puts both packages in the release body as a table. Agreed on keeping the tag scheme.
• Rate limit (note 2). fetchJson now recognises a 403 that is the anonymous budget and says export GITHUB_TOKEN=$(gh auth token) instead of a bare GET … -> 403 Forbidden. It keys on x-ratelimit-remaining: 0 or the absence of GITHUB_TOKEN, so a genuine permissions 403 still reads as itself.
• Release steps 2 and 4 (note 5). Corrected to "open a PR from the bump-versions-<version> branch and merge that" — the branches are protected and the composite action only pushes.

Also on this branch from the earlier round, since they overlap with what you looked at: move-platform-yalc now resets platform-yalc back to origin's state when the lockfile check fails (it previously left the branch rebased and diverged, and the next run then blamed the operator for its own commits); the snapshot copy moved into a mkdtemp directory; test.yml now runs on platform-yalc too, so the committed dist/ is actually verified on the branch core stages from; and all three workflows take Node from the Volta pin rather than hardcoding 20 — publish.yml most of all, since it rebuilds and compares that dist/ before cutting the tag.

Not done, deliberately:

• Note 3 (conflict with Remove the scribe package #2). Real — I confirmed it. That is sequencing for TJ, and whichever lands second needs the manual resolve and a lock regeneration.
• Note 4 (manual npm-publish path). Left as-is. Removing .npmrc, publishConfig, prepublishOnly/postpublish and prepare-publish.ts is more than a review fix, and I'd rather not half-remove a publish path. Worth a decision, then one change.
• Note 6 (repo hygiene). Needs an admin; not something I can do from here.
• Note 7 (workflows unexercised). Agreed, and I'd add: nothing I changed in publish.yml has been exercised either. A workflow_dispatch on a throwaway tag before the first real release is the actual test.
• The Nx Cloud token. I checked: eten-tech-foundation/scripture-editors is public and its main carries the identical token, so this move doesn't change its exposure. Still worth the "is it inert?" conversation, but it isn't a finding against this PR.

On the design question (tags vs the platform-yalc branch): TJ's call, and it's open on core#2745. One data point from the other side of it — paratext-10-studio's productInfo.json no longer names an editor revision at all; devPackageRepos[].branch is now optional and absent means "use whatever core's dev-packages.json pins". So whichever way that decision goes, it is now made in exactly one place.

[tjcouch-sil]

Correcting my earlier reply on note 2 (the anonymous rate limit) — I reported it done, and only half of it was. Both halves are now in 0d456a84.

What was missing: you asked for the 403 to be caught and for the README to say so. I did the first and skipped the second without noticing; the README section on moving platform-yalc had no mention of GITHUB_TOKEN at all. It now says the check spends tens of requests against the 60-an-hour anonymous budget, that Actions sets the token but a local run does not, and gives the one line.

And the detection was too narrow. Checking GitHub's actual behaviour rather than assuming: a rate limit comes back as 403 or 429, the primary limit zeroes x-ratelimit-remaining, and a secondary limit sends retry-after instead. My first version matched only 403-with-remaining-zero, so it would have missed the 429 form of both and every secondary limit. It also treated any unauthenticated 403 as a rate limit, which would confidently mislabel a genuine permissions failure — that case now gets the same advice (a token helps either way) under a hedged description rather than a wrong one.

Verified across nine response shapes: 403 and 429 with each header, a permissions 403 with a token and requests remaining, 404, 500, and a bare 403 both with and without a token in the environment. The check still passes end to end with and without a token.