@endora-commerce/mod-admin-roles 0.100.0

package/dist/backend/services/permission-catalogue.service.js

@@ -0,0 +1,175 @@
+import { PERMISSION_CATALOGUE, } from '@endora-commerce/contracts';
+/**
+ * Merges the core `PERMISSION_CATALOGUE` with the `permissions` arrays of every
+ * registered module manifest. Powers `GET /admin/permissions` and role upsert
+ * validation (feature 026).
+ *
+ * **There is no memo, and that is the design** (issue #213). `listAssignable()`
+ * cached its result into a field that only an explicit `invalidate()` cleared,
+ * and the two things that had to call it — a Redis pub/sub listener in each
+ * composition root — were a duplicated wiring step rather than a property of the
+ * service. That is the shape of issue #33 (an admin "clear cache" action that
+ * missed the per-process LRU) and issue #45 (an invalidation that depended on
+ * subscriber registration order) for the third time. Now that the value tracks a
+ * Setting an operator flips from the Admin UI at runtime, a per-process memo can
+ * only be wrong between the flip and whatever drops it.
+ *
+ * Nothing is lost by dropping it: every input is already in memory — the
+ * manifests are fixed at composition and the presence predicate reads the
+ * registry cache, which does its own refreshing — so a call is a map build and a
+ * sort over a few hundred rows, on two admin-only paths. There is no ordering
+ * trap to test because there is no invalidation to order.
+ */
+export class PermissionCatalogueService {
+    options;
+    isModulePresent;
+    constructor(options) {
+        this.options = options;
+        this.isModulePresent = options.isModulePresent ?? (() => true);
+    }
+    /**
+     * The grantable set: what `/admin-roles` renders and what an operator may
+     * newly grant. Presence-filtered, so a module that is off contributes nothing
+     * (Constitution XVII item 5).
+     */
+    listAssignable() {
+        return this.#merge()
+            .filter((row) => [...row.owners].some((owner) => this.isModulePresent(owner)))
+            .map((row) => row.entry);
+    }
+    listAssignableCodes() {
+        return this.listAssignable().map((e) => e.code);
+    }
+    /**
+     * Every code the platform knows, present or not — the **vocabulary**, not the
+     * grantable set.
+     *
+     * Role upsert validates against this rather than against `listAssignable()`,
+     * and the difference is what keeps "off is non-destructive and reversible"
+     * true. An "Editor" role holds `blog.read`; the operator switches `blog` off
+     * and then renames the role. Validating the submitted list against the
+     * grantable set would answer 400 `Unknown permission(s): blog.read` — the
+     * operator either loses the role or silently drops a grant that must come back
+     * when `blog` does. A code of an absent module grants access to nothing anyway:
+     * the routes behind it answer 503 `MODULE_DISABLED` at their own seam.
+     *
+     * This is what the role editor already relies on: `AdminRolesPage` seeds its
+     * selection from the **role's** codes and renders a checkbox only for the ones
+     * the catalogue offers, so an absent module's grant is carried through the
+     * round trip untouched and simply has no checkbox to un-tick while the module
+     * is off. Narrowing this method would turn that into a silent revocation.
+     */
+    listKnownCodes() {
+        return this.#merge().map((row) => row.entry.code);
+    }
+    /**
+     * Every code the platform knows, mapped to the modules whose presence keeps
+     * it grantable — {@link MergedRow.owners}, published.
+     *
+     * D-173's sweep reads it, and it is a method rather than a derivation of its
+     * own because the whole question is *"does `/admin-roles` still offer this
+     * code when its owner is switched off?"* — a question only the merge this
+     * class performs can answer. A second implementation over
+     * `PERMISSION_CATALOGUE` plus the manifests would be right on the day it was
+     * written and would drift the first time the merge learns a rule: a shared
+     * code with two owners, or a catalogue row a manifest re-declares, is exactly
+     * where the two would disagree, and exactly the shape the sweep exists for.
+     */
+    listOwnersByCode() {
+        return new Map(this.#merge().map((row) => [row.entry.code, row.owners]));
+    }
+    /**
+     * The codes `moduleId` contributes, whether or not it is present.
+     *
+     * Exists for the off-state harness: proving a module's codes leave the
+     * grantable set needs to know which codes are its, and deriving that from the
+     * `module` display field would silently measure nothing for `_lifecycle`.
+     */
+    listOwnedCodes(moduleId) {
+        return this.#merge()
+            .filter((row) => row.owners.has(moduleId))
+            .map((row) => row.entry.code);
+    }
+    #merge() {
+        const byCode = new Map();
+        // Core first: a core row wins the label and the display module on a code
+        // collision, which is the long-standing behaviour and what the dedupe test
+        // pins. Its `module` is a real module id — `audit_log:read` says so in its
+        // own comment (feature 072, T017).
+        for (const row of PERMISSION_CATALOGUE) {
+            byCode.set(row.code, {
+                code: row.code,
+                module: row.module,
+                label: row.label,
+                owners: new Set([row.module]),
+                requires: new Set(),
+            });
+        }
+        for (const { manifest } of this.options.registryEntries) {
+            if (!manifest.permissions?.length)
+                continue;
+            for (const decl of manifest.permissions) {
+                const existing = byCode.get(decl.code);
+                if (existing) {
+                    // A second declarer of an already-known code contributes an owner and
+                    // its requirements — the row keeps the first label it was given.
+                    //
+                    // `requires` is the one field a later declarer adds to rather than
+                    // loses (D-175). A shared code opens more than one surface and each
+                    // has its own needs, so the union is the only answer that is right for
+                    // every one of them; it is advisory, so advising a code an operator
+                    // already holds costs nothing while dropping one leaves a screen
+                    // half-working with no explanation.
+                    existing.owners.add(manifest.id);
+                    for (const code of decl.requires ?? [])
+                        existing.requires.add(code);
+                    continue;
+                }
+                byCode.set(decl.code, {
+                    code: decl.code,
+                    module: decl.module ?? manifest.id,
+                    label: decl.label,
+                    owners: new Set([manifest.id]),
+                    requires: new Set(decl.requires ?? []),
+                });
+            }
+        }
+        return [...byCode.values()]
+            .map((row) => ({
+            entry: {
+                code: row.code,
+                module: row.module,
+                label: row.label,
+                owners: [...row.owners].sort(),
+                ...(row.requires.size > 0 ? { requires: [...row.requires].sort() } : {}),
+            },
+            owners: row.owners,
+        }))
+            .sort((a, b) => a.entry.module.localeCompare(b.entry.module) ||
+            a.entry.code.localeCompare(b.entry.code));
+    }
+    /**
+     * Every declared requirement, as `code -> the codes a role holding it needs`
+     * (D-175, feature 080 T057).
+     *
+     * The **vocabulary's** view, not the grantable set's: the advisory has to
+     * survive its target's owner being switched off, or it would go quiet at
+     * exactly the moment an operator most needs to know why a screen came back
+     * incomplete. Empty requirement sets are omitted, so `size` is the number of
+     * codes that declare one.
+     */
+    listRequirementsByCode() {
+        return new Map(this.#merge()
+            .filter((row) => (row.entry.requires?.length ?? 0) > 0)
+            .map((row) => [row.entry.code, row.entry.requires]));
+    }
+}
+/** Test / CI helper — build assignable codes without wiring composition. */
+export function listAssignablePermissionCodes(registryEntries, presentModuleIds) {
+    const present = presentModuleIds === undefined ? null : new Set(presentModuleIds);
+    return new PermissionCatalogueService({
+        registryEntries,
+        ...(present ? { isModulePresent: (id) => present.has(id) } : {}),
+    }).listAssignableCodes();
+}
+//# sourceMappingURL=permission-catalogue.service.js.map

