@jskit-ai/users-core 0.1.55 → 0.1.57

package/templates/packages/users-workspace/package.descriptor.mjs

@@ -0,0 +1,66 @@
+export default Object.freeze({
+  packageVersion: 1,
+  packageId: "@local/users",
+  version: "0.1.0",
+  kind: "runtime",
+  description: "App-local CRUD package (users).",
+  dependsOn: [
+    "@jskit-ai/auth-core",
+    "@jskit-ai/crud-core",
+    "@jskit-ai/database-runtime",
+    "@jskit-ai/http-runtime",
+    "@jskit-ai/users-core",
+    "@jskit-ai/workspaces-core"
+  ],
+  capabilities: {
+    provides: [
+      "crud.users"
+    ],
+    requires: [
+      "runtime.actions",
+      "runtime.database",
+      "auth.policy"
+    ]
+  },
+  runtime: {
+    server: {
+      providers: [
+        {
+          entrypoint: "src/server/UsersProvider.js",
+          export: "UsersProvider"
+        }
+      ]
+    }
+  },
+  metadata: {
+    apiSummary: {
+      surfaces: [
+        {
+          subpath: "./server/actionIds",
+          summary: "App-local CRUD public action identifiers."
+        },
+        {
+          subpath: "./shared",
+          summary: "App-local CRUD shared resource."
+        }
+      ],
+      containerTokens: {
+        server: [
+          "repository.users",
+          "crud.users"
+        ]
+      }
+    }
+  },
+  mutations: {
+    dependencies: {
+      runtime: {},
+      dev: {}
+    },
+    packageJson: {
+      scripts: {}
+    },
+    procfile: {},
+    files: []
+  }
+});

package/templates/packages/users-workspace/src/server/UsersProvider.js

@@ -0,0 +1,92 @@
+import { resolveAppConfig } from "@jskit-ai/kernel/server/support";
+import { resolveCrudSurfacePolicyFromAppConfig } from "@jskit-ai/crud-core/server/crudModuleConfig";
+import {
+  createCrudLookupResolver,
+  createCrudLookup
+} from "@jskit-ai/crud-core/server/lookups";
+import { withActionDefaults } from "@jskit-ai/kernel/shared/actions";
+import { createRepository } from "./repository.js";
+import {
+  createService,
+  serviceEvents
+} from "./service.js";
+import { createActions } from "./actions.js";
+import { registerRoutes } from "./registerRoutes.js";
+
+const CRUD_MODULE_CONFIG = Object.freeze({
+  namespace: "users",
+  surface: "admin",
+  ownershipFilter: "public",
+  relativePath: "/users"
+});
+
+function resolveCrudPolicyFromApp(app) {
+  return resolveCrudSurfacePolicyFromAppConfig(CRUD_MODULE_CONFIG, resolveAppConfig(app), {
+    context: "UsersProvider"
+  });
+}
+
+class UsersProvider {
+  static id = "crud.users";
+
+  static dependsOn = ["runtime.actions", "runtime.database", "auth.policy.fastify", "local.main"];
+
+  register(app) {
+    if (!app || typeof app.singleton !== "function" || typeof app.service !== "function" || typeof app.actions !== "function") {
+      throw new Error("UsersProvider requires application singleton()/service()/actions().");
+    }
+
+    const crudPolicy = resolveCrudPolicyFromApp(app);
+
+    app.singleton("repository.users", (scope) => {
+      const knex = scope.make("jskit.database.knex");
+      return createRepository(knex, {
+        resolveLookup: createCrudLookupResolver(scope)
+      });
+    });
+
+    app.singleton("lookup.users", (scope) => {
+      return createCrudLookup(scope.make("repository.users"), {
+        ownershipFilter: crudPolicy.ownershipFilter
+      });
+    });
+
+    app.service(
+      "crud.users",
+      (scope) => {
+        return createService({
+          usersRepository: scope.make("repository.users")
+        });
+      },
+      {
+        events: serviceEvents
+      }
+    );
+
+    app.actions(
+      withActionDefaults(
+        createActions({
+          surface: crudPolicy.surfaceId
+        }),
+        {
+          domain: "crud",
+          dependencies: {
+            usersService: "crud.users"
+          }
+        }
+      )
+    );
+  }
+
+  boot(app) {
+    const crudPolicy = resolveCrudPolicyFromApp(app);
+    registerRoutes(app, {
+      routeOwnershipFilter: crudPolicy.ownershipFilter,
+      routeSurface: crudPolicy.surfaceId,
+      routeSurfaceRequiresWorkspace: crudPolicy.surfaceDefinition.requiresWorkspace === true,
+      routeRelativePath: crudPolicy.relativePath
+    });
+  }
+}
+
+export { UsersProvider };

