@rocapine/community 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rocapine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# @rocapine/community (CLI)
+
+Installs and manages the Community SDK backend — Supabase migrations and
+Edge Functions — inside your app's own Supabase project.
+
+```bash
+npx @rocapine/community <command>
+```
+
+No install needed for one-off use; `npx` always runs the latest published
+version. The binary is named `community`.
+
+## `init`
+
+```bash
+npx @rocapine/community init [--modules core,push,polls,reaction,inbox] [--project-url <url>] [--anon-key <key>] [--dir supabase]
+```
+
+Copies the migrations and Edge Functions for the requested modules into
+`<dir>/migrations/` and `<dir>/functions/` (default `dir`: `supabase`,
+relative to the current directory), and writes a `community-sdk.json`
+manifest at the repo root recording what was installed.
+
+- `--modules` — comma-separated (`core,push,polls,reaction,inbox`). `core`
+  is always implied even if omitted. Omit the flag entirely to install every
+  module. Regardless of the order you type them, modules are installed
+  `core → push → polls → reaction → inbox` — this order is load-bearing:
+  the inbox module's reaction trigger is guarded at install time and must
+  find the reaction module's table already present, so reaction has to land
+  first. Requesting `inbox` without `reaction` prints a (non-fatal) warning.
+- `--project-url` / `--anon-key` — needed only if a migration in the
+  selected modules carries a placeholder (see "Placeholder guard" below).
+  If omitted, the CLI tries to read the project URL from
+  `<dir>/config.toml`'s `project_id`, then prompts interactively; if stdin
+  isn't a TTY and a value is still missing, it fails loudly rather than
+  hanging.
+- `--dir` — target Supabase directory, default `supabase`.
+- Refuses to run if `community-sdk.json` already exists (use `upgrade`
+  instead) — see `ALREADY_INITIALIZED_MESSAGE`.
+- All-or-nothing: if anything fails partway through, every file this run
+  wrote is removed before the error propagates, so a retry starts clean.
+
+Prints next steps on success: review + `supabase db push`, set
+`OPENAI_API_KEY` (and optionally `SLACK_WEBHOOK_URL`,
+`COMMUNITY_APP_NAME`, `COMMUNITY_FALLBACK_NAME`, and — for the push module —
+`EXPO_ACCESS_TOKEN`), then `supabase functions deploy`.
+
+## `upgrade`
+
+```bash
+npx @rocapine/community upgrade [--project-url <url>] [--anon-key <key>] [--dir supabase]
+```
+
+Copies any migration templates shipped since `community-sdk.json` was last
+written (diffed by stable template identity, `<module>/<templateBaseName>`,
+not by filename — a template's numeric ordering prefix is not part of its
+identity), and copies in any Edge Function present in the shipped set but
+missing on disk. An Edge Function that already exists on disk but whose
+content differs from the shipped template is **overwritten, with a
+warning** — review the diff before deploying. `--project-url`/`--anon-key`
+are only needed if a newly-added migration carries a placeholder. Fails if
+`community-sdk.json` doesn't exist yet (run `init` or `adopt` first).
+
+## `adopt`
+
+```bash
+npx @rocapine/community adopt --schema-version <n> --modules core,push,... [--dir supabase]
+```
+
+For a backend that's already live in production, built by hand or migrated
+before this SDK existed (the mold precedent: Eve's Rhythm and other internal
+apps that hand-rolled their own community backend before this SDK existed).
+Writes **only** `community-sdk.json` — no migration or function file is ever
+copied — on the assumption the equivalent schema is already applied. A
+subsequent `upgrade` will still seed any Edge Function source not yet
+present in the repo (for review before deploy), since `adopt` never writes
+function files. If `--schema-version` doesn't match the CLI's current
+schema version, it warns that `installedTemplates` was reconstructed from
+the _current_ template set and points at `docs/compat.md` to check/adjust
+`community-sdk.json` by hand for a historical schema.
+
+## The manifest (`community-sdk.json`)
+
+```json
+{
+  "schemaVersion": 1,
+  "sdkVersion": "0.1.0",
+  "modules": ["core", "push", "polls", "reaction", "inbox"],
+  "installedFiles": ["supabase/migrations/20260101000000_community_core_tables.sql", "..."],
+  "installedTemplates": ["core/tables", "core/rls", "..."]
+}
+```
+
+- `schemaVersion` — the schema version this app's backend corresponds to
+  (see `docs/compat.md`).
+- `sdkVersion` — the CLI package version that last touched the manifest.
+- `modules` — canonical, ordered module list installed/adopted.
+- `installedFiles` — every file path this CLI has written (empty for an
+  `adopt`ed backend, since it copies nothing).
+- `installedTemplates` — stable `<module>/<templateBaseName>` identities of
+  every migration template known to be applied; this, not `installedFiles`,
+  is what `upgrade` diffs against (timestamped destination filenames can't
+  be compared meaningfully run to run).
+
+## Placeholder guard
+
+Three backend migration files (`core/003_moderation.sql`,
+`push/002_triggers.sql`, `reaction/001_reactions.sql`) embed the project's
+own URL/anon key (pg_net crons and webhooks that call back into the same
+project) as `__SUPABASE_PROJECT_URL__` / `__SUPABASE_ANON_KEY__`
+placeholders in the shipped template. `init`/`upgrade` substitute real
+values before writing the
+file to disk; if a value is missing and can't be resolved (flag, then
+`config.toml`, then a TTY prompt), the command fails rather than writing a
+file with a literal placeholder still in it — a migration with an
+unsubstituted placeholder would push successfully to Postgres and then fail
+silently at cron/webhook runtime, so this guard turns that into a loud,
+immediate CLI error instead.

