@cosmicdrift/kumiko-bundled-features 0.328.0 → 0.329.0

package/dist/admin-shell/constants.d.ts

@@ -0,0 +1,7 @@
+export declare const ADMIN_SHELL_FEATURE: "admin-shell";
+export declare const DEFAULT_TENANT_WORKSPACE_ID: "tenant-admin";
+export declare const DEFAULT_PLATFORM_WORKSPACE_ID: "platform";
+/** Tenant workspace home — attention cards, query-allowlisted. */
+export declare const TENANT_OVERVIEW_SCREEN_ID: "tenant-overview";
+/** Platform workspace home — attention cards, query-allowlisted. */
+export declare const PLATFORM_OVERVIEW_SCREEN_ID: "platform-overview";

package/dist/admin-shell/constants.js

@@ -0,0 +1,8 @@
+// @runtime client
+export const ADMIN_SHELL_FEATURE = "admin-shell";
+export const DEFAULT_TENANT_WORKSPACE_ID = "tenant-admin";
+export const DEFAULT_PLATFORM_WORKSPACE_ID = "platform";
+/** Tenant workspace home — attention cards, query-allowlisted. */
+export const TENANT_OVERVIEW_SCREEN_ID = "tenant-overview";
+/** Platform workspace home — attention cards, query-allowlisted. */
+export const PLATFORM_OVERVIEW_SCREEN_ID = "platform-overview";

package/dist/admin-shell/feature.d.ts

