/** The pnpm fetched when this machine has none of its own. */
declare const SCAFFOLD_PNPM = "pnpm@12.16.0";
/** A runnable pnpm: the executable and the arguments that must precede pnpm's own. */
interface PnpmInvocation {
    readonly file: string;
    readonly prefix: readonly string[];
}
/** The pnpm this machine can run, or `null` when it can run none. */
declare function pnpmInvocation(): PnpmInvocation | null;
/**
 * The same invocation as one shell string, for callers that shell out rather
 * than spawn — `pnpm install`, or `npx --yes pnpm@<pinned> install`. `null` when
 * this machine can run no pnpm at all. No argument here ever needs quoting: the
 * pieces are a fixed executable name, fixed flags, a `pnpm@<semver>` specifier
 * and the caller's own literal subcommands.
 */
declare function pnpmCommandLine(args: readonly string[]): string | null;
/** What to tell a user whose machine can run no pnpm. Never says `corepack`. */
declare function noPnpmMessage(what: string, cwd: string): string;
/**
 * What a user types to run pnpm on this machine, as the words before a
 * subcommand: `pnpm`, or `npx --yes pnpm@<pinned>` (guuey#1741). Every command
 * the scaffold prints, and every command its templates show, starts with this,
 * so a user without pnpm is never told to type `pnpm`. When the machine can run
 * no pnpm at all it is `pnpm`: that user has to install pnpm first, and the
 * next steps say so.
 */
declare function pnpmRunner(inv: PnpmInvocation | null): string;

/**
 * Opt-in analytics for a scaffolded app (guuey#1062):
 *
 *   1. The DEFAULT scaffold carries ZERO analytics bytes — no loader, no
 *      import, no key placeholder. A customer's app never reports to Guuey's
 *      PostHog by accident; `check-templates.mjs` asserts the template tree
 *      itself is clean (the guuey#930-class guard: template bytes, not
 *      emitted copies, are the truth).
 *   2. Opt-in ONLY by the explicit scaffold-time flag `--analytics posthog`
 *      (non-interactive-safe; the guuey-owned demo recipe passes it).
 *   3. With the flag, `web/index.html` gains the SAME cookieless loader
 *      guuey.com runs (landing guuey#626 / demos guuey#1059) — but the
 *      project key is never a literal in these bytes: the loader reads
 *      `%VITE_POSTHOG_KEY%` (+ optional `%VITE_POSTHOG_HOST%`), which Vite
 *      substitutes in `index.html` at build time from the app's env, and it
 *      renders nothing when the key is absent (Vite leaves an undefined
 *      `%VITE_*%` token in place — the guard treats that as "no key").
 *   4. Tracker semantics (cookieless_mode 'always', pageview/pageleave/
 *      autocapture, `register({ surface })`, the AEO bot register) mirror
 *      growth's snippet; growth owns them — when growth's bytes move, this
 *      block follows.
 */
type AnalyticsProvider = 'posthog';

/** Frameworks the scaffolder ships templates for. */
type Framework = 'claude-agent-sdk' | 'openai-agents-sdk' | 'google-adk';
/**
 * App templates the scaffolder ships. `base` = landing + login + home +
 * chat; `agentic-app` extends it with the split-sidebar product shell whose
 * agent dock swaps the main canvas to a fullscreen agent.
 */
type Template = 'base' | 'agentic-app' | 'agent';
/**
 * Who the agent is FOR (guuey#1597, stamped by guuey#1670): `personal` — the
 * builder's own assistant; `customers` — an agent on the builder's surface.
 * The same two values as `@guuey/config`'s `APP_BUILT_FOR`. That package is a
 * devDependency here, never a runtime one, so the list is restated and
 * `scaffold.test.ts` pins the two equal.
 */
type ScaffoldBuiltFor = 'personal' | 'customers';

