@rocapine/community 0.1.0

package/lib/commands/upgrade.js

@@ -0,0 +1,280 @@
+"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.NOT_INITIALIZED_MESSAGE = void 0;
+exports.runUpgrade = runUpgrade;
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const substitute_1 = require("../substitute");
+const manifest_1 = require("../manifest");
+const install_shared_1 = require("../install-shared");
+exports.NOT_INITIALIZED_MESSAGE = "community-sdk: not initialized, run init (or adopt)";
+async function runUpgrade(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const log = options.log ?? ((message) => console.log(message));
+    const onWarn = options.onWarn ?? ((message) => console.warn(message));
+    const manifest = (0, manifest_1.readManifest)(cwd);
+    if (!manifest) {
+        throw new Error(exports.NOT_INITIALIZED_MESSAGE);
+    }
+    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);
+    // Only modules the app actually has installed are diffed/re-synced —
+    // upgrade never adds or removes modules (that's what re-running init on a
+    // fresh dir, or a future dedicated command, would be for).
+    const canonicalModules = install_shared_1.MODULE_ORDER.filter((m) => manifest.modules.includes(m));
+    const installedTemplateIds = new Set(manifest.installedTemplates ?? reconstructInstalledTemplateIds(manifest.installedFiles));
+    const pending = [];
+    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"))
+            .sort();
+        for (const filename of filenames) {
+            const id = (0, manifest_1.migrationTemplateId)(moduleName, (0, install_shared_1.templateBaseName)(filename));
+            if (installedTemplateIds.has(id))
+                continue;
+            pending.push({
+                moduleName,
+                templateFilename: filename,
+                rawSql: fs.readFileSync(path.join(moduleSrcDir, filename), "utf8"),
+            });
+        }
+    }
+    // ---- functions: new (not on disk yet) vs changed (content differs) ----
+    const functionsDestRoot = path.join(dir, "functions");
+    const newFunctions = [];
+    const changedFunctions = [];
+    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);
+        if (!fs.existsSync(destDir)) {
+            newFunctions.push(fnName);
+        }
+        else if (functionDirDiffers(srcDir, destDir)) {
+            changedFunctions.push(fnName);
+        }
+    }
+    if (pending.length === 0 && newFunctions.length === 0 && changedFunctions.length === 0) {
+        log("community-sdk: already up to date");
+        return {
+            manifest,
+            dir,
+            upToDate: true,
+            addedMigrations: [],
+            newFunctions: [],
+            overwrittenFunctions: [],
+        };
+    }
+    // ---- credentials, only if a pending migration actually needs them ----
+    const needsCredentials = pending.some((p) => p.rawSql.includes("__SUPABASE"));
+    let projectUrl;
+    let anonKey;
+    if (needsCredentials) {
+        const creds = await (0, install_shared_1.resolveProjectCredentials)({
+            dir,
+            projectUrl: options.projectUrl,
+            anonKey: options.anonKey,
+            prompt: options.prompt,
+        });
+        projectUrl = creds.projectUrl;
+        anonKey = creds.anonKey;
+    }
+    const migrationsDestRoot = path.join(dir, "migrations");
+    const writtenMigrationPaths = [];
+    const addedMigrations = [];
+    const newInstalledTemplateIds = new Set(installedTemplateIds);
+    const createdFunctionDirs = [];
+    const backups = [];
+    try {
+        // ---- prepare every migration's final content up front: a placeholder
+        // error here must throw before a single byte is written to disk. ----
+        const now = options.now ?? new Date();
+        const prepared = pending.map((p) => {
+            if (!p.rawSql.includes("__SUPABASE"))
+                return { ...p, content: p.rawSql };
+            try {
+                return {
+                    ...p,
+                    content: (0, substitute_1.substitutePlaceholders)(p.rawSql, { projectUrl: projectUrl, anonKey: anonKey }),
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                throw new Error(`${message} (source: ${p.moduleName}/${p.templateFilename})`);
+            }
+        });
+        if (prepared.length > 0) {
+            fs.mkdirSync(migrationsDestRoot, { recursive: true });
+            prepared.forEach((p, index) => {
+                const timestamp = (0, install_shared_1.formatTimestamp)((0, install_shared_1.addSeconds)(now, index));
+                const name = (0, install_shared_1.templateBaseName)(p.templateFilename);
+                const destFilename = (0, install_shared_1.migrationDestFilename)(timestamp, p.moduleName, name);
+                const destPath = path.join(migrationsDestRoot, destFilename);
+                fs.writeFileSync(destPath, p.content, "utf8");
+                writtenMigrationPaths.push(destPath);
+                addedMigrations.push((0, install_shared_1.toRelativePosix)(cwd, destPath));
+                newInstalledTemplateIds.add((0, manifest_1.migrationTemplateId)(p.moduleName, name));
+            });
+        }
+        if (newFunctions.length > 0) {
+            fs.mkdirSync(functionsDestRoot, { recursive: true });
+        }
+        for (const fnName of newFunctions) {
+            const destDir = path.join(functionsDestRoot, fnName);
+            fs.cpSync(path.join(functionsSrcRoot, fnName), destDir, { recursive: true });
+            createdFunctionDirs.push(destDir);
+        }
+        for (const fnName of changedFunctions) {
+            const destDir = path.join(functionsDestRoot, fnName);
+            const backupDir = fs.mkdtempSync(path.join(os.tmpdir(), "community-sdk-upgrade-backup-"));
+            fs.cpSync(destDir, backupDir, { recursive: true });
+            backups.push({ destDir, backupDir });
+            fs.rmSync(destDir, { recursive: true, force: true });
+            fs.cpSync(path.join(functionsSrcRoot, fnName), destDir, { recursive: true });
+        }
+    }
+    catch (err) {
+        for (const p of writtenMigrationPaths)
+            fs.rmSync(p, { force: true });
+        for (const d of createdFunctionDirs)
+            fs.rmSync(d, { recursive: true, force: true });
+        for (const b of backups) {
+            fs.rmSync(b.destDir, { recursive: true, force: true });
+            fs.cpSync(b.backupDir, b.destDir, { recursive: true });
+        }
+        throw err;
+    }
+    finally {
+        for (const b of backups)
+            fs.rmSync(b.backupDir, { recursive: true, force: true });
+    }
+    // ---- manifest: fold in the newly added migrations + refreshed function
+    // file listings, dropping any stale entries for files a touched function
+    // no longer ships (e.g. one removed from a newer template). ----
+    const touchedFunctionDirs = [
+        ...createdFunctionDirs,
+        ...changedFunctions.map((fnName) => path.join(functionsDestRoot, fnName)),
+    ];
+    const touchedFunctionDirPrefixes = touchedFunctionDirs.map((d) => `${(0, install_shared_1.toRelativePosix)(cwd, d)}/`);
+    const touchedFunctionFiles = touchedFunctionDirs.flatMap((d) => (0, install_shared_1.listFilesRecursive)(d).map((f) => (0, install_shared_1.toRelativePosix)(cwd, f)));
+    const survivingOldFiles = manifest.installedFiles.filter((f) => !touchedFunctionDirPrefixes.some((prefix) => f.startsWith(prefix)));
+    const installedFiles = [
+        ...new Set([...survivingOldFiles, ...touchedFunctionFiles, ...addedMigrations]),
+    ].sort();
+    const updatedManifest = {
+        schemaVersion: manifest_1.CURRENT_SCHEMA_VERSION,
+        sdkVersion: (0, install_shared_1.readOwnPackageVersion)(),
+        modules: manifest.modules,
+        installedFiles,
+        installedTemplates: [...newInstalledTemplateIds].sort(),
+    };
+    (0, manifest_1.writeManifest)(cwd, updatedManifest);
+    printSummary(log, onWarn, {
+        addedMigrations,
+        newFunctions,
+        overwrittenFunctions: changedFunctions,
+    });
+    return {
+        manifest: updatedManifest,
+        dir,
+        upToDate: false,
+        addedMigrations,
+        newFunctions,
+        overwrittenFunctions: changedFunctions,
+    };
+}
+/**
+ * Fallback for a manifest written before `installedTemplates` existed
+ * (schemaVersion 1 `init`, Task 18): recovers the same `<module>/<name>`
+ * identity from the timestamped filenames already recorded in
+ * `installedFiles`. Non-migration entries (function files) don't match the
+ * pattern and are silently skipped.
+ */
+function reconstructInstalledTemplateIds(installedFiles) {
+    const ids = [];
+    for (const f of installedFiles) {
+        const parsed = (0, install_shared_1.parseMigrationDestFilename)(path.basename(f));
+        if (!parsed)
+            continue;
+        ids.push((0, manifest_1.migrationTemplateId)(parsed.moduleName, parsed.name));
+    }
+    return ids;
+}
+function functionDirDiffers(srcDir, destDir) {
+    const srcRel = new Set((0, install_shared_1.listFilesRecursive)(srcDir).map((f) => path.relative(srcDir, f)));
+    const destRel = new Set((0, install_shared_1.listFilesRecursive)(destDir).map((f) => path.relative(destDir, f)));
+    if (srcRel.size !== destRel.size)
+        return true;
+    for (const rel of srcRel) {
+        if (!destRel.has(rel))
+            return true;
+        const a = fs.readFileSync(path.join(srcDir, rel));
+        const b = fs.readFileSync(path.join(destDir, rel));
+        if (!a.equals(b))
+            return true;
+    }
+    return false;
+}
+function printSummary(log, onWarn, summary) {
+    log("");
+    log("community-sdk upgraded.");
+    if (summary.addedMigrations.length > 0) {
+        log(`Added ${summary.addedMigrations.length} migration(s):`);
+        for (const f of summary.addedMigrations)
+            log(`  ${f}`);
+    }
+    if (summary.newFunctions.length > 0) {
+        log(`Added ${summary.newFunctions.length} function(s): ${summary.newFunctions.join(", ")}`);
+    }
+    if (summary.overwrittenFunctions.length > 0) {
+        onWarn(`community-sdk: overwrote ${summary.overwrittenFunctions.length} function(s) with new template code — review before deploying: ${summary.overwrittenFunctions.join(", ")}`);
+    }
+    log("Next steps:");
+    if (summary.addedMigrations.length > 0) {
+        log("  1. Review the new migrations, then: supabase db push");
+    }
+    if (summary.newFunctions.length > 0 || summary.overwrittenFunctions.length > 0) {
+        log("  2. Review the function changes, then: supabase functions deploy");
+    }
+}

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/lib/index.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+"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 });
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const commander_1 = require("commander");
+const init_1 = require("./commands/init");
+const upgrade_1 = require("./commands/upgrade");
+const adopt_1 = require("./commands/adopt");
+function readOwnVersion() {
+    const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8"));
+    return pkg.version;
+}
+function parseModulesFlag(modules) {
+    return modules
+        ? modules
+            .split(",")
+            .map((m) => m.trim())
+            .filter(Boolean)
+        : undefined;
+}
+const program = new commander_1.Command();
+program
+    .name("community")
+    .description("Install and manage the Rocapine Community SDK backend (Supabase migrations + Edge Functions)")
+    .version(readOwnVersion());
+program
+    .command("init")
+    .description("Copy the community backend into a Supabase project: migrations, Edge Functions, and a community-sdk.json manifest")
+    .option("--modules <modules>", "comma-separated module list (core,push,polls,reaction,inbox) — core is always implied; defaults to all modules")
+    .option("--project-url <url>", "Supabase project URL, e.g. https://<ref>.supabase.co")
+    .option("--anon-key <key>", "Supabase anon key")
+    .option("--dir <dir>", "target Supabase directory, relative to the current directory", "supabase")
+    .action(async (opts) => {
+    try {
+        await (0, init_1.runInit)({
+            modules: parseModulesFlag(opts.modules),
+            projectUrl: opts.projectUrl,
+            anonKey: opts.anonKey,
+            dir: opts.dir,
+        });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+    }
+});
+program
+    .command("upgrade")
+    .description("Copy any new migrations/Edge Functions shipped since this repo's community-sdk.json was last written, and overwrite changed function code (with a warning)")
+    .option("--project-url <url>", "Supabase project URL, e.g. https://<ref>.supabase.co (only needed if a new migration carries a placeholder)")
+    .option("--anon-key <key>", "Supabase anon key (only needed if a new migration carries a placeholder)")
+    .option("--dir <dir>", "target Supabase directory, relative to the current directory", "supabase")
+    .action(async (opts) => {
+    try {
+        await (0, upgrade_1.runUpgrade)({
+            projectUrl: opts.projectUrl,
+            anonKey: opts.anonKey,
+            dir: opts.dir,
+        });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+    }
+});
+program
+    .command("adopt")
+    .description("Register an already-live community backend (e.g. an app that hand-rolled its own before this SDK existed) with community-sdk.json, without copying any files")
+    .requiredOption("--schema-version <n>", "the community-sdk schema version this app's live backend corresponds to")
+    .requiredOption("--modules <modules>", "comma-separated module list (core,push,polls,reaction,inbox) — core is always implied")
+    .option("--dir <dir>", "Supabase directory this app would use, relative to the current directory", "supabase")
+    .action(async (opts) => {
+    try {
+        const schemaVersion = Number(opts.schemaVersion);
+        await (0, adopt_1.runAdopt)({
+            schemaVersion,
+            modules: parseModulesFlag(opts.modules) ?? [],
+            dir: opts.dir,
+        });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+    }
+});
+program.parseAsync(process.argv).catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+});