package/templates/packages/users-workspace/src/server/actions.js

@@ -0,0 +1,74 @@
+import { recordIdParamsValidator } from "@jskit-ai/kernel/shared/validators";
+import {
+  createCrudCursorPaginationQueryValidator,
+  listSearchQueryValidator
+} from "@jskit-ai/crud-core/server/listQueryValidators";
+import { workspaceSlugParamsValidator } from "@jskit-ai/workspaces-core/server/validators/routeParamsValidator";
+import { resource } from "../shared/userResource.js";
+import { actionIds } from "./actionIds.js";
+import { LIST_CONFIG } from "./listConfig.js";
+
+const listCursorPaginationQueryValidator = createCrudCursorPaginationQueryValidator(LIST_CONFIG);
+const authenticatedPermission = Object.freeze({
+  require: "authenticated"
+});
+
+function requireActionSurface(surface = "") {
+  const normalizedSurface = String(surface || "").trim().toLowerCase();
+  if (!normalizedSurface) {
+    throw new TypeError("createActions requires a non-empty surface.");
+  }
+
+  return normalizedSurface;
+}
+
+function createActions({ surface = "" } = {}) {
+  const actionSurface = requireActionSurface(surface);
+
+  return Object.freeze([
+    {
+      id: actionIds.list,
+      version: 1,
+      kind: "query",
+      channels: ["api", "automation", "internal"],
+      surfaces: [actionSurface],
+      permission: authenticatedPermission,
+      inputValidator: [workspaceSlugParamsValidator, listCursorPaginationQueryValidator, listSearchQueryValidator],
+      outputValidator: resource.operations.list.outputValidator,
+      idempotency: "none",
+      audit: {
+        actionName: actionIds.list
+      },
+      observability: {},
+      async execute(input, context, deps) {
+        return deps.usersService.listRecords(input, {
+          context,
+          visibilityContext: context?.visibilityContext
+        });
+      }
+    },
+    {
+      id: actionIds.view,
+      version: 1,
+      kind: "query",
+      channels: ["api", "automation", "internal"],
+      surfaces: [actionSurface],
+      permission: authenticatedPermission,
+      inputValidator: [workspaceSlugParamsValidator, recordIdParamsValidator],
+      outputValidator: resource.operations.view.outputValidator,
+      idempotency: "none",
+      audit: {
+        actionName: actionIds.view
+      },
+      observability: {},
+      async execute(input, context, deps) {
+        return deps.usersService.getRecord(input.recordId, {
+          context,
+          visibilityContext: context?.visibilityContext
+        });
+      }
+    }
+  ]);
+}
+
+export { createActions };

package/templates/packages/users-workspace/src/server/registerRoutes.js

