@akanjs/cli 0.0.149 → 0.0.151

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

@@ -0,0 +1,135 @@
+{
+  "title": "Field Decorator",
+  "description": "How to use @Field decorators in Akan.js",
+  "scans": [
+    {
+      "type": "source",
+      "description": "Field decorator implementation",
+      "path": "pkgs/@akanjs/constant/src/fieldMeta.ts"
+    },
+    {
+      "type": "source",
+      "description": "Field options and metadata interface",
+      "path": "pkgs/@akanjs/constant/src/scalar.ts"
+    },
+    {
+      "type": "source",
+      "description": "Base enum and type definitions",
+      "path": "pkgs/@akanjs/base/src/base.ts"
+    },
+    {
+      "type": "source",
+      "description": "Scalar type definitions",
+      "path": "pkgs/@akanjs/base/src/scalar.ts"
+    },
+    {
+      "type": "source",
+      "description": "Model class metadata implementation",
+      "path": "pkgs/@akanjs/constant/src/classMeta.ts"
+    },
+    {
+      "type": "source",
+      "description": "GraphQL type generation from field metadata",
+      "path": "pkgs/@akanjs/server/src/gql.ts"
+    },
+    {
+      "type": "source",
+      "description": "MongoDB schema generation from field metadata",
+      "path": "pkgs/@akanjs/server/src/schema.ts"
+    },
+    {
+      "type": "source",
+      "description": "Search indexing based on field metadata",
+      "path": "pkgs/@akanjs/server/src/searchDaemon.ts"
+    },
+    {
+      "type": "example",
+      "description": "Examples of Field.Prop with basic options",
+      "path": "{apps,libs}/**/lib/__scalar/*/*.constant.ts",
+      "query": "/Field\\.Prop.*default/",
+      "sample": 3
+    },
+    {
+      "type": "example",
+      "description": "Examples of Field.Hidden and Field.Secret",
+      "path": "{apps,libs}/**/lib/*/*.constant.ts",
+      "query": "/Field\\.(Hidden|Secret)/",
+      "sample": 3
+    },
+    {
+      "type": "example",
+      "description": "Examples of Field.Resolve for computed properties",
+      "path": "{apps,libs}/**/lib/*/*.constant.ts",
+      "query": "/Field\\.Resolve/",
+      "sample": 2
+    },
+    {
+      "type": "example",
+      "description": "Examples of array field decorators",
+      "path": "{apps,libs}/**/lib/*/*.constant.ts",
+      "query": "/Field\\.Prop\\(\\(\\)\\s*=>\\s*\\[/",
+      "sample": 3
+    },
+    {
+      "type": "example",
+      "description": "Examples of enum usage with Field.Prop",
+      "path": "{apps,libs}/**/lib/*/*.constant.ts",
+      "query": "/Field\\.Prop.*enum:/",
+      "sample": 3
+    },
+    {
+      "type": "example",
+      "description": "Examples of text search and filter options",
+      "path": "{apps,libs}/**/lib/*/*.constant.ts",
+      "query": "/Field\\.Prop.*text:/",
+      "sample": 2
+    },
+    {
+      "type": "example",
+      "description": "Examples of validation options (min, max, minlength, etc.)",
+      "path": "{apps,libs}/**/lib/*/*.constant.ts",
+      "query": "/Field\\.Prop.*(min:|max:|minlength:|maxlength:|validate:)/",
+      "sample": 3
+    }
+  ],
+  "update": {
+    "filePath": "./fieldDecorator.instruction.md",
+    "contents": [
+      "Purpose and types of Field decorators",
+      "Basic syntax and structure",
+      "Field.Prop for standard properties",
+      "Field.Hidden for database-only fields",
+      "Field.Secret for sensitive data",
+      "Field.Resolve for computed properties",
+      "Field options reference",
+      "Working with primitive types",
+      "Working with enums",
+      "Working with arrays and nested structures",
+      "Reference fields and relationships",
+      "Date and special type handling",
+      "Validation and constraints",
+      "Search optimization",
+      "Default values and immutability",
+      "Integration with Model types",
+      "Best practices",
+      "Troubleshooting common issues"
+    ],
+    "rules": [
+      "Always use arrow function syntax for type specification: () => Type",
+      "Field type in the arrow function must match the TypeScript type",
+      "Use bracket notation for arrays: () => [Type] (not Array<Type>)",
+      "Always provide a default value for required fields",
+      "Mark sensitive fields with Field.Secret instead of Field.Prop",
+      "For nullable fields, add both { nullable: true } option and Type | null in TypeScript",
+      "When using enums, always create them with enumOf() and export both const and type",
+      "For date fields, use Date in the arrow function but Dayjs as the TypeScript type",
+      "Always specify the 'of' option when using Map type",
+      "Use text: 'search' for full-text searchable fields and text: 'filter' for filterable fields",
+      "Use immutable: true for fields that shouldn't change after creation",
+      "Array fields should have [] as the default value",
+      "Prefer Field.Resolve for computed properties instead of getters",
+      "Use Field.Hidden for internal fields that shouldn't be exposed in GraphQL"
+    ]
+  },
+  "page": "/[lang]/akanjs/(docs)/docs/codebase/field/page.tsx"
+}

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

