@codenotch/codenotch.cli 1.0.40 → 1.0.42

package/resources/docs/project.md

@@ -0,0 +1,101 @@
+# The anatomy of a Codenotch project
+
+What a Codenotch project is made of, which files are generated from which sources, and the commands of its lifecycle.
+
+A Codenotch project is TypeScript end to end: server-side processes are `process({...})`
+declarations from `@codenotch/process`, tables are `defineEntity({...})` from `@codenotch/orm`,
+apps are React 19 components. The project is built, deployed and run on a Codenotch runtime by
+the `cn` CLI. The CLI discovers what the project declares by parsing its TypeScript sources —
+there is no registry to maintain by hand.
+
+## Layout
+
+| Path | Contains | Topic |
+| --- | --- | --- |
+| `manifest.json` | project name, service name, version, languages and roles | below |
+| `package.json` | npm dependencies, React and `@codenotch/codenotch.react` | |
+| `tsconfig.json` | covers the sources and the generated `db-schema.d.ts` | below |
+| `processes/` | server side processes, plain TypeScript files | `cn docs processes` |
+| `tables/` | SQL table definitions (`defineEntity`) | `cn docs tables` |
+| `documents/` | NoSQL document schemas (`defineDocument`) | `cn docs tables` |
+| `queries/` | `.cnql` read queries run by the processes | `cn docs queries` |
+| `apps/` | React apps: `<App>.tsx` and its `<App>.manifest.json` | `cn docs apps` |
+| `*.i18n.csv` | translations, one column per language | `cn docs i18n` |
+
+The folder names are a convention, not a requirement: the CLI discovers declarations by parsing
+every TypeScript file of the project, wherever it sits.
+
+## manifest.json
+
+```json
+{
+    "packages": {},
+    "projectName": "My Project",
+    "serviceName": "myproject",
+    "languages": ["en", "de", "fr"],
+    "roles": [],
+    "version": "0.0.0",
+    "dependencies": [],
+    "postInstallationProcesses": []
+}
+```
+
+`serviceName` identifies the project on the runtime and is part of its URL. Renaming it means
+updating every reference to it (queries carry it as their `xmlns`, for instance) — treat it as
+fixed unless the user explicitly asks for a rename.
+
+## Generated files — never edit them
+
+| File | Generated from | Regenerate with |
+| --- | --- | --- |
+| `db-schema.xml` | the `defineEntity` declarations | `cn generate dbcontext -f .` |
+| `db-schema.d.ts` | same — types `ctx.tables` by declaration merging | `cn generate dbcontext -f .` |
+| `openapi.json` | the processes exposing endpoints | `cn generate openapi -f .` |
+| `*.i18n.ts` | its sibling `*.i18n.csv` | `cn generate i18n -f <file>.i18n.csv` |
+| `compiled/` | the processes, one self-contained `.js` each | `cn project compile` (or packaging) |
+| `.codenotch/` | React build staging | `cn react build` |
+
+These files are in `.gitignore`: after a fresh clone they have to be generated again before the
+project compiles. When one of them looks wrong, fix the source it is generated from, then
+regenerate — an edit to the generated file is overwritten on the next run.
+
+`tsconfig.json` must keep including `db-schema.d.ts`: the declaration merging it carries only
+applies to files of the same TypeScript program, so removing it from `include` silently untypes
+`ctx.tables` in every process.
+
+## Lifecycle
+
+```sh
+npm install -g @codenotch/codenotch.cli   # the 'cn' command
+cn runtime update              # install (or update) the local Codenotch runtime
+cn runtime start               # start it
+cn project start               # build, deploy and open this project
+cn project refresh             # after a change: sync the project with the runtime
+```
+
+Checks, at any time:
+
+```sh
+cn validate .                  # hints, warnings and errors of every file
+cn project inspect             # parse the project and display everything the CLI discovered
+cn project test                # run the tests of the project
+cn project compile             # typecheck and bundle the processes, without packaging
+```
+
+`cn validate`, `cn project inspect`, `cn runtime info` and `cn docs` all take `--json` for
+machine-readable output.
+
+Shipping:
+
+```sh
+cn project package             # compile and package the project as a zip
+cn project deploy <service> <zip>
+```
+
+Packaging typechecks the whole project first: type errors fail it.
+
+## The TODO policy
+
+Where the runtime API is not settled yet (the client-side call of a process, the CNQL filter
+syntax), the code carries an explicit `TODO` comment instead of a guess. Keep that policy: never
+invent an API shape where the existing sources marked one as unsettled.

package/resources/docs/queries.md

