@akanjs/cli 2.2.10 → 2.2.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/cli",
-  "version": "2.2.10",
+  "version": "2.2.12",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -35,7 +35,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.2.10",
+    "akanjs": "2.2.12",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "^5.5.20",

package/templates/__scalar/__model__/__model__.abstract.md

@@ -0,0 +1,28 @@
+# Scalar Abstract
+
+## Purpose
+
+Describe the embedded value object or reusable data concept this scalar owns.
+
+## Domain Rules
+
+- Keep durable validation and meaning rules here.
+- Avoid repeating field types that are already clear in the constant file.
+
+## Data Meaning
+
+Explain the meaning of the scalar fields and when this scalar should be used.
+
+## Workflows
+
+Describe lifecycle or normalization behavior when relevant.
+
+## Agent Notes
+
+- Read this abstract before changing the scalar.
+- Update this file when validation meaning, public behavior, or reuse rules change.
+- Do not update this file for formatting-only, import-only, or style-only changes.
+
+## Related Modules
+
+- None yet.

package/templates/module/__model__.abstract.md

@@ -0,0 +1,28 @@
+# Module Abstract
+
+## Purpose
+
+Describe the business concept this module owns.
+
+## Domain Rules
+
+- Keep durable business invariants here.
+- Avoid repeating field types that are already clear in the constant file.
+
+## Data Meaning
+
+Explain the meaning of important data only when the code does not make the intent obvious.
+
+## Workflows
+
+Describe create, update, approval, deletion, state transition, or other business flows.
+
+## Agent Notes
+
+- Read this abstract before changing the module.
+- Update this file when business invariants, workflows, or public behavior change.
+- Do not update this file for formatting-only, import-only, or style-only changes.
+
+## Related Modules
+
+- None yet.

package/templates/service/__model__.abstract.md

@@ -0,0 +1,28 @@
+# Service Abstract
+
+## Purpose
+
+Describe the business workflow or integration this service owns.
+
+## Domain Rules
+
+- Keep durable business invariants here.
+- Avoid repeating implementation details already clear in the service or signal files.
+
+## Data Meaning
+
+Explain important input, output, and state meanings only when the code does not make the intent obvious.
+
+## Workflows
+
+Describe the service workflows, background jobs, external calls, or state transitions.
+
+## Agent Notes
+
+- Read this abstract before changing the service module.
+- Keep business behavior in service code and expose callable actions through signals.
+- Update this file when business invariants, workflows, or public behavior change.
+
+## Related Modules
+
+- None yet.

package/templates/workspaceRoot/.cursor/rules/akan.mdc.template

@@ -0,0 +1,26 @@
+---
+description: Akan.js workspace conventions for coding agents
+alwaysApply: true
+---
+
+# Akan.js Workspace Rules
+
+- Keep edits inside the established Akan structure: `apps/<app>`, `libs/<lib>`, `pkgs/*`, and `infra`.
+- Pages live under `apps/<app>/page`; index routes use `_index.tsx`, and nested layouts use `_layout.tsx`.
+- Database domain modules live under `lib/<model>`.
+- Service modules live under `lib/_<service>`.
+- Scalar modules live under `lib/__scalar/<scalar>`.
+- Module abstracts live beside module code as `<model>.abstract.md`, `<service>.abstract.md`, or
+  `<scalar>.abstract.md`. Read them before changing module behavior.
+- Do not hand-edit generated Akan files such as `akan.app.json`, `client.ts`, `server.ts`, generated facet indexes,
+  `lib/cnst.ts`, `lib/dict.ts`, `lib/db.ts`, `lib/srv.ts`, `lib/st.ts`, `lib/sig.ts`, `lib/useClient.ts`, or
+  `lib/useServer.ts`.
+- For new domain behavior, inspect sibling `constant`, `dictionary`, `signal`, `document`, `service`, `store`, and UI
+  module files before changing shape.
+- Update `*.abstract.md` when business invariants, workflows, or public behavior change. Do not update it for
+  formatting-only, import-only, or style-only changes.
+- Respect server/client import boundaries. Use `akanjs/server` only in server-side code and `akanjs/client` only in
+  client/page runtime code.
+- Treat `AKAN_PUBLIC_*` env vars as public values. Do not store secrets in them.
+- Verify changes with the smallest relevant command: `akan lint <target>`, `akan test <target>`, or
+  `akan build <app-name>`.