@@ -0,0 +1,119 @@
+{
+  "title": "Akan.js Framework",
+  "description": "Comprehensive guide to the Akan.js framework architecture, concepts, and development patterns",
+  "scans": [
+    {
+      "type": "source",
+      "description": "Core framework packages",
+      "path": "pkgs/@akanjs/**/src/index.ts"
+    },
+    {
+      "type": "source",
+      "description": "Library implementations",
+      "path": "libs/*/index.ts"
+    },
+    {
+      "type": "example",
+      "description": "Application configurations",
+      "path": "apps/*/akan.config.ts",
+      "sample": 3
+    },
+    {
+      "type": "example",
+      "description": "Main application entry points",
+      "path": "apps/*/main.ts",
+      "sample": 3
+    },
+    {
+      "type": "example",
+      "description": "Client-side entry points",
+      "path": "apps/*/client.ts",
+      "sample": 3
+    },
+    {
+      "type": "example",
+      "description": "Server-side entry points",
+      "path": "apps/*/server.ts",
+      "sample": 3
+    },
+    {
+      "type": "example",
+      "description": "Model implementation patterns",
+      "path": "apps/*/lib/[!_]*/*.{constant,service,signal,store}.ts",
+      "sample": 4
+    },
+    {
+      "type": "example",
+      "description": "Component implementation patterns",
+      "path": "apps/*/lib/[!_]*/*.{View,Unit,Template,Zone}.tsx",
+      "sample": 4
+    },
+    {
+      "type": "usage",
+      "description": "Multi-environment configuration",
+      "path": "apps/*/env/*.ts",
+      "sample": 3
+    },
+    {
+      "type": "usage",
+      "description": "Routing implementation",
+      "path": "apps/*/app/**/*.tsx",
+      "sample": 3
+    },
+    {
+      "type": "usage",
+      "description": "State management with signals",
+      "path": "{apps,libs}/*/lib/[!_]*/*.signal.ts",
+      "sample": 3
+    },
+    {
+      "type": "usage",
+      "description": "Nestjs server integrations",
+      "path": "{apps,libs}/*/nest/*.ts",
+      "sample": 3
+    }
+  ],
+  "update": {
+    "filePath": "./framework.instruction.md",
+    "contents": [
+      "Introduction to Akan.js Framework",
+      "Key Features and Benefits",
+      "Architecture Overview",
+      "Environment and Configuration",
+      "Domain-Driven Development Pattern",
+      "Full-Stack Development Workflow",
+      "Model Architecture (constants, services, signals, stores)",
+      "Component Architecture (View, Unit, Template, Zone)",
+      "API Integration Pattern",
+      "State Management Pattern",
+      "Multi-Platform Support (Web, Mobile, SSR, CSR)",
+      "Type Safety and Code Generation",
+      "Internationalization (i18n) System",
+      "Security Best Practices",
+      "Deployment and CI/CD Integration",
+      "Performance Optimization Techniques",
+      "Development Tools and Commands",
+      "Database Integration Pattern",
+      "Authentication and Authorization System",
+      "File Management System",
+      "Real-time Communication Features",
+      "AI Integration and Code Generation",
+      "Testing and Quality Assurance",
+      "Best Practices and Common Patterns",
+      "Troubleshooting and Common Issues"
+    ],
+    "rules": [
+      "Emphasize the full-stack nature of the framework across all sections",
+      "Provide clear examples for each architectural pattern",
+      "Include code snippets demonstrating type safety across layers",
+      "Explain how components interact across client, server, and database",
+      "Highlight the automatic integration between layers",
+      "Provide both basic and advanced usage patterns",
+      "Include command-line examples for common development tasks",
+      "Organize content to flow from basic concepts to advanced usage",
+      "Use consistent terminology throughout the documentation",
+      "Include diagrams or visual aids to explain architectural concepts"
+    ]
+  },
+  "page": "/[lang]/akanjs/(docs)/docs/overview/page.tsx"
+}

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

