@usehyper/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Midday Labs AB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,31 @@
+# @usehyper/cli
+
+Hyper CLI — dev server, OpenAPI export, contract tests, security scan, benchmarks.
+
+## Install
+
+```bash
+bun add -d @usehyper/cli
+```
+
+## Usage
+
+```bash
+bun x hyper dev                 # hot-reload dev server
+bun x hyper routes              # print the route table
+bun x hyper test                # run .example() contracts
+bun x hyper test --fuzz --types # fuzz schemas + type-level assertions
+bun x hyper security --check    # static security audit
+bun x hyper openapi --out openapi.json
+bun x hyper bench --tests
+```
+
+`hyper dev` and every introspection command set `HYPER_SKIP_LISTEN=1` before importing your app, so the same `app.ts` works as both server entrypoint and CLI input.
+
+## Docs
+
+See the [main README](../../README.md) and [docs/](../../docs) for guides and integration recipes.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@usehyper/cli",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Hyper CLI — registry-driven scaffolding (init/add/diff/update) plus dev/build/test/openapi/mcp.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/usehyper/hyper.git"
+  },
+  "files": ["src", "registry-sources", "LICENSE", "README.md"],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsgo --noEmit || bunx tsc --noEmit -p tsconfig.json",
+    "test": "bun test",
+    "prepack": "bun run ../../tools/build-snapshots.ts"
+  },
+  "devDependencies": {
+    "@hyper/client": "0.1.0",
+    "@hyper/core": "0.1.0",
+    "@hyper/mcp": "0.1.0",
+    "@hyper/openapi": "0.1.0",
+    "@hyper/testing": "0.1.0",
+    "@types/bun": "1.3.1"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "hyper": "./src/bin.ts"
+  }
+}

package/registry-sources/agent-rules/README.md

@@ -0,0 +1,12 @@
+# agent-rules
+
+Drops `.cursor/rules/hyper.md` and `AGENTS.md` into your repo so Cursor, Claude
+Code, and other AI assistants understand how Hyper apps are structured: the
+chain API on `Hyper`, the explicit `route.<verb>().handle()` builder, the
+`decorate()` typing flow, plugin authoring, and the secure-by-default posture.
+
+```bash
+hyper add agent-rules
+```
+
+After install, AI agents get the rules automatically — no extra setup.

package/registry-sources/agent-rules/files/.cursor/rules/hyper.md

