hono-cli-adapter

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

hono-cli-adapter

(★ 11)

No description available.

hono-cli-adapter Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# hono-cli-adapter

Tiny library to adapt CLI arguments into a POST request for a Hono app — without touching stdout. It lets you build a small custom CLI around an existing Hono application, while keeping this package a pure, testable library.

Status: minimal but usable. ESM-only.

## Why
- Keep your CLI thin: printing, JSON formatting, and flags live in your own small bin.
- Library has no side effects: never writes to stdout/stderr.
- Strong constraints: POST-only philosophy for predictable calls from the shell.
- Reserved flags: easily exclude your CLI-only flags from HTTP query strings.
- Default env: `process.env` is merged by default.
- Env merging: combine `process.env` + `options.env` + repeated `--env KEY=VALUE` flags (later wins).
- Body tokens: pass `-- key=value` pairs to send JSON payloads.

## Install
```
npm install hono-cli-adapter
```

Peer/runtime expectations:
- Node 18+ (global WHATWG `fetch`)
- Hono app instance with `app.fetch(req, env)` available

## Quick Start
Create a tiny CLI that wraps your existing Hono app. Your CLI controls output and flags; the adapter only builds the request and calls `app.fetch`.

Default (recommended): one‑liner bin that prints and exits for you.

```ts
#!/usr/bin/env node
// my-cli.ts (ESM)
import { cli } from 'hono-cli-adapter'
import { app } from './dist/app.js' // your Hono app export

// Pass a process-like object (for argv/stdout/exit) or omit.
await cli(app) // or simply: await cli(app)
```

Pure/no‑stdout variant when you want to fully control printing and exiting yourself:

```ts
#!/usr/bin/env node
import { runCli } from 'hono-cli-adapter'
import { app } from './dist/app.js'

const { code, lines } = await runCli(app, process) // or runCli(app)
for (const l of lines) console.log(l)
process.exit(code)
```

## API
Exported from `src/index.ts`:

type AdapterOptions = {
  base?: string
  env?: Record<string, unknown>
  openapi?: OpenApiProvider
  reservedKeys?: string[]
  beforeFetch?: BeforeFetchFn | Record<string, BeforeFetchFn>
}

// High-level (recommended for CLI bins)
type RunCliResult = { code: number; lines: string[]; req?: Request; res?: Response }
type ProcLike = { argv?: any[]; stdout?: { write?: (s: string) => unknown }; exit?: (code?: number) => unknown }
function cli(app: any, argvOrProcess?: string[] | ProcLike | AdapterOptions, options?: AdapterOptions): Promise<number>
function runCli(app: any, argvOrProcess?: string[] | ProcLike | AdapterOptions, options?: AdapterOptions): Promise<RunCliResult>

// Mid-level
function adaptAndFetch(
  app: any,
  argvRaw?: string[] /* defaults to process.argv.slice(2) */,
  options?: AdapterOptions
): Promise<{ req: Request; res: Response }>

// Request building
function buildUrlFromArgv(argv: minimist.ParsedArgs, options?: AdapterOptions): URL
function buildRequestFromArgv(argv: minimist.ParsedArgs, options?: AdapterOptions): Request
function parseEnvFlags(envFlags: string | string[] | undefined): Record<string, string>
function parseBodyTokens(tokens: string | string[] | undefined): Record<string, string>
function commandFromArgv(argv: minimist.ParsedArgs, options?: AdapterOptions): string | undefined

