A native macOS database client (AppKit and SwiftUI), macOS 13.0+, Swift 6 language mode for the app targets. TableProMobile/ is the iOS app. A path here is relative to apple/, except .claude/ and .github/ at the repository root.
- Native only. AppKit, SwiftUI and system frameworks, used as Apple documents them and the HIG describes. No cross-platform layer, no web view for native UI.
- Open plugin domain.
DatabaseTypeis a string-backed struct, so a plugin's type round-trips. Aswitchover an open type keeps adefault:; one over a closed enum stays exhaustive.
Every capability is core, a module or a plugin. The first rule that fits decides:
- Used weekly by app or backend developers or AI-first users, or only a row that runs nothing until clicked: core, no toggle.
- UI for one engine: core, shown only for drivers that support it.
- A database driver or a heavy native dependency: plugin, registry-shipped, signed by TablePro.
- Any other advanced tool needing a session, the grid, the editor or native UI: module, compiled in, toggled as a unit.
- A duplicate, or not worth maintaining: delete it, never park it in the registry.
- A new engine ships only as a registry plugin: no engine-specific code in
TablePro/; engine UI uses a PluginKit capability or plugin metadata. - A new advanced tool ships as a module, off by default.
- A module PR declares its id, default, off-state sink, residue test (a behavior test) and docs page.
- An off module leaves nothing behind: no menu item, key equivalent, context item, Settings section or Keyboard row; no launch work, observer, timer, listener or child process; no Keychain read or network call. A URL, AppleScript or MCP request for it gets an error naming where to enable it; only a click in TablePro enables it.
TablePro/: the app.Plugins/: drivers and import/export formats as.tablepluginbundles, plusTableProPluginKit. Bundled plugins are thecopy: { destination: plugins }targets inproject.yml; the app never offers a registry install or update over one.Packages/:TableProCore(both apps),TableProMacCore(macOS only, never in the iOS project),TableProOracle,TableProEditor,TableProGrammars. Edit PluginKit inPlugins/TableProPluginKit/only;TableProCoresymlinks it. Never passSWIFT_VERSION=toxcodebuild.Native/: Rust and Go bridges.Libs/: static libraries fromscripts/download-libs.sh, not in git.Packages/TableProFFI: the shared Rust core (core/) as the moduleTableProFFI.scripts/build-core.shbuilds its XCFramework and generates its Swift from the same library, neither in git; thenswift test --package-path Packages/TableProFFI. Nothing in the app links it yet (core/docs/decisions/0010-macos-on-the-core.md).- XcodeGen generates
TablePro.xcodeprojandTableProMobile/TableProMobile.xcodeproj; never hand-edit them. Signing overrides go inConfigs/Secrets.xcconfig. - Architecture lives in
.claude/rules/:plugin-system.md,connection-window.md,editor.md,theme.mdanddata-sync-storage.md.
From the repository root:
apple/scripts/download-libs.sh # first time, and after a libs update
apple/scripts/generate-project.sh [both|macos|ios] # after a project.yml or Configs/ edit, or a new, moved or deleted source file
.claude/skills/fix-issue/scripts/verify.sh build
.claude/skills/fix-issue/scripts/verify.sh test [<Suite>|<Suite>/<case>()|<Target>/<Suite>...] # none: the Unit plan
.claude/skills/fix-issue/scripts/verify.sh lint <file.swift>...verify.sh --helplists every step. When each runs:.claude/skills/fix-issue/references/platform-apple.md, Verify. Verdicts, test names and red CI checks:.claude/skills/fix-issue/references/verification-apple.md.- A raw
xcodebuildruns inapple/with-skipPackagePluginValidation, plus-testPlan UnitorUIfor macOS tests (CONTRIBUTING.md, Tests). - Never add
-parallel-testing-enabled,-test-iterationsor-retry-tests-on-failureto a macOS run, except to reproduce a flake: the plans own those. iOS test flags:.claude/rules/tests.md, Plans. - Never run
swiftlint --fix. Formatting SwiftLint leaves open:CONTRIBUTING.md, Code style. - Releases:
RELEASING.mdand thereleaseskill.
- AppKit lifecycle.
main.swiftstarts the app,MainMenuBuilder.installbuilds the menus, windows areNSWindowControllers. Never add a SwiftUIApp: it rewritesNSApp.mainMenu. - A refresh never clears what it refreshes. Fetch, then commit over the old value;
.loadingonly when nothing is loaded; keep good data on failure;prepareForReloadto reload,invalidateon disconnect. - A canceled connect keeps running.
Task.cancel()cannot interrupt a blocking C call: poll the connect or resume throughrunCancellableBlocking, then check theConnectionAttemptRegistrygeneration before adopting a driver. - Storage resolves through
AppStorageEnvironment.shared: stores, defaults suite and keychain. - An AppKit autosave name (split view, window frame, table) goes through
SplitViewAutosaveName.current(_:): the sandbox does not redirect the defaults domain AppKit writes it to. - No new test-only branch in production code: tests use injection or
TABLEPRO_UI_TEST_SANDBOX. - macOS files the iOS app compiles (listed in
TableProMobile/project.yml) give each top-level declaration explicit isolation, usuallynonisolated, since iOS defaults toMainActor. The iOS build is the check. - No package product in a macOS binary depends on the
TableProPluginKitpackage: a plugin would carry its own PluginKit types. - A source-text rule is a SwiftLint rule or a
scripts/cicheck, never a test reading source. - Never
ForEach($bindable.array) { $item in }on an@Observablearray that can shrink: index bindings crash. UseForEach(array)and a manual binding. - Log with
Logger(subsystem: "com.TablePro", category: ...), neverprint().
- Tests. A test in the target owning the code. Read
.claude/rules/tests.mdbefore creating a test file. A UI flow only for a new or changed end-to-end flow (.claude/rules/ui-tests.md). - Changelog. A user-visible change adds
changelog.d/<PR>.<type>.md; only a release PR editsCHANGELOG.md(.claude/rules/changelog.md). - Localization.
String(localized:)outside SwiftUI literals, never interpolated:String(format: String(localized: "Preview %@"), name). Technical terms stay unlocalized. A plugin or package string goes in the host app's catalog: runpython3 scripts/localization.py plugins --addfromapple/, plus--target iosfor a package the iOS app links. A command-line build never adds the app's own new strings: after the build, runpython3 scripts/localization.py extracted --add, plus--target iosfor the iOS app. Never hand-edit a.xcstrings. - Docs. A new shortcut, UI or settings change, or driver change gets a paired draft PR in TableProApp/docs naming this one; it merges after this one.
verify.sh docsruns its checks here first. - Lint each changed Swift file with
verify.sh lint.