@akanjs/cli 1.0.20 → 2.1.0-rc.0

package/guidelines/moduleOverview/moduleOverview.instruction.md

@@ -0,0 +1,31 @@
+# Module Overview Guideline
+
+## Purpose
+Use this before generating or reviewing a database module. It defines which file owns which responsibility and in what order a module should grow.
+
+## Ownership
+- `model.constant.ts` defines business data shape, model layers, enums, field options, resolved values, and small type helpers.
+- `model.dictionary.ts` defines user-facing labels, descriptions, endpoint text, slice text, errors, and UI strings.
+- `model.document.ts` defines persistence behavior: filters, document methods, model helpers, indexes, and schema hooks.
+- `model.service.ts` owns business workflows using document helpers and other services.
+- `model.signal.ts` exposes internal tasks, slices, endpoints, realtime, pubsub, guards, and resolved handlers.
+- `model.store.ts` coordinates generated fetch APIs with client state, form state, list state, and UI actions.
+- `Model.Template.tsx`, `Model.Unit.tsx`, `Model.View.tsx`, `Model.Util.tsx`, and `Model.Zone.tsx` render forms, list items, detail views, controls, and page sections.
+
+## Current Akan Patterns
+- For a new model, read and generate in this order: constant, dictionary, document, service, signal, store, UI.
+- For a list page, inspect signal slice, store, Zone, then Unit.
+- For detail or edit UI, inspect signal view/endpoint, store, Zone/View, then Template.
+- For a user action, design service behavior first, then signal endpoint, store action, and Util or Template control.
+
+## Codegen Rules
+- Generate only files needed by the requested behavior; a simple read-only feature may not need every layer.
+- Do not hide business rules inside React render functions.
+- Do not copy model shapes by hand across files; rely on generated types and helpers.
+- Keep scanner-friendly names exactly aligned with the module name and PascalCase component name.
+
+## Review Checklist
+- The instruction points to current docs pages, not removed docs routes.
+- Generated examples use current Akan builder APIs and scanner-friendly filenames.
+- The output contract tells the model which file paths to return.
+- The guide avoids broad framework essays when a concrete file rule is better.

package/guidelines/scalarConstant/scalarConstant.generate.json

@@ -0,0 +1,37 @@
+{
+  "title": "Scalar Constant",
+  "description": "Scalar constant generation rules",
+  "group": "scalar",
+  "docsSource": "apps/angelo/page/akanjs/(docs)/conventions/scalar/constant.tsx",
+  "codegenPriority": 1,
+  "deprecated": false,
+  "scans": [
+    {
+      "type": "docs",
+      "description": "Current docs source for Scalar Constant",
+      "path": "apps/angelo/page/akanjs/(docs)/conventions/scalar/constant.tsx"
+    },
+    {
+      "type": "example",
+      "description": "Existing Akan implementation examples",
+      "path": "{apps,libs}/*/lib/**/*.ts",
+      "sample": 4
+    }
+  ],
+  "update": {
+    "filePath": "./scalarConstant.instruction.md",
+    "contents": [
+      "purpose",
+      "file ownership",
+      "current API patterns",
+      "codegen rules",
+      "validation checklist"
+    ],
+    "rules": [
+      "Use current Akan APIs only",
+      "Keep output parseable for codegen",
+      "Include ownership boundaries and review checklist"
+    ]
+  },
+  "page": "apps/angelo/page/akanjs/(docs)/conventions/scalar/constant.tsx"
+}

package/guidelines/scalarConstant/scalarConstant.instruction.md

