create-cogitator-app 0.4.0 → 0.5.0

package/dist/lib.d.ts

@@ -1,127 +1,839 @@
-type Template = 'basic' | 'memory' | 'swarm' | 'workflow' | 'api-server' | 'nextjs';
-type LLMProvider = 'ollama' | 'openai' | 'anthropic' | 'google';
-type PackageManager = 'pnpm' | 'npm' | 'yarn' | 'bun';
-interface ProjectOptions {
+import { z } from 'zod';
+import { ModelRegistry, ModelInfo } from '@cogitator-ai/models';
+
+declare const PROVIDERS: readonly ["ollama", "openai", "anthropic", "google"];
+declare const APP_KINDS: readonly ["script", "server", "next", "channels", "worker"];
+declare const SERVERS: readonly ["express", "fastify", "hono", "koa", "tetsu"];
+declare const MEMORIES: readonly ["none", "memory", "sqlite", "postgres", "redis", "mongodb"];
+declare const VECTOR_STORES: readonly ["memory", "postgres", "qdrant"];
+declare const FEATURES: readonly ["harness", "mcp", "rag", "workflows", "durable", "swarms", "evals", "otel", "langfuse", "voice", "sandbox", "a2a"];
+declare const DEPLOY_TARGETS: readonly ["none", "docker", "fly"];
+declare const CODING_AGENTS: readonly ["claude", "cursor", "codex"];
+declare const PACKAGE_MANAGERS: readonly ["pnpm", "npm", "yarn", "bun"];
+declare const CHANNELS: readonly ["telegram", "discord", "slack", "webchat"];
+type LLMProvider = (typeof PROVIDERS)[number];
+type AppKind = (typeof APP_KINDS)[number];
+type ServerFramework = (typeof SERVERS)[number];
+type MemoryKind = (typeof MEMORIES)[number];
+type VectorStore = (typeof VECTOR_STORES)[number];
+type FeatureId = (typeof FEATURES)[number];
+type DeployTarget = (typeof DEPLOY_TARGETS)[number];
+type CodingAgent = (typeof CODING_AGENTS)[number];
+type PackageManager = (typeof PACKAGE_MANAGERS)[number];
+type ChannelKind = (typeof CHANNELS)[number];
+/**
+ * Why `name` cannot be the generated package's name, or `undefined` when it can.
+ * The name lands in package.json and in generated code, so it has to be a valid
+ * unscoped npm package name.
+ */
+declare function validateProjectName(name: string): string | undefined;
+/**
+ * Everything that decides what a generated project contains. A spec is plain data:
+ * it is stored in the project's package.json (`cogitator.spec`) so the project can
+ * be regenerated and extended with `cogitator add`, and it never holds secrets.
+ */
+declare const ProjectSpecSchema: z.ZodObject<{
+    name: z.ZodString;
+    preset: z.ZodOptional<z.ZodString>;
+    app: z.ZodEnum<{
+        script: "script";
+        server: "server";
+        next: "next";
+        channels: "channels";
+        worker: "worker";
+    }>;
+    server: z.ZodOptional<z.ZodEnum<{
+        express: "express";
+        fastify: "fastify";
+        hono: "hono";
+        koa: "koa";
+        tetsu: "tetsu";
+    }>>;
+    channels: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        telegram: "telegram";
+        discord: "discord";
+        slack: "slack";
+        webchat: "webchat";
+    }>>>;
+    memory: z.ZodEnum<{
+        none: "none";
+        memory: "memory";
+        sqlite: "sqlite";
+        postgres: "postgres";
+        redis: "redis";
+        mongodb: "mongodb";
+    }>;
+    vectorStore: z.ZodDefault<z.ZodEnum<{
+        memory: "memory";
+        postgres: "postgres";
+        qdrant: "qdrant";
+    }>>;
+    features: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        harness: "harness";
+        mcp: "mcp";
+        rag: "rag";
+        workflows: "workflows";
+        durable: "durable";
+        swarms: "swarms";
+        evals: "evals";
+        otel: "otel";
+        langfuse: "langfuse";
+        voice: "voice";
+        sandbox: "sandbox";
+        a2a: "a2a";
+    }>>>;
+    provider: z.ZodEnum<{
+        ollama: "ollama";
+        openai: "openai";
+        anthropic: "anthropic";
+        google: "google";
+    }>;
+    model: z.ZodString;
+    deploy: z.ZodDefault<z.ZodEnum<{
+        none: "none";
+        docker: "docker";
+        fly: "fly";
+    }>>;
+    compose: z.ZodDefault<z.ZodBoolean>;
+    packageManager: z.ZodEnum<{
+        pnpm: "pnpm";
+        npm: "npm";
+        yarn: "yarn";
+        bun: "bun";
+    }>;
+    codingAgents: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        claude: "claude";
+        cursor: "cursor";
+        codex: "codex";
+    }>>>;
+}, z.core.$strict>;
+type ProjectSpec = z.output<typeof ProjectSpecSchema>;
+type ProjectSpecInput = z.input<typeof ProjectSpecSchema>;
+/**
+ * Parses and normalizes a spec: lists are deduplicated and sorted the way the
+ * catalogs list them, so two specs that mean the same project are equal.
+ */
+declare function parseSpec(input: unknown): ProjectSpec;
+/** The model as the runtime addresses it: `provider/model`. */
+declare function qualifiedModel(spec: Pick<ProjectSpec, 'provider' | 'model'>): string;
+/** The model without the provider prefix, as provider APIs and `ollama pull` name it. */
+declare function bareModel(spec: Pick<ProjectSpec, 'provider' | 'model'>): string;
+
+/** A variable the generated project reads from its environment. */
+interface EnvVar {
     name: string;
-    path: string;
-    template: Template;
-    provider: LLMProvider;
+    /** One line for `.env.example` and the env schema. */
+    description: string;
+    /** The value `.env.example` shows; secrets show an empty value. */
+    example?: string;
+    /** Whether the project refuses to start without it. */
+    required: boolean;
+    /** Whether it is a credential: never logged, kept out of `.env.example` values. */
+    secret: boolean;
     /**
-     * The model the agents use, without the provider prefix (`qwen3.5:9b`, `gpt-6.1-sol`).
-     * Defaults to the provider's entry in `defaultModels`.
+     * Whether a deployment must provide it, listed in `cogitator.yml` as a
+     * `deploy.secrets` entry. Defaults to secrets the project requires.
      */
-    model?: string;
-    packageManager: PackageManager;
-    docker: boolean;
-    git: boolean;
-    /** Run `<packageManager> install` after writing the files (default `true`). */
-    install?: boolean;
+    deploy?: boolean;
 }
