@usehyper/cli 0.1.0

package/src/commands/security.ts

@@ -0,0 +1,233 @@
+/**
+ * `hyper security --check` — static analysis of the booted app's
+ * security posture.
+ *
+ * The command loads the app, introspects routes + plugins + config, and
+ * prints a pass/warn/fail report. Exit code is 0 when no fails are
+ * found, 1 otherwise. `--json` emits a machine-readable report for CI.
+ *
+ * Checks:
+ *   [sec-headers]       applyDefaultHeaders is enabled (security.headers)
+ *   [sec-body-limit]    bodyLimitBytes is within the sane range (>=8KB, <=50MB)
+ *   [sec-proto]         JSON prototype-pollution guard is enabled
+ *   [sec-method-override] rejectMethodOverride is enabled
+ *   [sec-timeout]       requestTimeoutMs is a positive finite number
+ *   [sec-jwt-secret]    Any @hyper/auth-jwt secret env is >=32 bytes at boot
+ *   [sec-session-secret] Any @hyper/session secret env is >=32 bytes at boot
+ *   [sec-cors-wildcard] corsPlugin(origin:"*") is opt-in only
+ *   [sec-auth-rate]     Routes with meta.authEndpoint have an auto-rate-limit plugin
+ *   [sec-route-timeout] No route declares timeoutMs > global request budget
+ */
+
+import type { HyperApp, Route } from "@hyper/core"
+import { type ParsedArgs, isJson } from "../args.ts"
+import { resolveEntry } from "../entry.ts"
+import { loadApp } from "../load-app.ts"
+
+type Level = "pass" | "warn" | "fail"
+interface Finding {
+  readonly id: string
+  readonly level: Level
+  readonly message: string
+  readonly why?: string
+  readonly fix?: string
+}
+
+export async function runSecurity(args: ParsedArgs): Promise<number> {
+  // --check is a *subcommand flag*, so tolerate both shapes:
+  //   hyper security --check [entry]
+  //   hyper security check [entry]
+  // Our arg parser treats `--check entry.ts` as `flags.check = "entry.ts"`,
+  // so a string value is equivalent to `--check true` + positional entry.
+  let check = args.flags.check === true || args.positional[0] === "check"
+  const positionals = [...args.positional.filter((p) => p !== "check")]
+  if (typeof args.flags.check === "string") {
+    check = true
+    positionals.push(args.flags.check)
+  }
+  if (!check) {
+    console.error("usage: hyper security --check [entry]")
+    return 2
+  }
+
+  const entry = await resolveEntry(positionals)
+  if (!entry) {
+    console.error("error: no entry file found (tried src/app.ts, app.ts, index.ts)")
+    return 2
+  }
+  const app = await loadApp(entry)
+  if (!app) {
+    console.error(`error: no default/named 'app' export in ${entry}`)
+    return 2
+  }
+
+  const findings = await audit(app)
+  const failed = findings.filter((f) => f.level === "fail")
+  const warned = findings.filter((f) => f.level === "warn")
+
+  if (isJson(args.flags)) {
+    console.log(JSON.stringify({ findings, ok: failed.length === 0 }, null, 2))
+  } else {
+    for (const f of findings) {
+      const tag = f.level === "pass" ? "PASS" : f.level === "warn" ? "WARN" : "FAIL"
+      const prefix = `[${tag}] ${f.id}`.padEnd(30)
+      console.log(`${prefix} ${f.message}`)
+      if (f.why) console.log(`${" ".repeat(30)}  why: ${f.why}`)
+      if (f.fix) console.log(`${" ".repeat(30)}  fix: ${f.fix}`)
+    }
+    console.log(
+      `\nsummary: ${findings.filter((f) => f.level === "pass").length} pass, ${warned.length} warn, ${failed.length} fail`,
+    )
+  }
+  return failed.length === 0 ? 0 : 1
+}
+
+export async function auditApp(app: HyperApp): Promise<readonly Finding[]> {
+  return audit(app)
+}
+
+export type { Finding, Level }
+
+async function audit(app: HyperApp): Promise<readonly Finding[]> {
+  const out: Finding[] = []
+  const cfg = app.__config
+  const security = cfg.security ?? {}
+
+  push(out, "sec-headers", security.headers !== false, "Default security headers enabled", {
+    fail: "Default security headers are off. Re-enable unless you're behind a proxy that already applies them.",
+    fix: "Set `security: { headers: true }` (or omit — it's the default).",
+  })
+
+  const bodyLimit = security.bodyLimitBytes ?? 1_048_576
+  if (bodyLimit < 8_192) {
+    out.push({
+      id: "sec-body-limit",
+      level: "warn",
+      message: `Body limit is only ${bodyLimit} bytes — genuine JSON payloads may 413.`,
+      fix: "Raise to at least 8KB or rely on the 1MB default.",
+    })
+  } else if (bodyLimit > 50 * 1_048_576) {
+    out.push({
+      id: "sec-body-limit",
+      level: "warn",
+      message: `Body limit is ${bodyLimit} bytes (>50MB). Large bodies invite memory DoS.`,
+      fix: "Keep to ≤50MB unless you deliberately accept large uploads. Prefer streaming.",
+    })
+  } else {
+    out.push({ id: "sec-body-limit", level: "pass", message: `Body limit is ${bodyLimit} bytes` })
+  }
+
+  push(out, "sec-proto", security.rejectProtoKeys !== false, "Prototype-pollution guard enabled", {
+    fail: "JSON bodies may contain `__proto__` / `constructor` / `prototype` keys.",
+    fix: "Leave `security.rejectProtoKeys` on (default).",
+  })
+  push(
+    out,
+    "sec-method-override",
+    security.rejectMethodOverride !== false,
+    "Method-override guard enabled",
+    {
+      fail: "Headers like X-HTTP-Method-Override can rewrite the verb — CSRF/verb-smuggling risk.",
+      fix: "Leave `security.rejectMethodOverride` on (default).",
+    },
+  )
+  const timeout = security.requestTimeoutMs ?? 30_000
+  if (!(Number.isFinite(timeout) && timeout > 0)) {
+    out.push({
+      id: "sec-timeout",
+      level: "fail",
+      message: `requestTimeoutMs is ${timeout}`,
+      why: "Handlers without a deadline can hog workers forever.",
+      fix: "Set `security.requestTimeoutMs` to a finite positive number (default 30_000).",
+    })
+  } else {
+    out.push({ id: "sec-timeout", level: "pass", message: `Hard timeout: ${timeout}ms` })
+  }
+
+  // Plugin-based checks
+  const plugins = cfg.plugins ?? []
+
+  // CSRF / session coverage: we walk middleware tags on every route.
+  // session() is a middleware tagged "@hyper/session"; csrfGuard() is
+  // tagged "@hyper/session:csrf". A mutating route with session but
+  // without csrf is suspicious — we raise a warn, not a fail, because
+  // bearer-token APIs legitimately use session without CSRF.
+  const MUTATING = new Set(["POST", "PUT", "PATCH", "DELETE"])
+  const sessionNoCsrf: string[] = []
+  for (const r of app.routeList) {
+    const tags = r.middlewareTags ?? []
+    const hasSession = tags.includes("@hyper/session")
+    const hasCsrfTag = tags.includes("@hyper/session:csrf")
+    if (MUTATING.has(r.method) && hasSession && !hasCsrfTag) {
+      sessionNoCsrf.push(`${r.method} ${r.path}`)
+    }
+  }
+  if (sessionNoCsrf.length > 0) {
+    out.push({
+      id: "sec-csrf",
+      level: "warn",
+      message: `${sessionNoCsrf.length} mutating route(s) use session() without csrfGuard().`,
+      why: "Cookie-authenticated mutating endpoints without CSRF double-submit are vulnerable to cross-site request forgery.",
+      fix: `Chain csrfGuard() after session() on: ${sessionNoCsrf.slice(0, 3).join(", ")}${sessionNoCsrf.length > 3 ? ", ..." : ""}. Ignore if this endpoint uses bearer auth.`,
+    })
+  } else {
+    // Only emit a pass marker when session is actually used somewhere.
+    const anySession = app.routeList.some((r) =>
+      (r.middlewareTags ?? []).includes("@hyper/session"),
+    )
+    if (anySession) {
+      out.push({
+        id: "sec-csrf",
+        level: "pass",
+        message: "Every mutating session-backed route has csrfGuard().",
+      })
+    }
+  }
+
+  const hasAuthRl = plugins.some((p) => p.name === "@hyper/rate-limit:auth")
+  const authRoutes = app.routeList.filter((r) => r.meta.authEndpoint === true)
+  if (authRoutes.length > 0 && !hasAuthRl) {
+    out.push({
+      id: "sec-auth-rate",
+      level: "fail",
+      message: `${authRoutes.length} route(s) marked authEndpoint but no auto-rate-limit plugin installed.`,
+      why: "Auth endpoints unthrottled are trivially credential-stuffable.",
+      fix: "Add `authRateLimitPlugin()` from @hyper/rate-limit (limit: 10, window: '1m' is a good default).",
+    })
+  } else if (authRoutes.length > 0) {
+    out.push({
+      id: "sec-auth-rate",
+      level: "pass",
+      message: `authRateLimitPlugin is guarding ${authRoutes.length} auth route(s)`,
+    })
+  }
+
+  const longTimeouts = app.routeList.filter(
+    (r: Route) => typeof r.meta.timeoutMs === "number" && (r.meta.timeoutMs as number) > timeout,
+  )
+  if (longTimeouts.length > 0) {
+    out.push({
+      id: "sec-route-timeout",
+      level: "warn",
+      message: `${longTimeouts.length} route(s) have per-route timeoutMs > global requestTimeoutMs`,
+      why: "Per-route timeouts longer than the global budget risk starving workers.",
+      fix: "Lower the per-route timeout or raise the global budget.",
+    })
+  }
+
+  return out
+}
+
+function push(
+  out: Finding[],
+  id: string,
+  passed: boolean,
+  message: string,
+  onFail: { fail: string; fix: string },
+): void {
+  out.push(
+    passed
+      ? { id, level: "pass", message }
+      : { id, level: "fail", message, why: onFail.fail, fix: onFail.fix },
+  )
+}