package/lib/install-shared.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Ruled install order (controller ruling, task 18): core -> push -> polls ->
+ * reaction -> inbox. Reaction MUST land before inbox — inbox/001's reaction
+ * trigger is guarded with `to_regclass('public.post_reactions')` at install
+ * time and is never retroactively wired if the reaction module shows up
+ * later, so `reaction` needs to already exist when `inbox` runs.
+ *
+ * Shared between `init` (task 18) and `upgrade`/`adopt` (task 19) — the
+ * single source of truth for module names, order, and the function sets
+ * each module pulls in.
+ */
+export declare const MODULE_ORDER: readonly ["core", "push", "polls", "reaction", "inbox"];
+export type Module = (typeof MODULE_ORDER)[number];
+export declare function functionsForModules(modules: readonly Module[]): string[];
+/**
+ * Validates and canonicalizes a requested module list: rejects unknown
+ * names, always implies `core`, orders the result per MODULE_ORDER, and
+ * warns (non-fatally) when `inbox` is picked without `reaction`.
+ */
+export declare function resolveModules(requested: string[] | undefined, onWarn: (message: string) => void): Module[];
+/**
+ * Strips a template migration's leading numeric ordering prefix and `.sql`
+ * extension, e.g. "001_tables.sql" -> "tables". This is both the middle
+ * segment of the timestamped destination filename init/upgrade write
+ * (`<ts>_community_<module>_<name>.sql`) AND — paired with the module name —
+ * the stable identity `upgrade` diffs against (see manifest.ts
+ * `migrationTemplateId`).
+ */
+export declare function templateBaseName(templateFilename: string): string;
+export declare function migrationDestFilename(timestamp: string, moduleName: string, name: string): string;
+/**
+ * Parses a filename previously written by init/upgrade
+ * (`<ts>_community_<module>_<name>.sql`) back into its module + base name.
+ * Returns null for anything else (e.g. a function file, or a migration a
+ * user hand-wrote outside the SDK) — used by `upgrade` as a fallback when
+ * reconstructing template identity from a manifest that predates the
+ * `installedTemplates` field.
+ */
+export declare function parseMigrationDestFilename(filename: string): {
+    moduleName: string;
+    name: string;
+} | null;
+export declare function defaultTemplatesDir(): string;
+/** Asserts `templatesDir` looks like a real template tree and returns its two roots. */
+export declare function resolveTemplateRoots(templatesDir: string): {
+    migrationsSrcRoot: string;
+    functionsSrcRoot: string;
+};
+export declare function readOwnPackageVersion(): string;
+export declare function deriveProjectUrlFromConfig(dir: string): string | null;
+/**
+ * Resolves the Supabase project URL + anon key from (in order) explicit
+ * flags, `<dir>/config.toml` (URL only), or an interactive prompt — failing
+ * loudly instead of hanging when stdin is not a TTY and no `prompt`
+ * override was injected. Shared by `init` and `upgrade`, both of which only
+ * need this when a placeholder-bearing file is about to be written.
+ */
+export declare function resolveProjectCredentials(options: {
+    dir: string;
+    projectUrl?: string;
+    anonKey?: string;
+    prompt?: (question: string) => Promise<string>;
+}): Promise<{
+    projectUrl: string;
+    anonKey: string;
+}>;
+export declare function formatTimestamp(date: Date): string;
+export declare function addSeconds(date: Date, seconds: number): Date;
+export declare function listFilesRecursive(dir: string): string[];
+export declare function toRelativePosix(base: string, target: string): string;
+/** Resolves `dirRel` against `cwd`, throwing if it would escape the project root. */
+export declare function resolveContainedDir(cwd: string, dirRel: string): string;