@@ -0,0 +1,93 @@
+import { withStandardErrorResponses } from "@jskit-ai/http-runtime/shared/validators/errorResponses";
+import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
+import {
+  createCrudCursorPaginationQueryValidator,
+  listSearchQueryValidator
+} from "@jskit-ai/crud-core/server/listQueryValidators";
+import { resolveScopedApiBasePath } from "@jskit-ai/kernel/shared/surface";
+import { checkRouteVisibility } from "@jskit-ai/kernel/shared/support/visibility";
+import { recordIdParamsValidator } from "@jskit-ai/kernel/shared/validators";
+import { routeParamsValidator } from "@jskit-ai/workspaces-core/server/validators/routeParamsValidator";
+import { buildWorkspaceInputFromRouteParams } from "@jskit-ai/workspaces-core/server/support/workspaceRouteInput";
+import { actionIds } from "./actionIds.js";
+import { LIST_CONFIG } from "./listConfig.js";
+import { resource } from "../shared/userResource.js";
+
+const listCursorPaginationQueryValidator = createCrudCursorPaginationQueryValidator(LIST_CONFIG);
+
+function registerRoutes(
+  app,
+  {
+    routeOwnershipFilter = "public",
+    routeSurface = "",
+    routeSurfaceRequiresWorkspace = false,
+    routeRelativePath = ""
+  } = {}
+) {
+  const router = app.make("jskit.http.router");
+  const normalizedRouteSurface = normalizeSurfaceId(routeSurface);
+  const routeBase = resolveScopedApiBasePath({
+    routeBase: routeSurfaceRequiresWorkspace === true ? "/w/:workspaceSlug" : "/",
+    relativePath: routeRelativePath,
+    strictParams: false
+  });
+
+  router.register(
+    "GET",
+    routeBase,
+    {
+      auth: "required",
+      surface: normalizedRouteSurface,
+      visibility: checkRouteVisibility(routeOwnershipFilter),
+      meta: {
+        tags: ["crud"],
+        summary: "List users."
+      },
+      paramsValidator: routeParamsValidator,
+      queryValidator: [listCursorPaginationQueryValidator, listSearchQueryValidator],
+      responseValidators: withStandardErrorResponses({
+        200: resource.operations.list.outputValidator
+      })
+    },
+    async function (request, reply) {
+      const response = await request.executeAction({
+        actionId: actionIds.list,
+        input: {
+          ...buildWorkspaceInputFromRouteParams(request.input.params),
+          ...(request.input.query || {})
+        }
+      });
+      reply.code(200).send(response);
+    }
+  );
+
+  router.register(
+    "GET",
+    `${routeBase}/:recordId`,
+    {
+      auth: "required",
+      surface: normalizedRouteSurface,
+      visibility: checkRouteVisibility(routeOwnershipFilter),
+      meta: {
+        tags: ["crud"],
+        summary: "View a user."
+      },
+      paramsValidator: [routeParamsValidator, recordIdParamsValidator],
+      responseValidators: withStandardErrorResponses({
+        200: resource.operations.view.outputValidator
+      })
+    },
+    async function (request, reply) {
+      const response = await request.executeAction({
+        actionId: actionIds.view,
+        input: {
+          ...buildWorkspaceInputFromRouteParams(request.input.params),
+          recordId: request.input.params.recordId
+        }
+      });
+      reply.code(200).send(response);
+    }
+  );
+}
+
+export { registerRoutes };

package/test/authProfileSyncService.test.js

