@usehyper/cli 0.1.0

package/src/config/tsconfig.ts

@@ -0,0 +1,138 @@
+/**
+ * Minimal `tsconfig.json` reader/writer aware of JSONC (line + block comments
+ * and trailing commas) — many bun/node projects use a JSONC tsconfig.
+ *
+ * We only need to:
+ *   - read `compilerOptions.paths`
+ *   - upsert `<alias>/*` mappings under `paths`
+ *   - write back with comments and trailing commas preserved
+ *
+ * Strategy: read as JSONC into a JS object, mutate, write back with
+ * `JSON.stringify(_, null, 2)`. Comments/trailing commas are stripped on
+ * write — that's a deliberate trade-off (the user can re-add them) since
+ * preserving them losslessly would require a full CST parser.
+ */
+
+import { readFile, writeFile } from "node:fs/promises"
+import { resolve } from "node:path"
+
+export interface TsConfig {
+  extends?: string
+  compilerOptions?: {
+    baseUrl?: string
+    paths?: Record<string, string[]>
+    [k: string]: unknown
+  }
+  include?: string[]
+  exclude?: string[]
+  files?: string[]
+  [k: string]: unknown
+}
+
+/** Parse JSONC by stripping `//` line comments, `/* *\/` block comments, and trailing commas. */
+export function parseJsonc(input: string): unknown {
+  let s = input
+  // Strip line comments. Beware of "//" inside strings; we handle that by not
+  // touching characters inside double-quoted spans.
+  let out = ""
+  let i = 0
+  while (i < s.length) {
+    const c = s[i]
+    if (c === '"') {
+      // Copy entire string literal (incl. escape sequences) verbatim.
+      const start = i
+      i++
+      while (i < s.length) {
+        if (s[i] === "\\") {
+          i += 2
+          continue
+        }
+        if (s[i] === '"') {
+          i++
+          break
+        }
+        i++
+      }
+      out += s.slice(start, i)
+      continue
+    }
+    if (c === "/" && s[i + 1] === "/") {
+      while (i < s.length && s[i] !== "\n") i++
+      continue
+    }
+    if (c === "/" && s[i + 1] === "*") {
+      i += 2
+      while (i < s.length && !(s[i] === "*" && s[i + 1] === "/")) i++
+      i += 2
+      continue
+    }
+    out += c
+    i++
+  }
+  s = out
+  // Strip trailing commas before `}` or `]`.
+  s = s.replace(/,(\s*[}\]])/g, "$1")
+  return JSON.parse(s) as unknown
+}
+
+export async function readTsConfig(cwd: string = process.cwd()): Promise<{
+  raw: string
+  parsed: TsConfig
+} | null> {
+  const path = resolve(cwd, "tsconfig.json")
+  let raw: string
+  try {
+    raw = await readFile(path, "utf8")
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null
+    throw err
+  }
+  return { raw, parsed: parseJsonc(raw) as TsConfig }
+}
+
+export async function writeTsConfig(config: TsConfig, cwd: string = process.cwd()): Promise<void> {
+  const path = resolve(cwd, "tsconfig.json")
+  await writeFile(path, `${JSON.stringify(config, null, 2)}\n`)
+}
+
+/**
+ * Add `"<alias>/*": ["./<baseDir>/*", "./<baseDir>/*\/index.ts"]` to
+ * `compilerOptions.paths`. Idempotent: if the mapping already exists with
+ * the same value, returns the same config unchanged.
+ */
+export function upsertAlias(
+  config: TsConfig,
+  alias: string,
+  baseDir: string,
+): { config: TsConfig; changed: boolean } {
+  if (alias === "relative") return { config, changed: false }
+  const key = `${alias}/*`
+  const dir = baseDir.replace(/\/+$/, "")
+  const value = [`./${dir}/*`, `./${dir}/*/index.ts`]
+  const existing = config.compilerOptions?.paths?.[key]
+  if (existing && JSON.stringify(existing) === JSON.stringify(value)) {
+    return { config, changed: false }
+  }
+  const next: TsConfig = {
+    ...config,
+    compilerOptions: {
+      ...config.compilerOptions,
+      paths: { ...config.compilerOptions?.paths, [key]: value },
+    },
+  }
+  return { config: next, changed: true }
+}
+
+/** Convenience: read → upsert → write, only writing if something changed. */
+export async function patchTsConfig(
+  alias: string,
+  baseDir: string,
+  cwd: string = process.cwd(),
+): Promise<"missing" | "unchanged" | "patched"> {
+  const cur = await readTsConfig(cwd)
+  if (!cur) return "missing"
+  const { config: next, changed } = upsertAlias(cur.parsed, alias, baseDir)
+  if (!changed) return "unchanged"
+  await writeTsConfig(next, cwd)
+  return "patched"
+}

