@rocapine/community 0.2.0 → 0.3.2

package/README.md

@@ -61,6 +61,11 @@ 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).
 
+`--add-modules <modules>` installs one or more modules not yet in
+`community-sdk.json` on top of the existing backend (comma-separated, same
+parsing as `init --modules`) — e.g. `upgrade --add-modules translation` to
+add the translation module to an already-initialized app.
+
 ## `adopt`
 
 ```bash

package/lib/commands/init.js

@@ -110,7 +110,7 @@ async function runInit(options = {}) {
             if (!fs.existsSync(srcDir))
                 continue;
             const destDir = path.join(functionsDestRoot, fnName);
-            fs.cpSync(srcDir, destDir, { recursive: true });
+            fs.cpSync(srcDir, destDir, { recursive: true, filter: install_shared_1.isShippedFunctionFile });
             writtenPaths.push(...(0, install_shared_1.listFilesRecursive)(destDir));
         }
     }
@@ -148,5 +148,8 @@ function printNextSteps(log, modules) {
     if (modules.includes("push")) {
         log("     push module: EXPO_ACCESS_TOKEN (only if your Expo project enforces Enhanced Security for push); COMMUNITY_PUSH_COPY (optional per-locale copy)");
     }
+    if (modules.includes("translation")) {
+        log('     translation module: COMMUNITY_TRANSLATION_LOCALES="en,es-419,..." (required, same list as modules.translation.locales in the app); optional: COMMUNITY_TRANSLATION_MODEL, COMMUNITY_TRANSLATION_STYLE');
+    }
     log("  3. Deploy the Edge Functions: supabase functions deploy");
 }

package/lib/commands/upgrade.d.ts

@@ -9,6 +9,8 @@ export interface UpgradeOptions {
     cwd?: string;
     /** Source of the migrations/ + functions/ trees. Defaults to the shipped templates. */
     templatesDir?: string;
+    /** Module names to install on top of what's already in the manifest — validated, ordered and merged via resolveModules, same rules as `init --modules` (unknown names throw, dependency gaps warn). */
+    addModules?: 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. */
@@ -23,6 +25,8 @@ export interface UpgradeResult {
     dir: string;
     /** True when nothing needed to change — no new migrations, no function drift. */
     upToDate: boolean;
+    /** Modules newly added by `addModules` (not already in the manifest). Empty when `addModules` was omitted or every named module was already installed. */
+    addedModules: string[];
     /** 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. */

package/lib/commands/upgrade.js

@@ -54,10 +54,15 @@ async function runUpgrade(options = {}) {
     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));
+    // By default only modules the app already has installed are diffed/re-synced.
+    // `addModules` extends that list through the same validation/ordering/warning
+    // rules `init --modules` uses; left empty/undefined, behaviour here must stay
+    // byte-identical to the pre-`addModules` path (no resolveModules call, no
+    // spurious warnings for e.g. an existing inbox-without-reaction install).
+    const canonicalModules = options.addModules && options.addModules.length > 0
+        ? (0, install_shared_1.resolveModules)([...manifest.modules, ...options.addModules], onWarn)
+        : install_shared_1.MODULE_ORDER.filter((m) => manifest.modules.includes(m));
+    const addedModules = canonicalModules.filter((m) => !manifest.modules.includes(m));
     const installedTemplateIds = new Set(manifest.installedTemplates ?? reconstructInstalledTemplateIds(manifest.installedFiles));
     const pending = [];
     for (const moduleName of canonicalModules) {
@@ -101,6 +106,7 @@ async function runUpgrade(options = {}) {
             manifest,
             dir,
             upToDate: true,
+            addedModules,
             addedMigrations: [],
             newFunctions: [],
             overwrittenFunctions: [],
@@ -162,7 +168,10 @@ async function runUpgrade(options = {}) {
         }
         for (const fnName of newFunctions) {
             const destDir = path.join(functionsDestRoot, fnName);
-            fs.cpSync(path.join(functionsSrcRoot, fnName), destDir, { recursive: true });
+            fs.cpSync(path.join(functionsSrcRoot, fnName), destDir, {
+                recursive: true,
+                filter: install_shared_1.isShippedFunctionFile,
+            });
             createdFunctionDirs.push(destDir);
         }
         for (const fnName of changedFunctions) {
@@ -171,7 +180,10 @@ async function runUpgrade(options = {}) {
             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 });
+            fs.cpSync(path.join(functionsSrcRoot, fnName), destDir, {
+                recursive: true,
+                filter: install_shared_1.isShippedFunctionFile,
+            });
         }
     }
     catch (err) {
@@ -205,12 +217,15 @@ async function runUpgrade(options = {}) {
     const updatedManifest = {
         schemaVersion: manifest_1.CURRENT_SCHEMA_VERSION,
         sdkVersion: (0, install_shared_1.readOwnPackageVersion)(),
-        modules: manifest.modules,
+        // Only --add-modules rewrites the module list; a plain upgrade keeps the
+        // manifest's own (order and any entry this CLI doesn't know).
+        modules: options.addModules && options.addModules.length > 0 ? canonicalModules : manifest.modules,
         installedFiles,
         installedTemplates: [...newInstalledTemplateIds].sort(),
     };
     (0, manifest_1.writeManifest)(cwd, updatedManifest);
     printSummary(log, onWarn, {
+        addedModules,
         addedMigrations,
         newFunctions,
         overwrittenFunctions: changedFunctions,
@@ -219,6 +234,7 @@ async function runUpgrade(options = {}) {
         manifest: updatedManifest,
         dir,
         upToDate: false,
+        addedModules,
         addedMigrations,
         newFunctions,
         overwrittenFunctions: changedFunctions,
@@ -242,8 +258,11 @@ function reconstructInstalledTemplateIds(installedFiles) {
     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)));
+    const rel = (dir) => new Set((0, install_shared_1.listFilesRecursive)(dir)
+        .filter(install_shared_1.isShippedFunctionFile)
+        .map((f) => path.relative(dir, f)));
+    const srcRel = rel(srcDir);
+    const destRel = rel(destDir);
     if (srcRel.size !== destRel.size)
         return true;
     for (const rel of srcRel) {
@@ -259,6 +278,9 @@ function functionDirDiffers(srcDir, destDir) {
 function printSummary(log, onWarn, summary) {
     log("");
     log("community-sdk upgraded.");
+    if (summary.addedModules.length > 0) {
+        log(`Added module(s): ${summary.addedModules.join(", ")}`);
+    }
     if (summary.addedMigrations.length > 0) {
         log(`Added ${summary.addedMigrations.length} migration(s):`);
         for (const f of summary.addedMigrations)
@@ -277,4 +299,7 @@ function printSummary(log, onWarn, summary) {
     if (summary.newFunctions.length > 0 || summary.overwrittenFunctions.length > 0) {
         log("  2. Review the function changes, then: supabase functions deploy");
     }
+    if (summary.addedModules.includes("translation")) {
+        log('  3. translation module: COMMUNITY_TRANSLATION_LOCALES="en,es-419,..." (required, same list as modules.translation.locales in the app); optional: COMMUNITY_TRANSLATION_MODEL, COMMUNITY_TRANSLATION_STYLE');
+    }
 }

package/lib/index.js

@@ -81,12 +81,14 @@ program
 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("--add-modules <modules>", "comma-separated module list to install on top of what's already in community-sdk.json (e.g. translation)")
     .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)({
+            addModules: parseModulesFlag(opts.addModules),
             projectUrl: opts.projectUrl,
             anonKey: opts.anonKey,
             dir: opts.dir,

package/lib/install-shared.d.ts

@@ -1,15 +1,16 @@
 /**
  * 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.
+ * reaction -> inbox -> translation. 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 declare const MODULE_ORDER: readonly ["core", "push", "polls", "reaction", "inbox", "translation"];
 export type Module = (typeof MODULE_ORDER)[number];
 export declare function functionsForModules(modules: readonly Module[]): string[];
 /**
@@ -66,6 +67,9 @@ export declare function resolveProjectCredentials(options: {
 }>;
 export declare function formatTimestamp(date: Date): string;
 export declare function addSeconds(date: Date, seconds: number): Date;
+/** Deno test files (`*_test.ts`) stay in the repo: never copied into a host's
+ * functions, and ignored when diffing a host's function dir. */
+export declare function isShippedFunctionFile(file: string): boolean;
 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. */

package/lib/install-shared.js

@@ -46,6 +46,7 @@ exports.deriveProjectUrlFromConfig = deriveProjectUrlFromConfig;
 exports.resolveProjectCredentials = resolveProjectCredentials;
 exports.formatTimestamp = formatTimestamp;
 exports.addSeconds = addSeconds;
+exports.isShippedFunctionFile = isShippedFunctionFile;
 exports.listFilesRecursive = listFilesRecursive;
 exports.toRelativePosix = toRelativePosix;
 exports.resolveContainedDir = resolveContainedDir;
@@ -54,16 +55,17 @@ const path = __importStar(require("node:path"));
 const promises_1 = require("node:readline/promises");
 /**
  * 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.
+ * reaction -> inbox -> translation. 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.
  */
-exports.MODULE_ORDER = ["core", "push", "polls", "reaction", "inbox"];
+exports.MODULE_ORDER = ["core", "push", "polls", "reaction", "inbox", "translation"];
 const ALWAYS_FUNCTIONS = [
     "moderate-one",
     "daily-moderation",
@@ -73,6 +75,7 @@ const ALWAYS_FUNCTIONS = [
 ];
 const PUSH_FUNCTIONS = ["notify-like", "notify-comment", "broadcast-post"];
 const REACTION_FUNCTIONS = ["notify-reaction"];
+const TRANSLATION_FUNCTIONS = ["translate-one", "daily-translation"];
 function functionsForModules(modules) {
     const set = new Set(ALWAYS_FUNCTIONS);
     if (modules.includes("push"))
@@ -81,6 +84,9 @@ function functionsForModules(modules) {
     if (modules.includes("reaction"))
         for (const f of REACTION_FUNCTIONS)
             set.add(f);
+    if (modules.includes("translation"))
+        for (const f of TRANSLATION_FUNCTIONS)
+            set.add(f);
     return [...set];
 }
 /**
@@ -102,6 +108,9 @@ function resolveModules(requested, onWarn) {
     if (canonicalModules.includes("inbox") && !canonicalModules.includes("reaction")) {
         onWarn("community-sdk: module 'inbox' selected without 'reaction' — reaction notifications won't appear in the inbox until the reaction module is also installed.");
     }
+    if (canonicalModules.includes("translation") && !canonicalModules.includes("polls")) {
+        onWarn("community-sdk: module 'translation' selected without 'polls' — poll option labels won't be translated (posts and comments are).");
+    }
     return canonicalModules;
 }
 /**
@@ -228,6 +237,11 @@ function formatTimestamp(date) {
 function addSeconds(date, seconds) {
     return new Date(date.getTime() + seconds * 1000);
 }
+/** Deno test files (`*_test.ts`) stay in the repo: never copied into a host's
+ * functions, and ignored when diffing a host's function dir. */
+function isShippedFunctionFile(file) {
+    return !file.endsWith("_test.ts");
+}
 function listFilesRecursive(dir) {
     const entries = fs.readdirSync(dir, { withFileTypes: true });
     const files = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rocapine/community",
-  "version": "0.2.0",
+  "version": "0.3.2",
   "description": "CLI to install, upgrade and adopt the Rocapine Community SDK's Supabase backend (migrations, Edge Functions) into a project.",
   "license": "MIT",
   "repository": {

package/templates/functions/_shared/client.ts

@@ -11,6 +11,31 @@ export function adminClient() {
   return createClient(SUPABASE_URL, Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!);
 }
 
+// Reads every row of a query page by page: PostgREST caps one response at the
+// project's max_rows (Supabase default 1000), so a single select silently
+// truncates. `page` must apply a deterministic order and `.range(from, to)`.
+// Stops on the first short page. A failed page logs and returns what was read
+// so far — for a broadcast, a partial send beats none (re-running would
+// double-send to the pages already pushed).
+export async function fetchAllRows<T>(
+  page: (
+    from: number,
+    to: number,
+  ) => PromiseLike<{ data: T[] | null; error: { message: string } | null }>,
+  pageSize = 1000,
+): Promise<T[]> {
+  const rows: T[] = [];
+  for (let from = 0; ; from += pageSize) {
+    const { data, error } = await page(from, from + pageSize - 1);
+    if (error) {
+      console.error(`fetchAllRows: page failed, keeping ${rows.length} rows`, error.message);
+      return rows;
+    }
+    rows.push(...(data ?? []));
+    if ((data?.length ?? 0) < pageSize) return rows;
+  }
+}
+
 // The gateway (verify_jwt) has already validated the bearer's signature, so
 // only the role claim needs checking here. An exact string match against the
 // injected SUPABASE_SERVICE_ROLE_KEY broke when a project migrated to the new

package/templates/functions/_shared/push.ts

@@ -1,6 +1,8 @@
 // Shared Expo push sender. Used by notify-comment, notify-like,
 // notify-reaction and broadcast-post (push module).
 
+import { runPool } from "./translation.ts";
+
 export interface ExpoPushMessage {
   to: string;
   title: string;
@@ -11,21 +13,29 @@ export interface ExpoPushMessage {
   badge?: number;
 }
 
-// Sends in chunks of 100 (Expo API limit). Best-effort: push failures must
-// never fail the calling webhook. Projects with Enhanced Security for push
-// must set the EXPO_ACCESS_TOKEN function secret.
-export async function sendExpoPushBatch(messages: ExpoPushMessage[]): Promise<void> {
+// Sends in chunks of 100 (Expo API limit), 4 requests in flight at a time, each
+// aborted after 10 s so one hung request can't stall a large broadcast past the
+// function's wall-clock limit. Best-effort: push failures must never fail the
+// calling webhook. Projects with Enhanced Security for push must set the
+// EXPO_ACCESS_TOKEN function secret. `fetchImpl`/`concurrency` are for tests.
+export async function sendExpoPushBatch(
+  messages: ExpoPushMessage[],
+  opts: { fetchImpl?: typeof fetch; concurrency?: number } = {},
+): Promise<void> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
   const headers: Record<string, string> = { "Content-Type": "application/json" };
   const accessToken = Deno.env.get("EXPO_ACCESS_TOKEN");
   if (accessToken) headers["Authorization"] = `Bearer ${accessToken}`;
-  for (let i = 0; i < messages.length; i += 100) {
-    const chunk = messages.slice(i, i + 100);
-    await fetch("https://exp.host/--/api/v2/push/send", {
+  const chunks: ExpoPushMessage[][] = [];
+  for (let i = 0; i < messages.length; i += 100) chunks.push(messages.slice(i, i + 100));
+  await runPool(chunks, opts.concurrency ?? 4, (chunk) =>
+    fetchImpl("https://exp.host/--/api/v2/push/send", {
       method: "POST",
       headers,
       body: JSON.stringify(chunk.length === 1 ? chunk[0] : chunk),
-    }).catch(() => {});
-  }
+      signal: AbortSignal.timeout(10_000),
+    }).catch(() => {}),
+  );
 }
 
 export async function sendExpoPush(message: ExpoPushMessage): Promise<void> {