@jskit-ai/console-core 0.1.1

package/package.descriptor.mjs

@@ -0,0 +1,119 @@
+export default Object.freeze({
+  packageVersion: 1,
+  packageId: "@jskit-ai/console-core",
+  version: "0.1.1",
+  kind: "runtime",
+  description: "Console runtime: console settings schema, bootstrap flags, actions, and HTTP routes.",
+  dependsOn: [
+    "@jskit-ai/database-runtime",
+    "@jskit-ai/http-runtime",
+    "@jskit-ai/users-core"
+  ],
+  capabilities: {
+    provides: [
+      "console.core",
+      "console.server-routes"
+    ],
+    requires: [
+      "runtime.actions",
+      "runtime.database",
+      "users.core"
+    ]
+  },
+  runtime: {
+    server: {
+      providers: [
+        {
+          entrypoint: "src/server/ConsoleCoreServiceProvider.js",
+          export: "ConsoleCoreServiceProvider"
+        }
+      ]
+    },
+    client: {
+      providers: []
+    }
+  },
+  metadata: {
+    apiSummary: {
+      surfaces: [
+        {
+          subpath: "./server",
+          summary: "Exports ConsoleCoreServiceProvider plus console settings services, routes, and action definitions."
+        },
+        {
+          subpath: "./shared",
+          summary: "Exports shared console settings resource and field registration helpers."
+        },
+        {
+          subpath: "./client",
+          summary: "Exports no runtime API today (reserved client entrypoint)."
+        }
+      ],
+      containerTokens: {
+        server: [],
+        client: []
+      }
+    },
+    server: {
+      routes: [
+        {
+          method: "GET",
+          path: "/api/console/settings",
+          summary: "Get console settings."
+        },
+        {
+          method: "PATCH",
+          path: "/api/console/settings",
+          summary: "Update console settings."
+        }
+      ]
+    }
+  },
+  mutations: {
+    dependencies: {
+      runtime: {
+        "@jskit-ai/database-runtime": "0.1.38",
+        "@jskit-ai/http-runtime": "0.1.37",
+        "@jskit-ai/kernel": "0.1.38",
+        "@jskit-ai/users-core": "0.1.48",
+        "typebox": "^1.0.81"
+      },
+      dev: {}
+    },
+    packageJson: {
+      scripts: {}
+    },
+    procfile: {},
+    files: [
+      {
+        op: "install-migration",
+        from: "templates/migrations/console_core_generic_initial.cjs",
+        toDir: "migrations",
+        extension: ".cjs",
+        reason: "Install console settings schema migration.",
+        category: "migration",
+        id: "console-core-generic-initial-schema"
+      },
+      {
+        from: "templates/packages/main/src/shared/resources/consoleSettingsFields.js",
+        to: "packages/main/src/shared/resources/consoleSettingsFields.js",
+        preserveOnRemove: true,
+        reason: "Install app-owned console settings field definitions.",
+        category: "console-core",
+        id: "console-core-app-owned-console-settings-fields"
+      }
+    ],
+    text: [
+      {
+        op: "append-text",
+        file: "packages/main/src/shared/index.js",
+        position: "top",
+        skipIfContains: "import \"./resources/consoleSettingsFields.js\";",
+        value: "import \"./resources/consoleSettingsFields.js\";\n",
+        reason: "Load app-owned console settings field definitions inside the main shared module.",
+        category: "console-core",
+        id: "console-core-main-shared-console-settings-field-import"
+      }
+    ]
+  }
+});

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@jskit-ai/console-core",
+  "version": "0.1.1",
+  "type": "module",
+  "scripts": {
+    "test": "node --test"
+  },
+  "exports": {
+    "./shared/resources/consoleSettingsFields": "./src/shared/resources/consoleSettingsFields.js"
+  },
+  "dependencies": {
+    "@jskit-ai/database-runtime": "0.1.38",
+    "@jskit-ai/http-runtime": "0.1.37",
+    "@jskit-ai/kernel": "0.1.38",
+    "@jskit-ai/users-core": "0.1.48",
+    "typebox": "^1.0.81"
+  }
+}

