@akanjs/cli 0.0.149 → 0.0.151

package/cjs/src/guidelines/modelService/modelService.generate.json

@@ -0,0 +1,179 @@
+{
+  "title": "Model Service",
+  "description": "How to create and implement model.service.ts files in Akan.js",
+  "scans": [
+    {
+      "type": "source",
+      "description": "Service decorator implementation",
+      "path": "pkgs/@akanjs/service/src/serviceDecorators.ts"
+    },
+    {
+      "type": "source",
+      "description": "Database module implementation",
+      "path": "pkgs/@akanjs/server/src/module.ts"
+    },
+    {
+      "type": "example",
+      "description": "Simple service implementation",
+      "path": "libs/shared/lib/admin/admin.service.ts",
+      "sample": 1
+    },
+    {
+      "type": "example",
+      "description": "Complex service implementation",
+      "path": "libs/shared/lib/user/user.service.ts",
+      "sample": 1
+    },
+    {
+      "type": "example",
+      "description": "@Service decorator examples",
+      "path": "{apps,libs}/*/lib/*/*.service.ts",
+      "filterText": "@Service",
+      "sample": 2
+    },
+    {
+      "type": "example",
+      "description": "@Use decorator examples",
+      "path": "{apps,libs}/*/lib/*/*.service.ts",
+      "filterText": "@Use",
+      "sample": 2
+    },
+    {
+      "type": "example",
+      "description": "@Srv decorator examples",
+      "path": "{apps,libs}/*/lib/*/*.service.ts",
+      "filterText": "@Srv",
+      "sample": 2
+    },
+    {
+      "type": "example",
+      "description": "@Queue decorator examples",
+      "path": "{apps,libs}/*/lib/*/*.service.ts",
+      "filterText": "@Queue",
+      "sample": 1
+    },
+    {
+      "type": "example",
+      "description": "@Websocket decorator examples",
+      "path": "{apps,libs}/*/lib/*/*.service.ts",
+      "filterText": "@Websocket",
+      "sample": 1
+    },
+    {
+      "type": "example",
+      "description": "onModuleInit method examples",
+      "path": "{apps,libs}/*/lib/*/*.service.ts",
+      "filterText": "onModuleInit",
+      "sample": 2
+    },
+    {
+      "type": "example",
+      "description": "onModuleDestroy method examples",
+      "path": "{apps,libs}/*/lib/*/*.service.ts",
+      "filterText": "onModuleDestroy",
+      "sample": 1
+    },
+    {
+      "type": "example",
+      "description": "@Cron decorator examples",
+      "path": "{apps,libs}/*/lib/*/*.service.ts",
+      "filterText": "@Cron",
+      "sample": 2
+    },
+    {
+      "type": "example",
+      "description": "@Interval decorator examples",
+      "path": "{apps,libs}/*/lib/*/*.service.ts",
+      "filterText": "@Interval",
+      "sample": 1
+    },
+    {
+      "type": "example",
+      "description": "DbService _preCreate examples",
+      "path": "{apps,libs}/*/lib/*/*.service.ts",
+      "filterText": "_preCreate",
+      "sample": 1
+    },
+    {
+      "type": "example",
+      "description": "DbService _postCreate examples",
+      "path": "{apps,libs}/*/lib/*/*.service.ts",
+      "filterText": "_postCreate",
+      "sample": 1
+    },
+    {
+      "type": "example",
+      "description": "DbService _preUpdate examples",
+      "path": "{apps,libs}/*/lib/*/*.service.ts",
+      "filterText": "_preUpdate",
+      "sample": 1
+    },
+    {
+      "type": "example",
+      "description": "DbService _postUpdate examples",
+      "path": "{apps,libs}/*/lib/*/*.service.ts",
+      "filterText": "_postUpdate",
+      "sample": 1
+    },
+    {
+      "type": "example",
+      "description": "Database integration examples",
+      "path": "{apps,libs}/*/lib/*/*.service.ts",
+      "filterText": "DbService",
+      "sample": 2
+    },
+    {
+      "type": "example",
+      "description": "LogService examples",
+      "path": "{apps,libs}/*/lib/*/*.service.ts",
+      "filterText": "LogService",
+      "sample": 1
+    },
+    {
+      "type": "example",
+      "description": "Error handling examples",
+      "path": "{apps,libs}/*/lib/*/*.service.ts",
+      "filterText": "try {",
+      "sample": 1
+    },
+    {
+      "type": "example",
+      "description": "MixSrvs examples",
+      "path": "{apps,libs}/*/lib/_*/*.service.ts",
+      "filterText": "MixSrvs",
+      "sample": 1
+    }
+  ],
+  "update": {
+    "filePath": "./modelService.instruction.md",
+    "contents": [
+      "Purpose and role of model.service.ts files",
+      "Service structure and inheritance (DbService, LogService, MixSrvs)",
+      "Core decorators (@Service, @Srv, @Use, @Db, @Queue, @Websocket)",
+      "Lifecycle methods (onModuleInit, onModuleDestroy)",
+      "Scheduled tasks (@Cron, @Interval)",
+      "Database operations (CRUD, queries, search)",
+      "Customizing database operations (_preCreate, _postCreate, _preUpdate, _postUpdate, _preRemove, _postRemove)",
+      "Working with other services (dependency injection patterns)",
+      "Websocket integration (real-time features)",
+      "Queue integration (background processing)",
+      "Error handling (try/catch, domain errors)",
+      "Best practices (stateless design, single responsibility, resource management)",
+      "Integration with NestJS (module system)",
+      "Troubleshooting common issues"
+    ],
+    "rules": [
+      "Services should be stateless - use database and Redis for persistent state",
+      "Each service should follow the single responsibility principle",
+      "Use lifecycle hooks for proper resource management",
+      "Prefer dependency injection (@Srv, @Use) over direct imports",
+      "Implement proper error handling with domain-specific error classes",
+      "Use the built-in logger for consistent logging across services",
+      "Follow naming conventions for service methods",
+      "Document complex business logic with clear comments",
+      "Use hooks (_preCreate, etc.) for operation validation and transformation",
+      "Services should expose a clean API that hides implementation details"
+    ]
+  },
+  "page": "/[lang]/akanjs/(docs)/docs/module/service/page.tsx"
+}