package/src/commands/test.ts

@@ -0,0 +1,191 @@
+/**
+ * `hyper test` — runs `.example()` contracts + `bun:test` + optional
+ * typecheck + fuzz harness.
+ *
+ * Order:
+ *   1. example contracts (fast, surface DX regressions first)
+ *   2. bun:test (unit + integration)
+ *   3. optional --types (tsgo) and --fuzz (per-route attack corpus)
+ *
+ * Non-zero exit if any stage fails. `--reporter=junit` writes a JUnit
+ * XML file to `./test-report.xml` for CI.
+ */
+
+import { spawn } from "node:child_process"
+import { writeFile } from "node:fs/promises"
+import { resolve } from "node:path"
+import { type ParsedArgs, isJson } from "../args.ts"
+import { readConfig } from "../config/index.ts"
+import { resolveEntry } from "../entry.ts"
+import { loadApp, loadComponentModule } from "../load-app.ts"
+
+export async function runTest(args: ParsedArgs): Promise<number> {
+  const entry = await resolveEntry(args.positional)
+  if (!entry) {
+    console.error("error: no entry file found")
+    return 2
+  }
+  const reporter = typeof args.flags.reporter === "string" ? args.flags.reporter : undefined
+  const runFuzz = args.flags.fuzz === true
+  const runTypes = args.flags.types === true
+  const junitPath = typeof args.flags.junit === "string" ? args.flags.junit : "./test-report.xml"
+
+  const testResults: Array<{
+    suite: string
+    name: string
+    ok: boolean
+    error?: string
+    time: number
+  }> = []
+
+  const app = await loadApp(entry)
+  if (app) {
+    // `runExamples` lives in core. Try the user's installed copy first, fall
+    // back to the workspace package for monorepo dev.
+    const core = await loadComponentModule<typeof import("@hyper/core")>("core")
+    if (!core) {
+      console.error("error: core not loadable. Run `hyper add core` if you haven't already.")
+      return 2
+    }
+    const t0 = performance.now()
+    const results = await core.runExamples(app)
+    const failing = results.filter((r) => !r.ok)
+    for (const r of results) {
+      testResults.push({
+        suite: "examples",
+        name: `${r.method} ${r.route} — ${r.example}`,
+        ok: r.ok,
+        ...(r.error !== undefined && { error: r.error }),
+        time: 0,
+      })
+    }
+    if (isJson(args.flags)) {
+      console.log(JSON.stringify({ examples: results }))
+    } else if (results.length > 0) {
+      console.log(
+        `examples: ${results.length - failing.length}/${results.length} passing  (${(performance.now() - t0).toFixed(1)}ms)`,
+      )
+      for (const f of failing) {
+        console.log(`  FAIL  ${f.method} ${f.route}  "${f.example}"  status=${f.status}`)
+        if (f.error) console.log(`        ${f.error}`)
+      }
+    }
+    if (failing.length > 0) return 1
+
+    if (runFuzz) {
+      // testing/fuzz lives at <baseDir>/testing/fuzz.ts after `hyper add testing`.
+      const config = await readConfig()
+      const local = resolve(process.cwd(), config.baseDir, "testing/fuzz.ts")
+      let fuzz: typeof import("@hyper/testing/fuzz") | null = null
+      for (const spec of [local, "@hyper/testing/fuzz", "@hyper/testing/fuzz"]) {
+        try {
+          fuzz = (await import(spec)) as typeof import("@hyper/testing/fuzz")
+          break
+        } catch {
+          // try next
+        }
+      }
+      if (!fuzz) {
+        console.error("error: @hyper/testing not installed. Run `hyper add testing` first.")
+        return 2
+      }
+      const reports: string[] = []
+      let totalFailed = 0
+      for (const r of app.routeList) {
+        const entry = `${r.method} ${r.path}` as Parameters<typeof fuzz.fuzzRoute>[1]
+        const report = await fuzz.fuzzRoute(app, entry)
+        if (!report.ok) {
+          totalFailed += report.failed.length
+          reports.push(`FAIL ${r.method} ${r.path}: ${report.failed.length} case(s)`)
+          for (const f of report.failed) {
+            reports.push(`    ${f.case} (status=${f.status})`)
+            testResults.push({
+              suite: "fuzz",
+              name: `${r.method} ${r.path} :: ${f.case}`,
+              ok: false,
+              error: `status=${f.status}${f.error ? ` error=${f.error}` : ""}`,
+              time: 0,
+            })
+          }
+        } else {
+          testResults.push({
+            suite: "fuzz",
+            name: `${r.method} ${r.path}`,
+            ok: true,
+            time: 0,
+          })
+        }
+      }
+      if (reports.length > 0) {
+        console.log(reports.join("\n"))
+      } else {
+        console.log("fuzz: all routes clean")
+      }
+      if (totalFailed > 0) return 1
+    }
+  }
+
+  if (runTypes) {
+    const code = await runSpawn("tsgo", ["--noEmit", "-p", "tsconfig.json"])
+    if (code !== 0) {
+      const fallback = await runSpawn("bunx", ["tsc", "--noEmit", "-p", "tsconfig.json"])
+      if (fallback !== 0) return fallback
+    }
+  }
+
+  const bunCode = await runSpawn("bun", ["test"])
+
+  if (reporter === "junit") {
+    await writeFile(junitPath, toJunit(testResults))
+    if (!isJson(args.flags)) console.log(`junit report -> ${junitPath}`)
+  }
+
+  return bunCode
+}
+
+function runSpawn(cmd: string, args: readonly string[]): Promise<number> {
+  return new Promise<number>((res) => {
+    const child = spawn(cmd, [...args], { stdio: "inherit" })
+    child.on("exit", (code) => res(code ?? 1))
+    child.on("error", () => res(1))
+  })
+}
+
+function toJunit(
+  results: ReadonlyArray<{
+    suite: string
+    name: string
+    ok: boolean
+    error?: string
+    time: number
+  }>,
+): string {
+  const bySuite = new Map<string, typeof results>()
+  for (const r of results) {
+    const list = (bySuite.get(r.suite) ?? []) as typeof results
+    bySuite.set(r.suite, [...list, r] as typeof results)
+  }
+  const suites: string[] = []
+  for (const [name, rs] of bySuite) {
+    const failures = rs.filter((r) => !r.ok).length
+    const cases = rs
+      .map((r) => {
+        const open = `<testcase classname="${escapeXml(name)}" name="${escapeXml(r.name)}" time="${(r.time / 1000).toFixed(3)}">`
+        if (r.ok) return `${open}</testcase>`
+        return `${open}<failure message="${escapeXml(r.error ?? "failed")}" /></testcase>`
+      })
+      .join("\n")
+    suites.push(
+      `  <testsuite name="${escapeXml(name)}" tests="${rs.length}" failures="${failures}">\n${cases}\n  </testsuite>`,
+    )
+  }
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<testsuites>\n${suites.join("\n")}\n</testsuites>\n`
+}
+
+function escapeXml(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+}

package/src/commands/typecheck.ts

@@ -0,0 +1,19 @@
+import { spawn } from "node:child_process"
+import type { ParsedArgs } from "../args.ts"
+
+export async function runTypecheck(args: ParsedArgs): Promise<number> {
+  const tsconfig = typeof args.flags.p === "string" ? args.flags.p : "tsconfig.json"
+  // Prefer tsgo (TypeScript 7 native preview); fall back to tsc.
+  return new Promise((res) => {
+    const child = spawn("tsgo", ["--noEmit", "-p", tsconfig], {
+      stdio: "inherit",
+    })
+    child.on("error", () => {
+      const fallback = spawn("bunx", ["tsc", "--noEmit", "-p", tsconfig], {
+        stdio: "inherit",
+      })
+      fallback.on("exit", (code) => res(code ?? 1))
+    })
+    child.on("exit", (code) => res(code ?? 1))
+  })
+}

package/src/commands/update.ts

@@ -0,0 +1,91 @@
+/**
+ * `hyper update [component...]` — bump installed components to the
+ * latest registry version.
+ *
+ * Strategy: for each component listed in the lockfile (or the explicit
+ * positional list), fetch the latest manifest from the registry. If the
+ * version is newer, re-apply the component (subject to the same drift
+ * protection as `hyper add`).
+ *
+ * Conflicts are reported and skip that component's update — fix them with
+ * `hyper diff` + commit, or pass `--force`.
+ */
+
+import { type ParsedArgs, isJson } from "../args.ts"
+import { readConfig, readLock, writeLock } from "../config/index.ts"
+import { applyComponents, createRegistryClient } from "../registry/index.ts"
+
+export async function runUpdate(args: ParsedArgs): Promise<number> {
+  const config = await readConfig()
+  const client = createRegistryClient({ url: config.registryUrl })
+  const lock = await readLock()
+
+  const installed = Object.keys(lock.components)
+  if (installed.length === 0) {
+    console.error("no components installed (run `hyper add <component>` first)")
+    return 2
+  }
+
+  const targets = args.positional.length > 0 ? args.positional : installed
+  const force = args.flags.force === true
+  const dryRun = args.flags["dry-run"] === true || args.flags.n === true
+
+  const candidates: { name: string; from: string; to: string }[] = []
+  for (const name of targets) {
+    const cur = lock.components[name]
+    if (!cur) {
+      console.error(`not installed: ${name}`)
+      continue
+    }
+    const latest = await client.getComponent(name).catch(() => null)
+    if (!latest) {
+      console.error(`fetch failed: ${name}`)
+      continue
+    }
+    if (latest.version !== cur.version) {
+      candidates.push({ name, from: cur.version, to: latest.version })
+    }
+  }
+
+  if (candidates.length === 0) {
+    if (isJson(args.flags)) console.log(JSON.stringify({ updated: [], dryRun }))
+    else console.log("everything up-to-date.")
+    return 0
+  }
+
+  if (isJson(args.flags) && dryRun) {
+    console.log(JSON.stringify({ candidates, dryRun: true }))
+    return 0
+  }
+
+  const outcome = await applyComponents(
+    candidates.map((c) => c.name),
+    {
+      cwd: process.cwd(),
+      config,
+      client,
+      lock,
+      force,
+      dryRun,
+    },
+  )
+
+  if (outcome.conflicts.length > 0) {
+    console.error("conflicts (use --force, or `hyper diff <component>` first):")
+    for (const c of outcome.conflicts) console.error(`  ${c.path}  (${c.component})`)
+    return 1
+  }
+
+  if (!dryRun) await writeLock(outcome.lock)
+
+  if (isJson(args.flags)) {
+    console.log(JSON.stringify({ updated: candidates, written: outcome.written, dryRun }))
+    return 0
+  }
+
+  for (const c of candidates) console.log(`  ${c.name}: ${c.from} → ${c.to}`)
+  console.log(
+    `${dryRun ? "(dry-run) " : ""}${candidates.length} component(s) updated, ${outcome.written.length} file(s) ${dryRun ? "would be " : ""}written.`,
+  )
+  return 0
+}

package/src/commands/version.ts

@@ -0,0 +1,16 @@
+import { type ParsedArgs, isJson } from "../args.ts"
+
+export async function runVersion(args: ParsedArgs): Promise<number> {
+  const info = {
+    hyper: "0.0.0",
+    bun: typeof Bun !== "undefined" ? Bun.version : "unknown",
+    platform: process.platform,
+    arch: process.arch,
+  }
+  if (isJson(args.flags)) {
+    console.log(JSON.stringify(info))
+    return 0
+  }
+  console.log(`hyper ${info.hyper}  |  bun ${info.bun}  |  ${info.platform}-${info.arch}`)
+  return 0
+}

package/src/config/index.ts

@@ -0,0 +1,30 @@
+/** Public surface for `hyper.config.json` + `hyper.lock.json` IO. */
+
+export type {
+  HyperConfig,
+  HyperLock,
+  LockedComponent,
+  LockedFile,
+} from "./types.ts"
+export {
+  CONFIG_FILENAME,
+  DEFAULT_ALIAS,
+  DEFAULT_BASE_DIR,
+  DEFAULT_CONFIG,
+  DEFAULT_REGISTRY_URL,
+  LOCK_FILENAME,
+  SCHEMA_URL,
+} from "./types.ts"
+export {
+  configExists,
+  configPath,
+  defaultConfig,
+  emptyLock,
+  lockPath,
+  readConfig,
+  readLock,
+  writeConfig,
+  writeLock,
+} from "./io.ts"
+export { parseJsonc, patchTsConfig, readTsConfig, upsertAlias, writeTsConfig } from "./tsconfig.ts"
+export type { TsConfig } from "./tsconfig.ts"

package/src/config/io.ts

@@ -0,0 +1,112 @@
+/**
+ * Read/write helpers for `hyper.config.json` and `hyper.lock.json`.
+ *
+ * Behavioral guarantees:
+ *   - Reading a missing config file returns the defaults (with `registryUrl`
+ *     possibly overridden by the `HYPER_REGISTRY_URL` env var).
+ *   - Reading a missing lockfile returns an empty lock — never throws.
+ *   - Writes are pretty-printed with 2-space indent + trailing newline so the
+ *     files are diff-friendly when checked into source control.
+ */
+
+import { mkdir, readFile, writeFile } from "node:fs/promises"
+import { dirname, resolve } from "node:path"
+import {
+  CONFIG_FILENAME,
+  DEFAULT_ALIAS,
+  DEFAULT_BASE_DIR,
+  DEFAULT_CONFIG,
+  DEFAULT_REGISTRY_URL,
+  type HyperConfig,
+  type HyperLock,
+  LOCK_FILENAME,
+  type LockedComponent,
+  SCHEMA_URL,
+} from "./types.ts"
+
+export interface ConfigIO {
+  readonly cwd: string
+}
+
+export function configPath(cwd: string = process.cwd()): string {
+  return resolve(cwd, CONFIG_FILENAME)
+}
+
+export function lockPath(cwd: string = process.cwd()): string {
+  return resolve(cwd, LOCK_FILENAME)
+}
+
+async function readJsonOrNull<T>(path: string): Promise<T | null> {
+  try {
+    const buf = await readFile(path, "utf8")
+    return JSON.parse(buf) as T
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null
+    throw err
+  }
+}
+
+export async function readConfig(cwd: string = process.cwd()): Promise<HyperConfig> {
+  const fromDisk = await readJsonOrNull<Partial<HyperConfig>>(configPath(cwd))
+  const envUrl = process.env.HYPER_REGISTRY_URL
+  return {
+    $schema: fromDisk?.$schema ?? SCHEMA_URL,
+    registryUrl: envUrl ?? fromDisk?.registryUrl ?? DEFAULT_REGISTRY_URL,
+    baseDir: fromDisk?.baseDir ?? DEFAULT_BASE_DIR,
+    alias: fromDisk?.alias ?? DEFAULT_ALIAS,
+    ...(fromDisk?.tsx !== undefined && { tsx: fromDisk.tsx }),
+    ...(fromDisk?.pinVersions !== undefined && { pinVersions: fromDisk.pinVersions }),
+  }
+}
+
+export async function writeConfig(config: HyperConfig, cwd: string = process.cwd()): Promise<void> {
+  const path = configPath(cwd)
+  const ordered: HyperConfig = {
+    $schema: config.$schema ?? SCHEMA_URL,
+    registryUrl: config.registryUrl,
+    baseDir: config.baseDir,
+    alias: config.alias,
+    ...(config.tsx !== undefined && { tsx: config.tsx }),
+    ...(config.pinVersions !== undefined && { pinVersions: config.pinVersions }),
+  }
+  await mkdir(dirname(path), { recursive: true })
+  await writeFile(path, `${JSON.stringify(ordered, null, 2)}\n`)
+}
+
+export async function configExists(cwd: string = process.cwd()): Promise<boolean> {
+  return (await readJsonOrNull(configPath(cwd))) !== null
+}
+
+export function emptyLock(registryUrl: string = DEFAULT_REGISTRY_URL): HyperLock {
+  return { schema: 1, registryUrl, components: {} }
+}
+
+export async function readLock(cwd: string = process.cwd()): Promise<HyperLock> {
+  const fromDisk = await readJsonOrNull<HyperLock>(lockPath(cwd))
+  if (!fromDisk) return emptyLock()
+  return fromDisk
+}
+
+export async function writeLock(lock: HyperLock, cwd: string = process.cwd()): Promise<void> {
+  const path = lockPath(cwd)
+  await mkdir(dirname(path), { recursive: true })
+  // Sort keys deterministically so lockfile diffs are minimal.
+  const sortedComponents: Record<string, LockedComponent> = {}
+  for (const name of Object.keys(lock.components).sort()) {
+    sortedComponents[name] = lock.components[name]!
+  }
+  const ordered: HyperLock = {
+    schema: lock.schema,
+    registryUrl: lock.registryUrl,
+    components: sortedComponents,
+  }
+  await writeFile(path, `${JSON.stringify(ordered, null, 2)}\n`)
+}
+
+/** Default config with optional overrides for `hyper init`. */
+export function defaultConfig(overrides: Partial<HyperConfig> = {}): HyperConfig {
+  return {
+    ...DEFAULT_CONFIG,
+    ...overrides,
+  }
+}