package/lib/commands/adopt.d.ts

@@ -0,0 +1,38 @@
+import { type Manifest } from "../manifest";
+/**
+ * `community adopt` is for an app whose community backend already exists in
+ * production (hand-rolled before this SDK existed) rather than one being
+ * installed fresh. It writes ONLY community-sdk.json — no migration or
+ * function file ever touches disk — so `installedFiles` is always `[]`.
+ *
+ * `installedTemplates`, however, IS populated: it's set to every migration
+ * template this CLI currently ships for the adopted modules, on the
+ * assumption that a live/adopted schema already has everything up to the
+ * current template set (the only schemaVersion this CLI knows how to
+ * reconstruct — see the `--schema-version` mismatch warning below). This is
+ * what lets a subsequent `upgrade` recognize "nothing new to add" for
+ * migrations instead of trying to re-apply the app's entire schema history.
+ * It deliberately does NOT extend the same courtesy to functions: those are
+ * diffed by `upgrade` directly against files on disk, and adopt writes none,
+ * so the first `upgrade` after an `adopt` will (correctly) seed the
+ * Edge Function source into the repo for review before it's deployed.
+ */
+export declare const ALREADY_INITIALIZED_MESSAGE_ADOPT = "community-sdk: already initialized (found community-sdk.json) \u2014 adopt is only for a repo with no manifest yet";
+export interface AdoptOptions {
+    schemaVersion: number;
+    modules: string[];
+    /** Target Supabase directory, relative to `cwd`. Defaults to "supabase". Validated but otherwise unused — adopt copies nothing. */
+    dir?: string;
+    /** App repo root — where community-sdk.json lives. Defaults to process.cwd(). */
+    cwd?: string;
+    /** Source of the migrations/ tree, used only to compute `installedTemplates`. Defaults to the shipped templates. */
+    templatesDir?: string;
+    /** Called for non-fatal warnings (unknown-module-adjacent dependency warnings, schema-version mismatch). */
+    onWarn?: (message: string) => void;
+    /** Used to print the summary + compat-table pointer. */
+    log?: (message: string) => void;
+}
+export interface AdoptResult {
+    manifest: Manifest;
+}
+export declare function runAdopt(options: AdoptOptions): Promise<AdoptResult>;

package/lib/commands/adopt.js

