@aglyn/aglyn 1.0.0-beta.150 → 1.0.0-beta.151

package/src/lib/app-utils/index.d.ts

@@ -16,3 +16,4 @@
  */
 export * from './server';
 export * from './contexts';
+export * from './staff-role-gate';

package/src/lib/app-utils/index.js

@@ -19,5 +19,6 @@
 // reached via `@aglyn/aglyn`, keeps both for client consumers unchanged.
 export * from "./server.js";
 export * from "./contexts.js";
+export * from "./staff-role-gate.js";
 
 //# sourceMappingURL=index.js.map

package/src/lib/app-utils/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/index.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2022 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n// Full app-utils surface = server-safe utils + the client-only React\n// contexts. Split so `@aglyn/aglyn/server` can re-export just `./server`\n// (no `createContext`) for tenant Server Components (AGL-405); this barrel,\n// reached via `@aglyn/aglyn`, keeps both for client consumers unchanged.\nexport * from './server'\nexport * from './contexts'\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,qEAAqE;AACrE,yEAAyE;AACzE,4EAA4E;AAC5E,yEAAyE;AACzE,cAAc,cAAU;AACxB,cAAc,gBAAY"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/index.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2022 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n// Full app-utils surface = server-safe utils + the client-only React\n// contexts. Split so `@aglyn/aglyn/server` can re-export just `./server`\n// (no `createContext`) for tenant Server Components (AGL-405); this barrel,\n// reached via `@aglyn/aglyn`, keeps both for client consumers unchanged.\nexport * from './server'\nexport * from './contexts'\nexport * from './staff-role-gate'\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,qEAAqE;AACrE,yEAAyE;AACzE,4EAA4E;AAC5E,yEAAyE;AACzE,cAAc,cAAU;AACxB,cAAc,gBAAY;AAC1B,cAAc,uBAAmB"}

package/src/lib/app-utils/staff-role-gate.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export interface StaffRoleGate {
+    /**
+     * `false` while the claim is still resolving. Nothing may be BLOCKED in
+     * that window: rendering a refusal there would flash a disabled button at
+     * every super-staff member on every admin page load.
+     */
+    ready: boolean;
+    /** Whether the viewer's role is one the route admits. `false` until `ready`. */
+    admitted: boolean;
+    /**
+     * The one thing call sites branch on: a RESOLVED claim the route would
+     * refuse. Deliberately not `!admitted` — that is true during the
+     * unresolved window too, and would disable the control for everyone for a
+     * beat.
+     */
+    blocked: boolean;
+    /** The reason to show when `blocked`, else `undefined`. */
+    reason?: string;
+}
+/**
+ * The viewer's standing against the set of roles a route admits (AGL-2131,
+ * moved out of the console app by AGL-3080 so a plugin's staff page can ask
+ * the same question).
+ *
+ * Pure, and takes the role rather than reading it: the claim lives in the
+ * app's session, and a staff page the shell mounts is handed the resolved
+ * value. `null` means "still reading the token", and it is also what a
+ * non-staff viewer resolves to — who never reaches an `/admin` page at all,
+ * because the staff gate 404s them first. Treating both as unresolved is
+ * therefore right for the only population that gets here.
+ *
+ * Not every gated act is super-only: `/api/admin/org-override` admits
+ * `billing` for plan and quota writes and reserves only `releaseFlags` for
+ * `super`. A gate that could only say "super" would disable that dialog for
+ * the role whose entire purpose it is — trading one dishonest control for
+ * another.
+ */
+export declare function resolveStaffRoleGate(role: string | null | undefined, allowed: readonly string[]): StaffRoleGate;
+/** The single sentence every blocked super-only control says. */
+export declare const SUPER_STAFF_ONLY_REASON = "This action requires the super staff role. Ask someone who holds it.";

