saasaloy 0.1.0

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "saasaloy",
+  "version": "0.1.0",
+  "description": "Composable SaaS accelerator kit.",
+  "keywords": [
+    "saas",
+    "scaffold",
+    "starter",
+    "cli",
+    "astro",
+    "cloudflare-workers",
+    "drizzle",
+    "generator"
+  ],
+  "homepage": "https://github.com/mimukit/saasaloy#readme",
+  "bugs": {
+    "url": "https://github.com/mimukit/saasaloy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mimukit/saasaloy.git",
+    "directory": "packages/cli"
+  },
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "saasaloy": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "schemas/*.schema.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24.13.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "prepack": "pnpm run build",
+    "dev": "tsup --watch",
+    "start": "node ./dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --coverage",
+    "test:e2e": "vitest run --config vitest.integration.config.ts test/e2e",
+    "test:matrix": "vitest run --config vitest.integration.config.ts test/matrix",
+    "release": "release-it",
+    "release:dry": "release-it --dry-run"
+  },
+  "devDependencies": {
+    "@release-it/conventional-changelog": "12.0.0",
+    "@types/node": "26.1.1",
+    "@vitest/coverage-v8": "4.1.10",
+    "release-it": "21.0.2",
+    "tsup": "8.5.1",
+    "vitest": "4.1.10"
+  },
+  "dependencies": {
+    "@clack/prompts": "1.7.0",
+    "ajv": "8.17.1",
+    "diff": "9.0.0",
+    "giget": "3.3.0",
+    "jsonc-parser": "3.3.1",
+    "magicast": "0.5.3",
+    "picocolors": "1.1.1"
+  }
+}

