@endora-commerce/mod-admin-actions 0.100.0

package/dist/manifest.js

@@ -0,0 +1,85 @@
+import { defineModuleManifest } from '@endora-commerce/contracts';
+/**
+ * Admin Command Palette Actions Registry — feature 020.
+ *
+ * Owns the `module_actions` table, the install-time reconciler that
+ * ingests every module's manifest `actions` array, the in-process
+ * cache, and the read API consumed by the admin SPA's command palette.
+ * Itself declares no actions — this module is platform plumbing, not
+ * a place to surface UI features.
+ *
+ * Depends on `_lifecycle` because every module's action install / hard-
+ * uninstall is driven by the lifecycle orchestrator's hook surface, and
+ * on `_i18n` because action labels and descriptions are resolved
+ * through the existing translation-bundle resolver.
+ */
+export const manifest = defineModuleManifest({
+    id: 'admin_actions',
+    name: 'Admin Command Palette Actions',
+    description: 'Module-contributed action registry that surfaces declared actions in the admin command palette.',
+    version: '1.0.0',
+    // `auth` owns the `requireAdmin` port; `admin_roles` owns the permission
+    // service the palette filters entries with. Feature 072 made both container
+    // resolutions rather than constructor arguments.
+    dependencies: ['_i18n', '_lifecycle', 'auth', 'admin_roles'],
+    i18n: { bundlesDir: 'i18n' },
+    docs: { dir: 'docs' },
+    settings: {
+        moduleCode: 'admin_actions',
+        groups: [{ code: 'admin_actions', name: 'Command palette' }],
+        settings: [
+            {
+                // Feature 073 — the operator's activation control. Platform-wide.
+                code: 'admin_actions.enabled',
+                name: 'Command palette enabled',
+                description: 'Switches the admin command palette on or off: the action registry every module contributes to and the read API behind ⌘K. Switched off, the admin is navigated through the sidebar alone; nothing is dropped — the registered actions stay in the database and the palette answers again exactly as before when you switch it back on.',
+                groupCode: 'admin_actions',
+                valueType: 'boolean',
+                defaultValue: true,
+            },
+        ],
+    },
+    // Feature 073, Amendment A1 (Constitution XVII) — deactivatable. What this
+    // module gates is *discoverability*: with it off the sidebar still navigates
+    // the whole admin, so losing ⌘K is a degradation rather than the loss of a
+    // capability. It is also the only module in the declaring set with no external
+    // manifest dependent at all — nothing fails closed behind it — so the flag was
+    // protecting a convenience, which is not what `nonDeactivatable` is for.
+    activation: { settingCode: 'admin_actions.enabled', default: true },
+});
+/**
+ * `module_actions` follows the manifest set — feature 080, T036a / D-159.
+ *
+ * `_i18n/manifest.ts` states the shape's reasoning in full; this module is the
+ * second instance of it, projecting every other module's `manifest.actions`
+ * array instead of its `i18n` block.
+ *
+ * **It is not gated on this module's own activation, and that is a ruling**
+ * (D-159 §9, the owner, 2026-08-22). `composition.ts` used to forward the
+ * reconciler as a lazily-resolved port, so an operator who had switched the
+ * command palette off could not install an *unrelated* module — the install
+ * aborted on a `MODULE_DISABLED` from a discovery surface that has nothing to
+ * do with it. That was the better of the only two options then on the table,
+ * the other being a backend that would not start; the third, which this takes,
+ * is that a projection of manifest data is written whether or not anything is
+ * serving it. The rows are inert while the palette is off and the palette
+ * answers from them, unchanged, the moment it is switched back on.
+ */
+export const lifecycleParticipant = {
+    async onModuleInstalled({ moduleId, manifest: installed, em }) {
+        const { AdminActionsReconciler } = await import('./backend/services/admin-actions-reconciler.js');
+        await new AdminActionsReconciler({ em: () => em }).installForModule({
+            moduleId,
+            // Unconditional, including for the empty array: `installForModule`
+            // upserts *and prunes*, so a module that has dropped its last action
+            // needs the call in order for its last row to go.
+            actions: installed.actions ?? [],
+            em,
+        });
+    },
+    async onModuleHardUninstalled({ moduleId, em }) {
+        const { AdminActionsReconciler } = await import('./backend/services/admin-actions-reconciler.js');
+        await new AdminActionsReconciler({ em: () => em }).removeForModule({ moduleId, em });
+    },
+};
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAmC,MAAM,4BAA4B,CAAC;AAEnG;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,oBAAoB,CAAC;IAC3C,EAAE,EAAE,eAAe;IACnB,IAAI,EAAE,+BAA+B;IACrC,WAAW,EACT,iGAAiG;IACnG,OAAO,EAAE,OAAO;IAChB,yEAAyE;IACzE,4EAA4E;IAC5E,iDAAiD;IACjD,YAAY,EAAE,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,CAAC;IAC5D,IAAI,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE;IAC5B,IAAI,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE;IACrB,QAAQ,EAAE;QACR,UAAU,EAAE,eAAe;QAC3B,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAAC;QAC5D,QAAQ,EAAE;YACR;gBACE,kEAAkE;gBAClE,IAAI,EAAE,uBAAuB;gBAC7B,IAAI,EAAE,yBAAyB;gBAC/B,WAAW,EACT,wUAAwU;gBAC1U,SAAS,EAAE,eAAe;gBAC1B,SAAS,EAAE,SAAS;gBACpB,YAAY,EAAE,IAAI;aACnB;SACF;KACF;IACD,2EAA2E;IAC3E,6EAA6E;IAC7E,2EAA2E;IAC3E,+EAA+E;IAC/E,+EAA+E;IAC/E,yEAAyE;IACzE,UAAU,EAAE,EAAE,WAAW,EAAE,uBAAuB,EAAE,OAAO,EAAE,IAAI,EAAE;CACpE,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA8C;IAC7E,KAAK,CAAC,iBAAiB,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,EAAE;QAC3D,MAAM,EAAE,sBAAsB,EAAE,GAAG,MAAM,MAAM,CAC7C,gDAAgD,CACjD,CAAC;QACF,MAAM,IAAI,sBAAsB,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,gBAAgB,CAAC;YAClE,QAAQ;YACR,mEAAmE;YACnE,qEAAqE;YACrE,kDAAkD;YAClD,OAAO,EAAE,SAAS,CAAC,OAAO,IAAI,EAAE;YAChC,EAAE;SACH,CAAC,CAAC;IACL,CAAC;IACD,KAAK,CAAC,uBAAuB,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE;QAC5C,MAAM,EAAE,sBAAsB,EAAE,GAAG,MAAM,MAAM,CAC7C,gDAAgD,CACjD,CAAC;QACF,MAAM,IAAI,sBAAsB,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,eAAe,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC;IACvF,CAAC;CACF,CAAC"}