@@ -0,0 +1,28 @@
+# scalar.constant.ts Guideline
+
+## Purpose
+Generate reusable embedded value objects. A scalar constant should be small, typed, easy to embed, and understandable without the parent model.
+
+## Ownership
+- Define one PascalCase scalar class with `via((field) => ({ ... }))`.
+- Use base types, enum classes, other scalar classes, and arrays as needed.
+- Use `.optional()` when absence is valid for that value object.
+- Use pure instance methods only when they describe the value itself and do not need persistence.
+
+## Current Akan Patterns
+- Use defaults for stable empty values such as zero amount, empty text, empty list, or a date factory.
+- Use enum classes for constrained categorical values that need translations.
+- Use nested scalars when composition makes the parent model clearer.
+- Keep examples representative because API docs and AI generation rely on them.
+
+## Codegen Rules
+- Do not include collection-level queries, service calls, signal endpoints, or store state.
+- Do not create a scalar when the object needs its own identity and lifecycle.
+- Do not overfit scalar names to one parent model if the value object is reusable.
+- Every public field should be covered by scalar dictionary text.
+
+## Review Checklist
+- The instruction points to current docs pages, not removed docs routes.
+- Generated examples use current Akan builder APIs and scanner-friendly filenames.
+- The output contract tells the model which file paths to return.
+- The guide avoids broad framework essays when a concrete file rule is better.

package/guidelines/scalarDictionary/scalarDictionary.generate.json

@@ -0,0 +1,37 @@
+{
+  "title": "Scalar Dictionary",
+  "description": "Scalar dictionary generation rules",
+  "group": "scalar",
+  "docsSource": "apps/angelo/page/akanjs/(docs)/conventions/scalar/dictionary.tsx",
+  "codegenPriority": 1,
+  "deprecated": false,
+  "scans": [
+    {
+      "type": "docs",
+      "description": "Current docs source for Scalar Dictionary",
+      "path": "apps/angelo/page/akanjs/(docs)/conventions/scalar/dictionary.tsx"
+    },
+    {
+      "type": "example",
+      "description": "Existing Akan implementation examples",
+      "path": "{apps,libs}/*/lib/**/*.ts",
+      "sample": 4
+    }
+  ],
+  "update": {
+    "filePath": "./scalarDictionary.instruction.md",
+    "contents": [
+      "purpose",
+      "file ownership",
+      "current API patterns",
+      "codegen rules",
+      "validation checklist"
+    ],
+    "rules": [
+      "Use current Akan APIs only",
+      "Keep output parseable for codegen",
+      "Include ownership boundaries and review checklist"
+    ]
+  },
+  "page": "apps/angelo/page/akanjs/(docs)/conventions/scalar/dictionary.tsx"
+}

package/guidelines/scalarDictionary/scalarDictionary.instruction.md

@@ -0,0 +1,28 @@
+# scalar.dictionary.ts Guideline
+
+## Purpose
+Generate labels and descriptions for scalar value objects so embedded fields are readable in forms, detail views, docs, and generated API descriptions.
+
+## Ownership
+- `modelName` and `modelDesc` describe the scalar value object.
+- Each public scalar field needs a label and `desc-` description.
+- Each scalar enum value needs an enum label and enum description.
+- Scalar UI-specific text should be added only when the scalar has Template or Unit components.
+
+## Current Akan Patterns
+- Use `ModelDictionary<Scalar>` or the nearby project convention for typed scalar dictionaries.
+- Keep descriptions reusable across all parent modules that embed the scalar.
+- Use language order consistent with existing app dictionaries.
+- Avoid parent-specific wording unless the scalar is intentionally scoped to that parent.
+
+## Codegen Rules
+- Do not omit descriptions for public fields.
+- Do not define endpoint or slice keys for scalars unless a special UI integration actually uses them.
+- Do not duplicate parent model dictionary entries inside scalar dictionaries.
+- Do not leave orphan enum entries after scalar fields change.
+
+## Review Checklist
+- The instruction points to current docs pages, not removed docs routes.
+- Generated examples use current Akan builder APIs and scanner-friendly filenames.
+- The output contract tells the model which file paths to return.
+- The guide avoids broad framework essays when a concrete file rule is better.

