/**
 * Opt-in analytics for a scaffolded app (guuey#1062 — platform's ruling on
 * the row, 2026-09-09):
 *
 *   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';

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;
    /** Scaffold into a non-empty targetDir anyway. Default: false. */
    force?: boolean;
    /** Root directory holding `<template>/<framework>` trees (+ `mcp-base/`). Default: dist/templates. */
    templatesDir?: string;
}
interface ScaffoldResult {
    projectDir: string;
}
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;
    /**
     * 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;
}
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 pnpm fetched when this machine has none of its own. */
declare const SCAFFOLD_PNPM = "pnpm@11.2.2";
/** 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;

export { type Framework, type PnpmInvocation, SCAFFOLD_PNPM, type ScaffoldExampleOptions, type ScaffoldExampleResult, type ScaffoldMcpOptions, type ScaffoldMcpResult, type ScaffoldOptions, type ScaffoldResult, type Template, isNpmSafeName, noPnpmMessage, pnpmCommandLine, pnpmInvocation, scaffold, scaffoldExample, scaffoldMcp };