@@ -0,0 +1,54 @@
+# CNQL queries
+
+The `.cnql` read queries a process runs through `ctx.query`, and what is still unsettled in their syntax.
+
+CNQL is an XML query language for reading data. A query lives in its own `.cnql` file,
+conventionally under `queries/`, and is run from a process:
+
+```ts
+const lists = await ctx.query<ITodoList>('queries/all-todolists.cnql')
+const todos = await ctx.query<ITodo>('queries/todos-of-list.cnql', { listId: input.listId })
+```
+
+The path is relative to the project root; the type parameter types the returned rows.
+
+## Structure
+
+```xml
+<CNQL xmlns="myservice" PageSize="100" PageIndex="0">
+    <TodoList Ref="results">
+        <Id />
+        <Name />
+        <CreatedAt />
+    </TodoList>
+</CNQL>
+```
+
+- The root is `<CNQL>`, its `xmlns` is the **service name** of the project (`serviceName` of
+  `manifest.json`), `PageSize`/`PageIndex` paginate the result.
+- The first child is the queried **table**, named as declared in its `defineEntity` (`TodoList`,
+  not `todolists`). `Ref` names the output.
+- Its children are the **columns** to select, PascalCase. `CreatedAt` is maintained by the
+  runtime and can be selected without being declared on the entity.
+
+Only reads: inserts, updates and deletes go through `ctx.tables` in a process.
+
+## What is not settled yet — keep the TODO policy
+
+The **filter syntax** (restricting rows, binding the parameters passed as the second argument of
+`ctx.query`) is not settled in the runtime yet. Generated projects mark the spot with an explicit
+comment instead of guessing:
+
+```xml
+<!-- TODO: filter on the 'listId' parameter passed by the process. The filtering syntax of CNQL is not settled yet. -->
+<CNQL xmlns="myservice" PageSize="100" PageIndex="0">
+    <Todo Ref="results">
+        <Id />
+        <Title />
+        <ListId />
+    </Todo>
+</CNQL>
+```
+
+Do the same: never invent a filter, join, ordering or grouping syntax. When a query needs one,
+write the unfiltered query, carry the `TODO` comment, and mention it to the user.

package/resources/docs/tables.md

@@ -0,0 +1,97 @@
+# Tables and documents
+
+How to declare the SQL tables and NoSQL documents of a project with `@codenotch/orm`, and how they become `db-schema.xml` and the typed `ctx.tables`.
+
+## Declaring a table
+
+A table is a `defineEntity({...})` declaration, conventionally one file per table under `tables/`:
+
+```ts
+import { defineEntity, type InferEntity, p } from '@codenotch/orm';
+
+export const TodoList = defineEntity({
+  name: 'TodoList',
+  properties: {
+    id: p.uuid().primary(),
+    name: p.string().notNull(),
+    // Deleting a list deletes its todos
+    todos: p.hasMany('Todo').linkBehaviour('Delete'),
+  },
+});
+
+export type ITodoList = InferEntity<typeof TodoList>;
+```
+
+Three conventions are load-bearing, the CLI warns and skips when they are broken:
+
+- the variable is **exported** and `name` is a **string literal** (a name built at runtime cannot
+  be discovered from the sources);
+- the row type is exported next to it: `export type ITodoList = InferEntity<typeof TodoList>` —
+  without it the table is left out of the typed `ctx.tables`;
+- table names are unique once pluralized (see collection names below).
+
+## Column builders
+
+Everything `p` exposes, with the aliases mapping to the same schema type:
+
+| Builder | Schema type |
+| --- | --- |
+| `p.string()` — accepts a length, e.g. `p.string(255)` | String |
+| `p.text()` | Text |
+| `p.email()` | Email |
+| `p.integer()` / `p.int()` | Integer |
+| `p.decimal()` / `p.float()` / `p.number()` | Decimal |
+| `p.boolean()` / `p.bool()` | Boolean |
+| `p.uuid()` / `p.guid()` | Guid |
+| `p.date()` | Date |
+| `p.datetime()` / `p.timestamp()` | DateTime |
+| `p.version()` | Version |
+| `p.enum()` | Enum |
+| `p.autoIncrement()` | AutoIncrement |
+| `p.belongsTo('Target')` | relation, holds the foreign key |
+| `p.hasOne('Target')` / `p.hasMany('Target')` | relation on the other side |
+
+A builder outside this list is reported as a warning and left out of the schema — it is never
+silently mapped to a guessed type.
+
+Modifiers, chained after the builder:
+
+| Modifier | Effect |
+| --- | --- |
+| `.primary()` | primary key (implies non-nullable) |
+| `.notNull()` / `.required()` | non-nullable |
+| `.unique()` | uniqueness constraint |
+| `.default(value)` | default value (a literal) |
+| `.linkBehaviour('Delete')` | on a relation: deleting the parent deletes the linked rows |
+
+A `hasMany`/`hasOne` finds its paired `belongsTo` on the target table automatically; declare the
+`belongsTo` side explicitly when the target has several relations to the same table.
+
+## Collection names — how `ctx.tables` is keyed
+
+A table is reachable in the processes under its lowercased, pluralized name: `TodoList` →
+`ctx.tables.todolists`, `Box` → `ctx.tables.boxes`, `Category` → `ctx.tables.categories`. Two
+tables mapping to the same collection name is a conflict: only the first one is kept, with a
+warning.
+
+## Documents
+
+A document is declared the same way with `defineDocument({...})` (conventionally under
+`documents/`), its type exported with `InferDocument`. Documents are keyed by their lowercased
+name, **not** pluralized, and typed as document-store handles rather than table handles.
+
+## Generation
+
+```sh
+cn generate dbcontext -f .
+```
+
+writes two files at the project root — both generated, never edit them:
+
+- `db-schema.xml` — the schema the runtime migrates the database from;
+- `db-schema.d.ts` — augments the `ProjectTables` and `ProjectDocs` interfaces of
+  `@codenotch/process` by declaration merging, so `ctx.tables.<collection>` autocompletes with
+  the row type of the table.
+
+Regenerate after every change to a `defineEntity`/`defineDocument` declaration. The project's
+`tsconfig.json` must keep `db-schema.d.ts` in its `include` for the merging to apply.