package/cjs/src/guidelines/modelSignal/modelSignal.generate.json

@@ -0,0 +1,202 @@
+{
+  "title": "Model Signal",
+  "description": "How to create and implement model.signal.ts files in Akan.js",
+  "scans": [
+    {
+      "type": "source",
+      "description": "Core signal implementation files",
+      "path": "pkgs/@akanjs/signal/src/*.ts"
+    },
+    {
+      "type": "source",
+      "description": "Signal decorator implementation",
+      "path": "pkgs/@akanjs/signal/src/decorator/*.ts"
+    },
+    {
+      "type": "source",
+      "description": "DbSignal and other signal higher-order functions",
+      "path": "pkgs/@akanjs/signal/src/function/*.ts"
+    },
+    {
+      "type": "source",
+      "description": "Signal helper functions (resolve, emit, done, subscribe)",
+      "path": "pkgs/@akanjs/signal/src/helper/*.ts"
+    },
+    {
+      "type": "source",
+      "description": "Signal converts to nestjs module",
+      "path": "pkgs/@akanjs/server/src/module.ts"
+    },
+    {
+      "type": "example",
+      "description": "Signal converts to nestjs controller",
+      "path": "pkgs/@akanjs/server/src/controller.ts"
+    },
+    {
+      "type": "example",
+      "description": "Signal converts to nestjs resolver",
+      "path": "pkgs/@akanjs/server/src/resolver.ts"
+    },
+    {
+      "type": "example",
+      "description": "Signal converts to nestjs processor",
+      "path": "pkgs/@akanjs/server/src/processor.ts"
+    },
+    {
+      "type": "example",
+      "description": "Signal converts to nestjs websocket",
+      "path": "pkgs/@akanjs/server/src/websocket.ts"
+    },
+    {
+      "type": "example",
+      "description": "DbSignal usage examples",
+      "path": "{apps,libs}/*/lib/*/*.signal.ts",
+      "filterText": "extends DbSignal",
+      "sample": 3
+    },
+    {
+      "type": "example",
+      "description": "@Query.Public decorator examples",
+      "path": "{apps,libs}/*/lib/*/*.signal.ts",
+      "filterText": "@Query.Public",
+      "sample": 2
+    },
+    {
+      "type": "example",
+      "description": "@Query.User decorator examples",
+      "path": "{apps,libs}/*/lib/*/*.signal.ts",
+      "filterText": "@Query.User",
+      "sample": 2
+    },
+    {
+      "type": "example",
+      "description": "@Query.Admin decorator examples",
+      "path": "{apps,libs}/*/lib/*/*.signal.ts",
+      "filterText": "@Query.Admin",
+      "sample": 2
+    },
+    {
+      "type": "example",
+      "description": "@Mutation.User decorator examples",
+      "path": "{apps,libs}/*/lib/*/*.signal.ts",
+      "filterText": "@Mutation.User",
+      "sample": 2
+    },
+    {
+      "type": "example",
+      "description": "@Mutation.Admin decorator examples",
+      "path": "{apps,libs}/*/lib/*/*.signal.ts",
+      "filterText": "@Mutation.Admin",
+      "sample": 2
+    },
+    {
+      "type": "example",
+      "description": "@Message decorator examples",
+      "path": "{apps,libs}/*/lib/*/*.signal.ts",
+      "filterText": "@Message",
+      "sample": 2
+    },
+    {
+      "type": "example",
+      "description": "@Process decorator examples",
+      "path": "{apps,libs}/*/lib/*/*.signal.ts",
+      "filterText": "@Process",
+      "sample": 2
+    },
+    {
+      "type": "example",
+      "description": "@Pubsub decorator examples",
+      "path": "{apps,libs}/*/lib/*/*.signal.ts",
+      "filterText": "@Pubsub",
+      "sample": 2
+    },
+    {
+      "type": "example",
+      "description": "How to create slice signals with modelListIn<SliceName>",
+      "path": "{apps,libs}/*/lib/*/*.signal.ts",
+      "filterText": "ListIn",
+      "sample": 3
+    },
+    {
+      "type": "example",
+      "description": "How to create slice insights with modelInsightIn<SliceName>",
+      "path": "{apps,libs}/*/lib/*/*.signal.ts",
+      "filterText": "InsightIn",
+      "sample": 3
+    },
+    {
+      "type": "example",
+      "description": "Complete real-time chat implementation",
+      "path": "libs/social/lib/chatRoom/chatRoom.signal.ts",
+      "sample": 1
+    },
+    {
+      "type": "example",
+      "description": "Background processing examples",
+      "path": "apps/akasys/lib/dbBackup/dbBackup.signal.ts",
+      "sample": 1
+    },
+    {
+      "type": "example",
+      "description": "Search functionality examples",
+      "path": "libs/util/lib/_search/search.signal.ts",
+      "sample": 1
+    },
+    {
+      "type": "example",
+      "description": "API argument decorators usage",
+      "path": "{apps,libs}/*/lib/*/*.signal.ts",
+      "filterText": "@Arg",
+      "sample": 4
+    },
+    {
+      "type": "example",
+      "description": "Examples of @Self() decorator usage",
+      "path": "{apps,libs}/*/lib/*/*.signal.ts",
+      "filterText": "@Self()",
+      "sample": 3
+    },
+    {
+      "type": "example",
+      "description": "Error handling in signals",
+      "path": "{apps,libs}/*/lib/*/*.signal.ts",
+      "filterText": "try {",
+      "sample": 2
+    },
+    {
+      "type": "example",
+      "description": "Client-side signal imports",
+      "path": "{apps,libs}/*/lib/*/*.store.ts",
+      "filterText": "import {",
+      "sample": 3
+    }
+  ],
+  "update": {
+    "filePath": "./modelSignal.instruction.md",
+    "contents": [
+      "Purpose and role of model.signal.ts files",
+      "Signal class structure and core components",
+      "@Signal decorator and Signal class definition",
+      "DbSignal and other higher-order functions",
+      "Endpoint decorators (@Query, @Mutation, @Message, @Process, @Pubsub)",
+      "Parameter decorators (@Arg.Query, @Arg.Param, @Arg.Body, @Self, etc.)",
+      "Return helper functions (resolve, emit, done, subscribe)",
+      "Slice pattern for data access (modelListIn<SliceName>, modelInsightIn<SliceName>)",
+      "Client-side signal usage (direct API calls, store integration)",
+      "React component integration with signals",
+      "Real-time communication with Message and Pubsub",
+      "Background processing with Process decorator",
+      "Advanced patterns and best practices",
+      "Troubleshooting and debugging tips",
+      "Type safety and code generation"
+    ],
+    "rules": [
+      "Signal should be pure JavaScript/TypeScript, and should not use any other libraries or frameworks. It is imported and converted from both server and client side.",
+      "Always use parameter decorators (@Arg.*) for all method parameters in signals.",
+      "Always use appropriate helper functions to return data (resolve, emit, done, subscribe).",
+      "Always specify explicit return types in decorators and helper functions.",
+      "Follow consistent naming conventions for signals, especially for slice methods."
+    ]
+  },
+  "page": "/[lang]/akanjs/(docs)/docs/module/signal/page.tsx"
+}

