create-monolayer-app 0.5.1 → 0.6.1

package/bin/index.js

@@ -1,26 +1,30 @@
 #!/usr/bin/env node
 
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { spawnSync } from 'node:child_process';
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
+const __filename = import.meta.filename;
+const __dirname = import.meta.dirname;
 
 // Terminal color helpers
-const reset = '\x1b[0m';
-const bold = (str) => `\x1b[1m${str}${reset}`;
-const cyan = (str) => `\x1b[36m${str}${reset}`;
-const green = (str) => `\x1b[32m${str}${reset}`;
-const red = (str) => `\x1b[31m${str}${reset}`;
-const dim = (str) => `\x1b[2m${str}${reset}`;
-const yellow = (str) => `\x1b[33m${str}${reset}`;
+const reset = "\x1B[0m";
+const bold = (str) => `\x1B[1m${str}${reset}`;
+const cyan = (str) => `\x1B[36m${str}${reset}`;
+const green = (str) => `\x1B[32m${str}${reset}`;
+const red = (str) => `\x1B[31m${str}${reset}`;
+const dim = (str) => `\x1B[2m${str}${reset}`;
+const yellow = (str) => `\x1B[33m${str}${reset}`;
 
 // Helper to validate slug
 function isValidSlug(name) {
-  if (!name || typeof name !== 'string') return false;
-  if (/\s/.test(name)) return false;
+  if (!name || typeof name !== "string") {
+    return false;
+  }
+  if (/\s/.test(name)) {
+    return false;
+  }
   // Slug should consist of letters, numbers, hyphens, and underscores
   return /^[a-zA-Z0-9_-]+$/.test(name);
 }
