shutro-erp 0.2.1 → 0.3.1

package/README.md

@@ -1,6 +1,6 @@
 # shutro-erp
 
-**Kosh** is an ERP framework for Node.js, TypeScript and PostgreSQL, built on the
+**Shutro ERP** is an ERP framework for Node.js, TypeScript and PostgreSQL, built on the
 [Shutro](https://www.npmjs.com/package/shutro) ORM. Define a model once and get a REST API with OpenAPI, a typed
 client, list / form / kanban / pivot / graph / calendar / gantt / map / dashboard views, exports, PDF documents and a
 chatter on every record. Permissions are checked on the server on every route.
@@ -20,13 +20,13 @@ chatter on every record. Permissions are checked on the server on every route.
 ## Requirements
 
 - **Node.js 24** or later (`node --version`)
-- **PostgreSQL 16** or later, or **Docker** (Kosh can start PostgreSQL for you)
+- **PostgreSQL 16** or later, or **Docker** (Shutro ERP can start PostgreSQL for you)
 - An authenticator app for the administrator's second factor (Google Authenticator, Microsoft Authenticator,
   1Password, …)
 
 ## Install with the terminal
 
-One command creates the project, installs Kosh and asks for everything it needs:
+One command creates the project, installs Shutro ERP and asks for everything it needs:
 
 ```sh
 npx shutro-erp@latest init my-erp   # the project my-erp
@@ -37,54 +37,61 @@ npx shutro-erp@latest init          # asks for the project name first
 
 ```sh
 npm install shutro-erp      # Shutro, the ORM, comes with it
-npx kosh init
+npx shutro-erp init
 ```
 
-The setup asks for what the installation needs. Press **Enter** to keep the value in `[brackets]`:
+The setup asks for what the installation needs, one question at a time: type an answer or press **Enter** for
+the default shown, pick from lists with **↑ ↓** and **Enter**, tick apps with **Space**, stop with **Ctrl+C**
+(piped or scripted, the same questions are asked line by line):
 
 | Question | Example | Notes |
 |---|---|---|
-| PostgreSQL | `1` your server, `2` start one in Docker | `2` needs Docker Desktop running; it writes `compose.yaml` and starts the `db` service |
+| PostgreSQL | your server, or start one in Docker | Docker needs Docker Desktop running; it writes `compose.yaml` and starts the `db` service |
 | Username, password, port, host, database name | `postgres`, (hidden), `5432`, `localhost`, `my_erp` | for `1`; a missing database is created after you confirm; if nothing answers, it offers Docker instead |
-| Company name, currency | `Padma Traders`, `BDT` | the first company; more companies later |
+| Company name, currency, country | `Padma Traders`, `BDT`, Bangladesh | the first company; a country with a localization gets its taxes, chart and returns |
 | Language, time zone | `bn`, `Asia/Dhaka` | the administrator's |
 | Administrator login, name, email, password | `admin`, …, 12+ characters | the password is typed hidden and stored only as a hash |
-| Apps | `permissions,reporting,messaging` | roles and approvals, reports and documents, chatter and attachments |
-| File storage | `1` a folder, `2` S3-compatible | S3, SeaweedFS, MinIO; the bucket is created |
+| Apps | all ticked; untick what you do not need | roles and approvals, reports, chatter, the business apps |
+| File storage | a folder, or S3-compatible | S3, SeaweedFS, MinIO; the bucket is created |
 | Valkey/Redis URL | empty | optional: rate limits and caches shared by several servers |
-| API port | `3000` | |
+| API port, back-office (web) port | `3000`, `5173` | the next free ones are proposed |
 | Authenticator code | `123456` | scan the printed secret, type a code; **keep the recovery codes** it prints |
 
 Then it writes the project, creates the database tables (`migrations/0001_init.sql`), the company and the
-administrator, and loads the apps' default data. Run `npm install` once in the project, then start it:
+administrator, and loads the apps' default data. **Then it starts Shutro ERP for you**: it installs the project's
+dependencies (with the package manager you ran it with: npm, pnpm, yarn or bun), starts the API and the
+back-office, waits until both answer, and opens the back-office in your browser on the web port. Both keep
+running in that terminal; **Ctrl+C** stops them. Sign in with the administrator's login, password and a code from
+the authenticator app.
+
+To start it again later (or after `--no-start`, which only sets up):
 
 ```sh
