aktual: Skill for Claude Code

Apply a new upstream Actual database migration to Aktual's database layer.

Do NOT ask clarifying questions - just execute.

Arguments

• $ARGUMENTS is the migration filename, e.g. 1778510362740_add_cleanup_groups_and_def.sql
• If omitted, read it from .github/upstream-migration-tracker/last-known-migration.txt

Step-by-Step Process

1. Read the upstream migration SQL

The migration lives at:

/home/jon/dev/actual/packages/loot-core/migrations/<filename>

Parse all DDL statements: ALTER TABLE ... ADD COLUMN, CREATE TABLE, CREATE INDEX, etc. Strip BEGIN TRANSACTION / COMMIT wrappers.

2. Categorise the changes

For each statement:

Statement	Actions needed
ALTER TABLE t ADD COLUMN c	Update .sq file + possible adapter
CREATE TABLE t	New .sq file + adapter + BuildDatabase.kt + possible ID type. Emit as CREATE TABLE IF NOT EXISTS in the migration (never bare CREATE TABLE)
CREATE INDEX	Add to the relevant .sq file (no adapter)

Also check if new column types need new model classes (sealed interfaces, value class IDs).

3. Update SQLDelight schema files

All .sq files: aktual-budget/data/db/src/commonMain/sqldelight/aktual/budget/db/

New column on an existing table:

• Add the column to the CREATE TABLE statement in the matching .sq file
• If it stores typed JSON, declare it as TEXT AS MyType DEFAULT NULL with an import at the top
• If it stores a typed ID, declare it as TEXT AS FooId DEFAULT NULL

New table:

• Create Foo.sq (PascalCase, matching the table name)
• Mirror upstream columns with SQLDelight typed aliases
• Use tombstone INTEGER AS Boolean DEFAULT 0 for the tombstone column
• Add at minimum: insert: INSERT OR REPLACE INTO foo(id, ...) VALUES (?, ...); and getById: SELECT * FROM foo WHERE id = ?;

4. Add model types if needed

Types live in aktual-budget/model/src/commonMain/kotlin/aktual/budget/model/.

New table ID - add to Ids.kt, following the existing value class pattern:

@JvmInline
@Serializable
value class FooId(val value: String) : Comparable<FooId> {
  override fun toString(): String = value
  override fun compareTo(other: FooId) = value.compareTo(other.value)
}