@drhomet/mithaq 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,94 @@
 {
   "name": "@drhomet/mithaq",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./generate-auth": "./dist/auth/better-auth/generate.js",
+    "./generate-messages": "./dist/mithaq/generate-messages.js",
+    "./generate-screens": "./dist/screen/generate.js",
+    "./upgrade": "./dist/asas/cli/upgrade.js",
+    "./vite": "./dist/vite.js",
+    "./admin": "./dist/screen/client.js",
+    "./admin/react": "./dist/screen/react.js",
+    "./orpc": "./dist/asas/http/orpc.js",
+    "./rich-text": "./dist/rich-text/index.js",
+    "./targets": "./dist/targets.js",
+    "./drizzle": "./dist/drizzle/proxy/index.js",
+    "./drizzle/pg-core": "./dist/drizzle/proxy/pg-core.js",
+    "./drizzle/node-postgres": "./dist/drizzle/proxy/node-postgres.js"
+  },
+  "bin": {
+    "mithaq": "dist/asas/cli/mithaq.js"
+  },
+  "dependencies": {
+    "@babel/helper-validator-identifier": "^8.0.4",
+    "ajv": "8.20.0",
+    "ajv-formats": "3.0.1",
+    "drizzle-kit": "1.0.0-rc.4",
+    "drizzle-orm": "1.0.0-rc.4",
+    "jose": "6.2.12",
+    "pg": "^8.16.3",
+    "zod": "^4.6.5"
+  },
+  "peerDependencies": {
+    "@lexical/extension": "0.52.0",
+    "@lexical/link": "0.52.0",
+    "@lexical/list": "0.52.0",
+    "@lexical/rich-text": "0.52.0",
+    "@orpc/openapi": "^1.15.1",
+    "@orpc/server": "^1.15.1",
+    "better-auth": "1.7.4",
+    "lexical": "0.52.0",
+    "react": "^19.3.0",
+    "vite": ">=8"
+  },
+  "peerDependenciesMeta": {
+    "@lexical/extension": {
+      "optional": true
+    },
+    "@lexical/link": {
+      "optional": true
+    },
+    "@lexical/list": {
+      "optional": true
+    },
+    "@lexical/rich-text": {
+      "optional": true
+    },
+    "@orpc/openapi": {
+      "optional": true
+    },
+    "@orpc/server": {
+      "optional": true
+    },
+    "lexical": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "skills",
+    "LICENSES"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drhomet/mithaq.git",
+    "directory": "packages/mithaq"
+  },
+  "homepage": "https://github.com/drhomet/mithaq#readme",
+  "bugs": {
+    "url": "https://github.com/drhomet/mithaq/issues"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}

package/skills/add-field/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: add-field
+description: Add, change or remove a field of an existing kayan in this mithaq project and write the migration for it. Use when asked to add a column, change a field's kind or rules, or write a migration.
+---
+
+# Add a field and its migration
+
+The guide is "A field" under "Add a feature to an existing kayan" in `README.md`, and "Migrations" in `AGENTS.md`. The installed mithaq is `packages/asas/node_modules/mithaq/`, or `node_modules/mithaq/` where the package manager hoists it to the root: every kind and rule is in its `docs/packages/mithaq/README.md`, and `mithaq migrate` in its `docs/packages/mithaq/src/asas/cli/README.md`.
+
+1. Edit `fields` in the kayan's file. A kind or rule the language does not hold changes the vocabulary: stop and ask the developer.
+2. A new `required` field on a table with rows needs a literal `defaultValue`, or goes in without `required` and becomes required in a later migration.
+3. Add the field to the pages that should draw it, and to the roles' grants when they list fields one by one (`<kayan>.fields.<field>`).
+4. From `packages/asas/`, with `DATABASE_URL` pointing at a database built from the migrations (never a pushed one; `AGENTS.md` "Migrations" says how to build one):
+
+   ```sh
+   bunx mithaq generate screens      # when a page draws it
+   bunx mithaq generate messages     # then fill every empty translation
+   bunx mithaq migrate --name <slug>
+   bunx mithaq generate --check
+   ```
+
+5. When `mithaq migrate` stops and asks for an answer in `mithaq.hints.json`, it is a rename or a drop. A drop deletes rows: ask the developer before you answer it.
+6. From the project root, `bunx --package typescript tsc -p .` and the same with `-p` naming each app.
+
+Commit the migration folder.
+
+In a project made with `--layout single`, read each path as `AGENTS.md` maps it; the installed mithaq is `node_modules/mithaq/`.

package/skills/add-kayan/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: add-kayan
+description: Add a kayan, one data type with its table, operations, access and admin pages, to this mithaq project. Use when asked for a new entity, table, resource or list in the dashboard.
+---
+
+# Add a kayan
+
+The steps are "Adding a kayan" in `AGENTS.md`, and the guide's worked example is "Add a kayan" in `README.md`. The installed mithaq is `packages/asas/node_modules/mithaq/`, or `node_modules/mithaq/` where the package manager hoists it to the root; its `docs/packages/mithaq/README.md` lists every kind and rule a field can take.
+
+1. Ask, unless the request says: does each row belong to one organization (place `organization`, the usual answer) or does every organization share it?
+2. Follow `AGENTS.md` "Adding a kayan", copying `packages/features/tags/`. Use only the kinds and rules the language holds; a new one changes the vocabulary, so stop and ask the developer.
+3. Grant its keys to the roles that use it, as step 4 there says. A kayan no role is granted answers no one.
+4. From `packages/asas/`, with `DATABASE_URL` pointing at a database built from the migrations (never a pushed one; `AGENTS.md` "Migrations" says how to build one):
+
+   ```sh
+   bunx mithaq generate screens      # when a screen draws it
+   bunx mithaq generate messages     # then fill every empty translation
+   bunx mithaq migrate --name add_<name>
+   bunx mithaq generate --check
+   ```
+
+5. From the project root, `bunx --package typescript tsc -p .` and `bunx --package typescript tsc -p apps/asas-tanstack` (and `apps/asas-backoffice` when the project has it).
+
+Commit the migration folder. Never edit a file whose first line reads ``// Written by `mithaq <command>` ``; run the command again.
+
+In a project made with `--layout single`, read each path as `AGENTS.md` maps it; the installed mithaq is `node_modules/mithaq/`.

