outfitter 0.2.2 → 0.2.4

package/README.md

@@ -1,6 +1,6 @@
 # outfitter
 
-Umbrella CLI for scaffolding Outfitter projects and managing development environments.
+Umbrella CLI for scaffolding Outfitter projects and managing workspace adoption.
 
 ## Installation
 
@@ -11,186 +11,285 @@ bun add -g outfitter
 Or run directly with `bunx`:
 
 ```bash
-bunx outfitter init cli my-project
+bunx outfitter --help
 ```
 
 ## Quick Start
 
 ```bash
-# Scaffold a new CLI project
-outfitter init cli my-cli
+# Scaffold a new CLI project with defaults
+bunx outfitter init my-cli --preset cli --yes
+cd my-cli
+bun install
+bun run dev
+```
 
-# Scaffold a new MCP server
-outfitter init mcp my-mcp
+## CLI Overview
 
-# Scaffold a new daemon
-outfitter init daemon my-daemon
+```text
+outfitter [--json] <command>
+```
 
-# Check your environment
-outfitter doctor
+Global options:
+
+- `--json` - Force JSON output for supported commands
+
+Top-level commands:
+
+- `init [directory]` - Create a new project from scratch (interactive or scripted)
+- `scaffold <target> [name]` - Add a new capability to an existing project
+- `add <block>` - Add a tooling block (`claude`, `biome`, `lefthook`, `bootstrap`, `scaffolding`)
+- `repo <action> <subject>` - Repository maintenance namespace (`check|sync|export`)
+- `migrate kit [directory]` - Migrate foundation imports and dependencies to `@outfitter/kit`
+- `update` - Check installed `@outfitter/*` versions and optionally show migration guidance
+- `doctor` - Validate local environment and project dependencies
+- `demo [section]` - Forward to the dedicated demo CLI (`outfitter-demo`)
+
+## Command Reference
+
+### `init`
+
+Create a new project from scratch.
+
+```bash
+outfitter init [directory] [options]
+outfitter init cli [directory] [options]
+outfitter init mcp [directory] [options]
+outfitter init daemon [directory] [options]
 ```
 
-## Commands
+Options:
+
+- `-n, --name <name>` - Package name
+- `-b, --bin <name>` - Binary name
+- `-p, --preset <preset>` - Preset (`minimal`, `cli`, `mcp`, `daemon`)
+- `-t, --template <template>` - Deprecated alias for `--preset`
+- `-s, --structure <mode>` - Project structure (`single` | `workspace`)
+- `--workspace-name <name>` - Workspace root package name
+- `--local` - Use `workspace:*` for `@outfitter/*` dependencies
+- `--workspace` - Alias for `--local`
+- `--with <blocks>` - Add specific tooling blocks
+- `--no-tooling` - Skip tooling setup
+- `-f, --force` - Overwrite existing files
+- `-y, --yes` - Skip prompts and use defaults
+- `--dry-run` - Preview changes without writing files
+- `--skip-install` - Skip `bun install`
+- `--skip-git` - Skip `git init` and initial commit
+- `--skip-commit` - Skip initial commit only
 
-### init
+Examples:
 
-Scaffolds a new Outfitter project from a template.
+```bash
+outfitter init my-lib --preset minimal --yes
+outfitter init cli my-project --yes
+outfitter init my-workspace --preset mcp --structure workspace --workspace-name @acme/root
+outfitter init . --template basic --name my-lib
+```
+
+### `scaffold`
+
+Add a target capability into an existing project/workspace.
 
 ```bash
-outfitter init <cli|mcp|daemon> [directory] [options]
-outfitter init [directory] --template <template> [options]
+outfitter scaffold <target> [name] [options]
 ```
 
-**Arguments:**
-- `directory` - Target directory (defaults to current directory)
+Options:
 
-**Options:**
-- `-n, --name <name>` - Project name (defaults to directory name)
-- `-b, --bin <name>` - Binary name (defaults to project name)
-- `-t, --template <template>` - Template to use (default: `basic`, used with `outfitter init`)
 - `-f, --force` - Overwrite existing files
+- `--skip-install` - Skip `bun install`
+- `--dry-run` - Preview changes without writing files
+- `--with <blocks>` - Add specific tooling blocks
+- `--no-tooling` - Skip default tooling blocks
+- `--local` - Use `workspace:*` for `@outfitter/*` dependencies
+
+Examples:
+
+```bash
+outfitter scaffold mcp
+outfitter scaffold lib shared-utils
+outfitter scaffold cli admin-console --with biome,lefthook
+```
 