package/dist/backend/services/permission-catalogue.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-catalogue.service.js","sourceRoot":"","sources":["../../../src/backend/services/permission-catalogue.service.ts"],"names":[],"mappings":"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"}

package/dist/backend/services/permission-service.d.ts

@@ -0,0 +1,24 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import type { AdminUserReadPort } from '@endora-commerce/contracts';
+/**
+ * PermissionService (T187). Looks up an AdminUser's Role and checks if a
+ * specific permission string is present in the Role's permissions array.
+ *
+ * The wildcard `*` in a Role's permissions grants every permission — used for
+ * the bootstrap "platform admin" Role.
+ *
+ * The admin identity comes from `adminUserReadPort` (feature 075, Phase C)
+ * rather than from `em.findOne(AdminUser, …)`: the role assignment is a column
+ * on a table `admin_users` owns, and this module owns only what the role says.
+ * `activeOnly` is the `deletedAt: null` half of the query it replaced; the
+ * `status` test below is the other half and stays here, because "may this admin
+ * act" is this module's question.
+ */
+export declare class PermissionService {
+    private readonly emFactory;
+    private readonly adminUsers;
+    constructor(emFactory: () => EntityManager, adminUsers: AdminUserReadPort);
+    hasPermission(adminUserId: string, permission: string): Promise<boolean>;
+    listPermissions(adminUserId: string): Promise<string[]>;
+}
+//# sourceMappingURL=permission-service.d.ts.map