package/guidelines/scalarModule/scalarModule.generate.json

@@ -0,0 +1,37 @@
+{
+  "title": "Scalar Module",
+  "description": "Scalar module overview rules",
+  "group": "scalar",
+  "docsSource": "apps/angelo/page/akanjs/(docs)/conventions/scalar/overview.tsx",
+  "codegenPriority": 1,
+  "deprecated": false,
+  "scans": [
+    {
+      "type": "docs",
+      "description": "Current docs source for Scalar Module",
+      "path": "apps/angelo/page/akanjs/(docs)/conventions/scalar/overview.tsx"
+    },
+    {
+      "type": "example",
+      "description": "Existing Akan implementation examples",
+      "path": "{apps,libs}/*/lib/**/*.ts",
+      "sample": 4
+    }
+  ],
+  "update": {
+    "filePath": "./scalarModule.instruction.md",
+    "contents": [
+      "purpose",
+      "file ownership",
+      "current API patterns",
+      "codegen rules",
+      "validation checklist"
+    ],
+    "rules": [
+      "Use current Akan APIs only",
+      "Keep output parseable for codegen",
+      "Include ownership boundaries and review checklist"
+    ]
+  },
+  "page": "apps/angelo/page/akanjs/(docs)/conventions/scalar/overview.tsx"
+}

package/guidelines/scalarModule/scalarModule.instruction.md

@@ -0,0 +1,29 @@
+# Scalar Module Guideline
+
+## Purpose
+Use scalar modules for small embedded value objects shared across models. Scalars are not independent collections and should not own a separate lifecycle.
+
+## Ownership
+- Scalar files live under `lib/__scalar/<scalarName>`.
+- `scalar.constant.ts` defines the value shape, enum values, defaults, and pure helpers.
+- `scalar.dictionary.ts` defines labels and descriptions for scalar fields and enum values.
+- `scalar.document.ts` is optional and only for small value helper behavior.
+- `Scalar.Template.tsx` and `Scalar.Unit.tsx` are optional reusable editor/display components.
+
+## Current Akan Patterns
+- Choose scalar for reusable embedded values such as Price, Address, ContactInfo, Coordinate, FileMeta, or DateRange.
+- Choose a normal module when the data needs its own permissions, list page, service methods, independent lifecycle, or search surface.
+- Keep scalar constants focused and composable.
+- Let the parent module decide how scalar values are saved, loaded, and exposed.
+
+## Codegen Rules
+- Do not create service, signal, or store files for scalars by default.
+- Do not embed business workflows in scalar helpers.
+- Do not duplicate the same group of fields across many modules when a scalar would make the model clearer.
+- Do not add UI files unless the scalar needs reusable input or display across modules.
+
+## Review Checklist
+- The instruction points to current docs pages, not removed docs routes.
+- Generated examples use current Akan builder APIs and scanner-friendly filenames.
+- The output contract tells the model which file paths to return.
+- The guide avoids broad framework essays when a concrete file rule is better.

package/guidelines/sharedUiUsage/sharedUiUsage.generate.json

@@ -0,0 +1,37 @@
+{
+  "title": "Shared UI Usage",
+  "description": "Shared UI usage rules",
+  "group": "core",
+  "docsSource": "apps/angelo/page/akanjs/(docs)/references/ui/overview.tsx",
+  "codegenPriority": 3,
+  "deprecated": false,
+  "scans": [
+    {
+      "type": "docs",
+      "description": "Current docs source for Shared UI Usage",
+      "path": "apps/angelo/page/akanjs/(docs)/references/ui/overview.tsx"
+    },
+    {
+      "type": "example",
+      "description": "Existing Akan implementation examples",
+      "path": "{apps,libs}/*/lib/**/*.ts",
+      "sample": 4
+    }
+  ],
+  "update": {
+    "filePath": "./sharedUiUsage.instruction.md",
+    "contents": [
+      "purpose",
+      "file ownership",
+      "current API patterns",
+      "codegen rules",
+      "validation checklist"
+    ],
+    "rules": [
+      "Use current Akan APIs only",
+      "Keep output parseable for codegen",
+      "Include ownership boundaries and review checklist"
+    ]
+  },
+  "page": "apps/angelo/page/akanjs/(docs)/references/ui/overview.tsx"
+}