@@ -0,0 +1,135 @@
+{
+  "title": "Model Constant",
+  "description": "How to create and implement model.constant.ts files in Akan.js",
+  "scans": [
+    {
+      "type": "source",
+      "description": "Model decorator implementation",
+      "path": "pkgs/@akanjs/constant/src/classMeta.ts"
+    },
+    {
+      "type": "source",
+      "description": "Field decorator implementation",
+      "path": "pkgs/@akanjs/constant/src/fieldMeta.ts"
+    },
+    {
+      "type": "source",
+      "description": "Filter implementation",
+      "path": "pkgs/@akanjs/constant/src/filterMeta.ts"
+    },
+    {
+      "type": "source",
+      "description": "via and sortOf implementations",
+      "path": "pkgs/@akanjs/constant/src/constantDecorator.ts"
+    },
+    {
+      "type": "source",
+      "description": "GraphQL schema generation",
+      "path": "pkgs/@akanjs/server/src/gql.ts"
+    },
+    {
+      "type": "source",
+      "description": "MongoDB schema generation",
+      "path": "pkgs/@akanjs/server/src/schema.ts"
+    },
+    {
+      "type": "source",
+      "description": "Query resolver implementation",
+      "path": "pkgs/@akanjs/server/src/resolver.ts"
+    },
+    {
+      "type": "source",
+      "description": "Search indexing implementation",
+      "path": "pkgs/@akanjs/server/src/searchDaemon.ts"
+    },
+    {
+      "type": "example",
+      "description": "Simple model examples",
+      "path": "{apps,libs}/*/lib/*/*.constant.ts",
+      "query": "lines < 100",
+      "sample": 3
+    },
+    {
+      "type": "example",
+      "description": "Complex models with all types",
+      "path": "{apps,libs}/*/lib/*/*.constant.ts",
+      "filterText": "@Model\\.(Input|Object|Light|Full|Filter|Summary|Insight)",
+      "sample": 3
+    },
+    {
+      "type": "example",
+      "description": "Models with enum definitions",
+      "path": "{apps,libs}/*/lib/*/*.constant.ts",
+      "filterText": "enumOf",
+      "sample": 3
+    },
+    {
+      "type": "example",
+      "description": "Models with custom Filter methods",
+      "path": "{apps,libs}/*/lib/*/*.constant.ts",
+      "filterText": "@Filter.Mongo",
+      "sample": 2
+    },
+    {
+      "type": "example",
+      "description": "Models with reference fields",
+      "path": "{apps,libs}/*/lib/*/*.constant.ts",
+      "filterText": "ref: \"",
+      "sample": 2
+    },
+    {
+      "type": "usage",
+      "description": "Usage of models in UI components",
+      "path": "{apps,libs}/*/lib/*/[A-Z]*.{Template,Unit,View}.tsx",
+      "sample": 3
+    }
+  ],
+  "update": {
+    "filePath": "./modelConstant.instruction.md",
+    "contents": [
+      "Purpose and role of model.constant.ts files",
+      "Model class hierarchy and relationships",
+      "File structure and organization conventions",
+      "Required imports and dependencies",
+      "Enum definition patterns",
+      "ModelInput implementation",
+      "ModelObject implementation",
+      "LightModel implementation",
+      "Full Model implementation",
+      "Insight Model implementation",
+      "Summary Model implementation",
+      "Filter Model implementation",
+      "Field decorators and options",
+      "Filter decorators and arguments",
+      "Inheritance with via() and sortOf()",
+      "Working with references to other models",
+      "Validation rules and constraints",
+      "Type safety considerations",
+      "Common mistakes and solutions",
+      "Best practices for maintainable models",
+      "Complete example with all model types"
+    ],
+    "rules": [
+      "Follow the model hierarchy: Input → Object → Light/Full → Filter/Summary/Insight",
+      "Always create an Input model with user-editable fields",
+      "Always create an Object model extending Input with system fields",
+      "Always create a Light model with essential fields for listings",
+      "Always create a Full model combining Object and Light models",
+      "Create Filter models with sortOf() and custom filter methods",
+      "Create Insight models for aggregation/analytics",
+      "Create Summary models for dashboards",
+      "Use consistent naming: ModelInput, ModelObject, LightModel, Model (full)",
+      "Use via() for inheritance and field selection",
+      "Mark field arrays as const with 'as const' assertion",
+      "Avoid getters, setters, and instance methods - use static methods if needed",
+      "Always use Field.Prop/Hidden/Secret/Resolve decorators",
+      "Define enums with enumOf() and export both const and type",
+      "Set appropriate field defaults, especially for arrays (empty array)",
+      "Add validation constraints (min, max, minlength, maxlength) where appropriate",
+      "Use proper reference format with { ref: 'ModelName' }",
+      "Group related models in the same file",
+      "Export all models and enums"
+    ]
+  },
+  "page": "/[lang]/akanjs/(docs)/docs/module/constant/page.tsx"
+}