package/src/server/ConsoleCoreServiceProvider.js

@@ -0,0 +1,22 @@
+import { bootConsoleSettingsRoutes } from "./consoleSettings/bootConsoleSettingsRoutes.js";
+import { registerConsoleCore } from "./registerConsoleCore.js";
+import { registerConsoleBootstrap } from "./registerConsoleBootstrap.js";
+import { registerConsoleSettings } from "./consoleSettings/registerConsoleSettings.js";
+
+class ConsoleCoreServiceProvider {
+  static id = "console.core";
+
+  static dependsOn = ["users.core", "runtime.server", "runtime.actions", "runtime.database"];
+
+  register(app) {
+    registerConsoleCore(app);
+    registerConsoleBootstrap(app);
+    registerConsoleSettings(app);
+  }
+
+  async boot(app) {
+    bootConsoleSettingsRoutes(app);
+  }
+}
+
+export { ConsoleCoreServiceProvider };

package/src/server/consoleBootstrapContributor.js

@@ -0,0 +1,37 @@
+import { normalizeObject, normalizeRecordId } from "@jskit-ai/kernel/shared/support/normalize";
+
+function createConsoleBootstrapContributor({ consoleService } = {}) {
+  if (!consoleService || typeof consoleService.ensureInitialConsoleMember !== "function") {
+    throw new Error("createConsoleBootstrapContributor requires consoleService.ensureInitialConsoleMember().");
+  }
+
+  return Object.freeze({
+    contributorId: "console.bootstrap",
+    order: 300,
+    async contribute({ payload = {} } = {}) {
+      const normalizedPayload = normalizeObject(payload);
+      const session = normalizeObject(normalizedPayload.session);
+      const surfaceAccess = normalizeObject(normalizedPayload.surfaceAccess);
+      const authenticatedUserId =
+        session.authenticated === true ? normalizeRecordId(session.userId, { fallback: null }) : null;
+
+      let consoleOwner = false;
+      if (authenticatedUserId) {
+        const seededConsoleOwnerUserId = normalizeRecordId(
+          await consoleService.ensureInitialConsoleMember(authenticatedUserId),
+          { fallback: null }
+        );
+        consoleOwner = Boolean(seededConsoleOwnerUserId) && seededConsoleOwnerUserId === authenticatedUserId;
+      }
+
+      return {
+        surfaceAccess: {
+          ...surfaceAccess,
+          consoleowner: consoleOwner
+        }
+      };
+    }
+  });
+}
+
+export { createConsoleBootstrapContributor };

package/src/server/consoleSettings/bootConsoleSettingsRoutes.js

@@ -0,0 +1,63 @@
+import { withStandardErrorResponses } from "@jskit-ai/http-runtime/shared/validators/errorResponses";
+import { consoleSettingsResource } from "../../shared/resources/consoleSettingsResource.js";
+
+function bootConsoleSettingsRoutes(app) {
+  if (!app || typeof app.make !== "function") {
+    throw new Error("bootConsoleSettingsRoutes requires application make().");
+  }
+
+  const router = app.make("jskit.http.router");
+
+  router.register(
+    "GET",
+    "/api/console/settings",
+    {
+      auth: "required",
+      surface: "console",
+      meta: {
+        tags: ["console", "settings"],
+        summary: "Get console settings"
+      },
+      responseValidators: withStandardErrorResponses({
+        200: consoleSettingsResource.operations.view.outputValidator
+      })
+    },
+    async function (request, reply) {
+      const response = await request.executeAction({
+        actionId: "console.settings.read"
+      });
+      reply.code(200).send(response);
+    }
+  );
+
+  router.register(
+    "PATCH",
+    "/api/console/settings",
+    {
+      auth: "required",
+      surface: "console",
+      meta: {
+        tags: ["console", "settings"],
+        summary: "Update console settings"
+      },
+      bodyValidator: consoleSettingsResource.operations.replace.bodyValidator,
+      responseValidators: withStandardErrorResponses(
+        {
+          200: consoleSettingsResource.operations.view.outputValidator
+        },
+        { includeValidation400: true }
+      )
+    },
+    async function (request, reply) {
+      const response = await request.executeAction({
+        actionId: "console.settings.update",
+        input: {
+          payload: request.input.body
+        }
+      });
+      reply.code(200).send(response);
+    }
+  );
+}
+
+export { bootConsoleSettingsRoutes };