interface ScaffoldOptions {
    /** Absolute or cwd-relative path to create/populate the new project in. */
    targetDir: string;
    /** npm-safe project name (also used as the default scope). */
    name: string;
    framework: Framework;
    /** App template. Default: `base`. */
    template?: Template;
    /** Package scope for `@<scope>/*` packages. Default: `name`. */
    scope?: string;
    /** Run `pnpm install` in the new project after scaffolding. Default: false. */
    install?: boolean;
    /** Opt-in analytics loader in web/index.html (guuey#1062). Default: none — zero analytics bytes. */
    analytics?: AnalyticsProvider;
    /** Run `git init` + an initial commit in the new project. Default: true. */
    git?: boolean;
    /**
     * Bind the scaffold to an EXISTING guuey app (guuey#580 point 4 — the
     * tada page's one-liner): stamps top-level `appId` into the scaffolded
     * guuey.json, which is exactly where `scripts/bootstrap.mjs --link`
     * reads its default from — so the link phase runs promptless and the
     * repo is born bound to the just-created agent. No validation here
     * beyond non-empty: the id's truth is the platform's to judge at link
     * time (a wrong id fails loudly there, with auth in hand).
     */
    appId?: string;
    /**
     * Who the agent is FOR (guuey#1670, `guuey create --for`). Stamps
     * `app.builtFor` into the scaffolded guuey.json. `guuey deploy` sends it
     * when it creates the app, and `guuey agent apply` converges it. Absent
     * writes no key, and `guuey deploy` asks the question before it creates
     * the app.
     */
    builtFor?: ScaffoldBuiltFor;
    /** Scaffold into a non-empty targetDir anyway. Default: false. */
    force?: boolean;
    /**
     * How this machine runs pnpm, when the caller already asked `pnpmInvocation()`
     * (`null`: it runs none). Omitted, the scaffold asks it once itself. Either
     * way there is one answer per scaffold (guuey#1741).
     */
    pnpm?: PnpmInvocation | null;
    /** Root directory holding `<template>/<framework>` trees (+ `mcp-base/`). Default: dist/templates. */
    templatesDir?: string;
}
interface ScaffoldResult {
    projectDir: string;
    /**
     * How this machine runs pnpm, probed once for the whole scaffold
     * (guuey#1741): the install used it, the templates' command lines were
     * filled with it, and the caller prints its next steps with it
     * (`nextSteps`). `null` when the machine can run no pnpm.
     */
    pnpm: PnpmInvocation | null;
}
declare function scaffold(opts: ScaffoldOptions): Promise<ScaffoldResult>;

interface ScaffoldExampleOptions {
    /** Absolute or cwd-relative path to create/populate the new project in. */
    targetDir: string;
    /** The example's top-level directory name in withguuey/demos (e.g. `trimly`). */
    example: string;
    /** Run `pnpm install` after extraction. Default: false. */
    install?: boolean;
    /** Run `git init` + an initial commit. Default: true. */
    git?: boolean;
    /** Extract into a non-empty targetDir anyway. Default: false. */
    force?: boolean;
    /** How this machine runs pnpm, when the caller already asked `pnpmInvocation()`; omitted, asked once here (guuey#1741). */
    pnpm?: PnpmInvocation | null;
    /**
     * Test seam: returns the repo tarball as a stream. Default fetches the
     * codeload URL. The tarball's first path segment (`demos-main/`) is
     * discovered, never assumed.
     */
    fetchTarball?: () => Promise<NodeJS.ReadableStream>;
}
interface ScaffoldExampleResult {
    projectDir: string;
    /** How this machine runs pnpm, probed once (guuey#1741): the install used it and the next steps print it. */
    pnpm: PnpmInvocation | null;
}
declare function scaffoldExample(opts: ScaffoldExampleOptions): Promise<ScaffoldExampleResult>;

interface ScaffoldMcpOptions {
    /** Absolute or cwd-relative path to create the MCP package in. */
    targetDir: string;
    /** npm-safe MCP name (also the default scope in standalone mode). */
    name: string;
    /**
     * Package scope for the emitted `@<scope>/<name>-mcp` name. Project-mode
     * callers (`guuey mcp new` inside a scaffolded app) pass the surrounding
     * project's own scope — its root `package.json` name, since a scaffolded
     * app's own `scope` defaults to its (unscoped) project name (see
     * `scaffold()`'s `scope ?? name`). Standalone-mode callers default this
     * to `name`.
     */
    scope?: string;
    /** Root directory holding `mcp-base/`. Default: `dist/templates`. */
    templatesDir?: string;
}
interface ScaffoldMcpResult {
    mcpDir: string;
}
/**
 * Scaffold a single hosted-MCP package from the shared `mcp-base` template
 * (`templates-src/mcp-base/`, emitted verbatim with `NAME_PLACEHOLDER`
 * unresolved to `dist/templates/mcp-base/` by `build-templates.mjs`; see
 * the mcp-lifecycle design spec §5).
 *
 * The sole consumer today is `guuey mcp new` (`@guuey/cli`):
 * - **Project mode** — `targetDir: <project>/mcps/<name>`, `scope`: the
 *   surrounding project's own scope.
 * - **Standalone mode** — `targetDir: ./<name>`, `scope` left `undefined`
 *   (defaults to `name`).
 *
 * Refuses (via {@link ensureTargetDir}) a non-empty `targetDir` — callers
 * that want a stricter "refuse ANY existing directory" rule (project mode's
 * "refuse if `mcps/<name>` exists") check `existsSync(targetDir)` themselves
 * before calling this.
 */
