@nilejs/cli 1.0.2 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nile-js
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -72,12 +72,12 @@ const getUserSchema = z.object({
 
 type GetUserInput = z.infer<typeof getUserSchema>;
 
-const getUserHandler = async (input: GetUserInput) => {
+const getUserHandler = async (data: GetUserInput) => {
   // Implement users.get-user here
-  return Ok({ result: input });
+  return Ok({ result: data });
 };
 
-export const getUserAction = createAction<GetUserInput>({
+export const getUserAction = createAction({
   name: "get-user",
   description: "GetUser action for users",
   validation: getUserSchema,
@@ -107,7 +107,7 @@ Every registered action is included in `ServicePayloads`. Actions without a vali
 
 ## 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`.
+The starter uses Nile `^1.1.0`, 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.
 

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.2";
+var version = "1.0.3";
 
 // src/commands/generate-action.ts
 import { resolve } from "node:path";
@@ -99,12 +99,12 @@ const ${camel}Schema = z.object({
 
 type ${pascal}Input = z.infer<typeof ${camel}Schema>;
 
-const ${camel}Handler = async (input: ${pascal}Input) => {
+const ${camel}Handler = async (data: ${pascal}Input) => {
   // Implement ${serviceName}.${actionName} here
-  return Ok({ result: input });
+  return Ok({ result: data });
 };
 
-export const ${camel}Action = createAction<${pascal}Input>({
+export const ${camel}Action = createAction({
   name: "${actionName}",
   description: "${pascal} action for ${serviceName}",
   validation: ${camel}Schema,
@@ -459,11 +459,11 @@ const sample${pascal}Schema = z.object({
 
 type Sample${pascal}Input = z.infer<typeof sample${pascal}Schema>;
 
-const sample${pascal}Handler = async (input: Sample${pascal}Input) => {
-  return Ok({ ${camel}: { name: input.name } });
+const sample${pascal}Handler = async (data: Sample${pascal}Input) => {
+  return Ok({ ${camel}: { name: data.name } });
 };
 
-export const sample${pascal}Action = createAction<Sample${pascal}Input>({
+export const sample${pascal}Action = createAction({
   name: "sample",
   description: "Sample ${serviceName} action",
   validation: sample${pascal}Schema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nilejs/cli",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "CLI for scaffolding and generating Nile backend projects",
   "type": "module",
   "bin": {
@@ -10,6 +10,31 @@
     "dist",
     "template"
   ],
+  "homepage": "https://nile-js.github.io/nile/",
+  "bugs": {
+    "url": "https://github.com/nile-js/nile/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nile-js/nile.git",
+    "directory": "packages/cli"
+  },
+  "author": "Hussein Kizz",
+  "license": "MIT",
+  "keywords": [
+    "nile",
+    "cli",
+    "scaffolding",
+    "generator",
+    "codegen",
+    "backend",
+    "typescript",
+    "bun",
+    "zod"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "dependencies": {
     "commander": "^13.1.0",
     "json-schema-to-zod": "^2.7.0",

package/template/README.md

@@ -85,7 +85,7 @@ Responses have exactly `status`, `message` and `data`. The default success messa
 
 ## 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`.
+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/). On the frontend, `createNileClient` calls actions and sends and receives topics through `nile.socket`.
 
 ## Adding services
 

package/template/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Work in a Nile Js backend (@nilejs/nile 2.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
 ---
 
@@ -39,7 +39,6 @@ src/
     client.ts                      connection and driver
     models/                        persistence operations
   hooks/                           shared action policies
-  business/                        optional reusable domain functions
   generated/                       client payload/schema contracts
 ```
 
@@ -49,7 +48,7 @@ Structure violations fail startup by default. An application needs `src/index.ts
 
 ## The action pattern
 
-Every action uses a named schema, an inferred input type, a separately written named handler and `createAction<T>`:
+Define a named schema, derive the handler’s data type and pass the named handler to `createAction`. The action type and handler return type are inferred. Use `data` and `context` for the parameters you need; omit unused parameters:
 
 ```ts
 import { createAction } from "@nilejs/nile";
@@ -62,15 +61,15 @@ const createProjectSchema = z.object({
 
 type CreateProjectInput = z.infer<typeof createProjectSchema>;
 
-const createProjectHandler = (input: CreateProjectInput) => {
-  if (input.name === "system") {
+const createProjectHandler = (data: CreateProjectInput) => {
+  if (data.name === "system") {
     return Err("Choose a different project name");
   }
 
-  return Ok({ project: { name: input.name } });
+  return Ok({ project: { name: data.name } });
 };
 
-export const createProjectAction = createAction<CreateProjectInput>({
+export const createProjectAction = createAction({
   name: "create",
   description: "Create a project",
   validation: createProjectSchema,
@@ -104,7 +103,7 @@ Action names are unique within a service. Folder names do not create routes; onl
 
 ## 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.
+Nile Js calls every handler with two arguments: the validated input and the execution's `NileContext`. For a named handler, annotate `data` with the schema’s parsed output type and use `context` for its second parameter. Import `NileContext` when you need to annotate it. `createAction` infers its type from the handler; leave off the repeated generic argument and inferred return annotation. 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`).
@@ -258,7 +257,7 @@ This helper is internal: its failure still needs translation before being return
 
 - 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.
+- Topics: define each with `createTopic({ name, data, scope?, canReceive?, canSend? })` and pass `createTopics([...])` to the server `socket` config. A missing `canReceive` or `canSend` denies clients. Connections verify the server `auth` JWT; `user` in the checks is `{ userId, organizationId, claims }` or `undefined`. In actions, `const { socket } = getContext({ topics })`, then `socket.send({ topic, scope?, to?: { userId } | { connectionId }, data })` after the write commits. On the frontend, `nile.socket.receive({ topic, scope, onMessage })` subscribes and returns a Result holding `unsubscribe()`; `nile.socket.send` sends. Sockets do not call actions; use `nile.invoke`.
 - 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.
 
@@ -267,7 +266,7 @@ This helper is internal: its failure still needs translation before being return
 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.
+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/`. A rule another domain also needs stays in the domain that owns it; the other service imports it from there. 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.
@@ -311,7 +310,7 @@ Read the page for the feature you change before you write code:
 - [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)
+- [HTTP 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)
@@ -324,7 +323,7 @@ Advanced pages cover handler context, composed hooks, execution options and test
 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`.
+4. Use named schemas and handlers. Name action parameters `data` and `context`, and hook parameters `hookContext`. Annotate a named handler’s data from the schema; let `createAction` and return types infer the rest. Use 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.
@@ -337,7 +336,7 @@ Advanced pages cover handler context, composed hooks, execution options and test
 - 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.
+- A rate limit or topic permission (`canReceive`, `canSend`) 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

@@ -12,7 +12,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@nilejs/nile": "^1.0.4",
+    "@nilejs/nile": "^1.1.0",
     "@electric-sql/pglite": "^0.2.5",
     "drizzle-orm": "^0.45.4",
     "pino": "^10.4.0",

package/template/src/index.ts

@@ -54,12 +54,12 @@ const server = await createNileServer({
   onBoot: {
     // The first PGlite start on a slow machine can take longer than the 10 second default.
     maxWaitTime: 30_000,
-    fn: async (ctx) => {
+    fn: async (context) => {
       const prepared = await pushSchema();
       if (prepared.isErr) {
         return prepared;
       }
-      ctx.resources?.logger?.info({
+      context.resources?.logger?.info({
         atFunction: "onBoot",
         message: "{{projectName}} booted - PGLite schema ready",
       });

package/template/src/services/tasks/actions/create.ts

@@ -1,5 +1,5 @@
 import { createAction } from "@nilejs/nile";
-import { Err, Ok } from "@nilejs/nile/fp";
+import { Ok } from "@nilejs/nile/fp";
 import z from "zod";
 import { taskModel } from "@/db/models";
 
@@ -14,23 +14,23 @@ const createTaskSchema = z.object({
 
 type CreateTaskInput = z.infer<typeof createTaskSchema>;
 
-const createTaskHandler = async (input: CreateTaskInput) => {
+const createTaskHandler = async (data: CreateTaskInput) => {
   const result = await taskModel.create({
     data: {
-      title: input.title,
-      description: input.description,
-      status: input.status,
+      title: data.title,
+      description: data.description,
+      status: data.status,
     },
   });
 
   if (result.isErr) {
-    return Err(result.error);
+    return result;
   }
 
   return Ok({ task: result.value });
 };
 
-export const createTaskAction = createAction<CreateTaskInput>({
+export const createTaskAction = createAction({
   name: "create",
   description: "Create a new task",
   validation: createTaskSchema,

package/template/src/services/tasks/actions/delete.ts

@@ -1,5 +1,5 @@
 import { createAction } from "@nilejs/nile";
-import { Err, Ok } from "@nilejs/nile/fp";
+import { Ok } from "@nilejs/nile/fp";
 import z from "zod";
 import { taskModel } from "@/db/models";
 
@@ -9,17 +9,17 @@ const deleteTaskSchema = z.object({
 
 type DeleteTaskInput = z.infer<typeof deleteTaskSchema>;
 
-const deleteTaskHandler = async (input: DeleteTaskInput) => {
-  const result = await taskModel.delete(input.id);
+const deleteTaskHandler = async (data: DeleteTaskInput) => {
+  const result = await taskModel.delete(data.id);
 
   if (result.isErr) {
-    return Err(result.error);
+    return result;
   }
 
-  return Ok({ deleted: true, id: input.id });
+  return Ok({ deleted: true, id: data.id });
 };
 
-export const deleteTaskAction = createAction<DeleteTaskInput>({
+export const deleteTaskAction = createAction({
   name: "delete",
   description: "Delete a task by ID",
   validation: deleteTaskSchema,

package/template/src/services/tasks/actions/get.ts

@@ -1,5 +1,5 @@
 import { createAction } from "@nilejs/nile";
-import { Err, Ok } from "@nilejs/nile/fp";
+import { Ok } from "@nilejs/nile/fp";
 import z from "zod";
 import { taskModel } from "@/db/models";
 
@@ -9,17 +9,17 @@ const getTaskSchema = z.object({
 
 type GetTaskInput = z.infer<typeof getTaskSchema>;
 
-const getTaskHandler = async (input: GetTaskInput) => {
-  const result = await taskModel.findById(input.id);
+const getTaskHandler = async (data: GetTaskInput) => {
+  const result = await taskModel.findById(data.id);
 
   if (result.isErr) {
-    return Err(result.error);
+    return result;
   }
 
   return Ok({ task: result.value });
 };
 
-export const getTaskAction = createAction<GetTaskInput>({
+export const getTaskAction = createAction({
   name: "get",
   description: "Get a task by ID",
   validation: getTaskSchema,

package/template/src/services/tasks/actions/list.ts

@@ -1,12 +1,12 @@
 import { createAction } from "@nilejs/nile";
-import { Err, Ok } from "@nilejs/nile/fp";
+import { Ok } from "@nilejs/nile/fp";
 import { taskModel } from "@/db/models";
 
 const listTasksHandler = async () => {
   const result = await taskModel.findAll();
 
   if (result.isErr) {
-    return Err(result.error);
+    return result;
   }
 
   return Ok({ tasks: result.value });

package/template/src/services/tasks/actions/update.ts

@@ -1,5 +1,5 @@
 import { createAction } from "@nilejs/nile";
-import { Err, Ok } from "@nilejs/nile/fp";
+import { Ok } from "@nilejs/nile/fp";
 import z from "zod";
 import { taskModel } from "@/db/models";
 
@@ -12,25 +12,25 @@ const updateTaskSchema = z.object({
 
 type UpdateTaskInput = z.infer<typeof updateTaskSchema>;
 
-const updateTaskHandler = async (input: UpdateTaskInput) => {
+const updateTaskHandler = async (data: UpdateTaskInput) => {
   // Fields left out of the request stay undefined and are not changed.
   const result = await taskModel.update({
-    id: input.id,
+    id: data.id,
     data: {
-      title: input.title,
-      description: input.description,
-      status: input.status,
+      title: data.title,
+      description: data.description,
+      status: data.status,
     },
   });
 
   if (result.isErr) {
-    return Err(result.error);
+    return result;
   }
 
   return Ok({ task: result.value });
 };
 
-export const updateTaskAction = createAction<UpdateTaskInput>({
+export const updateTaskAction = createAction({
   name: "update",
   description: "Update an existing task",
   validation: updateTaskSchema,