-**Templates:**
-| Template | Description |
-|----------|-------------|
-| `basic` | Minimal TypeScript project structure |
-| `cli` | CLI application with Commander.js |
-| `mcp` | MCP server with typed tools |
-| `daemon` | Background daemon with IPC and health checks |
+### `add`
 
-**Examples:**
+Add a tooling block from the registry.
 
 ```bash
-# Create in new directory
-outfitter init cli my-project
+outfitter add <block> [options]
+outfitter add list
+```
 
-# Create with specific template
-outfitter init mcp my-mcp
+Options:
 
-# Create in current directory with custom name
-outfitter init . --name my-custom-name
+- `-f, --force` - Overwrite existing files
+- `--dry-run` - Preview without writing files
 
-# Create with a custom binary name
-outfitter init cli my-project --bin my-cli
+Examples:
 
-# Force overwrite existing files
-outfitter init my-project --force
+```bash
+outfitter add scaffolding
+outfitter add biome --dry-run
+outfitter add list
 ```
 
-### doctor
+### `repo`
 
-Validates your environment and project dependencies.
+Canonical namespace for repository maintenance workflows.
 
 ```bash
-outfitter doctor
+outfitter repo check <subject> [options]
+outfitter repo sync <subject> [options]
+outfitter repo export <subject> [options]
 ```
 
-Performs the following checks:
-- **Bun Version** - Ensures Bun >= 1.3.6 is installed
-- **package.json** - Validates required fields (name, version)
-- **Dependencies** - Checks if node_modules is present and complete
-- **tsconfig.json** - Verifies TypeScript configuration exists
-- **src/ directory** - Confirms source directory structure
+Current subjects:
+
+- `check docs` - Validate generated package docs are up to date
+- `sync docs` - Generate package docs into `docs/packages`
+- `export docs` - Export package and LLM docs artifacts
+- `check exports` - Validate package export maps
+- `check readme` - Validate README import examples
+- `check registry` - Validate bunup workspace registration
+- `check changeset` - Validate required changesets for package changes
+- `check tree` - Assert no modified/untracked files
+- `check boundary-invocations` - Disallow direct `packages/*/src` execution from root/app scripts
 
-**Example output:**
+Examples:
 
+```bash
+outfitter repo check docs --cwd .
+outfitter repo sync docs --cwd .
+outfitter repo export docs --target llms
+outfitter repo check exports --json
+outfitter repo check readme
 ```
-Outfitter Doctor
 
-==================================================
-[PASS] Bun Version: 1.3.6 (requires 1.3.6)
-[PASS] package.json
-       my-project@0.1.0-rc.0
-[PASS] Dependencies
-       12 dependencies installed
-[PASS] tsconfig.json
-[PASS] src/ directory
+### `migrate kit`
+
+Codemod for kit-first foundation adoption.
 
-==================================================
-5/5 checks passed
+```bash
+outfitter migrate kit [directory] [options]
 ```
 
-## Template Variables
+Options:
 
-Templates use placeholder syntax for project-specific values:
+- `--dry-run` - Preview changes without writing files
 
-| Placeholder | Description | Default |
-|-------------|-------------|---------|
-| `{{name}}` | Project name (legacy) | Directory name |
-| `{{projectName}}` | Project name | Directory name |
-| `{{binName}}` | Binary name | Project name |
-| `{{version}}` | Initial version | `0.1.0-rc.0` |
-| `{{description}}` | Project description | Generic description |
+Examples:
 
-Files ending in `.template` have their extension removed after processing (e.g., `package.json.template` becomes `package.json`).
+```bash
+outfitter migrate kit --dry-run
+outfitter migrate kit .
+```
 
-## Programmatic API
+### `update`
 
-The CLI commands are also available as a programmatic API:
+Check installed `@outfitter/*` packages against npm versions.
 
