outfitter 0.2.2 → 0.2.3

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/actions.d.ts

@@ -0,0 +1,2 @@
+import { outfitterActions } from "./shared/outfitter-6bkqjk86";
+export { outfitterActions };

package/dist/actions.js

@@ -0,0 +1,34 @@
+// @bun
+import {
+  outfitterActions
+} from "./shared/outfitter-fnsmx3xg.js";
+import"./shared/outfitter-9c8edfsn.js";
+import"./shared/outfitter-nmeecf1b.js";
+import"./shared/outfitter-pxt58tsq.js";
+import"./shared/outfitter-ehp18x1n.js";
+import"./shared/outfitter-1dd0k853.js";
+import"./shared/outfitter-jyxwznk1.js";
+import"./shared/outfitter-qfgj5xpq.js";
+import"./shared/outfitter-sftf1s26.js";
+import"./shared/outfitter-6a4bq054.js";
+import"./shared/outfitter-ya44h1km.js";
+import"./shared/outfitter-gp4v5gkf.js";
+import"./shared/outfitter-4s9meh3j.js";
+import"./shared/outfitter-344t1r38.js";
+import"./shared/outfitter-2np85etz.js";
+import"./shared/outfitter-q9agarmb.js";
+import"./shared/outfitter-1qwpjt6w.js";
+import"./shared/outfitter-9x1brcmq.js";
+import"./shared/outfitter-7cv5fg1m.js";
+import"./shared/outfitter-s6k8y2p4.js";
+import"./shared/outfitter-mtbpabf3.js";
+import"./shared/outfitter-6gc3g5wk.js";
+import"./shared/outfitter-7r12fj7f.js";
+import"./shared/outfitter-ara3djt0.js";
+import"./shared/outfitter-k112c427.js";
+import"./shared/outfitter-8y2dfx6n.js";
+import"./shared/outfitter-1h7k8xxt.js";
+import"./shared/outfitter-mdt37hqm.js";
+export {
+  outfitterActions
+};

package/dist/cli.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env bun
 import {
+  createRepoCommand,
   outfitterActions
-} from "./shared/chunk-sak1tt33.js";
+} from "./shared/chunk-b0y0cwkr.js";
 
 // src/cli.ts
 import { readFileSync } from "node:fs";
@@ -46,6 +47,7 @@ function createProgram() {
   })) {
     cli.register(command);
   }
+  cli.register(createRepoCommand());
   return cli;
 }
 var DEFAULT_CLI_VERSION = "0.0.0";

package/dist/commands/add.d.ts

@@ -0,0 +1,54 @@
+import { OutputMode } from "@outfitter/cli/types";
+import { Result } from "@outfitter/contracts";
+import { AddBlockResult } from "@outfitter/tooling";
+/**
+* Input for the add command.
+*/
+interface AddInput {
+	/** Block name to add */
+	readonly block: string;
+	/** Overwrite existing files */
+	readonly force: boolean;
+	/** Show what would be done without making changes */
+	readonly dryRun: boolean;
+	/** Working directory (defaults to cwd) */
+	readonly cwd?: string;
+}
+/**
+* Error returned when adding a block fails.
+*/
+declare class AddError extends Error {
+	readonly _tag: "AddError";
+	constructor(message: string);
+}
+/**
+* Runs the add command programmatically.
+*
+* @param input - Add command input
+* @returns Result with details of what was added
+*
+* @example
+* ```typescript
+* const result = await runAdd({
+*   block: "scaffolding",
+*   force: false,
+*   dryRun: false,
+* });
+*
+* if (result.isOk()) {
+*   console.log(`Created ${result.value.created.length} files`);
+* }
+* ```
+*/
+declare function runAdd(input: AddInput): Promise<Result<AddBlockResult, AddError>>;
+/**
+* Prints the results of the add command.
+*/
+declare function printAddResults(result: AddBlockResult, dryRun: boolean, options?: {
+	mode?: OutputMode;
+}): Promise<void>;
+/**
+* Lists available blocks.
+*/
+declare function listBlocks(): Result<string[], AddError>;
+export { runAdd, printAddResults, listBlocks, AddInput, AddError };

package/dist/commands/add.js

@@ -0,0 +1,16 @@
+// @bun
+import {
+  AddError,
+  listBlocks,
+  printAddResults,
+  runAdd
+} from "../shared/outfitter-s6k8y2p4.js";
+import"../shared/outfitter-mtbpabf3.js";
+import"../shared/outfitter-7r12fj7f.js";
+import"../shared/outfitter-mdt37hqm.js";
+export {
+  runAdd,
+  printAddResults,
+  listBlocks,
+  AddError
+};

package/dist/commands/check.d.ts