+cd my-erp
 npm start            # the API on http://localhost:3000
 npm run web          # the back-office on http://localhost:5173, in a second terminal
 ```
 
-Sign in with the administrator's login, password and a code from the authenticator app.
-
 **Without questions** (scripts, CI): pass the answers as flags.
 
 ```sh
 npx shutro-erp@latest init my-erp --yes --docker-db --admin-password "a long passphrase here"
 
-npx kosh init --yes \
+npx shutro-erp init --yes \
   --database-url postgres://postgres:postgres@localhost:5432/my_erp --create-database \
   --company "Padma Traders" --currency BDT --lang bn --tz Asia/Dhaka \
   --admin-login admin --admin-password "a long passphrase here" \
-  --apps permissions,reporting,messaging --storage-dir ./var/attachments --port 3000
+  --apps permissions,reporting,messaging --storage-dir ./var/attachments --port 3000 --web-port 5173
 ```
 
-With `--yes` nothing is asked, so the authenticator is not enrolled: run `npx kosh init` again in a terminal to
-enrol it (administrator rights wait for it). `npx kosh init --help` lists every flag. Replies by email: set `MAIL_INBOUND_DOMAIN` in `.env` (the secrets are generated) and point your email provider's inbound webhook at `/api/v1/mail/inbound` with the `MAIL_INBOUND_WEBHOOK_SECRET`. `--demo` (or a yes to the
+With `--yes` nothing is asked, so the authenticator is not enrolled: run `npx shutro-erp init` again in a terminal to
+enrol it (administrator rights wait for it). `npx shutro-erp init --help` lists every flag. Replies by email: set `MAIL_INBOUND_DOMAIN` in `.env` (the secrets are generated) and point your email provider's inbound webhook at `/api/v1/mail/inbound` with the `MAIL_INBOUND_WEBHOOK_SECRET`. `--demo` (or a yes to the
 question after the apps) loads a sample company with contacts, products, orders, invoices and projects, made by
 the demo users `dina`, `rahim`, `karim` and `sumi` (one shared password, printed at the end); not for production.
 
 ## Install with Docker
 
-`kosh init` writes `Dockerfile`, `compose.yaml`, `nginx.conf` and `.dockerignore` into every project.
+`shutro-erp init` writes `Dockerfile`, `compose.yaml`, `nginx.conf` and `.dockerignore` into every project.
 
 **PostgreSQL in Docker, the app on your machine** (development):
 
@@ -110,21 +117,21 @@ docker compose up -d --build        # db + api + web; the back-office on http://
 | Service | What | Port |
 |---|---|---|
 | `db` | PostgreSQL 18, data in the `db` volume | `127.0.0.1:5432` (`POSTGRES_PORT`) |
-| `api` | the Kosh API; runs `kosh migrate` on every start, then serves | inside the network (`api:3000`) |
+| `api` | the Shutro ERP API; runs `shutro-erp migrate` on every start, then serves | inside the network (`api:3000`) |
 | `web` | nginx with the built back-office, `/api` proxied to `api` | `8080` (`WEB_PORT`) |
 
 Useful commands:
 
 ```sh
 docker compose logs -f api                       # the API's log
-docker compose exec api npx kosh migrate status  # any kosh command inside the container
-docker compose exec api npx kosh seed
+docker compose exec api npx shutro-erp migrate status  # any shutro-erp command inside the container
+docker compose exec api npx shutro-erp seed
 docker compose up -d --build api                 # after changing modules: rebuild and migrate
 docker compose down                              # stop (volumes keep the data)