package/dist/migrations/20260507T142354_admin_actions_init.d.ts

@@ -0,0 +1,31 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * Module-Contributed Admin Actions — feature 020 / data-model.md.
+ *
+ * Schema changes (one atomic migration):
+ *   - new sequence `module_actions_version_seq` — monotonically-
+ *     increasing version vector consumed by the registry's HTTP cache
+ *     for `meta.registryVersion` diagnostics.
+ *   - new table `module_actions` — one row per `(module_id, action_id)`.
+ *     Stores the action's i18n keys, icon, target route, optional
+ *     required-permission code, optional keywords array (JSONB), and
+ *     ordering weight. Reconciler at module-install time UPSERTs every
+ *     declared action and prunes any rows the new manifest no longer
+ *     declares.
+ *   - btree index `idx_module_actions_weight_label_key` to support the
+ *     visibility query's ORDER BY (weight, label_key) when the cache
+ *     misses.
+ *
+ * No FK on `module_actions.module_id`: same rationale as feature 019's
+ * `translation_bundles` — modules are filesystem-driven (feature 018)
+ * and `module_registrations` is the registry of record; coupling
+ * lifecycle ordering through a FK would conflict with how the
+ * orchestrator runs its install phases. Cleanup is enforced by the
+ * lifecycle hard-uninstall hook (admin-actions reconciler), not by
+ * ON DELETE CASCADE.
+ */
+export declare class Migration20260507T142354AdminActionsInit extends Migration {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}
+//# sourceMappingURL=20260507T142354_admin_actions_init.d.ts.map