@@ -0,0 +1,91 @@
+import { OutputMode } from "@outfitter/cli/types";
+import { Result } from "@outfitter/contracts";
+/**
+* Options for the check command.
+*/
+interface CheckOptions {
+	/** Working directory to check. */
+	readonly cwd: string;
+	/** Show diff information for drifted files. */
+	readonly verbose?: boolean;
+	/** Check a specific block only. */
+	readonly block?: string;
+	/** Machine-oriented output for CI. */
+	readonly ci?: boolean;
+	/** Output mode override. */
+	readonly outputMode?: OutputMode;
+}
+/**
+* Information about a drifted file (included in verbose mode).
+*/
+interface DriftedFileInfo {
+	/** File path relative to project root. */
+	readonly path: string;
+	/** Reason for drift classification. */
+	readonly reason: "modified" | "missing";
+}
+/**
+* Status of a single block after comparison.
+*/
+interface BlockCheckStatus {
+	/** Block name. */
+	readonly name: string;
+	/** Comparison result. */
+	readonly status: "current" | "drifted" | "missing";
+	/** Tooling version the block was installed from. */
+	readonly installedFrom?: string;
+	/** Current tooling version providing the registry. */
+	readonly currentToolingVersion?: string;
+	/** Drifted file details (populated when verbose is true). */
+	readonly driftedFiles?: DriftedFileInfo[];
+}
+/**
+* Complete result of the check command.
+*/
+interface CheckResult {
+	/** Per-block comparison results. */
+	readonly blocks: BlockCheckStatus[];
+	/** Number of blocks checked. */
+	readonly totalChecked: number;
+	/** Number of blocks matching the registry. */
+	readonly currentCount: number;
+	/** Number of blocks with local modifications. */
+	readonly driftedCount: number;
+	/** Number of blocks with missing files. */
+	readonly missingCount: number;
+}
+/**
+* Error returned when the check command fails.
+*/
+declare class CheckError extends Error {
+	readonly _tag: "CheckError";
+	constructor(message: string);
+}
+/**
+* Runs the check command programmatically.
+*
+* Reads the manifest (or falls back to file-presence heuristic) and
+* compares each installed block against the registry.
+*
+* @param options - Check command options
+* @returns Result with per-block comparison statuses
+*
+* @example
+* ```typescript
+* const result = await runCheck({ cwd: process.cwd() });
+* if (result.isOk()) {
+*   if (result.value.driftedCount > 0) {
+*     console.log("Some blocks have drifted from the registry");
+*   }
+* }
+* ```
+*/
+declare function runCheck(options: CheckOptions): Promise<Result<CheckResult, CheckError>>;
+/**
+* Formats and outputs check results.
+*/
+declare function printCheckResults(result: CheckResult, options?: {
+	mode?: OutputMode;
+	verbose?: boolean;
+}): Promise<void>;
+export { runCheck, printCheckResults, DriftedFileInfo, CheckResult, CheckOptions, CheckError, BlockCheckStatus };

package/dist/commands/check.js

@@ -0,0 +1,14 @@
+// @bun
+import {
+  CheckError,
+  printCheckResults,
+  runCheck
+} from "../shared/outfitter-gp4v5gkf.js";
+import"../shared/outfitter-mtbpabf3.js";
+import"../shared/outfitter-7r12fj7f.js";
+import"../shared/outfitter-mdt37hqm.js";
+export {
+  runCheck,
+  printCheckResults,
+  CheckError
+};

package/dist/commands/demo.d.ts

@@ -0,0 +1,21 @@
+import { CliOutputMode } from "../shared/outfitter-a79xrm12";
+/**
+* Options for forwarding to the demo CLI.
+*/
+interface DemoOptions {
+	readonly section?: string | undefined;
+	readonly list?: boolean | undefined;
+	readonly animate?: boolean | undefined;
+	readonly outputMode: CliOutputMode;
+}
+/**
+* Result of forwarding the demo command.
+*/
+interface DemoResult {
+	readonly exitCode: number;
+}
+/**
+* Runs the demo command through available entrypoints.
+*/
+declare function runDemo(options: DemoOptions): Promise<DemoResult>;
+export { runDemo, DemoResult, DemoOptions };

package/dist/commands/demo.js

@@ -0,0 +1,8 @@
+// @bun
+import {
+  runDemo
+} from "../shared/outfitter-ya44h1km.js";
+import"../shared/outfitter-mdt37hqm.js";
+export {
+  runDemo
+};

package/dist/commands/docs-module-loader.d.ts

@@ -0,0 +1,2 @@
+import { CreateDocsCommandOptions, DocsCommandIo, DocsExportTarget, ExecuteCheckCommandOptions, ExecuteExportCommandOptions, ExecuteSyncCommandOptions, loadDocsModule } from "../shared/outfitter-dd0btgec";
+export { loadDocsModule, ExecuteSyncCommandOptions, ExecuteExportCommandOptions, ExecuteCheckCommandOptions, DocsExportTarget, DocsCommandIo, CreateDocsCommandOptions };

package/dist/commands/docs-module-loader.js

@@ -0,0 +1,8 @@
+// @bun
+import {
+  loadDocsModule
+} from "../shared/outfitter-zwyvewr1.js";
+import"../shared/outfitter-mdt37hqm.js";
+export {
+  loadDocsModule
+};