package/templates/workspaceRoot/AGENTS.md.template

@@ -0,0 +1,88 @@
+# <%= repoName %> Agent Guide
+
+This is an Akan.js workspace. Akan is convention-driven: keep business intent in the expected place and let
+the framework generate the repeated surfaces.
+
+## Workspace Layout
+
+- `apps/<app>` contains application pages, app UI, app domain modules, env files, and `akan.config.ts`.
+- `libs/<lib>` contains shared domain and utility code reused by apps.
+- `apps/<app>/page` contains file-routed pages. Index pages use `_index.tsx`; nested layouts use `_layout.tsx`.
+- `apps/<app>/lib/<model>` contains database-backed domain modules.
+- `apps/<app>/lib/_<service>` contains service modules that are not database document models.
+- `apps/<app>/lib/__scalar/<scalar>` contains reusable scalar/value types.
+- Module abstracts live beside module code as `<model>.abstract.md`, `<service>.abstract.md`, or
+  `<scalar>.abstract.md`.
+
+## Generated Files
+
+Do not hand-edit generated Akan files. Regenerate them through Akan scan, lint, start, build, or the matching
+CLI command instead.
+
+Common generated files include:
+
+- `apps/*/akan.app.json`
+- `libs/*/akan.lib.json`
+- `pkgs/*/akan.pkg.json`
+- `apps/*/client.ts`
+- `apps/*/server.ts`
+- `apps/*/lib/cnst.ts`
+- `apps/*/lib/dict.ts`
+- `apps/*/lib/db.ts`
+- `apps/*/lib/srv.ts`
+- `apps/*/lib/st.ts`
+- `apps/*/lib/sig.ts`
+- `apps/*/lib/useClient.ts`
+- `apps/*/lib/useServer.ts`
+- `apps/*/ui/index.ts`
+- `apps/*/webkit/index.ts`
+- `apps/*/srvkit/index.ts`
+- `apps/*/common/index.ts`
+- module `index.ts` and `index.tsx` files generated by scan
+
+## Domain Module Responsibilities
+
+Use the local module shape before adding a new abstraction.
+
+- `<model>.constant.ts` defines model, enum, scalar, and schema intent.
+- `<model>.abstract.md` defines business intent, domain rules, workflows, and agent notes that are not obvious
+  from code.
+- `<model>.dictionary.ts` defines labels, descriptions, messages, and i18n metadata.
+- `<model>.signal.ts` defines typed endpoint contracts.
+- `<model>.document.ts` owns persistence and document queries.
+- `<model>.service.ts` owns business logic.
+- `<model>.store.ts` owns domain state and actions.
+- `<Model>.Template.tsx` owns form-oriented UI.
+- `<Model>.Unit.tsx` owns list/item UI.
+- `<Model>.View.tsx` owns detail UI.
+- `<Model>.Zone.tsx` owns page/container integration.
+- `<model>.Util.tsx` owns small module UI helpers.
+
+## Agent Workflow
+
+1. Read the nearby module and convention before creating files. If `*.abstract.md` exists, read it first.
+2. Put new files in the established Akan location instead of adding parallel architecture.
+3. Prefer CLI generation commands for new apps, libraries, modules, scalars, pages, and generated references.
+4. Keep server-only logic out of client surfaces and client-only code out of server imports.
+5. Treat `AKAN_PUBLIC_*` env vars as public. Never put secrets in them.
+6. Add or update tests when behavior, contracts, or CLI output changes.
+7. Update `*.abstract.md` when business invariants, workflows, or public behavior change.
+8. Run the smallest relevant verification command after changes.
+
+## Common Commands
+
+Run commands from the workspace root unless a task says otherwise.
+
+```bash
+akan start <app-name>
+akan build <app-name>
+akan test <app-or-lib-or-pkg>
+akan lint <app-or-lib-or-pkg>
+akan lint-all
+```
+
+For the default generated app, start with:
+
+```bash
+akan start <%= appName %>
+```