package/dist/backend/services/permission-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-service.d.ts","sourceRoot":"","sources":["../../../src/backend/services/permission-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAGpE;;;;;;;;;;;;;GAaG;AACH,qBAAa,iBAAiB;IAE1B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,UAAU;gBADV,SAAS,EAAE,MAAM,aAAa,EAC9B,UAAU,EAAE,iBAAiB;IAG1C,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQxE,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAM9D"}

package/dist/backend/services/permission-service.js

@@ -0,0 +1,40 @@
+import { AdminRole } from '../entities/admin-role.entity.js';
+/**
+ * PermissionService (T187). Looks up an AdminUser's Role and checks if a
+ * specific permission string is present in the Role's permissions array.
+ *
+ * The wildcard `*` in a Role's permissions grants every permission — used for
+ * the bootstrap "platform admin" Role.
+ *
+ * The admin identity comes from `adminUserReadPort` (feature 075, Phase C)
+ * rather than from `em.findOne(AdminUser, …)`: the role assignment is a column
+ * on a table `admin_users` owns, and this module owns only what the role says.
+ * `activeOnly` is the `deletedAt: null` half of the query it replaced; the
+ * `status` test below is the other half and stays here, because "may this admin
+ * act" is this module's question.
+ */
+export class PermissionService {
+    emFactory;
+    adminUsers;
+    constructor(emFactory, adminUsers) {
+        this.emFactory = emFactory;
+        this.adminUsers = adminUsers;
+    }
+    async hasPermission(adminUserId, permission) {
+        const admin = await this.adminUsers.findById(adminUserId, { activeOnly: true });
+        if (!admin || admin.status !== 'active' || !admin.adminRoleId)
+            return false;
+        const role = await this.emFactory().findOne(AdminRole, { id: admin.adminRoleId });
+        if (!role)
+            return false;
+        return role.permissions.includes('*') || role.permissions.includes(permission);
+    }
+    async listPermissions(adminUserId) {
+        const admin = await this.adminUsers.findById(adminUserId, { activeOnly: true });
+        if (!admin?.adminRoleId)
+            return [];
+        const role = await this.emFactory().findOne(AdminRole, { id: admin.adminRoleId });
+        return role?.permissions ?? [];
+    }
+}
+//# sourceMappingURL=permission-service.js.map