@@ -0,0 +1,17 @@
+import { type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+export type CreateAdminShellOptions = {
+    /** Short workspace id for tenant operators (URL segment). Default `tenant-admin`. */
+    readonly workspaceIds?: {
+        readonly tenant?: string;
+        readonly platform?: string;
+    };
+    /** Platform nav → tier-engine:screen:tier-admin. Requires tier-engine mounted. Default true. */
+    readonly includeTierAdmin?: boolean;
+    /** Tenant nav → cap-overview:screen:my-caps, platform nav → cap-overview:screen:tenant-cap-list.
+     *  Requires cap-overview mounted. Default false — apps that don't mount cap-overview
+     *  must not get a nav entry pointing at a screen that doesn't exist. */
+    readonly includeCapOverview?: boolean;
+    /** When false, only overview screens + nav are registered — app owns r.workspace(). Default true. */
+    readonly registerWorkspaces?: boolean;
+};
+export declare function createAdminShellFeature(options?: CreateAdminShellOptions): FeatureDefinition;

package/dist/admin-shell/feature.js

@@ -0,0 +1,182 @@
+// admin-shell — role-gated workspaces + provider nav for tenant vs platform operators.
+// Screens live in owner features (tenant, audit, jobs, …); this feature only
+// composes workspaces and cross-feature nav entries.
+import { access, defineFeature, } from "@cosmicdrift/kumiko-framework/engine";
+import { ConfigQueries } from "../config/index.js";
+import { JobQueries } from "../jobs/index.js";
+import { TenantQueries } from "../tenant/index.js";
+import { UserQueries } from "../user/index.js";
+import { ADMIN_SHELL_FEATURE, DEFAULT_PLATFORM_WORKSPACE_ID, DEFAULT_TENANT_WORKSPACE_ID, PLATFORM_OVERVIEW_SCREEN_ID, TENANT_OVERVIEW_SCREEN_ID, } from "./constants.js";
+import { ADMIN_SHELL_I18N } from "./i18n.js";
+export function createAdminShellFeature(options = {}) {
+    const tenantWsId = options.workspaceIds?.tenant ?? DEFAULT_TENANT_WORKSPACE_ID;
+    const platformWsId = options.workspaceIds?.platform ?? DEFAULT_PLATFORM_WORKSPACE_ID;
+    const includeTierAdmin = options.includeTierAdmin ?? true;
+    const includeCapOverview = options.includeCapOverview ?? false;
+    const registerWorkspaces = options.registerWorkspaces ?? true;
+    return defineFeature(ADMIN_SHELL_FEATURE, (r) => {
+        r.describe("Registers tenant-admin and platform-admin workspaces with provider nav into owner-feature screens (`tenant:screen:members`, `audit:screen:audit-log`, `tenant:screen:tenant-list`, `jobs:screen:job-runs`, optional `tier-engine:screen:tier-admin`, optional `cap-overview:screen:my-caps`/`cap-overview:screen:tenant-cap-list`). Mount after user, tenant, audit, and jobs; pass `workspaceIds` to match app URL conventions (e.g. Studio `d`/`s`, PublicStatus `admin`/`sysadmin`). Client: `adminShellClient()`, `tenantClient()`, `auditClient()`, `jobsClient()`, optional `tierEngineClient()`.");
+        r.uiHints({
+            displayLabel: "Admin Shell",
+            category: "operations",
+            recommended: false,
+        });
+        r.requires("user");
+        r.requires("tenant");
+        r.requires("audit");
+        r.requires("jobs");
+        if (includeTierAdmin)
+            r.requires("tier-engine");
+        if (includeCapOverview)
+            r.requires("cap-overview");
+        r.translations({ keys: ADMIN_SHELL_I18N });
+        const tenantNav = [
+            "admin-shell:nav:tenant-overview",
+            "tenant:nav:members",
+            "audit:nav:audit-log",
+            ...(includeCapOverview ? ["admin-shell:nav:my-caps"] : []),
+        ];
+        const platformNav = [
+            "admin-shell:nav:platform-overview",
+            "admin-shell:nav:tenants",
+            ...(includeCapOverview ? ["admin-shell:nav:tenant-caps"] : []),
+            "jobs:nav:job-runs",
+            ...(includeTierAdmin ? ["admin-shell:nav:tier-admin"] : []),
+        ];
+        r.screen({
+            id: TENANT_OVERVIEW_SCREEN_ID,
+            type: "dashboard",
+            access: { roles: access.admin },
+            description: "Landing page of the tenant-admin workspace, showing pending invitation, member and missing-config counts for the caller's own tenant so an operator sees what needs attention there.",
+            panels: [
+                {
+                    kind: "stat",
+                    id: "pending-invitations",
+                    label: "admin-shell:overview.pendingInvitations",
+                    query: TenantQueries.invitations,
+                    // tenant:query:invitations returns a bare array, not a paged
+                    // envelope — "length" reads record["length"], i.e. the array's
+                    // own .length. Not a typo.
+                    valueField: "length",
+                },
+                {
+                    kind: "stat",
+                    id: "members",
+                    label: "admin-shell:overview.members",
+                    query: TenantQueries.members,
+                    // Same array-shaped response as invitations above.
+                    valueField: "length",
+                },
+                {
+                    kind: "stat",
+                    id: "missing-config",
+                    label: "admin-shell:overview.missingConfig",
+                    query: ConfigQueries.readiness,
+                    valueField: "missingCount",
+                    toneField: "missingTone",
+                },
+            ],
+        });
+        r.nav({
+            id: "tenant-overview",
+            label: "admin-shell:nav.tenantOverview",
+            icon: "home",
+            screen: "admin-shell:screen:tenant-overview",
+            order: 1,
+        });
+        r.screen({
+            id: PLATFORM_OVERVIEW_SCREEN_ID,
+            type: "dashboard",
+            access: { roles: access.systemAdmin },
+            description: "Landing page of the platform-admin workspace, showing installation-wide tenant, user and failed-job counts so a system admin sees the health of the whole deployment at a glance.",
+            panels: [
+                {
+                    kind: "stat",
+                    id: "tenants",
+                    label: "admin-shell:overview.tenants",
+                    query: TenantQueries.list,
+                    params: { totalCount: true },
+                    valueField: "total",
+                },
+                {
+                    kind: "stat",
+                    id: "users",
+                    label: "admin-shell:overview.users",
+                    query: UserQueries.list,
+                    params: { totalCount: true },
+                    valueField: "total",
+                },
+                {
+                    kind: "stat",
+                    id: "failed-jobs",
+                    label: "admin-shell:overview.failedJobs",
+                    query: JobQueries.list,
+                    params: { status: "failed", totalCount: true },
+                    valueField: "total",
+                },
+            ],
+        });
+        r.nav({
+            id: "platform-overview",
+            label: "admin-shell:nav.platformOverview",
+            icon: "dashboard",
+            screen: "admin-shell:screen:platform-overview",
+            order: 1,
+        });
+        r.nav({
+            id: "tenants",
+            label: "admin-shell:nav.tenants",
+            icon: "building",
+            screen: "tenant:screen:tenant-list",
+            access: { roles: access.systemAdmin },
+            order: 10,
+        });
+        if (includeTierAdmin) {
+            r.nav({
+                id: "tier-admin",
+                label: "admin-shell:nav.tierAdmin",
+                icon: "shield",
+                screen: "tier-engine:screen:tier-admin",
+                access: { roles: access.systemAdmin },
+                order: 30,
+            });
+        }
+        if (includeCapOverview) {
+            r.nav({
+                id: "my-caps",
+                label: "admin-shell:nav.myCaps",
+                icon: "gauge",
+                screen: "cap-overview:screen:my-caps",
+                access: { roles: access.admin },
+                order: 20,
+            });
+            r.nav({
+                id: "tenant-caps",
+                label: "admin-shell:nav.tenantCaps",
+                icon: "gauge",
+                screen: "cap-overview:screen:tenant-cap-list",
+                access: { roles: access.systemAdmin },
+                order: 20,
+            });
+        }
+        if (registerWorkspaces) {
+            r.workspace({
+                id: tenantWsId,
+                label: "admin-shell:workspace.tenant",
+                icon: "users",
+                order: 1,
+                access: { roles: access.admin },
+                nav: [...tenantNav],
+                default: true,
+            });
+            r.workspace({
+                id: platformWsId,
+                label: "admin-shell:workspace.platform",
+                icon: "shield",
+                order: 2,
+                access: { roles: access.systemAdmin },
+                nav: platformNav,
+            });
+        }
+    });
+}

package/dist/admin-shell/i18n.d.ts

@@ -0,0 +1,5 @@
+type LocalizedString = {
+    readonly en: string;
+};
+export declare const ADMIN_SHELL_I18N: Readonly<Record<string, LocalizedString>>;
+export {};

package/dist/admin-shell/i18n.js

@@ -0,0 +1,25 @@
+// @runtime client
+// Pure-Data i18n keys for admin-shell (server r.translations + client pivot).
+// Without these keys nav labels and workspace tabs render raw QNs in the shell.
+export const ADMIN_SHELL_I18N = {
+    "screen:tenant-overview.title": { en: "Overview" },
+    "screen:platform-overview.title": { en: "Overview" },
+    "admin-shell:workspace.tenant": { en: "Administration" },
+    "admin-shell:workspace.platform": { en: "Platform" },
+    "admin-shell:nav.tenantOverview": { en: "Overview" },
+    "admin-shell:nav.platformOverview": { en: "Overview" },
+    "admin-shell:nav.tenants": { en: "Tenants" },
+    "admin-shell:nav.tierAdmin": { en: "Assign tier" },
+    "admin-shell:nav.myCaps": { en: "Plans & Caps" },
+    "admin-shell:nav.tenantCaps": { en: "Plans & Caps" },
+    "admin-shell:overview.pendingInvitations": {
+        en: "Pending invitations",
+    },
+    "admin-shell:overview.members": { en: "Members" },
+    "admin-shell:overview.missingConfig": {
+        en: "Missing configuration",
+    },
+    "admin-shell:overview.tenants": { en: "Tenants" },
+    "admin-shell:overview.users": { en: "Users" },
+    "admin-shell:overview.failedJobs": { en: "Failed jobs" },
+};

package/dist/admin-shell/index.d.ts

@@ -0,0 +1,4 @@
+export { ADMIN_SHELL_FEATURE, DEFAULT_PLATFORM_WORKSPACE_ID, DEFAULT_TENANT_WORKSPACE_ID, PLATFORM_OVERVIEW_SCREEN_ID, TENANT_OVERVIEW_SCREEN_ID, } from "./constants.js";
+export { type CreateAdminShellOptions, createAdminShellFeature } from "./feature.js";
+export { ADMIN_SHELL_I18N } from "./i18n.js";
+export { isOverviewQueryAllowed, type OverviewWorkspaceKind, overviewAllowedQueries, PLATFORM_OVERVIEW_ALLOWED_QUERIES, TENANT_OVERVIEW_ALLOWED_QUERIES, TENANT_OVERVIEW_FORBIDDEN_QUERIES, } from "./overview-allowlist.js";

package/dist/admin-shell/index.js

@@ -0,0 +1,4 @@
+export { ADMIN_SHELL_FEATURE, DEFAULT_PLATFORM_WORKSPACE_ID, DEFAULT_TENANT_WORKSPACE_ID, PLATFORM_OVERVIEW_SCREEN_ID, TENANT_OVERVIEW_SCREEN_ID, } from "./constants.js";
+export { createAdminShellFeature } from "./feature.js";
+export { ADMIN_SHELL_I18N } from "./i18n.js";
+export { isOverviewQueryAllowed, overviewAllowedQueries, PLATFORM_OVERVIEW_ALLOWED_QUERIES, TENANT_OVERVIEW_ALLOWED_QUERIES, TENANT_OVERVIEW_FORBIDDEN_QUERIES, } from "./overview-allowlist.js";

package/dist/admin-shell/overview-allowlist.d.ts

@@ -0,0 +1,9 @@
+export type OverviewWorkspaceKind = "tenant" | "platform";
+/** Tenant workspace overview may only call these queries. */
+export declare const TENANT_OVERVIEW_ALLOWED_QUERIES: readonly ["tenant:query:invitations", "tenant:query:members", "config:query:readiness", "cap-counter:query:get-counter"];
+/** Platform workspace overview may only call these queries. */
+export declare const PLATFORM_OVERVIEW_ALLOWED_QUERIES: readonly ["tenant:query:list", "jobs:query:list", "user:query:user:list"];
+/** Regression guard — TenantAdmin overview must never touch these (HTTP 403). */
+export declare const TENANT_OVERVIEW_FORBIDDEN_QUERIES: readonly ["tenant:query:list", "jobs:query:list", "feature-toggles:query:list", "feature-toggles:query:registered", "user:query:user:list"];
+export declare function overviewAllowedQueries(kind: OverviewWorkspaceKind): readonly string[];
+export declare function isOverviewQueryAllowed(kind: OverviewWorkspaceKind, queryName: string): boolean;

package/dist/admin-shell/overview-allowlist.js

@@ -0,0 +1,30 @@
+// @runtime client
+// Hard-coded query allowlists for overview-home screens — security boundary
+// against privilege escalation via accidental cross-workspace fetches.
+/** Tenant workspace overview may only call these queries. */
+export const TENANT_OVERVIEW_ALLOWED_QUERIES = [
+    "tenant:query:invitations",
+    "tenant:query:members",
+    "config:query:readiness",
+    "cap-counter:query:get-counter",
+];
+/** Platform workspace overview may only call these queries. */
+export const PLATFORM_OVERVIEW_ALLOWED_QUERIES = [
+    "tenant:query:list",
+    "jobs:query:list",
+    "user:query:user:list",
+];
+/** Regression guard — TenantAdmin overview must never touch these (HTTP 403). */
+export const TENANT_OVERVIEW_FORBIDDEN_QUERIES = [
+    "tenant:query:list",
+    "jobs:query:list",
+    "feature-toggles:query:list",
+    "feature-toggles:query:registered",
+    "user:query:user:list",
+];
+export function overviewAllowedQueries(kind) {
+    return kind === "tenant" ? TENANT_OVERVIEW_ALLOWED_QUERIES : PLATFORM_OVERVIEW_ALLOWED_QUERIES;
+}
+export function isOverviewQueryAllowed(kind, queryName) {
+    return overviewAllowedQueries(kind).includes(queryName);
+}

package/dist/admin-shell/web/client-plugin.d.ts

@@ -0,0 +1,6 @@
+import { type TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+export type AdminShellClientOptions = {
+    readonly translations?: TranslationsByLocale;
+};
+export declare function adminShellClient(options?: AdminShellClientOptions): ClientFeatureDefinition;

package/dist/admin-shell/web/client-plugin.js

@@ -0,0 +1,10 @@
+// @runtime client
+import { mergeTranslations } from "@cosmicdrift/kumiko-renderer";
+import { ADMIN_SHELL_FEATURE } from "../constants.js";
+import { defaultTranslations } from "./i18n.js";
+export function adminShellClient(options) {
+    return {
+        name: ADMIN_SHELL_FEATURE,
+        translations: mergeTranslations(defaultTranslations, options?.translations ?? {}),
+    };
+}

package/dist/admin-shell/web/i18n.d.ts

@@ -0,0 +1,2 @@
+import { type TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+export declare const defaultTranslations: TranslationsByLocale;

package/dist/admin-shell/web/i18n.js

@@ -0,0 +1,5 @@
+// @runtime client
+// Client pivot of ADMIN_SHELL_I18N — same keys as server r.translations bundle.
+import { translationsByLocaleFromKeys, } from "@cosmicdrift/kumiko-renderer";
+import { ADMIN_SHELL_I18N } from "../i18n.js";
+export const defaultTranslations = translationsByLocaleFromKeys(ADMIN_SHELL_I18N);

package/dist/admin-shell/web/index.d.ts

@@ -0,0 +1 @@
+export { type AdminShellClientOptions, adminShellClient } from "./client-plugin.js";

package/dist/admin-shell/web/index.js

@@ -0,0 +1,2 @@
+// @runtime client
+export { adminShellClient } from "./client-plugin.js";

package/dist/agent-tools/agent-doc-lint.d.ts

@@ -0,0 +1,15 @@
+import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+export declare const AgentDocGapKinds: {
+    readonly handlerWithoutDescription: "handler-without-description";
+    readonly customScreenWithoutDescription: "custom-screen-without-description";
+    readonly exposedEntityWithoutDescription: "exposed-entity-without-description";
+};
+export type AgentDocGapKind = (typeof AgentDocGapKinds)[keyof typeof AgentDocGapKinds];
+export type AgentDocGap = {
+    readonly qn: string;
+    readonly feature: string;
+    readonly kind: AgentDocGapKind;
+    readonly message: string;
+};
+export declare function findAgentDocGaps(features: readonly FeatureDefinition[]): readonly AgentDocGap[];
+export declare function formatAgentDocGap(gap: AgentDocGap): string;

package/dist/agent-tools/agent-doc-lint.js

@@ -0,0 +1,94 @@
+import { isAgentVisibleScreen, QnTypes, qn, resolveAgentExposure, toKebab, } from "@cosmicdrift/kumiko-framework/engine";
+export const AgentDocGapKinds = {
+    handlerWithoutDescription: "handler-without-description",
+    customScreenWithoutDescription: "custom-screen-without-description",
+    exposedEntityWithoutDescription: "exposed-entity-without-description",
+};
+// No shared screen-type union exists in the codebase to import (ScreenDefinition
+// is a discriminated union keyed by inline string literals) — name the one
+// value this lint cares about instead of comparing against a bare string.
+const CUSTOM_SCREEN_TYPE = "custom";
+const ENTITY_QN_SEGMENT = "entity";
+// QNs contain `:`, so localeCompare's ICU punctuation rules would make sort
+// order depend on runtime locale — compare by code point instead (same
+// reasoning as agent-manifest.ts's compareIds).
+function compareByCodePoint(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function handlerDocGaps(feature, handlers, handlerQnType, handlerNoun) {
+    const gaps = [];
+    for (const [name, def] of Object.entries(handlers)) {
+        if (def.description !== undefined || def.agent?.expose === false)
+            continue;
+        gaps.push({
+            qn: qn(toKebab(feature.name), handlerQnType, toKebab(name)),
+            feature: feature.name,
+            kind: AgentDocGapKinds.handlerWithoutDescription,
+            message: `This ${handlerNoun} has no description, so it stays invisible to the AI agent — set \`description\` to expose it, or \`agent: { expose: false }\` to opt out deliberately.`,
+        });
+    }
+    return gaps;
+}
+function screenDocGaps(feature) {
+    const gaps = [];
+    for (const [shortId, screen] of Object.entries(feature.screens ?? {})) {
+        if (screen.type !== CUSTOM_SCREEN_TYPE ||
+            screen.description !== undefined ||
+            !isAgentVisibleScreen(screen))
+            continue;
+        gaps.push({
+            qn: qn(toKebab(feature.name), QnTypes.screen, toKebab(shortId)),
+            feature: feature.name,
+            kind: AgentDocGapKinds.customScreenWithoutDescription,
+            message: "This custom screen has no description, so the AI agent can't tell what it's for — set `description` to explain it, or `agent: { expose: false }` to hide it from the agent deliberately.",
+        });
+    }
+    return gaps;
+}
+// The handlerEntityMappings record can't distinguish write from query
+// namespaces (both share one short-name-keyed map), so both must be probed
+// per mapped handler name.
+function agentVisibleEntityNames(feature) {
+    const entityNames = new Set();
+    for (const [handlerName, entityName] of Object.entries(feature.handlerEntityMappings ?? {})) {
+        const writeDef = feature.writeHandlers?.[handlerName];
+        if (writeDef && resolveAgentExposure(writeDef, "write").expose)
+            entityNames.add(entityName);
+        const queryDef = feature.queryHandlers?.[handlerName];
+        if (queryDef && resolveAgentExposure(queryDef, "query").expose)
+            entityNames.add(entityName);
+    }
+    return entityNames;
+}
+function exposedEntityDocGaps(feature) {
+    const gaps = [];
+    for (const entityName of agentVisibleEntityNames(feature)) {
+        const entity = feature.entities?.[entityName];
+        if (!entity || entity.description !== undefined)
+            continue;
+        gaps.push({
+            // Registry keeps entities under their raw, non-kebab name (unlike
+            // handlers/screens) — qn() would throw on a camelCase segment.
+            qn: `${toKebab(feature.name)}:${ENTITY_QN_SEGMENT}:${entityName}`,
+            feature: feature.name,
+            kind: AgentDocGapKinds.exposedEntityWithoutDescription,
+            message: "This entity is reachable through an agent-visible handler, but the agent can't explain its schema — set `description` to describe it.",
+        });
+    }
+    return gaps;
+}
+export function findAgentDocGaps(features) {
+    const gaps = [];
+    for (const feature of features) {
+        gaps.push(...handlerDocGaps(feature, feature.writeHandlers ?? {}, QnTypes.write, "write handler"));
+        gaps.push(...handlerDocGaps(feature, feature.queryHandlers ?? {}, QnTypes.query, "query handler"));
+        gaps.push(...screenDocGaps(feature));
+        gaps.push(...exposedEntityDocGaps(feature));
+    }
+    // Map/Record iteration follows feature-mount order; the result must not
+    // depend on it (mirrors agent-manifest.ts's sortedByKey rationale).
+    return [...gaps].sort((a, b) => compareByCodePoint(a.qn, b.qn));
+}
+export function formatAgentDocGap(gap) {
+    return `${gap.qn} — ${gap.message}`;
+}

package/dist/agent-tools/agent-manifest.d.ts

@@ -0,0 +1,5 @@
+import type { AgentManifest, AgentManifestOptions, RegistryManifestView } from "./types.js";
+/** Registry snapshot → AI-agent manifest. Pure, deterministic, no I/O — mirrors
+ *  `buildToolCatalog`'s contract, just describing the app's shape instead of
+ *  generating callable tools from it. */
+export declare function buildAgentManifest(registry: RegistryManifestView, options: AgentManifestOptions): AgentManifest;