@adula/kit 0.2.0-alpha.1

package/build/stubs/resource_contract.txt

@@ -0,0 +1,390 @@
+import { test } from '@japa/runner'
+import User from '#models/user'
+import app from '@adonisjs/core/services/app'
+import db from '@adonisjs/lucid/services/db'
+import { kit } from '#services/kit'
+import { randomUUID } from 'node:crypto'
+import { columnName } from '@adula/kit'
+import type { Field, RecordData, Resource, SerializedRecord } from '@adula/kit'
+
+export type FixtureContext = { userId: number; orgUnitId: number; unique: string }
+export type ContractFixture = {
+  input: RecordData
+  /** Expected public values after validation; relations have separate tests. */
+  expected: SerializedRecord
+  /** Normalized database values for writable fields excluded from the response. */
+  stored?: RecordData
+  /** All live child rows after creation, ordered by ID, using public field names. */
+  inline?: Record<string, RecordData[]>
+  /** A valid update for this same record, including required validator fields. */
+  update: RecordData
+  updated: SerializedRecord
+  updatedStored?: RecordData
+  updatedInline?: Record<string, RecordData[]>
+}
+export type ResourceFixture = (
+  context: FixtureContext
+) => Promise<ContractFixture> | ContractFixture
+
+function storedValue(field: Field, value: unknown) {
+  if (!(value instanceof Date)) return value
+  return field.type === 'date'
+    ? [
+        value.getFullYear(),
+        String(value.getMonth() + 1).padStart(2, '0'),
+        String(value.getDate()).padStart(2, '0'),
+      ].join('-')
+    : value.toISOString()
+}
+
+/** Fixtures belong to the application and exercise its real validators and HTTP routes. */
+export function resourceContract(name: string, fixture: ResourceFixture) {
+  test.group(`HTTP security contract: ${name}`, (group) => {
+    let denied: User
+    let writer: User
+    let reader: User
+    let outsider: User
+    let orgUnitId: number
+    let resource: Resource
+    const base = `/resources/${name}`
+    const fresh = () => fixture({ userId: writer.id, orgUnitId, unique: randomUUID() })
+    const input = (values: RecordData) => ({ ...values, ...(resource.scoped ? { orgUnitId } : {}) })
+    const version = (row: SerializedRecord) => (resource.version ? { version: row.version } : {})
+
+    group.setup(async () => {
+      const knex = db.connection().getWriteClient()
+      const databaseInfo = await knex.raw('SELECT current_database() AS name')
+      const database = databaseInfo.rows[0].name
+      if (!app.inTest || !database.endsWith('_test'))
+        throw new Error('Resource contracts require a dedicated *_test database')
+      resource = kit().registry.get(name)
+      const suffix = randomUUID()
+      const users = []
+      for (const label of ['denied', 'writer', 'reader', 'outside']) {
+        users.push(
+          await User.create({
+            fullName: 'مستخدم الاختبار',
+            email: `${label}-${suffix}@example.test`,
+            password: 'a-long-test-password-123',
+          })
+        )
+      }
+      ;[denied, writer, reader, outsider] = users
+      const [org, outside] = await knex('org_units')
+        .insert([
+          { name: 'نطاق الاختبار', type: 'root', path: `contract_${suffix.replaceAll('-', '_')}` },
+          { name: 'نطاق آخر', type: 'root', path: `outside_${suffix.replaceAll('-', '_')}` },
+        ])
+        .returning('id')
+      orgUnitId = org.id
+      const [writeRole, readRole] = await knex('roles')
+        .insert([
+          { name: `writer-${suffix}`, permission_level: 1 },
+          { name: `reader-${suffix}`, permission_level: 0 },
+        ])
+        .returning('id')
+      await knex('role_rules').insert([
+        { role_id: writeRole.id, subject: 'all', action: 'manage' },
+        { role_id: readRole.id, subject: 'all', action: 'view' },
+      ])
+      await knex('user_roles').insert([
+        { user_id: writer.id, role_id: writeRole.id },
+        { user_id: outsider.id, role_id: writeRole.id },
+        { user_id: reader.id, role_id: readRole.id },
+      ])
+      await knex('user_org_units').insert([
+        { user_id: writer.id, org_unit_id: orgUnitId },
+        { user_id: reader.id, org_unit_id: orgUnitId },
+        { user_id: outsider.id, org_unit_id: outside.id },
+      ])
+    })
+
+    for (const [method, suffix] of [
+      ['get', ''],
+      ['get', '/create'],
+      ['get', '/999999/edit'],
+      ['get', '/999999'],
+      ['post', ''],
+      ['patch', '/999999'],
+      ['delete', '/999999'],
+      ['post', '/999999/submit'],
+      ['post', '/999999/cancel'],
+    ] as const) {
+      test(`${method.toUpperCase()} ${suffix || '/'} returns 403 without roles`, async ({
+        client,
+      }) => {
+        const response = await client[method](`${base}${suffix}`)
+          .loginAs(denied)
+          .withCsrfToken()
+          .header('Accept', 'application/json')
+        response.assertStatus(403)
+      })
+    }
+    test('resource route is protected from anonymous access', async ({ client }) => {
+      const response = await client.get(base).header('Accept', 'application/json')
+      response.assertStatus(401)
+    })
+    test('existing records enforce scope on reads and writes; central resources stay shared', async ({
+      client,
+      assert,
+    }) => {
+      const values = await fresh()
+      const created = await client
+        .post(base)
+        .loginAs(writer)
+        .withCsrfToken()
+        .header('Accept', 'application/json')
+        .json(input(values.input))
+      created.assertStatus(201)
+      const row = created.body().data
+      const visible = await client
+        .get(`${base}/${row.id}`)
+        .loginAs(writer)
+        .header('Accept', 'application/json')
+      visible.assertStatus(200)
+      assert.equal(visible.body().data.id, row.id)
+      const outside = await client
+        .get(`${base}/${row.id}`)
+        .loginAs(outsider)
+        .header('Accept', 'application/json')
+      outside.assertStatus(resource.scoped ? 404 : 200)
+      if (!resource.scoped) return
+      const listing = await client.get(base).loginAs(outsider).header('Accept', 'application/json')
+      listing.assertStatus(200)
+      assert.notInclude(
+        listing.body().data.map((entry: SerializedRecord) => entry.id),
+        row.id
+      )
+      const edit = await client
+        .get(`${base}/${row.id}/edit`)
+        .loginAs(outsider)
+        .header('Accept', 'application/json')
+      edit.assertStatus(404)
+      const changed = await client
+        .patch(`${base}/${row.id}`)
+        .loginAs(outsider)
+        .withCsrfToken()
+        .header('Accept', 'application/json')
+        .json({ ...values.update, ...version(row) })
+      changed.assertStatus(404)
+      const deleted = await client
+        .delete(`${base}/${row.id}`)
+        .loginAs(outsider)
+        .withCsrfToken()
+        .header('Accept', 'application/json')
+        .json(version(row))
+      deleted.assertStatus(404)
+      const after = await client
+        .get(`${base}/${row.id}`)
+        .loginAs(writer)
+        .header('Accept', 'application/json')
+      after.assertStatus(200)
+      assert.deepEqual(after.body().data, row)
+    })
+    test('fixture fields round-trip, private values stay hidden, updates and soft deletion persist', async ({
+      client,
+      assert,
+    }) => {
+      const values = await fresh()
+      for (const key of resource.form)
+        assert.property(values.input, key, `Missing ${name}.${key} fixture`)
+      const created = await client
+        .post(base)
+        .loginAs(writer)
+        .withCsrfToken()
+        .header('Accept', 'application/json')
+        .json(input(values.input))
+      created.assertStatus(201)
+      const row = created.body().data
+      assert.isNumber(row.id)
+      for (const [key, value] of Object.entries(values.expected))
+        assert.deepEqual(row[key], value, key)
+      const exposed = new Set([
+        'id',
+        ...(resource.serialize ?? [...resource.list, ...resource.show]),
+        ...(resource.scoped ? ['orgUnitId'] : []),
+        ...(resource.version ? ['version'] : []),
+        ...(resource.submittable ? ['docStatus'] : []),
+      ])
+      for (const key of Object.keys(row))
+        assert.isTrue(exposed.has(key), `Unexpected serialized field ${key}`)
+      const assertStored = async (
+        submitted: RecordData,
+        expected: SerializedRecord,
+        stored: RecordData = {},
+        inline: Record<string, RecordData[]> = {}
+      ) => {
+        const persistedRow = await db
+          .connection()
+          .getWriteClient()(name)
+          .where('id', row.id)
+          .first()
+        const expectations = { ...expected, ...stored }
+        for (const key of Object.keys(submitted)) {
+          if (!resource.form.includes(key)) continue
+          const field = resource.fields[key]
+          if (field.type === 'hasMany') {
+            assert.property(inline, key, `Missing expected ${name}.${key} child rows`)
+            const child = kit().registry.get(field.resource)
+            const foreignKey = child.fields[field.foreignKey].column ?? columnName(field.foreignKey)
+            const rows = await db
+              .connection()
+              .getWriteClient()(child.name)
+              .where(foreignKey, row.id)
+              .whereNull('deleted_at')
+              .orderBy('id')
+            assert.lengthOf(rows, inline[key].length)
+            for (const [index, entry] of inline[key].entries()) {
+              for (const childKey of child.form.filter((entryKey) => entryKey !== field.foreignKey))
+                assert.property(entry, childKey, `Missing expected ${field.resource}.${childKey}`)
+              for (const [childKey, value] of Object.entries(entry)) {
+                const childField = child.fields[childKey]
+                assert.exists(childField, `Unknown expected child field ${childKey}`)
+                assert.deepEqual(
+                  storedValue(childField, rows[index][childField.column ?? columnName(childKey)]),
+                  value
+                )
+              }
+            }
+          } else {
+            assert.property(expectations, key, `Missing stored ${name}.${key} expectation`)
+            if (exposed.has(key))
+              assert.property(expected, key, `Missing public ${name}.${key} expectation`)
+            assert.deepEqual(
+              storedValue(field, persistedRow[field.column ?? columnName(key)]),
+              expectations[key],
+              key
+            )
+          }
+        }
+      }
+      await assertStored(values.input, values.expected, values.stored, values.inline)
+      const shown = await client
+        .get(`${base}/${row.id}`)
+        .loginAs(reader)
+        .header('Accept', 'application/json')
+      shown.assertStatus(200)
+      for (const [key, field] of Object.entries(resource.fields)) {
+        if (field.permissionLevel || resource.hidden?.includes(key))
+          assert.notProperty(shown.body().data, key)
+      }
+      for (const key of ['createdBy', 'updatedBy', 'deletedAt', 'orgPath', 'searchVector']) {
+        const invalid = await client
+          .patch(`${base}/${row.id}`)
+          .loginAs(writer)
+          .withCsrfToken()
+          .header('Accept', 'application/json')
+          .json({ ...values.update, ...version(row), [key]: writer.id })
+        invalid.assertStatus(422)
+        assert.equal(invalid.body().error.code, 'E_FIELD_NOT_WRITABLE')
+      }
+      const updated = await client
+        .patch(`${base}/${row.id}`)
+        .loginAs(writer)
+        .withCsrfToken()
+        .header('Accept', 'application/json')
+        .json({ ...values.update, ...version(row) })
+      updated.assertStatus(200)
+      for (const [key, value] of Object.entries(values.updated))
+        assert.deepEqual(updated.body().data[key], value, key)
+      await assertStored(values.update, values.updated, values.updatedStored, values.updatedInline)
+      if (resource.version) {
+        assert.equal(updated.body().data.version, Number(row.version) + 1)
+        const stale = await client
+          .patch(`${base}/${row.id}`)
+          .loginAs(writer)
+          .withCsrfToken()
+          .header('Accept', 'application/json')
+          .json({ ...values.update, ...version(row) })
+        stale.assertStatus(409)
+      }
+      const persisted = await client
+        .get(`${base}/${row.id}`)
+        .loginAs(writer)
+        .header('Accept', 'application/json')
+      persisted.assertStatus(200)
+      assert.deepEqual(persisted.body().data, updated.body().data)
+      const removed = await client
+        .delete(`${base}/${row.id}`)
+        .loginAs(writer)
+        .withCsrfToken()
+        .header('Accept', 'application/json')
+        .json(version(updated.body().data))
+      removed.assertStatus(200)
+      const stored = await db.connection().getWriteClient()(name).where('id', row.id).first()
+      assert.exists(stored.deleted_at)
+      assert.equal(stored.created_by, writer.id)
+      const missing = await client
+        .get(`${base}/${row.id}`)
+        .loginAs(writer)
+        .header('Accept', 'application/json')
+      missing.assertStatus(404)
+    })
+    test('unique constraints reject duplicates and allow reuse after soft deletion', async ({
+      client,
+      assert,
+    }) => {
+      const keys = Object.entries(resource.fields).filter(([, field]) => field.unique)
+      if (!keys.length) return
+      const values = await fresh()
+      const created = await client
+        .post(base)
+        .loginAs(writer)
+        .withCsrfToken()
+        .header('Accept', 'application/json')
+        .json(input(values.input))
+      created.assertStatus(201)
+      const row = created.body().data
+      const knex = db.connection().getWriteClient()
+      const stored = await knex(name).where('id', row.id).first()
+      const distinct = await fresh()
+      const second = await client
+        .post(base)
+        .loginAs(writer)
+        .withCsrfToken()
+        .header('Accept', 'application/json')
+        .json(input(distinct.input))
+      second.assertStatus(201)
+      // Read-only sequence values also require real PostgreSQL uniqueness assertions.
+      for (const [key, field] of keys) {
+        const column = field.column ?? columnName(key)
+        assert.isNotNull(stored[column], `Missing unique fixture ${key}`)
+        await assert.rejects(
+          () =>
+            knex(name)
+              .where('id', second.body().data.id)
+              .update({ [column]: stored[column] }),
+          /duplicate key/
+        )
+      }
+      for (const [key, field] of keys) {
+        if (field.sequence || !resource.form.includes(key)) continue
+        const other = await fresh()
+        const rejected = await client
+          .post(base)
+          .loginAs(writer)
+          .withCsrfToken()
+          .header('Accept', 'application/json')
+          .json(input({ ...other.input, [key]: values.input[key] }))
+        rejected.assertStatus(409)
+        assert.equal(rejected.body().error.code, 'E_DUPLICATE')
+      }
+      const removed = await client
+        .delete(`${base}/${row.id}`)
+        .loginAs(writer)
+        .withCsrfToken()
+        .header('Accept', 'application/json')
+        .json(version(row))
+      removed.assertStatus(200)
+      for (const [key, field] of keys) {
+        const column = field.column ?? columnName(key)
+        assert.equal(
+          await knex(name)
+            .where('id', second.body().data.id)
+            .update({ [column]: stored[column] }),
+          1
+        )
+      }
+    })
+  })
+}