declare function scaffoldMcp(opts: ScaffoldMcpOptions): Promise<ScaffoldMcpResult>;

/** Whether `name` matches the npm-safe {@link NAME_PATTERN} rule. */
declare function isNpmSafeName(name: string): boolean;

/**
 * The "Next steps" a scaffold prints (guuey#1741). One printer for every
 * caller — `create-agentic-app` and `guuey create` — so the lines cannot drift
 * apart, and every command in them starts with the pnpm the scaffold itself
 * found (`ScaffoldResult.pnpm`): a user whose machine ran the install through
 * `npx --yes pnpm@<pinned>` is told to type exactly that, never a bare `pnpm`
 * that is not on their PATH. The templates' own command lines were filled with
 * the same words at scaffold time, so what the terminal says and what the app
 * says agree.
 */

/** What was scaffolded: a web-app template, the manage-only agent template, or an `--example` demo. */
type NextStepsKind = 'app' | 'agent' | 'example';
interface NextStepsInput {
    /** The scaffolded project's directory. */
    readonly projectDir: string;
    /** The scaffold's one probe of the pnpm ladder (`ScaffoldResult.pnpm`). */
    readonly pnpm: PnpmInvocation | null;
    /** Whether the scaffold ran the install; when it did not, installing is the first step. */
    readonly installed: boolean;
    readonly kind: NextStepsKind;
    /** How the user runs the guuey CLI in the project. Default `npx guuey`: the scaffold pins @guuey/cli. */
    readonly guuey?: string;
    /**
     * The scaffold is bound to an EXISTING app (`--app`). Its live definition is
     * not in the repo yet, and `apply` makes the live agent match the repo, so
     * the agent steps pull first: an apply before the pull would replace the
     * console-authored prompt and MCP servers with the template's.
     */
    readonly bound?: boolean;
}
/** The lines to print, `Next steps:` first. Each command line runs as printed, from the project directory. */
declare function nextSteps(input: NextStepsInput): string[];

interface AddCodeOptions {
    /** The declarative project to convert (its guuey.json is read from here). */
    projectDir: string;
    framework: Framework;
    /** Run `pnpm install` afterwards, so the new dependencies are present for the build. Default: false. */
    install?: boolean;
    /** How this machine runs pnpm, when the caller already asked (`null`: none). Omitted, asked once here. */
    pnpm?: PnpmInvocation | null;
    /** Root holding `base/<framework>` and `agent` (the assembled templates). Default: dist/templates. */
    templatesDir?: string;
}
interface AddCodeResult {
    projectDir: string;
    /** Project-relative paths written or changed, in order. */
    changed: string[];
    /** A pnpm-workspace.yaml the builder changed, kept as is: its install settings are theirs to merge. */
    keptWorkspaceFile: boolean;
    pnpm: PnpmInvocation | null;
}
/** Thrown for a project addCode cannot convert; the message is the whole reason, for the builder. */
declare class AddCodeError extends Error {
    readonly name = "AddCodeError";
}
declare function addCode(opts: AddCodeOptions): Promise<AddCodeResult>;

export { AddCodeError, type AddCodeOptions, type AddCodeResult, type Framework, type NextStepsInput, type NextStepsKind, type PnpmInvocation, SCAFFOLD_PNPM, type ScaffoldBuiltFor, type ScaffoldExampleOptions, type ScaffoldExampleResult, type ScaffoldMcpOptions, type ScaffoldMcpResult, type ScaffoldOptions, type ScaffoldResult, type Template, addCode, isNpmSafeName, nextSteps, noPnpmMessage, pnpmCommandLine, pnpmInvocation, pnpmRunner, scaffold, scaffoldExample, scaffoldMcp };