package/src/server/consoleSettings/consoleService.js

@@ -0,0 +1,36 @@
+import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
+import { normalizeRecordId } from "@jskit-ai/kernel/shared/support/normalize";
+
+function createService({ consoleSettingsRepository } = {}) {
+  if (!consoleSettingsRepository || typeof consoleSettingsRepository.ensureOwnerUserId !== "function") {
+    throw new Error("consoleService requires consoleSettingsRepository.ensureOwnerUserId().");
+  }
+
+  async function ensureInitialConsoleMember(userId, options = {}) {
+    const normalizedUserId = normalizeRecordId(userId, { fallback: null });
+    if (!normalizedUserId) {
+      throw new AppError(400, "Invalid console user.");
+    }
+
+    return consoleSettingsRepository.ensureOwnerUserId(normalizedUserId, options);
+  }
+
+  async function requireConsoleOwner(context = {}, options = {}) {
+    const actorUserId = normalizeRecordId(context?.actor?.id, { fallback: null });
+    if (!actorUserId) {
+      throw new AppError(401, "Authentication required.");
+    }
+
+    const ownerUserId = await ensureInitialConsoleMember(actorUserId, options);
+    if (actorUserId !== ownerUserId) {
+      throw new AppError(403, "Forbidden.");
+    }
+  }
+
+  return Object.freeze({
+    ensureInitialConsoleMember,
+    requireConsoleOwner
+  });
+}
+
+export { createService };

package/src/server/consoleSettings/consoleSettingsActions.js

@@ -0,0 +1,55 @@
+import {
+  EMPTY_INPUT_VALIDATOR
+} from "@jskit-ai/kernel/shared/actions/actionContributorHelpers";
+import { consoleSettingsResource } from "../../shared/resources/consoleSettingsResource.js";
+
+const consoleSettingsActions = Object.freeze([
+  {
+    id: "console.settings.read",
+    version: 1,
+    kind: "query",
+    channels: ["api", "automation", "internal"],
+    surfacesFrom: "console",
+    permission: {
+      require: "authenticated"
+    },
+    inputValidator: EMPTY_INPUT_VALIDATOR,
+    outputValidator: consoleSettingsResource.operations.view.outputValidator,
+    idempotency: "none",
+    audit: {
+      actionName: "console.settings.read"
+    },
+    observability: {},
+    async execute(_input, context, deps) {
+      return deps.consoleSettingsService.getSettings({
+        context
+      });
+    }
+  },
+  {
+    id: "console.settings.update",
+    version: 1,
+    kind: "command",
+    channels: ["api", "automation", "internal"],
+    surfacesFrom: "console",
+    permission: {
+      require: "authenticated"
+    },
+    inputValidator: {
+      payload: consoleSettingsResource.operations.replace.bodyValidator
+    },
+    outputValidator: consoleSettingsResource.operations.replace.outputValidator,
+    idempotency: "optional",
+    audit: {
+      actionName: "console.settings.update"
+    },
+    observability: {},
+    async execute(input, context, deps) {
+      return deps.consoleSettingsService.updateSettings(input.payload, {
+        context
+      });
+    }
+  }
+]);
+
+export { consoleSettingsActions };