package/src/lib/app-utils/staff-role-gate.js

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * The viewer's standing against the set of roles a route admits (AGL-2131,
+ * moved out of the console app by AGL-3080 so a plugin's staff page can ask
+ * the same question).
+ *
+ * Pure, and takes the role rather than reading it: the claim lives in the
+ * app's session, and a staff page the shell mounts is handed the resolved
+ * value. `null` means "still reading the token", and it is also what a
+ * non-staff viewer resolves to — who never reaches an `/admin` page at all,
+ * because the staff gate 404s them first. Treating both as unresolved is
+ * therefore right for the only population that gets here.
+ *
+ * Not every gated act is super-only: `/api/admin/org-override` admits
+ * `billing` for plan and quota writes and reserves only `releaseFlags` for
+ * `super`. A gate that could only say "super" would disable that dialog for
+ * the role whose entire purpose it is — trading one dishonest control for
+ * another.
+ */ export function resolveStaffRoleGate(role, allowed) {
+    const ready = role !== null && role !== undefined;
+    const admitted = ready && allowed.includes(String(role));
+    const blocked = ready && !admitted;
+    return {
+        ready,
+        admitted,
+        blocked,
+        reason: blocked ? `This action requires the ${allowed.join(' or ')} staff role. ` + 'Ask someone who holds it.' : undefined
+    };
+}
+/** The single sentence every blocked super-only control says. */ export const SUPER_STAFF_ONLY_REASON = 'This action requires the super staff role. Ask someone who holds it.';
+
+//# sourceMappingURL=staff-role-gate.js.map

package/src/lib/app-utils/staff-role-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/staff-role-gate.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexport interface StaffRoleGate {\n  /**\n   * `false` while the claim is still resolving. Nothing may be BLOCKED in\n   * that window: rendering a refusal there would flash a disabled button at\n   * every super-staff member on every admin page load.\n   */\n  ready: boolean\n  /** Whether the viewer's role is one the route admits. `false` until `ready`. */\n  admitted: boolean\n  /**\n   * The one thing call sites branch on: a RESOLVED claim the route would\n   * refuse. Deliberately not `!admitted` — that is true during the\n   * unresolved window too, and would disable the control for everyone for a\n   * beat.\n   */\n  blocked: boolean\n  /** The reason to show when `blocked`, else `undefined`. */\n  reason?: string\n}\n\n/**\n * The viewer's standing against the set of roles a route admits (AGL-2131,\n * moved out of the console app by AGL-3080 so a plugin's staff page can ask\n * the same question).\n *\n * Pure, and takes the role rather than reading it: the claim lives in the\n * app's session, and a staff page the shell mounts is handed the resolved\n * value. `null` means \"still reading the token\", and it is also what a\n * non-staff viewer resolves to — who never reaches an `/admin` page at all,\n * because the staff gate 404s them first. Treating both as unresolved is\n * therefore right for the only population that gets here.\n *\n * Not every gated act is super-only: `/api/admin/org-override` admits\n * `billing` for plan and quota writes and reserves only `releaseFlags` for\n * `super`. A gate that could only say \"super\" would disable that dialog for\n * the role whose entire purpose it is — trading one dishonest control for\n * another.\n */\nexport function resolveStaffRoleGate(\n  role: string | null | undefined,\n  allowed: readonly string[],\n): StaffRoleGate {\n  const ready = role !== null && role !== undefined\n  const admitted = ready && allowed.includes(String(role))\n  const blocked = ready && !admitted\n  return {\n    ready,\n    admitted,\n    blocked,\n    reason: blocked\n      ? `This action requires the ${allowed.join(' or ')} staff role. ` +\n        'Ask someone who holds it.'\n      : undefined,\n  }\n}\n\n/** The single sentence every blocked super-only control says. */\nexport const SUPER_STAFF_ONLY_REASON =\n  'This action requires the super staff role. Ask someone who holds it.'\n"],"names":["resolveStaffRoleGate","role","allowed","ready","undefined","admitted","includes","String","blocked","reason","join","SUPER_STAFF_ONLY_REASON"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAsBD;;;;;;;;;;;;;;;;;CAiBC,GACD,OAAO,SAASA,qBACdC,IAA+B,EAC/BC,OAA0B;IAE1B,MAAMC,QAAQF,SAAS,QAAQA,SAASG;IACxC,MAAMC,WAAWF,SAASD,QAAQI,QAAQ,CAACC,OAAON;IAClD,MAAMO,UAAUL,SAAS,CAACE;IAC1B,OAAO;QACLF;QACAE;QACAG;QACAC,QAAQD,UACJ,CAAC,yBAAyB,EAAEN,QAAQQ,IAAI,CAAC,QAAQ,aAAa,CAAC,GAC/D,8BACAN;IACN;AACF;AAEA,+DAA+D,GAC/D,OAAO,MAAMO,0BACX,uEAAsE"}