package/dist/backend/services/permission-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-service.js","sourceRoot":"","sources":["../../../src/backend/services/permission-service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAE7D;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,iBAAiB;IAET;IACA;IAFnB,YACmB,SAA8B,EAC9B,UAA6B;QAD7B,cAAS,GAAT,SAAS,CAAqB;QAC9B,eAAU,GAAV,UAAU,CAAmB;IAC7C,CAAC;IAEJ,KAAK,CAAC,aAAa,CAAC,WAAmB,EAAE,UAAkB;QACzD,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,WAAW,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;QAChF,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,WAAW;YAAE,OAAO,KAAK,CAAC;QAC5E,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,EAAE,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;QAClF,IAAI,CAAC,IAAI;YAAE,OAAO,KAAK,CAAC;QACxB,OAAO,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IACjF,CAAC;IAED,KAAK,CAAC,eAAe,CAAC,WAAmB;QACvC,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,WAAW,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;QAChF,IAAI,CAAC,KAAK,EAAE,WAAW;YAAE,OAAO,EAAE,CAAC;QACnC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,EAAE,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;QAClF,OAAO,IAAI,EAAE,WAAW,IAAI,EAAE,CAAC;IACjC,CAAC;CACF"}

package/dist/manifest.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Admin Roles module — manifest backfill (Module Lifecycle, feature 018).
+ *
+ * Predates the lifecycle system; this manifest is the static record
+ * required so the module participates in the registry. No install /
+ * uninstall hook today — the module's schema is owned by earlier
+ * platform-wide migrations.
+ */
+export declare const manifest: {
+    id: string;
+    name: string;
+    version: string;
+    dependencies: string[];
+    description?: string | undefined;
+    acknowledgedDependencies?: {
+        moduleId: string;
+        port: string;
+        reason: string;
+    }[] | undefined;
+    nonBindingDependencies?: {
+        moduleId: string;
+        name: string;
+        kind: "contributes-to" | "degrades-without" | "refuses-without";
+        reason: string;
+        whenAbsent?: string | undefined;
+    }[] | undefined;
+    activation?: {
+        settingCode: string;
+        default: boolean;
+    } | {
+        nonDeactivatable: true;
+        reason: string;
+    } | undefined;
+    settings?: {
+        moduleCode: string;
+        groups: {
+            code: string;
+            name: string;
+            salesChannelCodes?: string[] | undefined;
+            isSystemProtected?: boolean | undefined;
+        }[];
+        settings: {
+            code: string;
+            name: string;
+            valueType: "string" | "number" | "boolean" | "json" | "string_list" | "secret" | "credential_ref";
+            defaultValue: unknown;
+            description?: string | undefined;
+            groupCode?: string | undefined;
+            previousDefaultValues?: unknown[] | undefined;
+            salesChannelCodes?: string[] | undefined;
+            enumOptions?: string[] | undefined;
+            configurationType?: string | undefined;
+            hidden?: boolean | undefined;
+        }[];
+    } | undefined;
+    i18n?: {
+        bundlesDir: string;
+    } | undefined;
+    docs?: false | {
+        dir: string;
+    } | undefined;
+    demo?: false | {
+        summary: string;
+        seed: (context: import("@endora-commerce/contracts").ModuleDemoContext<never>) => Promise<import("@endora-commerce/contracts").DemoSeedResult>;
+        reset: (context: import("@endora-commerce/contracts").ModuleDemoContext<never>) => Promise<import("@endora-commerce/contracts").DemoResetResult>;
+        after?: readonly string[] | undefined;
+        package?: string | undefined;
+    } | undefined;
+    actions?: {
+        id: string;
+        labelKey: string;
+        icon: "Plus" | "Sparkles" | "Settings" | "Search" | "Boxes" | "Layers" | "Menu" | "PlusCircle" | "PlusSquare" | "FilePlus" | "FolderPlus" | "Upload" | "FileUp" | "CloudUpload" | "Download" | "FileDown" | "FileText" | "BookOpen" | "Rss" | "Package" | "Tag" | "ShoppingCart" | "Receipt" | "CreditCard" | "Users" | "UserPlus" | "Inbox" | "ListChecks" | "ClipboardList" | "Image" | "Video" | "LayoutDashboard" | "PanelLeft" | "KeyRound" | "ShieldCheck" | "Edit" | "Archive" | "Box" | "Truck" | "CircleDollarSign" | "Activity" | "LineChart" | "Smartphone" | "Webhook" | "Scale" | "PlugZap" | "PercentDiamond" | "Newspaper" | "Languages" | "Eraser" | "Warehouse" | "TrendingDown" | "Bell" | "PackageOpen" | "Building2" | "Store" | "ClipboardCheck";
+        targetRoute: string;
+        keywords: string[];
+        weight: number;
+        descriptionKey?: string | undefined;
+        requiredPermission?: string | undefined;
+    }[] | undefined;
+    permissions?: {
+        code: string;
+        label: string;
+        module?: string | undefined;
+        description?: string | undefined;
+        requires?: string[] | undefined;
+    }[] | undefined;
+    transactionalEmails?: {
+        code: string;
+        name: string;
+        variables: {
+            key: string;
+            label: string;
+            sampleValue?: string | undefined;
+            description?: string | undefined;
+        }[];
+        description?: string | undefined;
+        group?: string | undefined;
+    }[] | undefined;
+    capabilities?: string[] | undefined;
+    exclusiveCapabilities?: {
+        key: string;
+        errorCode: string;
+    }[] | undefined;
+    errorCodes?: {
+        code: string;
+        tokens?: string[] | undefined;
+    }[] | undefined;
+    blocks?: {
+        name: string;
+        labelKey: string;
+        category: string;
+        contexts: ("invoice" | "email" | "cms" | "newsletter")[];
+        fields: Record<string, {
+            type: "number" | "object" | "array" | "uuid" | "text" | "textarea" | "select" | "radio" | "external" | "richtext";
+            label?: string | undefined;
+            required?: boolean | undefined;
+            options?: {
+                label: string;
+                value: string | number;
+            }[] | undefined;
+            refKind?: string | undefined;
+        }>;
+        descriptionKey?: string | undefined;
+        defaultProps?: Record<string, unknown> | undefined;
+        responsiveFields?: string[] | undefined;
+        previewIcon?: string | undefined;
+        weight?: number | undefined;
+    }[] | undefined;
+    blockCategories?: {
+        key: string;
+        titleKey: string;
+        contexts: ("invoice" | "email" | "cms" | "newsletter")[];
+        weight?: number | undefined;
+        visible?: boolean | undefined;
+    }[] | undefined;
+    env?: {
+        name: string;
+        describes: {
+            en: string;
+            pl: string;
+        };
+        requirement: {
+            kind: "required";
+        } | {
+            kind: "requiredWhen";
+            input: string;
+            equals: string;
+        } | {
+            kind: "optional";
+            without: {
+                en: string;
+                pl: string;
+            };
+        };
+        secret: boolean;
+        generable: boolean;
+        owner: {
+            kind: "platform";
+        } | {
+            kind: "application";
+            application: "admin" | "backend" | "storefront";
+        } | {
+            kind: "module";
+            moduleId: string;
+        };
+        consumers: ("admin" | "backend" | "storefront")[];
+        addressOf: "admin" | "backend" | "storefront" | null;
+    }[] | undefined;
+};
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AA4BA;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgKnB,CAAC"}

