@percepta/create 3.1.5 → 3.3.0

package/dist/{upstream-F6m8zRBQ.js.map → upstream-D-LH_1z4.js.map}

@@ -1 +1 @@
-{"version":3,"file":"upstream-F6m8zRBQ.js","names":[],"sources":["../src/commands/upstream.ts"],"sourcesContent":["import path from \"node:path\";\nimport chalk from \"chalk\";\nimport fs from \"fs-extra\";\nimport { getFileAtTag } from \"../utils/git-ops.js\";\nimport {\n  readManifest,\n  resolveMosaicTemplatePath,\n  type MosaicManifest,\n} from \"../utils/manifest.js\";\n\nexport interface UpstreamOptions {\n  mosaicTemplatePath?: string;\n  files?: string[];\n}\n\nasync function generateUpstreamContext(\n  manifest: MosaicManifest,\n  mosaicTemplatePath: string,\n  tag: string,\n  appDir: string,\n  files: string[],\n): Promise<string> {\n  let content = `# Mosaic Upstream Context\n\n## App Info\n- **App name:** ${manifest.placeholders.__APP_NAME__ || \"unknown\"}\n- **Template:** ${manifest.templateType}\n- **Template version:** ${manifest.templateVersion}\n\n## Placeholder Mappings\n\nWhen generalizing app code back to template, replace these values with placeholder tokens:\n\n| Value | Placeholder |\n|-------|------------|\n${Object.entries(manifest.placeholders)\n  .sort((a, b) => b[1].length - a[1].length) // longest first to avoid partial matches\n  .map(([k, v]) => `| \\`${v}\\` | \\`${k}\\` |`)\n  .join(\"\\n\")}\n\n## Files to Review\n\n`;\n\n  for (const file of files) {\n    const appFilePath = path.resolve(appDir, file);\n    const templateRelPath = `${manifest.source.templatePath}/${file}`;\n\n    const appContent = (await fs.pathExists(appFilePath))\n      ? await fs.readFile(appFilePath, \"utf-8\")\n      : null;\n    const templateContent = getFileAtTag(\n      mosaicTemplatePath,\n      tag,\n      templateRelPath,\n    );\n\n    content += `### ${file}\\n\\n`;\n\n    if (!templateContent && appContent) {\n      content += `**New file** (not in template at ${manifest.templateVersion})\\n\\n`;\n      content += `\\`\\`\\`\\n${appContent}\\n\\`\\`\\`\\n\\n`;\n    } else if (templateContent && !appContent) {\n      content += `**Deleted** (exists in template but not in app)\\n\\n`;\n    } else if (appContent && templateContent) {\n      content += `**App version:**\\n\\`\\`\\`\\n${appContent}\\n\\`\\`\\`\\n\\n`;\n      content += `**Template version (at ${manifest.templateVersion}):**\\n\\`\\`\\`\\n${templateContent}\\n\\`\\`\\`\\n\\n`;\n    } else {\n      content += `**Not found** (file does not exist in app or template)\\n\\n`;\n    }\n  }\n\n  content += `## Instructions\n\n1. Review each file above\n2. Determine which changes are generalizable (useful for all apps) vs app-specific\n3. For generalizable changes: apply them to the template at \\`${manifest.source.templatePath}/\\`\n4. When applying, replace app-specific values with placeholders using the mapping table above (replace longest values first)\n5. After applying, bump the version in \\`packages/create-mosaic-module/template-versions.json\\`\n6. Run \\`pnpm template:tag\\` to create the new version tag\n7. Delete this file (\\`.mosaic-upstream-context.md\\`) when done\n`;\n\n  return content;\n}\n\nexport async function upstreamCommand(options: UpstreamOptions): Promise<void> {\n  const cwd = process.cwd();\n\n  try {\n    const manifest = await readManifest(cwd);\n    const mosaicTemplatePath = resolveMosaicTemplatePath(options);\n\n    if (!options.files || options.files.length === 0) {\n      console.error(\n        chalk.red(\"Specify files with --files <file1> <file2> ...\"),\n      );\n      console.log(\n        chalk.dim(\n          \"  Example: create upstream --files src/config/getEnvConfig.ts\",\n        ),\n      );\n      process.exit(1);\n    }\n\n    const tag = `template/${manifest.templateType}/${manifest.templateVersion}`;\n\n    const context = await generateUpstreamContext(\n      manifest,\n      mosaicTemplatePath,\n      tag,\n      cwd,\n      options.files,\n    );\n    const contextPath = path.join(cwd, \".mosaic-upstream-context.md\");\n    await fs.writeFile(contextPath, context);\n\n    console.log();\n    console.log(chalk.bold(\"Upstream Context Generated\"));\n    console.log();\n    console.log(chalk.dim(\"  Files:\"), options.files.join(\", \"));\n    console.log(chalk.dim(\"  Context file:\"), \".mosaic-upstream-context.md\");\n    console.log();\n    console.log(\"Next steps:\");\n    console.log(chalk.dim(\"  1.\"), \"Open Claude Code in the mosaic repo\");\n    console.log(\n      chalk.dim(\"  2.\"),\n      `Tell Claude: \"Read ${path.resolve(cwd, \".mosaic-upstream-context.md\")} and apply generalizable changes to the template\"`,\n    );\n    console.log(chalk.dim(\"  3.\"), \"Review Claude's changes to the template\");\n    console.log();\n  } catch (error) {\n    console.error(chalk.red((error as Error).message));\n    process.exit(1);\n  }\n}\n"],"mappings":";;;;;;AAeA,eAAe,wBACb,UACA,oBACA,KACA,QACA,OACiB;CACjB,IAAI,UAAU;;;kBAGE,SAAS,aAAa,gBAAgB,UAAU;kBAChD,SAAS,aAAa;0BACd,SAAS,gBAAgB;;;;;;;;EAQjD,OAAO,QAAQ,SAAS,aAAa,CACpC,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,EAAE,GAAG,OAAO,CACzC,KAAK,CAAC,GAAG,OAAO,OAAO,EAAE,SAAS,EAAE,MAAM,CAC1C,KAAK,KAAK,CAAC;;;;;AAMZ,MAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,cAAc,KAAK,QAAQ,QAAQ,KAAK;EAC9C,MAAM,kBAAkB,GAAG,SAAS,OAAO,aAAa,GAAG;EAE3D,MAAM,aAAc,MAAM,GAAG,WAAW,YAAY,GAChD,MAAM,GAAG,SAAS,aAAa,QAAQ,GACvC;EACJ,MAAM,kBAAkB,aACtB,oBACA,KACA,gBACD;AAED,aAAW,OAAO,KAAK;AAEvB,MAAI,CAAC,mBAAmB,YAAY;AAClC,cAAW,oCAAoC,SAAS,gBAAgB;AACxE,cAAW,WAAW,WAAW;aACxB,mBAAmB,CAAC,WAC7B,YAAW;WACF,cAAc,iBAAiB;AACxC,cAAW,6BAA6B,WAAW;AACnD,cAAW,0BAA0B,SAAS,gBAAgB,gBAAgB,gBAAgB;QAE9F,YAAW;;AAIf,YAAW;;;;gEAImD,SAAS,OAAO,aAAa;;;;;;AAO3F,QAAO;;AAGT,eAAsB,gBAAgB,SAAyC;CAC7E,MAAM,MAAM,QAAQ,KAAK;AAEzB,KAAI;EACF,MAAM,WAAW,MAAM,aAAa,IAAI;EACxC,MAAM,qBAAqB,0BAA0B,QAAQ;AAE7D,MAAI,CAAC,QAAQ,SAAS,QAAQ,MAAM,WAAW,GAAG;AAChD,WAAQ,MACN,MAAM,IAAI,iDAAiD,CAC5D;AACD,WAAQ,IACN,MAAM,IACJ,gEACD,CACF;AACD,WAAQ,KAAK,EAAE;;EAKjB,MAAM,UAAU,MAAM,wBACpB,UACA,oBACA,YALsB,SAAS,aAAa,GAAG,SAAS,mBAMxD,KACA,QAAQ,MACT;EACD,MAAM,cAAc,KAAK,KAAK,KAAK,8BAA8B;AACjE,QAAM,GAAG,UAAU,aAAa,QAAQ;AAExC,UAAQ,KAAK;AACb,UAAQ,IAAI,MAAM,KAAK,6BAA6B,CAAC;AACrD,UAAQ,KAAK;AACb,UAAQ,IAAI,MAAM,IAAI,WAAW,EAAE,QAAQ,MAAM,KAAK,KAAK,CAAC;AAC5D,UAAQ,IAAI,MAAM,IAAI,kBAAkB,EAAE,8BAA8B;AACxE,UAAQ,KAAK;AACb,UAAQ,IAAI,cAAc;AAC1B,UAAQ,IAAI,MAAM,IAAI,OAAO,EAAE,sCAAsC;AACrE,UAAQ,IACN,MAAM,IAAI,OAAO,EACjB,sBAAsB,KAAK,QAAQ,KAAK,8BAA8B,CAAC,mDACxE;AACD,UAAQ,IAAI,MAAM,IAAI,OAAO,EAAE,0CAA0C;AACzE,UAAQ,KAAK;UACN,OAAO;AACd,UAAQ,MAAM,MAAM,IAAK,MAAgB,QAAQ,CAAC;AAClD,UAAQ,KAAK,EAAE"}
+{"version":3,"file":"upstream-D-LH_1z4.js","names":[],"sources":["../src/commands/upstream.ts"],"sourcesContent":["import path from \"node:path\";\nimport chalk from \"chalk\";\nimport fs from \"fs-extra\";\nimport { getFileAtTag } from \"../utils/git-ops.js\";\nimport {\n  readManifest,\n  resolveMosaicTemplatePath,\n  type MosaicManifest,\n} from \"../utils/manifest.js\";\n\nexport interface UpstreamOptions {\n  mosaicTemplatePath?: string;\n  files?: string[];\n}\n\nasync function generateUpstreamContext(\n  manifest: MosaicManifest,\n  mosaicTemplatePath: string,\n  tag: string,\n  appDir: string,\n  files: string[],\n): Promise<string> {\n  let content = `# Mosaic Upstream Context\n\n## App Info\n- **App name:** ${manifest.placeholders.__APP_NAME__ || \"unknown\"}\n- **Template:** ${manifest.templateType}\n- **Template version:** ${manifest.templateVersion}\n\n## Placeholder Mappings\n\nWhen generalizing app code back to template, replace these values with placeholder tokens:\n\n| Value | Placeholder |\n|-------|------------|\n${Object.entries(manifest.placeholders)\n  .sort((a, b) => b[1].length - a[1].length) // longest first to avoid partial matches\n  .map(([k, v]) => `| \\`${v}\\` | \\`${k}\\` |`)\n  .join(\"\\n\")}\n\n## Files to Review\n\n`;\n\n  for (const file of files) {\n    const appFilePath = path.resolve(appDir, file);\n    const templateRelPath = `${manifest.source.templatePath}/${file}`;\n\n    const appContent = (await fs.pathExists(appFilePath))\n      ? await fs.readFile(appFilePath, \"utf-8\")\n      : null;\n    const templateContent = getFileAtTag(\n      mosaicTemplatePath,\n      tag,\n      templateRelPath,\n    );\n\n    content += `### ${file}\\n\\n`;\n\n    if (!templateContent && appContent) {\n      content += `**New file** (not in template at ${manifest.templateVersion})\\n\\n`;\n      content += `\\`\\`\\`\\n${appContent}\\n\\`\\`\\`\\n\\n`;\n    } else if (templateContent && !appContent) {\n      content += `**Deleted** (exists in template but not in app)\\n\\n`;\n    } else if (appContent && templateContent) {\n      content += `**App version:**\\n\\`\\`\\`\\n${appContent}\\n\\`\\`\\`\\n\\n`;\n      content += `**Template version (at ${manifest.templateVersion}):**\\n\\`\\`\\`\\n${templateContent}\\n\\`\\`\\`\\n\\n`;\n    } else {\n      content += `**Not found** (file does not exist in app or template)\\n\\n`;\n    }\n  }\n\n  content += `## Instructions\n\n1. Review each file above\n2. Determine which changes are generalizable (useful for all apps) vs app-specific\n3. For generalizable changes: apply them to the template at \\`${manifest.source.templatePath}/\\`\n4. When applying, replace app-specific values with placeholders using the mapping table above (replace longest values first)\n5. After applying, bump the version in \\`packages/create-mosaic-module/template-versions.json\\`\n6. Run \\`pnpm template:tag\\` to create the new version tag\n7. Delete this file (\\`.mosaic-upstream-context.md\\`) when done\n`;\n\n  return content;\n}\n\nexport async function upstreamCommand(options: UpstreamOptions): Promise<void> {\n  const cwd = process.cwd();\n\n  try {\n    const manifest = await readManifest(cwd);\n    const mosaicTemplatePath = resolveMosaicTemplatePath(options);\n\n    if (!options.files || options.files.length === 0) {\n      console.error(\n        chalk.red(\"Specify files with --files <file1> <file2> ...\"),\n      );\n      console.log(\n        chalk.dim(\n          \"  Example: create upstream --files src/config/getEnvConfig.ts\",\n        ),\n      );\n      process.exit(1);\n    }\n\n    const tag = `template/${manifest.templateType}/${manifest.templateVersion}`;\n\n    const context = await generateUpstreamContext(\n      manifest,\n      mosaicTemplatePath,\n      tag,\n      cwd,\n      options.files,\n    );\n    const contextPath = path.join(cwd, \".mosaic-upstream-context.md\");\n    await fs.writeFile(contextPath, context);\n\n    console.log();\n    console.log(chalk.bold(\"Upstream Context Generated\"));\n    console.log();\n    console.log(chalk.dim(\"  Files:\"), options.files.join(\", \"));\n    console.log(chalk.dim(\"  Context file:\"), \".mosaic-upstream-context.md\");\n    console.log();\n    console.log(\"Next steps:\");\n    console.log(chalk.dim(\"  1.\"), \"Open Claude Code in the mosaic repo\");\n    console.log(\n      chalk.dim(\"  2.\"),\n      `Tell Claude: \"Read ${path.resolve(cwd, \".mosaic-upstream-context.md\")} and apply generalizable changes to the template\"`,\n    );\n    console.log(chalk.dim(\"  3.\"), \"Review Claude's changes to the template\");\n    console.log();\n  } catch (error) {\n    console.error(chalk.red((error as Error).message));\n    process.exit(1);\n  }\n}\n"],"mappings":";;;;;;AAeA,eAAe,wBACb,UACA,oBACA,KACA,QACA,OACiB;CACjB,IAAI,UAAU;;;kBAGE,SAAS,aAAa,gBAAgB,UAAU;kBAChD,SAAS,aAAa;0BACd,SAAS,gBAAgB;;;;;;;;EAQjD,OAAO,QAAQ,SAAS,aAAa,CACpC,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,EAAE,GAAG,OAAO,CACzC,KAAK,CAAC,GAAG,OAAO,OAAO,EAAE,SAAS,EAAE,MAAM,CAC1C,KAAK,KAAK,CAAC;;;;;AAMZ,MAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,cAAc,KAAK,QAAQ,QAAQ,KAAK;EAC9C,MAAM,kBAAkB,GAAG,SAAS,OAAO,aAAa,GAAG;EAE3D,MAAM,aAAc,MAAM,GAAG,WAAW,YAAY,GAChD,MAAM,GAAG,SAAS,aAAa,QAAQ,GACvC;EACJ,MAAM,kBAAkB,aACtB,oBACA,KACA,gBACD;AAED,aAAW,OAAO,KAAK;AAEvB,MAAI,CAAC,mBAAmB,YAAY;AAClC,cAAW,oCAAoC,SAAS,gBAAgB;AACxE,cAAW,WAAW,WAAW;aACxB,mBAAmB,CAAC,WAC7B,YAAW;WACF,cAAc,iBAAiB;AACxC,cAAW,6BAA6B,WAAW;AACnD,cAAW,0BAA0B,SAAS,gBAAgB,gBAAgB,gBAAgB;QAE9F,YAAW;;AAIf,YAAW;;;;gEAImD,SAAS,OAAO,aAAa;;;;;;AAO3F,QAAO;;AAGT,eAAsB,gBAAgB,SAAyC;CAC7E,MAAM,MAAM,QAAQ,KAAK;AAEzB,KAAI;EACF,MAAM,WAAW,MAAM,aAAa,IAAI;EACxC,MAAM,qBAAqB,0BAA0B,QAAQ;AAE7D,MAAI,CAAC,QAAQ,SAAS,QAAQ,MAAM,WAAW,GAAG;AAChD,WAAQ,MACN,MAAM,IAAI,iDAAiD,CAC5D;AACD,WAAQ,IACN,MAAM,IACJ,gEACD,CACF;AACD,WAAQ,KAAK,EAAE;;EAKjB,MAAM,UAAU,MAAM,wBACpB,UACA,oBACA,YALsB,SAAS,aAAa,GAAG,SAAS,mBAMxD,KACA,QAAQ,MACT;EACD,MAAM,cAAc,KAAK,KAAK,KAAK,8BAA8B;AACjE,QAAM,GAAG,UAAU,aAAa,QAAQ;AAExC,UAAQ,KAAK;AACb,UAAQ,IAAI,MAAM,KAAK,6BAA6B,CAAC;AACrD,UAAQ,KAAK;AACb,UAAQ,IAAI,MAAM,IAAI,WAAW,EAAE,QAAQ,MAAM,KAAK,KAAK,CAAC;AAC5D,UAAQ,IAAI,MAAM,IAAI,kBAAkB,EAAE,8BAA8B;AACxE,UAAQ,KAAK;AACb,UAAQ,IAAI,cAAc;AAC1B,UAAQ,IAAI,MAAM,IAAI,OAAO,EAAE,sCAAsC;AACrE,UAAQ,IACN,MAAM,IAAI,OAAO,EACjB,sBAAsB,KAAK,QAAQ,KAAK,8BAA8B,CAAC,mDACxE;AACD,UAAQ,IAAI,MAAM,IAAI,OAAO,EAAE,0CAA0C;AACzE,UAAQ,KAAK;UACN,OAAO;AACd,UAAQ,MAAM,MAAM,IAAK,MAAgB,QAAQ,CAAC;AAClD,UAAQ,KAAK,EAAE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percepta/create",
-  "version": "3.1.5",
+  "version": "3.3.0",
   "description": "Scaffold a new Mosaic package",
   "keywords": [
     "cli",
@@ -38,7 +38,7 @@
     "@types/node": "^24.1.0",
     "@types/validate-npm-package-name": "^4.0.2",
     "vitest": "^4.0.0",
-    "@percepta/build": "0.5.0"
+    "@percepta/build": "1.0.0"
   },
   "engines": {
     "node": ">=18.0.0"

package/template-versions.json

@@ -1,4 +1,4 @@
 {
-  "webapp": "1.0.0",
+  "webapp": "1.1.0",
   "library": "1.0.0"
 }

package/templates/monorepo/.github/workflows/access-control.yml

@@ -0,0 +1,38 @@
+name: Access Control
+
+on:
+  pull_request: {}
+
+env:
+  PNPM_VERSION: 10.x
+
+jobs:
+  access-control:
+    name: Merge and Validate Access Schema
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup PNPM
+        uses: pnpm/action-setup@v4
+        with:
+          version: ${{ env.PNPM_VERSION }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Merge and validate access schema
+        run: |
+          if find packages -path '*/src/access/access.manifest.ts' | grep -q .; then
+            pnpm access:validate
+          else
+            echo "No app access manifests found yet; skipping access schema validation."
+          fi

package/templates/monorepo/README.md

@@ -1,6 +1,6 @@
 # __APP_TITLE__
 
-A monorepo powered by [pnpm workspaces](https://pnpm.io/workspaces).
+A customer monorepo powered by [pnpm workspaces](https://pnpm.io/workspaces).
 
 ## Getting Started
 
@@ -11,6 +11,12 @@ pnpm install
 # Run development mode for all packages
 pnpm dev
 
+# Set up local services, access-control topology, databases, and seed users
+pnpm run setup
+
+# Merge and validate customer access-control schema
+pnpm access:validate
+
 # Build all packages
 pnpm build
 
@@ -24,10 +30,44 @@ pnpm lint
 ## Structure
 
 ```
+access/              # Customer-level SpiceDB fixtures and generated merge artifacts
+auth/                # Shared Better Auth users/groups package for this customer
 packages/
-  └── your-package/    # Add your packages here
+  └── your-package/  # Application and library packages
+```
+
+## Access Control
+
+Application builders define app-local Zed schemas in each package's
+`src/access/` directory. The root access scripts merge those schemas with the
+shared `core/*` schema and apply customer-owned grants such
+as application owners, application members, and bootstrap customer admins.
+
+```bash
+pnpm access:merge
+pnpm access:validate
+pnpm access:apply
 ```
 
+PR CI merges the customer schema and runs static schema/manifest validation.
+`access:apply` is reserved for trusted deploy jobs and should run once per
+target environment with that environment's SpiceDB credentials.
+
+For local development, copy the example fixture files in `access/`, fill in
+customer-global user/group IDs from `auth/`, then run:
+
+```bash
+pnpm access:seed-grants
+pnpm access:bootstrap-customer-admin -- --subject core/user:<user-id>
+```
+
+## Shared Auth
+
+The `auth/` workspace wires the customer-global Better Auth schema from
+`@percepta/auth`, including `users`, `groups`, and `group_members`. Apps should
+consume this shared identity layer instead of creating app-local users or
+groups.
+
 ## Adding a new package
 
 Create a new directory in `packages/` with its own `package.json`:

package/templates/monorepo/access/README.md

@@ -0,0 +1,39 @@
+# Customer Access Control
+
+This directory owns the customer-level SpiceDB deployment surface:
+
+- `pnpm access:merge` combines every app's `src/access/schema.zed` with the shared core schema.
+- `pnpm access:validate` validates the merged schema and app manifests.
+- `pnpm access:apply` writes the merged schema and stable application topology links to SpiceDB.
+- `pnpm access:seed-grants` and `pnpm access:apply-bootstrap-grants` apply YAML fixture grants.
+- `pnpm access:bootstrap-customer-admin` creates the first direct customer-admin grant.
+- `pnpm access:reconcile` repairs SpiceDB from an explicit local projection.
+
+The source of truth for app-specific permissions remains the app's authored Zed
+file. This package owns only customer-level composition and customer-admin
+bootstrap.
+
+## Local Bootstrap
+
+```bash
+pnpm access:merge
+pnpm access:validate
+cp access/bootstrap-grants.yaml.example access/bootstrap-grants.yaml
+pnpm access:apply-local
+pnpm access:apply-bootstrap-grants -- --endpoint localhost:50051 --insecure --key dev-spicedb-token
+```
+
+Use `core/user:<users.id>` and `core/group:<groups.id>#member` subjects. The IDs
+come from the shared `auth/` package tables, not from per-app user tables.
+
+## Production Promotion
+
+Run `pnpm access:validate` in PR CI. Run `pnpm access:apply` only from trusted deploy jobs
+with the target environment's SpiceDB credentials. Promote the same merged
+schema artifact through environments before app code that depends on new
+relations or permissions.
+
+Use expand/contract for destructive changes: add the new shape, deploy
+dual-write/dual-read code, backfill with idempotent relationship writes,
+reconcile, then remove old relationships and schema definitions in a later
+deploy.

package/templates/monorepo/access/bootstrap-grants.yaml.example

@@ -0,0 +1,9 @@
+# Production bootstrap grants for first deploy / break-glass access.
+# Copy to bootstrap-grants.yaml, replace IDs with auth.users.id values, then run:
+#   pnpm access:apply-bootstrap-grants
+customerAdmins:
+  - userId: "00000000-0000-0000-0000-000000000000"
+
+applications: []
+appRoles: []
+resourceRelations: []

package/templates/monorepo/access/dev-grants.yaml.example

@@ -0,0 +1,19 @@
+# Local development grants. Copy to dev-grants.yaml and replace IDs with rows
+# from the shared auth.users / auth.groups tables.
+customerAdmins:
+  - userId: "00000000-0000-0000-0000-000000000000"
+
+applications:
+  - appNamespace: "people_app"
+    owners:
+      - userId: "00000000-0000-0000-0000-000000000000"
+    members:
+      - groupId: "11111111-1111-1111-1111-111111111111"
+
+appRoles:
+  - appNamespace: "people_app"
+    role: "admin"
+    subjects:
+      - groupId: "11111111-1111-1111-1111-111111111111"
+
+resourceRelations: []

package/templates/monorepo/access/dev-groups.yaml.example

@@ -0,0 +1,8 @@
+# Future fixture source for the auth-owned groupSync adapter.
+# SCIM/JIT is the production source of truth; this file is only for local dev.
+groups:
+  - externalId: "dev-group-admins"
+    name: "Development Admins"
+    source: "fixture"
+    members:
+      - userExternalId: "dev-admin"

package/templates/monorepo/access/reconcile.yaml.example

@@ -0,0 +1,11 @@
+# Explicit local projection for access:reconcile.
+applications:
+  - appNamespace: "people_app"
+
+groupMemberships:
+  - groupId: "11111111-1111-1111-1111-111111111111"
+    userIds:
+      - "00000000-0000-0000-0000-000000000000"
+
+deletedUserIds: []
+deletedGroupIds: []

package/templates/monorepo/auth/README.md

@@ -0,0 +1,27 @@
+# Shared Auth
+
+This workspace wires the customer-global Better Auth database schema from
+`@percepta/auth`. Apps in the customer monorepo should import this package for
+session validation and user / group table references instead of creating
+app-local auth tables.
+
+Import auth as `@__APP_NAME__/auth`, the database handle as
+`@__APP_NAME__/auth/db`, and table definitions as `@__APP_NAME__/auth/schema`
+from app packages.
+
+The important identity invariant is:
+
+- `core/user:<id>` uses `users.id` from this package.
+- `core/group:<id>#member` uses `groups.id` from this package.
+- `group_members` is the local projection that reconcile uses to repair
+  SpiceDB group membership relationships.
+
+SCIM/JIT protocol handlers are intentionally not implemented here yet; they
+should feed the access-control `groupSync` ingestion contract when that adapter
+lands.
+
+## Database
+
+By default this package uses the customer monorepo database name generated at
+scaffold time. Override with `AUTH_DATABASE_NAME` or `AUTH_DATABASE_URL` when
+the shared auth database lives somewhere else.

package/templates/monorepo/auth/drizzle.config.ts

@@ -0,0 +1,13 @@
+import type { Config } from "drizzle-kit";
+import { getAuthDatabaseConnectionString } from "./src/config/database";
+
+const config: Config = {
+  schema: "./src/drizzle/schema",
+  out: "./src/drizzle/migrations",
+  dialect: "postgresql",
+  dbCredentials: {
+    url: getAuthDatabaseConnectionString(),
+  },
+};
+
+export default config;

package/templates/monorepo/auth/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@__APP_NAME__/auth",
+  "version": "0.0.1",
+  "private": true,
+  "description": "Shared customer identity package.",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./db": "./src/drizzle/db.ts",
+    "./schema": "./src/drizzle/schema/index.ts"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:setup": "tsx ./scripts/setup-database.ts",
+    "db:setup-and-migrate": "pnpm db:setup && pnpm db:migrate"
+  },
+  "dependencies": {
+    "@percepta/auth": "0.1.0",
+    "drizzle-orm": "^0.45.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24.1.0",
+    "drizzle-kit": "^0.31.4",
+    "tsx": "^4.20.3",
+    "typescript": "^5.8.3"
+  }
+}

package/templates/monorepo/auth/scripts/setup-database.ts

@@ -0,0 +1,11 @@
+import { setupAuthDatabase } from "@percepta/auth";
+import { getAuthDatabaseConfig } from "../src/config/database";
+
+async function main(): Promise<void> {
+  await setupAuthDatabase({ config: getAuthDatabaseConfig() });
+}
+
+void main().catch((error) => {
+  console.error("Shared auth database setup failed:", error);
+  process.exit(1);
+});

package/templates/monorepo/auth/src/auth.ts

@@ -0,0 +1,47 @@
+import { createLazyAuth, createPerceptaAuth } from "@percepta/auth/better-auth";
+import { db } from "./drizzle/db";
+import { accounts } from "./drizzle/schema/auth/accounts";
+import { sessions } from "./drizzle/schema/auth/sessions";
+import { verifications } from "./drizzle/schema/auth/verifications";
+import { users } from "./drizzle/schema/users";
+
+// eslint-disable-next-line n/no-process-env -- detecting Next.js build phase
+const isBuildPhase = process.env.NEXT_PHASE === "phase-production-build";
+
+function requiredEnv(name: string): string {
+  const value = process.env[name];
+  if (value == null || value.length === 0) {
+    throw new Error(`${name} is required.`);
+  }
+  return value;
+}
+
+function getSecret(): string {
+  if (isBuildPhase) {
+    return "build-placeholder-not-used-at-runtime";
+  }
+
+  return requiredEnv("BETTER_AUTH_SECRET");
+}
+
+function createAuth() {
+  return createPerceptaAuth({
+    baseURL: process.env.BETTER_AUTH_URL ?? "http://localhost:3000",
+    database: db,
+    schema: {
+      user: users,
+      session: sessions,
+      account: accounts,
+      verification: verifications,
+    },
+    secret: getSecret(),
+  });
+}
+
+/**
+ * Lazy proxy so app builds can import the shared auth package without requiring
+ * runtime secrets until Better Auth is actually used.
+ */
+export const auth = createLazyAuth(createAuth);
+
+export type BetterAuthSession = typeof auth.$Infer.Session;

package/templates/monorepo/auth/src/config/database.ts

@@ -0,0 +1,15 @@
+import {
+  createAuthDatabaseConnectionString,
+  readAuthDatabaseConfig,
+  type AuthDatabaseConfig,
+} from "@percepta/auth";
+
+export type { AuthDatabaseConfig } from "@percepta/auth";
+
+export function getAuthDatabaseConfig(): AuthDatabaseConfig {
+  return readAuthDatabaseConfig({ defaultDatabaseName: "__DB_NAME__" });
+}
+
+export function getAuthDatabaseConnectionString(): string {
+  return createAuthDatabaseConnectionString(getAuthDatabaseConfig());
+}

package/templates/monorepo/auth/src/drizzle/db.ts

@@ -0,0 +1,8 @@
+import { createAuthDatabase } from "@percepta/auth/drizzle";
+import { getAuthDatabaseConnectionString } from "../config/database";
+import * as schema from "./schema";
+
+export const { client, db } = createAuthDatabase({
+  connectionString: getAuthDatabaseConnectionString(),
+  schema,
+});

package/templates/monorepo/auth/src/drizzle/migrations/0000_shared_auth.sql

@@ -0,0 +1,89 @@
+CREATE TABLE "users" (
+	"id" uuid PRIMARY KEY NOT NULL,
+	"external_id" text,
+	"name" text NOT NULL,
+	"email" text NOT NULL,
+	"email_verified" boolean DEFAULT false NOT NULL,
+	"image" text,
+	"role" text DEFAULT 'user' NOT NULL,
+	"banned" boolean DEFAULT false,
+	"ban_reason" text,
+	"ban_expires" timestamp,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "users_email_unique" UNIQUE("email")
+);
+--> statement-breakpoint
+CREATE TABLE "account" (
+	"id" text PRIMARY KEY NOT NULL,
+	"user_id" uuid NOT NULL,
+	"account_id" text NOT NULL,
+	"provider_id" text NOT NULL,
+	"access_token" text,
+	"refresh_token" text,
+	"expires_at" integer,
+	"access_token_expires_at" timestamp,
+	"refresh_token_expires_at" timestamp,
+	"scope" text,
+	"id_token" text,
+	"password" text,
+	"created_at" timestamp NOT NULL,
+	"updated_at" timestamp NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "session" (
+	"id" text PRIMARY KEY NOT NULL,
+	"user_id" uuid NOT NULL,
+	"token" text NOT NULL,
+	"expires_at" timestamp NOT NULL,
+	"ip_address" text,
+	"user_agent" text,
+	"impersonated_by" text,
+	"created_at" timestamp NOT NULL,
+	"updated_at" timestamp NOT NULL,
+	CONSTRAINT "session_token_unique" UNIQUE("token")
+);
+--> statement-breakpoint
+CREATE TABLE "verification" (
+	"id" text PRIMARY KEY NOT NULL,
+	"identifier" text NOT NULL,
+	"value" text NOT NULL,
+	"expires_at" timestamp NOT NULL,
+	"created_at" timestamp,
+	"updated_at" timestamp
+);
+--> statement-breakpoint
+CREATE TABLE "groups" (
+	"id" uuid PRIMARY KEY NOT NULL,
+	"external_id" text NOT NULL,
+	"name" text NOT NULL,
+	"source" text NOT NULL,
+	"deleted_at" timestamp,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "group_members" (
+	"group_id" uuid NOT NULL,
+	"user_id" uuid NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "group_members_pkey" PRIMARY KEY("group_id","user_id")
+);
+--> statement-breakpoint
+ALTER TABLE "account" ADD CONSTRAINT "account_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE cascade ON UPDATE no action;
+--> statement-breakpoint
+ALTER TABLE "session" ADD CONSTRAINT "session_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE cascade ON UPDATE no action;
+--> statement-breakpoint
+ALTER TABLE "group_members" ADD CONSTRAINT "group_members_group_id_groups_id_fk" FOREIGN KEY ("group_id") REFERENCES "groups"("id") ON DELETE cascade ON UPDATE no action;
+--> statement-breakpoint
+ALTER TABLE "group_members" ADD CONSTRAINT "group_members_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE cascade ON UPDATE no action;
+--> statement-breakpoint
+CREATE UNIQUE INDEX "users_lower_email_index" ON "users" USING btree (lower("email"));
+--> statement-breakpoint
+CREATE UNIQUE INDEX "users_external_id_index" ON "users" USING btree ("external_id") WHERE "users"."external_id" IS NOT NULL;
+--> statement-breakpoint
+CREATE UNIQUE INDEX "groups_live_external_id_index" ON "groups" USING btree ("external_id") WHERE "groups"."deleted_at" IS NULL;
+--> statement-breakpoint
+CREATE INDEX "groups_source_index" ON "groups" USING btree ("source");
+--> statement-breakpoint
+CREATE INDEX "group_members_user_id_index" ON "group_members" USING btree ("user_id");

package/templates/monorepo/auth/src/drizzle/migrations/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1777511400000,
+      "tag": "0000_shared_auth",
+      "breakpoints": true
+    }
+  ]
+}

package/templates/monorepo/auth/src/drizzle/schema/auth/accounts.ts

@@ -0,0 +1,7 @@
+import { createAccountsTable } from "@percepta/auth/drizzle";
+import { users } from "../users";
+
+export const accounts = createAccountsTable({ usersTable: users });
+
+export type Account = typeof accounts.$inferSelect;
+export type NewAccount = typeof accounts.$inferInsert;

package/templates/monorepo/auth/src/drizzle/schema/auth/sessions.ts

@@ -0,0 +1,7 @@
+import { createSessionsTable } from "@percepta/auth/drizzle";
+import { users } from "../users";
+
+export const sessions = createSessionsTable({ usersTable: users });
+
+export type Session = typeof sessions.$inferSelect;
+export type NewSession = typeof sessions.$inferInsert;

package/templates/monorepo/auth/src/drizzle/schema/auth/verifications.ts

@@ -0,0 +1,6 @@
+import { createVerificationsTable } from "@percepta/auth/drizzle";
+
+export const verifications = createVerificationsTable();
+
+export type Verification = typeof verifications.$inferSelect;
+export type NewVerification = typeof verifications.$inferInsert;

package/templates/monorepo/auth/src/drizzle/schema/groups.ts

@@ -0,0 +1,16 @@
+import {
+  createGroupMembersTable,
+  createGroupsTable,
+} from "@percepta/auth/drizzle";
+import { users } from "./users";
+
+export const groups = createGroupsTable();
+export const groupMembers = createGroupMembersTable({
+  groupsTable: groups,
+  usersTable: users,
+});
+
+export type Group = typeof groups.$inferSelect;
+export type NewGroup = typeof groups.$inferInsert;
+export type GroupMember = typeof groupMembers.$inferSelect;
+export type NewGroupMember = typeof groupMembers.$inferInsert;

package/templates/monorepo/auth/src/drizzle/schema/index.ts

@@ -0,0 +1,5 @@
+export { accounts } from "./auth/accounts";
+export { sessions } from "./auth/sessions";
+export { verifications } from "./auth/verifications";
+export { groupMembers, groups } from "./groups";
+export { users } from "./users";

package/templates/monorepo/auth/src/drizzle/schema/users.ts

@@ -0,0 +1,6 @@
+import { createUsersTable } from "@percepta/auth/drizzle";
+
+export const users = createUsersTable();
+
+export type User = typeof users.$inferSelect;
+export type NewUser = typeof users.$inferInsert;

package/templates/monorepo/auth/src/index.ts

@@ -0,0 +1 @@
+export { auth, type BetterAuthSession } from "./auth";

package/templates/monorepo/auth/src/scim/README.md

@@ -0,0 +1,6 @@
+# SCIM Placeholder
+
+SCIM `/Users` and `/Groups` endpoints are intentionally a follow-up project.
+When implemented, they should update the local `users`, `groups`, and
+`group_members` projection through the access-control `groupSync` ingestion
+contract so SpiceDB and Postgres stay aligned.

package/templates/monorepo/auth/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "declaration": false,
+    "declarationMap": false,
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["drizzle.config.ts", "src/**/*.ts"]
+}

package/templates/monorepo/package.json.template

@@ -5,18 +5,30 @@
   "description": "__APP_TITLE__",
   "scripts": {
     "preinstall": "npx only-allow pnpm",
-    "dev": "pnpm -r --parallel run dev",
-    "build": "pnpm -r run build",
-    "clean": "pnpm -r run clean",
-    "lint": "pnpm -r --parallel --no-bail run lint",
-    "lint:fix": "pnpm -r --no-bail run lint:fix",
-    "test": "pnpm -r run test"
+    "setup": "pnpm -r --filter './packages/*' --if-present run docker:up && pnpm run access:apply-local && pnpm run auth:db:setup-and-migrate && pnpm -r --filter './packages/*' --if-present run db:setup-and-migrate && pnpm -r --filter './packages/*' --if-present run db:seed",
+    "dev": "pnpm -r --parallel --if-present run dev",
+    "build": "pnpm -r --if-present run build",
+    "clean": "pnpm -r --if-present run clean",
+    "lint": "pnpm -r --parallel --no-bail --if-present run lint",
+    "lint:fix": "pnpm -r --no-bail --if-present run lint:fix",
+    "test": "pnpm -r --if-present run test",
+    "access:merge": "percepta-access-control merge --apps-dir \"$PWD/packages\" --out-dir access",
+    "access:validate": "percepta-access-control validate --apps-dir \"$PWD/packages\"",
+    "access:apply": "pnpm run access:merge && percepta-access-control apply --schema access/merged.zed --applications access/applications.generated.json",
+    "access:apply-local": "pnpm run access:merge && percepta-access-control apply --schema access/merged.zed --applications access/applications.generated.json --endpoint localhost:50051 --insecure --key dev-spicedb-token",
+    "access:seed-grants": "percepta-access-control seed-grants --fixture access/dev-grants.yaml",
+    "access:seed-groups": "percepta-access-control seed-groups",
+    "access:bootstrap-customer-admin": "percepta-access-control bootstrap-customer-admin",
+    "access:apply-bootstrap-grants": "percepta-access-control apply-bootstrap-grants --fixture access/bootstrap-grants.yaml",
+    "access:reconcile": "percepta-access-control reconcile --input access/reconcile.yaml",
+    "auth:db:setup-and-migrate": "pnpm --dir auth run db:setup-and-migrate"
   },
   "engines": {
     "node": ">=20",
     "pnpm": ">=9"
   },
   "devDependencies": {
+    "@percepta/access-control": "0.3.2",
     "@types/node": "^24.1.0",
     "eslint": "^9.18.0",
     "rimraf": "^5.0.5",

package/templates/monorepo/pnpm-workspace.yaml

@@ -1,2 +1,3 @@
 packages:
   - "packages/*"
+  - "auth"