@k2b/cloud 0.6.0-rc.0

package/src/api/help.ts

@@ -0,0 +1,78 @@
+import { Hono, type MiddlewareHandler } from "hono";
+import { createHelpCatalog, findHelpDocument, resolveAppHelp, searchHelpCatalog } from "../_internal/help-catalog";
+import { getApp, getHelp } from "../_internal/registry";
+import type { AppRegistryEntry, HelpRegistryEntry } from "../contracts/registry";
+import { type AuthContext, auth, getLocale } from "../server";
+import type { HelpDocumentPayload, HelpSearchPayload } from "../shared/help";
+import { renderHelpMarkdown } from "../shared/markdown";
+import { type HelpApiMessages, helpApiMessages } from "./help-messages";
+
+export type HelpRouteDependencies = {
+  getApp?: (appId: string) => Promise<AppRegistryEntry | null>;
+  getHelp?: (appId: string) => Promise<HelpRegistryEntry | null>;
+  authenticate?: MiddlewareHandler<AuthContext>;
+  renderMarkdown?: (markdown: string) => string;
+};
+
+const resolveHelp = async (appId: string, dependencies: HelpRouteDependencies, t: HelpApiMessages) => {
+  const resolved = await resolveAppHelp(appId, { getApp: dependencies.getApp ?? getApp, getHelp: dependencies.getHelp ?? getHelp });
+  if (resolved.status === "missing") {
+    return Response.json({ code: "APP_UNAVAILABLE", message: t.unavailable({ appId }) }, { status: 404 });
+  }
+  if (resolved.status === "stale") {
+    return Response.json({ code: "HELP_STALE", message: t.stale({ appId }) }, { status: 503 });
+  }
+  return resolved;
+};
+
+export const createHelpRoutes = (dependencies: HelpRouteDependencies = {}) => {
+  const renderedByApp = new Map<string, { manifestHash: string; documents: Map<string, string> }>();
+  const renderMarkdown = dependencies.renderMarkdown ?? renderHelpMarkdown;
+  const renderDocument = (help: HelpRegistryEntry, locale: string, documentId: string, markdown: string): string => {
+    let cached = renderedByApp.get(help.appId);
+    if (!cached || cached.manifestHash !== help.manifestHash) {
+      cached = { manifestHash: help.manifestHash, documents: new Map() };
+      renderedByApp.set(help.appId, cached);
+    }
+    const cacheKey = `${locale}:${documentId}`;
+    const html = cached.documents.get(cacheKey);
+    if (html !== undefined) return html;
+    const rendered = renderMarkdown(markdown);
+    cached.documents.set(cacheKey, rendered);
+    return rendered;
+  };
+
+  return new Hono<AuthContext>()
+    .use(dependencies.authenticate ?? auth.requireRole("*"))
+    .get("/help/v1/:appId/search", async (c) => {
+      const locale = getLocale(c);
+      const { t } = helpApiMessages.resolve([locale]);
+      const resolved = await resolveHelp(c.req.param("appId"), dependencies, t);
+      if (resolved instanceof Response) return resolved;
+      const query = c.req.query("q")?.trim().slice(0, 200) ?? "";
+      const catalog = createHelpCatalog([resolved.help], locale);
+      const payload: HelpSearchPayload = {
+        locale: catalog[0]?.locale ?? resolved.help.baseLocale ?? "en",
+        ids: query ? searchHelpCatalog(catalog, { query, appId: resolved.app.id, limit: 25 }).map((document) => document.documentId) : [],
+      };
+      return c.json(payload);
+    })
+    .get("/help/v1/:appId/documents/:documentId", async (c) => {
+      const locale = getLocale(c);
+      const { t } = helpApiMessages.resolve([locale]);
+      const resolved = await resolveHelp(c.req.param("appId"), dependencies, t);
+      if (resolved instanceof Response) return resolved;
+      const document = findHelpDocument(createHelpCatalog([resolved.help], locale), resolved.app.id, c.req.param("documentId"));
+      if (!document) return c.json({ code: "HELP_NOT_FOUND", message: t.notFound }, 404);
+      const payload: HelpDocumentPayload = {
+        locale: document.locale,
+        id: document.documentId,
+        title: document.title,
+        markdown: document.markdown,
+        html: renderDocument(resolved.help, document.locale, document.documentId, document.markdown),
+      };
+      return c.json(payload);
+    });
+};
+
+export type HelpApiType = ReturnType<typeof createHelpRoutes>;

package/src/api/index.ts

