saasaloy 0.2.0 → 0.3.0

package/README.md

@@ -91,9 +91,9 @@ Modules come in tiers. A **capability** scaffolds a workspace and sets conventio
 
 | Tier | Modules |
 |---|---|
-| Capability | `api`, `database`, `validators`, `logger`, `auth`, `admin`, `email`, `sms`, `queue`, `infra` |
-| Feature | `waitlist`, `teams`, `email-react` |
-| Provider | `email-console`, `email-cloudflare`, `email-plunk`, `logger-console`, `sms-console`, `queue-cloudflare`, `queue-memory` |
+| Capability | `api`, `database`, `validators`, `logger`, `auth`, `admin`, `email`, `sms`, `queue`, `kv`, `infra` |
+| Feature | `waitlist`, `teams`, `email-react`, `ratelimit`, `feature-flags` |
+| Provider | `email-console`, `email-cloudflare`, `email-plunk`, `logger-console`, `sms-console`, `queue-cloudflare`, `queue-memory`, `kv-cloudflare`, `kv-memory` |
 | Driver | `database-d1`, `database-postgres` |
 
 `saasaloy add <name> --dry-run` prints what a module would do to your project before it does it. The one-table map of every module, what it gives you, and what it depends on is on the [Modules](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/modules.md) page.
@@ -113,8 +113,9 @@ A few modules need something the free tier does not cover:
 | `database-postgres` | a Postgres server reachable from a Worker, with its URL in `DATABASE_URL`. Install instead of `database-d1`, never alongside |
 | `sms` | a third-party SMS account for any real send. Cloudflare has no SMS product. `sms-console` is free |
 | `queue-cloudflare` | a Workers paid plan, and the two queues created once with `wrangler queues create`. Install `queue-memory` instead for local work |
+| `kv-cloudflare` | a Workers KV namespace created with `wrangler kv namespace create`, and its id pasted into `wrangler.jsonc`. `kv-memory` needs nothing |
 