package/src/config/types.ts

@@ -0,0 +1,63 @@
+/**
+ * Shapes for `hyper.config.json` (project-level config) and
+ * `hyper.lock.json` (per-component install state).
+ *
+ * Both files live at the project root next to `package.json`.
+ */
+
+export interface HyperConfig {
+  /** JSON Schema URL — auto-injected, makes editor tooling work. */
+  readonly $schema?: string
+  /** Base URL of the registry. Default: `https://hyperjs.ai`. */
+  readonly registryUrl: string
+  /** Where components are written, relative to project root. Default: `src/hyper`. */
+  readonly baseDir: string
+  /**
+   * Import alias for installed components. The string `"relative"` means
+   * the CLI will rewrite all `@hyper/*` imports to relative paths instead.
+   * Default: `@hyper`.
+   */
+  readonly alias: string
+  /** Reserved for future TSX/JSX-aware components. */
+  readonly tsx?: boolean
+  /** Optional: pin every install to this exact registry version (CI use case). */
+  readonly pinVersions?: boolean
+}
+
+export interface LockedFile {
+  /** Path relative to project root (already resolved through `baseDir`). */
+  readonly path: string
+  /** SHA-256 of file contents AS WRITTEN (post import-rewrite). */
+  readonly sha256: string
+}
+
+export interface LockedComponent {
+  readonly version: string
+  /** When this component was installed/updated (ISO-8601). */
+  readonly installedAt: string
+  /** Which alias was used at install time (may differ from current config). */
+  readonly alias: string
+  /** Files installed by this component, in stable sorted order. */
+  readonly files: readonly LockedFile[]
+}
+
+export interface HyperLock {
+  readonly schema: 1
+  readonly registryUrl: string
+  readonly components: Readonly<Record<string, LockedComponent>>
+}
+
+export const CONFIG_FILENAME = "hyper.config.json"
+export const LOCK_FILENAME = "hyper.lock.json"
+
+export const DEFAULT_REGISTRY_URL = "https://hyperjs.ai"
+export const DEFAULT_BASE_DIR = "src/hyper"
+export const DEFAULT_ALIAS = "@hyper"
+export const SCHEMA_URL = "https://hyperjs.ai/schema.json"
+
+export const DEFAULT_CONFIG: HyperConfig = {
+  $schema: SCHEMA_URL,
+  registryUrl: DEFAULT_REGISTRY_URL,
+  baseDir: DEFAULT_BASE_DIR,
+  alias: DEFAULT_ALIAS,
+}

package/src/entry.ts

@@ -0,0 +1,42 @@
+/**
+ * Entry-point resolution. Default order:
+ *   1) The positional arg, if provided.
+ *   2) src/app.ts
+ *   3) app.ts
+ *   4) src/index.ts
+ *   5) index.ts
+ */
+
+import { resolve } from "node:path"
+
+const CANDIDATES = ["src/app.ts", "app.ts", "src/index.ts", "index.ts"]
+
+export async function resolveEntry(
+  positional: readonly string[],
+  cwd: string = process.cwd(),
+): Promise<string | null> {
+  const override = positional[0]
+  if (override) {
+    const p = resolve(cwd, override)
+    if (await exists(p)) return p
+    return null
+  }
+  for (const c of CANDIDATES) {
+    const p = resolve(cwd, c)
+    if (await exists(p)) return p
+  }
+  return null
+}
+
+async function exists(path: string): Promise<boolean> {
+  if (typeof Bun !== "undefined") {
+    return Bun.file(path).exists()
+  }
+  try {
+    const { access } = await import("node:fs/promises")
+    await access(path)
+    return true
+  } catch {
+    return false
+  }
+}

package/src/index.ts

