@usehyper/cli 0.1.0 → 0.1.1

package/package.json

@@ -1,12 +1,17 @@
 {
   "name": "@usehyper/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "Hyper CLI — registry-driven scaffolding (init/add/diff/update) plus dev/build/test/openapi/mcp.",
   "license": "MIT",
+  "homepage": "https://hyperjs.ai",
   "repository": {
     "type": "git",
-    "url": "https://github.com/usehyper/hyper.git"
+    "url": "git+https://github.com/pontusab/hyper.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/pontusab/hyper/issues"
   },
   "files": ["src", "registry-sources", "LICENSE", "README.md"],
   "exports": {

package/src/__tests__/cli.test.ts

@@ -38,8 +38,21 @@ describe("cli templates", () => {
   })
 
   test("templates have no @usehyper/* runtime deps", () => {
-    expect(TEMPLATES.minimal!.files["package.json"]).not.toContain("@usehyper/")
-    expect(TEMPLATES.api!.files["package.json"]).not.toContain("@usehyper/")
+    for (const name of ["minimal", "api"] as const) {
+      const pkg = JSON.parse(TEMPLATES[name]!.files["package.json"]!) as {
+        dependencies?: Record<string, string>
+      }
+      expect(pkg.dependencies ?? {}).toEqual({})
+    }
+  })
+
+  test("templates pin @usehyper/cli as a devDependency", () => {
+    for (const name of ["minimal", "api"] as const) {
+      const pkg = JSON.parse(TEMPLATES[name]!.files["package.json"]!) as {
+        devDependencies?: Record<string, string>
+      }
+      expect(pkg.devDependencies?.["@usehyper/cli"]).toBeDefined()
+    }
   })
 
   test("templates declare which components to install after init", () => {

package/src/banner.ts

@@ -0,0 +1,34 @@
+/**
+ * Welcome banner printed at the top of `hyper init`. Deliberately scoped
+ * to the scaffolding moment — every other command stays terse so output
+ * is friendly to pipes, agent loops, and CI logs.
+ *
+ * Suppressed when:
+ *   - `--json` is set (the caller wants machine output)
+ *   - stdout isn't a TTY (piped or redirected)
+ *   - `CI` is set (CI runners log this verbatim)
+ *
+ * The shape is the figlet "small" font for "hyper". Exact widths preserved
+ * so it lines up the same in any monospace terminal.
+ */
+
+const LOGO = String.raw`
+ _
+| |_  _ _ __   ___ _ __
+| ' \| || | '_ \ / -_) '_|
+|_||_|\_, | .__/ \___|_|
+      |__/|_|
+`
+
+export interface BannerOptions {
+  readonly json?: boolean
+}
+
+export function printBanner(version: string, opts: BannerOptions = {}): void {
+  if (opts.json) return
+  if (process.env.CI) return
+  if (process.env.HYPER_NO_BANNER) return
+  if (!process.stdout.isTTY) return
+  process.stdout.write(LOGO)
+  process.stdout.write(`v${version} · API framework for Bun, distributed as source\n\n`)
+}

package/src/commands/init.ts

@@ -4,21 +4,49 @@
  *   hyper init                 # minimal template into the current dir
  *   hyper init api             # api template
  *   hyper init --dir my-app    # into a subdir
- *   hyper init --no-install    # skip auto `hyper add core`
+ *   hyper init --no-components # skip auto `hyper add core`
+ *   hyper init --no-install    # skip `bun install` after scaffolding
  *   hyper init --agent-rules   # also install the agent-rules component
  *
- * The template files have NO `@usehyper/*` deps. After files are written
- * we run `hyper add` for each `template.components` entry, which copies the
- * framework source into `<baseDir>/<component>/` and updates the lockfile.
+ * The template files have NO `@hyper/*` runtime deps — imports use
+ * `@hyper/core` and resolve to vendored source under `src/hyper/<name>/` via
+ * tsconfig paths.
+ *
+ * Flow:
+ *   1. Write template files into the target dir (with `@usehyper/cli` pinned
+ *      to the running CLI's version in devDependencies).
+ *   2. Run the registry applier — copies component source into the project
+ *      and aggregates peer-dep declarations.
+ *   3. Merge any peer deps into `package.json`.
+ *   4. Run `bun install` so `node_modules/.bin/hyper` is available
+ *      immediately.
  */
 
-import { mkdir, stat, writeFile } from "node:fs/promises"
+import { spawn } from "node:child_process"
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises"
 import { dirname, resolve } from "node:path"
 import { type ParsedArgs, isJson } from "../args.ts"
+import { printBanner } from "../banner.ts"
 import { defaultConfig, patchTsConfig, readLock, writeConfig, writeLock } from "../config/index.ts"
 import { applyComponents, createRegistryClient } from "../registry/index.ts"
 import { TEMPLATES } from "../templates.ts"
 
+/**
+ * The CLI's own version. Used to pin `@usehyper/cli` in scaffolded
+ * `package.json` files. Resolved at runtime so we don't drift if the bin
+ * is invoked from a workspace where the package.json on disk is newer than
+ * the constants frozen into a build.
+ */
+async function readOwnVersion(): Promise<string> {
+  try {
+    const url = new URL("../../package.json", import.meta.url)
+    const raw = await readFile(url, "utf8")
+    const v = (JSON.parse(raw) as { version?: string }).version
+    if (typeof v === "string" && v.length > 0) return v
+  } catch {}
+  return "latest"
+}
+
 export async function runInit(args: ParsedArgs): Promise<number> {
   const templateName = args.positional[0] ?? "minimal"
   const targetDir = typeof args.flags.dir === "string" ? args.flags.dir : "."
@@ -33,16 +61,19 @@ export async function runInit(args: ParsedArgs): Promise<number> {
   const cwd = resolve(process.cwd(), targetDir)
   await mkdir(cwd, { recursive: true })
 
+  const cliVersion = await readOwnVersion()
+  printBanner(cliVersion, { json: isJson(args.flags) })
+
   const writtenFiles: string[] = []
   for (const [rel, contents] of Object.entries(template.files)) {
     const abs = resolve(cwd, rel)
     if (await pathExists(abs)) continue // never clobber existing files
     await mkdir(dirname(abs), { recursive: true })
-    await writeFile(abs, contents)
+    const final = contents.replaceAll("__HYPER_CLI_VERSION__", cliVersion)
+    await writeFile(abs, final)
     writtenFiles.push(abs)
   }
 
-  // Write hyper.config.json + patch tsconfig paths.
   const config = defaultConfig()
   await writeConfig(config, cwd)
   await patchTsConfig(config.alias, config.baseDir, cwd)
@@ -50,7 +81,7 @@ export async function runInit(args: ParsedArgs): Promise<number> {
   // Auto-install template components (core, optionally log, etc.).
   let componentsInstalled = 0
   let installPeerDeps: Record<string, string> = {}
-  if (args.flags["no-install"] !== true) {
+  if (args.flags["no-components"] !== true) {
     const components = [...template.components]
     if (args.flags["agent-rules"] === true || args.flags["with-agent-rules"] === true) {
       components.push("agent-rules")
@@ -70,6 +101,15 @@ export async function runInit(args: ParsedArgs): Promise<number> {
     installPeerDeps = outcome.peerDeps as Record<string, string>
   }
 
+  if (Object.keys(installPeerDeps).length > 0) {
+    await mergePackageJsonDeps(cwd, installPeerDeps)
+  }
+
+  let installRan = false
+  if (args.flags["no-install"] !== true) {
+    installRan = await runBunInstall(cwd)
+  }
+
   if (isJson(args.flags)) {
     console.log(
       JSON.stringify({
@@ -77,6 +117,7 @@ export async function runInit(args: ParsedArgs): Promise<number> {
         cwd,
         files: writtenFiles,
         componentsInstalled,
+        installRan,
       }),
     )
     return 0
@@ -90,18 +131,11 @@ export async function runInit(args: ParsedArgs): Promise<number> {
 
   console.log("\nnext steps:")
   console.log(`  cd ${targetDir === "." ? "." : targetDir}`)
-  console.log("  bun install")
-  if (Object.keys(installPeerDeps).length > 0) {
-    console.log(
-      `  bun add ${Object.entries(installPeerDeps)
-        .map(([k, v]) => `${k}@${v}`)
-        .join(" ")}`,
-    )
-  }
+  if (!installRan) console.log("  bun install")
   console.log("  bun run dev")
   console.log("")
   console.log("  # for AI agents (Cursor / Claude Code), drop in agent rules:")
-  console.log("  hyper add agent-rules")
+  console.log("  bunx hyper add agent-rules")
   console.log("")
   console.log("  # for AI tools to discover this registry, point them at:")
   console.log(`  ${config.registryUrl}/mcp`)
@@ -117,3 +151,49 @@ async function pathExists(p: string): Promise<boolean> {
     return false
   }
 }
+
+/**
+ * Merge peer-deps declared by registry components into the scaffolded
+ * `package.json`. Existing keys win — we never downgrade or override what
+ * the user already specified.
+ */
+async function mergePackageJsonDeps(
+  cwd: string,
+  peerDeps: Readonly<Record<string, string>>,
+): Promise<void> {
+  const path = resolve(cwd, "package.json")
+  let raw: string
+  try {
+    raw = await readFile(path, "utf8")
+  } catch {
+    return
+  }
+  const pkg = JSON.parse(raw) as { dependencies?: Record<string, string> }
+  const merged = { ...peerDeps, ...(pkg.dependencies ?? {}) }
+  pkg.dependencies = merged
+  await writeFile(path, `${JSON.stringify(pkg, null, 2)}\n`)
+}
+
+/**
+ * Spawn `bun install` in the project dir. Returns true on success. Errors
+ * are logged but don't abort the scaffold — the user can always retry the
+ * install manually.
+ */
+async function runBunInstall(cwd: string): Promise<boolean> {
+  process.stdout.write("\nrunning `bun install`…\n")
+  return await new Promise<boolean>((res) => {
+    const child = spawn("bun", ["install"], { cwd, stdio: "inherit" })
+    child.on("error", (err) => {
+      console.error(`warning: bun install failed to start (${err.message})`)
+      res(false)
+    })
+    child.on("exit", (code) => {
+      if (code !== 0) {
+        console.error(`warning: \`bun install\` exited with code ${code ?? "?"}; run it manually.`)
+        res(false)
+        return
+      }
+      res(true)
+    })
+  })
+}

package/src/registry/snapshot.ts

@@ -8,8 +8,8 @@ import type { RegistryComponent, RegistryIndex } from "./types.ts"
 
 export const SNAPSHOT_INDEX: RegistryIndex = {
   "schema": 1,
-  "generatedAt": "2026-05-24T12:15:05.341Z",
-  "source": "https://github.com/usehyper/hyper",
+  "generatedAt": "2026-05-24T13:00:38.109Z",
+  "source": "https://github.com/pontusab/hyper",
   "components": [
     {
       "name": "agent-rules",

package/src/templates.ts

@@ -49,6 +49,13 @@ const MINIMAL_TSCONFIG = `{
 }
 `
 
+/**
+ * Template `package.json`. `__HYPER_CLI_VERSION__` is replaced by `init` with
+ * the version of the running CLI so freshly-scaffolded projects pin against
+ * the same release that scaffolded them. Once `bun install` runs, the
+ * `hyper` binary lands in `node_modules/.bin/` and is available as
+ * `bun run hyper …` (or `bunx hyper …`).
+ */
 const MINIMAL_PKG = `{
   "name": "my-hyper-app",
   "type": "module",
@@ -61,6 +68,7 @@ const MINIMAL_PKG = `{
   },
   "devDependencies": {
     "@types/bun": "latest",
+    "@usehyper/cli": "^__HYPER_CLI_VERSION__",
     "typescript": "^5.6.0"
   }
 }
@@ -107,11 +115,13 @@ bun run dev
 
 ## Manage components
 
+The \`hyper\` CLI is a devDependency. Run it via \`bunx\` or \`bun run\`:
+
 \`\`\`bash
-hyper list                 # browse the registry
-hyper add cors             # add a component
-hyper diff log             # inspect drift on an installed component
-hyper update               # pull the latest registry versions
+bunx hyper list            # browse the registry
+bunx hyper add cors        # add a component
+bunx hyper diff log        # inspect drift on an installed component
+bunx hyper update          # pull the latest registry versions
 \`\`\`
 `