@@ -0,0 +1,108 @@
+/**
+ * Core platform API surface — owned by cloud-lib, mounted by the core-app.
+ *
+ * Lives here (not in an app) because every container shares the same auth
+ * model, self-service shape, lifecycle controls and entity search; redefining
+ * any of these per-app would break the platform invariant.
+ *
+ * Apps that need a typed client to these routes import from
+ * `@k2b/cloud/clients/core`. The client and the routes share their
+ * type via `CoreApiType` below.
+ *
+ * The OpenAPI spec for these routes is generated by `defineApp` (driven by
+ * core's `openapi: "/api/openapi.json"` opt-in) — this file no longer mounts
+ * any docs UI; the api-docs aggregator at `/app/api-docs` is the only consumer.
+ */
+import { Hono } from "hono";
+import { prettyJSON } from "hono/pretty-json";
+import { createAiApprovalPreferenceRoutes } from "../ai/approval-routes";
+import { aiProjectsRoutes } from "../ai/projects-routes";
+import { aiRoutes } from "../ai/routes";
+import { aiSkillsRoutes } from "../ai/skills-routes";
+import accountsEntitiesRoutes from "./accounts-entities";
+import adminAiUsageRoutes from "./admin-ai-usage";
+import adminAiProjectsRoutes from "./admin-ai-projects";
+import adminAiSkillsRoutes from "./admin-ai-skills";
+import adminCoreSettingsRoutes from "./admin-core-settings";
+import adminIdentityRoutes from "./admin-identity";
+import adminLifecycleRoutes from "./admin-lifecycle";
+import adminLinuxIdentityRoutes from "./admin-linux-identities";
+import { adminAnnouncementRoutes, announcementRoutes } from "./announcements";
+import { appDiscoveryRoutes } from "./apps";
+import { createAuthRoutes } from "./auth";
+import { createAppApprovalRoutes } from "./app-approval";
+import { createCapabilityRoutes } from "./capabilities";
+import { createHelpRoutes } from "./help";
+import { createMcpRoutes } from "./mcp";
+import meRoutes from "./me";
+import { createSearchRoutes } from "./search";
+import { createSyncOpsProxyRoutes } from "./sync-ops";
+import { createWidgetRoutes } from "./widgets";
+
+export { type CapabilityDispatchDependencies, dispatchCapability } from "./capabilities";
+
+/**
+ * Single-expression chain so `typeof buildCoreApi()` captures every route's
+ * input/output. Splitting into `new Hono()` + `.route(...)` calls would erase
+ * the typed shape for the client.
+ */
+export type CoreApiOptions = {
+  notifications: import("../services/auth-flows/notification-sender").AuthNotificationSender;
+};
+
+const buildCoreApi = (options: CoreApiOptions) => {
+  const searchRoutes = createSearchRoutes();
+  const capabilityRoutes = createCapabilityRoutes();
+  const mcpRoutes = createMcpRoutes();
+  const helpRoutes = createHelpRoutes();
+  const approvalPreferenceRoutes = createAiApprovalPreferenceRoutes();
+  const widgetRoutes = createWidgetRoutes();
+  return new Hono()
+    .use(prettyJSON())
+    .route("/auth/app-approval/v1", createAppApprovalRoutes())
+    .route("/auth", createAuthRoutes(options.notifications))
+    .route("/me", meRoutes)
+    .route("/accounts", accountsEntitiesRoutes)
+    .route("/apps", appDiscoveryRoutes)
+    .route("/announcements", announcementRoutes)
+    .route("/admin/core/ai-usage", adminAiUsageRoutes)
+    .route("/admin/core/ai-projects", adminAiProjectsRoutes)
+    .route("/admin/core/ai-skills", adminAiSkillsRoutes)
+    .route("/admin/core/announcements", adminAnnouncementRoutes)
+    .route("/admin/core/settings", adminCoreSettingsRoutes)
+    .route("/admin/core/linux-identities", adminLinuxIdentityRoutes)
+    .route("/admin/identity", adminIdentityRoutes)
+    .route("/admin/sync", createSyncOpsProxyRoutes())
+    .route("/admin/lifecycle", adminLifecycleRoutes)
+    .route("/ai/approval-preferences", approvalPreferenceRoutes)
+    .route("/ai/projects", aiProjectsRoutes)
+    .route("/ai/skills", aiSkillsRoutes)
+    .route("/ai", aiRoutes)
+    .route("/", helpRoutes)
+    .route("/", capabilityRoutes)
+    .route("/", mcpRoutes)
+    .route("/", widgetRoutes)
+    .route("/", searchRoutes);
+};
+
+/** Type of the entire core HTTP surface — consumed by the client builder. */
+export type CoreApiType = ReturnType<typeof buildCoreApi>;
+
+/**
+ * Build the core router. The core-app calls this and mounts the returned
+ * router under `/api`.
+ */
+export const createCoreApiRouter = (options: CoreApiOptions) => {
+  const api = buildCoreApi(options);
+  api.all("/*", (c) => c.json({ message: "API route not found" }, 404));
+  return { api };
+};
+
+export {
+  CLOUD_MCP_PATH,
+  CLOUD_MCP_PROTECTED_RESOURCE_PATH,
+  cloudMcpResourceUri,
+  createMcpProtectedResourceRoutes,
+  createMcpRoutes,
+  publicCloudOrigin,
+} from "./mcp";