@@ -0,0 +1,105 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALREADY_INITIALIZED_MESSAGE_ADOPT = void 0;
+exports.runAdopt = runAdopt;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const manifest_1 = require("../manifest");
+const install_shared_1 = require("../install-shared");
+/**
+ * `community adopt` is for an app whose community backend already exists in
+ * production (hand-rolled before this SDK existed) rather than one being
+ * installed fresh. It writes ONLY community-sdk.json — no migration or
+ * function file ever touches disk — so `installedFiles` is always `[]`.
+ *
+ * `installedTemplates`, however, IS populated: it's set to every migration
+ * template this CLI currently ships for the adopted modules, on the
+ * assumption that a live/adopted schema already has everything up to the
+ * current template set (the only schemaVersion this CLI knows how to
+ * reconstruct — see the `--schema-version` mismatch warning below). This is
+ * what lets a subsequent `upgrade` recognize "nothing new to add" for
+ * migrations instead of trying to re-apply the app's entire schema history.
+ * It deliberately does NOT extend the same courtesy to functions: those are
+ * diffed by `upgrade` directly against files on disk, and adopt writes none,
+ * so the first `upgrade` after an `adopt` will (correctly) seed the
+ * Edge Function source into the repo for review before it's deployed.
+ */
+exports.ALREADY_INITIALIZED_MESSAGE_ADOPT = "community-sdk: already initialized (found community-sdk.json) — adopt is only for a repo with no manifest yet";
+async function runAdopt(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const log = options.log ?? ((message) => console.log(message));
+    const onWarn = options.onWarn ?? ((message) => console.warn(message));
+    if ((0, manifest_1.readManifest)(cwd)) {
+        throw new Error(exports.ALREADY_INITIALIZED_MESSAGE_ADOPT);
+    }
+    if (!Number.isInteger(options.schemaVersion) || options.schemaVersion < 1) {
+        throw new Error(`community-sdk: --schema-version must be a positive integer, got ${options.schemaVersion}`);
+    }
+    const canonicalModules = (0, install_shared_1.resolveModules)(options.modules, onWarn);
+    const dirRel = options.dir ?? "supabase";
+    // Validated for consistency with init/upgrade (and to catch typos early)
+    // even though adopt never writes under it.
+    (0, install_shared_1.resolveContainedDir)(cwd, dirRel);
+    const templatesDir = options.templatesDir ?? (0, install_shared_1.defaultTemplatesDir)();
+    const { migrationsSrcRoot } = (0, install_shared_1.resolveTemplateRoots)(templatesDir);
+    if (options.schemaVersion !== manifest_1.CURRENT_SCHEMA_VERSION) {
+        onWarn(`community-sdk: --schema-version ${options.schemaVersion} was requested, but this CLI only knows the templates for the current schema (version ${manifest_1.CURRENT_SCHEMA_VERSION}) — it cannot reconstruct a historical template snapshot. installedTemplates was populated from the CURRENT template set; consult the compat table (docs/compat.md) and adjust community-sdk.json by hand if this app's live schema predates it.`);
+    }
+    const installedTemplates = [];
+    for (const moduleName of canonicalModules) {
+        const moduleSrcDir = path.join(migrationsSrcRoot, moduleName);
+        if (!fs.existsSync(moduleSrcDir))
+            continue;
+        const filenames = fs.readdirSync(moduleSrcDir).filter((f) => f.endsWith(".sql"));
+        for (const filename of filenames) {
+            installedTemplates.push((0, manifest_1.migrationTemplateId)(moduleName, (0, install_shared_1.templateBaseName)(filename)));
+        }
+    }
+    const manifest = {
+        schemaVersion: options.schemaVersion,
+        sdkVersion: (0, install_shared_1.readOwnPackageVersion)(),
+        modules: canonicalModules,
+        installedFiles: [],
+        installedTemplates: installedTemplates.sort(),
+    };
+    (0, manifest_1.writeManifest)(cwd, manifest);
+    log("");
+    log(`community-sdk adopted (${canonicalModules.join(", ")}) at schema version ${options.schemaVersion}.`);
+    log("No files were copied — this repo's schema/functions are assumed to already be live.");
+    log("Compat table: docs/compat.md (module <-> schemaVersion history, if this version isn't current).");
+    log("Next: `community upgrade` will seed any Edge Function source not yet present in this repo.");
+    return { manifest };
+}

package/lib/commands/init.d.ts

