@coreframe/scripts 0.0.0 → 0.1.0

package/bin/coreframe.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process"
+import { existsSync } from "node:fs"
+import { dirname, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..")
+const distBin = resolve(packageRoot, "dist/coreframe.js")
+
+if (!existsSync(distBin)) {
+  const build = spawnSync("pnpm", ["--dir", packageRoot, "build"], {
+    shell: process.platform === "win32",
+    stdio: "inherit",
+  })
+
+  if (build.error) {
+    console.error(build.error.message)
+    process.exit(1)
+  }
+
+  if (build.status !== 0) {
+    process.exit(build.status ?? 1)
+  }
+}
+
+const cli = spawnSync(process.execPath, [distBin, ...process.argv.slice(2)], {
+  stdio: "inherit",
+})
+
+if (cli.error) {
+  console.error(cli.error.message)
+  process.exit(1)
+}
+
+process.exit(cli.status ?? 1)

package/config.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from "vitest"
+
+import { defineConfig } from "./config.ts"
+
+describe("defineConfig", () => {
+  it("returns a typed Coreframe config object", () => {
+    const config = defineConfig({
+      deploy: {
+        smokeChecks: [{ name: "home", path: "/" }],
+      },
+    })
+
+    expect(config.deploy?.smokeChecks).toEqual([{ name: "home", path: "/" }])
+  })
+})

package/config.ts

@@ -0,0 +1,9 @@
+import type { DeployConfig } from "./deploy/config.ts"
+
+export type CoreframeConfig = {
+  deploy?: DeployConfig
+}
+
+export function defineConfig(config: CoreframeConfig) {
+  return config
+}

package/coreframe.ts

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+import {
+  array,
+  binary,
+  command,
+  flag,
+  multioption,
+  oneOf,
+  option,
+  optional,
+  positional,
+  rest,
+  run,
+  string,
+  subcommands,
+} from "cmd-ts"
+
+import { runDrizzleKitCommand } from "./db/drizzle-kit.ts"
+import { ensureLocalDb } from "./db/ensure.ts"
+import { migrateHeldMigrations } from "./db/migrate-held.ts"
+import { migrateLocalDb } from "./db/migrate.ts"
+import { resetLocalDb } from "./db/reset.ts"
+import { seedLocalDb } from "./db/seed.ts"
+import { setupLocalDb } from "./db/setup.ts"
+import { deployProject } from "./deploy.ts"
+import { checkDeployMigrations } from "./deploy/check-migrations.ts"
+import { tauriReleasePlatforms } from "./deploy/config.ts"
+import { runDevServer } from "./dev.ts"
+import { typecheckProject } from "./typecheck.ts"
+import { checkUpgradeSkillCurrent } from "./upgrade/check-skill-current.ts"
+import { ensureTemplateRemote } from "./upgrade/ensure-template-remote.ts"
+import { fastForwardTemplateFiles } from "./upgrade/fast-forward-template-files.ts"
+
+const heldMigrationConfirmation = "run-held-migrations"
+const devPlatforms = ["web", "desktop", "ios", "android"] as const
+
+export const coreframeCli = subcommands({
+  name: "coreframe",
+  cmds: {
+    deploy: command({
+      name: "deploy",
+      args: {
+        runMigrations: flag({
+          long: "run-migrations",
+          description: "Run pending deploy-safe database migrations before deploying.",
+          defaultValue: () => false,
+        }),
+        skipMigrations: flag({
+          long: "skip-migrations",
+          description: "Deploy without running pending deploy-safe database migrations.",
+          defaultValue: () => false,
+        }),
+        skipPostDeployChecks: flag({
+          long: "skip-post-deploy-checks",
+          description: "Skip post-deploy checks after Cloudflare deployment.",
+          defaultValue: () => false,
+        }),
+        tauriLocalPlatforms: multioption({
+          long: "tauri-local-platform",
+          type: array(oneOf(tauriReleasePlatforms)),
+          description: "Build one Tauri release platform locally. Repeat for multiple platforms.",
+          defaultValue: () => [],
+        }),
+        tauriWorkflowName: option({
+          long: "tauri-workflow-name",
+          type: optional(string),
+          description: "GitHub Actions workflow file or name for remote Tauri release builds.",
+        }),
+        tauriWorkflowPlatforms: multioption({
+          long: "tauri-workflow-platform",
+          type: array(oneOf(tauriReleasePlatforms)),
+          description:
+            "Build one Tauri release platform with GitHub Actions. Repeat for multiple platforms.",
+          defaultValue: () => [],
+        }),
+        tauriWorkflowRef: option({
+          long: "tauri-workflow-ref",
+          type: optional(string),
+          description: "Git ref used when dispatching remote Tauri release builds.",
+        }),
+        yes: flag({
+          long: "yes",
+          short: "y",
+          description: "Approve noninteractive deploy prompts.",
+          defaultValue: () => false,
+        }),
+      },
+      handler: ({
+        runMigrations,
+        skipMigrations,
+        skipPostDeployChecks,
+        tauriLocalPlatforms,
+        tauriWorkflowName,
+        tauriWorkflowPlatforms,
+        tauriWorkflowRef,
+        yes,
+      }) =>
+        deployProject([
+          ...(runMigrations ? ["--run-migrations"] : []),
+          ...(skipMigrations ? ["--skip-migrations"] : []),
+          ...(skipPostDeployChecks ? ["--skip-post-deploy-checks"] : []),
+          ...tauriLocalPlatforms.flatMap((platform) => ["--tauri-local-platform", platform]),
+          ...(tauriWorkflowName ? ["--tauri-workflow-name", tauriWorkflowName] : []),
+          ...tauriWorkflowPlatforms.flatMap((platform) => ["--tauri-workflow-platform", platform]),
+          ...(tauriWorkflowRef ? ["--tauri-workflow-ref", tauriWorkflowRef] : []),
+          ...(yes ? ["--yes"] : []),
+        ]),
+    }),
+    typecheck: command({
+      name: "typecheck",
+      args: {},
+      handler: typecheckProject,
+    }),
+    dev: command({
+      name: "dev",
+      args: {
+        platform: positional({
+          type: optional(oneOf(devPlatforms)),
+          displayName: "platform",
+          description: "Development target platform. Defaults to web.",
+        }),
+      },
+      handler: ({ platform }) => runDevServer({ platform: platform ?? "web" }),
+    }),
+    upgrade: subcommands({
+      name: "upgrade",
+      cmds: {
+        "ensure-template-remote": command({
+          name: "ensure-template-remote",
+          args: {
+            remote: option({
+              long: "remote",
+              type: string,
+              defaultValue: () => "template",
+              description: "Remote name to ensure.",
+            }),
+            noFetch: flag({
+              long: "no-fetch",
+              description: "Do not fetch the remote after ensuring it exists.",
+              defaultValue: () => false,
+            }),
+          },
+          handler: ({ noFetch, remote }) => ensureTemplateRemote({ fetch: !noFetch, remote }),
+        }),
+        "check-skill-current": command({
+          name: "check-skill-current",
+          args: {
+            target: option({
+              long: "target",
+              type: string,
+              description: "Target Coreframe template git ref.",
+            }),
+            apply: flag({
+              long: "apply",
+              description:
+                "Replace the local upgrade skill with the target version when it differs.",
+              defaultValue: () => false,
+            }),
+          },
+          handler: ({ apply, target }) => {
+            process.exitCode = checkUpgradeSkillCurrent({ apply, target })
+          },
+        }),
+        "fast-forward-template-files": command({
+          name: "fast-forward-template-files",
+          args: {
+            target: option({
+              long: "target",
+              type: string,
+              description: "Target Coreframe template git ref.",
+            }),
+            base: option({
+              long: "base",
+              type: optional(string),
+              description:
+                "Previous Coreframe template git ref. Defaults to package.json engines.coreframe.",
+            }),
+            apply: flag({
+              long: "apply",
+              description: "Write clean fast-forwards to the worktree.",
+              defaultValue: () => false,
+            }),
+          },
+          handler: ({ apply, base, target }) => fastForwardTemplateFiles({ apply, base, target }),
+        }),
+      },
+    }),
+    db: subcommands({
+      name: "db",
+      cmds: {
+        ensure: command({
+          name: "ensure",
+          args: {},
+          handler: ensureLocalDb,
+        }),
+        generate: command({
+          name: "generate",
+          args: {
+            args: rest({
+              displayName: "drizzle-kit args",
+              description: "Additional arguments passed to drizzle-kit generate.",
+            }),
+          },
+          handler: ({ args }) => runDrizzleKitCommand("generate", args),
+        }),
+        migrate: command({
+          name: "migrate",
+          args: {
+            args: rest({
+              displayName: "drizzle-kit args",
+              description: "Additional arguments passed to drizzle-kit migrate.",
+            }),
+          },
+          handler: ({ args }) => runDrizzleKitCommand("migrate", args),
+        }),
+        "migrate-held": command({
+          name: "migrate-held",
+          args: {
+            confirm: option({
+              long: "confirm",
+              type: optional(oneOf([heldMigrationConfirmation] as const)),
+              description: "Required confirmation value for held migrations.",
+            }),
+          },
+          handler: ({ confirm }) =>
+            migrateHeldMigrations({
+              argv: confirm ? [`--confirm=${confirm}`] : [],
+            }),
+        }),
+        "migrate-local": command({
+          name: "migrate-local",
+          args: {},
+          handler: migrateLocalDb,
+        }),
+        "migrations-check": command({
+          name: "migrations-check",
+          args: {},
+          handler: checkDeployMigrations,
+        }),
+        reset: command({
+          name: "reset",
+          args: {},
+          handler: resetLocalDb,
+        }),
+        seed: command({
+          name: "seed",
+          args: {},
+          handler: () => seedLocalDb(),
+        }),
+        setup: command({
+          name: "setup",
+          args: {},
+          handler: () => setupLocalDb(),
+        }),
+        studio: command({
+          name: "studio",
+          args: {
+            args: rest({
+              displayName: "drizzle-kit args",
+              description: "Additional arguments passed to drizzle-kit studio.",
+            }),
+          },
+          handler: ({ args }) => runDrizzleKitCommand("studio", args),
+        }),
+      },
+    }),
+  },
+})
+
+if (import.meta.main) {
+  run(binary(coreframeCli), process.argv)
+}

package/db/client.ts

@@ -0,0 +1,72 @@
+import { sql, type SQL } from "drizzle-orm"
+
+export type CoreframeDatabaseDialect = "postgres" | "sqlite"
+
+export type CoreframeQueryResult<Row extends Record<string, unknown> = Record<string, unknown>> = {
+  rowCount?: number | null
+  rows: Row[]
+}
+
+export type CoreframeDatabaseClient = {
+  dialect: CoreframeDatabaseDialect
+  execute<Row extends Record<string, unknown> = Record<string, unknown>>(
+    statement: string,
+  ): Promise<CoreframeQueryResult<Row>>
+  transaction?<Result>(run: (database: CoreframeDatabaseClient) => Promise<Result>): Promise<Result>
+  close?(): Promise<void>
+}
+
+export type CoreframeDrizzleExecutor = {
+  execute<Result = unknown>(query: SQL): Result | Promise<Result>
+}
+
+export type CreateDrizzleDatabaseClientOptions = {
+  close?(): Promise<void>
+  database: CoreframeDrizzleExecutor
+  dialect: CoreframeDatabaseDialect
+}
+
+export function createDrizzleDatabaseClient({
+  close,
+  database,
+  dialect,
+}: CreateDrizzleDatabaseClientOptions): CoreframeDatabaseClient {
+  return {
+    dialect,
+    async execute<Row extends Record<string, unknown> = Record<string, unknown>>(
+      statement: string,
+    ) {
+      return normalizeQueryResult<Row>(await database.execute(sql.raw(statement)))
+    },
+    close,
+  }
+}
+
+export function normalizeQueryResult<Row extends Record<string, unknown> = Record<string, unknown>>(
+  result: unknown,
+): CoreframeQueryResult<Row> {
+  if (Array.isArray(result)) {
+    return {
+      rows: result as Row[],
+    }
+  }
+
+  if (isQueryResultLike<Row>(result)) {
+    return {
+      rowCount: typeof result.rowCount === "number" ? result.rowCount : null,
+      rows: result.rows,
+    }
+  }
+
+  return {
+    rows: [],
+  }
+}
+
+function isQueryResultLike<Row extends Record<string, unknown>>(
+  result: unknown,
+): result is { rowCount?: unknown; rows: Row[] } {
+  return (
+    typeof result === "object" && result !== null && "rows" in result && Array.isArray(result.rows)
+  )
+}

package/db/config.ts

@@ -0,0 +1,41 @@
+export const LOCAL_DB_DIR = process.env.PGLITE_DATA_DIR ?? ".pglite"
+export const MIGRATIONS_FOLDER = "drizzle"
+export const HELD_MIGRATIONS_FOLDER = "drizzle-hold"
+export const NOW = new Date("2026-01-15T12:00:00.000Z")
+
+export const SEED_IDS = {
+  adminUser: "00000000-0000-4000-8000-000000000001",
+  viewerUser: "00000000-0000-4000-8000-000000000002",
+  inactiveUser: "00000000-0000-4000-8000-000000000003",
+  unicodeUser: "00000000-0000-4000-8000-000000000004",
+  longNameUser: "00000000-0000-4000-8000-000000000005",
+} as const
+
+export const SEED_EMAILS = {
+  adminUser: "admin@example.com",
+  viewerUser: "viewer@example.com",
+  inactiveUser: "inactive@example.com",
+  unicodeUser: "unicode@example.com",
+  longNameUser: "long-name@example.com",
+} as const
+
+export type SeedProfile = "small" | "large" | "demo" | "test"
+
+export function getSeedProfile(argv = process.argv.slice(2)): SeedProfile {
+  if (argv.includes("--large")) {
+    return "large"
+  }
+
+  const profileArg = argv.find((arg) => arg.startsWith("--profile="))
+  const profile = profileArg?.slice("--profile=".length) ?? "small"
+
+  if (profile === "small" || profile === "large" || profile === "demo" || profile === "test") {
+    return profile
+  }
+
+  throw new Error(`Unknown seed profile "${profile}". Expected small, large, demo, or test.`)
+}
+
+export function generatedUserId(index: number) {
+  return `00000000-0000-4000-8000-${String(1000 + index).padStart(12, "0")}`
+}

package/db/drizzle-kit.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest"
+
+import { runDrizzleKitCommand } from "./drizzle-kit.ts"
+
+describe("runDrizzleKitCommand", () => {
+  it("forwards drizzle-kit commands through the project binary", async () => {
+    const calls: unknown[] = []
+
+    await runDrizzleKitCommand("generate", ["--config", "drizzle.config.ts"], async (...args) => {
+      calls.push(args)
+      return { stdout: "", stderr: "", exitCode: 0 }
+    })
+
+    expect(calls).toEqual([
+      [
+        process.platform === "win32" ? "drizzle-kit.cmd" : "drizzle-kit",
+        ["generate", "--config", "drizzle.config.ts"],
+        {
+          env: expect.objectContaining({
+            PATH: expect.stringContaining("node_modules/.bin"),
+          }),
+          stdio: "inherit",
+        },
+      ],
+    ])
+  })
+})

package/db/drizzle-kit.ts

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import path from "node:path"
+import process from "node:process"
+
+import nanoSpawn from "nano-spawn"
+
+type Spawn = (
+  file: string,
+  args: readonly string[],
+  options: { env: NodeJS.ProcessEnv; stdio: "inherit" },
+) => PromiseLike<unknown>
+type DrizzleKitCommand = "generate" | "migrate" | "studio"
+
+const nodeModulesBinPath = path.resolve("node_modules", ".bin")
+const drizzleKitCommand = process.platform === "win32" ? "drizzle-kit.cmd" : "drizzle-kit"
+const pathEnvValue = process.env.PATH ?? process.env.Path ?? ""
+
+export async function runDrizzleKitCommand(
+  command: DrizzleKitCommand,
+  args: string[] = [],
+  spawn: Spawn = nanoSpawn,
+) {
+  await spawn(drizzleKitCommand, [command, ...args], {
+    env: {
+      ...process.env,
+      PATH: nodeModulesBinPath + path.delimiter + pathEnvValue,
+    },
+    stdio: "inherit",
+  })
+}
+
+if (import.meta.main) {
+  runDrizzleKitCommand(process.argv[2] as DrizzleKitCommand, process.argv.slice(3)).catch(
+    (error) => {
+      console.error(error)
+      process.exit(1)
+    },
+  )
+}

package/db/ensure.ts

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import { eq } from "drizzle-orm"
+
+import { importProjectModule } from "../project.ts"
+import { LOCAL_DB_DIR, SEED_EMAILS, SEED_IDS } from "./config.ts"
+import { setupLocalDb } from "./setup.ts"
+
+type LocalDbModule = {
+  createLocalDb(dataDir?: string): {
+    $client: {
+      close(): Promise<void>
+    }
+    select(selection: Record<string, unknown>): {
+      from(table: unknown): {
+        where(condition: unknown): {
+          limit(count: number): Promise<Array<{ id: string }>>
+        }
+      }
+    }
+  }
+}
+
+type SchemaModule = {
+  users: {
+    email: unknown
+    id: unknown
+  }
+}
+
+async function hasSeededAdminUser() {
+  const [{ createLocalDb }, { users }] = await Promise.all([
+    importProjectModule<LocalDbModule>("src/db/local.ts"),
+    importProjectModule<SchemaModule>("src/db/schema.ts"),
+  ])
+  const db = createLocalDb(LOCAL_DB_DIR)
+
+  try {
+    const [adminUser] = await db
+      .select({ id: users.id })
+      .from(users)
+      .where(eq(users.email as never, SEED_EMAILS.adminUser))
+      .limit(1)
+
+    return adminUser?.id === SEED_IDS.adminUser
+  } catch {
+    return false
+  } finally {
+    await db.$client.close()
+  }
+}
+
+export async function ensureLocalDb() {
+  if (await hasSeededAdminUser()) {
+    console.log("Local database already set up")
+    return
+  }
+
+  console.log("Local database is missing or unseeded; running setup")
+  await setupLocalDb()
+}
+
+if (import.meta.main) {
+  ensureLocalDb().catch((error) => {
+    console.error(error)
+    process.exit(1)
+  })
+}

package/db/migrate-held.test.ts

@@ -0,0 +1,81 @@
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+import { describe, expect, it } from "vitest"
+
+import type { CoreframeDatabaseClient, CoreframeDatabaseDialect } from "./client.ts"
+import {
+  heldMigrationInsertQuery,
+  heldMigrationSelectQuery,
+  migrateHeldMigrations,
+} from "./migrate-held.ts"
+
+describe("held migration journal queries", () => {
+  it("uses dialect-specific held migration journal tables", () => {
+    expect(heldMigrationSelectQuery("postgres", "20260703120000_first")).toBe(
+      "select sha256 from drizzle.__held_migrations where id = '20260703120000_first'",
+    )
+    expect(heldMigrationSelectQuery("sqlite", "20260703120000_first")).toBe(
+      "select sha256 from __held_migrations where id = '20260703120000_first'",
+    )
+    expect(heldMigrationInsertQuery("sqlite", "migration's id", "abc123")).toBe(
+      "insert into __held_migrations (id, sha256) values ('migration''s id', 'abc123')",
+    )
+  })
+})
+
+describe("migrateHeldMigrations", () => {
+  it("runs held migrations through a SQLite database adapter", async () => {
+    const root = await mkdtemp(join(tmpdir(), "coreframe-held-migrations-"))
+    await mkdir(join(root, "drizzle-hold"), { recursive: true })
+    await writeFile(
+      join(root, "drizzle-hold", "20260703120000_backfill.sql"),
+      `-- Held migration: test backfill
+-- Safe after: the test says so
+-- Verification: inspect the rows
+insert into users (id) values ('user-1');`,
+    )
+    const database = createRecordingDatabase("sqlite")
+    const cwd = process.cwd()
+
+    try {
+      process.chdir(root)
+      await migrateHeldMigrations({
+        argv: ["--confirm=run-held-migrations"],
+        database,
+      })
+    } finally {
+      process.chdir(cwd)
+    }
+
+    expect(database.statements).toEqual([
+      expect.stringContaining("create table if not exists __held_migrations"),
+      "select sha256 from __held_migrations where id = '20260703120000_backfill'",
+      "begin",
+      expect.stringContaining("insert into users"),
+      expect.stringMatching(
+        /^insert into __held_migrations \(id, sha256\) values \('20260703120000_backfill', '[a-f0-9]{64}'\)$/,
+      ),
+      "commit",
+    ])
+  })
+})
+
+function createRecordingDatabase(
+  dialect: CoreframeDatabaseDialect,
+): CoreframeDatabaseClient & { statements: string[] } {
+  const statements: string[] = []
+
+  return {
+    dialect,
+    statements,
+    async execute(statement) {
+      statements.push(statement)
+
+      return {
+        rows: [],
+      }
+    },
+  }
+}