@dusted/anqst 0.1.0 → 0.1.2

package/README.md

@@ -1,136 +1,142 @@
-# AnQstGen
-
-Isolated TypeScript implementation of the `anqst` generator CLI npm package.
-
-## Build and run locally
-
-```bash
-npm install
-npm run build
-```
-
-Run directly from build output:
-
-```bash
-node dist/src/bin/anqst.js <command> [args]
-```
-
-Optional: expose the command in your shell while developing:
-
-```bash
-npm link
-# now you can run: anqst <command> [args]
-```
-
-Run via npx (preferred package workflow):
+# AnQstGen
+
+TypeScript implementation of the `anqst` CLI generator package.
+
+## Build locally
 
 ```bash
-npx @dusted/anqst <command> [args]
+npm install
+npm run build
 ```
-
-## CLI commands
-
-- `anqst instill <WidgetName>`
-  - Must be run in a directory containing `package.json`.
-  - Fails if `package.json.AnQst` already exists.
-  - Adds:
-    - `"AnQst": { "spec": "<WidgetName>.AnQst.d.ts", "generate": ["QWidget", "AngularService", "//DOM", "//node_express_ws"] }`
-    - `build` script prefix: `npx anqst build`
-    - `test` script prefix: `npx anqst test`
-  - Scaffolds `<WidgetName>.AnQst.d.ts` in project root.
-  - Installs a project-local DSL definition at `anqst-dsl/AnQst-Spec-DSL.d.ts`.
-
-- `anqst test`
-  - Reads `package.json.AnQst.spec`.
-  - Verifies the configured spec.
-  - On first error: prints readable error and exits `1`.
-  - On success: prints summary and exits `0`.
-
-- `anqst build`
-  - Reads `package.json.AnQst.spec`.
-  - Reads optional `package.json.AnQst.generate` string array to select emitted outputs:
-    - `"QWidget"` enables Qt/C++ emission and embedding flow.
-    - `"AngularService"` enables TypeScript service package emission/install.
-    - `"node_express_ws"` enables Node/Express backend bridge package emission.
-    - Empty list is valid and emits nothing.
-    - `//DOM` and `//node_express_ws` remain accepted placeholders and are ignored.
-  - Verifies and generates outputs.
-  - Writes raw outputs to `<cwd>/generated_output`:
-    - TypeScript package sources under `generated_output/npmpackage`
-    - C++ widget library sources plus CMake environment under `generated_output/<WidgetName>_QtWidget`
-    - Node/Express backend package sources under `generated_output/<WidgetName>_node_express_ws`
-  - When `"AngularService"` is enabled:
-    - Replaces installed TypeScript artifacts in `<cwd>/src/anqst-generated`.
-  - When `"QWidget"` is enabled:
-    - Writes Qt integration glue to `<cwd>/anqst-cmake/CMakeLists.txt` so Qt consumers can `add_subdirectory(...)` and link `<WidgetName>Widget`.
-    - If an Angular project is detected (`angular.json` exists), runs a production `ng build`.
-    - Embeds the built web bundle into the generated widget library under `generated_output/<WidgetName>_QtWidget/webapp/*`.
-
-- `anqst generate <specFile>`
-  - Verifies the provided spec file and generates raw output.
-  - Also applies `package.json.AnQst.generate` when `package.json` is present and contains `AnQst`.
-  - If `"AngularService"` is enabled, installs into `src/anqst-generated`.
-  - If `"QWidget"` is enabled, writes `anqst-cmake/CMakeLists.txt`.
-  - If `"node_express_ws"` is enabled, emits `generated_output/<WidgetName>_node_express_ws`.
-  - If no package config is present, defaults to emitting both QWidget and AngularService outputs.
-  - Writes to `<cwd>/generated_output`.
-
-- `anqst verify <specFile>`
-  - Verifies a spec file without generating artifacts.
-
-- `anqst clean <path> [-f|--force]`
-  - `<path>` may be absolute or relative to current working directory.
-  - Without `--force`:
-    - requires `<path>/package.json` with `AnQst.spec`
-    - removes only widget-scoped generated folders for the referenced widget.
-  - With `--force`:
-    - removes broad generated folders under `<path>` regardless of package metadata.
-  - Reports grouped cleanup results: `Deleted`, `Not found`, `Failed`.
-  - Groups with zero entries are omitted from the output.
-
-## Typical usage flow (Angular widget project)
-
+
+Run from build output:
+
+```bash
+node dist/src/bin/anqst.js <command> [args]
+```
+
+Or with npm link during development:
+
+```bash
+npm link
+anqst <command> [args]
+```
+
+## In-project contract
+
+AnQst-generated artifacts are consolidated under one project-root directory:
+
+- `./AnQst`
+
+`package.json` stores a settings path string:
+
+```json
+{
+  "AnQst": "./AnQst/<WidgetName>.settings.json"
+}
+```
+
+Settings file (`./AnQst/<WidgetName>.settings.json`) owns project-local AnQst configuration:
+
+```json
+{
+  "layoutVersion": 2,
+  "widgetName": "<WidgetName>",
+  "spec": "./AnQst/<WidgetName>.AnQst.d.ts",
+  "generate": ["QWidget", "AngularService", "node_express_ws"],
+  "widgetCategory": "AnQst Widgets"
+}
+```
+
+## CLI commands
+
+- `anqst instill <WidgetName>`
+  - Initializes `./AnQst`.
+  - Creates:
+    - `./AnQst/<WidgetName>.AnQst.d.ts`
+    - `./AnQst/<WidgetName>.settings.json`
+    - `./AnQst/.gitignore`
+    - `./AnQst/README.md`
+  - Updates `package.json`:
+    - `AnQst` string path to settings file.
+    - build hooks: `postinstall`, `prebuild`, `prestart` (all run `npx anqst build`).
+  - Updates `tsconfig.json` (when present):
+    - `compilerOptions.paths["anqst-generated/*"] = ["AnQst/generated/frontend/<WidgetName>_Angular/*"]`
+
+- `anqst test`
+  - Loads settings from `package.json.AnQst`.
+  - Verifies the configured spec.
+
+- `anqst build [--designerplugin[=true|false]]`
+  - Loads settings from `package.json.AnQst`.
+  - Verifies spec and regenerates selected targets.
+  - Writes only under `./AnQst/generated`.
+  - Removes selected target roots before regeneration (no stale generated files).
+  - If `QWidget` is enabled and `angular.json` exists:
+    - runs production Angular build
+    - embeds built web assets into generated Qt widget `webapp/`.
+  - If `--designerplugin` is enabled:
+    - requires `ANQST_WEBBASE_DIR`
+    - emits plugin sources in `./AnQst/generated/backend/cpp/qt/<WidgetName>_widget/designerPlugin`
+    - runs CMake configure/build in plugin `build/` subdir.
+
+- `anqst generate <specFile>`
+  - Verifies explicit spec and emits selected outputs.
+  - Uses package settings targets when package `AnQst` key exists, else default targets.
+
+- `anqst verify <specFile>`
+  - Verifies explicit spec only.
+
+- `anqst clean <path> [-f|--force]`
+  - Without `--force`: resolves settings under `<path>` and removes widget-scoped generated roots.
+  - With `--force`: removes `<path>/AnQst/generated`.
+  - Prints grouped cleanup summary (`Deleted`, `Not found`, `Failed`).
+
+## Generated structure
+
+```text
+<project-root>/
+  AnQst/
+    <WidgetName>.AnQst.d.ts
+    <WidgetName>.settings.json
+    .gitignore
+    README.md
+    generated/
+      frontend/
+        <WidgetName>_Angular/
+      backend/
+        node/
+          express/
+            <WidgetName>_anQst/
+        cpp/
+          cmake/
+            CMakeLists.txt
+          qt/
+            <WidgetName>_widget/
+              CMakeLists.txt
+              <WidgetName>.qrc
+              <WidgetName>.cpp
+              include/
+              webapp/
+              designerPlugin/
+                CMakeLists.txt
+                <WidgetName>DesignerPlugin.cpp
+                designerplugin.qrc
+                plugin-icon.png
+                build/
+                  <WidgetName>DesignerPlugin.(so|dylib|dll)
+      debug/
+        intermediate/
+```
+
+## Typical workflow
+
 ```bash
-# 1) in your widget project
 npx @dusted/anqst instill BurgerConstructor
-
-# 2) edit generated spec scaffold
-code BurgerConstructor.AnQst.d.ts
-
-# 3) validate spec
-npx @dusted/anqst test
 
-# 4) generate and install artifacts
+# edit spec
+code AnQst/BurgerConstructor.AnQst.d.ts
+
+npx @dusted/anqst test
 npx @dusted/anqst build
-
-# or via npm scripts enriched by instill
-npm run test
-npm run build
-```
-
-## Generated output structure
-
-When generation succeeds:
-
-- `generated_output/npmpackage/package.json`
-- `generated_output/npmpackage/index.ts`
-- `generated_output/npmpackage/services.ts`
-- `generated_output/npmpackage/types.ts`
-- `generated_output/npmpackage/index.js`
-- `generated_output/npmpackage/services.js`
-- `generated_output/npmpackage/types.js`
-- `generated_output/npmpackage/types/index.d.ts`
-- `generated_output/npmpackage/types/services.d.ts`
-- `generated_output/npmpackage/types/types.d.ts`
-- `generated_output/<WidgetName>_QtWidget/CMakeLists.txt`
-- `generated_output/<WidgetName>_QtWidget/<WidgetName>.qrc`
-- `generated_output/<WidgetName>_QtWidget/include/<WidgetName>.h`
-- `generated_output/<WidgetName>_QtWidget/include/<WidgetName>Types.h`
-- `generated_output/<WidgetName>_QtWidget/<WidgetName>.cpp`
-- `generated_output/<WidgetName>_QtWidget/webapp/*` (embedded Angular build artifacts)
-- Generated CMake links the widget library target (`<WidgetName>Widget`) against `anqstwebhostbase`.
-- `anqst-cmake/CMakeLists.txt` (consumer-facing CMake entrypoint that triggers on-demand Angular/anqst build)
-
-And after `anqst build`:
-
-- `src/anqst-generated/*` (installed TypeScript artifacts, replaced on each build)
+```