package/schemas/manifest.schema.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://saasaloy.dev/schemas/manifest.schema.json",
+  "title": ".saasaloy/manifest.json — managed-file tracking",
+  "description": "Records every file a module applied — copied source files and copied skill files — with the owning module and a content hash, so update/remove know exactly what to undo. Replaces in-file `// saasaloy:managed` markers (build spec §2.9 / §3.2). `saasaloy init` writes it first, with one entry per base template file under the reserved module name `base` (ADR 0032).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["managed"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Optional pointer to this schema for editor validation."
+    },
+    "managed": {
+      "type": "object",
+      "description": "Project-relative file path → the module that owns it and a content hash. On update the tool re-hashes the file: match → safe overwrite; drift → route to AI-merge.",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["module", "hash"],
+        "properties": {
+          "module": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]*$",
+            "description": "Name of the module that applied this file. `base` is reserved for the template `saasaloy init` rendered; it is never in saasaloy.json's `installed` list."
+          },
+          "hash": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{64}$",
+            "description": "sha256 hex digest of the file's content as written."
+          },
+          "from": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Module-relative POSIX source path this file was copied from (e.g. `files/lib/email.ts`). `update` uses it to fetch the same file at the old and new commit SHAs. Optional — entries written before this field shipped fall back to re-deriving the target from the module descriptor."
+          }
+        }
+      }
+    },
+    "links": {
+      "type": "object",
+      "description": "Symlink map (source path → link path): a module's skill files live under .agents/skills/<name>/ and `add` points a .claude/skills/<name> symlink at them, recorded here so `remove` can undo both (ADR 0015).",
+      "additionalProperties": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "removeWarnings": {
+      "type": "object",
+      "description": "Installed module name to removal warnings copied from its descriptor. The remover reads this map offline.",
+      "propertyNames": {
+        "pattern": "^[a-z0-9][a-z0-9-]*$"
+      },
+      "additionalProperties": {
+        "type": "array",
+        "items": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "patches": {
+      "type": "array",
+      "description": "Structural config patches actually applied to disk, so `remove` can warn which files it can't clean up on its own (reversal is a follow-up issue). Deduped on re-apply (structural equality) so `--force` stays idempotent.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["module", "file", "patch"],
+        "properties": {
+          "module": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]*$",
+            "description": "Name of the module that applied this patch."
+          },
+          "file": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Project-relative POSIX path of the file that was patched."
+          },
+          "patch": {
+            "type": "object",
+            "required": ["file", "kind"],
+            "properties": {
+              "file": {
+                "type": "string",
+                "minLength": 1
+              },
+              "kind": {
+                "type": "string",
+                "enum": [
+                  "wrangler-binding",
+                  "package-json-dependency",
+                  "package-json-script",
+                  "plugin-array",
+                  "const-array",
+                  "chained-route"
+                ],
+                "description": "Which codemod applied this patch. Must list exactly the kinds registry-item.schema.json accepts — the applier records here whatever a descriptor authored, so a kind missing from this enum makes the next `loadManifest` refuse a manifest the tool itself wrote (#98). `schema.test.ts` asserts the two enums and the `Patch` union agree."
+              }
+            },
+            "description": "The op as authored (kind + payload + file), re-applicable at execute time."
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/registry-item.schema.json

@@ -0,0 +1,336 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://saasaloy.dev/schemas/registry-item.schema.json",
+  "title": "registry-item.json — module descriptor",
+  "description": "shadcn-shaped descriptor authored in the CLI/registry repo. The applier reads it off disk to resolve dependencies, apply files + npm deps + patches, and copy the module's skill folder(s) into .claude/skills/ (build spec §3.3).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["name", "type"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Optional pointer to this schema for editor validation."
+    },
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*$",
+      "description": "Module name (lowercase, digits, hyphens). Unique within the registry."
+    },
+    "type": {
+      "type": "string",
+      "enum": ["saasaloy:capability", "saasaloy:feature"],
+      "description": "`saasaloy:capability` scaffolds an app/package and establishes extension points; `saasaloy:feature` extends capabilities by dropping files into their conventions."
+    },
+    "requires": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Tool versions this descriptor needs. A descriptor sets `additionalProperties: false`, so an old CLI meeting a new field already fails — as a raw schema dump, and not at all when an existing field merely changed meaning. Declaring a range turns both into one fatal, actionable message, checked before any write is planned. Optional: a descriptor without it works on every CLI version.",
+      "properties": {
+        "saasaloy": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Semver range the running `saasaloy` CLI has to satisfy (e.g. `>=0.3`, `>=0.3 <2`, `^1.2.0`, `1.x`). Any range shape is accepted, upper bounds included, so there is no separate maximum field. A CLI outside the range refuses the whole run and names this module, even when it is a transitive `dependsOn`."
+        }
+      }
+    },
+    "dependsOn": {
+      "type": "array",
+      "description": "Modules this one requires. Resolved recursively and topologically sorted behind a confirmation prompt.",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9][a-z0-9-]*$"
+      }
+    },
+    "conflictsWith": {
+      "type": "array",
+      "description": "Modules this one refuses to sit beside — two implementations of the same capability, say. `add` refuses with a message naming both modules when a conflicting module is already installed. Either side may declare it: the field is recorded into saasaloy-lock.json, so the refusal fires in either install order. Never auto-resolved; `add` uninstalls nothing.",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9][a-z0-9-]*$"
+      }
+    },
+    "requiresOneOf": {
+      "type": "array",
+      "description": "Modules exactly one of which has to be present — a capability naming its mutually exclusive drivers (e.g. `database` naming `database-d1` and `database-postgres`). `add` counts a module as present when it is already installed or arrives in the same resolved graph, refuses when none is, and offers the list as a prompt on an interactive terminal. Use `dependsOn` for a single hard prerequisite; this field exists for a choice, so it takes at least two names (#98, ADR 0026).",
+      "uniqueItems": true,
+      "minItems": 2,
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9][a-z0-9-]*$"
+      }
+    },
+    "dependencies": {
+      "type": "array",
+      "description": "npm packages merged into the consumer's `dependencies`. Each must be exact-pinned `name@version` (e.g. zod@4.0.5) — bare names and ranges are rejected; `pnpm deps:update` fills/refreshes the versions.",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^(@[a-z0-9][a-z0-9._-]*/)?[a-z0-9][a-z0-9._-]*@\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?(\\+[0-9A-Za-z.-]+)?$"
+      }
+    },
+    "devDependencies": {
+      "type": "array",
+      "description": "npm packages merged into the consumer's `devDependencies` (e.g. @types/*, build tooling). Same exact-pinned `name@version` form as `dependencies`. A name declared in both buckets lands in `dependencies` only.",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^(@[a-z0-9][a-z0-9._-]*/)?[a-z0-9][a-z0-9._-]*@\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?(\\+[0-9A-Za-z.-]+)?$"
+      }
+    },
+    "files": {
+      "type": "array",
+      "description": "Files to copy into the project. `path` is relative to the module folder; `target` resolves through the project's alias map.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "target"],
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "not": { "pattern": "(^|/)\\.\\.?(/|$)" },
+            "description": "Source path relative to the module folder (e.g. files/api/routes/waitlist.ts). No '.' or '..' path segment: the applier refuses one at runtime and this fails the descriptor at authoring time (#98). A dot-leading file name such as .gitignore is fine."
+          },
+          "target": {
+            "type": "string",
+            "pattern": "^@[a-z0-9][a-z0-9-]*/.+",
+            "not": { "pattern": "(^|/)\\.\\.?(/|$)" },
+            "description": "Alias-prefixed destination (e.g. @api/routes/waitlist.ts). No '.' or '..' path segment: the applier refuses one at runtime and this fails the descriptor at authoring time (#98). A dot-leading file name such as .gitignore is fine."
+          },
+          "onlyWith": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]*$",
+            "description": "Install this file only when the named module is in the resolved install set — this run's dependsOn graph plus what saasaloy.json already records (#99). Two entries may share one `target` when their conditions are disjoint: that is how a module ships a per-driver variant of a dialect-bound file. A target whose entries are all conditional and none matches is a plan-time refusal, not a silently missing file."
+          }
+        }
+      }
+    },
+    "envVars": {
+      "type": "object",
+      "description": "Environment variables the module needs: NAME → human description (or default/placeholder).",
+      "propertyNames": {
+        "pattern": "^[A-Z][A-Z0-9_]*$"
+      },
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
+    "devVars": {
+      "type": "object",
+      "description": "Local-development values for a subset of `envVars`: NAME → the value `saasaloy add` pre-fills into the generated `apps/api/.dev.vars.example`. Only for a value that is the same on every machine and is not a secret (a loopback URL, a fixed port). Every key here must also appear in `envVars`; a key absent here is written with an empty value for the owner to fill in.",
+      "propertyNames": {
+        "pattern": "^[A-Z][A-Z0-9_]*$"
+      },
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
+    "removeWarnings": {
+      "type": "array",
+      "description": "Warnings saved with an installed module and shown before removal. Use this for deployed resources that file and patch removal cannot delete safely.",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "patches": {
+      "type": "array",
+      "description": "Structural config patches applied at `add` time by the patch engine (issue #7). A flat array where each op names its own target `file` and codemod `kind` (wrangler.jsonc bindings, package.json dependency merges, package.json script entries, Better Auth plugin-array insertions, router chain `.route()` links); kind-specific payload fields are defined by the engine. An empty array means no patches (ADR 0019).",
+      "items": {
+        "type": "object",
+        "required": ["file", "kind"],
+        "properties": {
+          "file": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^[^/@]",
+            "not": { "pattern": "(^|/)\\.\\.?(/|$)" },
+            "description": "Project-relative POSIX path of the file to patch (e.g. apps/api/wrangler.jsonc). No leading slash or @alias, and no '.' or '..' path segment (#98). A dot-leading file name such as .eslintrc.json is fine."
+          },
+          "kind": {
+            "type": "string",
+            "enum": [
+              "wrangler-binding",
+              "package-json-dependency",
+              "package-json-script",
+              "plugin-array",
+              "const-array",
+              "chained-route"
+            ],
+            "description": "Which codemod applies this patch. `const-array`, `plugin-array`, and `chained-route` have removal inverses."
+          }
+        },
+        "allOf": [
+          {
+            "if": {
+              "properties": { "kind": { "const": "const-array" } },
+              "required": ["kind"]
+            },
+            "then": {
+              "required": ["constName", "key", "entry"],
+              "properties": {
+                "constName": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Name of the module-scope const array to extend."
+                },
+                "key": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Entry property whose JSON value identifies the entry for add and remove."
+                },
+                "entry": {
+                  "type": "object",
+                  "minProperties": 1,
+                  "description": "JSON object literal appended to the named array."
+                }
+              }
+            }
+          },
+          {
+            "if": {
+              "properties": { "kind": { "const": "package-json-script" } },
+              "required": ["kind"]
+            },
+            "then": {
+              "required": ["name", "value"],
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Script key to upsert into the target's `scripts` map (e.g. db:generate)."
+                },
+                "value": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Command the script runs (e.g. drizzle-kit generate). An entry already present under this key is never overwritten."
+                }
+              }
+            }
+          },
+          {
+            "if": {
+              "properties": { "kind": { "const": "chained-route" } },
+              "required": ["kind"]
+            },
+            "then": {
+              "required": ["exportName", "path", "call", "import"],
+              "properties": {
+                "exportName": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Exported binding whose call chain to extend — `default`, or the name in `export const <name> = …`. A bare `export default app` is followed to its declaration."
+                },
+                "path": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Route path — `.route()`'s first argument (e.g. /waitlist). Also the match key: a chain already routing this path is left alone, and `remove` finds the link by it."
+                },
+                "call": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Identifier passed as `.route()`'s second argument (e.g. waitlist) — the sub-router the import supplies."
+                },
+                "import": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["name", "from"],
+                  "description": "Named import to add for `call`, dropped again on `remove` (with its statement, when it was the only specifier).",
+                  "properties": {
+                    "name": {
+                      "type": "string",
+                      "minLength": 1,
+                      "description": "Imported binding name (e.g. waitlist)."
+                    },
+                    "from": {
+                      "type": "string",
+                      "minLength": 1,
+                      "description": "Module specifier to import from (e.g. ./routes/waitlist.js)."
+                    }
+                  }
+                }
+              }
+            }
+          }
+        ]
+      }
+    },
+    "scaffolds": {
+      "type": "array",
+      "description": "New workspaces a capability module creates (apps/packages). Each entry births one workspace: copies its files to workspace-root-relative targets and registers the aliases it declares into saasaloy.json (ADR 0013).",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["workspace", "files"],
+        "properties": {
+          "workspace": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^[^/@]",
+            "description": "New workspace directory, project-relative POSIX (e.g. apps/api). No leading slash or @alias."
+          },
+          "aliases": {
+            "type": "object",
+            "description": "Alias → path-prefix map this scaffold registers into saasaloy.json (e.g. { \"@api\": \"apps/api/src\" }).",
+            "propertyNames": {
+              "pattern": "^@[a-z0-9][a-z0-9-]*$"
+            },
+            "additionalProperties": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Project-relative path prefix (POSIX separators, no leading slash)."
+            }
+          },
+          "files": {
+            "type": "array",
+            "description": "Files copied into the workspace. `path` is relative to the module folder; `target` is relative to the workspace root (no @alias — the alias root doesn't exist yet).",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["path", "target"],
+              "properties": {
+                "path": {
+                  "type": "string",
+                  "minLength": 1,
+                  "not": { "pattern": "(^|/)\\.\\.?(/|$)" },
+                  "description": "Source path relative to the module folder (e.g. files/src/index.ts). No '.' or '..' path segment: the applier refuses one at runtime and this fails the descriptor at authoring time (#98). A dot-leading file name such as .dev.vars.example is fine."
+                },
+                "target": {
+                  "type": "string",
+                  "minLength": 1,
+                  "pattern": "^[^/@]",
+                  "not": { "pattern": "(^|/)\\.\\.?(/|$)" },
+                  "description": "Destination relative to the workspace root (e.g. src/index.ts). No leading slash or @alias, and no '.' or '..' path segment (#98). A dot-leading file name such as .dev.vars.example is fine."
+                },
+                "onlyWith": {
+                  "type": "string",
+                  "pattern": "^[a-z0-9][a-z0-9-]*$",
+                  "description": "Install this file only when the named module is in the resolved install set — this run's dependsOn graph plus what saasaloy.json already records (#99). Same rule as a top-level files[] entry: two entries may share one `target` when their conditions are disjoint, and a target no candidate matches is a plan-time refusal. auth's per-driver db-provider.ts lives here rather than in files[], which is why both shapes carry the keyword."
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "agent": {
+      "type": "object",
+      "description": "AI context contributed by this module. A module ships skill folder(s) that `add` copies into .claude/skills/ (recorded in the manifest for a clean `remove`); it never edits the committed AGENTS.md/CLAUDE.md.",
+      "additionalProperties": false,
+      "properties": {
+        "skills": {
+          "type": "array",
+          "description": "Skill folder(s) relative to the module folder, copied into .claude/skills/.",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/saasaloy-lock.schema.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://saasaloy.dev/schemas/saasaloy-lock.schema.json",
+  "title": "saasaloy-lock.json — resolved module provenance",
+  "description": "Machine-owned lock at a generated project's root: for every installed module, the registry source it came from, the ref requested, and the exact commit SHA resolved — so a re-install reproduces identical bytes. The npm-style lock to saasaloy.json's intent (build spec §2.11; ADR 0012). Integrity is the commit SHA itself; there is no separate integrity field. The optional `base` object records the template `saasaloy init` rendered, keyed by CLI version and template hash rather than a commit, because the base ships inside the CLI package (ADR 0032).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["lockfileVersion", "modules"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Optional pointer to this schema for editor validation."
+    },
+    "lockfileVersion": {
+      "const": 1,
+      "description": "Lock format version; bumped only on a breaking shape change."
+    },
+    "base": {
+      "type": "object",
+      "description": "Provenance of the base template `init` rendered, or `update` adopted. Absent on a project scaffolded before the record existed; `saasaloy update` writes it.",
+      "additionalProperties": false,
+      "required": ["name", "cliVersion", "templateHash"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9-]*$",
+          "description": "The base app's name — saasaloy.json's `base` field (`web`)."
+        },
+        "cliVersion": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The CLI version that rendered or adopted the base. A label beside the hash: `outdated` compares `templateHash`, and `update` refuses a downgrade when both sides are real semver."
+        },
+        "templateHash": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$",
+          "description": "sha256 over the sorted (path, sha256) pairs of the template as shipped in the CLI package. Differs whenever any shipped template file differs."
+        }
+      }
+    },
+    "modules": {
+      "type": "object",
+      "description": "Module name → the source it was resolved from. Holds the full resolved graph (dependencies included), not just the top-level asks.",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["source", "ref", "resolved"],
+        "properties": {
+          "source": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Registry source slug: `owner/repo` for a remote GitHub source, or `local` for a SAASALOY_REGISTRY_DIR checkout."
+          },
+          "ref": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The ref requested (branch/tag/SHA), or `local` for a local checkout."
+          },
+          "resolved": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The exact commit SHA the ref resolved to — the integrity anchor. `local` for a local checkout."
+          },
+          "dependsOn": {
+            "type": "array",
+            "description": "The module's declared dependencies, recorded so the resolved graph is self-describing.",
+            "uniqueItems": true,
+            "items": {
+              "type": "string",
+              "pattern": "^[a-z0-9][a-z0-9-]*$"
+            }
+          },
+          "conflictsWith": {
+            "type": "array",
+            "description": "The module's declared `conflictsWith` list, recorded because descriptors aren't kept after install — this is what lets `add` refuse a conflicting module that goes in second.",
+            "uniqueItems": true,
+            "items": {
+              "type": "string",
+              "pattern": "^[a-z0-9][a-z0-9-]*$"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/saasaloy.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://saasaloy.dev/schemas/saasaloy.schema.json",
+  "title": "saasaloy.json — consumer manifest",
+  "description": "Alias map + installed-module list that lives at a generated project's root. Resolves module file targets and drives dependsOn resolution (build spec §3.2).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["aliases", "installed"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Optional pointer to this schema for editor validation."
+    },
+    "aliases": {
+      "type": "object",
+      "description": "Alias → path-prefix map. Keys are `@`-prefixed aliases (e.g. `@api`); values are project-relative directories a module's file targets resolve against.",
+      "propertyNames": {
+        "pattern": "^@[a-z0-9][a-z0-9-]*$"
+      },
+      "additionalProperties": {
+        "type": "string",
+        "minLength": 1,
+        "description": "Project-relative path prefix (POSIX separators, no leading slash)."
+      }
+    },
+    "base": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*$",
+      "description": "The base app `saasaloy init` scaffolded (e.g. `web`). It is not a module: the tool never applied it, it has no descriptor and no lock entry, so it never takes part in dependsOn resolution or conflict checks. Absent in a project scaffolded before this field existed; `saasaloy` migrates such a project on its next write."
+    },
+    "installed": {
+      "type": "array",
+      "description": "Modules present in this project. Grows as `saasaloy add` runs; drives dependsOn resolution.",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9][a-z0-9-]*$",
+        "description": "Module name (lowercase, digits, hyphens)."
+      }
+    }
+  }
+}