-```typescript
-import { runInit, runDoctor } from "outfitter";
+```bash
+outfitter update [options]
+```
 
-// Initialize a project programmatically
-const initResult = await runInit({
-  targetDir: "./my-project",
-  name: "my-project",
-  template: "cli",
-  force: false,
-});
+Options:
 
-if (initResult.isErr()) {
-  console.error("Failed:", initResult.error.message);
-}
+- `--guide` - Include composed migration guidance
+- `--cwd <path>` - Working directory to inspect
 
-// Run doctor checks programmatically
-const doctorResult = await runDoctor({ cwd: process.cwd() });
+Examples:
 
-if (doctorResult.exitCode === 0) {
-  console.log("All checks passed!");
-} else {
-  console.log(`${doctorResult.summary.failed} checks failed`);
-}
+```bash
+outfitter update
+outfitter update --guide
+outfitter update --json --cwd .
+```
+
+### `doctor`
+
+Validate local environment and project structure.
+
+```bash
+outfitter doctor
 ```
 
-### API Types
+### `demo`
+
+Compatibility bridge to the dedicated demo CLI.
+
+```bash
+outfitter demo [section] [options]
+```
+
+Options:
+
+- `-l, --list` - List available sections
+- `-a, --animate` - Run animated spinner demo
+
+Use `outfitter-demo` (or `cli-demo`) directly for the dedicated demo app.
+
+## Command Conventions
+
+Canonical boundary and command conventions are documented in
+[`docs/BOUNDARY-CONVENTIONS.md`](../../docs/BOUNDARY-CONVENTIONS.md).
+
+Quick model status:
+
+- `init`, `add`, `check`: implemented user-facing verbs
+- `setup`, `fix`, user-facing `docs`: planned convergence verbs
+- `repo check|sync|export`: canonical maintenance namespace
+
+## Programmatic API
+
+Root exports:
 
 ```typescript
-interface InitOptions {
-  readonly targetDir: string;
-  readonly name: string | undefined;
-  readonly template: string | undefined;
-  readonly force: boolean;
-}
+import {
+  runDoctor,
+  runInit,
+  runMigrateKit,
+  runScaffold,
+  type InitOptions,
+  type MigrateKitOptions,
+  type ScaffoldOptions,
+} from "outfitter";
+```
 
-interface DoctorOptions {
-  readonly cwd: string;
-}
+Command subpath exports:
+
+```typescript
+import { runAdd } from "outfitter/commands/add";
+import { runUpdate } from "outfitter/commands/update";
+```
+
+Example:
+
+```typescript
+import { runInit } from "outfitter";
+
+const result = await runInit({
+  targetDir: "./my-app",
+  preset: "cli",
+  force: false,
+  yes: true,
+});
 
-interface DoctorResult {
-  readonly checks: {
-    readonly bunVersion: BunVersionCheck;
-    readonly packageJson: PackageJsonCheck;
-    readonly dependencies: DependenciesCheck;
-    readonly configFiles: ConfigFilesCheck;
-    readonly directories: DirectoriesCheck;
-  };
-  readonly summary: DoctorSummary;
-  readonly exitCode: number;
+if (result.isErr()) {
+  console.error(result.error.message);
 }
 ```
 
 ## Requirements
 
-- Bun >= 1.3.6
+- Bun >= 1.3.7
 
 ## Related Packages
 
-- `@outfitter/cli` - CLI framework for building command-line tools
+- `@outfitter/cli` - CLI framework primitives
+- `@outfitter/contracts` - Result and error contracts
 - `@outfitter/mcp` - MCP server framework
-- `@outfitter/daemon` - Daemon lifecycle management
-- `@outfitter/config` - Configuration loading
-- `@outfitter/contracts` - Result types and error patterns
+- `@outfitter/tooling` - Tooling presets and verification CLI
+- `outfitter-cli-demo` - Dedicated CLI/TUI demo app
 
 ## License
 

package/dist/cli.js

@@ -1,13 +1,14 @@
 #!/usr/bin/env bun
 import {
+  createRepoCommand,
   outfitterActions
-} from "./shared/chunk-sak1tt33.js";
+} from "./shared/chunk-tpwtpa74.js";
 
 // src/cli.ts
 import { readFileSync } from "node:fs";
+import { exitWithError } from "@outfitter/cli";
 import { buildCliCommands } from "@outfitter/cli/actions";
 import { createCLI } from "@outfitter/cli/command";
-import { exitWithError } from "@outfitter/cli/output";
 import { createContext, generateRequestId } from "@outfitter/contracts";
 import { createOutfitterLoggerFactory } from "@outfitter/logging";
 function createProgram() {
@@ -46,6 +47,7 @@ function createProgram() {
   })) {
     cli.register(command);
   }
+  cli.register(createRepoCommand());
   return cli;
 }
 var DEFAULT_CLI_VERSION = "0.0.0";