@adula/kit 0.2.0-alpha.1

package/LICENSE.md

@@ -0,0 +1,10 @@
+# The MIT License
+
+Copyright (c) 2023
+Copyright (c) 2026 adula contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,31 @@
+# @adula/kit
+
+Unreleased 0.2.0-alpha.1 resource framework for AdonisJS 7 and PostgreSQL 17. Node 24 or later is required. MIT licensed. The target is the complete approved 1.0 scope; it has not passed acceptance.
+
+## Install into a consumer
+
+Follow the canonical [installation guide](https://github.com/adulash/adula-kit/blob/main/docs/installation.md). For a new application, the separate `@adula/create-app` initializer installs the AdonisJS host and application screens from an empty directory; it is available locally until publication. For an existing official AdonisJS 7 React/PostgreSQL application, install the kit/UI archives and documented UI prerequisites, configure the kit, migrate and create the intended administrator before `node ace adula:install`. The Ace command completes initialization inside that host. No educational customers/orders/tasks modules are installed by either path.
+
+The managed rules require the bundled `.agents/skills/adula-frontend-design/SKILL.md` for UI work. It is tailored to business workflows, asks for missing company identity at project kickoff, and uses project-owned shadcn components with modal forms and record details by default. User-requested presentation exceptions remain supported. Company identity belongs in `docs/design-identity.md`, which installation never overwrites. Doctor verifies the design skill along with the idea-review skill.
+
+## Contracts
+
+`defineResource` declares fields, forms, serialization, actions and scope. `ResourceRegistry` validates module ownership and dependencies. `ResourceService` applies CASL and organizational scope to JSON operations, serialization, editor options and atomic inline reconciliation. Money is a canonical string of integer minor units within PostgreSQL bigint range; calendar dates are YYYY-MM-DD; timestamps are canonical UTC ISO strings with milliseconds. Versioned updates require the current version and stale writes return 409.
+
+Use `buildAbility(rules, registry.all())` for schema-aware money conditions. The SQL adapter rejects ordered money predicates without schemas. Browser code may import the same matcher through `@adula/kit/auth`. Organizational restrictions remain a separate AND condition.
+
+Other exports include `ActorStore`, schema helpers, organizational moves, settings, sequences, notifications, jobs/outbox interfaces, packed rules and the generic controller factory. Commands include `adula:resource`, `adula:install`, `adula:doctor`, `adula:module:add`, `adula:module:remove`, `adula:ui add` and `adula:capabilities`.
+
+The optional `@adula/kit/mcp` entry exports `createResourceTools`. Install @jrmc/adonis-mcp 2.0.0 and supply an authenticated actor resolver. Cookie-authenticated MCP routes must keep CSRF protection enabled. Tool inputs cannot supply identity or organizational scope.
+
+## Generated HTTP contracts
+
+Generated tests call the copied `resourceContract(name, fixture)` helper. Extend the application-owned fixture whenever fields or validation change. Supply `input` and a valid `update`, plus `expected` and `updated` values after normalization. Every form field needs an input fixture; every written scalar needs a storage expectation. Use `stored`/`updatedStored` for writable fields excluded from the response, and `inline`/`updatedInline` for the complete live child rows in ID order. Dates use YYYY-MM-DD, timestamps canonical UTC strings, and money integer-minor-unit strings in expectations. Fixture callbacks receive `userId`, `orgUnitId` and a unique suffix for creating real related records.
+
+The harness creates database-backed roles and organization memberships, checks existing-record isolation across reads and writes, central-resource visibility, serialization, mapped storage, forbidden fields, stale versions, unique constraints and soft deletion. It refuses non-test databases. Configuration preserves existing copied helpers: consumers with the old one-argument helper must review and merge the new template before generating tests that use fixtures.
+
+Doctor measures the deployment's `storage/uploads` directory and warns above 5 decimal GB. When copied UI hashes or kit compatibility change, it inventories project pages for review. This conservative check does not prove import compatibility, completed page review or attachment restoration.
+
+## Current limitations
+
+Attachment ownership, upload/download, storage migration, authentication lifecycle/rate limiting, generic resource UI and core administration have local integration consumers and tests. Real OAuth/SMTP, full Tuyau field contracts, human/performance acceptance, XState workflows, later business features, staging/offsite restoration and a genuine minor-version consumer upgrade remain open. Submission envelopes are durable records in pending_definition state, not running workflows. See [implementation status](https://github.com/adulash/adula-kit/blob/main/docs/implementation-status.md), [gaps](https://github.com/adulash/adula-kit/blob/main/KIT_GAPS.md) and [1.0 acceptance](https://github.com/adulash/adula-kit/blob/main/docs/acceptance-1.0.md). No package has been published.

package/build/agent/AGENTS.template.md

@@ -0,0 +1,28 @@
+<!-- adula-kit:start (managed by adula:doctor — do not edit) -->
+
+# adula-kit rules
+
+A plugin is just code that has not been written yet. No abstraction before the second need.
+
+Structure
+
+1. One system. Every entity lives in app/modules/<module>. No separate "apps".
+2. Generate the resource scaffold with adula:resource and follow its typed definition. Reuse an existing project resource when available; never assume educational modules are installed.
+3. New entity: `node ace adula:resource <name> --module=<module>`, then fill the fields.
+4. Before creating an entity, check the registry. Same meaning exists → belongsTo. Never duplicate a table.
+5. A module writes only its own tables; dependency direction follows start/modules.ts, never backwards.
+6. Modules talk through events, never by importing each other's controllers. Heavy listeners go to jobs.
+7. Every resource declares `scoped` explicitly. Standard columns are generated; never edit them. Migrations follow expand/contract: never drop or rename a column in the same release that stops using it.
+8. Deletes are soft. Changeable lists come from lookups. Approvable documents use `submittable: true`.
+9. Notify via notify(), number via sequence, configure via settings. Nothing else.
+
+Security 10. Every route passes the authorize middleware. Every transformer uses `serialize` (explicit pick). 11. Never write crypto, sessions, or auth flows; use kit. 2FA and impersonation changes need a human review. 12. Never delete or weaken a test to make the build pass.
+
+UI 13. Before designing or changing any interface, read and apply `.agents/skills/adula-frontend-design/SKILL.md` (the kit's bundled frontend-design skill for business applications). At project kickoff, request the company's identity before the first design: name, logo, colors, fonts and brand guidelines when available. Reuse supplied identity, ask only for missing information, and preserve it in project-owned docs/design-identity.md. Fill the resource definition before writing a page. Override only via pages/<resource>/. 14. Compose interfaces from the project-owned shadcn/ui components in inertia/components/ui/. Use Button, Input, Select, Table, Card and the other registry primitives instead of hand-styled native controls or homemade equivalents. Semantic HTML for structure, text and form submission is allowed. Add components only via `node ace adula:ui add`, never `shadcn add`. 15. All forms (including create/edit) and row/record detail views use shadcn Dialog (modal) by default. Use ResourceSurface for resource forms/details; do not choose a standalone page, Sheet or custom overlay unless the user explicitly requests that alternative. View dialogs close on outside click; edit dialogs ask before closing by default. Honor system preferences for Gregorian, Hijri or both calendars and reduced motion. RTL by default; Arabic labels; English identifiers. Installation terminal instructions are English. Preserve explicit user exceptions and project-owned customizations.
+
+Boundaries 16. Never modify node_modules/@adula and never use patch-package (enforced by lint). Do not re-implement a kit service under another name (checked in review). 17. A limitation is recorded in KIT_GAPS.md (template inside) and reported to the developer — never worked around. 18. Only packages already in package.json. Ask before adding one. 19. New module or workflow → run the idea-review skill first. Field changes do not need it. 20. Before finishing: `npm run typecheck && npm test && node ace adula:doctor`.
+<!-- adula-kit:end -->
+
+## Project rules
+
+This is a reference consumer. Additions approved by the implementation plan are authorized.

package/build/agent/capabilities.md

@@ -0,0 +1,13 @@
+# Current capabilities
+
+Version 0.2.0-alpha.1, unreleased. Resource definitions and registry; six flat condition operators (typed limits documented in KIT_GAPS.md); CASL evaluation with structural ltree scope; JSON/Inertia resource CRUD; field contracts; keyset pagination; sequences/lookups/settings; soft deletion; optimistic concurrency; atomic inline writes/activity/outbox; deduplicated database listeners; org moves; attachment ownership/storage migration; saved views; core administration services; resource/module commands; copied shadcn UI and installation diagnostics.
+
+The reference consumer wires authentication/session lifecycle, admin screens, authorized attachments, optional MCP, Redis actor caching, a queue worker, one scheduler and backup/restore drills. Educational modules are isolated test fixtures, not installed application features. The agent ships business frontend-design and idea-review skills, company identity intake and modal defaults. Real SMTP receipt/recovery and isolated offsite local/source-S3 attachment recovery are documented in the source repository's confirmed-achievements ledger. OAuth is optional and externally unverified. Source-S3 recovery is integrated into the operational backup commands and verified directly; local Docker backup/recovery also passed; natural scheduled operation and staging remain pending; each consumer must verify its own configuration.
+
+This is not the 1.0 capability catalog. Read docs/implementation-status.md before using a planned feature.
+
+Core user invitations are available through `UserInvitations` and the `core.users/invite` permission. New standalone projects include an Arabic invitation Dialog, SMTP mail and single-use 24-hour acceptance links; recipients set their own passwords and receive no automatic roles. Configure SMTP and APP_URL, then assign business roles after acceptance. Existing consumers must merge project-owned routes/pages deliberately.
+
+Administrative mutations protect the last active administrator and the acting administrator's own access. Repeated installation repairs missing bootstrap grants. The reference settings screen controls Gregorian, Umm al-Qura Hijri or dual-calendar presentation, edit-dialog dismissal confirmation and restrained transitions. Storage and API dates stay canonical. Permission actions require confirmation and report server outcomes.
+
+The separate @adula/create-app package creates a complete application from an empty directory, including local service provisioning, fresh migrations, an administrator and company identity intake. Node/npm and Docker for the default service mode are prerequisites; existing PostgreSQL/Redis can be used instead. The creator and kit remain unpublished; use local archives until an authorized release exists.

package/build/agent/skills/adula-frontend-design/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: adula-frontend-design
+description: Design business application interfaces for adula-kit using project-owned shadcn/ui components, Arabic RTL layouts, practical data density, and modal forms and record details. Apply whenever creating or changing an operational page, form, table, dialog, or dashboard in a kit consumer.
+---
+
+# Frontend design for adula-kit
+
+This is the kit's self-contained frontend-design skill. Read it before UI work; it does not require a globally installed skill or a particular agent vendor.
+
+## Request company identity on day one
+
+At project kickoff, before the first visual design, inspect the user's brief, existing assets, theme and `docs/design-identity.md`. If the company identity has not been supplied, ask for it early in one concise Arabic request. For example:
+
+> لتطبيق هوية شركتكم من أول واجهة، زوّدني باسم الشركة وشعارها وألوانها وخطوطها المعتمدة ودليل الهوية إن وُجد. وإن لم تكن لديكم هوية جاهزة، أخبرني بذلك لنحدد اتجاهًا مناسبًا لنظام الأعمال.
+
+Use the normal conversation when requesting logo files or a brand guide; a text-only input tool cannot receive attachments. Ask only for missing items when some identity is already known. Do not request information or approval already supplied. If the user explicitly delegates brand creation or says there is no identity, propose a restrained business direction within that authorization.
+
+Record supplied identity in project-owned `docs/design-identity.md`: company/product names, local asset paths or supplied source links, color tokens, Arabic and Latin fonts if specified, logo usage, source of each decision and unresolved items. This is application content, not a kit-managed file; installation and upgrades must preserve it. Do not claim that a proposed or inferred choice came from the company's official guidelines.
+
+Apply known identity from the first interface through theme tokens, typography, logo placement and naming. Adapt inaccessible color combinations through readable pairings while retaining the brand's role and noting the decision. Do not distort logos or fetch unrelated branding. If a reply or assets are pending, continue independent work; use the existing theme or a clearly provisional neutral theme for unavoidable previews. Elapsed time is not brand approval. Incorporate supplied identity once it arrives.
+
+## Design within the application
+
+Understand the user's task, the important action and the information hierarchy. Inspect the existing theme and nearby screens before choosing typography, density, spacing and emphasis. Build a deliberate, cohesive interface using the application's tokens and Arabic typography. Prefer a restrained business interface with clear states and useful whitespace; avoid generic dashboard decoration and invented metrics. Honor a supplied design direction.
+
+## Business application priorities
+
+Optimize for repeated daily work: finding a record, understanding its status, entering accurate data and completing an authorized action. Use familiar layouts consistently across modules. A marketing landing page, experimental typography, oversized hero section or ornamental animation is not the default for an operational screen.
+
+- Tables: prioritize identifiers, meaningful names, status, dates and amounts. Align numeric values consistently, use tabular numerals, preserve searchable/filterable columns, and keep row actions predictable. Prefer useful density with readable spacing; do not replace comparable rows with decorative cards. Show totals or KPIs only when backed by actual data.
+- Forms: group related fields, order them according to the business workflow, expose required fields and format hints, distinguish editable and read-only values, and place validation beside the affected field. Use sensible existing defaults, clear save/cancel actions and visible saving/success/conflict feedback. Keep inline document items within the parent transaction.
+- Details: lead with the record identifier and current status, followed by the business facts, permitted next actions, related items and audit history when available. Do not expose hidden fields or use color as the only status indicator.
+- Appearance: reuse the application's typography and design tokens, quiet surfaces, clear borders and a restrained accent for the primary action. Reserve warning/destructive colors for their actual meaning. Avoid gradients, decorative motion, arbitrary font changes and excess whitespace that slows scanning unless the user specifically requests them.
+- Arabic and accessibility: use RTL logical spacing and Arabic labels, keep identifiers and numeric/date inputs legible with appropriate direction, maintain keyboard order and visible focus, and keep controls usable on mobile. Long forms scroll inside their Dialog rather than switching presentation automatically.
+- Operational states: provide specific Arabic loading, empty, no-results, permission-denied, validation and recoverable-error states. Distinguish an empty dataset from a failed request; never invent sample success data in a live screen.
+
+If a general frontend-design skill is also available, apply its craft within these business constraints. Do not follow its more experimental visual suggestions when they conflict with consistency, usability or the user's workflow.
+
+## Compose shadcn components
+
+Use the copied shadcn/ui primitives in `inertia/components/ui/`: Button, Input, Textarea, Select, Checkbox, Switch, Table, Card, Dialog, Alert and related components. Compose them; do not recreate controls with styled native HTML, a custom modal overlay or an unrelated component library. Semantic elements such as main, section, headings, dl and form remain appropriate for structure and submission. Hidden inputs remain appropriate for metadata.
+
+Install missing registry components with `node ace adula:ui add <component>`. Never run `shadcn add` directly or modify installed kit internals. Preserve application-owned component customizations; preview updates and merge deliberate changes.
+
+## Modal is the default
+
+Every form and every row/record detail view opens in a shadcn Dialog unless the user explicitly requests another presentation. This includes create/edit forms and custom page overrides. Do not infer a page or Sheet exception from screen size, form length or personal design preference.
+
+For resource routes, use `ResourcePage`, which selects the modal surface by default. For a custom form/detail override, wrap its content in `ResourceSurface` with a title, description and the list's `backHref`. It keeps direct URLs usable and returns to the list when dismissed. Use `presentation="page"` only for a user-requested page exception. Keep embedded line-item fields within their parent's form, not separate nested forms. Search and filter controls may stay in the list toolbar; their form element is submission structure, not a separate record form.
+
+Give every Dialog a visible DialogTitle and a useful DialogDescription. Keep long content scrollable within the viewport, Arabic RTL alignment, an accessible close control, focus containment and Escape dismissal. Use shadcn components inside the modal too. Keep validation and conflict messages inside it, preserve typed values on errors, and keep unauthorized actions absent. Do not replace server authorization with UI checks.
+
+Use `mode="view"` for details and `mode="edit"` for custom forms. Details close on outside click; editors ask for confirmation on outside click, close or Escape by default and preserve input when the user continues editing. Respect `ui.preferences` rather than rebuilding dismissal logic. Confirm permission changes and destructive actions with distinct labels, and display server rejection/success feedback. Administrative access protection must remain enforced on the server.
+
+Honor the system calendar preference: Gregorian, Umm al-Qura Hijri, or both. Reuse FieldControl/ResourceValue and the shared formatter; never store formatted Hijri text in a date column. Both mode shows two representations of one date and allows either input calendar. Keep transitions short, preserve the workspace shell and honor reduced motion. Installation terminal instructions are English for terminal compatibility; the application remains Arabic.
+
+## Verify the experience
+
+Exercise opening, filling, validation, saving, viewing details and closing. Check direct links, nested selects/popovers, keyboard focus and Escape, and a narrow mobile viewport. Test the explicit page exception when adding one. Use realistic Arabic content, inspect the rendered result, and run the project's required checks. Report which behavior was actually verified without claiming the broader visual or release acceptance gate is complete.

package/build/agent/skills/idea-review/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: idea-review
+description: Translate a new module or workflow into existing kit resources and declared extension points before writing code.
+---
+
+Read docs/decisions, the resource registry, capabilities and KIT_GAPS.md. Identify existing entities before proposing new ones. Produce a compact module blueprint with owned tables, explicit scope, dependencies, relationships, events, field visibility and acceptance tests. Classify each requirement as implemented now, a declared extension, or outside the kit. Do not design a dynamic field editor, runtime plugin loader or visual workflow editor. A user's already-approved plan authorizes its specified reference modules; do not ask to approve them again.

package/build/commands/capabilities.d.ts

@@ -0,0 +1,6 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+export default class Capabilities extends BaseCommand {
+    static commandName: string;
+    static description: string;
+    run(): Promise<void>;
+}

package/build/commands/capabilities.js

@@ -0,0 +1,9 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+import { readFile } from 'node:fs/promises';
+export default class Capabilities extends BaseCommand {
+    static commandName = 'adula:capabilities';
+    static description = 'Print implemented capabilities and current acceptance boundary';
+    async run() {
+        this.logger.log(await readFile(new URL('../agent/capabilities.md', import.meta.url), 'utf8'));
+    }
+}

package/build/commands/doctor.d.ts

@@ -0,0 +1,9 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+export default class Doctor extends BaseCommand {
+    static commandName: string;
+    static description: string;
+    static options: {
+        startApp: boolean;
+    };
+    run(): Promise<void>;
+}

package/build/commands/doctor.js

@@ -0,0 +1,32 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+import { fileURLToPath } from 'node:url';
+import { diagnose } from '../src/commands/doctor.js';
+import { diagnoseAttachments } from '../src/attachments/doctor.js';
+import { Settings } from '../src/services/settings.js';
+import { MigrationRunner } from '@adonisjs/lucid/migration';
+export default class Doctor extends BaseCommand {
+    static commandName = 'adula:doctor';
+    static description = 'Check kit ownership, installation and backup readiness';
+    static options = { startApp: true };
+    async run() {
+        const { default: db } = await import('@adonisjs/lucid/services/db');
+        const findings = await diagnose(fileURLToPath(this.app.appRoot), new Settings(db.connection().getWriteClient()), this.app.inProduction, process.env);
+        findings.push(await diagnoseAttachments(db.connection().getWriteClient()));
+        const migrations = await new MigrationRunner(db, this.app, { direction: 'up' }).getList();
+        const missing = migrations.filter((entry) => entry.status === 'corrupt');
+        const pending = migrations.filter((entry) => entry.status === 'pending');
+        findings.push({
+            check: 'database.migrations',
+            status: missing.length ? 'fail' : pending.length ? 'warn' : 'pass',
+            message: missing.length
+                ? `Applied migration files are missing: ${missing.map((entry) => entry.name).join(', ')}`
+                : pending.length
+                    ? `${pending.length} pending migrations; run migration:run after the deployment backup`
+                    : 'Migration files and database history agree',
+        });
+        for (const finding of findings)
+            this.logger.log(`${finding.status.toUpperCase()} ${finding.check}: ${finding.message}`);
+        if (findings.some((finding) => finding.status === 'fail'))
+            this.exitCode = 1;
+    }
+}

package/build/commands/gaps.d.ts

@@ -0,0 +1,12 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+/** Collects KIT_GAPS.md for reporting; nothing leaves the machine without explicit confirmation. */
+export default class Gaps extends BaseCommand {
+    static commandName: string;
+    static description: string;
+    static options: {
+        startApp: boolean;
+    };
+    action: string;
+    yes: boolean;
+    run(): Promise<void>;
+}

package/build/commands/gaps.js

@@ -0,0 +1,46 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { BaseCommand, args, flags } from '@adonisjs/core/ace';
+import { readFile } from 'node:fs/promises';
+/** Collects KIT_GAPS.md for reporting; nothing leaves the machine without explicit confirmation. */
+export default class Gaps extends BaseCommand {
+    static commandName = 'adula:gaps';
+    static description = 'Show the project gap report with private names masked before it is sent';
+    static options = { startApp: false };
+    async run() {
+        if (this.action !== 'report')
+            throw new Error('Usage: adula:gaps report [--yes]');
+        const path = this.app.makePath('KIT_GAPS.md');
+        let content;
+        try {
+            content = await readFile(path, 'utf8');
+        }
+        catch {
+            throw new Error('KIT_GAPS.md does not exist; adula:install creates it');
+        }
+        const masked = content
+            .replace(/[\w.+-]+@[\w-]+(\.[\w-]+)+/g, '<email>')
+            .replace(/https?:\/\/[^\s)]+/g, '<url>')
+            .replace(/\b(?:\d{1,3}\.){3}\d{1,3}\b/g, '<ip>');
+        const gaps = masked.match(/^## GAP-\d+.*$/gm) ?? [];
+        this.logger.info(`${gaps.length} gap(s) recorded in KIT_GAPS.md`);
+        for (const title of gaps)
+            this.logger.log(`  ${title.replace(/^## /, '')}`);
+        if (!this.yes) {
+            const confirmed = await this.prompt.confirm('Show the full masked report? Nothing is sent anywhere by this command.');
+            if (!confirmed)
+                return;
+        }
+        this.logger.log(masked);
+    }
+}
+__decorate([
+    args.string({ description: 'report' })
+], Gaps.prototype, "action", void 0);
+__decorate([
+    flags.boolean({ description: 'Print without asking for confirmation' })
+], Gaps.prototype, "yes", void 0);

package/build/commands/install.d.ts

@@ -0,0 +1,9 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+export default class Install extends BaseCommand {
+    static commandName: string;
+    static description: string;
+    static options: {
+        startApp: boolean;
+    };
+    run(): Promise<void>;
+}

package/build/commands/install.js

@@ -0,0 +1,91 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+import { readFile, writeFile, access } from 'node:fs/promises';
+import { Settings } from '../src/services/settings.js';
+import { syncAgentAssets } from '../src/commands/agent_assets.js';
+import { KIT_VERSION } from '../src/version.js';
+import { fileURLToPath } from 'node:url';
+export default class Install extends BaseCommand {
+    static commandName = 'adula:install';
+    static description = 'Install core organization, administrator role and managed agent instructions after migrations';
+    static options = { startApp: true };
+    async run() {
+        const { default: db } = await import('@adonisjs/lucid/services/db');
+        const knex = db.connection().getWriteClient();
+        const email = process.env.ADULA_ADMIN_EMAIL;
+        if (!email)
+            throw new Error('Set ADULA_ADMIN_EMAIL to an existing user email. Create the user through the official auth flow first.');
+        const user = await knex('users').where({ email }).first('id');
+        if (!user)
+            throw new Error('Administrator user does not exist. Create it using the official signup flow first.');
+        await knex.transaction(async (trx) => {
+            await trx.raw('SELECT pg_advisory_xact_lock(717011)');
+            let root = await trx('org_units').whereNull('parent_id').first();
+            if (!root) {
+                const [created] = await trx('org_units')
+                    .insert({ name: 'الجهة', type: 'root', path: 'root' })
+                    .returning('*');
+                await trx('org_units')
+                    .where('id', created.id)
+                    .update({ path: String(created.id) });
+                root = created;
+            }
+            let role = await trx('roles').where('name', 'administrator').first();
+            if (!role) {
+                const [created] = await trx('roles')
+                    .insert({ name: 'administrator', permission_level: 1 })
+                    .returning('*');
+                role = created;
+            }
+            // Repair a missing bootstrap grant even when the role already exists.
+            // The transaction lock makes repeated/concurrent installation idempotent.
+            if (!(await trx('role_rules')
+                .where({ role_id: role.id, subject: 'all', action: 'manage', inverted: false })
+                .whereNull('conditions')
+                .whereNull('fields')
+                .first()))
+                await trx('role_rules').insert({ role_id: role.id, subject: 'all', action: 'manage' });
+            if (!(await trx('user_roles')
+                .where({ user_id: user.id, role_id: role.id })
+                .whereNull('org_unit_id')
+                .first()))
+                await trx('user_roles').insert({ user_id: user.id, role_id: role.id });
+            await trx('user_org_units')
+                .insert({ user_id: user.id, org_unit_id: root.id })
+                .onConflict(['user_id', 'org_unit_id'])
+                .ignore();
+            await new Settings(trx).set('kit.version', KIT_VERSION);
+        });
+        for (const [name, content] of [
+            ['CLAUDE.md', 'Read and follow AGENTS.md.\nThe project rules are maintained there.\n'],
+            [
+                'KIT_GAPS.md',
+                '# Kit gaps\n\nRecord Needed by, Tried, Blocked because, Proposed kit change, Workaround.\n',
+            ],
+        ]) {
+            const path = this.app.makePath(name);
+            try {
+                await access(path);
+            }
+            catch {
+                await writeFile(path, content, { flag: 'wx' });
+            }
+        }
+        await syncAgentAssets(fileURLToPath(this.app.appRoot));
+        const pkg = JSON.parse(await readFile(this.app.makePath('package.json'), 'utf8'));
+        let uiInstalled = false;
+        try {
+            await access(this.app.makePath('ui.lock.json'));
+            uiInstalled = true;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (pkg.dependencies?.['@adula/ui'] && !uiInstalled) {
+            const ui = await this.kernel.exec('adula:ui', ['add', 'all']);
+            if (ui.exitCode)
+                throw new Error('UI installation failed; existing project customizations require review');
+        }
+        this.logger.success('Core installation complete. Run adula:doctor.');
+    }
+}

package/build/commands/main.d.ts

@@ -0,0 +1,6 @@
+import Doctor from './doctor.js';
+import Capabilities from './capabilities.js';
+export declare function getMetaData(): Promise<import("@adonisjs/core/types/ace").CommandMetaData[]>;
+export declare function getCommand(meta: {
+    commandName: string;
+}): Promise<typeof Capabilities | typeof Doctor | null>;

package/build/commands/main.js

@@ -0,0 +1,27 @@
+import Resource from './resource.js';
+import Doctor from './doctor.js';
+import Install from './install.js';
+import Capabilities from './capabilities.js';
+import ModuleAdd from './module_add.js';
+import ModuleRemove from './module_remove.js';
+import Ui from './ui.js';
+import StorageMigrate from './storage_migrate.js';
+const commands = [
+    Resource,
+    Doctor,
+    Install,
+    Capabilities,
+    ModuleAdd,
+    ModuleRemove,
+    Ui,
+    StorageMigrate,
+];
+export async function getMetaData() {
+    return commands.map((command) => {
+        command.boot();
+        return command.serialize();
+    });
+}
+export async function getCommand(meta) {
+    return commands.find((command) => command.commandName === meta.commandName) ?? null;
+}

package/build/commands/module_add.d.ts

@@ -0,0 +1,8 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+export default class ModuleAdd extends BaseCommand {
+    static commandName: string;
+    static description: string;
+    name: string;
+    reference: boolean;
+    run(): Promise<void>;
+}

package/build/commands/module_add.js

@@ -0,0 +1,57 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { BaseCommand, args, flags } from '@adonisjs/core/ace';
+import { mkdir, readFile, writeFile, access } from 'node:fs/promises';
+import { identifier } from '../src/resource/define_resource.js';
+import { appendMarkedItem } from '../src/commands/source_markers.js';
+export default class ModuleAdd extends BaseCommand {
+    static commandName = 'adula:module:add';
+    static description = 'Create and register an application-owned module';
+    async run() {
+        identifier(this.name);
+        if (this.app.inProduction)
+            throw new Error('Generate modules in the source checkout, not in production');
+        const path = this.app.makePath('app/modules', this.name);
+        try {
+            await access(path);
+            throw new Error(`Module directory already exists: ${this.name}`);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const indexPath = this.app.makePath('start/modules.ts');
+        const source = await readFile(indexPath, 'utf8');
+        if (!source.includes('// adula:imports'))
+            throw new Error('Module index registration markers are missing');
+        const alias = `module_${this.name}`;
+        const next = appendMarkedItem(source.replace('// adula:imports', `import ${alias} from '#modules/${this.name}/module'\n// adula:imports`), '/* adula:modules */', alias);
+        for (const directory of [
+            'models',
+            'resources',
+            'validators',
+            'migrations',
+            'factories',
+            'listeners',
+            'jobs',
+            'workflows',
+            'reports',
+            'pages',
+            'tests',
+        ])
+            await mkdir(this.app.makePath('app/modules', this.name, directory), { recursive: true });
+        await writeFile(this.app.makePath('app/modules', this.name, 'module.ts'), `import type { Module } from '@adula/kit'\n// adula:imports\nexport default { name: '${this.name}', label: { ar: '${this.name}', en: '${this.name}' }, reference: ${Boolean(this.reference)}, dependsOn: [], resources: [/* adula:resources */] } satisfies Module\n`, { flag: 'wx' });
+        await writeFile(indexPath, next);
+        this.logger.success(`Created ${this.name}. Fill bilingual labels and declare dependencies before adding resources.`);
+    }
+}
+__decorate([
+    args.string()
+], ModuleAdd.prototype, "name", void 0);
+__decorate([
+    flags.boolean({ description: 'Mark a disposable reference module' })
+], ModuleAdd.prototype, "reference", void 0);

package/build/commands/module_remove.d.ts

@@ -0,0 +1,10 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+export default class ModuleRemove extends BaseCommand {
+    static commandName: string;
+    static description: string;
+    static options: {
+        startApp: boolean;
+    };
+    name: string;
+    run(): Promise<void>;
+}

package/build/commands/module_remove.js

@@ -0,0 +1,94 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { BaseCommand, args } from '@adonisjs/core/ace';
+import { mkdir, rename, realpath, lstat, readdir } from 'node:fs/promises';
+import { dirname, join, relative, isAbsolute } from 'node:path';
+import { identifier } from '../src/resource/define_resource.js';
+export default class ModuleRemove extends BaseCommand {
+    static commandName = 'adula:module:remove';
+    static description = 'Unregister and archive a reference module; preserve its database tables';
+    static options = { startApp: true };
+    async run() {
+        identifier(this.name);
+        if (this.app.inProduction)
+            throw new Error('Remove reference modules in the source checkout, not in production');
+        const { modules } = await this.app.import('#start/modules');
+        const module = modules.find((entry) => entry.name === this.name);
+        if (!module?.reference)
+            throw new Error('Only modules explicitly marked reference: true can be removed');
+        const dependents = modules.filter((entry) => entry.dependsOn.includes(this.name));
+        if (dependents.length)
+            throw new Error(`Remove dependent reference modules first: ${dependents.map((entry) => entry.name).join(', ')}`);
+        const root = await realpath(this.app.makePath());
+        const path = this.app.makePath('app/modules', this.name);
+        const actual = await realpath(path);
+        const inside = relative(root, actual);
+        const directoryInfo = await lstat(path);
+        if (directoryInfo.isSymbolicLink() || inside.startsWith('..') || isAbsolute(inside))
+            throw new Error('Refusing to move a module outside the application');
+        const codemods = await this.createCodemods();
+        const project = await codemods.getTsMorphProject();
+        if (!project)
+            throw new Error('Module removal requires @adonisjs/assembler');
+        const source = project.addSourceFileAtPathIfExists(this.app.makePath('start/modules.ts'));
+        const imported = source.getImportDeclaration(`#modules/${this.name}/module`);
+        const alias = imported?.getDefaultImport()?.getText();
+        const declaration = source.getVariableDeclaration('modules')?.getInitializer();
+        if (!alias || !declaration || !('getElements' in declaration))
+            throw new Error('Expected a literal module registry; no files were changed');
+        const array = declaration;
+        const index = array.getElements().findIndex((element) => element.getText() === alias);
+        if (index < 0)
+            throw new Error('Module import is not a literal registry item; no files were changed');
+        array.removeElement(index);
+        imported.remove();
+        const archive = this.app.tmpPath('adula-removed', `${this.name}-${Date.now()}`);
+        await mkdir(dirname(archive), { recursive: true });
+        const archiveParent = relative(root, await realpath(dirname(archive)));
+        if (archiveParent.startsWith('..') || isAbsolute(archiveParent))
+            throw new Error('Archive must stay inside the application');
+        const moves = [];
+        const move = async (from, to) => {
+            await rename(from, to);
+            moves.push([from, to]);
+        };
+        // No delete and no database mutation. Archived source receives .bak suffixes so it is not compiled.
+        const preserve = async (directory) => {
+            for (const entry of await readdir(directory, { withFileTypes: true })) {
+                const file = join(directory, entry.name);
+                if (entry.isDirectory())
+                    await preserve(file);
+                else if (entry.isFile() && /\.(ts|tsx|js|jsx)$/.test(entry.name))
+                    await move(file, `${file}.bak`);
+            }
+        };
+        try {
+            await move(path, archive);
+            await preserve(archive);
+            for (const resource of module.resources) {
+                const testPath = this.app.makePath('tests/functional', `${identifier(resource.name)}.spec.ts`);
+                try {
+                    await move(testPath, join(archive, `${resource.name}.spec.ts.bak`));
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                }
+            }
+            await source.save();
+        }
+        catch (error) {
+            for (const [from, to] of moves.reverse())
+                await rename(to, from);
+            throw error;
+        }
+        this.logger.success(`Unregistered ${this.name}; source archived at ${archive}. Database tables and migration history were preserved.`);
+    }
+}
+__decorate([
+    args.string()
+], ModuleRemove.prototype, "name", void 0);

package/build/commands/resource.d.ts

@@ -0,0 +1,8 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+export default class Resource extends BaseCommand {
+    static commandName: string;
+    static description: string;
+    name: string;
+    module: string;
+    run(): Promise<void>;
+}