@@ -0,0 +1,29 @@
+import { type Manifest } from "../manifest";
+import { MODULE_ORDER, type Module } from "../install-shared";
+export { MODULE_ORDER, type Module };
+export declare const ALREADY_INITIALIZED_MESSAGE = "community-sdk: already initialized (found community-sdk.json), use upgrade";
+export interface InitOptions {
+    /** Modules to install. Defaults to every module. `core` is always implied. */
+    modules?: string[];
+    projectUrl?: string;
+    anonKey?: string;
+    /** Target Supabase directory, relative to `cwd`. Defaults to "supabase". */
+    dir?: string;
+    /** App repo root — where community-sdk.json lives. Defaults to process.cwd(). */
+    cwd?: string;
+    /** Source of the migrations/ + functions/ trees. Defaults to the shipped templates. */
+    templatesDir?: string;
+    /** Used to ask for projectUrl/anonKey when missing and not derivable. */
+    prompt?: (question: string) => Promise<string>;
+    /** Called for non-fatal dependency warnings (e.g. inbox without reaction). */
+    onWarn?: (message: string) => void;
+    /** Used to print the summary + next steps. */
+    log?: (message: string) => void;
+    /** Clock override for deterministic migration timestamps in tests. */
+    now?: Date;
+}
+export interface InitResult {
+    manifest: Manifest;
+    dir: string;
+}
+export declare function runInit(options?: InitOptions): Promise<InitResult>;

package/lib/commands/init.js

@@ -0,0 +1,152 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALREADY_INITIALIZED_MESSAGE = exports.MODULE_ORDER = void 0;
+exports.runInit = runInit;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const substitute_1 = require("../substitute");
+const manifest_1 = require("../manifest");
+const install_shared_1 = require("../install-shared");
+Object.defineProperty(exports, "MODULE_ORDER", { enumerable: true, get: function () { return install_shared_1.MODULE_ORDER; } });
+exports.ALREADY_INITIALIZED_MESSAGE = "community-sdk: already initialized (found community-sdk.json), use upgrade";
+async function runInit(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const log = options.log ?? ((message) => console.log(message));
+    const onWarn = options.onWarn ?? ((message) => console.warn(message));
+    if ((0, manifest_1.readManifest)(cwd)) {
+        throw new Error(exports.ALREADY_INITIALIZED_MESSAGE);
+    }
+    const canonicalModules = (0, install_shared_1.resolveModules)(options.modules, onWarn);
+    const dirRel = options.dir ?? "supabase";
+    const dir = (0, install_shared_1.resolveContainedDir)(cwd, dirRel);
+    const templatesDir = options.templatesDir ?? (0, install_shared_1.defaultTemplatesDir)();
+    const { migrationsSrcRoot, functionsSrcRoot } = (0, install_shared_1.resolveTemplateRoots)(templatesDir);
+    const { projectUrl, anonKey } = await (0, install_shared_1.resolveProjectCredentials)({
+        dir,
+        projectUrl: options.projectUrl,
+        anonKey: options.anonKey,
+        prompt: options.prompt,
+    });
+    const now = options.now ?? new Date();
+    // ---- migrations + functions, staged atomically: on any failure partway
+    // through, every file this run wrote (which may already contain the real
+    // project URL / anon key) is removed before the error propagates, so a
+    // retry starts clean instead of finding stale/duplicate files and no
+    // manifest to explain them. The manifest itself is written last, only once
+    // every file below has landed successfully.
+    const migrationsDestRoot = path.join(dir, "migrations");
+    const functionsDestRoot = path.join(dir, "functions");
+    const migrationsDestRootExisted = fs.existsSync(migrationsDestRoot);
+    const functionsDestRootExisted = fs.existsSync(functionsDestRoot);
+    const writtenPaths = [];
+    const installedTemplates = [];
+    try {
+        // ---- migrations ----
+        fs.mkdirSync(migrationsDestRoot, { recursive: true });
+        let fileIndex = 0;
+        for (const moduleName of canonicalModules) {
+            const moduleSrcDir = path.join(migrationsSrcRoot, moduleName);
+            const filenames = fs
+                .readdirSync(moduleSrcDir)
+                .filter((f) => f.endsWith(".sql"))
+                .sort();
+            for (const filename of filenames) {
+                const name = (0, install_shared_1.templateBaseName)(filename);
+                const timestamp = (0, install_shared_1.formatTimestamp)((0, install_shared_1.addSeconds)(now, fileIndex));
+                fileIndex += 1;
+                const destFilename = (0, install_shared_1.migrationDestFilename)(timestamp, moduleName, name);
+                const rawSql = fs.readFileSync(path.join(moduleSrcDir, filename), "utf8");
+                let substituted;
+                try {
+                    substituted = (0, substitute_1.substitutePlaceholders)(rawSql, { projectUrl, anonKey });
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    throw new Error(`${message} (source: ${moduleName}/${filename})`);
+                }
+                const destPath = path.join(migrationsDestRoot, destFilename);
+                fs.writeFileSync(destPath, substituted, "utf8");
+                writtenPaths.push(destPath);
+                installedTemplates.push((0, manifest_1.migrationTemplateId)(moduleName, name));
+            }
+        }
+        // ---- functions ----
+        fs.mkdirSync(functionsDestRoot, { recursive: true });
+        for (const fnName of (0, install_shared_1.functionsForModules)(canonicalModules)) {
+            const srcDir = path.join(functionsSrcRoot, fnName);
+            if (!fs.existsSync(srcDir))
+                continue;
+            const destDir = path.join(functionsDestRoot, fnName);
+            fs.cpSync(srcDir, destDir, { recursive: true });
+            writtenPaths.push(...(0, install_shared_1.listFilesRecursive)(destDir));
+        }
+    }
+    catch (err) {
+        for (const p of writtenPaths) {
+            fs.rmSync(p, { force: true });
+        }
+        if (!functionsDestRootExisted) {
+            fs.rmSync(functionsDestRoot, { recursive: true, force: true });
+        }
+        if (!migrationsDestRootExisted) {
+            fs.rmSync(migrationsDestRoot, { recursive: true, force: true });
+        }
+        throw err;
+    }
+    // ---- manifest ----
+    const manifest = {
+        schemaVersion: manifest_1.CURRENT_SCHEMA_VERSION,
+        sdkVersion: (0, install_shared_1.readOwnPackageVersion)(),
+        modules: canonicalModules,
+        installedFiles: writtenPaths.map((f) => (0, install_shared_1.toRelativePosix)(cwd, f)).sort(),
+        installedTemplates: installedTemplates.sort(),
+    };
+    (0, manifest_1.writeManifest)(cwd, manifest);
+    printNextSteps(log, canonicalModules);
+    return { manifest, dir };
+}
+function printNextSteps(log, modules) {
+    log("");
+    log(`community-sdk initialized (${modules.join(", ")}).`);
+    log("Next steps:");
+    log("  1. Review the copied migrations, then: supabase db push");
+    log("  2. Set Edge Function secrets: supabase secrets set OPENAI_API_KEY=...");
+    log("     optional: SLACK_WEBHOOK_URL, COMMUNITY_APP_NAME, COMMUNITY_FALLBACK_NAME");
+    if (modules.includes("push")) {
+        log("     push module: EXPO_ACCESS_TOKEN (required for notify-like/notify-comment)");
+    }
+    log("  3. Deploy the Edge Functions: supabase functions deploy");
+}