package/cjs/src/guidelines/modelConstant/modelConstant.instruction.md

@@ -340,7 +340,7 @@ const drones = await this.listByName("myDrone", { sort: "alphabetical" });
 | `maxlength`  | `number`             | -       | Maximum string length                  | `@Field.Prop(()=> String, { maxlength: 30 }) title: string;`           |
 | `query`      | `object`             | -       | Query value for Summary fields         | `@Field.Prop(() => Int, { query: { status: { $ne: 'inactive' } })`     |
 | `accumulate` | `object`             | -       | Aggregation value for Insight fields   | `@Field.Prop(() => Int, { accumulate: { $sum: 1 } }) count: number;`   |
-| `example`    | `any`                | -       | Example value for API docs             | `@Field.Prop(()=> String, { example: "hello@akanjs.com" }) email;`     |
+| `example`    | `any`                | -       | Example value for API docs             | `@Field.Prop(()=> String, { example: "contact@akanjs.com" }) email;`   |
 | `of`         | `any`                | -       | Value type for Map fields              | `@Field.Prop(()=> Map, { of: Date }) readAts: Map<string, Dayjs>;`     |
 | `validate`   | `(value) => boolean` | -       | Custom validation function             | `@Field.Prop(()=> String, { validate: (v)=> v.includes("@") }) email;` |
 

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