package/dist/migrations/20260507T142354_admin_actions_init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260507T142354_admin_actions_init.d.ts","sourceRoot":"","sources":["../../src/migrations/20260507T142354_admin_actions_init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,wCAAyC,SAAQ,SAAS;IACtD,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;IA8BnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAIrC"}

package/dist/migrations/20260507T142354_admin_actions_init.js

@@ -0,0 +1,55 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * Module-Contributed Admin Actions — feature 020 / data-model.md.
+ *
+ * Schema changes (one atomic migration):
+ *   - new sequence `module_actions_version_seq` — monotonically-
+ *     increasing version vector consumed by the registry's HTTP cache
+ *     for `meta.registryVersion` diagnostics.
+ *   - new table `module_actions` — one row per `(module_id, action_id)`.
+ *     Stores the action's i18n keys, icon, target route, optional
+ *     required-permission code, optional keywords array (JSONB), and
+ *     ordering weight. Reconciler at module-install time UPSERTs every
+ *     declared action and prunes any rows the new manifest no longer
+ *     declares.
+ *   - btree index `idx_module_actions_weight_label_key` to support the
+ *     visibility query's ORDER BY (weight, label_key) when the cache
+ *     misses.
+ *
+ * No FK on `module_actions.module_id`: same rationale as feature 019's
+ * `translation_bundles` — modules are filesystem-driven (feature 018)
+ * and `module_registrations` is the registry of record; coupling
+ * lifecycle ordering through a FK would conflict with how the
+ * orchestrator runs its install phases. Cleanup is enforced by the
+ * lifecycle hard-uninstall hook (admin-actions reconciler), not by
+ * ON DELETE CASCADE.
+ */
+export class Migration20260507T142354AdminActionsInit extends Migration {
+    async up() {
+        this.addSql(`create sequence "module_actions_version_seq" as bigint;`);
+        this.addSql(`
+      create table "module_actions" (
+        "module_id" varchar(64) not null,
+        "action_id" varchar(64) not null,
+        "label_key" varchar(255) not null,
+        "description_key" varchar(255) null,
+        "icon" varchar(64) not null,
+        "target_route" varchar(255) not null,
+        "required_permission" varchar(64) null,
+        "keywords" jsonb not null default '[]'::jsonb,
+        "weight" integer not null default 100,
+        "version" bigint not null default nextval('module_actions_version_seq'),
+        "installed_at" timestamptz not null default now(),
+        "updated_at" timestamptz not null default now(),
+        constraint "module_actions_pkey" primary key ("module_id", "action_id")
+      );
+    `);
+        this.addSql(`alter sequence "module_actions_version_seq" owned by "module_actions"."version";`);
+        this.addSql(`create index "idx_module_actions_weight_label_key" on "module_actions" ("weight", "label_key");`);
+    }
+    async down() {
+        this.addSql(`drop table if exists "module_actions";`);
+        this.addSql(`drop sequence if exists "module_actions_version_seq";`);
+    }
+}
+//# sourceMappingURL=20260507T142354_admin_actions_init.js.map