package/build/stubs/routes.stub

@@ -0,0 +1,16 @@
+{{{ exports({ to: app.makePath('start/kit_routes.ts') }) }}}
+import router from '@adonisjs/core/services/router'
+import { middleware } from '#start/kernel'
+const ResourcesController = () => import('#controllers/resources_controller')
+
+router.group(() => {
+  router.get('/resources/:resource', [ResourcesController, 'index'])
+  router.get('/resources/:resource/create', [ResourcesController, 'create'])
+  router.get('/resources/:resource/:id/edit', [ResourcesController, 'edit'])
+  router.get('/resources/:resource/:id', [ResourcesController, 'show'])
+  router.post('/resources/:resource', [ResourcesController, 'store'])
+  router.patch('/resources/:resource/:id', [ResourcesController, 'update'])
+  router.delete('/resources/:resource/:id', [ResourcesController, 'destroy'])
+  router.post('/resources/:resource/:id/submit', [ResourcesController, 'submit'])
+  router.post('/resources/:resource/:id/cancel', [ResourcesController, 'cancel'])
+}).use(middleware.auth())

package/build/stubs/service.stub

@@ -0,0 +1,9 @@
+{{{ exports({ to: app.makePath('app/services/kit.ts') }) }}}
+import db from '@adonisjs/lucid/services/db'
+import { ActorStore, ResourceService } from '@adula/kit'
+import { registry } from '#start/modules'
+
+export function kit() {
+  const knex = db.connection().getWriteClient()
+  return { registry, resources: new ResourceService(knex, registry), actors: new ActorStore(knex, registry) }
+}