package/src/server/consoleSettings/consoleSettingsRepository.js

@@ -0,0 +1,119 @@
+import {
+  normalizeDbRecordId,
+  toIsoString,
+  createWithTransaction
+} from "@jskit-ai/database-runtime/shared";
+import { toInsertDateTime } from "@jskit-ai/database-runtime/shared";
+import { normalizeObjectInput } from "@jskit-ai/kernel/shared/validators/inputNormalization";
+import { normalizeRecordId as normalizeKernelRecordId } from "@jskit-ai/kernel/shared/support/normalize";
+import { consoleSettingsFields } from "../../shared/resources/consoleSettingsFields.js";
+
+function nowDb() {
+  return toInsertDateTime();
+}
+
+function mapSettings(row = {}) {
+  const settings = {};
+  for (const field of consoleSettingsFields) {
+    const rawValue = Object.hasOwn(row, field.dbColumn)
+      ? row[field.dbColumn]
+      : field.resolveDefault({
+          settings: row
+        });
+    settings[field.key] = field.normalizeOutput(rawValue, {
+      settings: row
+    });
+  }
+  return settings;
+}
+
+function mapSingletonRow(row) {
+  if (!row) {
+    throw new Error("console_settings singleton row is missing.");
+  }
+
+  const ownerUserId = normalizeDbRecordId(row.owner_user_id, { fallback: null });
+  return {
+    id: normalizeDbRecordId(row.id, { fallback: "1" }),
+    ownerUserId,
+    settings: mapSettings(row),
+    createdAt: toIsoString(row.created_at),
+    updatedAt: toIsoString(row.updated_at)
+  };
+}
+
+function createRepository(knex) {
+  if (typeof knex !== "function") {
+    throw new TypeError("consoleSettingsRepository requires knex.");
+  }
+  const withTransaction = createWithTransaction(knex);
+
+  async function readSingleton(client) {
+    return client("console_settings").where({ id: 1 }).first();
+  }
+
+  async function getSingleton(options = {}) {
+    const client = options?.trx || knex;
+    return mapSingletonRow(await readSingleton(client));
+  }
+
+  async function ensureOwnerUserId(userId, options = {}) {
+    const client = options?.trx || knex;
+    const candidateOwnerUserId = normalizeKernelRecordId(userId, { fallback: null });
+    if (!candidateOwnerUserId) {
+      throw new TypeError("consoleSettingsRepository.ensureOwnerUserId requires a positive user id.");
+    }
+
+    const current = mapSingletonRow(await readSingleton(client));
+    if (current.ownerUserId) {
+      return current.ownerUserId;
+    }
+
+    await client("console_settings")
+      .where({ id: 1 })
+      .whereNull("owner_user_id")
+      .update({
+        owner_user_id: candidateOwnerUserId,
+        updated_at: nowDb()
+      });
+
+    const reloaded = mapSingletonRow(await readSingleton(client));
+    if (!reloaded.ownerUserId) {
+      throw new Error("console_settings owner_user_id could not be resolved.");
+    }
+
+    return reloaded.ownerUserId;
+  }
+
+  async function updateSingleton(patch, options = {}) {
+    const client = options?.trx || knex;
+    const source = normalizeObjectInput(patch);
+    const dbPatch = {
+      updated_at: nowDb()
+    };
+
+    for (const field of consoleSettingsFields) {
+      if (!Object.hasOwn(source, field.key)) {
+        continue;
+      }
+      dbPatch[field.dbColumn] = field.normalizeInput(source[field.key], {
+        payload: source
+      });
+    }
+
+    await client("console_settings")
+      .where({ id: 1 })
+      .update(dbPatch);
+
+    return getSingleton({ trx: client });
+  }
+
+  return Object.freeze({
+    withTransaction,
+    getSingleton,
+    ensureOwnerUserId,
+    updateSingleton
+  });
+}
+
+export { createRepository };

