|
1 | 1 | <div align="center"> |
2 | 2 | <img src="assets/banner.svg" alt="kidd" width="90%" /> |
3 | 3 | <p><strong>An opinionated CLI framework for Node.js. Convention over configuration, end-to-end type safety.</strong></p> |
| 4 | + <a href="https://kidd.dev">Documentation</a> |
4 | 5 | </div> |
5 | 6 |
|
6 | 7 | ## Features |
@@ -101,168 +102,7 @@ kidd compile # -> dist/deploy (standalone binary) |
101 | 102 | ./dist/deploy deploy --tag v1.2.3 # no node/bun needed on target |
102 | 103 | ``` |
103 | 104 |
|
104 | | -## Design Philosophy |
105 | | - |
106 | | -- **Opinionated** — One way to structure a CLI, one way to define commands, one way to handle config. This is a framework, not a toolkit |
107 | | -- **Convention-based** — Inspired by Next.js file-system routing. Add a file, it appears as a command |
108 | | -- **Context flows everywhere** — Like [Hono's `c`](https://hono.dev/docs/api/context), `ctx` is the one argument you need |
109 | | -- **Zod-first** — Yargs-native arg format is also accepted and converted internally, but Zod is the primary API |
110 | | -- **Compiled for production** — File-system conventions for authoring, hard references for production (same pattern as Next.js route manifests) |
111 | | -- **ESM-only** — Pure ESM, `"type": "module"`, `.js` extensions. No CJS dual-publish, no interop hacks |
112 | | - |
113 | | -## Commands |
114 | | - |
115 | | -The file system maps directly to the command tree: |
116 | | - |
117 | | -``` |
118 | | -commands/ |
119 | | - greet.ts -> mycli greet |
120 | | - deploy.ts -> mycli deploy |
121 | | - config/ |
122 | | - index.ts -> mycli config |
123 | | - set.ts -> mycli config set |
124 | | - get.ts -> mycli config get |
125 | | -``` |
126 | | - |
127 | | -Nested commands use `autoload()` to discover siblings: |
128 | | - |
129 | | -```typescript |
130 | | -// commands/config/index.ts |
131 | | -import { command, autoload } from 'kidd' |
132 | | - |
133 | | -export default command({ |
134 | | - description: 'Manage configuration', |
135 | | - commands: autoload(), |
136 | | - handler: (ctx) => { |
137 | | - ctx.output.write(ctx.config) |
138 | | - }, |
139 | | -}) |
140 | | -``` |
141 | | - |
142 | | -## The Context Object |
143 | | - |
144 | | -`ctx` is the single argument passed to every handler, middleware, and hook: |
145 | | - |
146 | | -```typescript |
147 | | -ctx.args // Parsed & typed from this command's Zod args schema |
148 | | -ctx.config // Loaded via c12, validated & typed from the Zod schema in cli() |
149 | | -ctx.credentials // Typed from the credentials map passed to cli() |
150 | | -ctx.logger // Structured logger |
151 | | -ctx.prompts // @clack/prompts (confirm, select, text, etc.) |
152 | | -ctx.spinner // Start/stop spinner for long-running operations |
153 | | -ctx.output // Structured output (JSON, Markdown, file) |
154 | | -ctx.store // In-memory key-value store (typed) |
155 | | -ctx.errors // Redaction, sanitization utilities |
156 | | -ctx.meta // { name, version, command } — CLI metadata |
157 | | -``` |
158 | | - |
159 | | -## Subpath Exports |
160 | | - |
161 | | -| Import | What | When to use | |
162 | | -| --------------- | ------------------------------------------------------------- | ------------------------------------------------ | |
163 | | -| `kidd` | `cli`, `command`, `autoload`, `middleware`, context types | Always — this is the framework | |
164 | | -| `kidd/logger` | `createLogger` | Standalone logger outside of ctx (pino peer dep) | |
165 | | -| `kidd/config` | `loadConfig`, `createDotEnv` | Standalone c12 config loading outside of ctx | |
166 | | -| `kidd/output` | `createOutput` | Standalone output formatting outside of ctx | |
167 | | -| `kidd/errors` | `redactObject`, `sanitize`, `SENSITIVE_PATTERNS` | Standalone error utilities outside of ctx | |
168 | | -| `kidd/store` | `createStore` | Standalone store outside of ctx | |
169 | | -| `kidd/validate` | `validate`, `ValidationErrorFactory` | Standalone Zod validation outside of ctx | |
170 | | -| `kidd/project` | `findProjectRoot`, `createCredentialLoader` | Project discovery and credentials outside of ctx | |
171 | | -| `kidd/prompts` | `createPromptUtils`, `createSpinner` | Standalone prompts outside of ctx | |
172 | | - |
173 | | -## kidd-cli |
174 | | - |
175 | | -`kidd-cli` is the DX companion. It handles scaffolding, development, building, and debugging. |
176 | | - |
177 | | -```bash |
178 | | -npm install -g kidd-cli |
179 | | -``` |
180 | | - |
181 | | -| Command | Description | |
182 | | -| ------------------ | ------------------------------------------------------ | |
183 | | -| `kidd init` | Scaffold a new kidd project interactively | |
184 | | -| `kidd generate` | Generate commands and middleware with correct structure | |
185 | | -| `kidd dev` | Run in dev mode with dynamic autoloading and watch | |
186 | | -| `kidd build` | Generate manifest + bundle via tsdown | |
187 | | -| `kidd compile` | Create standalone binaries via `bun build --compile` | |
188 | | -| `kidd routes` | Print the resolved command tree | |
189 | | -| `kidd doctor` | Validate project structure and check for issues | |
190 | | - |
191 | | -### Cross-compilation Targets |
192 | | - |
193 | | -| Target | Platform | |
194 | | -| ---------------- | --------------------------- | |
195 | | -| `darwin-arm64` | macOS Apple Silicon | |
196 | | -| `darwin-x64` | macOS Intel | |
197 | | -| `linux-x64` | Linux x64 | |
198 | | -| `linux-arm64` | Linux ARM64 (Graviton, RPi) | |
199 | | -| `linux-x64-musl` | Alpine Linux | |
200 | | -| `windows-x64` | Windows x64 | |
201 | | -| `windows-arm64` | Windows ARM64 | |
202 | | - |
203 | | -## Configuration |
204 | | - |
205 | | -kidd has two config files that serve different audiences: |
206 | | - |
207 | | -| File | Who creates it | Who reads it | Purpose | |
208 | | -| ------------------ | ------------------------ | -------------------------- | ---------------------------------------------------- | |
209 | | -| `kidd.config.ts` | CLI developer (you) | `kidd` | Build entry, output, compile targets, included files | |
210 | | -| `<name>.config.ts` | CLI consumer (your user) | `cli()` at runtime via c12 | Runtime settings for the CLI, typed via Zod schema | |
211 | | - |
212 | | -## Repository Structure |
213 | | - |
214 | | -``` |
215 | | -kidd/ |
216 | | -├── packages/ |
217 | | -│ ├── kidd/ # The framework (npm: kidd) |
218 | | -│ │ ├── src/ |
219 | | -│ │ │ ├── core/ # cli(), command(), middleware(), autoloader |
220 | | -│ │ │ ├── lib/ # Subpath exports (logger, config, output, etc.) |
221 | | -│ │ │ ├── types/ # Type barrel, module augmentation, utility types |
222 | | -│ │ │ └── internal/ # Shared internal utilities |
223 | | -│ │ └── test/ |
224 | | -│ └── kidd-cli/ # The companion CLI (npm: kidd-cli) |
225 | | -│ ├── src/ |
226 | | -│ │ ├── commands/ # init, build, compile, dev, generate, doctor, routes |
227 | | -│ │ ├── manifest.ts |
228 | | -│ │ ├── bundler.ts |
229 | | -│ │ └── compiler.ts |
230 | | -│ └── test/ |
231 | | -├── apps/ |
232 | | -│ └── example/ # Example CLI (living integration test) |
233 | | -├── tooling/ |
234 | | -│ └── tsconfig/ # Shared TypeScript configs |
235 | | -├── turbo.json |
236 | | -├── pnpm-workspace.yaml |
237 | | -└── vitest.workspace.ts |
238 | | -``` |
239 | | - |
240 | | -## Dependencies |
241 | | - |
242 | | -| Package | Purpose | |
243 | | -| ---------------- | -------------------------------------- | |
244 | | -| `yargs` | Command parsing | |
245 | | -| `zod` | Schema validation | |
246 | | -| `c12` | Config loading (auto-resolves formats) | |
247 | | -| `@clack/prompts` | Interactive prompts | |
248 | | -| `picocolors` | Terminal colors | |
249 | | -| `es-toolkit` | Utility functions | |
250 | | -| `ts-pattern` | Pattern matching | |
251 | | -| `dotenv` | `.env` file loading | |
252 | | - |
253 | | -**Optional peer dependency:** `pino` >= 9.0.0 (required by `kidd/logger`) |
254 | | - |
255 | | -## Tooling |
256 | | - |
257 | | -| Tool | Role | |
258 | | -| ------------------------------------------------------ | ---------------------- | |
259 | | -| [tsdown](https://tsdown.dev/) | Library bundling | |
260 | | -| [Bun](https://bun.sh/) | Binary compilation | |
261 | | -| [Vitest](https://vitest.dev/) | Testing | |
262 | | -| [OXC](https://oxc.rs/) | Linting | |
263 | | -| [Turborepo](https://turbo.build/) | Monorepo orchestration | |
264 | | -| [Changesets](https://github.com/changesets/changesets) | Versioning + release | |
265 | | -| [pnpm](https://pnpm.io/) | Package manager | |
| 105 | +For the full guide — commands, context, middleware, config, subpath exports, and more — see the [documentation](https://kidd.dev). |
266 | 106 |
|
267 | 107 | ## Vision |
268 | 108 |
|
|
0 commit comments