-docker compose exec db pg_dump -U kosh my_erp > backup.sql   # a backup
+docker compose exec db pg_dump -U shutro my_erp > backup.sql   # a backup
 ```
 
-Behind HTTPS, set `KOSH_SECURE_COOKIES: "true"` in `compose.yaml`. To use a PostgreSQL server outside Docker, set
+Behind HTTPS, set `SHUTRO_ERP_SECURE_COOKIES: "true"` in `compose.yaml`. To use a PostgreSQL server outside Docker, set
 `DOCKER_DATABASE_URL` in `.env` (an address the container can reach, not `localhost`).
 
 ## Project structure
@@ -137,7 +144,7 @@ my-erp/
 ├── src/
 │   ├── modules.ts          the installed modules: base, the apps, your modules
 │   ├── server.ts           the API server (npm start)
-│   ├── modules/            your modules (kosh module create <name>)
+│   ├── modules/            your modules (shutro-erp module create <name>)
 │   │   └── library/
 │   │       ├── index.ts        the module: groups, access levels, app, menus, actions, views
 │   │       ├── models.ts       its models (fields, access per group, record rules)
@@ -145,7 +152,7 @@ my-erp/
 │   │       └── migrations.ts   its data migrations
 │   └── web/
 │       ├── main.tsx        the back-office (React): renderers of each installed app
-│       └── index.css       Tailwind + Kosh's design tokens
+│       └── index.css       Tailwind + Shutro ERP's design tokens
 ├── index.html, vite.config.ts   the back-office build (npm run web / build:web)
 ├── Dockerfile, compose.yaml, nginx.conf, .dockerignore
 └── var/attachments/        uploaded files (with folder storage)
@@ -156,8 +163,8 @@ my-erp/
 A module is a folder with its models and a manifest. Create one:
 
 ```sh
-npx kosh module create library
-npx kosh migrate             # creates its tables, records it, loads its seed data
+npx shutro-erp module create library
+npx shutro-erp migrate             # creates its tables, records it, loads its seed data
 ```
 
 It writes `src/modules/library/` and adds `library` to `src/modules.ts`. After `npm start` and a reload of the
@@ -191,7 +198,7 @@ export const Book = defineModel('library.book', {
 ```
 
 **`index.ts`**: the module: its Shutro part (name, version, groups, models, seed data, data migrations) and its
-Kosh part (access levels, app, menus, actions, views):
+Shutro ERP part (access levels, app, menus, actions, views):
 
 ```ts
 import { base, baseShutro } from 'shutro-erp';
@@ -252,29 +259,29 @@ export const modules = [base, messaging, library];
 ```
 
 ```sh
-npx kosh migrate    # tables, the module's version (shutro_module), its seed data
+npx shutro-erp migrate    # tables, the module's version (shutro_module), its seed data
 ```
 
 A module published on npm installs the same way: `npm install <package>`, import it in `src/modules.ts`, then