package/src/server/consoleSettings/consoleSettingsService.js

@@ -0,0 +1,40 @@
+function buildSettingsResponse(record = {}) {
+  return {
+    settings: {
+      ...(record?.settings && typeof record.settings === "object" ? record.settings : {})
+    }
+  };
+}
+
+function createService({ consoleSettingsRepository, consoleService } = {}) {
+  if (!consoleSettingsRepository || typeof consoleSettingsRepository.getSingleton !== "function") {
+    throw new Error("consoleSettingsService requires consoleSettingsRepository.getSingleton().");
+  }
+  if (!consoleSettingsRepository || typeof consoleSettingsRepository.updateSingleton !== "function") {
+    throw new Error("consoleSettingsService requires consoleSettingsRepository.updateSingleton().");
+  }
+  if (!consoleService || typeof consoleService.requireConsoleOwner !== "function") {
+    throw new Error("consoleSettingsService requires consoleService.requireConsoleOwner().");
+  }
+
+  async function getSettings(options = {}) {
+    await consoleService.requireConsoleOwner(options?.context, options);
+    const settings = await consoleSettingsRepository.getSingleton();
+
+    return buildSettingsResponse(settings);
+  }
+
+  async function updateSettings(input = {}, options = {}) {
+    await consoleService.requireConsoleOwner(options?.context, options);
+    const settings = await consoleSettingsRepository.updateSingleton(input);
+
+    return buildSettingsResponse(settings);
+  }
+
+  return Object.freeze({
+    getSettings,
+    updateSettings
+  });
+}
+
+export { createService };

package/src/server/consoleSettings/registerConsoleSettings.js

@@ -0,0 +1,56 @@
+import { withActionDefaults } from "@jskit-ai/kernel/shared/actions";
+import { createService as createConsoleSettingsService } from "./consoleSettingsService.js";
+import { createService as createConsoleService } from "./consoleService.js";
+import { consoleSettingsActions } from "./consoleSettingsActions.js";
+
+function registerConsoleSettings(app) {
+  if (!app || typeof app.singleton !== "function" || typeof app.service !== "function" || typeof app.actions !== "function") {
+    throw new Error("registerConsoleSettings requires application singleton()/service()/actions().");
+  }
+
+  const hasConsoleService = typeof app.has === "function" ? app.has("consoleService") : false;
+  if (!hasConsoleService) {
+    app.singleton("consoleService", (scope) =>
+      createConsoleService({
+        consoleSettingsRepository: scope.make("consoleSettingsRepository")
+      })
+    );
+  }
+
+  app.service(
+    "console.settings.service",
+    (scope) =>
+      createConsoleSettingsService({
+        consoleSettingsRepository: scope.make("consoleSettingsRepository"),
+        consoleService: scope.make("consoleService")
+      }),
+    {
+      events: Object.freeze({
+        updateSettings: Object.freeze([
+          Object.freeze({
+            type: "entity.changed",
+            source: "console",
+            entity: "settings",
+            operation: "updated",
+            entityId: 1,
+            realtime: Object.freeze({
+              event: "console.settings.changed",
+              audience: "all_users"
+            })
+          })
+        ])
+      })
+    }
+  );
+
+  app.actions(
+    withActionDefaults(consoleSettingsActions, {
+      domain: "console",
+      dependencies: {
+        consoleSettingsService: "console.settings.service"
+      }
+    })
+  );
+}
+
+export { registerConsoleSettings };

package/src/server/registerConsoleBootstrap.js

