@endora-commerce/mod-prompt-actions 0.0.0-stage → 0.100.0

package/dist/migrations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,yCAAyC,EAAE,MAAM,0CAA0C,CAAC;AAErG,eAAO,MAAM,UAAU,sDAEtB,CAAC;AAEF,OAAO,EACL,yCAAyC,GAC1C,CAAC"}

package/dist/migrations/index.js

@@ -0,0 +1,29 @@
+/**
+ * The `./migrations` subpath — every migration class this module owns, as one
+ * ordered `migrations` array.
+ *
+ * The array is what the platform reads when this module is **installed**:
+ * `src/packages/package-runtime.ts` takes `exported['migrations']` and refuses
+ * the package outright when it is absent (D-168).
+ *
+ * Listed in ascending timestamp, which is the order of this module's own
+ * migrations and of nothing else (feature 081): a manifest `dependencies` array
+ * is the only thing ordering this block against another module's.
+ *
+ * The **named** exports stay beside the array, and the asymmetry with
+ * `./backend` — which publishes an array and no named class (D-168) — is
+ * deliberate. `db/migrations-registry.generated.ts` imports each class by name
+ * from this specifier, and a migration class name is contract in a way an entity
+ * class name is not: `mikro_orm_migrations` persists it, so it is a string every
+ * already-migrated database holds.
+ *
+ * A class that is in neither the array nor the barrel is a migration that does
+ * not run: `migration:pending` reports nothing pending and the first symptom is
+ * a query against a table nobody created.
+ */
+import { Migration20260611T140410PromptActionsInit } from './20260611T140410_prompt_actions_init.js';
+export const migrations = [
+    Migration20260611T140410PromptActionsInit,
+];
+export { Migration20260611T140410PromptActionsInit, };
+//# sourceMappingURL=index.js.map

package/dist/migrations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,yCAAyC,EAAE,MAAM,0CAA0C,CAAC;AAErG,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,yCAAyC;CAC1C,CAAC;AAEF,OAAO,EACL,yCAAyC,GAC1C,CAAC"}

package/docs/prompt-actions.md