@@ -31,14 +35,16 @@ function copyDir(src, dest) {
   const entries = fs.readdirSync(src, { withFileTypes: true });
 
   for (const entry of entries) {
-    if (entry.name === '.DS_Store') continue;
+    if (entry.name === ".DS_Store") {
+      continue;
+    }
 
     const srcPath = path.join(src, entry.name);
     let destName = entry.name;
 
     // npm ignores or modifies .gitignore during publishing, so we use _gitignore in template
-    if (destName === '_gitignore') {
-      destName = '.gitignore';
+    if (destName === "_gitignore") {
+      destName = ".gitignore";
     }
 
     const destPath = path.join(dest, destName);
@@ -53,20 +59,20 @@ function copyDir(src, dest) {
 
 function printUsage() {
   console.log(`
-${bold('create-monolayer-app')} - Scaffold a new Monolayer application
+${bold("create-monolayer-app")} - Scaffold a new Monolayer application
 
-${bold('Usage:')}
-  npx create-monolayer-app ${green('<app-name>')}
+${bold("Usage:")}
+  npx create-monolayer-app ${green("<app-name>")}
 
-${bold('Arguments:')}
-  ${green('<app-name>')}    Required. The name of the app (slug, no spaces). A directory
+${bold("Arguments:")}
+  ${green("<app-name>")}    Required. The name of the app (slug, no spaces). A directory
                 with this name will be created in the current working directory.
 
-${bold('Options:')}
+${bold("Options:")}
   -h, --help       Show this help message
   -v, --version    Show version number
 
-${bold('Example:')}
+${bold("Example:")}
   npx create-monolayer-app my-monolayer-app
 `);
 }
@@ -74,22 +80,22 @@ ${bold('Example:')}
 function main() {
   const args = process.argv.slice(2);
 
-  if (args.includes('--help') || args.includes('-h')) {
+  if (args.includes("--help") || args.includes("-h")) {
     printUsage();
     process.exit(0);
   }
 
-  if (args.includes('--version') || args.includes('-v')) {
-    const pkgPath = path.join(__dirname, '../package.json');
-    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  if (args.includes("--version") || args.includes("-v")) {
+    const pkgPath = path.join(__dirname, "../package.json");
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
     console.log(pkg.version);
     process.exit(0);
   }
 
-  const rawArg = args.find((arg) => !arg.startsWith('-'));
+  const rawArg = args.find((arg) => !arg.startsWith("-"));
 
   if (!rawArg) {
-    console.error(red('Error: <app-name> is required.'));
+    console.error(red("Error: <app-name> is required."));
     printUsage();
     process.exit(1);
   }
@@ -97,24 +103,30 @@ function main() {
   const appName = rawArg.trim();
 
   if (appName.length === 0) {
-    console.error(red('Error: App name cannot be empty.'));
+    console.error(red("Error: App name cannot be empty."));
     process.exit(1);
   }
 
   if (/\s/.test(appName)) {
     console.error(red(`Error: App name "${appName}" contains spaces.`));
-    console.error(yellow('App name must be a slug without spaces (e.g. my-app or my_app).'));
+    console.error(
+      yellow("App name must be a slug without spaces (e.g. my-app or my_app)."),
+    );
     process.exit(1);
   }
 
   if (!isValidSlug(appName)) {
     console.error(red(`Error: App name "${appName}" is not a valid slug.`));
-    console.error(yellow('Only alphanumeric characters, hyphens (-), and underscores (_) are allowed.'));
+    console.error(
+      yellow(
+        "Only alphanumeric characters, hyphens (-), and underscores (_) are allowed.",
+      ),
+    );
     process.exit(1);
   }
 
   const targetDir = path.resolve(process.cwd(), appName);
-  const templateDir = path.resolve(__dirname, '../template');
+  const templateDir = path.resolve(__dirname, "../template");
 
   if (!fs.existsSync(templateDir)) {
     console.error(red(`Error: Template directory not found at ${templateDir}`));
@@ -124,56 +136,76 @@ function main() {
   if (fs.existsSync(targetDir)) {
     const existingFiles = fs.readdirSync(targetDir);
     if (existingFiles.length > 0) {
-      console.error(red(`Error: Directory "${appName}" already exists and is not empty.`));
+      console.error(
+        red(`Error: Directory "${appName}" already exists and is not empty.`),
+      );
       process.exit(1);
     }
   }
 
-  console.log(`\nCreating a new Monolayer app in ${green(targetDir)}...\n`);
+  console.log(`\nCreating a new monolayer app in ${green(targetDir)}...\n`);
 
   // 1. Copy template files
   copyDir(templateDir, targetDir);
 
   // 2. Update package.json name
-  const targetPkgPath = path.join(targetDir, 'package.json');
+  const targetPkgPath = path.join(targetDir, "package.json");
   if (fs.existsSync(targetPkgPath)) {
-    const pkg = JSON.parse(fs.readFileSync(targetPkgPath, 'utf8'));
+    const pkg = JSON.parse(fs.readFileSync(targetPkgPath, "utf-8"));
     pkg.name = appName.toLowerCase();
-    fs.writeFileSync(targetPkgPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');
+    fs.writeFileSync(
+      targetPkgPath,
+      `${JSON.stringify(pkg, null, 2)}\n`,
+      "utf-8",
+    );
   }
 
   // 3. Install dependencies with npm
-  console.log(cyan('Installing dependencies with npm...'));
+  console.log(cyan("Installing dependencies with npm..."));
   console.log(dim(`Running npm install in ${targetDir}\n`));
 
-  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-  const installResult = spawnSync(npmCmd, ['install', '--no-audit', '--no-fund'], {
-    cwd: targetDir,
-    stdio: 'inherit',
-  });
+  const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";
+  const installResult = spawnSync(
+    npmCmd,
+    ["install", "--no-audit", "--no-fund"],
+    {
+      cwd: targetDir,
+      stdio: "inherit",
+    },
+  );
 
   if (installResult.status !== 0) {
-    console.error(red('\nFailed to install dependencies with npm.'));
+    console.error(red("\nFailed to install dependencies with npm."));
     process.exit(installResult.status ?? 1);
   }
 
   // 4. Success message
-  console.log(`\n${green('✔')} Successfully created ${bold(appName)} at ${dim(targetDir)}\n`);
-  console.log('Inside that directory, you can run:');
+  console.log(
+    `\n${green("✔")} Successfully created ${bold(appName)} at ${dim(targetDir)}\n`,
+  );
+  console.log("Inside that directory, you can run:");
   console.log(`\n  ${cyan(`cd ${appName}`)}`);
-  console.log(`  ${cyan('npm run dev')}\n`);
-  console.log('Available scripts:');
-  console.log(`  ${cyan('npm run dev')}     - Start the development server with HMR`);
-  console.log(`  ${cyan('npm run build')}   - Build the application for production`);
-  console.log(`  ${cyan('npm run start')}   - Start the production server`);
-  console.log(`  ${cyan('npm run check')}   - Run typegen, TypeScript, and Ultracite checks`);
-  console.log(`  ${cyan('npm run fix')}     - Automatically fix lint and format issues\n`);
-  console.log(bold('Happy coding!'));
+  console.log(`  ${cyan("npm run dev")}\n`);
+  console.log("Available scripts:");
+  console.log(
+    `  ${cyan("npm run dev")}     - Start the development server with HMR`,
+  );
+  console.log(
+    `  ${cyan("npm run build")}   - Build the application for production`,
+  );
+  console.log(`  ${cyan("npm run start")}   - Start the production server`);
+  console.log(
+    `  ${cyan("npm run check")}   - Run typegen, TypeScript, and Ultracite checks`,
+  );
+  console.log(
+    `  ${cyan("npm run fix")}     - Automatically fix lint and format issues\n`,
+  );
+  console.log(bold("Happy coding!"));
 }
 
 try {
   main();
-} catch (err) {
-  console.error(red('\nAn unexpected error occurred:'), err);
+} catch (error) {
+  console.error(red("\nAn unexpected error occurred:"), error);
   process.exit(1);
 }

package/package.json

@@ -1,29 +1,32 @@
 {
   "name": "create-monolayer-app",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "CLI to scaffold a new monolayer application",
-  "type": "module",
+  "keywords": [
+    "create-app",
+    "create-monolayer-app",
+    "monolayer",
+    "react-router",
+    "scaffold",
+    "template"
+  ],
+  "license": "MIT",
   "bin": {
     "create-monolayer-app": "./bin/index.js"
   },
-  "scripts": {
-    "publish:local": "npm publish --registry http://localhost:4873",
-    "unpublish:local": "npm unpublish --registry http://localhost:4873 create-monolayer-app -f"
-  },
   "files": [
     "bin",
     "template"
   ],
+  "type": "module",
+  "scripts": {
+    "release": "npm publish",
+    "prerelease": "rm -rf template && cp -r ./../../apps/monolayer-app-template . && mv monolayer-app-template template && rm -rf template/node_modules template/.gitignore template/.pglite* template/.turbo template/vendor/kysely-dsql/scripts/.pglite*",
+    "publish:local": "npm publish --registry http://localhost:4873",
+    "prepublish:local": "rm -rf template && cp -r ./../../apps/monolayer-app-template . && mv monolayer-app-template template && rm -rf template/node_modules template/.gitignore template/.pglite* template/.turbo template/vendor/kysely-dsql/scripts/.pglite*",
+    "unpublish:local": "npm unpublish --registry http://localhost:4873 create-monolayer-app -f"
+  },
   "engines": {
     "node": ">=22.0.0"
-  },
-  "keywords": [
-    "create-monolayer-app",
-    "create-app",
-    "monolayer",
-    "react-router",
-    "scaffold",
-    "template"
-  ],
-  "license": "MIT"
+  }
 }

package/template/.agents/skills/{monolayer-application-permissions → application-permissions}/SKILL.md

@@ -1,12 +1,12 @@
 ---
-name: monolayer-application-permissions
+name: application-permissions
 description: >
   Apply viewer, editor, and owner permissions in monolayer React Router apps.
   Use for application content access, editing interactions, or changes to
   authentication and user context, including demos with sample or temporary data.
 ---
 
-# Monolayer Application Permissions
+# Application Permissions
 
 Build application features using the existing user context. The application is the sharing boundary: authorized users see the same content, subject to explicit product rules.
 

package/template/.agents/skills/application-permissions/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Application Permissions"
+  short_description: "Use shared application roles in React Router"
+  default_prompt: "Use $application-permissions to apply shared read and write permissions with the existing user middleware."

package/template/.agents/skills/kysely/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: kysely
+description: Build, debug, review, and explain type-safe PostgreSQL with Kysely. Use for schema types, queries, expressions, transactions, migrations, plugins, compiled queries, or Kysely errors.
+---
+
+# Kysely
+
+Use Kysely as a type-safe PostgreSQL query builder. Keep SQL behavior, PostgreSQL behavior, and TypeScript types aligned.
+
+## Workflow
+
+1. Inspect the Kysely version, PostgreSQL version, `pg` settings, `Database` type, migrations, and local query patterns.
+2. Select the smallest applicable reference from the section map below.
+3. Build the query from typed Kysely expressions and PostgreSQL behavior.
+4. Check generated SQL when PostgreSQL behavior, parameters, plugins, or query shape can change the result.
+5. Run the focused type checks and tests that cover the changed query behavior.
+
+The work is complete when strict TypeScript checks pass and focused tests prove the required database behavior.
+
+## Core Rules
+
+- Treat Kysely as a query builder. Model relations and loading behavior explicitly with SQL.
+- Treat PostgreSQL and `pg` as the source for runtime value types.
+- Keep the `Database` type aligned with the deployed schema.
+- Reassign immutable query builders when conditional calls add filters, grouping, or ordering.
+- Use `$if` when a runtime condition changes the selected or returned row shape.
+- Use expression-builder callbacks when visible tables and columns must control type inference.
+- Use the `sql` template tag for missing SQL features. Interpolated values become query parameters.
+- Use trusted identifiers with identifier helpers. Keep untrusted text out of `sql.raw`.
+- Use PostgreSQL behavior for `returning`, JSON helpers, merge queries, DDL, and database functions.
+- Keep migrations independent from current application types and current application functions.
+
+## Section Map
+
+- Read [types.md](references/types.md) for PostgreSQL schema types, operation types, generated types, and `pg` runtime values.
+- Read [query-building.md](references/query-building.md) for selects, filters, joins, writes, CTEs, merge queries, and execution methods.
+- Read [expressions-and-helpers.md](references/expressions-and-helpers.md) for expressions, raw SQL, conditional queries, dynamic references, and reusable helpers.
+- Read [transactions.md](references/transactions.md) for callback transactions, controlled transactions, and savepoints.
+- Read [migrations.md](references/migrations.md) for migration files, schema changes, migration order, and execution.
+- Read [execution-plugins-and-runtime.md](references/execution-plugins-and-runtime.md) for execution flow, plugins, logging, introspection, and compiled PostgreSQL queries.
+- Read [troubleshooting-and-boundaries.md](references/troubleshooting-and-boundaries.md) for runtime type errors, nullable results, deep types, joins, schemas, and relation loading.
+- Read [official-docs-map.md](references/official-docs-map.md) when an exact API detail needs its official Kysely source page.
+
+## Source Policy
+
+These references summarize the PostgreSQL sections in the official Kysely `llms-full.txt` document retrieved on 2026-08-22.
+
+Inspect local package types first when the installed version differs from the source. Use the official API documentation for exact signatures.

package/template/.agents/skills/kysely/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Kysely"
+  short_description: "Build type-safe PostgreSQL with Kysely"
+  default_prompt: "Use $kysely to implement a type-safe PostgreSQL query for this application."

package/template/.agents/skills/kysely/references/execution-plugins-and-runtime.md

@@ -0,0 +1,67 @@
+# Execution, plugins, and runtime
+
+Use this reference for query execution, plugins, diagnostics, compiled queries, and compile-only environments.
+
+## Execution flow
+
+Kysely query building is immutable. Each query-builder call returns a new abstract syntax tree.
+
+Execution follows this sequence:
+
+1. The query executor calls each plugin `transformQuery` method.
+2. The PostgreSQL compiler creates SQL text and parameters.
+3. The Kysely driver gets a `pg` connection.
+4. The database connection executes the compiled query.
+5. `pg` returns values through a standard Kysely query result.
+6. The query executor calls each plugin `transformResult` method.
+
+This sequence explains why plugins can change identifiers, SQL structure, and returned data.
+
+## Plugins
+
+Register global plugins in the Kysely configuration. Use `withPlugin` for one query chain.
+
+Built-in plugins include these plugins:
+
+- `CamelCasePlugin` maps database snake-case names to JavaScript camel-case names.
+- `DeduplicateJoinsPlugin` removes duplicate joins when its structural comparison succeeds.
+- `HandleEmptyInListsPlugin` selects behavior for empty `IN` and `NOT IN` lists.
+- `SafeNullComparisonPlugin` maps null equality operators to `IS` and `IS NOT`.
+
+Check plugin order because each transformation receives the prior transformed query or result.
+
+## Logging
+
+The Kysely `log` setting accepts log levels or a logging function. Use a function for structured application events.
+
+Query events include compiled SQL, parameters, duration, and query results. Error events include the database error.
+
+Apply the repository redaction rules before logs record parameters or database errors.
+
+## Compile and execute separately
+
+Call `.compile()` to get a `CompiledQuery` with SQL, parameters, and the Kysely query tree.
+
+Use `InferResult<typeof query>` or `InferResult<typeof compiledQuery>` to keep the inferred row type.
+
+Execute a compiled query with a connected Kysely instance:
+
+```typescript
+const query = db
+  .selectFrom("person")
+  .select("first_name")
+  .where("id", "=", personId)
+
+const compiled = query.compile()
+const result = await db.executeQuery(compiled)
+```
+
+A `DummyDriver` creates a compile-only Kysely instance. Use `PostgresAdapter`, `PostgresIntrospector`, and `PostgresQueryCompiler` with it.
+
+Compile-only mode creates PostgreSQL SQL without a database connection. Executing through `DummyDriver` does not contact PostgreSQL.
+
+## Runtime checks
+
+Check the `pg` documentation when a value has an unexpected runtime type. Kysely returns `pg` values without conversion by default.
+
+Configure `pg` type parsers when the application requires different PostgreSQL runtime values.

package/template/.agents/skills/kysely/references/expressions-and-helpers.md

@@ -0,0 +1,102 @@
+# Expressions and helpers
+
+Use this reference for complex expressions, raw SQL, conditional output, and reusable query parts.
+
+## Expression builder
+
+`Expression<T>` is the common Kysely query part. `T` is the expression output type.
+
+Use callback expression builders when the visible tables must control available references.
+
+```typescript
+const row = await db
+  .selectFrom("person")
+  .select(({ fn, ref, val }) => [
+    fn<string>("upper", ["first_name"]).as("upper_first_name"),
+    ref("last_name").as("family_name"),
+    val("person").as("kind"),
+  ])
+  .executeTakeFirstOrThrow()
+```
+
+Expression-builder callbacks infer the query context. A global `expressionBuilder<DB>()` has no visible tables by default.
+
+Use `Expression<SqlBool>` for reusable predicates. Use `Expression<T>` parameters for reusable value helpers.
+
+## Conditional queries
+
+Kysely query builders are immutable. A reassigned builder keeps its original static variable type.
+
+Conditional filters, groups, and ordering usually keep the row type unchanged. Reassign those builders directly.
+
+Conditional selects, returning clauses, and joins change the row type. Use `$if` for optional output properties.
+
+```typescript
+const row = await db
+  .selectFrom("person")
+  .select("first_name")
+  .$if(includeLastName, (query) => query.select("last_name"))
+  .where("id", "=", personId)
+  .executeTakeFirstOrThrow()
+```
+
+The `last_name` result property is optional. Use explicit branches when the function needs a discriminated result union.
+
+## Raw SQL
+
+Use the `sql` template tag when Kysely has no suitable typed method.
+
+```typescript
+import { sql } from "kysely"
+
+const rows = await db
+  .selectFrom("person")
+  .select(sql<string>`upper(${sql.ref("first_name")})`.as("name"))
+  .where("id", "=", personId)
+  .execute()
+```
+
+Normal interpolated values become query parameters. Expressions inside interpolation remain SQL expressions.
+
+Choose identifier helpers by purpose:
+
+- `sql.ref` creates a column reference.
+- `sql.table` creates a table reference.
+- `sql.id` creates a general identifier.
+- `sql.join` joins expressions with a SQL separator.
+- `sql.val` creates a parameterized value.
+- `sql.lit` creates a literal.
+- `sql.raw` inserts trusted SQL text unchanged.
+
+Validate runtime identifiers against an application allowlist. Raw identifier helpers do not make untrusted names safe.
+
+Use a generic type on `sql<T>` because Kysely cannot infer raw SQL output types.
+
+## Dynamic references
+
+Use `db.dynamic.ref` when a validated runtime value selects a column. The result type can become a union of optional properties.
+
+Prefer ordinary typed references when the column name is known during compilation.
+
+## Reusable helpers
+
+Accept expressions instead of raw values when callers can pass columns, values, functions, or subqueries.
+
+```typescript
+import type { Expression } from "kysely"
+import { sql } from "kysely"
+
+function upper(value: Expression<string>) {
+  return sql<string>`upper(${value})`
+}
+```
+
+Add `as` when a helper appears in a select list. Use `$asScalar()` when a one-column subquery must act as a scalar expression.
+
+Use conditional generic types when a helper must preserve nullable input behavior. Use `$notNull()` only with a proven SQL invariant.
+
+## Extension choices
+
+Prefer a small helper that returns `Expression<T>` or `AliasedExpression<T, A>`. This choice keeps the public API small.
+
+Implement Kysely interfaces directly only when raw builders cannot express the required operation. Preserve operation-node immutability in custom implementations.

package/template/.agents/skills/kysely/references/migrations.md

@@ -0,0 +1,43 @@
+# Migrations
+
+Use this reference for migration files, schema changes, migration order, and execution.
+
+## Migration files
+
+Migration modules export `up` and `down` functions.
+
+```typescript
+import type { Kysely } from "kysely"
+
+export async function up(db: Kysely<any>): Promise<void> {
+  await db.schema
+    .createTable("person")
+    .addColumn("id", "serial", (column) => column.primaryKey())
+    .addColumn("name", "varchar", (column) => column.notNull())
+    .execute()
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema.dropTable("person").execute()
+}
+```
+
+The official guidance uses `Kysely<any>` in migrations. A migration represents its historical schema, not the current application schema.
+
+Keep migration behavior frozen in time. Put required data changes and SQL inside the migration boundary.
+
+## Order and execution
+
+Kysely sorts migration names with alphanumeric order. Prefix names with an ISO 8601 date or another sortable identifier.
+
+The default migrator verifies that file order matches the prior database execution order. `allowUnorderedMigrations` relaxes this check for parallel teams.
+
+Pending unordered migrations still run in alphanumeric order. Down migrations run in reverse execution order.
+
+`Migrator.migrateToLatest()` uses a database lock. Concurrent application instances execute each migration once.
+
+Always inspect the returned `error` and `results`. Destroy the migration Kysely instance after the runner finishes.
+
+## Schema operations
+
+Use PostgreSQL data types, defaults, constraints, and index behavior. Check the generated SQL before production use.