-`npx kosh migrate`. Installing does not give anyone access: grant its roles to users ([Users and roles](#users-and-roles)).
+`npx shutro-erp migrate`. Installing does not give anyone access: grant its roles to users ([Users and roles](#users-and-roles)).
 
-**Remove a module**: take it out of `src/modules.ts`; `npx kosh migrate` then plans dropping its tables, which is
-destructive: it stops for review, and `npx kosh migrate --allow-destructive` applies it. Back up first.
+**Remove a module**: take it out of `src/modules.ts`; `npx shutro-erp migrate` then plans dropping its tables, which is
+destructive: it stops for review, and `npx shutro-erp migrate --allow-destructive` applies it. Back up first.
 
 ## Migrations
 
 ```sh
-npx kosh migrate                   # plan + apply + seed
-npx kosh migrate --plan            # only write the plan, to review it
-npx kosh migrate --name add_isbn   # name the new file (migrations/0002_add_isbn.sql)
-npx kosh migrate status            # applied and pending files
-npx kosh migrate --allow-destructive
+npx shutro-erp migrate                   # plan + apply + seed
+npx shutro-erp migrate --plan            # only write the plan, to review it
+npx shutro-erp migrate --name add_isbn   # name the new file (migrations/0002_add_isbn.sql)
+npx shutro-erp migrate status            # applied and pending files
+npx shutro-erp migrate --allow-destructive
 ```
 
-- **Schema migrations** are SQL files in `migrations/`. `kosh migrate` compares your modules with the live database
+- **Schema migrations** are SQL files in `migrations/`. `shutro-erp migrate` compares your modules with the live database
   and writes the differences as the next file (`0002_update.sql`), applies every pending file in order (each in its
   own transaction, recorded in `shutro_migration`), then loads the seed data. Commit the files: a deployment runs the
-  same ones (the Docker `api` service runs `kosh migrate` on start).
+  same ones (the Docker `api` service runs `shutro-erp migrate` on start).
 - **Destructive changes** (dropping a column or a table, narrowing a type) are written but not applied without
   `--allow-destructive`. A file written earlier and not applied yet is applied first.
 - **Per-module data migrations** change existing data when a module is upgraded. Declare them in the module's
@@ -298,7 +305,7 @@ export const migrations: DataMigration[] = [
 
 ```sh
 # index.ts: version: '0.2.0'
-npx kosh migrate    # … module library: 0.1.0 → 0.2.0, data migration library@0.2.0
+npx shutro-erp migrate    # … module library: 0.1.0 → 0.2.0, data migration library@0.2.0
 ```
 
 ## Seed data
@@ -322,18 +329,18 @@ export const data = [
 ```
 
 ```sh
-npx kosh seed                 # every module's seed data, and the apps' defaults
-npx kosh seed library         # one module (or several: kosh seed library inventory)
+npx shutro-erp seed                 # every module's seed data, and the apps' defaults
+npx shutro-erp seed library         # one module (or several: shutro-erp seed library inventory)
 ```
 
-`kosh migrate` seeds too (skip with `--no-seed`). The apps' defaults are also seeded: approval policies
+`shutro-erp migrate` seeds too (skip with `--no-seed`). The apps' defaults are also seeded: approval policies
 (permissions), document templates (reporting), activity types (messaging); users may edit them afterwards.
 
 ## Users and roles
 
 ```sh
-npx kosh user create rahim --name "Rahim Uddin" --email rahim@example.com --roles library.user,messaging.user
-npx kosh user password rahim     # a new password (asked, hidden)
+npx shutro-erp user create rahim --name "Rahim Uddin" --email rahim@example.com --roles library.user,messaging.user
+npx shutro-erp user password rahim     # a new password (asked, hidden)
 ```
 
 Roles are the groups of the installed modules' access levels (`library.user`, `library.manager`,
@@ -347,31 +354,31 @@ their roles grants it. Administrators manage roles, field security and grants in
 |---|---|
 | `DATABASE_URL` | PostgreSQL: `postgres://user:password@host:5432/database` |
 | `PORT`, `HOST` | the API's port (3000) and address (127.0.0.1; 0.0.0.0 in Docker) |
-| `KOSH_STORAGE_DIR` | attachments in this folder, or: |
+| `SHUTRO_ERP_STORAGE_DIR` | attachments in this folder, or: |
 | `S3_ENDPOINT`, `S3_BUCKET`, `S3_ACCESS_KEY`, `S3_SECRET_KEY`, `S3_REGION` | S3-compatible storage |
-| `KOSH_ATTACHMENT_MAX_BYTES` | upload limit (25 MB) |
+| `SHUTRO_ERP_ATTACHMENT_MAX_BYTES` | upload limit (25 MB) |
 | `VALKEY_URL` | optional Valkey/Redis: rate limits and caches across servers |
-| `KOSH_SECURE_COOKIES` | `true` behind HTTPS (default in production), `false` for plain HTTP |
-| `KOSH_SCHEDULES` | `off` stops the scheduled-report ticker on this server |
+| `SHUTRO_ERP_SECURE_COOKIES` | `true` behind HTTPS (default in production), `false` for plain HTTP |
+| `SHUTRO_ERP_SCHEDULES` | `off` stops the scheduled-report ticker on this server |
 | `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`, `POSTGRES_PORT` | the Docker `db` service |
 | `DOCKER_DATABASE_URL`, `WEB_PORT` | Docker: another database for `api`; the back-office's port (8080) |
 
 ## Command reference
 
-Run them in the project folder (`npx kosh …`, or `npm run migrate` / `npm run seed`). They read `.env` and
+Run them in the project folder (`npx shutro-erp …`, or `npm run migrate` / `npm run seed`). They read `.env` and
 `src/modules.ts` (`--modules <file>` for another list).
 
 | Command | What |
 |---|---|
-| `kosh init [folder]` | set up an installation (questions, or flags with `--yes`); again later to enrol 2FA |
-| `kosh migrate` | apply pending files, plan what is missing into a new file and apply it, run data migrations, seed |
-| `kosh migrate --plan` · `--name <n>` · `--allow-destructive` · `--no-seed` | review only · file name · drops · no seeding |
-| `kosh migrate status` | applied and pending migration files |
-| `kosh seed [module …]` | seed data of all modules, or of those named |
-| `kosh module create <name>` | a new module in `src/modules/<name>/`, listed in `src/modules.ts` |
-| `kosh user create <login>` | a user: `--name`, `--email`, `--roles`, `--password` (asked when missing) |
-| `kosh user password <login>` | a new password |
-| `kosh generate client` | a typed API client for your front-end (`--out src/api/kosh.gen.ts`) |
+| `shutro-erp init [folder]` | set up an installation (questions, or flags with `--yes`); again later to enrol 2FA |
+| `shutro-erp migrate` | apply pending files, plan what is missing into a new file and apply it, run data migrations, seed |
+| `shutro-erp migrate --plan` · `--name <n>` · `--allow-destructive` · `--no-seed` | review only · file name · drops · no seeding |
+| `shutro-erp migrate status` | applied and pending migration files |
+| `shutro-erp seed [module …]` | seed data of all modules, or of those named |
+| `shutro-erp module create <name>` | a new module in `src/modules/<name>/`, listed in `src/modules.ts` |
+| `shutro-erp user create <login>` | a user: `--name`, `--email`, `--roles`, `--password` (asked when missing) |
+| `shutro-erp user password <login>` | a new password |
+| `shutro-erp generate client` | a typed API client for your front-end (`--out src/api/shutro-erp.gen.ts`) |
 | `npm start` · `npm run web` · `npm run build:web` | the API · the back-office (dev) · the back-office build (`dist/`) |
 | `npm run docker:up` | `docker compose up -d --build` |
 
@@ -380,26 +387,26 @@ Run them in the project folder (`npx kosh …`, or `npm run migrate` / `npm run
 | Import | What |
 |---|---|
 | `shutro-erp` | the server: `createServer`, `startServer`, `base`, REST + OpenAPI, sessions and 2FA |
-| `shutro-erp/orm` | Shutro (models, fields, groups, records, migrations) as Kosh uses it |
+| `shutro-erp/orm` | Shutro (models, fields, groups, records, migrations) as Shutro ERP uses it |
 | `shutro-erp/modules-sdk` | `defineModule`: manifests, access levels, menus, actions |
 | `shutro-erp/views`, `shutro-erp/search` | view definitions (`list`, `form`, `kanban`, `pivot`, …) and the search layer |
 | `shutro-erp/permissions` | roles, field security, approvals (`/web`: the approval panel) |
 | `shutro-erp/reporting` | pivots, exports, documents, scheduled reports (`/web`: the report views) |
 | `shutro-erp/messaging`, `shutro-erp/storage` | the chatter, activities, attachments (`/web`: the chatter) |
 | `shutro-erp/ui` | the React app shell, design system and renderers; `shutro-erp/ui/styles.css` the tokens |
-| `shutro-erp/cli` | the `kosh` command's functions |
+| `shutro-erp/cli` | the `shutro-erp` command's functions |
 
 ## Troubleshooting
 
 - **"PostgreSQL did not answer"**: nothing listens at that host and port. Start your PostgreSQL service, or
   answer `2` (Docker) to the first question; Docker Desktop must be running.
 - **"password authentication failed"**: the user or password in `DATABASE_URL` is wrong.
-- **Signed in but no apps**: the user has no role granting them (`kosh user create … --roles`); administrators need
-  their authenticator enrolled (`npx kosh init` again).
-- **Sign-in works on the API but not in the browser over plain HTTP**: `KOSH_SECURE_COOKIES=false`.
-- **Lost the phone**: sign in with one of the recovery codes `kosh init` printed.
-- **"It drops or changes existing data"**: `kosh migrate` found a destructive change; read the new file in
-  `migrations/`, back up, then `npx kosh migrate --allow-destructive`.
+- **Signed in but no apps**: the user has no role granting them (`shutro-erp user create … --roles`); administrators need
+  their authenticator enrolled (`npx shutro-erp init` again).
+- **Sign-in works on the API but not in the browser over plain HTTP**: `SHUTRO_ERP_SECURE_COOKIES=false`.
+- **Lost the phone**: sign in with one of the recovery codes `shutro-erp init` printed.
+- **"It drops or changes existing data"**: `shutro-erp migrate` found a destructive change; read the new file in
+  `migrations/`, back up, then `npx shutro-erp migrate --allow-destructive`.
 
 Documentation, design notes and the source: https://github.com/isahaq1/kosh
 

package/dist/account_portal/.kosh/bindings.d.ts

@@ -0,0 +1,22 @@
+export { defineModel, defineModule, extendModel, f, replace } from '../../server/orm.js';
+import { type DefinitionHelpers } from '../../server/orm.js';
+import type { DefaultLoaded, Env as CoreEnv, RecordSet as CoreRecordSet, Shutro as CoreShutro } from '../../server/orm.js';
+import type { SchemaView } from './schema.js';
+export type { SchemaView };
+/** Every model visible in this view. */
+export type ModelName = keyof SchemaView & string;
+/** `Env` typed to this view. */
+export type Env = CoreEnv<SchemaView>;
+/** `Shutro` typed to this view. */
+export type Shutro = CoreShutro<SchemaView>;
+/** A recordset of `M`, with the default loaded shape unless `L` is given. */
+export type Records<M extends ModelName, L = DefaultLoaded<SchemaView, M>> = CoreRecordSet<SchemaView, M, L>;
+export declare const compute: DefinitionHelpers<SchemaView>['compute'];
+export declare const check: DefinitionHelpers<SchemaView>['check'];
+export declare const onchange: DefinitionHelpers<SchemaView>['onchange'];
+export declare const records: DefinitionHelpers<SchemaView>['records'];
+export declare const method: DefinitionHelpers<SchemaView>['method'];
+/** Module data (RFC 0017): records, overrides of dependencies' records, and references, typed like creates. */
+export declare const record: DefinitionHelpers<SchemaView>['record'];
+export declare const override: DefinitionHelpers<SchemaView>['override'];
+export declare const ref: DefinitionHelpers<SchemaView>['ref'];

package/dist/account_portal/.kosh/bindings.js

@@ -0,0 +1,15 @@
+// GENERATED by `pnpm generate:models` (Shutro’s generator). Do not edit. definitions-hash: 0ea5d21ac5b24166
+// Bindings of module `account_portal`: import the definition API from here to get types scoped to what it can see.
+export { defineModel, defineModule, extendModel, f, replace } from '../../server/orm.js';
+import { definitions } from '../../server/orm.js';
+/** Definition callbacks typed against this module's view: no casts in computes, checks, onchange, methods. */
+const helpers = definitions();
+export const compute = helpers.compute;
+export const check = helpers.check;
+export const onchange = helpers.onchange;
+export const records = helpers.records;
+export const method = helpers.method;
+/** Module data (RFC 0017): records, overrides of dependencies' records, and references, typed like creates. */
+export const record = helpers.record;
+export const override = helpers.override;
+export const ref = helpers.ref;