namirasoft-sdk-generator 1.4.61 → 1.4.62
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/SKILL.md +191 -0
- package/logo.png +0 -0
- package/package.json +4 -4
- package/tsconfig.json +3 -0
package/SKILL.md
ADDED
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: namirasoft-sdk-generator
|
|
3
|
+
description: Use the namirasoft-sdk-generator (`ns-sdkg`) CLI to generate downstream client SDK packages (TypeScript NPM and PHP/Composer) from a Namirasoft API server's `application.schema`. Trigger when the user runs `ns-sdkg`, asks how to (re)generate a `Namirasoft<X>Server` / `<X>MetaDatabase` / `<X>Row` / CLI command set for an API, edits files in a generated SDK package and needs them regenerated, or works with `.ns-sdkg-file-keep` / `.ns-sdkg-dir-keep` / `.ns-sdkg-dir-deep` / `ns-sdkg` blocks in `package.json`.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# namirasoft-sdk-generator
|
|
7
|
+
|
|
8
|
+
A code-generator CLI published as `namirasoft-sdk-generator` on npm. The binary is `ns-sdkg`. It reads a Namirasoft API server's compiled `application.schema` and emits a fully-typed client SDK package — either a TypeScript NPM package or a PHP/Composer package — covering the API server class, per-tag server bases, row types, enums, meta tables/database, and a `cli.ts` entry point.
|
|
9
|
+
|
|
10
|
+
## When this skill applies
|
|
11
|
+
|
|
12
|
+
Trigger when:
|
|
13
|
+
- The user invokes `ns-sdkg build npm <src> <dst>` or `ns-sdkg build php <src> <dst>`.
|
|
14
|
+
- The user asks "how do I regenerate the SDK", "regen the client", or talks about updating a `Namirasoft<X>Server` / `Namirasoft<X>MetaDatabase` package.
|
|
15
|
+
- The user edits a file marked `This is an Auto-Generated File` and needs the change to survive regeneration (see Cardinal rule #2).
|
|
16
|
+
- The user adds/edits an `ns-sdkg` config block inside an API server's `package.json`.
|
|
17
|
+
- The user runs `ns-sdkg git login` / `clone` / `logout` to manage SDK repos.
|
|
18
|
+
|
|
19
|
+
Skip otherwise — this is not a generic codegen tool; it only consumes Namirasoft `application.schema` files.
|
|
20
|
+
|
|
21
|
+
## Cardinal rules
|
|
22
|
+
|
|
23
|
+
1. **`ns-sdkg` is the only supported entry.** Always invoke through the binary (`npx ns-sdkg ...` or globally installed `ns-sdkg ...`). Do not import builders programmatically — `NPMBuilder` / `PHPBuilder` are not part of the public surface.
|
|
24
|
+
2. **Generated files are sacred.** Every emitted file starts with `This is an Auto-Generated File ... Please do not make any change to this file`. Edits will be wiped on the next run. To preserve hand-written code in a generated package, use the keep-files (rule #4) and put your code in non-generated paths.
|
|
25
|
+
3. **The source directory must be a buildable Namirasoft API server.** The builder runs `ncu -u`, `npm i`, `tsc`, then `node ./dist/index.js` against the source — that step writes `application.schema`, which is then parsed. If the API server doesn't compile or doesn't emit `application.schema`, generation fails.
|
|
26
|
+
4. **Use the keep-files in the destination to preserve hand-written content across regenerations:**
|
|
27
|
+
- `.ns-sdkg-file-keep` — newline-separated file paths to keep (always-kept defaults: `package.json`, the three keep-files themselves).
|
|
28
|
+
- `.ns-sdkg-dir-keep` — newline-separated directory names to keep entirely (always-kept default: `.git`).
|
|
29
|
+
- `.ns-sdkg-dir-deep` — directories to recurse into (apply keep rules within) instead of dropping wholesale.
|
|
30
|
+
The destination is cleaned at the start of each run; anything not protected by these files is deleted.
|
|
31
|
+
5. **Customize generation via the `ns-sdkg` block in the source `package.json`**, not by patching output. Two supported sub-blocks:
|
|
32
|
+
- `ns-sdkg.package.dependencies` — extra deps to add to the generated `package.json` / `composer.json`. Each is pinned to `BaseBuilder.MIN_VERSION` (`^1.4.0`).
|
|
33
|
+
- `ns-sdkg.meta.tables.<TableName>` — per-table overrides: `row` (rename the generated row class), and per-controller overrides (`_Get`, `Get`, `_List`, `List`) with `enabled`, `function` (rename the called server method), and `parameters.id.type` (`"string"` or `"number"`).
|
|
34
|
+
6. **Account-aware APIs are auto-detected** from `schema.tags.account === "true"`. When true, the generated server extends `NSABaseServer`, the constructor takes a `TokenManager`, and CLI commands require a logged-in account token. The Account API itself imports `TokenManager` locally; every other account-aware API imports it from `namirasoft-account`.
|
|
35
|
+
7. **`ns-sdkg git login` stores credentials**, used by `ns-sdkg git clone <url> <directory>` to inject `https://user:pass@<url>` for HTTPS clones. Treat these as secrets — they live in the storage backed by `BaseStorage` from `namirasoft-node-cli`.
|
|
36
|
+
8. **MIN_VERSION is fixed at `^1.4.0`.** Generated packages pin every Namirasoft peer (`namirasoft-core`, `namirasoft-site`, `namirasoft-node-cli`, `namirasoft-account`, plus user-listed extras) to that range — bump `BaseBuilder.MIN_VERSION` in this package if you need to lift the floor.
|
|
37
|
+
|
|
38
|
+
## Command surface
|
|
39
|
+
|
|
40
|
+
```
|
|
41
|
+
ns-sdkg build npm <source> <destination> # generate TS NPM SDK
|
|
42
|
+
ns-sdkg build php <source> <destination> # generate PHP/Composer SDK
|
|
43
|
+
ns-sdkg git login <username> <password> # store git creds for clone
|
|
44
|
+
ns-sdkg git clone <url-without-scheme> <dir> # https clone using stored creds
|
|
45
|
+
ns-sdkg git logout # delete stored git creds
|
|
46
|
+
ns-sdkg config <key> <value> # base config (from namirasoft-node-cli)
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
`<source>` and `<destination>` are paths; both are resolved with `path.resolve(...).toLowerCase()` before use, so case differences won't create duplicate dirs but **paths on case-sensitive filesystems must already be lowercase**.
|
|
50
|
+
|
|
51
|
+
## Input expectations (source directory)
|
|
52
|
+
|
|
53
|
+
The source must be a Namirasoft API server package whose `package.json` includes:
|
|
54
|
+
- `name`, `title`, `description`, `version`, `logo` — copied/derived into the generated package.
|
|
55
|
+
- Optional `ns-sdkg` block (see Cardinal rule #5).
|
|
56
|
+
|
|
57
|
+
After build, the source is expected to produce `application.schema` at the root (the builder runs `node ./dist/index.js` with `NAMIRASOFT_MUTE="true"` and `BASE_PATH=/` in `.env` to trigger this). The schema is loaded via `ApplicationSchema.byFile`, then `NamirasoftAPIProductServer` (`https://namirasoft.com/api/product/v1`) is queried for product metadata using `schema.meta.product_id`.
|
|
58
|
+
|
|
59
|
+
## Output structure (NPM target)
|
|
60
|
+
|
|
61
|
+
```
|
|
62
|
+
<dst>/
|
|
63
|
+
├── package.json # name, version, deps pinned to ^1.4.0
|
|
64
|
+
├── tsconfig.json # downloaded template
|
|
65
|
+
├── .gitignore .npmignore .gitlab-ci.yml # downloaded templates
|
|
66
|
+
├── logo.png # copied from source
|
|
67
|
+
└── src/
|
|
68
|
+
├── index.ts # re-exports every generated module + kept .ts files
|
|
69
|
+
├── Namirasoft<X>Server.ts # extends NSBaseServer or NSABaseServer
|
|
70
|
+
├── Namirasoft<X>ServerBase.ts # holds `server` ref for tag servers
|
|
71
|
+
├── Namirasoft<X>Server<Tag>.ts # one per controller tag, with bound methods
|
|
72
|
+
├── command/
|
|
73
|
+
│ ├── cli.ts # #!/usr/bin/env node, registers tag commands
|
|
74
|
+
│ ├── <Tag>Command.ts # BaseNavigatorCommand per tag
|
|
75
|
+
│ └── <Tag><Op>Command.ts # BaseFinalCommand per controller op
|
|
76
|
+
├── meta/
|
|
77
|
+
│ ├── Namirasoft<X>MetaDatabase.ts # extends NSBaseMetaDatabase
|
|
78
|
+
│ └── <Table>MetaTable.ts # extends NSBaseMetaTable, columns + back_end hooks
|
|
79
|
+
├── row/<Type>Row.ts # exported `type` aliases for objects
|
|
80
|
+
└── enum/<Enum>.ts # `export enum ...`
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
The `package.json` `bin` entry is set to the API's command name (from `NSNameParser`) pointing at `./dist/command/cli.js`.
|
|
84
|
+
|
|
85
|
+
## Output structure (PHP target)
|
|
86
|
+
|
|
87
|
+
Mirrors the NPM layout under `src/`, but emits PHP classes via the parallel `PHPBuilder` / `TypeBuilder` / `PHP` modules, and writes both `package.json` (Namirasoft-style metadata) and `composer.json` (PSR-4 autoload, requires `namirasoft/core` + `namirasoft/site`, optionally `namirasoft/account`).
|
|
88
|
+
|
|
89
|
+
## Customization hooks (recap)
|
|
90
|
+
|
|
91
|
+
| Hook | Where | Effect |
|
|
92
|
+
|---|---|---|
|
|
93
|
+
| `ns-sdkg.package.dependencies` | source `package.json` | Adds deps to generated package, pinned to `^1.4.0` |
|
|
94
|
+
| `ns-sdkg.meta.tables.<T>.row` | source `package.json` | Override generated row class name |
|
|
95
|
+
| `ns-sdkg.meta.tables.<T>.<Op>.enabled` | source `package.json` | Force-enable/disable a meta back_end binding (default: presence of matching controller) |
|
|
96
|
+
| `ns-sdkg.meta.tables.<T>.<Op>.function` | source `package.json` | Call a different server method name |
|
|
97
|
+
| `ns-sdkg.meta.tables.<T>.<Op>.parameters.id.type` | source `package.json` | `"number"` wraps id in `parseInt(...)` |
|
|
98
|
+
| `.ns-sdkg-file-keep` | destination root | Preserve specific files |
|
|
99
|
+
| `.ns-sdkg-dir-keep` | destination root | Preserve whole directories |
|
|
100
|
+
| `.ns-sdkg-dir-deep` | destination root | Recurse into directories instead of dropping them |
|
|
101
|
+
| `schema.tags.account === "true"` | source `application.schema` | Switches generation to `NSABaseServer` + `TokenManager` |
|
|
102
|
+
|
|
103
|
+
## Canonical examples
|
|
104
|
+
|
|
105
|
+
### Regenerate a TypeScript SDK
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
# from a workspace that holds both the API server and SDK package
|
|
109
|
+
ns-sdkg build npm ./api/myproduct ./sdk/namirasoft-myproduct
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
What happens:
|
|
113
|
+
1. `cwd = ./api/myproduct`: runs `ncu -u`, `npm i`, `tsc`, writes `.env`, runs `node ./dist/index.js` to produce `application.schema`.
|
|
114
|
+
2. Loads schema, fetches product metadata from the Namirasoft product API.
|
|
115
|
+
3. Cleans `./sdk/namirasoft-myproduct` (respecting `.ns-sdkg-file-keep` / `.ns-sdkg-dir-keep` / `.ns-sdkg-dir-deep`).
|
|
116
|
+
4. Writes `package.json`, downloaded templates, `src/` tree, then runs `tsc` in the destination.
|
|
117
|
+
|
|
118
|
+
### Preserve a hand-written README and a `custom/` folder
|
|
119
|
+
|
|
120
|
+
In `<dst>/.ns-sdkg-file-keep`:
|
|
121
|
+
```
|
|
122
|
+
README.md
|
|
123
|
+
LICENSE.txt
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
In `<dst>/.ns-sdkg-dir-keep`:
|
|
127
|
+
```
|
|
128
|
+
custom
|
|
129
|
+
docs
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
After this, `ns-sdkg build npm ...` will keep those untouched while regenerating everything else.
|
|
133
|
+
|
|
134
|
+
### Add a non-Namirasoft dependency to the generated SDK
|
|
135
|
+
|
|
136
|
+
In the **source** API server's `package.json`:
|
|
137
|
+
```json
|
|
138
|
+
{
|
|
139
|
+
"ns-sdkg": {
|
|
140
|
+
"package": {
|
|
141
|
+
"dependencies": {
|
|
142
|
+
"uuid": ""
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
The generated `package.json` gets `"uuid": "^1.4.0"` (the version is forced — this hook is for Namirasoft-pinned deps; non-Namirasoft pins should be patched in a kept overlay).
|
|
150
|
+
|
|
151
|
+
### Override a meta back_end binding
|
|
152
|
+
|
|
153
|
+
```json
|
|
154
|
+
{
|
|
155
|
+
"ns-sdkg": {
|
|
156
|
+
"meta": {
|
|
157
|
+
"tables": {
|
|
158
|
+
"Invoice": {
|
|
159
|
+
"row": "InvoiceFullRow",
|
|
160
|
+
"Get": { "enabled": true, "function": "GetById", "parameters": { "id": { "type": "number" } } },
|
|
161
|
+
"List": { "enabled": false }
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
Generated `InvoiceMetaTable` will:
|
|
170
|
+
- Type the row as `InvoiceFullRow`.
|
|
171
|
+
- Bind `back_end.get = (id) => server.invoice.GetById(parseInt(id))`.
|
|
172
|
+
- Skip the `back_end.list` binding entirely.
|
|
173
|
+
|
|
174
|
+
## Common mistakes to avoid
|
|
175
|
+
|
|
176
|
+
- ❌ Editing files in a generated SDK (every file says "do not make any change to this file") — your edits vanish on the next `ns-sdkg build`. Move custom code outside the regenerated tree and add the path to `.ns-sdkg-file-keep` / `.ns-sdkg-dir-keep`.
|
|
177
|
+
- ❌ Pointing `<source>` at a directory that doesn't compile or doesn't emit `application.schema` — generation aborts after the `tsc` / `node dist/index.js` step.
|
|
178
|
+
- ❌ Mixing-case source/destination paths and expecting them preserved — `BaseBuilder` lowercases both. On Linux/macOS, pass already-lowercase paths.
|
|
179
|
+
- ❌ Importing `NPMBuilder` / `PHPBuilder` / `BaseBuilder` directly from `namirasoft-sdk-generator` in your own code — the package only exposes `index.ts` (which re-exports nothing user-facing) and the `ns-sdkg` binary.
|
|
180
|
+
- ❌ Calling `ns-sdkg git clone` before `ns-sdkg git login` — the clone command exits 1 with "Login is required before using clone."
|
|
181
|
+
- ❌ Forgetting that `ncu -u` runs against the source — your source `package.json` will get its dependency ranges rewritten on every build. Commit the bump if you don't want surprises.
|
|
182
|
+
- ❌ Hand-pinning a different version range for Namirasoft deps in the generated package — the builder hard-writes `BaseBuilder.MIN_VERSION` (`^1.4.0`) for every `namirasoft-*` dep.
|
|
183
|
+
- ❌ Tweaking output by editing this generator's `BaseBuilder.template()` paths — the function copies from `__dirname`, so templates only resolve when shipped inside `dist/`.
|
|
184
|
+
|
|
185
|
+
## Peer expectations
|
|
186
|
+
|
|
187
|
+
- **Node**: required — the binary uses `child_process.execSync` for `ncu`, `npm`, `tsc`, `node`, `git`, and on Windows `rmdir /s /q` (POSIX uses `rm -rf`). `@types/node@^25` is declared.
|
|
188
|
+
- **Tools on PATH**: `npm`, `npx`, `ncu` (`npm i -g npm-check-updates`), `tsc` (`npm i -g typescript`), `git`. PHP target additionally expects nothing at runtime (Composer commands are commented out in `PHPBuilder.onRun`), but consumers running the generated package will need `composer`.
|
|
189
|
+
- **Network**: required at build time. The builder downloads templates from `https://static.namirasoft.com/template/...` and queries `https://namirasoft.com/api/product/v1` for product metadata.
|
|
190
|
+
- **Source env vars (written by the builder)**: `.env` is overwritten with `NAMIRASOFT_MUTE="true"` and `BASE_PATH=/` before running the source — if your API server reads other env vars at boot, supply them via the shell before invoking `ns-sdkg`, or the schema-emit step will use defaults.
|
|
191
|
+
- **Peer packages**: `namirasoft-core`, `namirasoft-schema`, `namirasoft-site`, `namirasoft-api-product`, `namirasoft-node-cli`, plus `axios`. The generator does not depend on `namirasoft-account`, but the *generated* package will pull it in for account-aware APIs.
|
package/logo.png
CHANGED
|
Binary file
|
package/package.json
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
"framework": "npm",
|
|
9
9
|
"application": "package",
|
|
10
10
|
"private": false,
|
|
11
|
-
"version": "1.4.
|
|
11
|
+
"version": "1.4.62",
|
|
12
12
|
"author": "Amir Abolhasani",
|
|
13
13
|
"license": "MIT",
|
|
14
14
|
"main": "./dist/index.js",
|
|
@@ -17,9 +17,9 @@
|
|
|
17
17
|
"build": ""
|
|
18
18
|
},
|
|
19
19
|
"dependencies": {
|
|
20
|
-
"@types/node": "^25.
|
|
21
|
-
"axios": "^1.
|
|
22
|
-
"namirasoft-account": "^1.4.
|
|
20
|
+
"@types/node": "^25.9.1",
|
|
21
|
+
"axios": "^1.16.1",
|
|
22
|
+
"namirasoft-account": "^1.4.108",
|
|
23
23
|
"namirasoft-api-product": "^1.4.52",
|
|
24
24
|
"namirasoft-core": "^1.4.114",
|
|
25
25
|
"namirasoft-node-cli": "^1.4.13",
|