namirasoft-site 1.4.45 → 1.4.46

package/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: namirasoft-site
+description: Use the namirasoft-site package when modeling a Namirasoft product as a typed metadata graph (database -> tables -> rows) with shared HTTP versioning. Trigger when the project's package.json depends on "namirasoft-site", when subclassing NSBaseServer / NSBaseMetaDatabase / NSBaseMetaTable, when wiring an axios-based product client that must send the ns-site-version header, when generating route URLs (list/new/view/edit) for a product table, or when parsing a Namirasoft package/API/console name with NSNameParser. Skip for pure UI work — that lives in namirasoft-site-react.
+---
+
+# namirasoft-site
+
+The framework-agnostic "site" layer for Namirasoft products. It extends `namirasoft-core`'s `BaseServer` / `BaseMetaDatabase` / `BaseMetaTable` with product-aware metadata, link generation, and a shared `ns-site-version` request header convention. There is no UI here — `namirasoft-site-react` is the React companion.
+
+## When this skill applies
+
+Trigger when the project's `package.json` lists `namirasoft-site` as a dependency, or when the user imports anything from `"namirasoft-site"`. Typical signals:
+
+- defining a new product's database/table metadata (`class FooDatabase extends NSBaseMetaDatabase<FooServer>`)
+- writing an axios client that must propagate or read the `ns-site-version` header
+- generating product-relative URLs (`/foo/list`, `/foo/{id}/view`, `/foo/{id}/edit`)
+- introspecting a Namirasoft package/repo name to derive class names, short names, or CLI command names
+
+Skip for plain backend services that don't model a product, and for UI rendering (use `namirasoft-site-react`).
+
+## Cardinal rules
+
+1. **Reuse the base classes — don't reimplement.** Every product server extends `NSBaseServer`, every product database extends `NSBaseMetaDatabase<YourServer>`, every product table extends `NSBaseMetaTable<YourServer, Row>`. Don't hand-roll axios clients or metadata containers; subclass these so version-header wiring, link generation, and CFT (category/field/tag) sibling-table detection come for free.
+2. **Always import from the package root**: `import { NSBaseServer, NSHeader } from "namirasoft-site";` — never deep-import from `dist/...`.
+3. **Override `NSBaseMetaDatabase.getServerBaseURL`** (the static method) at app bootstrap before any server is instantiated. The default throws. The React companion sets this from `REACT_APP_BASE_URL_<X>` env vars; non-React consumers must provide their own resolver.
+4. **The version header is `ns-site-version` for both request and response.** Use `NSHeader.req.VERSION()` / `NSHeader.res.VERSION()` instead of hard-coding the string. `NSBaseServer` already attaches it via `addOnBeforeRequest` / `addOnAfterRequest` in its constructor — don't re-register the same hooks in subclasses.
+5. **Pass the product to the database constructor.** `NSBaseMetaDatabase` requires `{ id, name, headline, description, logo, link }`; `link` is the URL prefix that `NSBaseMetaTable_Frontend.getBaseLink()` joins against.
+6. **Use `NamingConvention.lower_case_dash` for CFT lookups.** `isCFTTable()` / `hasFieldTables()` already do; if you call the static helpers (`getCFTTables`, `HasCFTTable`, `IsCFTTable`) directly, pass a `NamingConvention` from `namirasoft-core` — the helpers normalize on your behalf.
+7. **Treat `NSBaseMetaTable_Backend<Row>` slots as optional.** Each verb has both an underscore-prefixed (raw) and bare (wrapped) slot: `_get`/`get`, `_list`/`list`, `_create`/`create`, `_update`/`update`, `_delete`/`delete`. Wire only the verbs the API actually supports; consumers must null-check before calling.
+
+## API surface
+
+All exports come from the package root.
+
+### Servers
+
+- **`NSBaseServer`** (abstract, extends `BaseServer` from `namirasoft-core`) — axios-based product client.
+  - `constructor(base_url: string, version: string)` — registers before/after-request hooks that set the request `ns-site-version` header to `version` and capture the response's version into `this.backend.version`.
+  - `backend: { version: string }` — last-seen backend version, populated after each response.
+  - Static helpers: `onBeforeRequest_SetVersion(version, config)`, `onAfterRequest_GetVersion(res)` — usable standalone if you need the same wiring outside an `NSBaseServer` subclass.
+
+### Metadata
+
+- **`NSBaseMetaDatabase<Server extends NSBaseServer>`** (abstract, extends `BaseMetaDatabase`) — container for a product's tables.
+  - `static getServerBaseURL(product_name: string): string` — override this once at module load to map a product name to its base URL. Default throws.
+  - `product: { id, name, headline, description, logo, link }` — set via constructor.
+  - `tables: { [name: string]: NSBaseMetaTable<Server, any> }` — populate in your subclass.
+  - `abstract getServer(): Server` — returns the singleton server for this database.
+  - `getByShortName(short)` / `getByShortNameOrNull(short)` — look up a table by `uuid.short`.
+
+- **`NSBaseMetaTable<Server, Row>`** (abstract, extends `BaseMetaTable`) — one product table.
+  - `constructor(database, name, text, uuid: BaseUUID)` — auto-creates `front_end` and `back_end`.
+  - `front_end: NSBaseMetaTable_Frontend`, `back_end: NSBaseMetaTable_Backend<Row>`.
+  - `isCFTTable()` / `hasFieldTables()` — detect category/field/tag siblings (`<name>_category`, `<name>_field`, `<name>_tag`).
+  - Static helpers: `getTableAndCFTs`, `getTableAndCFTsIfExists`, `getCFTTables`, `getCFTTablesIfExists`, `HasCFTTable`, `IsCFTTable`.
+
+- **`NSBaseMetaTable_Frontend`** — link builder bound to a table.
+  - `getBaseLink()` -> `<product.link>/<table-in-slash-case>`
+  - `getListLink()` -> `<base>/list`
+  - `getNewLink()`  -> `<base>/new`
+  - `getViewLink(id)` -> `<base>/<id>/view`
+  - `getUpdateLink(id)` -> `<base>/<id>/edit`
+
+- **`NSBaseMetaTable_Backend<Row>`** — optional CRUD adapter slots: `_get`/`get`, `_list`/`list`, `_create`/`create`, `_update`/`update`, `_delete`/`delete`. The `_*` variants are the raw API call; the bare ones are the wrapped/cached version. Both signatures match `namirasoft-core`'s `FilterItem` / `SortItem`.
+
+### Headers
+
+- **`NSHeader`** — namespace with three static fields:
+  - `NSHeader.req: NSReqHeader` — `req.VERSION()` returns `"ns-site-version"`.
+  - `NSHeader.res: NSResHeader` — `res.VERSION()` returns `"ns-site-version"`.
+  - `NSHeader.cookies: NSCookiesHeader` — currently empty, reserved.
+- **`NSReqHeader`**, **`NSResHeader`**, **`NSCookiesHeader`** — exported individually if you need to extend.
+
+### Name parsing
+
+- **`NSNameParser(name_full, title_full)`** — classifies a Namirasoft repo/package name and extracts canonical short/long forms.
+  - Booleans: `isAPI`, `isConsole`, `isLibrary`, `isNPM`, `isPHP`, `isAccountAPI`.
+  - Per-kind structures (`api`, `console`, `library`) of type `NSNameParserStructure` with `name_namirasoft`, `name_short`, `title_namirasoft`, `title_short`, `class_namirasoft`, `class_short`.
+  - `command.name` — derived CLI command (`namirasoft-` -> `ns-`).
+  - Detection regexes: API matches `^namirasoft(-\w*)*-api(-\w*)*-v\d+$`, Console matches `^namirasoft-(\w+-)+console$`, Library is the residual `^namirasoft-\w+`. NPM/PHP are inferred from `title_full` ending in `NPM Package` / `PHP Package`.
+
+## Canonical examples
+
+### Subclassing `NSBaseServer`
+
+```ts
+import { NSBaseServer } from "namirasoft-site";
+
+export class FooServer extends NSBaseServer {
+    constructor(base_url: string, version: string) {
+        super(base_url, version);
+        // version header + backend.version capture are wired by the parent
+    }
+
+    public listFoos = () => this.axios.get("/foo");
+}
+```
+
+Don't re-register `addOnBeforeRequest` / `addOnAfterRequest` for versioning — `NSBaseServer`'s constructor already does it. Read the latest backend version from `this.backend.version` after any request.
+
+### Defining a product database + table
+
+```ts
+import { NSBaseMetaDatabase, NSBaseMetaTable } from "namirasoft-site";
+import { BaseUUID } from "namirasoft-core";
+import { FooServer } from "./FooServer";
+
+class FooTable extends NSBaseMetaTable<FooServer, { id: string; name: string }> {
+    constructor(db: FooDatabase) {
+        super(db, "foo", "Foo", new BaseUUID(/* ... */));
+        this.back_end._list = async (filters, page, size, sorts) => {
+            const res = await db.getServer().listFoos();
+            return { rows: res.data, count: res.data.length };
+        };
+        this.back_end.list = this.back_end._list;
+    }
+}
+
+export class FooDatabase extends NSBaseMetaDatabase<FooServer> {
+    private server: FooServer;
+    constructor() {
+        super({
+            id: "foo",
+            name: "foo",
+            headline: "Foo headline",
+            description: "Foo description",
+            logo: "/logo.png",
+            link: "/foo",
+        });
+        this.server = new FooServer(
+            NSBaseMetaDatabase.getServerBaseURL("namirasoft-foo"),
+            "1.0.0",
+        );
+        this.tables["foo"] = new FooTable(this);
+    }
+    getServer() { return this.server; }
+}
+```
+
+Once instantiated, `database.tables["foo"].front_end.getViewLink("123")` yields `"/foo/foo/123/view"`.
+
+### Registering the base-URL resolver
+
+```ts
+import { NSBaseMetaDatabase } from "namirasoft-site";
+
+NSBaseMetaDatabase.getServerBaseURL = (product_name: string) => {
+    const key = product_name.replace(/^namirasoft-/, "").replace(/-/g, "_").toUpperCase();
+    const url = process.env[`BASE_URL_${key}`];
+    if (!url) throw new Error(`Missing BASE_URL_${key} for ${product_name}`);
+    return url;
+};
+```
+
+Do this once at app bootstrap, before any `NSBaseMetaDatabase` subclass is constructed.
+
+### Parsing a package name
+
+```ts
+import { NSNameParser } from "namirasoft-site";
+
+const p = new NSNameParser("namirasoft-account-api-v3", "Namirasoft Account API V3");
+p.isAPI;                  // true
+p.isAccountAPI;           // true
+p.api.name_short;         // "account"
+p.api.class_namirasoft;   // "NamirasoftAccount"
+p.command.name;           // "ns-account"
+```
+
+## Common mistakes to avoid
+
+- Hand-rolling an axios client with a hard-coded `"ns-site-version"` string instead of subclassing `NSBaseServer` and using `NSHeader.req.VERSION()`.
+- Leaving `NSBaseMetaDatabase.getServerBaseURL` at its default — instantiating any database will throw with `"NSBaseMetaDatabase.getServerBaseURL was not overriden"`.
+- Calling `back_end.get?.(id)` without null-checking — every CRUD slot is optional.
+- Using `className`-style slash-cased table names directly in URLs; `NSBaseMetaTable_Frontend` already converts `lower_case_underscore` -> `lower_case_slash` via `NamingConvention`.
+- Re-adding `addOnBeforeRequest` / `addOnAfterRequest` for versioning in an `NSBaseServer` subclass — duplicates the header write.
+- Importing `BaseServer`, `BaseMetaTable`, `BaseUUID`, `NamingConvention`, `FilterItem`, `SortItem` from `"namirasoft-site"` — they live in `namirasoft-core`. This package only re-exports its own `NS*` extensions.
+- Treating `NSCookiesHeader` as having members — it is currently an empty placeholder.
+
+## Peer expectations
+
+- **Runtime deps**: `namirasoft-core` (^1.4.108), `axios` (^1.13.x). Both are required peers in practice — `BaseServer`, `BaseMetaTable`, `BaseUUID`, `NamingConvention`, `FilterItem`, `SortItem` all come from `namirasoft-core`.
+- **No framework binding**: this package is framework-agnostic (Node or browser). Consumers needing React UI should pair it with `namirasoft-site-react`, which depends on this package.
+- **No env vars are read directly** — `getServerBaseURL` is a static hook the host app must implement. The React companion wires it to `REACT_APP_BASE_URL_<X>`; backend hosts typically wire it to `process.env.BASE_URL_<X>`.

package/package.json

@@ -8,7 +8,7 @@
     "framework": "npm",
     "application": "package",
     "private": false,
-    "version": "1.4.45",
+    "version": "1.4.46",
     "author": "Amir Abolhasani",
     "license": "MIT",
     "main": "./dist/index.js",
@@ -17,7 +17,7 @@
         "build": ""
     },
     "dependencies": {
-        "axios": "^1.14.0",
-        "namirasoft-core": "^1.4.114"
+        "axios": "^1.18.1",
+        "namirasoft-core": "^1.4.120"
     }
 }

package/tsconfig.json

@@ -8,6 +8,9 @@
             "es6",
             "dom"
         ],
+        "types": [
+            "node"
+        ],
         "allowJs": false,
         "checkJs": false,
         "strict": true,