@@ -7,7 +7,7 @@ test("authProfileSyncService.syncIdentityProfile uses shared transaction for pro
   const transaction = { trxId: "tx-1" };
 
   const service = createService({
-    usersRepository: {
+    userProfilesRepository: {
       async findByIdentity(_identity, options = {}) {
         calls.push({ step: "find", trx: options.trx || null });
         return null;
@@ -68,7 +68,7 @@ test("authProfileSyncService.syncIdentityProfile skips write path when profile i
   let provisionCalls = 0;
 
   const service = createService({
-    usersRepository: {
+    userProfilesRepository: {
       async findByIdentity() {
         return {
           id: "7",
@@ -118,7 +118,7 @@ test("authProfileSyncService.syncIdentityProfile skips write path when profile i
 test("authProfileSyncService.findByIdentity normalizes provider identity input", async () => {
   let capturedIdentity = null;
   const service = createService({
-    usersRepository: {
+    userProfilesRepository: {
       async findByIdentity(identity) {
         capturedIdentity = identity;
         return null;

package/test/avatarService.test.js

@@ -59,7 +59,7 @@ test("avatarService uploadForUser stores bytes and updates profile avatar fields
   };
 
   const avatarService = createService({
-    usersRepository: repository,
+    userProfilesRepository: repository,
     avatarStorageService
   });
 
@@ -99,7 +99,7 @@ test("avatarService clearForUser removes stored avatar and clears profile fields
   };
 
   const avatarService = createService({
-    usersRepository: repository,
+    userProfilesRepository: repository,
     avatarStorageService
   });
 

package/test/registerCommonRepositories.test.js

@@ -0,0 +1,37 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { registerCommonRepositories } from "../src/server/common/registerCommonRepositories.js";
+
+test("registerCommonRepositories exposes the shared users-core repositories", async () => {
+  const bindings = new Map();
+  const app = {
+    singleton(token, factory) {
+      bindings.set(token, factory);
+      return this;
+    }
+  };
+
+  registerCommonRepositories(app);
+
+  assert.equal(typeof bindings.get("internal.repository.user-settings"), "function");
+  assert.equal(typeof bindings.get("internal.repository.user-profiles"), "function");
+
+  const scope = {
+    make(token) {
+      assert.equal(token, "jskit.database.knex");
+      return Object.assign(() => {
+        throw new Error("query execution not expected");
+      }, {
+        async transaction(work) {
+          return work({ trxId: "trx-1" });
+        }
+      });
+    }
+  };
+
+  const settingsRepository = bindings.get("internal.repository.user-settings")(scope);
+  const profileRepository = bindings.get("internal.repository.user-profiles")(scope);
+
+  assert.equal(typeof settingsRepository.findByUserId, "function");
+  assert.equal(typeof profileRepository.findById, "function");
+});

package/test/repositoryContracts.test.js

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import { createRepository as createUsersRepository } from "../src/server/common/repositories/usersRepository.js";
+import { createRepository as createUserProfilesRepository } from "../src/server/common/repositories/userProfilesRepository.js";
 import { createRepository as createUserSettingsRepository } from "../src/server/common/repositories/userSettingsRepository.js";
 
 function createKnexStub() {
@@ -17,10 +17,7 @@ function createKnexStub() {
 
 test("users-core repositories expose withTransaction", async () => {
   const knex = createKnexStub();
-  const repositories = [
-    createUsersRepository(knex),
-    createUserSettingsRepository(knex)
-  ];
+  const repositories = [createUserProfilesRepository(knex), createUserSettingsRepository(knex)];
 
   for (const repository of repositories) {
     assert.equal(typeof repository.withTransaction, "function");
@@ -28,3 +25,49 @@ test("users-core repositories expose withTransaction", async () => {
     assert.deepEqual(result, { id: "trx-1" });
   }
 });
+
+function createFindByEmailKnexStub(expectedRow) {
+  const calls = [];
+  const knex = Object.assign((tableName) => {
+    assert.equal(tableName, "users");
+    return {
+      where(criteria) {
+        calls.push(criteria);
+        return {
+          async first() {
+            return expectedRow;
+          }
+        };
+      }
+    };
+  }, {
+    async transaction(work) {
+      return work({ trxId: "trx-1" });
+    }
+  });
+
+  return { knex, calls };
+}
+
+test("userProfilesRepository.findByEmail normalizes email lookup", async () => {
+  const { knex, calls } = createFindByEmailKnexStub({
+    id: 7,
+    auth_provider: "supabase",
+    auth_provider_user_sid: "supabase-user-7",
+    email: "ada@example.com",
+    username: "ada",
+    display_name: "Ada Example",
+    avatar_storage_key: null,
+    avatar_version: null,
+    avatar_updated_at: null,
+    created_at: "2026-04-20T00:00:00.000Z"
+  });
+  const repository = createUserProfilesRepository(knex);
+
+  const profile = await repository.findByEmail(" ADA@EXAMPLE.COM ");
+
+  assert.deepEqual(calls, [{ email: "ada@example.com" }]);
+  assert.equal(profile?.id, "7");
+  assert.equal(profile?.email, "ada@example.com");
+  assert.equal(profile?.displayName, "Ada Example");
+});

package/test/usersBootstrapContributor.test.js

@@ -33,7 +33,7 @@ test("users bootstrap contributor exposes the generic authenticated bootstrap pa
   const profile = createAuthenticatedProfile({ id: "12" });
   const writtenSessions = [];
   const contributor = createUsersBootstrapContributor({
-    usersRepository: {
+    userProfilesRepository: {
       async findById() {
         return profile;
       }
@@ -103,7 +103,7 @@ test("users bootstrap contributor exposes the generic authenticated bootstrap pa
 
 test("users bootstrap contributor emits anonymous bootstrap payload without workspace fields", async () => {
   const contributor = createUsersBootstrapContributor({
-    usersRepository: {
+    userProfilesRepository: {
       async findById() {
         return null;
       }

package/test/usersPackageScaffoldContract.test.js

@@ -0,0 +1,98 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import descriptor from "../package.descriptor.mjs";
+
+const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = path.resolve(TEST_DIRECTORY, "..");
+
+function readFileMutationById(id) {
+  return descriptor.mutations.files.find((entry) => entry.id === id) || null;
+}
+
+test("users-core installs the app-local users package scaffold", () => {
+  assert.equal(descriptor.mutations.dependencies.runtime["@local/users"], "file:packages/users");
+  assert.equal(descriptor.mutations.dependencies.runtime["@jskit-ai/crud-core"], "0.1.54");
+
+  const expectedFileIds = [
+    "users-core-users-package-json",
+    "users-core-users-package-descriptor-base",
+    "users-core-users-package-descriptor-workspace",
+    "users-core-users-provider-base",
+    "users-core-users-provider-workspace",
+    "users-core-users-action-ids",
+    "users-core-users-actions-base",
+    "users-core-users-actions-workspace",
+    "users-core-users-list-config",
+    "users-core-users-routes-base",
+    "users-core-users-routes-workspace",
+    "users-core-users-repository",
+    "users-core-users-service",
+    "users-core-users-shared-index",
+    "users-core-users-resource"
+  ];
+
+  for (const fileId of expectedFileIds) {
+    const mutation = readFileMutationById(fileId);
+    assert.ok(mutation, `Missing users-core scaffold file mutation ${fileId}.`);
+    assert.equal(mutation.ownership, "app", `${fileId} must remain app-owned.`);
+    assert.equal(mutation.preserveOnRemove, true, `${fileId} must remain preserved on remove.`);
+    assert.ok(mutation.to.startsWith("packages/users/"), `${fileId} must target packages/users.`);
+    assert.ok(mutation.from, `${fileId} must define a template source.`);
+    assert.ok(mutation.reason, `${fileId} must document why it exists.`);
+  }
+});
+
+test("users-core base users package templates stay aligned with non-workspace apps", async () => {
+  const packageDescriptorSource = await readFile(
+    path.join(PACKAGE_ROOT, "templates/packages/users/package.descriptor.mjs"),
+    "utf8"
+  );
+  const providerSource = await readFile(
+    path.join(PACKAGE_ROOT, "templates/packages/users/src/server/UsersProvider.js"),
+    "utf8"
+  );
+  const actionsSource = await readFile(
+    path.join(PACKAGE_ROOT, "templates/packages/users/src/server/actions.js"),
+    "utf8"
+  );
+  const routesSource = await readFile(
+    path.join(PACKAGE_ROOT, "templates/packages/users/src/server/registerRoutes.js"),
+    "utf8"
+  );
+
+  assert.doesNotMatch(packageDescriptorSource, /@jskit-ai\/workspaces-core/);
+  assert.match(providerSource, /surface: "home"/);
+  assert.doesNotMatch(providerSource, /routeSurfaceRequiresWorkspace/);
+  assert.doesNotMatch(actionsSource, /workspaceSlugParamsValidator/);
+  assert.doesNotMatch(routesSource, /workspaceRouteInput/);
+  assert.match(routesSource, /routeBase: "\/"/);
+});
+
+test("users-core workspace users package templates stay aligned with workspace apps", async () => {
+  const packageDescriptorSource = await readFile(
+    path.join(PACKAGE_ROOT, "templates/packages/users-workspace/package.descriptor.mjs"),
+    "utf8"
+  );
+  const providerSource = await readFile(
+    path.join(PACKAGE_ROOT, "templates/packages/users-workspace/src/server/UsersProvider.js"),
+    "utf8"
+  );
+  const actionsSource = await readFile(
+    path.join(PACKAGE_ROOT, "templates/packages/users-workspace/src/server/actions.js"),
+    "utf8"
+  );
+  const routesSource = await readFile(
+    path.join(PACKAGE_ROOT, "templates/packages/users-workspace/src/server/registerRoutes.js"),
+    "utf8"
+  );
+
+  assert.match(packageDescriptorSource, /@jskit-ai\/workspaces-core/);
+  assert.match(providerSource, /surface: "admin"/);
+  assert.match(providerSource, /routeSurfaceRequiresWorkspace/);
+  assert.match(actionsSource, /workspaceSlugParamsValidator/);
+  assert.match(routesSource, /buildWorkspaceInputFromRouteParams/);
+  assert.match(routesSource, /routeBase: routeSurfaceRequiresWorkspace === true \? "\/w\/:workspaceSlug" : "\/"/);
+});

package/test/usersRouteResources.test.js

@@ -11,7 +11,7 @@ import { userSettingsResource } from "../src/shared/resources/userSettingsResour
 function assertResourceShape(resource, label) {
   assert.ok(resource, `${label} resource must exist.`);
   assert.equal(typeof resource, "object", `${label} resource must be an object.`);
-  assert.equal(typeof resource.resource, "string", `${label}.resource must be a string.`);
+  assert.equal(typeof resource.namespace, "string", `.namespace must be a string.`);
 
   for (const operationName of ["view", "list", "create", "replace", "patch"]) {
     const operation = resource.operations?.[operationName];