@samveys/console

# createKernel Function

Creates a new Samveys CLI kernel.

function createKernel(options?: KernelOptions): Kernel;

Exported from packages/console/src/kernel.ts

# createOutput Function

Creates an agent-aware Output implementation.

function createOutput(options?: CreateOutputOptions): OutputInstance;

Exported from packages/console/src/output.ts

# defineCommand Function

Defines a CLI command with type-safe arguments and flags.

function defineCommand<const F extends FlagsShape = FlagsShape>(name: string, definition: CommandDefinition<F>): Command<F>;

Exported from packages/console/src/command.ts

# defineRecipe Function

Declares a recipe for `svs add`. Packages export it as the default export of a `./recipe` subpath. The recipe is validated here, so a bad recipe fails when it is loaded, not halfway through writing files.

function defineRecipe(recipe: Omit<Recipe, 'kind'>): Recipe;

Exported from packages/console/src/recipes/define.ts

# detectAgent Function

Detects whether the current process is running inside an AI coding agent environment.

function detectAgent(env?: Readonly<Record<string, string | undefined>>, stdout?: {

Exported from packages/console/src/output.ts

# findConfigFile Function

Searches for `samveys.config.ts` by walking up from the specified directory.

function findConfigFile(cwd: string): string | undefined;

Exported from packages/console/src/project.ts

# loadProject Function

Loads the project configuration from disk or via the provided loader.

function loadProject(options?: {

Exported from packages/console/src/project.ts

# parseArgv Function

Parses argv against a command definition, handling flags, global flags, and arguments.

function parseArgv<const F extends FlagsShape = FlagsShape>(definition: ArgvDefinition<F>, argv: readonly string[]): ParsedArgv<F>;

Exported from packages/console/src/args.ts

# upgradeProject Function

Plans (and with `write`, applies) the upgrade of every `@samveys/*` dependency to `target` (`2.0.0`, or a per-package map). Only codemods whose `from` lies in [current major, target major) run, in major order, so 1 → 3 applies the 1→2 then the 2→3 codemods.

function upgradeProject(root: string, target: string | Readonly<Record<string, string>>, write: boolean): Promise<UpgradePlan>;

Exported from packages/console/src/upgrade.ts

# ArgDefinition Interface

No documentation comment.

interface ArgDefinition {
    readonly name: string;
    readonly description: string;
    readonly required?: boolean;
    /** Collects the remaining positionals. Only the last argument may be variadic. */
    readonly variadic?: boolean;
}

Exported from packages/console/src/contracts.ts

# Codemod Interface

No documentation comment.

interface Codemod {
    /** Stable id, e.g. `http-2-route-options`. */
    readonly name: string;
    readonly description: string;
    /** The package major this upgrades FROM, e.g. 1 for 1.x → 2.x. */
    readonly from: number;
    transform(source: string, file: string): string | undefined;
}

Exported from packages/console/src/upgrade.ts

# Command Interface

No documentation comment.

interface Command<F extends FlagsShape = FlagsShape> extends CommandLike {
    readonly kind: 'command';
    /** `report:daily`; lowercase, `[a-z0-9-]+(:[a-z0-9-]+)*`. */
    readonly name: string;
    readonly definition: CommandDefinition<F>;
}

Exported from packages/console/src/contracts.ts

# CommandContext Interface

No documentation comment.

interface CommandContext<F extends FlagsShape = FlagsShape> {
    readonly args: Readonly<Record<string, string | string[] | undefined>>;
    readonly flags: InferFlags<F> & GlobalFlags;
    readonly argv: readonly string[];
    readonly output: Output;
    readonly cwd: string;
    /** Boots the app from `samveys.config.ts` (register + boot only). Cached per run. */
    app(): Promise<AppContext>;
    /** Asks a yes/no question (`KernelOptions.confirm`, else stdin when it is a TTY, else no). */
    confirm(question: string): Promise<boolean>;
  …

interface CommandContext<F extends FlagsShape = FlagsShape> {
    readonly args: Readonly<Record<string, string | string[] | undefined>>;
    readonly flags: InferFlags<F> & GlobalFlags;
    readonly argv: readonly string[];
    readonly output: Output;
    readonly cwd: string;
    /** Boots the app from `samveys.config.ts` (register + boot only). Cached per run. */
    app(): Promise<AppContext>;
    /** Asks a yes/no question (`KernelOptions.confirm`, else stdin when it is a TTY, else no). */
    confirm(question: string): Promise<boolean>;
    /** Environment of the run (`KernelOptions.env`, else `process.env`). */
    readonly env: Readonly<Record<string, string | undefined>>;
}

Exported from packages/console/src/contracts.ts

# CommandDefinition Interface

No documentation comment.

interface CommandDefinition<F extends FlagsShape = FlagsShape> {
    readonly description: string;
    readonly args?: readonly ArgDefinition[];
    readonly flags?: F;
    /** Hidden from `svs --help`. */
    readonly hidden?: boolean;
    /** Exit code; `undefined` means 0. */
    run(context: CommandContext<F>): void | number | Promise<void | number>;
}

Exported from packages/console/src/contracts.ts

# CreateOutputOptions Interface

No documentation comment.

interface CreateOutputOptions {
    readonly json?: boolean;
    readonly agent?: boolean;
    readonly color?: boolean;
    readonly stdout?: {
        write(chunk: string): unknown;
        readonly isTTY?: boolean;
    };
    readonly stderr?: {
        write(chunk: string): unknown;
  …

interface CreateOutputOptions {
    readonly json?: boolean;
    readonly agent?: boolean;
    readonly color?: boolean;
    readonly stdout?: {
        write(chunk: string): unknown;
        readonly isTTY?: boolean;
    };
    readonly stderr?: {
        write(chunk: string): unknown;
    };
    readonly env?: Readonly<Record<string, string | undefined>>;
}

Exported from packages/console/src/output.ts

# FlagDefinition Interface

No documentation comment.

interface FlagDefinition<T extends FlagType = FlagType> {
    readonly type: T;
    readonly description: string;
    readonly short?: string;
    readonly default?: FlagValue<T>;
    readonly multiple?: boolean;
}

Exported from packages/console/src/contracts.ts

# GlobalFlags Interface

Global flags every command accepts.

interface GlobalFlags {
    /** Print one JSON document on stdout instead of human output. */
    readonly json: boolean;
    readonly help: boolean;
    /** Disable colors. Also set by `NO_COLOR` and when stdout is not a TTY. */
    readonly noColor: boolean;
}

Exported from packages/console/src/contracts.ts

# Kernel Interface

No documentation comment.

interface Kernel {
    register(command: Lazy<Command>): void;
    commands(): Promise<readonly Command[]>;
    /** Parses argv (without node and script), runs the command, returns the exit code. Never calls process.exit. */
    run(argv: readonly string[]): Promise<number>;
}

Exported from packages/console/src/contracts.ts

# KernelOptions Interface

No documentation comment.

interface KernelOptions {
    readonly cwd?: string;
    readonly env?: Readonly<Record<string, string | undefined>>;
    readonly stdout?: {
        write(chunk: string): unknown;
        readonly isTTY?: boolean;
    };
    readonly stderr?: {
        write(chunk: string): unknown;
    };
    /** Override project loading (tests). */
    readonly loadConfig?: () => Promise<SamveysConfig | undefined>;

Exported from packages/console/src/contracts.ts

# LoadedProject Interface

No documentation comment.

interface LoadedProject {
    readonly config: SamveysConfig;
    readonly rootDir: string;
}

Exported from packages/console/src/project.ts

# Output Interface

No documentation comment.

interface Output {
    /** True when an AI coding agent is detected: output is condensed, no colors, no spinners. */
    readonly agent: boolean;
    readonly json: boolean;
    readonly color: boolean;
    /** Human line; suppressed in `--json` mode. */
    line(text?: string): void;
    /** Human table; suppressed in `--json` mode. Condensed to `key=value` lines for agents. */
    table(rows: readonly Readonly<Record<string, unknown>>[], columns?: readonly string[]): void;
    success(text: string): void;
  …

interface Output {
    /** True when an AI coding agent is detected: output is condensed, no colors, no spinners. */
    readonly agent: boolean;
    readonly json: boolean;
    readonly color: boolean;
    /** Human line; suppressed in `--json` mode. */
    line(text?: string): void;
    /** Human table; suppressed in `--json` mode. Condensed to `key=value` lines for agents. */
    table(rows: readonly Readonly<Record<string, unknown>>[], columns?: readonly string[]): void;
    success(text: string): void;
    warn(text: string): void;
    /** Always on stderr. */
    error(text: string): void;
    /** The single JSON result printed in `--json` mode. Last call wins; printed once when the command ends. */
    result(data: unknown): void;
}

Exported from packages/console/src/contracts.ts

# OutputInstance Interface

No documentation comment.

interface OutputInstance extends Output {
    /** Prints the single JSON result in --json mode. */
    flush(): void;
}

Exported from packages/console/src/output.ts

# ParsedArgv Interface

No documentation comment.

interface ParsedArgv<F extends FlagsShape = FlagsShape> {
    readonly args: Readonly<Record<string, string | string[] | undefined>>;
    readonly flags: InferFlags<F> & GlobalFlags;
    readonly positionals: readonly string[];
}

Exported from packages/console/src/args.ts

# PlannedChange Interface

One file change planned by `svs add`; nothing is written until the plan is confirmed.

interface PlannedChange {
    readonly path: string;
    readonly action: 'create' | 'update';
    readonly before: string | undefined;
    readonly after: string;
}

Exported from packages/console/src/contracts.ts

# Recipe Interface

No documentation comment.

interface Recipe {
    readonly kind: 'recipe';
    /** The package the recipe belongs to, e.g. `@samveys/http`. */
    readonly package: string;
    /** Packages installed as dependencies, defaulting to `[package]`. */
    readonly dependencies?: readonly string[];
    readonly devDependencies?: readonly string[];
    readonly imports?: readonly RecipeImport[];
    /** Expressions appended to `plugins: [...]` in `samveys.config.ts`, e.g. `http()`. */
    readonly plugins?: readonly string[];
  …

interface Recipe {
    readonly kind: 'recipe';
    /** The package the recipe belongs to, e.g. `@samveys/http`. */
    readonly package: string;
    /** Packages installed as dependencies, defaulting to `[package]`. */
    readonly dependencies?: readonly string[];
    readonly devDependencies?: readonly string[];
    readonly imports?: readonly RecipeImport[];
    /** Expressions appended to `plugins: [...]` in `samveys.config.ts`, e.g. `http()`. */
    readonly plugins?: readonly string[];
    /** Created when missing; an existing file with other content stops the recipe (SVS_E064). */
    readonly files?: readonly RecipeFile[];
    readonly env?: readonly RecipeEnvKey[];
    /** Printed after a successful apply. */
    readonly nextSteps?: readonly string[];
}

Exported from packages/console/src/contracts.ts

# RecipeEnvKey Interface

No documentation comment.

interface RecipeEnvKey {
    readonly key: string;
    /** Written to `.env.example`. Never a real secret. */
    readonly example: string;
    /** One-line comment written above the key. */
    readonly comment?: string;
}

Exported from packages/console/src/contracts.ts

# RecipeFile Interface

No documentation comment.

interface RecipeFile {
    /** Path relative to the project root, e.g. `config/http.ts`. Must stay inside the project. */
    readonly path: string;
    readonly content: string;
}

Exported from packages/console/src/contracts.ts

# RecipeImport Interface

An import to add to `samveys.config.ts`. Skipped when the same specifier is already imported.

interface RecipeImport {
    /** Named bindings, e.g. `['http']`. */
    readonly names: readonly string[];
    readonly from: string;
}

Exported from packages/console/src/contracts.ts

# RecipePlan Interface

No documentation comment.

interface RecipePlan {
    readonly recipe: Recipe;
    readonly packageManager: PackageManager;
    /** The install command, or `undefined` when every dependency is already declared. */
    readonly install: {
        readonly command: string;
        readonly args: readonly string[];
    } | undefined;
    readonly changes: readonly PlannedChange[];
}

Exported from packages/console/src/contracts.ts

# UpgradeChange Interface

No documentation comment.

interface UpgradeChange {
    readonly file: string;
    readonly codemods: readonly string[];
}

Exported from packages/console/src/upgrade.ts

# UpgradePlan Interface

No documentation comment.

interface UpgradePlan {
    readonly packages: readonly {
        readonly name: string;
        readonly from: string;
        readonly to: string;
        readonly codemods: readonly string[];
    }[];
    readonly changes: readonly UpgradeChange[];
}

Exported from packages/console/src/upgrade.ts

# FlagsShape Type

No documentation comment.

type FlagsShape = Readonly<Record<string, FlagDefinition>>;

Exported from packages/console/src/contracts.ts

# FlagType Type

Locked public contracts of `@samveys/console` (design §10).

type FlagType = 'string' | 'boolean' | 'number';

Exported from packages/console/src/contracts.ts

# FlagValue Type

No documentation comment.

type FlagValue<T extends FlagType> = T extends 'string' ? string : T extends 'boolean' ? boolean : number;

Exported from packages/console/src/contracts.ts

# InferFlags Type

No documentation comment.

type InferFlags<F extends FlagsShape> = {
    readonly [K in keyof F]: F[K] extends FlagDefinition<infer T> ? F[K] extends {
        readonly multiple: true;
    } ? FlagValue<T>[] : F[K] extends {
        readonly default: unknown;
    } ? FlagValue<T> : FlagValue<T> | undefined : never;
};

Exported from packages/console/src/contracts.ts

# PackageManager Type

No documentation comment.

type PackageManager = 'pnpm' | 'npm' | 'yarn' | 'bun';

Exported from packages/console/src/contracts.ts