@@ -0,0 +1,115 @@
+{
+  "title": "Model Dictionary",
+  "description": "Guidelines for creating and managing model.dictionary.ts files for multilingual support",
+  "scans": [
+    {
+      "type": "source",
+      "description": "Core dictionary library implementation",
+      "path": "pkgs/@akanjs/dictionary/src/*.ts"
+    },
+    {
+      "type": "example",
+      "description": "Dictionary type definitions and interfaces",
+      "path": "pkgs/@akanjs/dictionary/src/trans.ts",
+      "sample": 1
+    },
+    {
+      "type": "example",
+      "description": "Well-structured model dictionaries from shared libraries",
+      "path": "libs/shared/lib/*/**.dictionary.ts",
+      "sample": 3
+    },
+    {
+      "type": "example",
+      "description": "Standard model dictionaries with comprehensive field coverage",
+      "path": "{apps,libs}/*/lib/[!_]*/*.dictionary.ts",
+      "sample": 5
+    },
+    {
+      "type": "example",
+      "description": "Extended model dictionaries (user, setting, etc.)",
+      "path": "{apps,libs}/*/lib/{user,setting}/*.dictionary.ts",
+      "sample": 2
+    },
+    {
+      "type": "example",
+      "description": "Examples of summary dictionaries",
+      "path": "{apps,libs}/*/lib/[!_]*/*.dictionary.ts",
+      "filterText": "SummaryDictionary",
+      "sample": 2
+    },
+    {
+      "type": "example",
+      "description": "Examples of enum translations",
+      "path": "{apps,libs}/*/lib/[!_]*/*.dictionary.ts",
+      "filterText": "enum-",
+      "sample": 3
+    },
+    {
+      "type": "usage",
+      "description": "Frontend usage with usePage hook",
+      "path": "{apps,libs}/*/lib/[!_]*/*.tsx",
+      "filterText": "usePage();",
+      "sample": 2
+    },
+    {
+      "type": "usage",
+      "description": "Frontend usage accessing translations",
+      "path": "{apps,libs}/*/lib/[!_]*/*.tsx",
+      "filterText": "l(",
+      "sample": 2
+    },
+    {
+      "type": "usage",
+      "description": "Backend error handling with translation keys",
+      "path": "{apps,libs}/*/lib/[!_]*/*.{document,service}.ts",
+      "filterText": "throw new Revert",
+      "sample": 2
+    },
+    {
+      "type": "usage",
+      "description": "Dictionary validation in development",
+      "path": "pkgs/@akanjs/dictionary/src/trans.ts",
+      "filterText": "checkDictCoverage",
+      "sample": 1
+    }
+  ],
+  "update": {
+    "filePath": "./modelDictionary.instruction.md",
+    "contents": [
+      "Purpose and benefits of model.dictionary.ts files",
+      "Complete file structure with all sections",
+      "Translation key conventions and naming patterns",
+      "How to add Model field translations (standard fields)",
+      "How to add field descriptions (desc- entries)",
+      "How to add Summary translations (aggregated metrics)",
+      "How to add Signal/API endpoint translations",
+      "How to add Filter query translations",
+      "How to add Enum value translations and descriptions",
+      "How to add custom UI text translations",
+      "Working with Extended models (user, setting, summary)",
+      "Validation rules and automated dictionary checks",
+      "Manual validation checklist before commits",
+      "Common mistakes and best practices",
+      "Required imports and type safety",
+      "Full example of standard model.dictionary.ts file",
+      "Full example of extended model dictionary",
+      "Section comment format and organization best practices",
+      "Language order consistency requirements",
+      "Using the dictionary in frontend components",
+      "Using the dictionary for backend error messages"
+    ],
+    "rules": [
+      "Do not remove or change comment splitting lines. The standard format is '// * ==================== Section ==================== * //'",
+      "Field descriptions (desc-) must immediately follow their field declarations",
+      "Enum descriptions (enumdesc-) must immediately follow their enum declarations",
+      "Filter argument descriptions (qargdesc-) must immediately follow their qarg- declarations",
+      "API argument descriptions (argdesc-) must immediately follow their arg- declarations",
+      "Always maintain section organization (Model, Insight, Filter, Etc, Endpoint)",
+      "Translation arrays must follow consistent order: [English, Korean]",
+      "All examples should include proper type safety with the 'satisfies' keyword",
+      "Include recommendations for running 'akan dict:check' before commits"
+    ]
+  },
+  "page": "/[lang]/akanjs/(docs)/docs/module/dictionary/page.tsx"
+}

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