package/guidelines/sharedUiUsage/sharedUiUsage.instruction.md

@@ -0,0 +1,25 @@
+# Shared UI Usage Guideline
+
+## Purpose
+Use shared UI components when building app or module UI that should stay consistent across products.
+
+## Ownership
+- Shared UI components provide reusable display, form, overlay, and layout primitives.
+- Prefer documented props and local examples before inventing new wrappers.
+- Shared UI should remain domain-neutral.
+
+## Current Akan Patterns
+- Import from the project shared UI entrypoints already used nearby.
+- Wrap shared UI only when the module needs domain-specific labels or behavior.
+- Preserve accessibility and theming assumptions from the shared component.
+
+## Codegen Rules
+- Do not copy shared UI internals into module files.
+- Do not pass unsupported props.
+- Do not make shared UI depend on one app domain.
+
+## Review Checklist
+- The instruction points to current docs pages, not removed docs routes.
+- Generated examples use current Akan builder APIs and scanner-friendly filenames.
+- The output contract tells the model which file paths to return.
+- The guide avoids broad framework essays when a concrete file rule is better.

package/guidelines/utilUiUsage/utilUiUsage.generate.json

@@ -0,0 +1,37 @@
+{
+  "title": "Util UI Usage",
+  "description": "Utility UI usage rules",
+  "group": "core",
+  "docsSource": "apps/angelo/page/akanjs/(docs)/references/ui/core.tsx",
+  "codegenPriority": 3,
+  "deprecated": false,
+  "scans": [
+    {
+      "type": "docs",
+      "description": "Current docs source for Util UI Usage",
+      "path": "apps/angelo/page/akanjs/(docs)/references/ui/core.tsx"
+    },
+    {
+      "type": "example",
+      "description": "Existing Akan implementation examples",
+      "path": "{apps,libs}/*/lib/**/*.ts",
+      "sample": 4
+    }
+  ],
+  "update": {
+    "filePath": "./utilUiUsage.instruction.md",
+    "contents": [
+      "purpose",
+      "file ownership",
+      "current API patterns",
+      "codegen rules",
+      "validation checklist"
+    ],
+    "rules": [
+      "Use current Akan APIs only",
+      "Keep output parseable for codegen",
+      "Include ownership boundaries and review checklist"
+    ]
+  },
+  "page": "apps/angelo/page/akanjs/(docs)/references/ui/core.tsx"
+}

package/guidelines/utilUiUsage/utilUiUsage.instruction.md

@@ -0,0 +1,25 @@
+# Util UI Usage Guideline
+
+## Purpose
+Use utility UI components for common application interactions, layout helpers, scrolling, loading, and small display patterns.
+
+## Ownership
+- Utility UI is for cross-domain layout and interaction helpers.
+- Module-specific controls still belong in Model.Util.
+- Docs pages may use utility UI for scroll sections and navigation.
+
+## Current Akan Patterns
+- Prefer existing utility components before adding custom layout code.
+- Keep imported utility UI usage close to nearby docs and app examples.
+- Forward className and preserve composition.
+
+## Codegen Rules
+- Do not make utility UI carry model-specific business behavior.
+- Do not duplicate util components in each module.
+- Do not use utility components without checking expected props.
+
+## Review Checklist
+- The instruction points to current docs pages, not removed docs routes.
+- Generated examples use current Akan builder APIs and scanner-friendly filenames.
+- The output contract tells the model which file paths to return.
+- The guide avoids broad framework essays when a concrete file rule is better.