@@ -0,0 +1,57 @@
+/**
+ * @usehyper/cli — programmatic entry for embedding the CLI in scripts/CI.
+ *
+ * The CLI is also installable as a binary via `bun add -D @usehyper/cli`
+ * (exposes the `hyper` executable). Most users won't import this module
+ * directly.
+ */
+
+export { parseArgs } from "./args.ts"
+export type { ParsedArgs } from "./args.ts"
+
+export { runAdd } from "./commands/add.ts"
+export { runBuild } from "./commands/build.ts"
+export { runDev } from "./commands/dev.ts"
+export { runDiff } from "./commands/diff.ts"
+export { runEnvCheck } from "./commands/env.ts"
+export { runHelp } from "./commands/help.ts"
+export { runInit } from "./commands/init.ts"
+export { runList } from "./commands/list.ts"
+export { runRoutes } from "./commands/routes.ts"
+export { runTypecheck } from "./commands/typecheck.ts"
+export { runUpdate } from "./commands/update.ts"
+export { runVersion } from "./commands/version.ts"
+
+export { resolveEntry } from "./entry.ts"
+export { TEMPLATES } from "./templates.ts"
+
+// Config
+export type { HyperConfig, HyperLock } from "./config/index.ts"
+export {
+  CONFIG_FILENAME,
+  DEFAULT_ALIAS,
+  DEFAULT_BASE_DIR,
+  DEFAULT_REGISTRY_URL,
+  LOCK_FILENAME,
+  defaultConfig,
+  readConfig,
+  readLock,
+  writeConfig,
+  writeLock,
+} from "./config/index.ts"
+
+// Registry
+export {
+  applyComponents,
+  createRegistryClient,
+  RegistryError,
+  resolveDeps,
+} from "./registry/index.ts"
+export type {
+  ApplyOptions,
+  ApplyOutcome,
+  RegistryClient,
+  RegistryComponent,
+  RegistryFile,
+  RegistryIndex,
+} from "./registry/index.ts"

package/src/load-app.ts

@@ -0,0 +1,89 @@
+/**
+ * Load a built HyperApp from a source path.
+ *
+ * Before importing we set `HYPER_SKIP_LISTEN=1` so user modules that call
+ * `.listen()` on their default export don't actually boot a socket during
+ * CLI introspection. The chain still runs through `.build()` so everything
+ * downstream (openapi, routes, mcp, bench) works.
+ *
+ * The user module can export any of:
+ *   - a `Hyper` instance (preferred — lowered via `.build()`)
+ *   - a `HyperApp` (the legacy `app({...})` shape)
+ *   - a `default` or named `app` export of either shape
+ *
+ * We deliberately duck-type rather than `import { Hyper }` so the CLI has
+ * no hard runtime dependency on `@hyper/core` — the user's local copy
+ * lives at `<baseDir>/core/` and is reached via tsconfig path resolution
+ * from their entry file.
+ */
+
+import { resolve } from "node:path"
+import { readConfig } from "./config/index.ts"
+
+/**
+ * Type-only stand-in. The real shape comes from the user's `@hyper/core`.
+ * We keep the import as `import type` so it's erased by Bun at runtime.
+ */
+import type { HyperApp } from "@hyper/core"
+
+interface DuckHyper {
+  build(): HyperApp
+}
+
+function isDuckHyper(x: unknown): x is DuckHyper {
+  return (
+    typeof x === "object" &&
+    x !== null &&
+    "build" in x &&
+    typeof (x as { build: unknown }).build === "function"
+  )
+}
+
+function isDuckHyperApp(x: unknown): x is HyperApp {
+  return (
+    typeof x === "object" &&
+    x !== null &&
+    "fetch" in x &&
+    typeof (x as { fetch: unknown }).fetch === "function" &&
+    "routeList" in x &&
+    Array.isArray((x as { routeList: unknown }).routeList)
+  )
+}
+
+export async function loadApp(entry: string): Promise<HyperApp | null> {
+  process.env.HYPER_SKIP_LISTEN = "1"
+  const mod = (await import(entry)) as {
+    default?: unknown
+    app?: unknown
+  }
+  const raw = mod.default ?? mod.app ?? null
+  if (raw === null) return null
+  if (isDuckHyper(raw)) return raw.build()
+  if (isDuckHyperApp(raw)) return raw
+  return null
+}
+
+/**
+ * Resolve a Hyper component module from the user's local install (preferred)
+ * or fall back to a workspace-resolved import (monorepo dev case).
+ *
+ * `name` is a registry component name (`"openapi"`, `"mcp"`, `"client"`, …).
+ *
+ * Resolution order:
+ *   1. `<cwd>/<baseDir>/<name>/index.ts`  (user's installed copy)
+ *   2. `@hyper/<name>`                    (workspace dev, or user's tsconfig alias)
+ *
+ * Returns `null` if neither works.
+ */
+export async function loadComponentModule<T>(name: string): Promise<T | null> {
+  const config = await readConfig()
+  const local = resolve(process.cwd(), config.baseDir, name, "index.ts")
+  for (const spec of [local, `@hyper/${name}`]) {
+    try {
+      return (await import(spec)) as T
+    } catch {
+      // try next
+    }
+  }
+  return null
+}