package/skills/eject-admin-piece/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: eject-admin-piece
+description: Change how the admin draws something in this mithaq project, by replacing a control, cell or node in the components map or by ejecting a mithaq-admin piece. Use when asked to restyle or change an admin control, list, form, shell or page piece.
+---
+
+# Change an admin piece
+
+The installed mithaq is `packages/asas/node_modules/mithaq/`, or `node_modules/mithaq/` where the package manager hoists it to the root. The guide is the admin's, its `docs/packages/mithaq-admin/README.md` ("Add or replace a control", "Replace a node", "Eject a piece"), and `eject` in its `docs/packages/mithaq/src/asas/cli/README.md`.
+
+1. Reach for the components map first: a control, a cell or a node is replaced in the app's `src/components.ts` without ejecting anything.
+2. Otherwise eject the piece, in the app that draws it (`apps/asas-tanstack` or `apps/asas-backoffice`):
+
+   ```sh
+   bunx mithaq eject <item>          # an unknown name lists every item
+   ```
+
+   It writes the piece into `src/components/mithaq/`, drawn in place of the package's, and names any shadcn primitive or npm package to add. Restart the dev server.
+3. Edit the ejected file in place; it is the project's now. Keep its last line, the `// mithaq-admin` marker, which `upgrade --check` reads.
+4. Check, in the app:
+
+   ```sh
+   bunx mithaq upgrade --check       # the held files against the installed mithaq-admin
+   bunx --package typescript tsc -p .
+   ```
+
+To go back to the package's piece, delete the file, or run `bunx mithaq eject --prune`, which deletes every ejected file nobody edited.
+
+In a project made with `--layout single`, read each path as `AGENTS.md` maps it; the installed mithaq is `node_modules/mithaq/`.

package/skills/upgrade-mithaq/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: upgrade-mithaq
+description: Upgrade this project to a newer mithaq and mithaq-admin. Use when asked to update or upgrade mithaq, or when the installed version is behind the one a task needs.
+---
+
+# Upgrade mithaq
+
+Run each command from the project root. The installed mithaq, `$M` below, is `packages/asas/node_modules/mithaq/`, or `node_modules/mithaq/` where the package manager hoists it to the root, as in a project made with `--layout single`; each block finds it first.
+
+1. Before you install, save the developer's own edits to the skills this version shipped. Skip this when `$M/skills` does not exist: that version shipped none.
+
+   ```sh
+   M=packages/asas/node_modules/mithaq; [ -d "$M" ] || M=node_modules/mithaq
+   ls "$M/skills" > /tmp/mithaq-shipped-skills
+   for skill in $(cat /tmp/mithaq-shipped-skills); do diff -ru "$M/skills/$skill" ".claude/skills/$skill"; done > /tmp/mithaq-skill-edits.diff
+   ```
+
+2. Set `mithaq` and `mithaq-admin` to the same new version in every `package.json` that names them (`npm:@drhomet/mithaq@<version>` and `npm:@drhomet/mithaq-admin@<version>`), and install.
+3. Read "Upgrading" in the new version's project guide, `$M/docs/templates/asas/README.md`: it says what a project made before each round changes. Apply every note for the rounds since this project's version, in order. A note that changes the vocabulary or drops data needs the developer's word first.
+4. Replace the shipped skills with the new version's. A skill the old version shipped and the new one does not is deleted; a skill the developer wrote, which no version shipped, is left alone.
+
+   ```sh
+   M=packages/asas/node_modules/mithaq; [ -d "$M" ] || M=node_modules/mithaq
+   for skill in $(cat /tmp/mithaq-shipped-skills 2>/dev/null); do rm -rf ".claude/skills/$skill"; done
+   mkdir -p .claude/skills && cp -R "$M/skills/." .claude/skills/
+   git status --short -- .claude/skills
+   git diff -- .claude/skills
+   ```
+
+   Then put back each of the developer's edits in `/tmp/mithaq-skill-edits.diff` that the new text lost, and ask the developer where an edit no longer fits the new text.
+5. From `packages/asas/`, with `DATABASE_URL` exported, run `bunx mithaq generate --check`. It also checks the lock and the migrations; rerun `generate auth`, `screens` or `messages` as it says.
+6. Run `bunx mithaq upgrade --check` in each folder holding a `components.json`: `packages/mithaq`, `apps/asas-tanstack` and, when the project has it, `apps/asas-backoffice`. Each file it reports as `differs` came from mithaq-admin: diff it against the package's and merge by hand, keeping the project's own edits.
+7. From the project root, `bunx --package typescript tsc -p .` and the same with `-p` naming each app, then build and start each app once.
+
+In a project made with `--layout single`, read each path as `AGENTS.md` maps it.