saasaloy 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,154 @@
+<!-- Generated by scripts/build-cli-readme.ts from the repo root README.md. Edit that file. -->
+
+# Saasaloy
+
+**Open source, composable SaaS starter kit for Cloudflare.** A CLI plus a module registry, not a boilerplate. Think shadcn/ui for a full-stack SaaS: you scaffold a small base, then copy in the API, database, auth, and product features one command at a time, as source files you own.
+
+[![npm version](https://img.shields.io/npm/v/saasaloy)](https://www.npmjs.com/package/saasaloy)
+[![CI](https://github.com/mimukit/saasaloy/actions/workflows/ci.yml/badge.svg)](https://github.com/mimukit/saasaloy/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.md)
+
+## Why Saasaloy
+
+- **You own the code.** Nothing is imported from a Saasaloy package at runtime. The CLI writes files into your repo and gets out of the way.
+- **Start small, add on demand.** `saasaloy init` gives you a landing page and a UI package. API, database, auth, admin, email, SMS, and features arrive later with `saasaloy add`, each with its dependencies resolved.
+- **Cloudflare-native, near zero cost.** Workers, D1, and static assets by default. Most modules run on the free tier, and the ones that do not say so up front.
+- **Agent-native.** Every generated project ships `AGENTS.md`, `CLAUDE.md`, a `DESIGN.md` contract, and per-module skills for Claude Code and other agents.
+- **Reversible.** `saasaloy remove` undoes a module from its manifest, and `saasaloy update` re-applies at a newer version with a merge plan for your edits.
+
+## Quick start
+
+Requires Node 24.13.0+ and pnpm 11+. No Cloudflare account is needed until you deploy.
+
+```bash
+npm install -g saasaloy      # or: pnpm add -g saasaloy, or prefix commands with npx
+saasaloy init my-app
+cd my-app
+pnpm install
+pnpm dev                     # landing page on http://localhost:3000
+```
+
+Then compose the product:
+
+```bash
+saasaloy list                # what the registry offers, and what you already have
+saasaloy add database-d1     # pulls api + database, then binds them to D1 (or pick database-postgres)
+saasaloy add admin           # pulls auth, then an auth-gated admin SPA
+saasaloy add waitlist        # a feature: form, API route, table
+saasaloy env                 # fill in the variables your modules declare (--check gates a deploy)
+```
+
+Full walkthrough: [Getting started](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/getting-started.md), then [Make the project yours](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/how-to/make-it-yours.md) for the bundled skills that write your product brief, landing copy, and theme.
+
+## What you get
+
+```text
+my-app/
+  apps/web/            Astro landing page (the base)
+  apps/api/            Hono Worker            (saasaloy add api)
+  apps/admin/          TanStack Router SPA    (saasaloy add admin)
+  packages/ui/         shared React + Tailwind components
+  packages/db/         Drizzle schema + client (saasaloy add database-d1 | database-postgres)
+  packages/auth/       Better Auth            (saasaloy add auth)
+  packages/email/      email provider interface (saasaloy add email)
+  packages/queue/      background jobs + schedules (saasaloy add queue)
+  .agents/skills/      agent skills, symlinked from .claude/skills/
+  DESIGN.md            the design contract
+  saasaloy.json        installed modules + alias map
+```
+
+| Concern | Choice |
+|---|---|
+| Marketing site (`apps/web`) | Astro on Workers static assets |
+| App (`apps/admin`) | TanStack Router + Vite SPA |
+| Backend (`apps/api`) | Hono on Cloudflare Workers |
+| Database | Drizzle ORM on D1 (SQLite) or Postgres |
+| Auth | Better Auth |
+| Email | Cloudflare Email Sending, Plunk, or a console logger |
+| Background work | Cloudflare Queues and Cron Triggers, or an in-process runner |
+| Infra | wrangler per workspace, or Pulumi via the `infra` module |
+| Monorepo | Turborepo + pnpm |
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `init` | scaffold a new project (Astro landing + ui + config) |
+| `add` | apply a module into the current project, resolving `dependsOn` |
+| `env` | fill in the environment variables the installed modules declare (`--check` gates a deploy) |
+| `outdated` | report the base template and each installed module, current vs latest (`--check` gates CI) |
+| `update` | re-apply the base and modules at a newer version, with a merge plan for anything you edited |
+| `remove` | undo a module's applied files via the manifest, offline |
+| `list` | list the modules a registry offers, marking the ones installed here |
+| `new` | scaffold a new module in a registry repo (descriptor + files + skill stub) |
+| `doctor` | validate module descriptors, or a project's state files against each other |
+
+Every command answers `--help`. Flags, exit codes, coordinate grammar, and environment variables are in the [Reference](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/reference.md).
+
+## Modules
+
+Modules come in tiers. A **capability** scaffolds a workspace and sets conventions. A **feature** drops files into those conventions. A **provider** supplies one implementation behind a capability's interface. A **driver** supplies the connection half of a stateful capability, and only one may be installed.
+
+| 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` |
+| 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.
+
+The default registry is this repo. `saasaloy add waitlist` fetches `modules/waitlist/` from GitHub at a pinned commit SHA. Any repo with a `modules/` directory can serve as a registry with `saasaloy add owner/repo/<name>`. To publish your own, start at [Contribute a module](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/how-to/contribute-a-module.md).
+
+## Cost and requirements
+
+`init`, `api`, `database` + `database-d1`, `validators`, `logger`, `auth`, `admin`, `waitlist`, and `teams` all run on Cloudflare's free tier. Cloudflare's limits are Cloudflare's to change, and a project that grows past them should expect to pay.
+
+A few modules need something the free tier does not cover:
+
+| Module | Needs |
+|---|---|
+| `email-cloudflare` | a Workers paid plan and a sending domain onboarded by hand in the Cloudflare dashboard |
+| `email-plunk` | a [Plunk](https://www.useplunk.com) account and `PLUNK_API_KEY` |
+| `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 |
+
+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).
+
+## Deploy
+
+Each deployable workspace owns its `wrangler.jsonc` and `deploy` script. Run them one at a time, or install the `infra` module and deploy every Worker with one Pulumi program. See [Deploy to Cloudflare](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/how-to/deploy-to-cloudflare.md).
+
+## Documentation
+
+All docs live in [`docs/wiki/`](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/index.md).
+
+**Use Saasaloy**
+
+- [Getting started](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/getting-started.md): install the CLI, scaffold a project, run it.
+- [Make the project yours](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/how-to/make-it-yours.md): the bundled skills for the product brief, landing copy, and theme.
+- [Modules](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/modules.md): every module in the default registry, in one table.
+- [Add a module](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/how-to/add-a-module.md): install a feature and its prerequisites.
+- [Remove a module](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/how-to/remove-a-module.md): take one back out, and what stays behind.
+- [Deploy to Cloudflare](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/how-to/deploy-to-cloudflare.md): ship each workspace.
+
+**Build a module**
+
+- [Contribute a module](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/how-to/contribute-a-module.md): authoring guides and how to test a module before it ships.
+- [A bad descriptor reached `main`](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/runbooks/bad-descriptor-on-main.md): the registry is live, so this is an incident.
+
+**Both tracks**
+
+- [Architecture](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/architecture.md): how the CLI, the registry, and a generated project fit together.
+- [Reference](https://github.com/mimukit/saasaloy/blob/main/docs/wiki/reference.md): every command, flag, environment variable, and config file.
+- [`CONTEXT.md`](https://github.com/mimukit/saasaloy/blob/main/CONTEXT.md): the vocabulary. Module, capability, provider, coordinate, applier.
+- [`docs/adr/`](https://github.com/mimukit/saasaloy/blob/main/docs/adr/): why the design is what it is, one decision per file.
+
+## Contributing
+
+Issues and pull requests are welcome. [`CONTRIBUTING.md`](https://github.com/mimukit/saasaloy/blob/main/CONTRIBUTING.md) covers the `.dev/playground`, the lint and test gates, and the dependency update flow. The `billing` module is tracked in [#14](https://github.com/mimukit/saasaloy/issues/14).
+
+## License
+
+[MIT](https://github.com/mimukit/saasaloy/blob/main/LICENSE.md)

package/dist/index.js

@@ -877,7 +877,8 @@ function upsertWranglerBinding(source, patch) {
   if (!root) {
     return source;
   }
-  const arrayNode = findNodeAtLocation(root, [patch.bindingType]);
+  const bindingPath = splitBindingType(patch.bindingType);
+  const arrayNode = findNodeAtLocation(root, bindingPath);
   const formattingOptions = inferFormatting(source);
   if (arrayNode?.type === "array") {
     const existing = (arrayNode.children ?? []).map(
@@ -892,7 +893,7 @@ function upsertWranglerBinding(source, patch) {
     }
     const edits2 = modify(
       source,
-      [patch.bindingType, existing.length],
+      [...bindingPath, existing.length],
       patch.entry,
       {
         formattingOptions,
@@ -901,7 +902,7 @@ function upsertWranglerBinding(source, patch) {
     );
     return applyEdits(source, edits2);
   }
-  const edits = modify(source, [patch.bindingType], [patch.entry], {
+  const edits = modify(source, bindingPath, [patch.entry], {
     formattingOptions
   });
   return applyEdits(source, edits);
@@ -911,7 +912,8 @@ function removeWranglerBinding(source, patch) {
   if (!root) {
     return source;
   }
-  const arrayNode = findNodeAtLocation(root, [patch.bindingType]);
+  const bindingPath = splitBindingType(patch.bindingType);
+  const arrayNode = findNodeAtLocation(root, bindingPath);
   if (arrayNode?.type !== "array") {
     return source;
   }
@@ -925,7 +927,7 @@ function removeWranglerBinding(source, patch) {
   if (matchWranglerBinding(source, patch)) {
     return source;
   }
-  const path = existing.length === 1 ? [patch.bindingType] : [patch.bindingType, index];
+  const path = existing.length === 1 ? emptiedAncestorPath(root, bindingPath) : [...bindingPath, index];
   const edits = modify(source, path, void 0, {
     formattingOptions: inferFormatting(source)
   });
@@ -938,6 +940,20 @@ function wranglerBindingRemoveRefusal(source, patch) {
   }
   return `${match.key} holds ${JSON.stringify(match.current)} now, not the entry that was applied, so it is not ours to delete`;
 }
+function splitBindingType(bindingType) {
+  return bindingType.split(".");
+}
+function emptiedAncestorPath(root, bindingPath) {
+  let cut = bindingPath.length;
+  for (let depth = bindingPath.length - 1; depth >= 1; depth -= 1) {
+    const parent = findNodeAtLocation(root, bindingPath.slice(0, depth));
+    if (parent?.type !== "object" || (parent.children?.length ?? 0) !== 1) {
+      break;
+    }
+    cut = depth;
+  }
+  return bindingPath.slice(0, cut);
+}
 function findEntryIndex(existing, patch) {
   const { entry } = patch;
   if (typeof entry === "string") {
@@ -957,7 +973,10 @@ function matchWranglerBinding(source, patch) {
   if (!root) {
     return void 0;
   }
-  const arrayNode = findNodeAtLocation(root, [patch.bindingType]);
+  const arrayNode = findNodeAtLocation(
+    root,
+    splitBindingType(patch.bindingType)
+  );
   if (arrayNode?.type !== "array") {
     return void 0;
   }
@@ -3667,7 +3686,7 @@ import { fileURLToPath as fileURLToPath3 } from "url";
 // package.json
 var package_default = {
   name: "saasaloy",
-  version: "0.1.0",
+  version: "0.1.2",
   description: "Composable SaaS accelerator kit.",
   keywords: [
     "saas",
@@ -3706,7 +3725,7 @@ var package_default = {
   },
   scripts: {
     build: "tsup",
-    prepack: "pnpm run build",
+    prepack: "pnpm -w run readme:cli && pnpm run build",
     dev: "tsup --watch",
     start: "node ./dist/index.js",
     typecheck: "tsc --noEmit",
@@ -3888,6 +3907,19 @@ function recordBaseFiles(manifest, files) {
 function isBaseTracked(lock, manifest) {
   return lock.base !== void 0 && Object.keys(baseEntries(manifest)).length > 0;
 }
+async function missingBaseTargets(root, manifest, templateDir) {
+  const seed = new Set((await readBaseDeclaration(templateDir)).seedFiles);
+  const missing = [];
+  for (const target of Object.keys(baseEntries(manifest))) {
+    if (seed.has(target)) {
+      continue;
+    }
+    if (await readIfPresent(resolveWithinRoot(root, target)) === void 0) {
+      missing.push(target);
+    }
+  }
+  return missing.toSorted((a, b) => a < b ? -1 : 1);
+}
 async function renderTemplate(root, templateDir) {
   const dir = await mkdtemp2(join10(tmpdir2(), "saasaloy-base-render-"));
   const files = await copyTemplate(
@@ -4326,7 +4358,7 @@ var HELP2 = {
   usage: USAGE2,
   flags: {}
 };
-var DEFAULT_PATH = "modules";
+var DEFAULT_PATH = ".";
 function parseArgs2(argv) {
   const positional = [];
   const unknown = [];
@@ -4425,9 +4457,8 @@ async function runDoctor(argv) {
   const path = opts.path ?? DEFAULT_PATH;
   try {
     if (!await pathExists(path)) {
-      const hint = opts.path === void 0 && await pathExists(CONFIG_FILE) ? ` Run \`saasaloy doctor .\` to check this project instead.` : "";
       cancel2(
-        `No such path: ${path} \u2014 point \`doctor\` at a module folder or at a directory of them.${hint}`
+        `No such path: ${path} \u2014 point \`doctor\` at a module folder or at a directory of them.`
       );
       return EXIT_REFUSED;
     }
@@ -6244,6 +6275,7 @@ function baseLabel(version2, hash) {
 }
 function compareBase(args) {
   const { lock, manifest, runningHash, runningVersion } = args;
+  const missing = args.missingTargets ?? [];
   const latest = baseLabel(runningVersion, runningHash);
   if (!isBaseTracked(lock, manifest) || !lock.base) {
     return {
@@ -6256,13 +6288,18 @@ function compareBase(args) {
       detail: "not recorded \u2014 run `saasaloy update` to adopt the base at this CLI"
     };
   }
+  const moved = lock.base.templateHash !== runningHash;
   return {
     name: BASE_MODULE,
     source: BASE_SOURCE,
     ref: BASE_REF,
     current: baseLabel(lock.base.cliVersion, lock.base.templateHash),
     latest,
-    status: lock.base.templateHash === runningHash ? "current" : "outdated"
+    status: moved || missing.length > 0 ? "outdated" : "current",
+    // Say why, or an unmoved hash beside `outdated` reads as a bug.
+    ...!moved && missing.length > 0 ? {
+      detail: `${missing.length} tracked file${missing.length === 1 ? " is" : "s are"} missing from disk`
+    } : {}
   };
 }
 function recordRefRewrites(lock, comparisons) {
@@ -6923,11 +6960,13 @@ async function runOutdated(argv) {
         `${REGISTRY_ENV} is set, so every module reads as local \u2014 unset it to compare against the registry.`
       );
     }
+    const templateDir = await baseTemplateDir();
     const baseRow = compareBase({
       lock,
       manifest,
-      runningHash: await templateHash(await baseTemplateDir()),
-      runningVersion: await readVersion()
+      runningHash: await templateHash(templateDir),
+      runningVersion: await readVersion(),
+      missingTargets: await missingBaseTargets(root, manifest, templateDir)
     });
     const resolvers = /* @__PURE__ */ new Map();
     const remote = (slug, ref) => {
@@ -7953,7 +7992,8 @@ async function runUpdate(argv) {
         lock,
         manifest,
         runningHash: await templateHash(templateDir),
-        runningVersion: cliVersion
+        runningVersion: cliVersion,
+        missingTargets: await missingBaseTargets(root, manifest, templateDir)
       });
     }
     if (targets.length === 0 && !baseComparison) {