package/lib/commands/upgrade.d.ts

@@ -0,0 +1,33 @@
+import { type Manifest } from "../manifest";
+export declare const NOT_INITIALIZED_MESSAGE = "community-sdk: not initialized, run init (or adopt)";
+export interface UpgradeOptions {
+    /** Target Supabase directory, relative to `cwd`. Defaults to "supabase". */
+    dir?: string;
+    projectUrl?: string;
+    anonKey?: string;
+    /** App repo root — where community-sdk.json lives. Defaults to process.cwd(). */
+    cwd?: string;
+    /** Source of the migrations/ + functions/ trees. Defaults to the shipped templates. */
+    templatesDir?: string;
+    /** Used to ask for projectUrl/anonKey when a newly copied migration needs them. */
+    prompt?: (question: string) => Promise<string>;
+    /** Called for non-fatal warnings — most importantly, functions overwritten with new content. */
+    onWarn?: (message: string) => void;
+    /** Used to print the summary + next steps. */
+    log?: (message: string) => void;
+    /** Clock override for deterministic migration timestamps in tests. */
+    now?: Date;
+}
+export interface UpgradeResult {
+    manifest: Manifest;
+    dir: string;
+    /** True when nothing needed to change — no new migrations, no function drift. */
+    upToDate: boolean;
+    /** Relative (to `cwd`) paths of newly copied migration files, in copy order. */
+    addedMigrations: string[];
+    /** Function names copied because they weren't present on disk yet. */
+    newFunctions: string[];
+    /** Function names whose installed content differed from the template and was overwritten. */
+    overwrittenFunctions: string[];
+}
+export declare function runUpgrade(options?: UpgradeOptions): Promise<UpgradeResult>;