@@ -0,0 +1,178 @@
+---
+description: How to write Hyper routes, plugins, and middleware in this repo
+globs:
+  - src/hyper/**/*.ts
+  - src/**/*.ts
+alwaysApply: true
+---
+
+# Hyper rules
+
+This project uses [Hyper](https://hyperjs.ai), a Bun-first API framework whose
+source code lives in this repository at `src/hyper/<component>/`. Imports use
+the `@hyper/*` alias (mapped via `tsconfig.json` `paths`).
+
+## Authoring routes
+
+Two equivalent styles. Prefer the chain API for app composition; prefer the
+builder for routes you want to attach middleware/decorators/types to.
+
+### Chain API (preferred for top-level apps)
+
+```ts
+import { Hyper, ok } from "@hyper/core"
+import { z } from "zod"
+
+export default new Hyper()
+  .get("/health", "OK")
+  .post(
+    "/users",
+    { body: z.object({ name: z.string(), email: z.email() }) },
+    ({ body }) => ok({ id: crypto.randomUUID(), ...body }),
+  )
+  .listen(3000)
+```
+
+### Route builder (preferred when you need typed responses + middleware)
+
+```ts
+import { ok, route, notFound } from "@hyper/core"
+import { z } from "zod"
+
+const UserParams = z.object({ id: z.string() })
+
+export const getUser = route
+  .get("/users/:id")
+  .params(UserParams)
+  .handle(async ({ params, ctx }) => {
+    const u = await ctx.store.get(params.id)
+    if (!u) return notFound({ code: "user_not_found" })
+    return ok(u)
+  })
+```
+
+## Composing apps with `.use()`
+
+`.use()` is polymorphic. It accepts:
+
+- A sub-`Hyper` instance — its prefix is honored
+- A `HyperApp` from `app({...})`
+- A raw `Route` value or array of routes
+- A plugin returned by a plugin factory (`hyperLog(...)`, `cors(...)`, etc.)
+- A plain middleware (object with `start`/`success`/`error`/`finish`)
+
+```ts
+import { Hyper } from "@hyper/core"
+import { hyperLog } from "@hyper/log"
+import { cors } from "@hyper/cors"
+import users from "./routes/users.ts"
+import posts from "./routes/posts.ts"
+
+export default new Hyper()
+  .use(hyperLog({ service: "api" }))
+  .use(cors({ origin: ["https://example.com"] }))
+  .use(users)            // honors `users`'s own prefix
+  .use("/v1", posts)     // re-prefix
+  .listen(3000)
+```
+
+## Decorating context
+
+Use `.decorate()` (or `decorate: [...]` in `app({...})`) to attach typed
+services to `ctx`. Always extend `AppContext` via module augmentation so
+handlers see the right types.
+
+```ts
+import { Hyper } from "@hyper/core"
+import { db } from "./db.ts"
+
+declare module "@hyper/core" {
+  interface AppContext {
+    readonly db: typeof db
+  }
+}
+
+export default new Hyper().decorate(() => ({ db }))
+```
+
+## Response helpers
+
+Always return through helpers — they project to OpenAPI/MCP/client-types
+correctly. Never `new Response()` directly.
+
+```ts
+import {
+  ok, created, accepted, noContent,
+  badRequest, unauthorized, forbidden, notFound, conflict, unprocessable, tooManyRequests,
+  redirect, html, text, sse, stream, file,
+} from "@hyper/core"
+```
+
+## Errors
+
+Throw `HyperError` for typed errors — they project to the route's `errors`
+union and serialize consistently.
+
+```ts
+import { createError } from "@hyper/core"
+
+throw createError({ status: 409, code: "duplicate_email", message: "Email already in use" })
+```
+
+## Validation
+
+Body / params / query schemas are Standard Schema-compatible: Zod, Valibot,
+ArkType all work. Schemas declared on a route project to OpenAPI input
+schemas automatically.
+
+## Secure-by-default — do NOT disable lightly
+
+Hyper sets these for every response unless explicitly turned off:
+
+- `x-content-type-options: nosniff`
+- `x-frame-options: DENY`
+- `referrer-policy: strict-origin-when-cross-origin`
+- `strict-transport-security` (production only)
+- 1MB body cap
+- prototype-pollution guards on JSON bodies
+- per-route timeouts
+
+Auth endpoints default to rate-limiting via `@hyper/rate-limit`. JWT secrets
+must be ≥32 bytes (`@hyper/auth-jwt` will refuse to start otherwise).
+
+## Testing
+
+Use `@hyper/testing` — `app.test()`, `call()`, memory stores, deterministic
+clocks. Tests should run against `app.fetch(new Request(...))` directly,
+no network.
+
+```ts
+import { describe, expect, test } from "bun:test"
+import app from "../src/app.ts"
+
+describe("users", () => {
+  test("GET /users/:id", async () => {
+    const res = await app.fetch(new Request("http://localhost/users/u1"))
+    expect(res.status).toBe(200)
+  })
+})
+```
+
+## File layout convention
+
+```
+src/
+  hyper/                 # Hyper framework source (managed by `hyper` CLI)
+    core/                # @hyper/core
+    log/                 # @hyper/log
+    cors/                # @hyper/cors
+    ...
+  app.ts                 # entrypoint; default-exports a Hyper instance or HyperApp
+  routes/                # sub-app modules (preferred over inline routes)
+  schemas/               # Zod / Valibot schemas
+```
+
+`src/hyper/` is owned by the registry — do not edit by hand unless you intend
+to fork that component (and accept that `hyper update` will conflict). Run
+`hyper diff` to inspect drift between your local copy and the upstream
+registry.

package/registry-sources/agent-rules/files/AGENTS.md

@@ -0,0 +1,64 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+This project uses [Hyper](https://hyperjs.ai), a Bun-first API framework. The
+framework source is **vendored into this repo** under `src/hyper/<component>/`
+and managed by the `hyper` CLI — components are installed from a registry and
+copied directly into the project, not pulled in as npm dependencies. You own
+the code; you can edit it freely; `hyper update` will pull upstream changes
+when you ask for them.
+
+## Quick orientation
+
+- `src/app.ts` — entrypoint. Default-exports a `Hyper` instance or `HyperApp`.
+- `src/hyper/core/` — framework runtime. Imports as `@hyper/core`.
+- `src/hyper/<plugin>/` — installable plugins (log, cors, auth-jwt, …). Each is
+  imported as `@hyper/<plugin>`.
+- `package.json` has **no `@usehyper/*` deps** — everything ships via the
+  registry.
+- `hyper.config.json` — the registry config (URL, baseDir, alias).
+- `hyper.lock.json` — pins each installed component's version + per-file hash.
+
+## When you write code
+
+1. Import from `@hyper/<component>` — never `@usehyper/<component>`.
+2. Always return through Hyper's response helpers (`ok`, `created`, `notFound`, …).
+3. Always declare schemas (`body`, `params`, `query`) — they project to
+   OpenAPI/MCP/client types automatically.
+4. Use `.decorate()` for typed services on `ctx`. Augment `AppContext` via
+   `declare module "@hyper/core"`.
+5. For protected routes, chain `.auth()` from `@hyper/auth-jwt`.
+6. Never weaken the secure-by-default headers without an explicit reason.
+
+## When you install components
+
+Use the CLI, not edits:
+
+```bash
+hyper add cors
+hyper add auth-jwt
+hyper add openapi openapi-zod
+hyper diff log              # inspect drift
+hyper update log            # bump to latest registry version
+hyper add --info session    # show readme/files/deps without installing
+```
+
+The CLI rewrites `@hyper/*` imports to whatever alias is configured in
+`hyper.config.json`. Do not hand-edit the `paths` mapping.
+
+## When you debug or extend
+
+- `hyper routes` — print the route graph
+- `hyper openapi` — emit OpenAPI 3.1
+- `hyper client out.ts` — emit a typed RPC client
+- `hyper mcp` — serve the app's routes over MCP for AI introspection
+- `hyper bench --tests` — measure per-route latency
+
+## Style
+
+- Imports use `.ts` extensions (`from "./schemas.ts"`) — `verbatimModuleSyntax`
+  is on.
+- Prefer the chain API (`new Hyper().get(...)`) for top-level apps; prefer
+  the builder (`route.get(...).body(...).handle(...)`) for sub-app modules.
+- Tests run via `bun test` against `app.fetch(new Request(...))` — no network.

package/registry-sources/agent-rules/manifest.json

@@ -0,0 +1,15 @@
+{
+  "name": "agent-rules",
+  "version": "0.1.0",
+  "title": "Agent rules",
+  "description": "Cursor / Claude Code rules teaching AI assistants how to compose Hyper routes, plugins, and middleware correctly.",
+  "registryDeps": [],
+  "peerDeps": {},
+  "optionalPeerDeps": {},
+  "subpaths": {},
+  "files": [
+    { "path": "AGENTS.md", "target": "@root/AGENTS.md" },
+    { "path": ".cursor/rules/hyper.md", "target": "@root/.cursor/rules/hyper.md" }
+  ],
+  "docs": "Files installed:\n  - AGENTS.md (project root)\n  - .cursor/rules/hyper.md\n\nKeep these committed so AI assistants pick up Hyper's conventions automatically. Re-run `hyper add agent-rules` after upgrading Hyper to refresh."
+}

package/src/__tests__/add.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, test } from "bun:test"
+import { mkdtemp, readFile, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { runAdd } from "../commands/add.ts"
+import { runDiff } from "../commands/diff.ts"
+import { writeConfig } from "../config/index.ts"
+import { SNAPSHOT_INDEX, createRegistryClient } from "../registry/index.ts"
+
+async function withCwd<T>(dir: string, fn: () => Promise<T>): Promise<T> {
+  const prev = process.cwd()
+  process.chdir(dir)
+  try {
+    return await fn()
+  } finally {
+    process.chdir(prev)
+  }
+}
+
+async function setupProject(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), "hyper-add-"))
+  await writeConfig(
+    {
+      registryUrl: "https://example.invalid",
+      baseDir: "src/hyper",
+      alias: "@hyper",
+    },
+    dir,
+  )
+  return dir
+}
+
+describe("registry client (snapshot fallback)", () => {
+  test("snapshot index includes core + a representative set of components", () => {
+    const names = SNAPSHOT_INDEX.components.map((c) => c.name)
+    expect(names).toContain("core")
+    expect(names).toContain("cors")
+    expect(names).toContain("auth-jwt")
+    expect(names).toContain("agent-rules")
+  })
+
+  test("offline client serves the snapshot index", async () => {
+    const c = createRegistryClient({ url: "https://example.invalid", offline: true })
+    const idx = await c.getIndex()
+    expect(idx.components.length).toBeGreaterThan(0)
+    const cors = await c.getComponent("cors")
+    expect(cors.name).toBe("cors")
+    expect(cors.registryDeps).toContain("core")
+  })
+})
+
+describe("hyper add", () => {
+  test("copies cors + transitive core deps into the project", async () => {
+    const dir = await setupProject()
+    await withCwd(dir, async () => {
+      // Force snapshot mode by pointing at an unreachable URL.
+      const code = await runAdd({
+        command: "add",
+        positional: ["cors"],
+        flags: {},
+      })
+      expect(code).toBe(0)
+      const corsBody = await readFile(join(dir, "src/hyper/cors/index.ts"), "utf8")
+      expect(corsBody).toContain("@hyper/core")
+      const coreIndex = await readFile(join(dir, "src/hyper/core/index.ts"), "utf8")
+      expect(coreIndex).toContain("export")
+    })
+  })
+
+  test("refuses to overwrite drifted files without --force", async () => {
+    const dir = await setupProject()
+    await withCwd(dir, async () => {
+      await runAdd({ command: "add", positional: ["cors"], flags: {} })
+      await writeFile(join(dir, "src/hyper/cors/index.ts"), "// drifted\n")
+      const code = await runAdd({ command: "add", positional: ["cors"], flags: {} })
+      expect(code).toBe(1)
+    })
+  })
+
+  test("--force overrides drift protection", async () => {
+    const dir = await setupProject()
+    await withCwd(dir, async () => {
+      await runAdd({ command: "add", positional: ["cors"], flags: {} })
+      await writeFile(join(dir, "src/hyper/cors/index.ts"), "// drifted\n")
+      const code = await runAdd({
+        command: "add",
+        positional: ["cors"],
+        flags: { force: true },
+      })
+      expect(code).toBe(0)
+      const after = await readFile(join(dir, "src/hyper/cors/index.ts"), "utf8")
+      expect(after).not.toBe("// drifted\n")
+    })
+  })
+
+  test("agent-rules drops .cursor/rules + AGENTS.md at project root, NOT under baseDir", async () => {
+    const dir = await setupProject()
+    await withCwd(dir, async () => {
+      const code = await runAdd({
+        command: "add",
+        positional: ["agent-rules"],
+        flags: {},
+      })
+      expect(code).toBe(0)
+      const rules = await readFile(join(dir, ".cursor/rules/hyper.md"), "utf8")
+      expect(rules).toContain("Hyper rules")
+      const agents = await readFile(join(dir, "AGENTS.md"), "utf8")
+      expect(agents).toContain("AGENTS.md")
+    })
+  })
+})
+
+describe("hyper diff", () => {
+  test("detects drift against the registry", async () => {
+    const dir = await setupProject()
+    await withCwd(dir, async () => {
+      await runAdd({ command: "add", positional: ["cors"], flags: {} })
+      const clean = await runDiff({ command: "diff", positional: ["cors"], flags: {} })
+      expect(clean).toBe(0)
+      await writeFile(join(dir, "src/hyper/cors/index.ts"), "// drifted\n")
+      const drift = await runDiff({ command: "diff", positional: ["cors"], flags: {} })
+      expect(drift).toBe(1)
+    })
+  })
+})