package/cjs/src/guidelines/modelStore/modelStore.generate.json

@@ -0,0 +1,130 @@
+{
+  "title": "Model Store",
+  "description": "How to create and implement model.store.ts files in Akan.js",
+  "scans": [
+    {
+      "type": "source",
+      "description": "Core store implementation",
+      "path": "pkgs/@akanjs/store/src/stateOf.ts"
+    },
+    {
+      "type": "source",
+      "description": "Store decorator implementation",
+      "path": "pkgs/@akanjs/store/src/Store.ts"
+    },
+    {
+      "type": "source",
+      "description": "Toast decorator implementation",
+      "path": "pkgs/@akanjs/store/src/Toast.ts"
+    },
+    {
+      "type": "source",
+      "description": "Store utility functions",
+      "path": "pkgs/@akanjs/store/src/makeStore.ts"
+    },
+    {
+      "type": "example",
+      "description": "Basic store implementation examples",
+      "path": "{apps,libs}/*/lib/*/*.store.ts",
+      "filterText": "@Store",
+      "sample": 5
+    },
+    {
+      "type": "example",
+      "description": "Store examples with custom actions",
+      "path": "{apps,libs}/*/lib/*/*.store.ts",
+      "filterText": "async",
+      "sample": 5
+    },
+    {
+      "type": "example",
+      "description": "Store examples with toast notifications",
+      "path": "{apps,libs}/*/lib/*/*.store.ts",
+      "filterText": "@Toast",
+      "sample": 3
+    },
+    {
+      "type": "example",
+      "description": "Complex state management examples",
+      "path": "{apps,libs}/*/lib/*/*.store.ts",
+      "filterText": "this.pick",
+      "sample": 3
+    },
+    {
+      "type": "example",
+      "description": "Store composition examples",
+      "path": "{apps,libs}/*/lib/store.ts",
+      "filterText": "MixStore",
+      "sample": 3
+    },
+    {
+      "type": "usage",
+      "description": "Store usage in forms (Template files)",
+      "path": "{apps,libs}/*/lib/*/*.Template.ts{,x}",
+      "filterText": "st.use.modelForm",
+      "sample": 3
+    },
+    {
+      "type": "usage",
+      "description": "Store form submission examples",
+      "path": "{apps,libs}/*/lib/*/*.Template.ts{,x}",
+      "filterText": "submitModel",
+      "sample": 3
+    },
+    {
+      "type": "usage",
+      "description": "Store list rendering examples",
+      "path": "{apps,libs}/*/lib/*/*.Zone.ts{,x}",
+      "filterText": "st.use.modelList",
+      "sample": 3
+    },
+    {
+      "type": "usage",
+      "description": "Store pagination examples",
+      "path": "{apps,libs}/*/lib/*/*.Zone.ts{,x}",
+      "filterText": "setPageOf",
+      "sample": 3
+    },
+    {
+      "type": "usage",
+      "description": "Store filtering examples",
+      "path": "{apps,libs}/*/lib/*/*.Util.ts{,x}",
+      "filterText": "setQueryArgsOf",
+      "sample": 3
+    },
+    {
+      "type": "usage",
+      "description": "Store slice initialization examples",
+      "path": "{apps,libs}/*/lib/*/*.{View,Zone}.ts{,x}",
+      "filterText": "initModelList",
+      "sample": 3
+    }
+  ],
+  "update": {
+    "filePath": "./modelStore.instruction.md",
+    "contents": [
+      "Purpose and role of model.store.ts files",
+      "Store architecture overview and integration with other framework components",
+      "Basic store implementation with Store decorator and stateOf",
+      "State management: base state, custom state, and accessing state",
+      "Store actions: core CRUD operations and custom business logic",
+      "Using slices for contextual list operations",
+      "Form management: state handling, field updates, and submission",
+      "Advanced patterns: store composition, cross-store operations, optimistic updates, real-time",
+      "Best practices for naming, state management, performance, error handling, and testing",
+      "Complete example with comprehensive implementation",
+      "File structure conventions"
+    ],
+    "rules": [
+      "Include diagrams showing store architecture",
+      "Provide real-world examples for all major concepts",
+      "Explain both simple and advanced usage patterns",
+      "Cover form handling in detail",
+      "Include error handling and loading state management",
+      "Explain the relationship with model.signal.ts and GraphQL operations",
+      "Include performance optimization techniques",
+      "Provide testing strategies for stores"
+    ]
+  },
+  "page": "/[lang]/akanjs/(docs)/docs/module/store/page.tsx"
+}