@@ -0,0 +1,117 @@
+---
+title: Prompt Actions (AI assistant)
+description: Natural-language prompt mode for the admin command palette, with an explicit preview-and-confirm step before any change
+---
+
+# Prompt Actions (AI assistant)
+
+The `prompt_actions` module adds a natural-language prompt mode to the admin
+command palette (`⌘K` / `Ctrl+K`). An operator describes what they want in
+plain language — Polish or English — and the platform interprets the
+instruction, shows exactly what it is about to change, and executes it only
+after explicit confirmation.
+
+Example prompts:
+
+- *Dla produktu „Bolts 0193" zwiększ stan magazynowy w magazynie „Default" na 120 sztuk*
+- *Assign every product with "Helmets" in its name to the "Helmets" category*
+
+## How it works (operator view)
+
+1. Open the palette and pick **Ask the assistant…** (visible only when the
+   feature is enabled, configured, and you hold the *Use the prompt
+   assistant* permission).
+2. Type the instruction and submit. The assistant resolves names ("Bolts
+   0193", "Default") into concrete records using read-only searches.
+3. A **plan card** appears: the exact operation(s), the current value, the
+   number of affected records and a sample for bulk changes. Nothing has
+   been changed yet.
+4. **Confirm** to execute, or **Cancel** to keep everything untouched. Plans
+   expire after 10 minutes without confirmation.
+5. The result reports per-item outcomes. Bulk runs above 50 records continue
+   in the background; if you close the palette, a notice appears on the next
+   open until you view the result.
+
+If the instruction is ambiguous the assistant asks one clarifying question
+(with concrete candidates) instead of guessing. Unsupported requests and
+missing permissions are reported plainly, and nothing changes.
+
+## Security model
+
+- The model can only call a **curated tool catalogue** registered in code —
+  it cannot run SQL, call arbitrary endpoints, or invent operations. Tools
+  the operator has no permission for are not even shown to the model.
+- Mutations are **never executed during interpretation**: they are captured
+  into a plan; each plan operation re-checks the operator's live permission
+  at execution time.
+- Everything on the plan card is **server-computed** (names, counts, current
+  values). Model prose is never displayed, and tool results are treated
+  strictly as data — a product named like an instruction cannot change the
+  assistant's behavior.
+- Every execution writes audit entries: a `prompt_action.execute` summary
+  (with the original prompt, provider and model) plus the underlying
+  modules' own audit rows (e.g. `stock_level.adjust`). Permission refusals
+  are audited as `prompt_action.refused`. Executions also appear on the
+  dashboard's Recent Activity card.
+
+## Configuration (platform administrator)
+
+Settings → group **Prompt actions (AI assistant)**:
+
+| Setting | Default | Meaning |
+|---------|---------|---------|
+| `prompt_actions.enabled` | `false` | Platform-wide kill switch. When off, the palette behaves exactly as without the module. |
+| `prompt_actions.provider` | `anthropic` | LLM provider: `anthropic` (Claude), `google` (Gemini) or `openai` (GPT). |
+| `prompt_actions.model` | `claude-sonnet-4-6` | Model ID for the chosen provider. |
+| `prompt_actions.api_key` | *(unset)* | Provider credential. **Write-only secret**: encrypted at rest, never returned by the settings API after saving. |
+| `prompt_actions.bulk_limit` | `500` | Maximum records one prompt may affect; larger plans are blocked at preview. |
+
+Configuration changes apply on the next prompt — no restart. The backend
+needs `SETTINGS_SECRET_ENCRYPTION_KEY` in its environment to store the API
+key (see the root README, *Environment variables*).
+
+Grant operators the **Use the prompt assistant** (`prompt_actions:use`)
+permission on the Roles screen. Each planned operation additionally requires
+the same permission as the equivalent manual action (e.g. `catalog:write`
+for a stock change), so the assistant can never exceed what the operator
+could do by hand.
+
+## Extending the catalogue (module authors)
+
+Modules contribute tools at composition time through the
+`PromptActionToolRegistry` port — the same adapter-registry pattern used by
+payment and shipping providers. A tool declares:
+
+```ts
+{
+  id: '<moduleId>.<snake_case_name>',   // e.g. 'inventory.set_stock_level'
+  moduleId: 'inventory',
+  kind: 'resolver' | 'mutation',
+  description: '…',                      // English; the LLM's only documentation
+  requiredPermission: 'catalog:write',   // MUST mirror the manual route's permission
+  paramsSchema: zodSchema,               // validates LLM args + becomes the JSON Schema
+  execute(params, ctx) { … },            // resolvers run during interpretation;
+                                         // mutations only at confirm time
+  preview(params, ctx) { … },            // mutations only — server-computed facts
+}
+```
+
+Rules (enforced at registration where possible): dotted ids prefixed with
+the owning module; resolvers are side-effect-free and cap results (≤ 20);
+mutations must implement `preview()` returning honest, server-computed
+counts and samples; tools of disabled modules disappear from the catalogue
+automatically.
+
+## v1 tool catalogue
+
+| Tool | Kind | Permission |
+|------|------|------------|
+| `catalog.search_products` | resolver | `catalog:read` |
+| `catalog.search_categories` | resolver | `catalog:read` |
+| `inventory.search_warehouses` | resolver | `catalog:read` |
+| `inventory.set_stock_level` | mutation | `catalog:write` |
+| `catalog.assign_products_to_category` | mutation | `catalog:write` |
+
+Bulk category assignments above 50 products ride the existing durable
+`catalog.bulk-operation` queue (the same worker that serves the bulk-edit
+screen), so large prompts never block the API process.

package/i18n/en.json

@@ -0,0 +1,40 @@
+{
+  "adminRoles.permission.prompt_actions:use": "Use the prompt assistant",
+  "palette.entry.label": "Ask the assistant…",
+  "palette.entry.description": "Describe what you want to do in plain language",
+  "panel.inputPlaceholder": "e.g. Set the stock of \"Bolts 0193\" in warehouse \"Default\" to 120",
+  "panel.voiceInput": "Dictate (speech-to-text)",
+  "panel.voiceInputStop": "Stop dictation",
+  "panel.submit": "Interpret",
+  "panel.interpreting": "Interpreting your instruction…",
+  "panel.executing": "Executing…",
+  "panel.confirm": "Confirm and execute",
+  "panel.cancel": "Cancel",
+  "panel.back": "Back",
+  "panel.close": "Close",
+  "panel.planHeading": "The assistant proposes:",
+  "panel.affectedCount": "{count} record(s) will be affected",
+  "panel.sampleHeading": "Sample of matched records:",
+  "panel.currentValue": "Current value:",
+  "panel.expiresHint": "This plan must be confirmed within 10 minutes.",
+  "panel.success": "Done — the change has been applied.",
+  "panel.successWithErrors": "Finished with some failures — see the breakdown below.",
+  "panel.failed": "The assistant could not complete this request.",
+  "panel.unsupported": "This request is not supported by the assistant.",
+  "panel.refused": "You do not have the permission required for this action.",
+  "panel.providerError": "The assistant service is currently unavailable. Your data has not been changed — please try again or use the regular admin screens.",
+  "panel.clarificationHeading": "The assistant needs one detail:",
+  "panel.clarificationFreeTextPlaceholder": "Type your answer…",
+  "panel.clarificationSubmit": "Answer",
+  "panel.resultSucceeded": "{count} succeeded",
+  "panel.resultFailed": "{count} failed",
+  "panel.openTarget": "Open the affected record",
+  "panel.unseenNotice": "A prompt you confirmed earlier has finished — open the assistant to see the result.",
+  "panel.inFlight": "Another prompt is still being processed — wait for it to finish.",
+  "panel.bulkLimitExceeded": "This prompt would affect more records than the configured limit ({limit}). Narrow the instruction and try again.",
+  "panel.planExpired": "This plan has expired without confirmation. Submit the prompt again.",
+  "capability.disabled": "The prompt assistant is disabled on this platform.",
+  "capability.notConfigured": "The prompt assistant is not configured yet — set the provider and API key in Settings.",
+  "palette.group.label": "Assistant",
+  "activity.verb.prompt_action.execute": "ran a prompt action"
+}

package/i18n/pl.json

@@ -0,0 +1,40 @@
+{
+  "adminRoles.permission.prompt_actions:use": "Korzystanie z asystenta promptów",
+  "palette.entry.label": "Zapytaj asystenta…",
+  "palette.entry.description": "Opisz, co chcesz zrobić, własnymi słowami",
+  "panel.inputPlaceholder": "np. Dla produktu \"Bolts 0193\" zwiększ stan magazynowy w magazynie \"Default\" na 120 sztuk",
+  "panel.voiceInput": "Dyktowanie (mowa na tekst)",
+  "panel.voiceInputStop": "Zatrzymaj dyktowanie",
+  "panel.submit": "Interpretuj",
+  "panel.interpreting": "Interpretuję polecenie…",
+  "panel.executing": "Wykonuję…",
+  "panel.confirm": "Potwierdź i wykonaj",
+  "panel.cancel": "Anuluj",
+  "panel.back": "Wróć",
+  "panel.close": "Zamknij",
+  "panel.planHeading": "Asystent proponuje:",
+  "panel.affectedCount": "Zmiana obejmie {count} rekord(ów)",
+  "panel.sampleHeading": "Przykładowe dopasowane rekordy:",
+  "panel.currentValue": "Obecna wartość:",
+  "panel.expiresHint": "Ten plan trzeba potwierdzić w ciągu 10 minut.",
+  "panel.success": "Gotowe — zmiana została zastosowana.",
+  "panel.successWithErrors": "Zakończono z błędami — szczegóły poniżej.",
+  "panel.failed": "Asystent nie mógł zrealizować tego polecenia.",
+  "panel.unsupported": "To polecenie nie jest obsługiwane przez asystenta.",
+  "panel.refused": "Nie masz uprawnienia wymaganego do tej operacji.",
+  "panel.providerError": "Usługa asystenta jest chwilowo niedostępna. Dane nie zostały zmienione — spróbuj ponownie lub użyj zwykłych ekranów panelu.",
+  "panel.clarificationHeading": "Asystent potrzebuje jednego doprecyzowania:",
+  "panel.clarificationFreeTextPlaceholder": "Wpisz odpowiedź…",
+  "panel.clarificationSubmit": "Odpowiedz",
+  "panel.resultSucceeded": "{count} powiodło się",
+  "panel.resultFailed": "{count} nie powiodło się",
+  "panel.openTarget": "Otwórz zmieniony rekord",
+  "panel.unseenNotice": "Wcześniej potwierdzony prompt został zakończony — otwórz asystenta, aby zobaczyć wynik.",
+  "panel.inFlight": "Poprzedni prompt jest wciąż przetwarzany — poczekaj na jego zakończenie.",
+  "panel.bulkLimitExceeded": "To polecenie objęłoby więcej rekordów niż ustawiony limit ({limit}). Zawęź polecenie i spróbuj ponownie.",
+  "panel.planExpired": "Ten plan wygasł bez potwierdzenia. Wyślij polecenie ponownie.",
+  "capability.disabled": "Asystent promptów jest wyłączony na tej platformie.",
+  "capability.notConfigured": "Asystent promptów nie jest jeszcze skonfigurowany — ustaw dostawcę i klucz API w Ustawieniach.",
+  "palette.group.label": "Asystent",
+  "activity.verb.prompt_action.execute": "wykonał akcję asystenta"
+}

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@endora-commerce/mod-prompt-actions",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.100.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Natural-language prompt mode for the admin command palette: interpret an operator instruction with an LLM, preview the plan, execute it through existing module services after explicit confirmation.",
+  "license": "MIT",
+  "endora": {
+    "type": "module",
+    "id": "prompt_actions"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/endora-commerce/endora-commerce.git",
+    "directory": "packages/modules/prompt_actions"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/manifest.d.ts",
+      "default": "./dist/manifest.js"
+    },
+    "./backend": {
+      "types": "./dist/backend/index.d.ts",
+      "default": "./dist/backend/index.js"
+    },
+    "./migrations": {
+      "types": "./dist/migrations/index.d.ts",
+      "default": "./dist/migrations/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "i18n",
+    "docs"
+  ],
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "peerDependencies": {
+    "@mikro-orm/core": "^6",
+    "@mikro-orm/migrations": "^6",
+    "@mikro-orm/postgresql": "^6",
+    "fastify": "^5",
+    "zod": "^4",
+    "@endora-commerce/contracts": "0.100.0",
+    "@endora-commerce/platform": "0.100.0"
+  },
+  "devDependencies": {
+    "@mikro-orm/core": "^6.6.13",
+    "@mikro-orm/migrations": "^6.6.13",
+    "@mikro-orm/postgresql": "^6.6.13",
+    "@types/node": "^22.9.0",
+    "fastify": "^5.12.5",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11",
+    "zod": "^4.2.0",
+    "@endora-commerce/contracts": "0.100.0",
+    "@endora-commerce/platform": "0.100.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "test": "vitest run"
+  }
 }