package/src/__tests__/cli.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from "bun:test"
+import { parseArgs } from "../args.ts"
+import { TEMPLATES } from "../templates.ts"
+
+describe("cli args parser", () => {
+  test("parses command + positional + flags", () => {
+    const a = parseArgs(["build", "src/app.ts", "--out", "dist", "--minify"])
+    expect(a.command).toBe("build")
+    expect(a.positional).toEqual(["src/app.ts"])
+    expect(a.flags.out).toBe("dist")
+    expect(a.flags.minify).toBe(true)
+  })
+
+  test("respects --json", () => {
+    const a = parseArgs(["routes", "--json"])
+    expect(a.flags.json).toBe(true)
+  })
+
+  test("no command returns undefined", () => {
+    const a = parseArgs([])
+    expect(a.command).toBeUndefined()
+  })
+})
+
+describe("cli templates", () => {
+  test("templates ship with @hyper/* (not @usehyper/*) imports", () => {
+    expect(TEMPLATES.minimal).toBeDefined()
+    expect(TEMPLATES.minimal!.files["src/app.ts"]).toContain("@hyper/core")
+    expect(TEMPLATES.minimal!.files["src/app.ts"]).not.toContain("@usehyper/core")
+    expect(TEMPLATES.api).toBeDefined()
+    expect(TEMPLATES.api!.files["src/app.ts"]).toContain("@hyper/log")
+    expect(TEMPLATES.api!.files["src/app.ts"]).not.toContain("@usehyper/log")
+  })
+
+  test("templates patch tsconfig with @hyper/* path mapping", () => {
+    expect(TEMPLATES.minimal!.files["tsconfig.json"]).toContain('"@hyper/*"')
+    expect(TEMPLATES.minimal!.files["tsconfig.json"]).toContain("./src/hyper/*")
+  })
+
+  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/")
+  })
+
+  test("templates declare which components to install after init", () => {
+    expect(TEMPLATES.minimal!.components).toContain("core")
+    expect(TEMPLATES.api!.components).toContain("core")
+    expect(TEMPLATES.api!.components).toContain("log")
+  })
+})