package/package.json

@@ -0,0 +1,104 @@
+{
+  "name": "@adula/kit",
+  "description": "Resource-driven business applications for AdonisJS 7",
+  "version": "0.2.0-alpha.1",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "type": "module",
+  "files": [
+    "build",
+    "!build/bin",
+    "!build/tests"
+  ],
+  "main": "build/index.js",
+  "exports": {
+    ".": "./build/index.js",
+    "./types": "./build/src/resource/types.js",
+    "./auth": "./build/src/auth/ability.js",
+    "./mcp": "./build/src/mcp/tools.js",
+    "./provider": "./build/providers/kit_provider.js",
+    "./commands": "./build/commands/main.js",
+    "./eslint": "./build/src/eslint/index.js",
+    "./migrations/*": "./build/database/migrations/*.js",
+    "./package.json": "./package.json"
+  },
+  "keywords": [
+    "adonisjs",
+    "business-applications",
+    "arabic",
+    "rtl",
+    "postgresql",
+    "authorization"
+  ],
+  "author": "adula contributors",
+  "license": "MIT",
+  "devDependencies": {
+    "@adonisjs/assembler": "8.5.0",
+    "@adonisjs/core": "7.5.0",
+    "@adonisjs/drive": "4.0.0",
+    "@adonisjs/eslint-config": "3.1.0",
+    "@adonisjs/lucid": "22.4.2",
+    "@adonisjs/tsconfig": "2.0.0",
+    "@japa/assert": "4.2.0",
+    "@japa/runner": "5.3.0",
+    "@jrmc/adonis-mcp": "2.0.0",
+    "@poppinss/ts-exec": "1.4.4",
+    "@types/node": "26.2.0",
+    "@ucast/sql": "0.2.0",
+    "eslint": "10.9.0",
+    "pg": "8.16.3",
+    "typescript": "6.0.3"
+  },
+  "peerDependencies": {
+    "@adonisjs/assembler": "^8.5.0",
+    "@adonisjs/core": "^7.0.0",
+    "@adonisjs/drive": "^4.0.0",
+    "@adonisjs/lucid": "^22.0.0",
+    "@jrmc/adonis-mcp": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@jrmc/adonis-mcp": {
+      "optional": true
+    },
+    "@adonisjs/assembler": {
+      "optional": true
+    },
+    "@adonisjs/drive": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "c8": {
+    "reporter": [
+      "text",
+      "html"
+    ],
+    "exclude": [
+      "tests/**"
+    ]
+  },
+  "prettier": "@adonisjs/prettier-config",
+  "dependencies": {
+    "@casl/ability": "7.0.1",
+    "knex": "3.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adulash/adula-kit.git",
+    "directory": "packages/kit"
+  },
+  "homepage": "https://github.com/adulash/adula-kit/tree/main/packages/kit#readme",
+  "bugs": {
+    "url": "https://github.com/adulash/adula-kit/issues"
+  },
+  "scripts": {
+    "build": "node ../../scripts/clean-kit-build.mjs && tsc -p tsconfig.build.json && node ../../scripts/copy-kit-assets.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import=@poppinss/ts-exec bin/test.ts",
+    "lint": "eslint src providers commands database tests index.ts"
+  }
+}