@@ -0,0 +1,16 @@
+import { registerBootstrapPayloadContributor } from "@jskit-ai/kernel/server/runtime";
+import { createConsoleBootstrapContributor } from "./consoleBootstrapContributor.js";
+
+function registerConsoleBootstrap(app) {
+  if (!app || typeof app.singleton !== "function") {
+    throw new Error("registerConsoleBootstrap requires application singleton().");
+  }
+
+  registerBootstrapPayloadContributor(app, "console.core.bootstrap.payloadContributor", (scope) => {
+    return createConsoleBootstrapContributor({
+      consoleService: scope.make("consoleService")
+    });
+  });
+}
+
+export { registerConsoleBootstrap };

package/src/server/registerConsoleCore.js

@@ -0,0 +1,17 @@
+import { createRepository as createConsoleSettingsRepository } from "./consoleSettings/consoleSettingsRepository.js";
+import { registerConsoleCoreActionSurfaceSources } from "./support/consoleActionSurfaces.js";
+
+function registerConsoleCore(app) {
+  if (!app || typeof app.singleton !== "function") {
+    throw new Error("registerConsoleCore requires application singleton().");
+  }
+
+  registerConsoleCoreActionSurfaceSources(app);
+
+  app.singleton("consoleSettingsRepository", (scope) => {
+    const knex = scope.make("jskit.database.knex");
+    return createConsoleSettingsRepository(knex);
+  });
+}
+
+export { registerConsoleCore };

package/src/server/support/consoleActionSurfaces.js

@@ -0,0 +1,62 @@
+import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
+import { isRecord, normalizeLowerText } from "@jskit-ai/kernel/shared/support/normalize";
+
+const CONSOLE_OWNER_ACCESS_POLICY_ID = "console_owner";
+
+function normalizeSurfaceIds(surfaceIds = []) {
+  const source = Array.isArray(surfaceIds) ? surfaceIds : [];
+  const seen = new Set();
+  const normalized = [];
+
+  for (const candidate of source) {
+    const surfaceId = normalizeSurfaceId(candidate);
+    if (!surfaceId || seen.has(surfaceId)) {
+      continue;
+    }
+    seen.add(surfaceId);
+    normalized.push(surfaceId);
+  }
+
+  return normalized;
+}
+
+function resolveConsoleSurfaceIdsFromAppConfig(appConfig = {}) {
+  const source = isRecord(appConfig?.surfaceDefinitions) ? appConfig.surfaceDefinitions : {};
+  const resolved = [];
+
+  for (const [key, value] of Object.entries(source)) {
+    const definition = isRecord(value) ? value : {};
+    const surfaceId = normalizeSurfaceId(definition.id || key);
+    if (!surfaceId) {
+      continue;
+    }
+    if (definition.enabled === false) {
+      continue;
+    }
+    if (definition.requiresWorkspace === true) {
+      continue;
+    }
+    if (normalizeLowerText(definition.accessPolicyId) !== CONSOLE_OWNER_ACCESS_POLICY_ID) {
+      continue;
+    }
+    resolved.push(surfaceId);
+  }
+
+  return normalizeSurfaceIds(resolved);
+}
+
+function registerConsoleCoreActionSurfaceSources(app) {
+  if (!app || typeof app.actionSurfaceSource !== "function") {
+    return;
+  }
+
+  app.actionSurfaceSource("console", ({ scope }) => {
+    const appConfig = scope?.has?.("appConfig") ? scope.make("appConfig") : {};
+    return resolveConsoleSurfaceIdsFromAppConfig(appConfig);
+  });
+}
+
+export {
+  resolveConsoleSurfaceIdsFromAppConfig,
+  registerConsoleCoreActionSurfaceSources
+};

package/src/shared/operationMessages.js

@@ -0,0 +1,16 @@
+function createOperationMessages({
+  validationMessage = "Validation failed.",
+  apiValidationMessage = validationMessage
+} = {}) {
+  const validation = String(validationMessage || "Validation failed.");
+  const apiValidation = String(apiValidationMessage || validation || "Validation failed.");
+
+  return Object.freeze({
+    validation,
+    apiValidation
+  });
+}
+
+export {
+  createOperationMessages
+};