package/src/registry/__tests__/env-writer.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test } from "bun:test"
+import { mergeEnvFile } from "../env-writer.ts"
+
+describe("mergeEnvFile", () => {
+  test("appends new keys to empty file", () => {
+    const r = mergeEnvFile("", { FOO: "bar" })
+    expect(r.added).toEqual(["FOO"])
+    expect(r.preserved).toEqual([])
+    expect(r.merged).toContain("FOO=bar\n")
+    expect(r.merged.startsWith("# Added by `hyper add`")).toBe(true)
+  })
+
+  test("preserves existing keys verbatim", () => {
+    const existing = "FOO=existing-value\n"
+    const r = mergeEnvFile(existing, { FOO: "new-value" })
+    expect(r.added).toEqual([])
+    expect(r.preserved).toEqual(["FOO"])
+    expect(r.merged).toBe(existing)
+  })
+
+  test("mixed: keep existing, append missing", () => {
+    const existing = "FOO=keep-me\n"
+    const r = mergeEnvFile(existing, { FOO: "ignored", BAR: "added" })
+    expect(r.added).toEqual(["BAR"])
+    expect(r.preserved).toEqual(["FOO"])
+    expect(r.merged).toContain("FOO=keep-me\n")
+    expect(r.merged).toContain("BAR=added\n")
+  })
+
+  test("resolves ${random:hex:N} into 2N hex chars", () => {
+    const r = mergeEnvFile("", { JWT_SECRET: "${random:hex:32}" })
+    const m = /JWT_SECRET=([a-f0-9]+)/.exec(r.merged)
+    expect(m).not.toBeNull()
+    expect(m?.[1]?.length).toBe(64)
+  })
+
+  test("resolves ${random:base64:N}", () => {
+    const r = mergeEnvFile("", { S: "${random:base64:24}" })
+    const m = /S=(.+)/.exec(r.merged)
+    expect(m).not.toBeNull()
+    expect(m?.[1]).toMatch(/^[A-Za-z0-9+/=]+$/)
+  })
+
+  test("ignores ${...} forms it doesn't recognize", () => {
+    const r = mergeEnvFile("", { X: "${env:OTHER}" })
+    expect(r.merged).toContain('X="${env:OTHER}"\n')
+  })
+
+  test("respects export prefix when checking existing keys", () => {
+    const r = mergeEnvFile("export FOO=1\n", { FOO: "x" })
+    expect(r.preserved).toEqual(["FOO"])
+    expect(r.added).toEqual([])
+  })
+
+  test("skips comments and quoted hashes when reading keys", () => {
+    const existing = `# FOO=hidden
+BAR="value with # hash"
+`
+    const r = mergeEnvFile(existing, { FOO: "added", BAR: "ignored" })
+    expect(r.added).toEqual(["FOO"])
+    expect(r.preserved).toEqual(["BAR"])
+  })
+
+  test("idempotent: re-running yields the same file", () => {
+    const r1 = mergeEnvFile("", { A: "1", B: "2" })
+    const r2 = mergeEnvFile(r1.merged, { A: "x", B: "y" })
+    expect(r2.merged).toBe(r1.merged)
+    expect(r2.added).toEqual([])
+    expect(r2.preserved.sort()).toEqual(["A", "B"])
+  })
+
+  test("alphabetical key order in appended block", () => {
+    const r = mergeEnvFile("", { ZED: "z", ALPHA: "a", MID: "m" })
+    const lines = r.merged.split("\n").filter((l) => l.includes("="))
+    expect(lines).toEqual(["ALPHA=a", "MID=m", "ZED=z"])
+  })
+
+  test("preserves trailing-newline normalization", () => {
+    const r = mergeEnvFile("EXIST=1\n\n\n", { NEW: "v" })
+    expect(r.merged).toContain("EXIST=1\n\n# Added by `hyper add`")
+    expect(r.merged.endsWith("\n")).toBe(true)
+  })
+})