@@ -0,0 +1,129 @@
+{
+  "title": "Model Document",
+  "description": "How to create and implement model.document.ts files in Akan.js",
+  "scans": [
+    {
+      "type": "source",
+      "description": "Database decorator implementation",
+      "path": "pkgs/@akanjs/document/src/dbDecorators.ts"
+    },
+    {
+      "type": "source",
+      "description": "Model loader implementation",
+      "path": "pkgs/@akanjs/document/src/dataLoader.ts"
+    },
+    {
+      "type": "source",
+      "description": "Database model implementation",
+      "path": "pkgs/@akanjs/document/src/database.ts"
+    },
+    {
+      "type": "example",
+      "description": "Simple document implementation",
+      "path": "libs/shared/lib/admin/admin.document.ts",
+      "sample": 1
+    },
+    {
+      "type": "example",
+      "description": "Complex document implementation",
+      "path": "libs/shared/lib/user/user.document.ts",
+      "sample": 1
+    },
+    {
+      "type": "example",
+      "description": "Document with DataLoader example",
+      "path": "libs/mint/lib/token/token.document.ts",
+      "sample": 1
+    },
+    {
+      "type": "example",
+      "description": "Document middleware examples",
+      "path": "{apps,libs}/*/lib/*/*.document.ts",
+      "filterText": "schema.pre",
+      "sample": 2
+    },
+    {
+      "type": "example",
+      "description": "Document index examples",
+      "path": "{apps,libs}/*/lib/*/*.document.ts",
+      "filterText": "schema.index",
+      "sample": 2
+    },
+    {
+      "type": "example",
+      "description": "Document dataloader examples",
+      "path": "{apps,libs}/*/lib/*/*.document.ts",
+      "filterText": "@Loader",
+      "sample": 2
+    },
+    {
+      "type": "example",
+      "description": "Document model statics examples",
+      "path": "{apps,libs}/*/lib/*/*.document.ts",
+      "filterText": "async",
+      "sample": 3
+    },
+    {
+      "type": "example",
+      "description": "Document model methods examples",
+      "path": "{apps,libs}/*/lib/*/*.document.ts",
+      "filterText": "return this",
+      "sample": 3
+    },
+    {
+      "type": "example",
+      "description": "Cache implementation examples",
+      "path": "{apps,libs}/*/lib/*/*.document.ts",
+      "filterText": "Cache.set",
+      "sample": 2
+    },
+    {
+      "type": "example",
+      "description": "Transaction examples",
+      "path": "{apps,libs}/*/lib/*/*.document.ts",
+      "filterText": "@Transaction",
+      "sample": 1
+    },
+    {
+      "type": "example",
+      "description": "Search implementation",
+      "path": "{apps,libs}/*/lib/*/*.document.ts",
+      "filterText": "search",
+      "sample": 1
+    }
+  ],
+  "update": {
+    "filePath": "./modelDocument.instruction.md",
+    "contents": [
+      "Purpose and role of model.document.ts files",
+      "File structure and class organization",
+      "Relationship with model.constant.ts files",
+      "How to use document methods (instance methods)",
+      "How to use model statics (static methods)",
+      "How to apply middleware (lifecycle hooks)",
+      "How to define and apply indexes",
+      "How to use MongoDB model (direct access)",
+      "How to use dataloader (batching and caching)",
+      "How to use cache with Redis",
+      "How to use search with Meilisearch",
+      "Built-in model functions",
+      "Transactions and atomic operations",
+      "Integration with NestJS",
+      "Client-side usage patterns",
+      "Soft delete functionality",
+      "Error handling patterns",
+      "Optimization techniques"
+    ],
+    "rules": [
+      "Document methods are typically synchronous and return 'this' for method chaining",
+      "Model statics are typically asynchronous and return Promises",
+      "Use DataLoader for efficient relationship loading",
+      "Apply proper indexes for query patterns used in your application",
+      "Use Redis cache for frequently accessed data",
+      "Use transactions for operations that need to be atomic",
+      "Follow naming conventions for consistency",
+      "Handle errors with appropriate domain-specific error classes"
+    ]
+  },
+  "page": "/[lang]/akanjs/(docs)/docs/module/document/page.tsx"
+}