0 Fork 0

Files

T

Kaede Akino 1c429a301b Adopt AgentKit 0.3.0 scratch_replace, scratch_copy and scratch_move

scratch_edit is now scratch_replace, and takes a regex mode and a per-entry
count — omit it to require exactly one match as before, 0 for every occurrence,
n for the first n. scratch_copy and scratch_move move a staged file or subtree
without its bytes passing through the transcript, which is what duplicating a
file before a risky change used to cost.

The app-side changes are the ones the rename and the two new tools reach:
ActionKind.copy in both the English and Chinese verb tables, the pull → copy →
replace → push recipe in the built-in config-edit skill, and the same wording in
the system prompt and the plan contract. The legacy tables are deliberately
untouched: legacyToolNames and legacyMetadata describe cards written before
presenter IDs were persisted, and scratch_edit belongs in both. AgentKit keeps
builtin.scratch_edit registered as an alias, so a transcript from before the
rename still draws its diff rather than falling back to generic fields — which
aCardWrittenAsScratchEditStillFindsItsProjection now pins.

AppLanguageTests no longer requires %lld results. That plural moved to AgentKit
with web_search's card, which is what db8796c removed from this catalog; the
test's list had been left behind and was failing.

AGENTS.md said AgentKit was referenced as a local SPM package. It is a versioned
remote dependency, so an uncommitted change in ../AgentKit is invisible to the
app and a change spanning both sides needs a tagged release in between. Said so,
because working the other way wastes a build cycle before the mistake shows.

Verified: AgentKit 0.3.0 builds and passes its 112 tests, and the six suites
this touches pass here. The five failures in the full run — ColorSystemTests,
two ChatComposerStateTests, FileURLDropTargetTests and WindowStateTests — all
reproduce on a clean worktree at HEAD and are unrelated.

2026-09-02 15:44:52 +08:00

4.6 KiB

Raw Blame History

Repository Guidelines

Project Structure & Module Organization

Termind/ contains the Swift 6 macOS app: models in Domain/, orchestration and ports in Application/, adapters in Infrastructure/, UI in Features/, and macOS integration in Platform/macOS/. TermindMCPBridge/ builds termind-mcp; tests live in TermindTests/. LandingPage/ is the Astro site. Utilities belong in Scripts/.

The agent runtime is AgentKit, a separate open-source package developed in the sibling ../AgentKit repository and consumed as a versioned remote SPM dependency on github.com/AkinoKaede/AgentKit, pinned in Package.resolved. It owns the loop, the approval gate, the provider adapters, the MCP client, and the built-in tools that know nothing about hosts. Termind owns the SSH/SFTP tools and registers them through TermindAgentTools. Never add SSH, SFTP, UI, or the name Termind to that package.

Xcode builds the pinned tag, not the sibling working tree, so an uncommitted change in ../AgentKit is invisible to the app. A change that spans both sides takes three steps: make and test the package change, tag and push a release from ../AgentKit, then bump minimumVersion in project.pbxproj and re-resolve so Package.resolved records the new revision. Both files belong in the same commit as the app-side change that needs them.

Architecture Records & Refactoring Memory

Treat Memory/ as durable engineering context. Read ARCHITECTURE.md before changing dependencies, navigation ownership, state lifetimes, persistence, agent execution, permissions, or secret handling. Update invalidated invariants and keep ArchitectureBoundaryTests aligned.

REFACTOR.md is the English-only redundancy backlog. Lifecycle: confirm an item with rg → record evidence, action, and estimated reduction → implement one independent, code-reducing change → run risk-appropriate tests → mark its status and verification. Append rather than rewrite, retain completed items, and preserve SwiftUI/AppKit boundaries.

Build, Test, and Development Commands

xcodebuild -project Termind.xcodeproj -scheme Termind -destination 'platform=macOS' -onlyUsePackageVersionsFromResolvedFile build builds the app, the MCP bridge, and AgentKit. Keep the flag: resolving without it silently bumps pinned dependencies.
cd ../AgentKit && swift build && swift test builds and tests the agent package on its own.
xcodebuild -project Termind.xcodeproj -scheme Termind -destination 'platform=macOS' test runs all Swift tests.
xcrun swift-format lint --strict --recursive Termind TermindTests TermindMCPBridge checks Swift formatting. AgentKit passes the same command over Sources Tests and must keep passing it.
cd LandingPage && npm ci && npm run dev installs locked web dependencies and starts Astro locally.
cd LandingPage && npm run build type-checks and emits the production site to LandingPage/dist/.

Coding Style & Naming Conventions

Follow .swift-format: four spaces and 120 columns. Use PascalCase types, camelCase members, behavior-based test names, and matching type/file names. Preserve ArchitectureBoundaryTests restrictions. The site uses strict TypeScript.

Testing Guidelines

Use Swift Testing (@Suite, @Test, #expect) in TermindTests/*Tests.swift. Add regression coverage and run all tests before submission. Web changes must pass npm run build; verify English and /zh/ routes visually.

Localization Guidelines

Put user-facing app text in Termind/Resources/Localizable.xcstrings and bundle metadata in InfoPlist.xcstrings. Text owned by the agent runtime lives in ../AgentKit/Localizations/Localizable.xcstrings; after editing it run ../AgentKit/Scripts/build-localizations.sh, because swift build copies resources verbatim instead of compiling string catalogs. New or changed English strings require finished zh-Hans translations in the same commit. Preserve placeholders and Chinese punctuation conventions. Before committing, run Scripts/check-zh-localization.sh (requires jq); it rejects invalid catalogs, missing or unfinished translations, and spacing errors. Run AppLanguageTests for localization behavior changes.

Commit & Pull Request Guidelines

Use short, imperative subjects such as Fix Assistant sidebar navigation round-trip; reserve Bump to X.Y.Z for releases. Keep commits focused. Always include Scripts/check-zh-localization.sh in the commit pipeline, even without intentional localization changes. PRs should describe the outcome, affected layers, verification, and issues. Include bilingual screenshots for UI changes when applicable. Never commit secrets, .env files, build products, or user-specific Xcode data.

4.6 KiB Raw Blame History