package/cjs/src/guidelines/modelTemplate/modelTemplate.generate.json

@@ -0,0 +1,104 @@
+{
+  "title": "Model Template",
+  "description": "How to create and implement Model.Template.ts files in Akan.js",
+  "scans": [
+    {
+      "type": "example",
+      "description": "Model Template examples",
+      "path": "{apps,libs}/*/lib/*/*.Template.ts{,x}",
+      "sample": 5
+    },
+    {
+      "type": "usage",
+      "description": "Model Template usage in pages",
+      "path": "apps/*/app/**/page.tsx",
+      "filterText": ".Template.",
+      "sample": 3
+    },
+    {
+      "type": "usage",
+      "description": "Model Template usage in Utils",
+      "path": "{apps,libs}/*/lib/*/*.Util.tsx",
+      "filterText": ".Template.",
+      "sample": 3
+    },
+    {
+      "type": "usage",
+      "description": "Model Template usage in Zones",
+      "path": "{apps,libs}/*/lib/*/*.Zone.tsx",
+      "filterText": ".Template.",
+      "sample": 3
+    },
+    {
+      "type": "reference",
+      "description": "Form Field components",
+      "path": "libs/shared/ui/Field.tsx",
+      "sample": 5
+    },
+    {
+      "type": "reference",
+      "description": "Form validation examples",
+      "path": "{apps,libs}/*/lib/**/*.Template.tsx",
+      "filterText": "validate",
+      "sample": 3
+    },
+    {
+      "type": "reference",
+      "description": "Store integration examples",
+      "path": "{apps,libs}/*/lib/**/*.store.ts",
+      "filterText": "Form",
+      "sample": 3
+    },
+    {
+      "type": "reference",
+      "description": "Internationalization with usePage",
+      "path": "{apps,libs}/*/lib/**/usePage.{ts,tsx}",
+      "sample": 1
+    },
+    {
+      "type": "reference",
+      "description": "Integration with Model.constant.ts",
+      "path": "{apps,libs}/*/lib/**/*.constant.ts",
+      "filterText": "@Model.Input",
+      "sample": 3
+    }
+  ],
+  "update": {
+    "filePath": "./modelTemplate.instruction.md",
+    "contents": [
+      "Purpose and role of Model.Template.tsx files",
+      "File location and naming conventions",
+      "Basic structure and component patterns",
+      "Integration with store state management",
+      "Field types and form components",
+      "Form validation approaches",
+      "Internationalization with usePage",
+      "Form layout patterns and best practices",
+      "Using templates in pages, utilities, and zones",
+      "State management and lifecycle methods",
+      "Performance optimization techniques",
+      "Accessibility considerations",
+      "Common patterns and reusable components",
+      "Form state integration with database models",
+      "Troubleshooting common issues",
+      "Integration with API calls and form submission"
+    ],
+    "rules": [
+      "Model.Template.tsx is a client component, so it should include 'use client' directive",
+      "Model.Template.tsx components should accept an optional id parameter to support both creation and editing",
+      "Use Form components from the Field namespace for consistent UI and validation",
+      "Always connect form state to Zustand store via st.use.[model]Form()",
+      "Update form state using st.do.set[Field]On[Model]() actions",
+      "Use usePage() hook for internationalization of labels and messages",
+      "Implement form validation at field level when possible",
+      "Reset form state on component unmount to prevent stale data",
+      "Split complex forms into smaller, focused components",
+      "Follow accessibility best practices for all form fields",
+      "Use consistent layout patterns across the application",
+      "Provide clear validation feedback and error messages",
+      "Initialize form data from API when editing existing models",
+      "Implement proper error handling for form submissions"
+    ]
+  },
+  "page": "/[lang]/akanjs/(docs)/docs/module/template/page.tsx"
+}