package/src/lib/plugin-manager/feature-plugins.d.ts

@@ -1242,6 +1242,48 @@ export interface ConsoleUpgradeNotice {
 export interface ConsoleStaffPageProps {
     /** The page's own console path, `/admin/{id}`. */
     basePath: string;
+    /**
+     * Path segments beneath {@link basePath}, `[]` on the page's own URL
+     * (AGL-3080). Only ever non-empty for a page that declared
+     * {@link ConsoleStaffPage.ownsSubtree}.
+     *
+     * The staff twin of {@link ConsolePluginPageProps.segments}, and for the
+     * same case: a queue is a list, and a row of it is a page. A staff page
+     * without this could only ever BE the list.
+     */
+    segments?: readonly string[];
+    /**
+     * The viewer's staff ROLE, or `null` while the claim is still resolving
+     * (AGL-3080).
+     *
+     * Not every staff act is open to every staff role — six are `super`-only
+     * on the server — and a page that cannot tell renders live controls to a
+     * `support` engineer who clicks them and gets a raw 403. Pass it to
+     * `resolveStaffRoleGate` and render the verdict with
+     * `BlockedControl`; `null` must never be treated as a refusal, or every
+     * page flashes a disabled button at the people who may use it.
+     *
+     * ⚠️ NOT the boundary. The routes verify the decoded token per request and
+     * refuse regardless of what rendered. This exists so the console stops
+     * promising what the server will refuse.
+     */
+    staffRole?: string | null;
+    /**
+     * Console destinations a staff page may link ACROSS to, built by the shell
+     * (AGL-3080) — the staff twin of {@link ConsolePluginOrgMount}'s paths,
+     * and for the same reason: a plugin cannot import the console's route
+     * table, and a plugin that rebuilt one of these from a string would break
+     * silently the day the console moved it.
+     */
+    staffPaths?: ConsoleStaffPagePaths;
+}
+export interface ConsoleStaffPagePaths {
+    /**
+     * The staff console's page for one workspace. `undefined` on a deployment
+     * that has no such page, which a caller renders as no link rather than a
+     * dead one.
+     */
+    orgDetail(orgId: string): string | undefined;
 }
 /**
  * A page a plugin adds to the STAFF area (AGL-2939): a tab in the staff
@@ -1274,6 +1316,25 @@ export interface ConsoleStaffPage {
         icon?: MdiIconProps;
         docsTopic?: string;
     };
+    /**
+     * Whether this page claims every path beneath `/admin/{id}` too
+     * (AGL-3080) — the staff twin of {@link ConsoleNavItem.ownsSubtree}, with
+     * the same trade and the same duty.
+     *
+     * The case is a staff QUEUE: the list is the page, and each row opens one
+     * submission. The set of ids is a property of the data, so no static list
+     * could enumerate them, and without this every row's URL is a 404.
+     *
+     * A page that claims its subtree can no longer tell a typo from an id, so
+     * it takes on saying "no such thing" itself — which a queue has to be able
+     * to do anyway for a submission withdrawn while a link to it was still in
+     * a reviewer's inbox.
+     *
+     * The console's own staff routes keep winning their segments either way:
+     * a static path beats a dynamic one segment by segment, so `/admin/orgs/1`
+     * is still the orgs route and never a staff page's subtree.
+     */
+    ownsSubtree?: boolean;
     Component: ComponentType<ConsoleStaffPageProps>;
 }
 export interface ConsoleExtension {