-The local providers (`email-console`, `sms-console`, `logger-console`, `queue-memory`) log or run inline instead of calling a service, so local development needs no plan, domain, or key. Details for each are in the [Reference](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/reference.md#email-providers).
+The local providers (`email-console`, `sms-console`, `logger-console`, `queue-memory`, `kv-memory`) log or run inline instead of calling a service, so local development needs no plan, domain, or key. Details for each are in the [Reference](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/reference.md#email-providers).
 
 ## Deploy
 

package/dist/index.js

@@ -490,7 +490,7 @@ function insertChainedRoute(source, patch) {
     return source;
   }
   if (!(patch.import.name in mod.imports)) {
-    mod.imports.$add({
+    mod.imports.$prepend({
       from: patch.import.from,
       imported: patch.import.name,
       local: patch.import.name
@@ -864,6 +864,193 @@ function toDiff(before, after, filename) {
   return patch;
 }
 
+// src/lib/patch/drizzle-column.ts
+import { generateCode as generateCode2, parseModule as parseModule3 } from "magicast";
+var COLUMNS_ARG = 1;
+function insertDrizzleColumn(source, patch) {
+  const mod = parseModule3(source);
+  const columns = columnsObject(mod, patch);
+  if (!columns) {
+    return source;
+  }
+  if (indexOfColumn(columns, patch.column) !== -1) {
+    return source;
+  }
+  parseExpressionNode(patch.value);
+  if (patch.import && foreignBinding(mod.imports, patch.import)) {
+    return source;
+  }
+  const withColumn = spliceColumn(source, columns, patch);
+  if (!withColumn) {
+    return source;
+  }
+  return addImport(withColumn, patch);
+}
+function removeDrizzleColumn(source, patch) {
+  const mod = parseModule3(source);
+  const columns = columnsObject(mod, patch);
+  const at = columns ? indexOfColumn(columns, patch.column) : -1;
+  if (!columns || at === -1) {
+    return source;
+  }
+  if (valueDrift(columns, at, patch)) {
+    return source;
+  }
+  if (patch.import && removeBindingConflict2(mod.imports, patch.import)) {
+    return source;
+  }
+  const withoutColumn = cutColumn(source, columns, at);
+  if (!withoutColumn) {
+    return source;
+  }
+  return dropImport(withoutColumn, patch);
+}
+function spliceColumn(source, columns, patch) {
+  const last = columns.properties.at(-1);
+  const end = offset(last, "end");
+  if (end === void 0) {
+    return void 0;
+  }
+  const indent = indentOf(source, offset(last, "start") ?? end);
+  const comma = source.slice(end).trimStart().startsWith(",");
+  const at = comma ? end + source.slice(end).indexOf(",") + 1 : end;
+  const line = `${indent}${patch.column}: ${patch.value}`;
+  return comma ? `${source.slice(0, at)}
+${line},${source.slice(at)}` : `${source.slice(0, at)},
+${line}${source.slice(at)}`;
+}
+function cutColumn(source, columns, at) {
+  const property = columns.properties[at];
+  const start = offset(property, "start");
+  const end = offset(property, "end");
+  if (start === void 0 || end === void 0) {
+    return void 0;
+  }
+  const from = source.lastIndexOf("\n", start) + 1;
+  const after = source.indexOf("\n", end);
+  const to = after === -1 ? source.length : after + 1;
+  const head = source.slice(from, start);
+  const tail = source.slice(end, to);
+  if (head.trim() !== "" || tail.replace(/^,/u, "").trim() !== "") {
+    return void 0;
+  }
+  return source.slice(0, from) + source.slice(to);
+}
+function indentOf(source, at) {
+  const from = source.lastIndexOf("\n", at) + 1;
+  return /^[\t ]*/u.exec(source.slice(from, at))?.[0] ?? "";
+}
+function offset(node, end) {
+  const value = node?.[end];
+  return typeof value === "number" ? value : void 0;
+}
+function addImport(source, patch) {
+  if (!patch.import) {
+    return source;
+  }
+  const mod = parseModule3(source);
+  if (patch.import.name in mod.imports) {
+    return source;
+  }
+  mod.imports.$prepend({
+    from: patch.import.from,
+    imported: patch.import.name,
+    local: patch.import.name
+  });
+  return print(source, mod);
+}
+function dropImport(source, patch) {
+  if (!patch.import) {
+    return source;
+  }
+  const mod = parseModule3(source);
+  const program = mod.$ast;
+  if (!(patch.import.name in mod.imports) || isReferenced(program, patch.import.name)) {
+    return source;
+  }
+  delete mod.imports[patch.import.name];
+  return print(source, mod);
+}
+function drizzleColumnInsertRefusal(source, patch) {
+  const mod = parseModule3(source);
+  if (!mod.exports[patch.exportName]) {
+    return `drizzle-column could not find an export named ${JSON.stringify(patch.exportName)}`;
+  }
+  const columns = columnsObject(mod, patch);
+  if (!columns) {
+    return `${JSON.stringify(patch.exportName)} is not a Drizzle table call with a columns object as its second argument`;
+  }
+  const at = indexOfColumn(columns, patch.column);
+  if (at !== -1 && valueDrift(columns, at, patch)) {
+    return `${JSON.stringify(patch.column)} on ${JSON.stringify(patch.exportName)} holds ${printed(columns, at)}, not the ${patch.value} this patch adds`;
+  }
+  if (at === -1 && patch.import) {
+    return insertBindingConflict2(mod.imports, patch);
+  }
+  return void 0;
+}
+function drizzleColumnRemoveRefusal(source, patch) {
+  const mod = parseModule3(source);
+  const columns = columnsObject(mod, patch);
+  const at = columns ? indexOfColumn(columns, patch.column) : -1;
+  if (!columns || at === -1) {
+    return void 0;
+  }
+  return valueDrift(columns, at, patch) ?? (patch.import ? removeBindingConflict2(mod.imports, patch.import) : void 0);
+}
+function columnsObject(mod, patch) {
+  const { exports } = mod;
+  const node = exports[patch.exportName]?.$args?.[COLUMNS_ARG]?.$ast;
+  return node?.type === "ObjectExpression" ? node : void 0;
+}
+function indexOfColumn(columns, column) {
+  return columns.properties.findIndex(
+    (property) => property.key?.name === column || property.key?.value === column
+  );
+}
+function parseExpressionNode(code) {
+  const declaration = parseModule3(`const __drizzleColumn = ${code};`).$ast;
+  const init = declaration.body.length === 1 ? declaration.body[0]?.declarations?.[0]?.init : void 0;
+  if (!init) {
+    throw new TypeError(
+      `drizzle-column value is not a single expression: ${JSON.stringify(code)}`
+    );
+  }
+  return init;
+}
+function printed(columns, at) {
+  return generateCode2(columns.properties[at]?.value).code;
+}
+function valueDrift(columns, at, patch) {
+  if (collapse(printed(columns, at)) === collapse(patch.value)) {
+    return void 0;
+  }
+  return `${JSON.stringify(patch.column)} on ${JSON.stringify(patch.exportName)} reads ${printed(columns, at)} now, not the ${patch.value} that was applied`;
+}
+function collapse(code) {
+  return code.replaceAll(/\s+/gu, "");
+}
+function insertBindingConflict2(imports, patch) {
+  const held = patch.import ? foreignBinding(imports, patch.import) : void 0;
+  if (!held || !patch.import) {
+    return void 0;
+  }
+  return `${describeBinding(patch.import.name, held)}, so ${JSON.stringify(patch.column)} would read the wrong builder`;
+}
+function removeBindingConflict2(imports, want) {
+  const held = foreignBinding(imports, want);
+  if (!held) {
+    return void 0;
+  }
+  return `${describeBinding(want.name, held)} now, not from ${JSON.stringify(want.from)}, so the column and its import are not the ones that were applied`;
+}
+function print(source, mod) {
+  return keepTerminator(
+    source,
+    generateCode2(mod, { format: { objectCurlySpacing: true } }).code
+  );
+}
+
 // src/lib/patch/jsonc.ts
 import {
   applyEdits,
@@ -1138,9 +1325,9 @@ function upsertPackageJsonScript(source, patch) {
 }
 
 // src/lib/patch/ts-module.ts
-import { builders as builders2, generateCode as generateCode2, parseModule as parseModule3 } from "magicast";
+import { builders as builders2, generateCode as generateCode3, parseModule as parseModule4 } from "magicast";
 function insertIntoPluginArray(source, patch) {
-  const mod = parseModule3(source);
+  const mod = parseModule4(source);
   const exported = mod.exports[patch.exportName];
   const callArg = exported?.$args?.[0];
   if (!callArg) {
@@ -1151,7 +1338,7 @@ function insertIntoPluginArray(source, patch) {
     return source;
   }
   if (!(patch.import.name in mod.imports)) {
-    mod.imports.$add({
+    mod.imports.$prepend({
       from: patch.import.from,
       imported: patch.import.name,
       local: patch.import.name
@@ -1163,10 +1350,10 @@ function insertIntoPluginArray(source, patch) {
   } else {
     callArg[patch.arrayProp] = [newCall];
   }
-  return print(source, mod);
+  return print2(source, mod);
 }
 function removeFromPluginArray(source, patch) {
-  const mod = parseModule3(source);
+  const mod = parseModule4(source);
   const exported = mod.exports[patch.exportName];
   const callArg = exported?.$args?.[0];
   if (!callArg) {
@@ -1183,7 +1370,7 @@ function removeFromPluginArray(source, patch) {
   if (argumentDrift(array[index], patch)) {
     return source;
   }
-  if (removeBindingConflict2(mod.imports, patch)) {
+  if (removeBindingConflict3(mod.imports, patch)) {
     return source;
   }
   array.splice(index, 1);
@@ -1191,10 +1378,10 @@ function removeFromPluginArray(source, patch) {
   if (patch.import.name in mod.imports && !isReferenced(program, patch.import.name)) {
     delete mod.imports[patch.import.name];
   }
-  return print(source, mod);
+  return print2(source, mod);
 }
 function pluginArrayRemoveRefusal(source, patch) {
-  const mod = parseModule3(source);
+  const mod = parseModule4(source);
   const callArg = mod.exports[patch.exportName]?.$args?.[0];
   if (!callArg) {
     return void 0;
@@ -1207,12 +1394,12 @@ function pluginArrayRemoveRefusal(source, patch) {
   if (index === -1) {
     return void 0;
   }
-  return argumentDrift(array[index], patch) ?? removeBindingConflict2(mod.imports, patch);
+  return argumentDrift(array[index], patch) ?? removeBindingConflict3(mod.imports, patch);
 }
-function print(source, mod) {
+function print2(source, mod) {
   return keepTerminator(
     source,
-    generateCode2(mod, { format: { objectCurlySpacing: true } }).code
+    generateCode3(mod, { format: { objectCurlySpacing: true } }).code
   );
 }
 function findCallIndex(array, call) {
@@ -1230,7 +1417,7 @@ function argumentDrift(element, patch) {
   }
   return `${patch.call}() in ${JSON.stringify(patch.arrayProp)} takes arguments now, not the bare call that was applied`;
 }
-function removeBindingConflict2(imports, patch) {
+function removeBindingConflict3(imports, patch) {
   const held = foreignBinding(imports, patch.import);
   if (!held) {
     return void 0;
@@ -1245,6 +1432,7 @@ function isFunctionCall(value) {
 var PATCH_KIND_KEYS = {
   "chained-route": true,
   "const-array": true,
+  "drizzle-column": true,
   "package-json-dependency": true,
   "package-json-script": true,
   "plugin-array": true,
@@ -1281,6 +1469,9 @@ function applyCodemod(source, patch) {
     case "const-array": {
       return insertIntoConstArray(source, patch);
     }
+    case "drizzle-column": {
+      return insertDrizzleColumn(source, patch);
+    }
     case "wrangler-binding": {
       return upsertWranglerBinding(source, patch);
     }
@@ -1305,6 +1496,7 @@ function applyCodemod(source, patch) {
 var INVERSES = {
   "chained-route": removeChainedRoute,
   "const-array": removeFromConstArray,
+  "drizzle-column": removeDrizzleColumn,
   "plugin-array": removeFromPluginArray,
   "wrangler-binding": removeWranglerBinding
 };
@@ -1328,10 +1520,12 @@ function reversePatch(source, patch, filename) {
 var REFUSALS = {
   "chained-route": chainedRouteInsertRefusal,
   "const-array": constArrayInsertRefusal,
+  "drizzle-column": drizzleColumnInsertRefusal,
   "package-json-script": packageJsonScriptRefusal
 };
 var REVERSAL_REFUSALS = {
   "chained-route": chainedRouteRemoveRefusal,
+  "drizzle-column": drizzleColumnRemoveRefusal,
   "plugin-array": pluginArrayRemoveRefusal,
   "wrangler-binding": wranglerBindingRemoveRefusal
 };
@@ -3687,7 +3881,7 @@ import { fileURLToPath as fileURLToPath3 } from "url";
 // package.json
 var package_default = {
   name: "saasaloy",
-  version: "0.2.0",
+  version: "0.3.0",
   description: "Composable SaaS accelerator kit.",
   keywords: [
     "saas",
@@ -3738,19 +3932,19 @@ var package_default = {
   },
   devDependencies: {
     "@release-it/conventional-changelog": "12.0.0",
-    "@types/node": "26.1.1",
-    "@vitest/coverage-v8": "4.1.10",
+    "@types/node": "26.4.1",
+    "@vitest/coverage-v8": "5.0.0",
     "release-it": "21.0.2",
     tsup: "8.5.1",
-    vitest: "4.1.10"
+    vitest: "5.0.0"
   },
   dependencies: {
     "@clack/prompts": "1.7.0",
-    ajv: "8.17.1",
+    ajv: "8.20.0",
     diff: "9.0.0",
-    giget: "3.3.0",
+    giget: "3.3.1",
     "jsonc-parser": "3.3.1",
-    magicast: "0.5.3",
+    magicast: "0.5.4",
     picocolors: "1.1.1"
   }
 };
@@ -4055,6 +4249,8 @@ async function baseUpdateInput(args) {
 }
 
 // src/lib/doctor.ts
+import { findNodeAtLocation as findNodeAtLocation4, getNodeValue as getNodeValue4, parseTree as parseTree4 } from "jsonc-parser";
+import { parseModule as parseModule5 } from "magicast";
 import { readFile as readFile13 } from "fs/promises";
 import { basename, dirname as dirname6, join as join11, posix as posix7, resolve as resolve3 } from "path";
 var SKILL_PREFIX = "saasaloy-";
@@ -4311,6 +4507,200 @@ function checkProject(args) {
     )
   );
 }
+var KV_INDEX_FILE = "packages/kv/src/index.ts";
+var WRANGLER_FILE = "apps/api/wrangler.jsonc";
+var CLOUDFLARE_KV_MODULE = "kv-cloudflare";
+function checkPolicyBindings(args) {
+  const bound = new Set(rateLimitBindingNames(args.wrangler));
+  const findings = [];
+  for (const entry of registeredPolicies(args)) {
+    if (entry.name === void 0) {
+      findings.push(
+        finding(
+          "ratelimit",
+          `/policies/${String(entry.index)}`,
+          `the policy at index ${String(entry.index)} of the \`policies\` array in ${KV_INDEX_FILE} has no name this check can read, so its RL_<NAME> binding in ${WRANGLER_FILE} was not checked. Write it as \`definePolicy({ name: "..." })\`, or as a factory exported from a file under packages/kv/src/policies/.`
+        )
+      );
+      continue;
+    }
+    if (!bound.has(bindingFor(entry.name))) {
+      findings.push(
+        finding(
+          "ratelimit",
+          `/policies/${entry.name}`,
+          `policy "${entry.name}" has no ${bindingFor(entry.name)} entry in ${WRANGLER_FILE} \u2014 consume({ policy: "${entry.name}" }) throws not_supported on the first request. Add the binding, or drop the policy from ${KV_INDEX_FILE}.`
+        )
+      );
+    }
+  }
+  return findings;
+}
+function bindingFor(policy) {
+  return `RL_${policy.toUpperCase()}`;
+}
+function rateLimitBindingNames(wrangler) {
+  const root = parseTree4(wrangler);
+  if (!root) {
+    return [];
+  }
+  const node = findNodeAtLocation4(root, ["ratelimits"]);
+  if (node?.type !== "array") {
+    return [];
+  }
+  const names = [];
+  for (const child of node.children ?? []) {
+    const value = getNodeValue4(child);
+    const name = asRecord(value).name;
+    if (typeof name === "string") {
+      names.push(name);
+    }
+  }
+  return names;
+}
+function registeredPolicies(args) {
+  let mod;
+  try {
+    mod = parseModule5(args.index);
+  } catch {
+    return [];
+  }
+  const callArg = mod.exports.kv?.$args?.[0];
+  const array = callArg?.policies;
+  if (!Array.isArray(array)) {
+    return [];
+  }
+  const imports = mod.imports;
+  const policies = [];
+  for (let i = 0; i < array.length; i++) {
+    const element = array[i];
+    policies.push({ index: i, name: policyNameOf(element, args, imports) });
+  }
+  return policies;
+}
+function policyNameOf(element, args, imports) {
+  const callee = calleeName(element);
+  if (callee === void 0) {
+    return void 0;
+  }
+  const inline = inlineNameArgument(element);
+  if (inline !== void 0) {
+    return inline;
+  }
+  const from = imports[callee]?.from;
+  const source = typeof from === "string" ? args.policySources[from] : void 0;
+  return source === void 0 ? void 0 : policyNameIn(source, callee);
+}
+function inlineNameArgument(element) {
+  const args = element.$args;
+  if (!Array.isArray(args)) {
+    return void 0;
+  }
+  const name = asRecord(args[0]).name;
+  return typeof name === "string" ? name : void 0;
+}
+function calleeName(element) {
+  if (typeof element !== "object" || element === null) {
+    return void 0;
+  }
+  const record = element;
+  return record.$type === "function-call" && typeof record.$callee === "string" ? record.$callee : void 0;
+}
+function policyNameIn(source, callee) {
+  let program;
+  try {
+    program = parseModule5(source).$ast;
+  } catch {
+    return void 0;
+  }
+  const factory = findNode(
+    program,
+    (node) => (node.type === "FunctionDeclaration" || node.type === "VariableDeclarator") && asRecord(node.id).name === callee
+  );
+  if (!factory) {
+    return void 0;
+  }
+  const call = findNode(
+    factory,
+    (node) => node.type === "CallExpression" && asRecord(node.callee).name === "definePolicy"
+  );
+  const argument = asArray(call?.arguments)[0];
+  const property = asArray(asRecord(argument).properties).find(
+    (entry) => asRecord(asRecord(entry).key).name === "name"
+  );
+  const value = asRecord(asRecord(property).value).value;
+  return typeof value === "string" ? value : void 0;
+}
+function findNode(root, accept) {
+  if (Array.isArray(root)) {
+    for (const child of root) {
+      const found = findNode(child, accept);
+      if (found) {
+        return found;
+      }
+    }
+    return void 0;
+  }
+  if (typeof root !== "object" || root === null) {
+    return void 0;
+  }
+  const node = root;
+  if (typeof node.type === "string") {
+    const typed = node;
+    if (accept(typed)) {
+      return typed;
+    }
+  }
+  for (const [key, value] of Object.entries(node)) {
+    if (key === "loc" || key === "comments" || key === "original") {
+      continue;
+    }
+    const found = findNode(value, accept);
+    if (found) {
+      return found;
+    }
+  }
+  return void 0;
+}
+async function readPolicyState(root, installed) {
+  if (!installed.includes(CLOUDFLARE_KV_MODULE)) {
+    return void 0;
+  }
+  const index = await readIfPresent(resolveWithinRoot(root, KV_INDEX_FILE));
+  const wrangler = await readIfPresent(resolveWithinRoot(root, WRANGLER_FILE));
+  if (index === void 0 || wrangler === void 0) {
+    return void 0;
+  }
+  const policySources = {};
+  for (const specifier of relativeImportsIn(index)) {
+    const source = await readIfPresent(
+      resolveWithinRoot(
+        root,
+        posix7.join(posix7.dirname(KV_INDEX_FILE), `${specifier}.ts`)
+      )
+    );
+    if (source !== void 0) {
+      policySources[specifier] = source;
+    }
+  }
+  return { index, policySources, wrangler };
+}
+function relativeImportsIn(index) {
+  let mod;
+  try {
+    mod = parseModule5(index);
+  } catch {
+    return [];
+  }
+  const imports = mod.imports;
+  const specifiers = /* @__PURE__ */ new Set();
+  for (const held of Object.values(imports)) {
+    if (typeof held?.from === "string" && held.from.startsWith(".")) {
+      specifiers.add(held.from);
+    }
+  }
+  return [...specifiers];
+}
 async function resolveDoctorTarget(path) {
   const dir = resolve3(path);
   if (await pathExists(join11(dir, "registry-item.json"))) {
@@ -4456,9 +4846,11 @@ async function reportProject(path) {
     seedFiles: (await readBaseDeclaration(await baseTemplateDir())).seedFiles
   });
   note2(wrapForNote(renderBase(base)), "Base");
+  const policyState = await readPolicyState(path, config.installed);
   const findings = [
     ...checkProject({ config, manifest }),
-    ...checkPartialInstalls({ installed: config.installed, manifest })
+    ...checkPartialInstalls({ installed: config.installed, manifest }),
+    ...policyState ? checkPolicyBindings(policyState) : []
   ];
   if (findings.length === 0) {
     const count = config.installed.length;