-/** How an optional step of `scaffold()` went. */
-type ScaffoldStep = {
+/** A command that takes the project to its first run, with an optional explanation. */
+interface NextStep {
+    command: string;
+    note?: string;
+}
+interface GeneratedFile {
+    path: string;
+    /** Mutable until the plan is done, so a final pass can adapt every file. */
+    content: string;
+    /** File mode for `chmod`, used for `.env` (0600) and executable scripts. */
+    mode?: number;
+}
+
+/** What is already done when the next steps are shown. */
+interface SetupState {
+    /** Where the project is relative to the user's shell; no `cd` step when absent. */
+    directory?: string;
+    installed: boolean;
+    /** Whether the provider key was written to `.env`. */
+    keyWritten: boolean;
+    /** Whether the Ollama model is known to be pulled. */
+    modelReady: boolean;
+}
+
+interface PlanOptions {
+    /** Values for `.env`, such as the provider key. Never written anywhere else. */
+    secrets?: Record<string, string>;
+    /** `name@version` of the package manager, written to package.json's `packageManager`. */
+    packageManagerSpec?: string;
+}
+/** Everything a project consists of, computed without touching the disk. */
+interface ProjectPlan {
+    spec: ProjectSpec;
+    files: GeneratedFile[];
+    dependencies: Record<string, string>;
+    devDependencies: Record<string, string>;
+    scripts: Record<string, string>;
+    env: EnvVar[];
+    /** Compose services the project starts locally. */
+    services: string[];
+    warnings: string[];
+    /** The command that creates this project again. */
+    command: string;
+    /** The steps to the first run, before anything is installed. */
+    nextSteps(state: SetupState): NextStep[];
+}
+/** What package.json records under `cogitator` so `cogitator add` can grow the project. */
+interface ScaffoldManifest {
+    generator: string;
+    spec: ProjectSpec;
+    command: string;
+}
+declare const MANIFEST_KEY = "cogitator";
+/**
+ * The project `spec` describes. Throws when the spec is invalid or its parts do
+ * not fit together, before anything is generated.
+ */
+declare function planProject(input: unknown, options?: PlanOptions): ProjectPlan;
+
+/**
+ * Where the scaffolder reports progress. The CLI shows it with spinners, the
+ * programmatic API stays silent unless a logger is passed.
+ */
+interface ScaffoldLogger {
+    start(message: string): void;
+    done(message: string): void;
+    fail(message: string): void;
+    warn(message: string): void;
+}
+declare const silentLogger: ScaffoldLogger;
+/** How an optional step went. */
+type StepResult = {
     status: 'done';
 } | {
     status: 'skipped';
+    reason: string;
 } | {
     status: 'failed';
     error: Error;
 };
-/** What `scaffold()` did: the project is written even when a later step failed. */
+interface ScaffoldOptions extends PlanOptions {
+    /** The directory to create the project in. It must not exist or be empty. */
+    directory: string;
+    /** Run the package manager's install (default `true`). */
+    install?: boolean;
+    /** Initialize a git repository and commit the project (default `true`). */
+    git?: boolean;
+    log?: ScaffoldLogger;
+    /** Show the install's output live instead of capturing it. */
+    inheritOutput?: boolean;
+}
 interface ScaffoldResult {
-    /** The generated files, relative to the project directory. */
+    plan: ProjectPlan;
+    directory: string;
+    /** The generated files, relative to `directory`. */
     files: string[];
-    /** `<packageManager> install`, skipped with `install: false`. */
-    install: ScaffoldStep;
-    /** `git init` and the first commit, skipped with `git: false` or when git is not installed. */
-    git: ScaffoldStep;
+    install: StepResult;
+    format: StepResult;
+    git: StepResult;
+    /** The workspace root above the project, when it was created inside one. */
+    parentWorkspace?: string;
+}
+/** Hashes of the files the scaffolder wrote, so `cogitator add` can tell them from files the user edited. */
+interface ScaffoldLock {
+    version: 1;
+    generator: string;
+    files: Record<string, string>;
 }
-interface TemplateFile {
+declare const LOCK_PATH = ".cogitator/scaffold.json";
+declare function hashContent(content: string): string;
+declare function writeFiles(directory: string, files: readonly GeneratedFile[]): Promise<void>;
+declare function writeLock(directory: string, paths: readonly string[]): Promise<void>;
+/**
+ * Re-hashes `paths` in the lock after `cogitator add` wrote or deleted them,
+ * keeping the hashes of every other file.
+ */
+declare function updateLock(directory: string, paths: readonly string[]): Promise<void>;
+declare function readLock(directory: string): ScaffoldLock | undefined;
+/**
+ * Formats the generated code with the project's own Biome, so it starts clean
+ * under `lint`: the whole project, or only `paths` when they are given.
+ */
+declare function formatProject(directory: string, paths?: readonly string[]): Promise<StepResult>;
+/**
+ * Creates the project `spec` describes in `options.directory`, then installs
+ * its dependencies, formats it and commits it to a new git repository. Throws
+ * when the spec is invalid or the directory is taken. A failed install, format
+ * or git step does not throw: the result reports it and the project stays.
+ */
+declare function scaffold(spec: unknown, options: ScaffoldOptions): Promise<ScaffoldResult>;
+
+/** What `cogitator add` brings into a project. Lists are added to, the rest replaced. */
+interface AddChanges {
+    features?: readonly FeatureId[];
+    channels?: readonly ChannelKind[];
+    codingAgents?: readonly CodingAgent[];
+    memory?: MemoryKind;
+    vectorStore?: VectorStore;
+    deploy?: DeployTarget;
+}
+/** A file `cogitator add` writes or removes, with the diff against what is on disk. */
+interface FileChange {
     path: string;
-    content: string;
+    kind: 'create' | 'update' | 'delete';
+    /** The new content, absent for a deletion. */
+    content?: string;
+    /** How the content came about: generated as a whole, or merged into the user's copy. */
+    source: 'generated' | 'merged';
+    diff: string;
 }
-interface TemplateGenerator {
-    /**
-     * The path the generated app answers health checks on, written to
-     * cogitator.yml as `deploy.health.path` so `cogitator deploy` probes it.
-     * Absent for templates that run as scripts rather than servers.
-     */
-    healthPath?: string;
-    /**
-     * The memory adapter the generated code configures, written to cogitator.yml so
-     * `cogitator deploy` provisions the services it needs. Absent when it keeps none.
-     */
-    memoryAdapter?: 'memory' | 'redis';
-    /**
-     * Environment variables the deployed app needs besides the provider key, written
-     * to cogitator.yml as `deploy.secrets` together with that key.
-     */
-    secrets?: string[];
-    files(options: ProjectOptions): TemplateFile[];
-    dependencies(): Record<string, string>;
-    devDependencies(): Record<string, string>;
-    scripts(): Record<string, string>;
+/** Something the addition left as it is on purpose. */
+interface AddNote {
+    message: string;
+    path?: string;
+    /** The change that was not applied, when there is one. */
+    diff?: string;
+}
+/** A file the user changed in a way the addition cannot be merged into. */
+interface AddConflict {
+    path: string;
+    reason: string;
+    /** The change the addition needs to make to the file as generated. */
+    diff: string;
+}
+interface AddPlan {
+    directory: string;
+    from: ProjectSpec;
+    to: ProjectSpec;
+    /** What changes in the spec, one item per line: `feature rag`, `memory sqlite -> postgres`. */
+    summary: string[];
+    changes: FileChange[];
+    conflicts: AddConflict[];
+    /** What was left as it is on purpose, and why. */
+    notes: AddNote[];
+    /** Dependencies the project gains or whose version changes. */
+    dependencies: Record<string, string>;
+    devDependencies: Record<string, string>;
+    /** Dependencies and dev dependencies the merged package.json no longer lists. */
+    removedDependencies: string[];
+    /** Environment variables the project starts reading. */
+    env: EnvVar[];
+    /** Compose services the project starts using. */
+    services: string[];
+    warnings: string[];
+    /** The command that creates the project as it is after the addition. */
+    command: string;
+    /** Whether the project already has everything asked for. */
+    upToDate: boolean;
+}
+interface AddOptions {
+    /** Install when the dependencies change (default `true`). */
+    install?: boolean;
+    log?: ScaffoldLogger;
+    /** Show the install's output live instead of capturing it. */
+    inheritOutput?: boolean;
+}
+interface AddResult {
+    plan: AddPlan;
+    /** Files written, relative to the project. */
+    written: string[];
+    deleted: string[];
+    install: StepResult;
+    format: StepResult;
+}
+/** Thrown when the project is not one the scaffolder generated, so its parts are unknown. */
+declare class NotAScaffoldedProjectError extends Error {
+    constructor(message: string);
+}
+/** Thrown when an addition would overwrite changes the user made. Nothing is written. */
+declare class AddConflictError extends Error {
+    readonly conflicts: AddConflict[];
+    constructor(conflicts: AddConflict[]);
 }
+/**
+ * Whether the addition changes what the project depends on, in either
+ * direction: the lockfile and the installed tree need an install either way.
+ */
+declare function changesDependencies(plan: AddPlan): boolean;
+/**
+ * What adding `changes` to the project in `directory` would do, without
+ * writing anything. The project's spec is read from package.json, both the
+ * project as it is and as it would be are planned, and what the addition
+ * changes between them is merged into the files on disk. A file the user
+ * edited takes the change when it can be merged key by key (package.json,
+ * cogitator.yml, docker-compose.yml, the managed block of AGENTS.md,
+ * .gitignore), and is a conflict otherwise.
+ */
+declare function planAdd(directory: string, changes: AddChanges): AddPlan;
+/**
+ * Adds `changes` to the project in `directory`: plans the addition, refuses
+ * with an `AddConflictError` when it would overwrite the user's edits, then
+ * writes the files, installs new dependencies, formats what it wrote and
+ * records the new spec and file hashes. Adding what the project already has
+ * changes nothing.
+ */
+declare function addToProject(directory: string, changes: AddChanges, options?: AddOptions): Promise<AddResult>;
 
 /**
- * Writes the project described by `options`, then installs its dependencies
- * (unless `install` is `false`) and initializes git (when `git` is `true`).
- * Throws when `name` is not a valid package name or `path` exists and is not
- * empty. A failed install or git step does not throw: the result reports it,
- * and the project stays written.
+ * A unified diff from `before` to `after`, as `git diff` prints it, or an
+ * empty string when they are equal. A missing side is `undefined`: the file
+ * is created or deleted.
  */
-declare function scaffold(options: ProjectOptions): Promise<ScaffoldResult>;
+declare function unifiedDiff(path: string, before: string | undefined, after: string | undefined): string;
 
-interface ParsedArgs {
-    name?: string;
-    template?: Template;
-    provider?: LLMProvider;
-    model?: string;
+/** An example of the Cogitator repo, as `--example` turns it into a project. Indexed at build time. */
+interface ExampleEntry {
+    /** `core/basic-agent`: the category and the file name without its number. */
+    name: string;
+    title: string;
+    /** The runnable file, relative to `examples/`. */
+    entry: string;
+    /** Every file the project needs, relative to `examples/`. */
+    files: string[];
+    dependencies: Record<string, string>;
+    devDependencies: Record<string, string>;
+    /** Environment variables the files read. */
+    env: string[];
+    /** What runs the example: Node through tsx, or Bun for examples that use its APIs. */
+    runtime: 'node' | 'bun';
+}
+/** The examples indexed when the scaffolder was built, from the `examples/` it is released with. */
+declare function examples(): ExampleEntry[];
+/** The git tag the examples of a scaffolder version are fetched from. */
+declare function exampleRef(version: string): string;
+/** `name#ref` as `--example` takes it. */
+declare function parseExampleArgument(value: string): {
+    query: string;
+    ref?: string;
+};
+/**
+ * The example `query` names: `core/basic-agent`, its file `core/01-basic-agent`
+ * or `core/01-basic-agent.ts`, or just `basic-agent` when only one category
+ * has it. Throws with the closest names otherwise.
+ */
+declare function findExample(query: string, index?: readonly ExampleEntry[]): ExampleEntry;
+/** Where the raw content of `examples/<path>` is at `ref`. */
+declare function exampleFileUrl(ref: string, path: string): string;
+interface ExamplePlanOptions {
+    name: string;
+    packageManager: PackageManager;
+    version: string;
+    ref: string;
+    /** Values for `.env`. */
+    secrets?: Record<string, string>;
+}
+interface ExamplePlan {
+    example: ExampleEntry;
+    ref: string;
+    /** Files generated around the example. */
+    files: GeneratedFile[];
+    /** The example's own files, fetched from GitHub, relative to `examples/`. */
+    remoteFiles: string[];
+    command: string;
+    scripts: Record<string, string>;
+}
+/** The project around an example: package.json, tsconfig, .env.example, README and the rest. */
+declare function planExample(example: ExampleEntry, options: ExamplePlanOptions): ExamplePlan;
+/** Fetches the example's own files from GitHub at the plan's ref. */
+declare function fetchExampleFiles(plan: ExamplePlan, fetchImpl?: typeof fetch): Promise<GeneratedFile[]>;
+
+/** A template fetched from a GitHub repository instead of generated: `github:owner/repo[/path][#ref]`. */
+interface RemoteTemplate {
+    owner: string;
+    repo: string;
+    path?: string;
+    ref?: string;
+}
+declare function describeTemplate(template: RemoteTemplate): string;
+/**
+ * Where the archive of `template` is. With a token it goes through the GitHub
+ * API, which serves private repositories; without one through codeload.
+ */
+declare function templateArchive(template: RemoteTemplate, token?: string): {
+    url: string;
+    headers: Record<string, string>;
+};
+interface DownloadResult {
+    /** Files written, relative to the directory. */
+    files: string[];
+    /** Entries left out: links and special files, which a template has no business shipping. */
+    skipped: string[];
+}
+/**
+ * Downloads `template` and extracts it, or its `path` inside the repository,
+ * into `directory`. Only regular files and directories are written, none
+ * outside `directory`.
+ */
+declare function downloadTemplate(template: RemoteTemplate, directory: string, options?: {
+    fetch?: typeof fetch;
+    token?: string;
+}): Promise<DownloadResult>;
+interface PreparedTemplate {
+    /** The package manager its lockfile belongs to, when it has one. */
     packageManager?: PackageManager;
-    docker?: boolean;
-    git?: boolean;
+    /** Dependencies rewritten from `workspace:` to published versions. */
+    rewritten: string[];
+}
+/**
+ * Makes an extracted template a project of its own: package.json gets the
+ * project's name, and `workspace:` ranges of `@cogitator-ai/*` packages, which
+ * templates from a monorepo carry, become the versions released with the
+ * scaffolder. Other workspace and catalog ranges cannot be resolved outside
+ * their monorepo and are refused.
+ */
+declare function prepareTemplate(directory: string, options: {
+    name: string;
+}): PreparedTemplate;
+
+interface StarterOptions {
+    directory: string;
+    name: string;
+    packageManager: PackageManager;
     install?: boolean;
-    yes?: boolean;
+    git?: boolean;
+    log?: ScaffoldLogger;
+    inheritOutput?: boolean;
+    fetch?: typeof fetch;
 }
-declare function parseArgs(args: string[]): ParsedArgs;
+/** A project made from an example or a remote template instead of the generator. */
+interface StarterResult {
+    directory: string;
+    /** Where it came from: `example core/basic-agent at create-cogitator-app@0.4.0` or `github:owner/repo`. */
+    source: string;
+    files: string[];
+    packageManager: PackageManager;
+    install: StepResult;
+    git: StepResult;
+    /** Commands to the first run. */
+    nextSteps: NextStep[];
+    notes: string[];
+}
+/** The project `--example` describes, before anything is fetched or written. */
+declare function resolveExample(argument: string, options: Pick<StarterOptions, 'name' | 'packageManager'> & {
+    secrets?: Record<string, string>;
+}): ExamplePlan;
+/**
+ * Creates a project from an example of the Cogitator repo: its files at the
+ * tag of this scaffolder version (or the ref after `#`), with a package.json,
+ * tsconfig, .env.example and README around them.
+ */
+declare function createFromExample(plan: ExamplePlan, options: StarterOptions): Promise<StarterResult>;
 /**
- * Turn the parsed arguments into project options, asking for whatever they leave
- * out; with `--yes` nothing is asked and the defaults fill the gaps.
+ * Creates a project from a GitHub repository or a directory of one. The
+ * repository's lockfile decides the package manager when it has one.
+ * Nothing is left behind when the download fails.
  */
-declare function collectOptions(args: ParsedArgs): Promise<ProjectOptions>;
+declare function createFromTemplate(template: RemoteTemplate, options: StarterOptions & {
+    token?: string;
+}): Promise<StarterResult>;
 
-declare function getTemplate(name: Template): TemplateGenerator;
-declare const templateChoices: Array<{
-    value: Template;
+/** A combination the generated project could not work with, and how to fix it. */
+interface CompatIssue {
+    message: string;
+    fix: string;
+}
+/**
+ * Every reason `spec` describes a project that would not work, empty when it is
+ * consistent. Checked before any file is written, so an impossible project is
+ * refused instead of generated half-broken.
+ */
+declare function compatibilityIssues(spec: ProjectSpec): CompatIssue[];
+declare class IncompatibleSpecError extends Error {
+    readonly issues: CompatIssue[];
+    constructor(issues: CompatIssue[]);
+}
+declare function assertCompatible(spec: ProjectSpec): void;
+
+/** The parts of a spec a preset fixes: everything except the name, provider and tooling. */
+type PresetSpec = Pick<ProjectSpecInput, 'app' | 'server' | 'channels' | 'memory' | 'vectorStore' | 'features'> & {
+    provider?: ProjectSpecInput['provider'];
+};
+interface Preset {
+    id: string;
     label: string;
     hint: string;
-}>;
+    spec: PresetSpec;
+    /** Earlier names of the preset that `--template` still accepts. */
+    aliases?: string[];
+}
+/**
+ * Named starting points. Every preset is a combination of the stack axes, so a
+ * preset project can grow with `cogitator add` like any other.
+ */
+declare const PRESETS: readonly Preset[];
+declare const DEFAULT_PRESET = "basic";
+declare function findPreset(idOrAlias: string): Preset | undefined;
+declare function presetIds(): string[];
+
+interface Choice<T extends string> {
+    value: T;
+    label: string;
+    hint: string;
+}
+declare const APP_CHOICES: Choice<AppKind>[];
+declare const SERVER_CHOICES: Choice<ServerFramework>[];
+declare const MEMORY_CHOICES: Choice<MemoryKind>[];
+declare const VECTOR_STORE_CHOICES: Choice<VectorStore>[];
+declare const FEATURE_CHOICES: Choice<FeatureId>[];
+declare const DEPLOY_CHOICES: Choice<DeployTarget>[];
+declare const CHANNEL_CHOICES: Choice<ChannelKind>[];
+declare const CODING_AGENT_CHOICES: Choice<CodingAgent>[];
+
+interface ProviderInfo {
+    id: LLMProvider;
+    label: string;
+    /** The variable the API key is read from, absent for providers without one. */
+    envKey?: string;
+    /** Where to create an API key. */
+    keyUrl?: string;
+    /** The model a new project uses unless another one is chosen. */
+    defaultModel: string;
+    /** The embedding model RAG uses with this provider, absent when it has none. */
+    embeddingModel?: string;
+    /** The dimensions of `embeddingModel`, which vector stores size their collections by. */
+    embeddingDimensions?: number;
+    /** Whether the provider has a realtime voice API Cogitator drives. */
+    realtime: boolean;
+    /** A short line for prompts and `--help`. */
+    hint: string;
+}
+declare const PROVIDER_INFO: Record<LLMProvider, ProviderInfo>;
+declare function providerInfo(provider: LLMProvider): ProviderInfo;
+declare function providerEnvKey(provider: LLMProvider): string | undefined;
+declare function defaultModel(provider: LLMProvider): string;
+/**
+ * Small models with reliable tool calling that run on a laptop, offered when
+ * Ollama is not reachable to list what is installed.
+ */
+declare const OLLAMA_SUGGESTED_MODELS: readonly ["qwen3.5:9b", "qwen3.5:4b", "gemma4:e4b", "llama3.1:8b", "mistral-small3.2:24b"];
+declare const DEFAULT_OLLAMA_URL = "http://localhost:11434";
+
+interface ModelChoice {
+    /** The model id without the provider prefix. */
+    value: string;
+    label: string;
+    hint?: string;
+}
+/** Where the choices came from: the live catalogue, the built-in list, the local Ollama, or a fallback. */
+type ModelSource = 'catalog' | 'builtin' | 'ollama' | 'suggested';
+interface ModelChoices {
+    choices: ModelChoice[];
+    source: ModelSource;
+}
+/** `$2 in / $10 out per 1M tokens, 1M context`, the line a model choice shows. */
+declare function describeModel(model: Pick<ModelInfo, 'pricing' | 'contextWindow'>): string;
+/**
+ * The current models of a cloud provider: its built-in lineup from
+ * `@cogitator-ai/models`, with prices and context windows refreshed from the
+ * live catalogue when it answers in time. The provider's default comes first.
+ */
+declare function cloudModelChoices(provider: Exclude<LLMProvider, 'ollama'>, options?: {
+    timeoutMs?: number;
+    registry?: Pick<ModelRegistry, 'initialize' | 'getModel'>;
+}): Promise<ModelChoices>;
+/**
+ * The models of the local Ollama, with the recommended one first and marked as
+ * installed or not. When Ollama does not answer, a list of small models with
+ * reliable tool calling to pull.
+ */
+declare function ollamaModelChoices(baseUrl?: string): Promise<ModelChoices>;
+declare function modelChoices(provider: LLMProvider): Promise<ModelChoices>;
+
+/** What checking an API key found out. The key itself never appears in it. */
+type KeyCheck = {
+    status: 'valid';
+} | {
+    status: 'rate-limited';
+} | {
+    status: 'invalid';
+    httpStatus: number;
+} | {
+    status: 'unreachable';
+    reason: string;
+} | {
+    status: 'unexpected';
+    httpStatus: number;
+};
+/** Checks that `key` is accepted by `provider`, within `timeoutMs`. */
+declare function checkApiKey(provider: Exclude<LLMProvider, 'ollama'>, key: string, options?: {
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}): Promise<KeyCheck>;
+/** One line for the user about a key check. */
+declare function describeKeyCheck(envKey: string, check: KeyCheck): string;
+
+interface OllamaModel {
+    name: string;
+    size: number;
+}
+/**
+ * The Ollama server the generated code talks to: `OLLAMA_BASE_URL`, which it
+ * reads, then `OLLAMA_HOST`, which the Ollama CLI reads, then the local default.
+ */
+declare function resolveOllamaUrl(env?: Record<string, string | undefined>): string;
+/** The models installed in the Ollama at `baseUrl`, or `undefined` when it does not answer. */
+declare function listOllamaModels(baseUrl: string, timeoutMs?: number): Promise<OllamaModel[] | undefined>;
+/** Whether `model` is among `installed`, treating a name without a tag as `:latest` like Ollama does. */
+declare function hasOllamaModel(installed: readonly OllamaModel[], model: string): boolean;
+/** Pulls `model` into the Ollama at `baseUrl`, reporting each status line; throws when the pull fails. */
+declare function pullOllamaModel(baseUrl: string, model: string, onStatus: (status: string) => void): Promise<void>;
 
 /**
  * The package manager that launched the scaffolder, read from the
  * `npm_config_user_agent` it sets (`npm/10.9.8 node/v22...` under npx), or pnpm
  * when there is none.
  */
-declare function detectPackageManager(): PackageManager;
-declare function devCommand(pm: PackageManager): string;
+declare function detectPackageManager(userAgent?: string | undefined): PackageManager;
+/**
+ * The `packageManager` field for the pnpm, Yarn or Bun that runs the scaffolder,
+ * e.g. `pnpm@10.26.0`, so corepack and the deploy image install with the same
+ * version. Undefined for npm, which corepack leaves alone, and when the version
+ * is unknown.
+ */
+declare function detectPackageManagerSpec(pm: PackageManager, userAgent?: string | undefined): string | undefined;
+/** The command that runs the package.json script `script`. */
+declare function runScript(pm: PackageManager, script: string, args?: string): string;
+/** The command that runs a binary of an installed package. */
+declare function execCommand(pm: PackageManager, bin: string): string;
+declare function installCommand(pm: PackageManager): string;
 
-declare const defaultModels: Record<LLMProvider, string>;
-declare function providerEnvKey(provider: LLMProvider): string;
+/** The version of create-cogitator-app itself, inlined at build time. */
+declare function scaffolderVersion(): string;
+type CogitatorPackage = `@cogitator-ai/${string}`;
+/** The range a generated project depends on for `name`: a caret on the version released with the scaffolder. */
+declare function cogitatorVersion(name: CogitatorPackage): string;
+/** Every `@cogitator-ai/*` version the scaffolder knows, for `--json` and diagnostics. */
+declare function knownCogitatorVersions(): Record<string, string>;
 /**
- * How generated code reads the provider's API key: `requireEnv` calls the
- * `requireEnv` helper of the generated `src/env.ts`, which fails at startup
- * with the name of the missing variable. `process-env` reads `process.env` and
- * leaves a missing key to the first request, for code a build imports without
- * the key, such as a Next.js route.
+ * Third-party packages generated projects depend on, in one place so every
+ * feature asks for the same range. Ranges follow the current majors.
  */
-type ApiKeyAccess = 'requireEnv' | 'process-env';
-/** The `llm` section of the generated `new Cogitator({...})` call. */
-declare function providerConfig(provider: LLMProvider, access?: ApiKeyAccess): string;
+declare const VERSIONS: {
+    readonly zod: "^4.6.5";
+    readonly typescript: "^7.0.2";
+    readonly typesNode: "^24.19.1";
+    readonly tsx: "^4.23.15";
+    readonly vitest: "^5.0.3";
+    readonly biome: "^2.5.15";
+    readonly express: "^5.2.1";
+    readonly typesExpress: "^5.0.6";
+    readonly fastify: "^5.12.5";
+    readonly fastifyCors: "^11.3.0";
+    readonly hono: "^4.13.13";
+    readonly honoNodeServer: "^2.1.3";
+    readonly koa: "^3.2.1";
+    readonly koaRouter: "^15.7.0";
+    readonly typesKoa: "^3.0.3";
+    readonly typesKoaRouter: "^15.0.0";
+    readonly koaCors: "^5.0.0";
+    readonly typesKoaCors: "^5.0.1";
+    readonly koaBodyparser: "^6.1.0";
+    readonly tetsuCore: "^0.6.3";
+    readonly tetsuSse: "^0.6.3";
+    readonly tetsuOpenapi: "^0.6.3";
+    readonly typesBun: "^1.4.2";
+    readonly next: "^16.4.0";
+    readonly react: "^19.3.0";
+    readonly reactDom: "^19.3.0";
+    readonly typesReact: "^19.3.0";
+    readonly typesReactDom: "^19.3.0";
+    readonly tailwind: "^4.3.3";
+    readonly tailwindPostcss: "^4.3.3";
+    readonly reactMarkdown: "^10.1.0";
+    readonly betterSqlite3: "^13.0.3";
+    readonly pg: "^8.23.1";
+    readonly ioredis: "^6.0.0";
+    readonly mongodb: "^7.7.0";
+    readonly qdrant: "^1.19.0";
+    readonly grammy: "^1.46.0";
+    readonly discord: "^14.27.0";
+    readonly slackBolt: "^5.1.0";
+    readonly ws: "^8.22.0";
+    readonly langfuse: "^3.39.2";
+    readonly modelContextProtocol: "^1.32.1";
+};
+/** Container images compose and deploy use, pinned so a project starts the same way every time. */
+declare const IMAGES: {
+    readonly redis: "redis:8.8-alpine";
+    readonly postgres: "pgvector/pgvector:0.8.7-pg18-trixie";
+    readonly mongodb: "mongo:8.3";
+    readonly qdrant: "qdrant/qdrant:v1.19.2";
+    readonly ollama: "ollama/ollama:0.40.0";
+    readonly jaeger: "jaegertracing/jaeger:2.22.0";
+};
 
+/** Where the events go: the Umami instance of the Cogitator project. */
+declare const TELEMETRY_HOST = "https://analytics.el1fe.com";
+declare const TELEMETRY_DOCS = "https://cogitator.app/docs/getting-started/telemetry";
 /**
- * Why `name` cannot be the generated package's name, or `undefined` when it can.
- * The name lands in package.json and in generated code, so it has to be a valid
- * unscoped npm package name.
+ * The Umami website the events are counted under, set when the scaffolder is
+ * built for a release (`COGITATOR_UMAMI_WEBSITE_ID`). A build without it sends
+ * nothing.
  */
-declare function validateProjectName(name: string): string | undefined;
+declare function telemetryWebsiteId(): string;
+/**
+ * Everything one event carries, and nothing else: no project name, path,
+ * model, key or anything a user typed.
+ */
+interface TelemetryPayload {
+    version: string;
+    /** The preset, `custom` for a stack picked by hand, `example` or `template` for copied projects. */
+    preset: string;
+    provider: string;
+    memory: string;
+    /** The add-ons, comma-separated in catalog order. */
+    features: string;
+    packageManager: string;
+    /** The major version of Node, such as `24`. */
+    node: string;
+    /** `darwin`, `linux` or `win32`. */
+    os: string;
+    outcome: 'success' | 'failure';
+}
+declare const PAYLOAD_FIELDS: ReadonlyArray<keyof TelemetryPayload>;
+declare function payloadFor(spec: Pick<ProjectSpec, 'preset' | 'provider' | 'memory' | 'features' | 'packageManager'> | undefined, outcome: TelemetryPayload['outcome'], kind?: 'generated' | 'example' | 'template'): TelemetryPayload;
+/** Why no event is sent, or `undefined` when one is. */
+declare function telemetryDisabledReason(options: {
+    flag?: boolean;
+    dryRun?: boolean;
+    env?: NodeJS.ProcessEnv;
+    websiteId?: string;
+}): string | undefined;
+/**
+ * The one line about telemetry shown the first time it is on, or `undefined`
+ * when it was shown before. Showing it is remembered in the user's config
+ * directory.
+ */
+declare function firstRunNotice(env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Sends the event to Umami. It never throws and never takes longer than its
+ * timeout: a slow or failing network changes nothing for the scaffolder.
+ */
+declare function sendTelemetry(payload: TelemetryPayload, options?: {
+    fetch?: typeof fetch;
+    websiteId?: string;
+    host?: string;
+    timeoutMs?: number;
+}): Promise<boolean>;
+
+interface Io {
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+}
+/** What `run` reaches the network and the environment with, replaceable in tests. */
+interface RunDeps {
+    fetch?: typeof fetch;
+    env?: NodeJS.ProcessEnv;
+    /** Where telemetry goes, the release's Umami website by default. */
+    telemetry?: {
+        websiteId?: string;
+        host?: string;
+        fetch?: typeof fetch;
+    };
+}
+/** Runs the scaffolder for `argv` and resolves with the exit code. */
+declare function run(argv: readonly string[], io?: Io, deps?: RunDeps): Promise<number>;
+
+/** The candidate closest to `input`, when it is close enough to be a typo of it. */
+declare function closest(input: string, candidates: readonly string[]): string | undefined;
 
-export { type LLMProvider, type PackageManager, type ProjectOptions, type ScaffoldResult, type ScaffoldStep, type Template, type TemplateFile, collectOptions, defaultModels, detectPackageManager, devCommand, getTemplate, parseArgs, providerConfig, providerEnvKey, scaffold, templateChoices, validateProjectName };
+export { APP_CHOICES, APP_KINDS, type AddChanges, type AddConflict, AddConflictError, type AddNote, type AddOptions, type AddPlan, type AddResult, type AppKind, CHANNELS, CHANNEL_CHOICES, CODING_AGENTS, CODING_AGENT_CHOICES, type ChannelKind, type Choice, type CodingAgent, type CompatIssue, DEFAULT_OLLAMA_URL, DEFAULT_PRESET, DEPLOY_CHOICES, DEPLOY_TARGETS, type DeployTarget, type DownloadResult, type ExampleEntry, type ExamplePlan, type ExamplePlanOptions, FEATURES, FEATURE_CHOICES, type FeatureId, type FileChange, IMAGES, IncompatibleSpecError, type KeyCheck, type LLMProvider, LOCK_PATH, MANIFEST_KEY, MEMORIES, MEMORY_CHOICES, type MemoryKind, type ModelChoice, type ModelChoices, type ModelSource, NotAScaffoldedProjectError, OLLAMA_SUGGESTED_MODELS, type OllamaModel, PACKAGE_MANAGERS, PAYLOAD_FIELDS, PRESETS, PROVIDERS, PROVIDER_INFO, type PackageManager, type PlanOptions, type PreparedTemplate, type Preset, type ProjectPlan, type ProjectSpec, type ProjectSpecInput, ProjectSpecSchema, type ProviderInfo, type RemoteTemplate, SERVERS, SERVER_CHOICES, type ScaffoldLock, type ScaffoldLogger, type ScaffoldManifest, type ScaffoldOptions, type ScaffoldResult, type ServerFramework, type StarterOptions, type StarterResult, type StepResult, TELEMETRY_DOCS, TELEMETRY_HOST, type TelemetryPayload, VECTOR_STORES, VECTOR_STORE_CHOICES, VERSIONS, type VectorStore, addToProject, assertCompatible, bareModel, changesDependencies, checkApiKey, closest, cloudModelChoices, cogitatorVersion, compatibilityIssues, createFromExample, createFromTemplate, defaultModel, describeKeyCheck, describeModel, describeTemplate, detectPackageManager, detectPackageManagerSpec, downloadTemplate, exampleFileUrl, exampleRef, examples, execCommand, fetchExampleFiles, findExample, findPreset, firstRunNotice, formatProject, hasOllamaModel, hashContent, installCommand, knownCogitatorVersions, listOllamaModels, modelChoices, ollamaModelChoices, parseExampleArgument, parseSpec, payloadFor, planAdd, planExample, planProject, prepareTemplate, presetIds, providerEnvKey, providerInfo, pullOllamaModel, qualifiedModel, readLock, resolveExample, resolveOllamaUrl, run, runScript, scaffold, scaffolderVersion, sendTelemetry, silentLogger, telemetryDisabledReason, telemetryWebsiteId, templateArchive, unifiedDiff, updateLock, validateProjectName, writeFiles, writeLock };