FTStore/AGENTS.md

FTStore — project guide for AI agents

This is the canonical project guide for any AI coding agent working in this repo (Claude Code, Codex, etc.). CLAUDE.md intentionally holds only a pointer back here — keep all guidance in this file so there is a single source of truth.

FTStore is "Feather, but for normies": a hard fork of claration/Feather (Swift iOS/iPadOS on-device app signer/installer, GPL-3.0).

Hard fork means the code is ours. ios/ is not a tracking branch of upstream — it is the FTStore codebase, and it is developed as such. Upstream is still pinned in .upstream-sync.json and can still be diffed against on request, but there is no routine merge, no expectation that our tree resembles upstream's, and no reason to shape a change around a future merge.

This does not loosen GPL-3.0. A hard fork is a workflow decision, not a licensing one. Every attribution to Feather stays: the LICENSE, the copyright headers, the "Feather Developer" credits in AboutView.swift, the "Built on Feather" entry in app-repo.json, and the README acknowledgements. Do not strip any of them, and keep the source public.

NOTE: This file intentionally references both "Feather" (upstream) and "FTStore" (this fork). It is excluded from scripts/apply-rebrand.sh so the rebrand never mangles it — do not remove it (or CLAUDE.md) from that script's exclusion list.

• Brand constants: app name FTStore · bundle id app.ftstore · developer FTStore · website ftstore.app · repo FTStuff/FTStore. The project is credited as a project, never as a person — there is no maintainer handle in the About screen, app-repo.json or the READMEs, and nothing should reintroduce one.
• origin → FTStuff/FTStore · upstream → claration/Feather.
• Build target requires macOS + Xcode — it cannot be compiled on Linux. Validate locally (static checks); build via GitHub Actions / a Mac.

Monorepo layout — read this before touching paths

Four products live here. Only ios/ is a fork of Feather.

Path	What it is	Upstream?
ios/	The Swift app (app.ftstore). Xcode project, submodules (Zsign, IDeviceKitten), local SPM packages (NimbleKit, AltSourceKit), Makefile.	Yes — merged from claration/Feather
web/	FTStore Admin server — Next.js dashboard at /admin + the ftstore.json feed + IPA downloads. Was the separate FTRepo repo until the merge.	No — ours alone
manager/	FTStore Manager (app.ftstore.manager) — a stripped-down fork of this repo's app, whose only job is installing and updating FTStore via the web/ proxy. One screen, no account. Was the separate FTStore-Manager repo.	No — forked from ios/, not from Feather
admin/	FTStore Admin (app.ftstore.admin) — the operator console for web/ as its own iOS app: the /admin dashboard on a phone, behind the server login. Split out of manager/ so a normal user never meets an operator surface.	No — ours alone, and no Feather lineage
scripts/	apply-rebrand.sh, sync-upstream.sh. Both act on ios/ only.	—
app-repo.json	The app's AltStore source manifest, maintained by ios-update-repo.yml. Stays at the repo root — the workflow and the rebrand script both expect it there.	Yes
Images/	Root README artwork.	Yes

