@nilejs/cli 1.0.0 → 1.0.2

package/README.md

@@ -20,7 +20,7 @@ The starter includes:
 
 - `src/index.ts`: server entry point on Bun's native HTTP server, with a logger and an `onBoot` schema push
 - `src/db/`: PGlite and Drizzle client, the `tasks` table and a `taskModel` built with `createModel`
-- `src/services/`: a `tasks` service with create, list, get, update and delete actions
+- `src/services/`: an explicit registry and domain entry point for a `tasks` service with create, list, get, update and delete actions
 - `Dockerfile`, `docker-compose.yml` and `docker-compose.dev.yml` for container deployments
 - `drizzle.config.ts`, `.env.example`, `tsconfig.json` and `package.json`
 
@@ -48,7 +48,7 @@ Creates:
 ```text
 src/services/users/
   actions/sample.ts   Sample action with a schema, an input type and a named handler
-  index.ts            Exports the sample action
+  index.ts            Registers the service and its public actions
 ```
 
 The CLI then asks whether to register the service in `src/services/services.config.ts`. If you decline, it prints the lines to add yourself.
@@ -85,7 +85,7 @@ export const getUserAction = createAction<GetUserInput>({
 });
 ```
 
-Kebab-case names become camelCase variables and PascalCase types. Register the action by importing it in `src/services/services.config.ts` and adding it to the service's `actions` list.
+Kebab-case names become camelCase variables and PascalCase types. Register the action by importing it in `src/services/users/index.ts` and adding it to the service’s `actions` list. The root registry imports services, not individual actions.
 
 ### Schemas and types
 
@@ -96,14 +96,24 @@ bun run gen schema
 Reads every action's validation schema from `src/services/services.config.ts` and writes:
 
 - `src/generated/schemas.ts`: named Zod schemas, such as `tasksCreateSchema`
-- `src/generated/types.ts`: inferred types, such as `TasksCreatePayload`
+- `src/generated/types.ts`: input types, such as `TasksCreatePayload`
 
 | Flag | Description |
 |---|---|
 | `-e, --entry <path>` | Path to the services config (detected by default) |
 | `-o, --output <path>` | Output directory (default: `src/generated`) |
 
-Actions without a validation schema are skipped and listed in the output. Share the generated files with a frontend to validate forms with the same rules as the server.
+Every registered action is included in `ServicePayloads`. Actions without a validation schema accept an object payload (`Record<string, unknown>`), so actions such as `tasks.list` can be called with `{}`. This fallback does not add server-side validation. Schemas that cannot be converted are reported separately. Share the generated files with a frontend to validate forms with the same rules as the server.
+
+## Current starter
+
+CLI 1.0.2 targets Nile `^1.0.4`, Zod 4, TypeScript 7 and the Drizzle model helpers. The generated layout passes Nile’s strict boot checks. Database setup returns a Result and prevents startup on failure; shutdown drains Nile’s work before closing PGlite. Helpers are available as `utils.createModel`, and Result helpers come from `@nilejs/nile/fp`.
+
+Existing apps are not rewritten when the CLI updates. For an older starter, add a service entry point at `src/services/<domain>/index.ts`, register its actions there, and import that service from `services.config.ts`. [Nile’s migration notes](https://github.com/nile-js/nile/blob/main/packages/nile/docs/release-migration.md) describe the current error and startup behavior.
+
+## Coding assistants
+
+The starter includes `SKILL.md` with the current Nile action pattern, service layout, Results, access policies and client calls. Ask your assistant to read it before changing the backend. After updating Nile, use the version shipped at `node_modules/@nilejs/nile/SKILL.md`.
 
 ## Requirements
 

package/dist/index.js

@@ -4,7 +4,7 @@
 import { resolve as resolve6 } from "node:path";
 import { Command } from "commander";
 // package.json
-var version = "1.0.0";
+var version = "1.0.2";
 
 // src/commands/generate-action.ts
 import { resolve } from "node:path";
@@ -141,8 +141,8 @@ var generateActionCommand = async (serviceName, actionName, options = {}) => {
   spinner.stop(`Action created at src/services/${serviceName}/${relative}`);
   const camel = toCamelCase(actionName);
   console.log("");
-  hint("Register the action in your service config:");
-  hint(`  import { ${camel}Action } from "./${serviceName}/actions/${actionName}";`);
+  hint("Import the action in your service index.ts and add it to actions:");
+  hint(`  import { ${camel}Action } from "./actions/${actionName}";`);
   outro();
 };
 
@@ -186,12 +186,14 @@ var inputPrompt = (question) => {
 // src/utils/schema-codegen.ts
 import { jsonSchemaToZod } from "json-schema-to-zod";
 var toSchemaExportName = (service, action) => {
-  const pascalAction = action.charAt(0).toUpperCase() + action.slice(1);
+  const camelAction = toCamelCase2(action);
+  const pascalAction = camelAction.charAt(0).toUpperCase() + camelAction.slice(1);
   return `${toCamelCase2(service)}${pascalAction}Schema`;
 };
 var toTypeExportName = (service, action) => {
   const pascalService = toCamelCase2(service).charAt(0).toUpperCase() + toCamelCase2(service).slice(1);
-  const pascalAction = action.charAt(0).toUpperCase() + action.slice(1);
+  const camelAction = toCamelCase2(action);
+  const pascalAction = camelAction.charAt(0).toUpperCase() + camelAction.slice(1);
   return `${pascalService}${pascalAction}Payload`;
 };
 var toCamelCase2 = (str) => str.replace(/-([a-z])/g, (_, char) => char.toUpperCase());
@@ -208,7 +210,7 @@ var buildSchemaEntries = (extraction) => {
   const entries = [];
   for (const [serviceName, actions] of Object.entries(extraction.schemas)) {
     for (const [actionName, jsonSchema] of Object.entries(actions)) {
-      const zodCode = jsonSchemaToZod(jsonSchema, {
+      const zodCode = jsonSchema === null ? "z.record(z.string(), z.unknown())" : jsonSchemaToZod(jsonSchema, {
         noImport: true
       });
       entries.push({
@@ -235,7 +237,7 @@ var generateSchemasFile = (extraction) => {
     lines.push("");
   }
   if (extraction.skipped.length > 0) {
-    lines.push(`// Skipped (no validation): ${extraction.skipped.join(", ")}`);
+    lines.push(`// Skipped (schema conversion failed): ${extraction.skipped.join(", ")}`);
     lines.push("");
   }
   return lines.join(`
@@ -245,7 +247,7 @@ var generateTypesFile = (extraction) => {
   const entries = buildSchemaEntries(extraction);
   if (entries.length === 0) {
     return `${generateHeader()}
-// No action types found.
+export type ServicePayloads = Record<never, never>;
 `;
   }
   const schemaImports = entries.map((e) => e.exportName);
@@ -258,7 +260,7 @@ var generateTypesFile = (extraction) => {
     ""
   ];
   for (const entry of entries) {
-    lines.push(`export type ${entry.typeName} = z.infer<typeof ${entry.exportName}>;`);
+    lines.push(`export type ${entry.typeName} = z.input<typeof ${entry.exportName}>;`);
   }
   lines.push("");
   lines.push("/** Map of all services and their action payloads for @nilejs/client */");
@@ -300,12 +302,12 @@ for (const service of services) {
 
   for (const action of service.actions) {
     if (!action.validation) {
-      skipped.push(\`\${service.name}.\${action.name}\`);
+      serviceSchemas[action.name] = null;
       continue;
     }
 
     try {
-      const jsonSchema = z.toJSONSchema(action.validation, { unrepresentable: "any" });
+      const jsonSchema = z.toJSONSchema(action.validation, { unrepresentable: "any", io: "input" });
       serviceSchemas[action.name] = jsonSchema;
     } catch {
       skipped.push(\`\${service.name}.\${action.name}\`);
@@ -417,15 +419,8 @@ var generateSchemaCommand = async (options) => {
     error(err instanceof Error ? err.message : String(err));
     process.exit(1);
   }
-  const schemaCount = Object.values(extraction.schemas).reduce((sum, actions) => sum + Object.keys(actions).length, 0);
-  if (schemaCount === 0) {
-    spinner.stop("No action schemas found");
-    warn("None of the actions have validation schemas defined.");
-    hint("Add a Zod validation schema to your actions to generate types.");
-    outro();
-    return;
-  }
-  spinner.stop(`Extracted ${schemaCount} action schema${schemaCount > 1 ? "s" : ""}`);
+  const actionCount = Object.values(extraction.schemas).reduce((sum, actions) => sum + Object.keys(actions).length, 0);
+  spinner.stop(`Read ${actionCount} action contract${actionCount === 1 ? "" : "s"}`);
   const outputDir = resolve3(projectRoot, options.output ?? DEFAULT_OUTPUT_DIR);
   await ensureDir(outputDir);
   const schemasContent = generateSchemasFile(extraction);
@@ -438,7 +433,7 @@ var generateSchemaCommand = async (options) => {
   success(`Generated ${typesPath.replace(projectRoot, "").replace(LEADING_SLASH2, "")}`);
   if (extraction.skipped.length > 0) {
     console.log("");
-    hint(`Skipped ${extraction.skipped.length} action(s) without validation:`);
+    warn(`Could not convert validation schemas for ${extraction.skipped.length} action(s):`);
     hint(extraction.skipped.join(", "));
   }
   outro();
@@ -478,17 +473,21 @@ export const sample${pascal}Action = createAction<Sample${pascal}Input>({
 };
 var generateBarrelContent = (serviceName) => {
   const pascal = toPascalCase2(serviceName);
-  return `export { sample${pascal}Action } from "./actions/sample";
+  const camel = toCamelCase3(serviceName);
+  return `import { createService } from "@nilejs/nile";
+import { sample${pascal}Action } from "./actions/sample";
+
+export const ${camel}Service = createService({
+  name: "${serviceName}",
+  description: "${pascal} service",
+  actions: [sample${pascal}Action],
+});
 `;
 };
 var generateConfigSnippet = (serviceName) => {
-  const pascal = toPascalCase2(serviceName);
-  const importLine = `import { sample${pascal}Action } from "./${serviceName}/actions/sample";`;
-  const serviceEntry = `  {
-    name: "${serviceName}",
-    description: "${pascal} service",
-    actions: [sample${pascal}Action],
-  },`;
+  const camel = toCamelCase3(serviceName);
+  const importLine = `import { ${camel}Service } from "./${serviceName}";`;
+  const serviceEntry = `  ${camel}Service,`;
   return `${importLine}
 
 // Add to services array:
@@ -497,8 +496,8 @@ ${serviceEntry}`;
 var autoRegisterService = async (configPath, serviceName) => {
   try {
     let content = await readFileContent(configPath);
-    const pascal = toPascalCase2(serviceName);
-    const importLine = `import { sample${pascal}Action } from "./${serviceName}/actions/sample";`;
+    const camel = toCamelCase3(serviceName);
+    const importLine = `import { ${camel}Service } from "./${serviceName}";`;
     const importLines = content.split(`
 `).filter((line) => line.startsWith("import "));
     if (importLines.length === 0) {
@@ -510,19 +509,18 @@ var autoRegisterService = async (configPath, serviceName) => {
     }
     content = content.replace(lastImport, `${lastImport}
 ${importLine}`);
-    const serviceEntry = `  {
-    name: "${serviceName}",
-    description: "${pascal} service",
-    actions: [sample${pascal}Action],
-  },`;
+    const serviceEntry = `  ${camel}Service,`;
     const wrappedClosingIndex = content.lastIndexOf("]);");
     const plainClosingIndex = content.lastIndexOf("];");
     const closingIndex = Math.max(wrappedClosingIndex, plainClosingIndex);
     if (closingIndex === -1) {
       return false;
     }
-    content = content.slice(0, closingIndex) + serviceEntry + `
-` + content.slice(closingIndex);
+    const prefix = content.slice(0, closingIndex).trimEnd();
+    const separator = prefix.endsWith("[") || prefix.endsWith(",") ? "" : ",";
+    content = `${prefix}${separator}
+${serviceEntry}
+${content.slice(closingIndex)}`;
     await writeFileSafe(configPath, content);
     return true;
   } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nilejs/cli",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "CLI for scaffolding and generating Nile backend projects",
   "type": "module",
   "bin": {
@@ -17,12 +17,14 @@
   },
   "devDependencies": {
     "@types/node": "^22.8.1",
-    "typescript": "^5"
+    "typescript": "^5",
+    "zod": "4.6.7"
   },
   "scripts": {
     "build": "bun run scripts/build.ts",
     "dev": "bun run src/index.ts",
     "typecheck": "tsc --noEmit",
-    "export": "bun run typecheck && bun run build && node dist/index.js --version"
+    "export": "bun run typecheck && bun run build && node dist/index.js --version",
+    "test": "bun test scripts/schema-contracts.spec.ts"
   }
 }

package/template/README.md

@@ -4,6 +4,8 @@ Built with [Nile Js](https://nile-js.github.io/nile/). Read the [getting started
 
 The server runs on Bun's native HTTP server (`runtime: "bun", native: true` in `src/index.ts`). REST settings live under `rest`; custom routes and middleware are available on `server.nativeRest`.
 
+The included `SKILL.md` gives coding assistants the action pattern, service layout and current error-handling rules. After a Nile upgrade, use `node_modules/@nilejs/nile/SKILL.md` as the current reference.
+
 ## Setup
 
 ```bash
@@ -41,17 +43,19 @@ src/
       index.ts                    # Barrel export
   services/
     services.config.ts            # Service registry
-    tasks/actions/
-      create.ts                   # Create task action
-      list.ts                     # List tasks action
-      get.ts                      # Get task by ID action
-      update.ts                   # Update task action
-      delete.ts                   # Delete task action
+    tasks/
+      index.ts                    # Registers the tasks service
+      actions/
+        create.ts                   # Create task action
+        list.ts                     # List tasks action
+        get.ts                      # Get task by ID action
+        update.ts                   # Update task action
+        delete.ts                   # Delete task action
 ```
 
 ## Usage
 
-All requests go through a single POST endpoint. The `intent` field determines the operation.
+HTTP action calls go through a single POST endpoint. The `intent` field determines the operation.
 
 ### Explore available services
 
@@ -77,6 +81,12 @@ curl -X POST http://localhost:8000/api/services \
   -d '{"intent":"schema","service":"tasks","action":"*","payload":{}}'
 ```
 
+Responses have exactly `status`, `message` and `data`. The default success message is `Action completed.` Validation failures contain Zod’s readable message and `{ errorCode, issues }` in `data`. Unexpected failures use a generated diagnostic reference linked to the log’s `log_id`; internal `raw` causes are never sent to the frontend.
+
+## Optional features
+
+Keep business logic in actions and ordinary functions. Configure other features when the product needs them: [typed Socket.IO topics](https://nile-js.github.io/nile/guide/features/websockets/), [cron jobs](https://nile-js.github.io/nile/guide/features/cron-jobs/), [rate limits](https://nile-js.github.io/nile/guide/features/rate-limiting/), [queues](https://nile-js.github.io/nile/guide/features/queues-debounce-throttle/) and [telemetry](https://nile-js.github.io/nile/guide/features/telemetry/). The frontend package provides both `createNileClient` and a separate `createNileSocketClient`.
+
 ## Adding services
 
 Generate a new service with the CLI:
@@ -85,7 +95,7 @@ Generate a new service with the CLI:
 bun run gen service users
 ```
 
-The generator offers to register the service in `src/services/services.config.ts`. To add one by hand, create a folder under `src/services/` with an `actions/` folder and register its actions in `services.config.ts`.
+The generator offers to register the service in `src/services/services.config.ts`. To add one by hand, create a folder under `src/services/` with an `actions/` folder and create an `index.ts` that registers its actions with `createService`. Import that service into `services.config.ts`. Nile checks this layout at startup and fails on violations by default. Set `project.structure` to `"warn"` explicitly if you need to migrate an older layout gradually.
 
 ## Adding actions
 
@@ -95,7 +105,7 @@ Generate a new action in an existing service:
 bun run gen action users get-user
 ```
 
-This creates `src/services/users/actions/get-user.ts`. Each action file exports one action created with `createAction`: a named Zod schema, an input type inferred from it and a named handler that returns `Ok(data)` or `Err(message)`. Import the action in `src/services/services.config.ts` and add it to the service's `actions` list.
+This creates `src/services/users/actions/get-user.ts`. Each action file exports one action created with `createAction`: a named Zod schema, an input type inferred from it and a named handler that returns `Ok(data)` or `Err(message)`. Import the action in `src/services/users/index.ts` and add it to the service's `actions` list.
 
 ## Generating schemas and types
 
@@ -108,7 +118,7 @@ bun run gen schema
 This auto-detects `src/services/services.config.ts`, reads validation schemas from all actions, and outputs two files:
 
 - `src/generated/schemas.ts`: named Zod schema exports
-- `src/generated/types.ts`: inferred TypeScript types via `z.infer`
+- `src/generated/types.ts`: input TypeScript types via `z.input`
 
 Options:
 
@@ -117,7 +127,7 @@ Options:
 | `-e, --entry <path>` | Path to services config (auto-detected by default) |
 | `-o, --output <path>` | Output directory (default: `src/generated`) |
 
-Actions without a validation schema are skipped and listed in the CLI output.
+Every registered action is included in `ServicePayloads`. Actions without validation accept an object payload (`Record<string, unknown>`); call `tasks.list` with `{}`. This fallback does not add server-side validation. Schemas that cannot be converted are reported separately.
 
 ## Database
 

package/template/SKILL.md

@@ -0,0 +1,343 @@
+---
+name: nile
+description: Work in a Nile Js backend (@nilejs/nile 1.x). Organize business operations as services and actions with Zod validation, Result returns, hooks, JWT protection and typed clients. Use when adding or changing actions, services, hooks, uploads, topics, schedules or the @nilejs/client calls in a Nile Js project.
+license: MIT
+---
+
+# Working in a Nile Js application
+
+Nile Js organizes a backend into **services** (business areas) and **actions** (one operation each). Read the project's `src/services/services.config.ts` first: it is the registry of every action the server exposes. Then read the domain’s `index.ts`, a neighboring action, its model and any global policy hooks. Follow one operation from registration to persistence before changing it.
+
+Use Nile’s conventions to make business operations easy to find. Prefer named functions, explicit inputs and early Result branches. Choose FP helpers when they make absence, failure, transformation or async control clearer; ordinary functions and straightforward `if` statements remain useful.
+
+Documentation: https://nile-js.github.io/nile/guide/
+Feature pages: https://nile-js.github.io/nile/guide/features/
+Examples: https://nile-js.github.io/nile/guide/examples/
+Every guide page is also listed in https://nile-js.github.io/nile/llms.txt
+
+## Project structure
+
+Service and action entry points are the enforced core. The rest of this tree shows where supporting code goes when needed. Add optional layers when a real feature needs them; do not generate empty layers up front.
+
+```text
+src/
+  index.ts                         listener and process lifecycle
+  server.ts                        optional server composition
+  config.ts                        optional environment parsing in one place
+  services/
+    services.config.ts             explicit service registry
+    projects/
+      index.ts                     createService and public actions
+      actions/
+        create.ts                  a small action
+        archive/
+          archive.ts               a larger action's entry point
+          index.ts                 exports archiveAction
+          modules/                 archive's private helpers
+      modules/                     helpers shared within this domain
+  db/
+    client.ts                      connection and driver
+    models/                        persistence operations
+  hooks/                           shared action policies
+  business/                        optional reusable domain functions
+  generated/                       client payload/schema contracts
+```
+
+Create a project with `bunx @nilejs/cli new my-app`. Start it with `bun run dev`. Generate code with `bun run gen service <name>` and `bun run gen action <service> <action>`. Generate Zod schemas and accepted payload types from validations with `bun run gen schema`. Handler types describe parsed output (`z.infer`); client payload types describe input (`z.input`), so fields with defaults can be omitted by callers.
+
+Structure violations fail startup by default. An application needs `src/index.ts` or `src/server.ts`, `src/services/services.config.ts`, and each service’s `index.ts` and `actions/`. For a growing action, use `actions/archive/archive.ts`, an `index.ts` export and private helpers in `actions/archive/modules/`. Action entry points above 400 lines are reported for refactoring. `project: { root: ".", structure: "warn" }` reports violations without stopping; `false` disables inspection. Source-less bundles skip inspection unless a root is explicit.
+
+## The action pattern
+
+Every action uses a named schema, an inferred input type, a separately written named handler and `createAction<T>`:
+
+```ts
+import { createAction } from "@nilejs/nile";
+import { Err, Ok } from "@nilejs/nile/fp";
+import { z } from "zod";
+
+const createProjectSchema = z.object({
+  name: z.string().trim().min(3, "Name must have at least 3 characters"),
+});
+
+type CreateProjectInput = z.infer<typeof createProjectSchema>;
+
+const createProjectHandler = (input: CreateProjectInput) => {
+  if (input.name === "system") {
+    return Err("Choose a different project name");
+  }
+
+  return Ok({ project: { name: input.name } });
+};
+
+export const createProjectAction = createAction<CreateProjectInput>({
+  name: "create",
+  description: "Create a project",
+  validation: createProjectSchema,
+  handler: createProjectHandler,
+});
+```
+
+Register the action in its service entry point, then register the service:
+
+```ts
+// src/services/projects/index.ts
+import { createService } from "@nilejs/nile";
+import { createProjectAction } from "./actions/create";
+
+export const projectsService = createService({
+  name: "projects",
+  description: "Project operations",
+  actions: [createProjectAction],
+});
+```
+
+```ts
+// src/services/services.config.ts
+import { createServices } from "@nilejs/nile";
+import { projectsService } from "./projects";
+
+export const services = createServices([projectsService]);
+```
+
+Action names are unique within a service. Folder names do not create routes; only the registry does.
+
+## Handlers take (data, context)
+
+Nile Js calls every handler with two arguments: the validated input and the execution's `NileContext`. The type marks the context optional. Use `createAction<Input>` for the schema’s parsed output type, and import `NileContext` when annotating a named handler’s second argument. Read an optional context with `?.` or explicitly reject its absence before using it.
+
+- `context.getSession("rest")` returns the verified JWT identity (`userId`, `organizationId` and other claims) for a protected action.
+- `context.resources` holds what `createNileServer` received (`logger`, `database`).
+- `context.execution` holds `requestId`, `transport`, `signal` and `clientKey`.
+- `context.updateHookState` and `context.hookContext.state` are per execution. `context.set` and `context.get` are shared by every request in the process.
+- `getContext<T>()` returns the context outside a handler. It throws before `createNileServer` runs.
+
+## Results
+
+Handlers return `Ok(value)` or `Err(message)` from `@nilejs/nile/fp`, which re-exports `slang-ts`. Check `isErr` before reading `value`. Use `safeTry` around a call that can throw or reject. Use `utils.handleError({ message, data })` with `import { utils } from "@nilejs/nile"` to log an error and return it as an `Err` in one step.
+
+The default success message is `Action completed.` Set `successMessage` on the action, or return `Ok(value, message)` to choose one per call; the handler's message wins.
+
+HTTP envelope: success is `{ status: true, message, data }`. Failure is `{ status: false, message, data }`; inspect the envelope rather than assuming every failure has the same HTTP status. Validation failures use Zod’s prettified message (or an explicit validation message) and put a generated unique reference in `data.errorCode` alongside field paths in `data.issues`.
+
+Slang 0.2.2 preserves caught causes on `result.raw`. `safeTry` returns a Result directly, including when the callback returns a Result; never expect a Result inside `result.value`. Nested `Ok(Ok(...))` and `Ok(Err(...))` are rejected. Return an existing Result directly.
+
+`dbTry` is removed. For a database promise, use `safeTry`, inspect `result.raw` internally and pass `utils.describeError(result.raw)` to `utils.handleError` with a deliberate caller-safe message. `result.error` may contain driver text and must not be forwarded blindly. Unexpected throws inside Nile-managed work are logged and become `Error Code: <unique-code> - could not complete the action`. The generated reference matches the log’s `log_id`. Never use it as a stable error category. Custom success and intentional `Err` messages retain their wording.
+
+`raw` is reserved for internal diagnostics and removed recursively from outgoing JSON and Socket.IO messages. Choose another name for public domain fields. Do not rely on that filter to sanitize secrets stored under other names.
+
+## Choose FP helpers for the job
+
+Import from `@nilejs/nile/fp`, so application code and Nile share the same Slang types. Import Nile-specific helpers through `utils` from `@nilejs/nile`. Check the installed declarations before using an unfamiliar helper; do not copy APIs from a different FP library.
+
+| Need | Use | Important boundary |
+|---|---|---|
+| An operation can succeed or fail | `Ok`, `Err`, `Result` | Check `isErr` before reading `value`; propagate a narrowed failure directly. |
+| A dependency can throw or reject | `safeTry` | Await it. A caught failure still needs a safe caller message. |
+| A value may legitimately be absent | `option`, `Option` | Absence is different from a failed lookup. |
+| Both Result or Option branches produce a value | `match` | Supply both branches; callbacks receive the variant, not its unwrapped payload. |
+| Several domain cases choose behavior | `matchAll` | Include the `_` fallback; keep business cases explicit. |
+| A successful value needs a transformation | `andThen` | It propagates failure; await async transformations. Do not return `undefined` to mean removal. |
+| Several Result-producing steps form a pipeline | `pipe` | Use the installed `.run()` API. A plain sequence of early returns is often easier to read. |
+| Indexed slicing, shaping or set operations need explicit failure handling | `list`, `struct`, `sets`, `Ok.iterate` | Collection chains can return `Fallible`; finish with a deliberate fallback or handle the failure. |
+| One async operation needs cancellation/deadline control | `superPromise` | It settles to a Result. Pass its signal to the dependency. |
+| Several controlled tasks share a concurrency budget | `taskGroup`, `superRunner` | Share the group across calls; creating one per action execution does not bound total concurrency. |
+| A pure calculation is reused with the same arguments | `memoized` | It caches by argument identity; do not cache sessions, permissions or mutable database reads this way. |
+| An in-process notification coordinates local functions | `createChannel`, `createSignal` | These are local primitives, not Nile’s schema-validated Socket.IO topics or a cross-process event bus. |
+
+### Propagate Results instead of nesting them
+
+Use an early failure branch when it makes the operation easier to follow. Once a Result is narrowed to `Err`, return it directly. A handler returning a Result does not need another `Ok` around that Result.
+
+```ts
+import { Err, Ok, type Result } from "@nilejs/nile/fp";
+
+const calculateTotal = (quantity: number): Result<number, string> => {
+  if (quantity < 1) {
+    return Err("Choose at least one item");
+  }
+  return Ok(quantity * 100);
+};
+
+export const prepareQuote = (quantity: number) => {
+  const total = calculateTotal(quantity);
+  if (total.isErr) {
+    return total;
+  }
+  return Ok({ total: total.value });
+};
+```
+
+`andThen` is useful for a short transformation of a successful value. In this Slang version, callbacks may return a plain value or a Result; the returned Result is not nested. A callback returning `undefined` preserves the original value, so do not use that to remove data. Callback exceptions become failures; keep them free of secret-bearing exception messages if the Result will reach a caller.
+
+### Model expected absence explicitly
+
+Use an Option when “not configured yet” is a valid answer. Use an Err when the operation cannot proceed without the value. Do not silently turn a failed database call into an empty collection or a missing setting.
+
+```ts
+import { match, option } from "@nilejs/nile/fp";
+
+export const getDisplayName = (name: string | null) => {
+  return match(option(name), {
+    Some: (present) => {
+      return present.value;
+    },
+    None: () => {
+      return "Unnamed project";
+    },
+  });
+};
+```
+
+Slang’s absence rules matter: `0` and `false` are present; `null`, `undefined`, empty strings and non-finite numbers are absent. Use an explicit check or a schema instead when an empty string is meaningful domain data. `.unwrap().else(fallback)` is for a deliberate fallback; `.expect()` and `.panic()` throw and should not replace normal input validation or business refusals.
+
+### Translate dependency failures at their boundary
+
+Use `safeTry` for a promise that can throw. Keep the original cause for bounded internal diagnostics and return an intentional message. A returned `Err` from your own code may already be safe and logged; propagate it instead of logging it repeatedly.
+
+```ts
+import { utils, type NileLogger } from "@nilejs/nile";
+import { Ok, safeTry } from "@nilejs/nile/fp";
+
+export const readProviderStatus = async (
+  url: string,
+  signal: AbortSignal,
+  logger: NileLogger
+) => {
+  const response = await safeTry(() => fetch(url, { signal: signal }));
+  if (response.isErr) {
+    return utils.handleError({
+      message: "Could not check the provider status",
+      atFunction: "readProviderStatus",
+      data: utils.describeError(response.raw),
+      logger: logger,
+    });
+  }
+  return Ok({ available: response.value.ok });
+};
+```
+
+The same pattern applies to raw database promises. Nile’s model helpers already return Results; inspect those directly. `safeTry` can flatten a Result-returning callback, but a second wrapper is unnecessary when the operation already has the intended failure contract. Never look for another `isErr` inside `result.value`.
+
+### Choose one owner for async policy
+
+Use `superPromise` for a dependency operation that needs Slang’s timeout, cancellation or task-group controls. Use Nile’s execution settings and `utils.createQueue`, `utils.createRateLimiter` or `utils.retryFnWithJitter` when the policy belongs to an action or shared application resource. Avoid independently stacked retries and deadlines: they multiply attempts and obscure which operation failed.
+
+```ts
+import { superPromise, taskGroup } from "@nilejs/nile/fp";
+
+const providerCalls = taskGroup("provider-status", { concurrency: 4 });
+
+export const checkProvider = async (url: string, signal: AbortSignal) => {
+  const task = superPromise(
+    async (attemptSignal) => {
+      const response = await fetch(url, { signal: attemptSignal });
+      return { available: response.ok };
+    },
+    { group: providerCalls, timeout: 3000 }
+  );
+  const cancel = () => {
+    task.abort();
+  };
+  if (signal.aborted) {
+    cancel();
+  } else {
+    signal.addEventListener("abort", cancel, { once: true });
+  }
+  try {
+    return await task;
+  } finally {
+    signal.removeEventListener("abort", cancel);
+  }
+};
+```
+
+This helper is internal: its failure still needs translation before being returned publicly. A timeout or aborted Result does not roll back completed effects. Retry only operations safe to repeat, use idempotency for writes, and keep retry count, pending work and concurrency bounded. A task group limits running attempts; it does not cap all pending work or persist jobs. Use a Nile queue with explicit capacity when you also need admission control. Long-lived resources belong in the application lifecycle so shutdown can drain or close them.
+
+## Calling actions
+
+- HTTP: `POST /api/services` with `{ "intent": "execute", "service": "projects", "action": "create", "payload": { ... } }`.
+- Client (`@nilejs/client`): `createNileClient<Payloads>({ baseUrl })`, then `await nile.invoke({ service, action, payload })`. Every method returns a Result: `if (result.isErr) { ... return; }`, then read `result.value`. On failure `result.error` is the message and `result.details` holds the server's `data`. `data` is a deprecated alias; do not use it.
+- Sockets: `createNileSocketClient<Actions, Topics>` owns its connection. Use `socket.invoke`, `socket.send` and `socket.receive`; check each Result and unsubscribe/close when finished. Declare backend topics and validate their data and scope; frontend types come from shared or generated definitions. Authorization is still a backend policy.
+- Server code: `await server.invoke({ service, action, payload, credentials? })`. Protected actions need `credentials` with headers.
+- Uploads: `nile.upload({ service, action, files, fields })` for `isSpecial: { contentType: "multipart/form-data" }` actions. A JSON request to such an action returns HTTP 400.
+
+## Organize a feature as it grows
+
+1. Find the domain in `services.config.ts` and read its `index.ts`. Name the action for the business operation, then define its input schema and named handler.
+2. Keep a short, single-use rule in that handler. Extract ordinary domain functions when a rule is reused, complicated enough to test independently, or coordinates a transaction. Do not create a repository, class or service layer solely because a folder exists.
+3. Put data access in the project’s model convention. `utils.createModel` and `utils.getZodSchema` are optional Drizzle helpers; a handwritten model is also valid. Pass the database or transaction explicitly where transaction ownership matters.
+4. For a growing action, move its private helpers under its action folder’s `modules/`. Put helpers shared by the domain in the service’s `modules/`. Cross-domain rules can use `business/` when useful. Do not expose a private helper as an action just to call it.
+5. Register the action in the domain’s `actions` list. An export alone does not make it reachable. Register a new service in the root registry.
+6. Carry validated input into business functions and trusted identity into policy checks. Keep request identity in scoped sessions and execution state, not process-wide context values.
+7. Verify the registered operation through `server.invoke` or a transport when changing validation, permissions or registration. Test a transaction’s rollback and idempotency when those are part of the business guarantee.
+
+A transaction belongs to the layer that knows which writes must be atomic. Calling several actions or adding an after hook does not make the work transactional. An after hook is not a `finally` block: cleanup belongs in `finally` or the lifecycle, since after hooks do not run after every failure.
+
+## Anti-patterns to avoid
+
+| Anti-pattern | Prefer |
+|---|---|
+| `Ok(existingResult)` or checking `result.value.isErr` | One Result boundary, then an early failure branch or a short transformation. |
+| Returning a caught driver’s `result.error` directly | Log bounded diagnostics and choose a safe business-facing message. |
+| `.expect()`, `.panic()` or a non-null assertion to bypass an ordinary refusal | An explicit Err, Option branch or validation schema. |
+| `unwrap().else([])` on a failed write or required lookup | Preserve the failure; default only when absence is a valid answer. |
+| Long chains with hidden writes and logging | Named functions and explicit Result checks around side effects. |
+| Parsing or guessing business values in a before hook | Treat payloads as untrusted; rely on the action’s parsed input for business logic. |
+| `context.set("user", identity)` | Scoped sessions or an application-owned request scope. |
+| Creating a queue, rate limiter or task group inside every invocation | A shared resource with an explicit owner and shutdown policy. |
+| Unbounded `Promise.all` over user-sized inputs | A concurrency limit and bounded pending work. |
+| Memoizing authorization or mutable account state | Fresh checks or an explicit cache with appropriate invalidation. |
+| Treating a generated diagnostic code as `NOT_FOUND` or another stable category | Keep domain decisions in explicit data/schema contracts; use the generated code only to find a log. |
+| Assuming optional schemas, topics or hooks authorize an operation | Enforce authorization at the backend policy boundary. |
+
+## Protection and policy
+
+- JWT: set `auth: { secret, method: "header" }` on the server and `isProtected: true` on the action. Both are required.
+- `accessControl` lists role labels. Nile Js stores them but does not enforce them. Enforce them in a global `onBeforeActionHandler` that checks `action.accessControl` against the session's `roles`.
+- Hooks: `hooks.before` and `hooks.after` run another action's handler directly. They do not run that action's JWT check, validation or hooks.
+- Discovery is off by default. When `rest.discovery.secret` is configured, `explore` and `schema` need the matching `payload.discoverySecret`. Enabling discovery without a secret exposes metadata to callers.
+
+## Feature guides
+
+Read the page for the feature you change before you write code:
+
+- [Validation and errors](https://nile-js.github.io/nile/guide/features/validation-and-errors)
+- [Authentication and hooks](https://nile-js.github.io/nile/guide/features/authentication-and-hooks)
+- [Context and logging](https://nile-js.github.io/nile/guide/features/context-and-logging)
+- [Queues, debounce and throttle](https://nile-js.github.io/nile/guide/features/queues-debounce-throttle)
+- [Telemetry](https://nile-js.github.io/nile/guide/features/telemetry)
+- [WebSockets](https://nile-js.github.io/nile/guide/features/websockets)
+- [Cron jobs](https://nile-js.github.io/nile/guide/features/cron-jobs)
+- [Database models](https://nile-js.github.io/nile/guide/features/database-models)
+- [API discovery and schemas](https://nile-js.github.io/nile/guide/features/api-discovery)
+- [HTTP, WebSocket and direct calls](https://nile-js.github.io/nile/guide/features/calling-actions)
+- [Retries and utilities](https://nile-js.github.io/nile/guide/features/retries-and-utilities)
+- [Rate limiting](https://nile-js.github.io/nile/guide/features/rate-limiting)
+- [File uploads](https://nile-js.github.io/nile/guide/features/file-uploads)
+- [Readiness and shutdown](https://nile-js.github.io/nile/guide/features/readiness-and-shutdown)
+
+Advanced pages cover handler context, composed hooks, execution options and testing with `server.invoke`: https://nile-js.github.io/nile/guide/advanced/
+
+## Rules for agents
+
+1. Read `services.config.ts`, the target service’s `index.ts` and its actions before you change anything.
+2. Follow the existing pattern in that service. Do not add a second architecture.
+3. Never invent an API. Check the guide, the installed `@nilejs/nile` types in `node_modules`, or the existing code. If it is not there, say so.
+4. Use named schemas, inferred input types, named handlers, `createAction<T>` and braces on every `if`.
+5. Start with business rules in the action’s named handler. Move reusable rules or transaction coordination into ordinary domain functions when that makes them easier to share or test. Keep persistence in models or repositories; keep transaction boundaries explicit.
+6. Typecheck and run the relevant tests after a coherent change. Exercise the registered action through `server.invoke` or a transport when registration, policy or validation changes.
+7. Do not commit, publish or change secrets, `.env` values or deployment settings unless the user asks.
+
+## Common pitfalls
+
+- `isProtected` without `auth` does nothing useful. Configure both.
+- `accessControl` does not block anything by itself. Add a hook that checks it.
+- A before hook sees the raw payload, before validation.
+- A global before hook's returned value does not replace the payload. Use a local hook to transform input.
+- A local hook does not protect the parent action.
+- `context.set` values are shared by all requests. Never store the current user there.
+- A rate limit or topic policy that is missing denies or does not apply. Read the feature page for the default.
+- Multiple replicas each keep their own queues, schedules, rate-limit counters and WebSocket subscriptions.
+- JWT failures return fixed messages such as `JWT authentication failed: token expired` or `JWT authentication failed: invalid token`. They never include the token or its claims, so do not add them back in your own logs.
+- Import Results from `@nilejs/nile/fp`, not a separately installed `slang-ts`. Two copies of `slang-ts` produce type errors.

package/template/package.json

@@ -8,18 +8,20 @@
     "gen": "bunx @nilejs/cli generate",
     "db:generate": "bunx drizzle-kit generate",
     "db:push": "bunx drizzle-kit push",
-    "db:studio": "bunx drizzle-kit studio"
+    "db:studio": "bunx drizzle-kit studio",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@nilejs/nile": "latest",
+    "@nilejs/nile": "^1.0.4",
     "@electric-sql/pglite": "^0.2.5",
-    "drizzle-orm": "^0.45.2",
-    "pino": "^10.3.1",
-    "zod": "^4.3.6"
+    "drizzle-orm": "^0.45.4",
+    "pino": "^10.4.0",
+    "zod": "^4.6.7",
+    "drizzle-zod": "^0.8.3"
   },
   "devDependencies": {
     "@types/bun": "latest",
     "drizzle-kit": "^0.31.10",
-    "typescript": "^5"
+    "typescript": "^7.0.2"
   }
 }

package/template/src/db/models/tasks.ts

@@ -1,6 +1,6 @@
-import { createModel } from "@nilejs/nile";
+import { utils } from "@nilejs/nile";
 import { db } from "@/db/client";
 import { tasks } from "@/db/schema";
 
 /** CRUD model for tasks — auto-validates, handles errors, and supports transactions */
-export const taskModel = createModel(tasks, { db, name: "task" });
+export const taskModel = utils.createModel(tasks, { db, name: "task" });

package/template/src/index.ts

@@ -1,7 +1,7 @@
-import { createLogger, createNileServer } from "@nilejs/nile";
+import { createLogger, createNileServer, utils } from "@nilejs/nile";
 import { sql } from "drizzle-orm";
 import { Ok, safeTry } from "@nilejs/nile/fp";
-import { db } from "@/db/client";
+import { db, pglite } from "@/db/client";
 import { services } from "@/services/services.config";
 
 const logger = createLogger("{{projectName}}", {
@@ -25,15 +25,22 @@ const pushSchema = async () => {
   );
 
   if (result.isErr) {
-    console.error("[pushSchema] Failed:", result.error);
+    return utils.handleError({
+      message: "Could not prepare the task database.",
+      data: utils.describeError(result.raw),
+      atFunction: "pushSchema",
+      logger: logger,
+    });
   }
+
+  return Ok(null);
 };
 
 const server = await createNileServer({
   serverName: "{{projectName}}",
   runtime: "bun",
   native: true,
-  project: { structure: "error" },
+  project: { root: process.cwd(), structure: "error" },
   services,
   resources: { logger, database: db },
   rest: {
@@ -48,7 +55,10 @@ const server = await createNileServer({
     // The first PGlite start on a slow machine can take longer than the 10 second default.
     maxWaitTime: 30_000,
     fn: async (ctx) => {
-      await pushSchema();
+      const prepared = await pushSchema();
+      if (prepared.isErr) {
+        return prepared;
+      }
       ctx.resources?.logger?.info({
         atFunction: "onBoot",
         message: "{{projectName}} booted - PGLite schema ready",
@@ -72,6 +82,21 @@ server.nativeRest?.addMiddleware("/api", async (c, next) => {
 
 if (server.nativeRest) {
   const port = server.config.rest?.port ?? 8000;
-  Bun.serve({ port, fetch: server.nativeRest.fetch });
+  const listener = Bun.serve({
+    port: port,
+    fetch: server.nativeRest.fetch,
+  });
+  let closing = false;
+  const shutdown = async () => {
+    if (closing) {
+      return;
+    }
+    closing = true;
+    listener.stop();
+    await server.lifecycle.shutdown();
+    await pglite.close();
+  };
+  process.once("SIGINT", shutdown);
+  process.once("SIGTERM", shutdown);
   console.log(`\n{{projectName}} listening on http://localhost:${port}\n`);
 }

package/template/src/services/services.config.ts

@@ -1,21 +1,4 @@
-import { createServices, type Services } from "@nilejs/nile";
-import { createTaskAction } from "./tasks/actions/create";
-import { deleteTaskAction } from "./tasks/actions/delete";
-import { getTaskAction } from "./tasks/actions/get";
-import { listTaskAction } from "./tasks/actions/list";
-import { updateTaskAction } from "./tasks/actions/update";
+import { createServices } from "@nilejs/nile";
+import { tasksService } from "./tasks";
 
-export const services: Services = createServices([
-  {
-    name: "tasks",
-    description: "Task management with CRUD operations",
-    meta: { version: "1.0.0" },
-    actions: [
-      createTaskAction,
-      listTaskAction,
-      getTaskAction,
-      updateTaskAction,
-      deleteTaskAction,
-    ],
-  },
-]);
+export const services = createServices([tasksService]);

package/template/src/services/tasks/index.ts

@@ -0,0 +1,18 @@
+import { createService } from "@nilejs/nile";
+import { createTaskAction } from "./actions/create";
+import { deleteTaskAction } from "./actions/delete";
+import { getTaskAction } from "./actions/get";
+import { listTaskAction } from "./actions/list";
+import { updateTaskAction } from "./actions/update";
+
+export const tasksService = createService({
+  name: "tasks",
+  description: "Task management with CRUD operations",
+  actions: [
+    createTaskAction,
+    listTaskAction,
+    getTaskAction,
+    updateTaskAction,
+    deleteTaskAction,
+  ],
+});

package/template/tsconfig.json

@@ -8,11 +8,23 @@
     "skipLibCheck": true,
     "outDir": "./dist",
     "rootDir": ".",
-    "baseUrl": ".",
     "paths": {
-      "@/*": ["./src/*"]
-    }
+      "@/*": [
+        "./src/*"
+      ]
+    },
+    "noEmit": true,
+    "types": [
+      "bun"
+    ]
   },
-  "include": ["./src/**/*.ts", "./drizzle.config.ts"],
-  "exclude": ["node_modules", "dist", "data"]
+  "include": [
+    "./src/**/*.ts",
+    "./drizzle.config.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "data"
+  ]
 }