package/dist/migrations/20260507T142354_admin_actions_init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260507T142354_admin_actions_init.js","sourceRoot":"","sources":["../../src/migrations/20260507T142354_admin_actions_init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,OAAO,wCAAyC,SAAQ,SAAS;IAC5D,KAAK,CAAC,EAAE;QACf,IAAI,CAAC,MAAM,CAAC,yDAAyD,CAAC,CAAC;QAEvE,IAAI,CAAC,MAAM,CAAC;;;;;;;;;;;;;;;;KAgBX,CAAC,CAAC;QAEH,IAAI,CAAC,MAAM,CACT,kFAAkF,CACnF,CAAC;QAEF,IAAI,CAAC,MAAM,CACT,iGAAiG,CAClG,CAAC;IACJ,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,IAAI,CAAC,MAAM,CAAC,wCAAwC,CAAC,CAAC;QACtD,IAAI,CAAC,MAAM,CAAC,uDAAuD,CAAC,CAAC;IACvE,CAAC;CACF"}

package/dist/migrations/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 orders **this module's own** migrations
+ * and nothing else (feature 081). Where the block sits relative to every other
+ * module's is decided by the manifest `dependencies` graph.
+ *
+ * The **named** exports stay, and the asymmetry with `./backend` — which
+ * publishes an array and no entity class by name (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 { Migration20260507T142354AdminActionsInit } from './20260507T142354_admin_actions_init.js';
+export declare const migrations: (typeof Migration20260507T142354AdminActionsInit)[];
+export { Migration20260507T142354AdminActionsInit, };
+//# sourceMappingURL=index.d.ts.map

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,wCAAwC,EAAE,MAAM,yCAAyC,CAAC;AAEnG,eAAO,MAAM,UAAU,qDAEtB,CAAC;AAEF,OAAO,EACL,wCAAwC,GACzC,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 orders **this module's own** migrations
+ * and nothing else (feature 081). Where the block sits relative to every other
+ * module's is decided by the manifest `dependencies` graph.
+ *
+ * The **named** exports stay, and the asymmetry with `./backend` — which
+ * publishes an array and no entity class by name (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 { Migration20260507T142354AdminActionsInit } from './20260507T142354_admin_actions_init.js';
+export const migrations = [
+    Migration20260507T142354AdminActionsInit,
+];
+export { Migration20260507T142354AdminActionsInit, };
+//# 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,wCAAwC,EAAE,MAAM,yCAAyC,CAAC;AAEnG,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,wCAAwC;CACzC,CAAC;AAEF,OAAO,EACL,wCAAwC,GACzC,CAAC"}

package/docs/admin-actions.md

@@ -0,0 +1,164 @@
+---
+title: Admin Command Palette Actions
+description: Module-contributed action registry surfaced in the Admin Command Palette (⌘K Actions group)
+---
+
+# Admin Command Palette Actions
+
+A registry-backed contribution point that lets every backend module add action buttons to
+the Admin UI's command palette (the `⌘K` / `Ctrl+K` modal — what the operator sees as the
+**Actions** group). Two actions ship hardcoded today (*New product*, *Import products*); those,
+and every future action, are declared once in their owning module's manifest and surfaced
+through this registry.
+
+The platform side lives at `packages/modules/admin_actions/` and the admin runtime at
+`admin/src/lib/admin-actions/`.
+
+## What a module declares
+
+A module's `manifest.ts` may declare zero or more actions inline alongside its existing
+`settings` and `i18n` fields:
+
+```ts
+import { defineModuleManifest } from '@endora-commerce/contracts';
+
+export const manifest = defineModuleManifest({
+  id: 'catalog',
+  name: 'Catalog',
+  version: '1.4.0',
+  dependencies: [],
+  i18n: { bundlesDir: 'i18n' },
+  actions: [
+    {
+      id: 'new-product',
+      labelKey: 'catalog.actions.newProduct.label',
+      descriptionKey: 'catalog.actions.newProduct.description',
+      icon: 'Plus',
+      targetRoute: '/catalog/products/new',
+      requiredPermission: 'catalog:write',
+      keywords: ['product', 'new', 'add', 'create', 'produkt', 'nowy', 'dodaj'],
+      weight: 100,
+    },
+  ],
+});
+```
+
+Each entry MUST carry a stable `id`, a translatable `labelKey`, an `icon` from the closed
+allowlist, and a `targetRoute`. Optional fields are `descriptionKey`, `requiredPermission`,
+`keywords` (up to 10), and `weight` (default 100).
+
+`requiredPermission` is optional in the schema and all but mandatory in practice: it must be
+**the code the backend enforces on the route behind `targetRoute`**, so the palette never
+advertises a 403 and never hides a screen from an operator entitled to open it. Both failures
+happened — `settings/open-settings` shipped with no code at all against a `settings:read`
+route, and `inventory/open-inventory` declared `catalog:write` against an `orders:read` one —
+and the permission inventory could not see either, because it sweeps whether a code is
+*enforced somewhere*, not whether it is enforced *here*.
+`pnpm --filter backend run check:action-route-permissions` compares the two, resolving the SPA
+`targetRoute` to the admin API route that gates it. Leave the field unset only when the
+destination genuinely has no gate; where the screen is read-gated but the action's label
+promises a write, the field cannot say both, and the disagreement is recorded in that check's
+ledger rather than guessed at.
+
+Within-module `id` uniqueness is enforced by the manifest's Zod schema — installing a
+manifest with two actions sharing an id fails the install with a clear, indexed error.
+
+## Public surface
+
+| Verb + Path | Purpose |
+| --- | --- |
+| `GET /api/v1/admin/admin-actions?language=<en\|pl>` | Returns the operator-visible action list, already filtered by the operator's permissions and the module's installed state, sorted by `(weight, locale-aware label)`, with labels and descriptions resolved into the requested language (falling back to English then to the raw key, identical to the Admin UI i18n fallback chain). Permission: any authenticated admin. |
+
+The response carries a `meta.registryVersion` field — `MAX(version)` over the visible rows
+— useful for diagnostics. The admin SPA does not poll on it; refreshes are driven by the
+operator's language flip and on-mount fetch.
+
+## How an operator sees actions
+
+1. The operator opens the Admin UI and presses `⌘K` (or `Ctrl+K` on Windows / Linux).
+2. The palette renders two groups: **Navigate** (static jump targets) and **Actions**.
+3. The Actions group shows every action whose owning module is installed AND whose
+   `requiredPermission` (if any) the operator's role grants. The wildcard `*` permission
+   held by `platform_admin` satisfies every action.
+4. Typing in the search box filters across **both** groups by case-insensitive,
+   diacritic-insensitive substring match against the row's label, description, and
+   keywords. Polish operators can type `latwy` to match `łatwy`, English operators can
+   type `import` to match `Importuj produkty`, etc.
+5. Clicking a row or pressing `Enter` navigates to the action's `targetRoute` and closes
+   the palette.
+
+When no action is visible to the operator (rare; only with a no-permission role and no
+modules contributing permissionless actions), the **Actions** group is hidden entirely.
+
+## Lifecycle integration
+
+The orchestrator install path runs `module_actions` reconciliation between the i18n
+bundle install and the module's own install hook. The reconciler UPSERTs every declared
+action and prunes any rows the new manifest no longer declares — install order, version
+upgrades, and action removals are all idempotent. On hard-uninstall (`module:uninstall
+--hard`) the reconciler deletes every action row owned by the module before the i18n
+bundle removal step.
+
+State is persisted in `module_actions` (composite PK `(module_id, action_id)`); soft-
+uninstall (state → `disabled`) does NOT delete rows — it relies on the visibility read
+filtering every row whose module is not effectively present, which hides the actions
+while preserving them for re-enable.
+
+That filter asks the kernel's effective-state combiner, through a probe the composition
+root contributes, and it asks it for **both** presence axes: the deployment's
+`module_registrations` state and the operator's activation Setting. It used to ask only
+the second that way and join `module_registrations.state = 'installed'` for the first,
+which meant the palette and the route gates read one question out of two sources —
+disagreeing for the length of every `registryCache.refreshFromDb`, so a palette could
+advertise an action whose route answered 503 and hide one the route would still serve.
+The registry table is still the record for the platform axis; the palette simply no
+longer reads it behind the platform's back.
+
+## Storage shape
+
+| Column | Type | Notes |
+| --- | --- | --- |
+| `module_id` | `varchar(64)` | Part of PK. |
+| `action_id` | `varchar(64)` | Part of PK. |
+| `label_key` | `varchar(255)` | i18n key resolved at read time. |
+| `description_key` | `varchar(255) NULL` | Optional. |
+| `icon` | `varchar(64)` | One of the closed-allowlist names. |
+| `target_route` | `varchar(255)` | Admin route. |
+| `required_permission` | `varchar(64) NULL` | Permission code, any notation. |
+| `keywords` | `jsonb` | Array of strings. |
+| `weight` | `integer` | Sort key (default 100). |
+| `version` | `bigint` | Per-row sequence; bumped on every UPSERT. |
+| `installed_at`, `updated_at` | `timestamptz` | Row metadata. |
+
+There is no foreign key on `module_id` — modules are filesystem-driven and
+`module_registrations` is the registry of record. Cleanup is enforced by the
+hard-uninstall path of the reconciler, mirroring the `translation_bundles`
+choice.
+
+## Recommended weight bands
+
+Weights are advisory but reviewers expect new actions to land in the appropriate band:
+
+| Band | Use case |
+| --- | --- |
+| 0–99 | Reserved for the platform shell. |
+| 100–199 | Primary creation (e.g., New product, New page, New post). |
+| 200–299 | Secondary creation / configuration entry points. |
+| 300–399 | Workflow / inbox actions. |
+| 400–499 | Less-frequent navigation / utilities. |
+| ≥ 500 | Rarely-used actions; sink to the bottom. |
+
+## Icon allowlist
+
+Allowed icon names are an enum in `packages/contracts/src/admin-actions.ts`. Adding a new
+icon is a one-line PR that edits both the enum and the admin's `icon-map.ts`.
+
+## v1 seed set
+
+The initial release ships ten actions across nine modules: `catalog/new-product`,
+`import_export/import-products`, `import_export/open-import-export-center`,
+`inventory/open-inventory`, `quote_requests/open-rfq-inbox`, `cms/new-page`,
+`blog/new-post`, `megamenu/edit-megamenu`, `sales_channels/new-sales-channel`,
+`settings/open-settings`. Eight further candidates from the spec were deferred until
+their target admin pages exist (Adjust stock, New draft order, Find order by number,
+New customer, New price list, New promotion, Upload asset, New category).

package/i18n/en.json

@@ -0,0 +1,5 @@
+{
+  "palette.actionsHeader": "Actions",
+  "palette.empty": "No actions available",
+  "palette.searchPlaceholder": "Type to search actions…"
+}

package/i18n/pl.json

@@ -0,0 +1,5 @@
+{
+  "palette.actionsHeader": "Akcje",
+  "palette.empty": "Brak dostępnych akcji",
+  "palette.searchPlaceholder": "Wpisz, aby wyszukać akcje…"
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@endora-commerce/mod-admin-actions",
+  "version": "0.100.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Module-contributed action registry that surfaces declared actions in the admin command palette.",
+  "license": "MIT",
+  "endora": {
+    "type": "module",
+    "id": "admin_actions"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/endora-commerce/endora-commerce.git",
+    "directory": "packages/modules/admin_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",
+    "@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",
+    "@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"
+  }
+}