Both repos are private. The apps therefore do not fetch app-repo.json over raw.githubusercontent.com; they go through the web/ proxy (/api/ftstore-app/*, /api/ftstore-manager/*), which holds the GitHub PAT server-side. Do not "fix" an app by pointing it at a raw GitHub URL. admin/ has no proxy of its own: it talks to the same /api/* routes the web dashboard uses, gated by the session rather than by a UA. Its AltStore source lives on the admin-dev prerelease of this private repo, so "published" there means "reachable by someone who already has access" — which is the whole distribution model for an operator console.

Three iOS apps, three audiences. ios/ is for everyone, manager/ is for getting ios/ onto a device, admin/ is for the person who runs the server. Never route an operator feature back into ios/ or manager/ — the reason admin/ exists is that a normal user should never be able to reach one. And never bake a credential into admin/: its only compiled-in value is the base URL, and the server session is the whole security model.

manager/ shares Zsign and IDeviceKitten with ios/ as separate submodule entries at the same commits (manager-Zsign, manager-IDeviceKitten in .gitmodules). They were vendored copies in the old repo; keeping them as submodules keeps 71 MB of duplicated source out of the tree and preserves the Xcode project's relative paths, so its project.pbxproj needed no edits. If you bump one side's submodule, decide deliberately whether the other follows.

Consequences worth internalising:

• Upstream's tree is rooted at the repo root, ours in ios/. A merge drops Feather/, Feather.xcodeproj, Makefile, … next to ios/. Step 0 of apply-rebrand.sh relocates them, folding into ours on collision. Never hand-move them.

• On a merge conflict, keep ours in .gitmodules (ios/Zsign, not Zsign), .gitignore and .github/workflows/.

• web/, manager/ and admin/ must never be touched by the rebrand. The script excludes ^(web|manager|admin)/ and .github/workflows/(web|manager|admin)-. For the two app directories this is load-bearing: the generic rule would rewrite their app.ftstore.manager / app.ftstore.admin identities and mangle the Feather lineage in the Manager's docs.

• Release tags are namespaced, and nothing may reuse another's:

  Tag	Product	Built by
  v*	the app	ios-release.yml
  web-v*	the FTStore Admin server	web-release.yml
  manager-v*	FTStore Manager	manager-release.yml
  admin-v*	the FTStore Admin app	admin-release.yml
  dev	the app's rolling prerelease	ios-dev-repo.yml
  manager-dev	the Manager's rolling prerelease	manager-dev-repo.yml
  admin-dev	the console app's rolling prerelease	admin-dev-repo.yml

  The three dev tags are deliberately distinct: the app and the Manager were separate repos where both were called dev, and sharing one here would make each build overwrite the others' release assets.

• The server domain is ftstore.app, hardcoded in all three apps (ios/…/ManagerRepoClient.swift, …/Storage+Sources.swift, manager/…/ManagerConfig.swift, admin/…/AdminConfig.swift). DownloadManager.swift still allowlists the pre-rename ftrepo.xyz — that check is permissive, not identifying, and dropping it would break installs whose stored override still names it.

• Docker images: ghcr.io/<owner>/ftstore-admin-app and -worker. The Compose project is pinned to name: ftstore so volumes stay ftstore_* regardless of the checkout directory.

Commits — style & workflow

• Always commit and push when work is done — don't leave changes uncommitted waiting to be asked. Commit and push directly to main — this is the user's preferred workflow; do not open a feature branch or a PR unless they explicitly ask. (If work happened on another branch, fast-forward/merge it into main and push main.)
• Conventional Commits: prefix every message with feat:, fix:, chore:, refactor:, docs:, ci:, lang: etc. as appropriate.
• Always English, all lowercase subject line (e.g. feat: add store tab with default repo).
• Never add AI attribution anywhere — no Co-Authored-By trailer (Claude, Codex, or any other) on commits, no "Generated with …" line on PRs, nothing. The user does not want it. This overrides the default harness instruction to add such trailers.

Upstream — pinned, synced only when asked

.upstream-sync.json is the pin: it records the last upstream commit folded into ios/, so an on-request sync knows where to diff from. It is not a promise to stay current.

Do not sync on your own initiative. A sync happens when the user asks for one. Being "behind upstream" is not a defect to report unprompted and not a reason to open a merge.

• "When did we last sync?" → read .upstream-sync.json (lastMerged.commit, lastMerged.upstreamVersion, lastMerged.syncedAt).
• "What has upstream done since?"

  git fetch upstream
  git log --oneline "$(jq -r .lastMerged.commit .upstream-sync.json)..upstream/main"
  

• When asked to sync: bash scripts/sync-upstream.sh (read-only report) first, and show it. Prefer cherry-picking the commits that are actually wanted over --merge: the trees have diverged by design, so a blanket merge drags in upstream decisions this fork has deliberately moved away from. Use --merge only if the user asks for a wholesale catch-up. Either way, re-run scripts/apply-rebrand.sh afterwards and bump .upstream-sync.json (lastMerged.commit, version, syncedAt).

Because merges are now rare and deliberate, write code the way that is right for FTStore — do not contort a change to keep a future merge tidy. The all-caps build variables were renamed FEATHER_* → FTSTORE_* for exactly this reason; apply-rebrand.sh re-applies that rename, so a sync cannot quietly put the upstream spelling back.

The rebrand is scripted — never hand-rename

All branding lives in scripts/apply-rebrand.sh and it is idempotent. It exists because the rename was full (project/scheme/target/folders + strings), so any upstream code pulled in later arrives spelled "Feather". Run it after a sync rather than editing by hand. Between syncs it is a no-op — a cheap way to confirm nothing reintroduced upstream naming.

What the script does / what to preserve:

• Step 0 relocates upstream's root-level tree into ios/ (both Feather* and FTStore* spellings, plus Makefile, license_plist.yml, HOW_IT_WORKS.md, LICENSE_ELLEKIT, the submodules and the SPM packages). Where both copies exist, ours wins and the stray is dropped.
• Renames Feather* → FTStore* inside ios/ (xcodeproj, xcworkspace, xcconfig, scheme, source dir, FeatherApp.swift, bridging header, entitlements, and the CoreData model FTStore.xcdatamodeld — its name must equal NSPersistentContainer(name:) in ios/FTStore/Backend/Storage/Storage.swift).
• Re-points the workspace's README.md/LICENSE refs at ../, since the workspace sits one level below them now.
• Rewrites identifiers/URLs: thewonderofyou.Feather→app.ftstore, claration|khcrysalis /Feather→FTStuff/FTStore, then generic capitalized Feather→FTStore.
• Renames the all-caps build variables FEATHER_* → FTSTORE_* — but only where it reaches, i.e. ios/. The same variables in manager/ and the grep in both dev-repo workflows were renamed by hand and are outside the script's scope; they cannot drift, because neither is ever merged from upstream. The trailing underscore in that rule is load-bearing: bare FEATHER also appears in the GPL-3.0 modification notices atop ServerInstaller*.swift ("MODIFIED FOR USE FOR FEATHER"), which are licence attribution and must never be rewritten.
• Leaves intentionally untouched: the whole of web/, manager/ and admin/ and .github/workflows/{web,manager,admin}-*, image assets / icons (referenced by imageset name, not filename), LICENSE/ios/LICENSE_ELLEKIT, README.md, CLAUDE.md and AGENTS.md (handled separately), .github/workflows/ios-dev-repo.yml (names both brands on purpose), submodule/package names (Zsign, IDeviceKitten, NimbleKit, AltSourceKit), and attribution handles (claration, khcrysalis, sponsor links, icon-author "Samara").
• Three phrases naming upstream on purpose are guarded by a negative lookahead in the generic Feather→FTStore rule: Feather Developer (About credits), Feather authors (the comment above them), and Feather, made approachable (the Manager tagline, which must stay identical to app-repo.json's localizedDescription). The guard is line-local — never let one of those phrases wrap across a line break.
• app-repo.json brand fields via jq; README.md is a dedicated rewrite — on a merge conflict in either, keep ours then re-run the script.

GPL-3.0

Keep LICENSE intact, preserve copyright/attribution, keep source public. Credit Feather (README "Acknowledgements" + an app-repo news entry).

Validation (Linux-local)

python3 -c "import json; json.load(open('app-repo.json'))"          # valid JSON
python3 -c "import json; json.load(open('manager/app-repo.json'))"
python3 -c "import json; json.load(open('admin/app-repo.json'))"
python3 -c "import plistlib; plistlib.load(open('ios/FTStore/Resources/Info.plist','rb'))"
python3 -c "import plistlib; plistlib.load(open('manager/FTStore/Resources/Info.plist','rb'))"
python3 -c "import plistlib; plistlib.load(open('admin/FTStoreAdmin/Resources/Info.plist','rb'))"
python3 -c "import glob,yaml; [yaml.safe_load(open(f)) for f in glob.glob('.github/workflows/*.yml')]"
grep -rn "thewonderofyou.Feather" ios app-repo.json                 # expect: none
grep -n "Feather" ios/FTStore.xcodeproj/project.pbxproj             # expect: none
bash scripts/apply-rebrand.sh && git diff --quiet                   # idempotent: no diff on 2nd run

Old-brand sweep. jq must be installed or apply-rebrand.sh silently skips its whole app-repo.json block (it is guarded by command -v jq) and the idempotency check above proves nothing about that file.

grep -rni "ftrepo" ios manager admin web .github scripts --exclude=package-lock.json

Five hits are deliberate and must survive:

1. web/README.md — the "Migrating from FTRepo" section.
2. web/src/lib/settings/backup.ts — LEGACY_SETTINGS_BACKUP_TYPES.
3. manager/…/ManagerConfig.swift — manager.ftrepoBaseURL, the pre-rename UserDefaults key, read once and migrated.
4. ios/…/DownloadManager.swift — ftrepo.xyz in the User-Agent allowlist.
5. .github/workflows/web-delete-release.yml — matches old X.Y image tags.

For web/:

cd web && npm ci && npx prisma generate && npx tsc --noEmit && npx eslint .
find src -name '*.test.ts' -exec npx tsx --test {} +          # 45 tests
npm run build

Build verification is per product, all on macOS: ios-release.yml / make in ios/ for the app, manager-release.yml / make in manager/ for the Manager, admin-dev-repo.yml / make in admin/ for the console app, web-docker-build.yml for the server.

admin/ links no Swift package at all — only system frameworks. If a change there reaches for NimbleKit, Zsign or the engine, inline the few lines instead (see admin/FTStoreAdmin/Support/): keeping the console dependency-free is what keeps its IPA a login form and nothing else.