package/src/__tests__/security.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, test } from "bun:test"
+import { app, route } from "@hyper/core"
+import { auditApp } from "../commands/security.ts"
+
+describe("hyper security --check — auditApp", () => {
+  test("clean app passes", async () => {
+    const a = app({ routes: [route.get("/").handle(() => "ok")] })
+    const findings = await auditApp(a)
+    const failed = findings.filter((f) => f.level === "fail")
+    expect(failed).toEqual([])
+  })
+
+  test("fails when default headers are disabled", async () => {
+    const a = app({
+      routes: [route.get("/").handle(() => "ok")],
+      security: { headers: false },
+    })
+    const findings = await auditApp(a)
+    const f = findings.find((x) => x.id === "sec-headers")!
+    expect(f.level).toBe("fail")
+  })
+
+  test("fails when method-override guard is off", async () => {
+    const a = app({
+      routes: [route.get("/").handle(() => "ok")],
+      security: { rejectMethodOverride: false },
+    })
+    const f = (await auditApp(a)).find((x) => x.id === "sec-method-override")!
+    expect(f.level).toBe("fail")
+  })
+
+  test("flags authEndpoint routes with no authRateLimitPlugin", async () => {
+    const a = app({
+      routes: [
+        route
+          .post("/login")
+          .meta({ authEndpoint: true })
+          .handle(() => ({ ok: true })),
+      ],
+    })
+    const f = (await auditApp(a)).find((x) => x.id === "sec-auth-rate")!
+    expect(f.level).toBe("fail")
+  })
+
+  test("warns on excessive body limit", async () => {
+    const a = app({
+      routes: [route.get("/").handle(() => "ok")],
+      security: { bodyLimitBytes: 100 * 1_048_576 },
+    })
+    const f = (await auditApp(a)).find((x) => x.id === "sec-body-limit")!
+    expect(f.level).toBe("warn")
+  })
+
+  test("warns when session() middleware is present on a mutating route without csrfGuard()", async () => {
+    const fakeSession: import("@hyper/core").Middleware = Object.assign(
+      async ({ next }: { next: () => Promise<unknown> }) => next() as Promise<Response>,
+      { __hyperTag: "@hyper/session" },
+    ) as unknown as import("@hyper/core").Middleware
+    const a = app({
+      routes: [
+        route
+          .post("/profile")
+          .use(fakeSession)
+          .handle(() => ({ ok: true })),
+      ],
+    })
+    const f = (await auditApp(a)).find((x) => x.id === "sec-csrf")!
+    expect(f.level).toBe("warn")
+    expect(f.fix).toContain("POST /profile")
+  })
+
+  test("passes sec-csrf when session + csrfGuard are chained", async () => {
+    const fakeSession: import("@hyper/core").Middleware = Object.assign(
+      async ({ next }: { next: () => Promise<unknown> }) => next() as Promise<Response>,
+      { __hyperTag: "@hyper/session" },
+    ) as unknown as import("@hyper/core").Middleware
+    const fakeCsrf: import("@hyper/core").Middleware = Object.assign(
+      async ({ next }: { next: () => Promise<unknown> }) => next() as Promise<Response>,
+      { __hyperTag: "@hyper/session:csrf" },
+    ) as unknown as import("@hyper/core").Middleware
+    const a = app({
+      routes: [
+        route
+          .post("/profile")
+          .use(fakeSession)
+          .use(fakeCsrf)
+          .handle(() => ({ ok: true })),
+      ],
+    })
+    const f = (await auditApp(a)).find((x) => x.id === "sec-csrf")!
+    expect(f.level).toBe("pass")
+  })
+
+  test("does not emit sec-csrf when session middleware is absent", async () => {
+    const a = app({
+      routes: [route.post("/anything").handle(() => ({ ok: true }))],
+    })
+    const f = (await auditApp(a)).find((x) => x.id === "sec-csrf")
+    expect(f).toBeUndefined()
+  })
+})

package/src/args.ts

@@ -0,0 +1,38 @@
+/**
+ * Minimal arg parser — no deps. Supports:
+ *   hyper <command> [positional] [--flag value] [--bool] [-s]
+ */
+
+export interface ParsedArgs {
+  readonly command: string | undefined
+  readonly positional: readonly string[]
+  readonly flags: Readonly<Record<string, string | boolean>>
+}
+
+export function parseArgs(argv: readonly string[]): ParsedArgs {
+  const [command, ...rest] = argv
+  const positional: string[] = []
+  const flags: Record<string, string | boolean> = {}
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i]!
+    if (a.startsWith("--")) {
+      const key = a.slice(2)
+      const next = rest[i + 1]
+      if (next !== undefined && !next.startsWith("-")) {
+        flags[key] = next
+        i++
+      } else {
+        flags[key] = true
+      }
+    } else if (a.startsWith("-")) {
+      flags[a.slice(1)] = true
+    } else {
+      positional.push(a)
+    }
+  }
+  return { command, positional, flags }
+}
+
+export function isJson(flags: Readonly<Record<string, string | boolean>>): boolean {
+  return flags.json === true || flags.json === "true"
+}