// Route helpers
function listPostRoutes(app: any): string[]
function routePathToCommandSegments(routePath: string): string[]
function buildCommandExample(routePath: string, cmdBase: string): string
function buildCommandExamples(routes: string[], cmdBase: string): string[]
function detectCommandBase(argv0?: string, argv1?: string): string
function listRoutesWithExamples(app: any, cmdBase?: string): { routes: string[]; examples: string[] }
function listCommandExamples(app: any, cmdBase?: string): string[]
function listHelpLinesFromOpenApi(openapi: any, cmdBase?: string): string[]
```

Key behaviors:
- Reserved keys default to `['_', '--', 'base', 'env']` and are removed from the query string. Add your own via `options.reservedKeys`.
- `runCli`/`cli` also reserve global flags automatically: `json`, `list`, `help`, `base`, `env`.
- If `options.openapi` is provided, `--help` uses it to include per-parameter details (type, required/optional, description, default) and `--list` includes `--param` examples from the spec.
- Environment precedence when calling `app.fetch(req, env)`:
  1) `process.env` (base, included by default)
  2) `options.env` (overrides base)
  3) `--env KEY=VALUE` flags (highest precedence)
- Tokens after `--` like `key=value` become a JSON body.
- `buildRequestFromArgv` and `adaptAndFetch` use POST only.
- `listPostRoutes` is best-effort and relies on Hono’s internal shape. It enumerates POST paths only.

## Usage Patterns
Two ways to integrate (besides the default `cli` above):

1) High-level: let the adapter parse `argvRaw` for the common flags `--base`, `--env`.
```ts
const { res } = await adaptAndFetch(app, process.argv.slice(2), { reservedKeys: ['json'] })
```

2) Lower-level: parse your own flags, then build the request yourself.
```ts
import minimist from 'minimist'
import { buildRequestFromArgv, parseEnvFlags, listRoutesWithExamples, detectCommandBase } from 'hono-cli-adapter'

const argv = minimist(process.argv.slice(2), { string: ['env'], '--': true })
const req = buildRequestFromArgv(argv, { base: '/v1', reservedKeys: ['json'] })
const res = await app.fetch(req, { ...parseEnvFlags(argv.env) })

// Show routes plus runnable examples (you print; library does not):
const { routes, examples } = listRoutesWithExamples(app, detectCommandBase())
console.log('POST routes:')
for (const p of routes) console.log('  POST ' + p)
console.log('\nCommand examples:')
for (const ex of examples) console.log('  ' + ex)
```

### OpenAPI-powered help

If you have an OpenAPI spec (e.g., from `hono-openapi` + `describeRoute`), pass it to `runCli` to enrich `--help`:

```ts
const openapi = await getOpenApiSpecSomehow()
const { lines } = await runCli(app, process, { openapi })
for (const l of lines) console.log(l)
```

### Hooks and command detection

Tweak the outgoing `Request` before sending:

```ts
import fs from 'node:fs/promises'
import minimist from 'minimist'
import { adaptAndFetch, commandFromArgv } from 'hono-cli-adapter'

const argv = minimist(process.argv.slice(2), { '--': true })
const cmd = commandFromArgv(argv) // safe: no direct argv._ access

await adaptAndFetch(app, process.argv.slice(2), {
  beforeFetch: {
    upload: async (req, argv) => {
      if (argv.file) {
        const buf = await fs.readFile(argv.file)
        const headers = new Headers(req.headers)
        headers.set('content-type', 'application/octet-stream')
        return new Request(req, { body: buf, headers })
      }
    }
  }
})
```

## Example Projects
This repo ships runnable examples:
- `example/basic/` — minimal Hono app + CLI (`example/basic/README.md`)
- `example/slaq/` — Slack-focused CLI example built on this adapter

Quick taste:
```
npm run build
node example/basic/cli.mjs --list   # prints runnable command examples only
node example/basic/cli.mjs --help   # adds a Flags section
node example/basic/cli.mjs hello Taro         # -> "Hello, Taro!"
node example/basic/cli.mjs env API_KEY --env API_KEY=secret-123   # -> "API_KEY=secret-123"
```

Single-file binary via Bun:
```
npm run build:example:bin
./example/basic/bin/hono-example --list
./example/basic/bin/hono-example --help   # shows flags
```

## Design Notes
- POST-only now; adding other methods can be an additive future feature when/if needed.
- The adapter never writes to stdout — your CLI formats results (plain text, JSON, etc.).
- `runCli` automatically excludes the global CLI flags from the query. Add more via `reservedKeys` when needed.

## Compatibility
- ESM only. If you need CJS, transpile on your side.
- Node 18+ recommended. If you don’t have global `fetch`, polyfill (e.g. `undici`).

## Caveats
- `listPostRoutes` depends on Hono internals and may break if they change. Consider maintaining your own list if you need strong guarantees.

## Development
```
npm i
npm run build
```

That’s it — minimal surface, focused on the adapter behavior.

hono-cli-adapter

hono-cli-adapter Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

hono-cli-adapter

hono-cli-adapter Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README