package/dist/manifest.js

@@ -0,0 +1,192 @@
+import { defineModuleManifest } from '@endora-commerce/contracts';
+/**
+ * The demo data this module owns (feature 113, T222 — contract §1.3).
+ *
+ * A typed `const` rather than an inline object literal: declared inline the
+ * parameter infers from the schema and is `never`, so the author loses
+ * `context.ctx: ModuleContext`.
+ *
+ * Both bodies are reached by a **relative `await import()`** (§1.4), in
+ * `cliCommands.run`'s shape and for `cliCommands`' reason: a manifest is loaded
+ * by every process that composes the platform and by the check scripts that
+ * import the generated index, so a demo body imported at the top of this file
+ * would be a service graph pulled into all of them. It needs no `exports`
+ * subpath and no `files` entry (§1.5).
+ *
+ * **Which administrator holds which role is not here.** An `admin_users` row
+ * carrying an `admin_roles` id is two modules' rows in one statement, so the
+ * assignment is a composition step (§5.1) and belongs to whoever owns the
+ * instance.
+ */
+const demo = {
+    summary: 'The platform-administrator and sales-representative roles the demo signs in with.',
+    seed: async (context) => (await import('./backend/demo/seed.js')).seedDemo(context),
+    reset: async (context) => (await import('./backend/demo/reset.js')).resetDemo(context),
+};
+/**
+ * Admin Roles module — manifest backfill (Module Lifecycle, feature 018).
+ *
+ * Predates the lifecycle system; this manifest is the static record
+ * required so the module participates in the registry. No install /
+ * uninstall hook today — the module's schema is owned by earlier
+ * platform-wide migrations.
+ */
+export const manifest = defineModuleManifest({
+    id: 'admin_roles',
+    name: 'Admin Roles',
+    description: 'Admin RBAC — roles, permissions, and policy enforcement for admin sessions.',
+    version: '1.0.0',
+    dependencies: [],
+    /**
+     * Feature 075, Phase C — the two reads of the `AdminUser` row became
+     * `adminUserReadPort`, and `admin_users` declares this module, so declaring
+     * it back in `dependencies` closes a cycle that `module-graph.test.ts` and the
+     * composer generator both refuse. The mutual shape
+     * `acknowledgedDependencies` exists for, and the same one `auth` records
+     * against `customer_accounts`.
+     *
+     * With `admin_users` absent the seam fails closed: the port is gated, so the
+     * permission check refuses rather than answering from an admin row nobody
+     * read. That is the same answer every `requireAdmin` route on such a
+     * deployment gives, and it is why the edge is safe to withhold from
+     * `dependencies` — not a claim about which flips the orchestrator refuses,
+     * which is derived from the manifests on every run and copied here by nobody
+     * (D-100).
+     */
+    acknowledgedDependencies: [
+        {
+            moduleId: 'admin_users',
+            port: 'adminUserReadPort',
+            reason: 'Answering "may this admin do this?" starts from the admin row — its role assignment ' +
+                'and whether it is still live — and that row belongs to admin_users, which declares ' +
+                'this module for the catalogue it reads back. Declaring it here closes a cycle. With ' +
+                'admin_users absent the seam fails closed: the port is gated, so the permission check ' +
+                'refuses rather than answering from an admin row nobody read.',
+        },
+    ],
+    // Feature 072/073 (Constitution XVII) — `admin_roles` answers "may this admin
+    // do this?" for every guarded route in the platform. Switched off, the
+    // question has no answer and `requireAdmin` has nothing to check against, so
+    // the correct behaviour would be to refuse every admin request — which is not
+    // a deployment anyone wants and not a state the orchestrator will produce.
+    demo,
+    activation: {
+        nonDeactivatable: true,
+        reason: 'Answers the permission check behind every guarded admin route; switched off, no admin ' +
+            'request could be authorised at all.',
+    },
+    /**
+     * This module's first i18n bundle — D-129's remaining sweep, MR 6.
+     *
+     * It exists because a **declaring** module that contributes no bundle file is
+     * `check:error-translations` exit 2 for the whole tree rather than a finding
+     * (`specs/090-module-owned-error-codes/contracts/error-translation-population.md`
+     * §2.1, §2.3; `d129-sweep.md` §3.4). The bundle lives at the **package
+     * root**, not under `dist`: `manifest-locations.ts` resolves a packaged
+     * module's `manifestPath` to its `package.json`, so `dirname` is the package
+     * directory. The file is a **flat** `{"a.b.c": "text"}` map, because a nested
+     * object fails `TranslationBundleEntriesSchema` and the boot reconciler logs
+     * and skips it — silently.
+     */
+    i18n: { bundlesDir: 'i18n' },
+    docs: { dir: 'docs' },
+    /**
+     * This module's first command-palette action — feature 091, Phase 4, batch
+     * four — and it points at a route **`admin_users` declares**.
+     *
+     * That is the same split `src/admin/index.ts` makes for the sidebar entry and
+     * it is made for the same reason: the roles editor is served by
+     * `GET /api/v1/admin/admin-roles` in `admin_users`, so that module owns the
+     * route, while the advertisement of the roles capability is this module's.
+     * `check:action-route-permissions` resolves a `targetRoute` by path and not
+     * by owner, so it holds this declaration to the gate `/admin-roles` really
+     * enforces — `admin_users:manage`, which is why the code below is not an
+     * `admin_roles:*` one. This module registers no admin route and declares no
+     * permission of its own.
+     *
+     * It pays one of the fifteen entries `specs/deferred-defects.md` still holds
+     * under *"Sixteen modules with an admin screen declare no command-palette
+     * action"*, and the two labels live in this module's own bundle above.
+     */
+    actions: [
+        {
+            id: 'open-admin-roles',
+            labelKey: 'actions.openAdminRoles.label',
+            descriptionKey: 'actions.openAdminRoles.description',
+            icon: 'ShieldCheck',
+            targetRoute: '/admin-roles',
+            requiredPermission: 'admin_users:manage',
+            keywords: ['roles', 'role', 'rbac', 'permissions', 'uprawnienia', 'access'],
+            weight: 300,
+        },
+    ],
+    /**
+     * The three `ADMIN_ROLE_*` codes — D-129's remaining sweep, **Tier C**
+     * (`specs/090-module-owned-error-codes/d129-sweep.md` §5.2, Appendix A; MR 6).
+     *
+     * They were declared by `_i18n` until this merge request, not because anybody
+     * judged them the platform's but because the deleted prefix chain had no rule
+     * for them and its last line was `return 'core'`. **D-121 T1 puts all three
+     * here**: the noun is an admin role, this module's own `admin_roles` row, and
+     * every one of the four raise sites is in this module's
+     * `services/admin-role-service.ts`. Noun and thrower agree, which is why the
+     * sweep classes this batch by its *content* rather than by its judgement —
+     * Tier C is the two modules where prose moves.
+     *
+     * **`ADMIN_ROLE_IN_USE` is the sweep's only multi-token sentence**, and the
+     * one code in it where a wrong key is a wrong sentence rather than a missing
+     * one. `tokens` is derived from the raise sites and not from the bundle
+     * (runbook §5): both raises pass a `details.code` — `assigned` when live
+     * admin accounts still hold the role, `assigned_to_deleted` when only
+     * soft-deleted ones do — measured by balanced-paren extraction of each call's
+     * own argument list, resolving `ERROR_CODES.<CODE>` and the bare literal
+     * alike. The two populations are counted apart because the remedy differs,
+     * which is issue #168; `test/unit/admin_roles/role-in-use-sentence.test.ts`
+     * renders a real refusal against these keys.
+     *
+     * **The base key `errors.ADMIN_ROLE_IN_USE` is unreachable, and it is carried
+     * anyway.** `localizeErrorEnvelope` composes `` `${target.key}.${token}` ``
+     * whenever `details.code` is present and has **no** fall-back to the base key
+     * (`packages/platform/src/http/error-envelope.ts`), so with both raise sites
+     * tokened nothing in the tree renders that sentence. Deleting it is not free,
+     * and the measurement is the reason it is still here: P1 asks its question at
+     * `errors.<CODE>` and at no other key, so the bundle without the base pair
+     * reports `ADMIN_ROLE_IN_USE → admin_roles (missing in: en, pl)` and exits 1
+     * — for the best-translated code in the sweep. The two ways out are both
+     * worse than one unreachable string. `UNTRANSLATED_ERROR_CODES` would be a
+     * false entry: its own header defines an entry as a code with **no sentence
+     * anywhere**, this code has four, and nothing could ever drain it. Widening
+     * P1 to accept "every declared token answered" is the real repair, and it is
+     * a change to a tree-wide instrument made by the merge request that benefits
+     * from it — reported for the defect register instead, with the second half of
+     * the same finding: three places in this repository document a fall-back to
+     * `errors.<CODE>` that the envelope does not implement
+     * (`packages/contracts/src/modules.ts`'s `errorCodeTokenRe` note,
+     * `check-error-translations.ts`' `ERROR_KEY` note, and the test above).
+     *
+     * **The other two arrive with prose.** Both carried a placeholder in `_i18n`'s
+     * bundle — `"Admin Role Code Taken."` / `"Błąd: admin role code taken."` and
+     * the same for `ADMIN_ROLE_PROTECTED` — which D-186 §2 deletes rather than
+     * carries, because in this module's own bundle it would read as this module's
+     * answer. §5.4 keeps writing the prose available and is not a re-opening of
+     * that ruling, and both are the case for taking it: the reader is an operator
+     * on `/admin-roles`, saving a role or pressing Delete on a row, and each
+     * refusal has one remedy to offer.
+     *
+     * `ADMIN_ROLE_PROTECTED` needed one more thing first. Its raise interpolates
+     * the role's own code into the English message and passed no `details`, so a
+     * translated sentence with no placeholder would have rendered cleanly and
+     * lost the value — the shape !1181 measured at 85 codes tree-wide. The raise
+     * now carries `details: { role: role.code }` and both sentences name it as
+     * `{role}`. The member is `role` and not `code` deliberately: `details.code`
+     * is the refusal **token**, so the obvious spelling would have sent the
+     * envelope looking for `errors.ADMIN_ROLE_PROTECTED.<role code>` and rendered
+     * nothing at all.
+     */
+    errorCodes: [
+        { code: 'ADMIN_ROLE_CODE_TAKEN' },
+        { code: 'ADMIN_ROLE_IN_USE', tokens: ['assigned', 'assigned_to_deleted'] },
+        { code: 'ADMIN_ROLE_PROTECTED' },
+    ],
+});
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAA2B,MAAM,4BAA4B,CAAC;AAG3F;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,IAAI,GAAsC;IAC9C,OAAO,EAAE,mFAAmF;IAC5F,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,wBAAwB,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC;IACnF,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,yBAAyB,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC;CACvF,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,oBAAoB,CAAC;IAC3C,EAAE,EAAE,aAAa;IACjB,IAAI,EAAE,aAAa;IACnB,WAAW,EACT,6EAA6E;IAC/E,OAAO,EAAE,OAAO;IAChB,YAAY,EAAE,EAAE;IAChB;;;;;;;;;;;;;;;OAeG;IACH,wBAAwB,EAAE;QACxB;YACE,QAAQ,EAAE,aAAa;YACvB,IAAI,EAAE,mBAAmB;YACzB,MAAM,EACJ,sFAAsF;gBACtF,qFAAqF;gBACrF,sFAAsF;gBACtF,uFAAuF;gBACvF,8DAA8D;SACjE;KACF;IACD,8EAA8E;IAC9E,uEAAuE;IACvE,6EAA6E;IAC7E,8EAA8E;IAC9E,2EAA2E;IAC3E,IAAI;IACJ,UAAU,EAAE;QACV,gBAAgB,EAAE,IAAI;QACtB,MAAM,EACJ,wFAAwF;YACxF,qCAAqC;KACxC;IACD;;;;;;;;;;;;OAYG;IACH,IAAI,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE;IAC5B,IAAI,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE;IACrB;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,EAAE;QACP;YACE,EAAE,EAAE,kBAAkB;YACtB,QAAQ,EAAE,8BAA8B;YACxC,cAAc,EAAE,oCAAoC;YACpD,IAAI,EAAE,aAAa;YACnB,WAAW,EAAE,cAAc;YAC3B,kBAAkB,EAAE,oBAAoB;YACxC,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,aAAa,EAAE,QAAQ,CAAC;YAC3E,MAAM,EAAE,GAAG;SACZ;KACF;IACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8DG;IACH,UAAU,EAAE;QACV,EAAE,IAAI,EAAE,uBAAuB,EAAE;QACjC,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,EAAE,CAAC,UAAU,EAAE,qBAAqB,CAAC,EAAE;QAC1E,EAAE,IAAI,EAAE,sBAAsB,EAAE;KACjC;CACF,CAAC,CAAC"}