@jskit-ai/agent-docs 0.1.148 → 0.1.150

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users/src/shared/userResource.js

@@ -0,0 +1,69 @@
+import { defineCrudResource } from "@jskit-ai/resource-crud-core/shared/crudResource";
+
+const resource = defineCrudResource({
+  namespace: "users",
+  tableName: "users",
+  crudOperations: ["list", "view"],
+  schema: {
+    name: {
+      type: "string",
+      required: true,
+      minLength: 1,
+      maxLength: 160,
+      actualField: "display_name",
+      search: true,
+      operations: {
+        output: { required: false }
+      }
+    },
+    email: {
+      type: "string",
+      required: true,
+      search: true,
+      operations: {
+        output: { required: false }
+      }
+    },
+    username: {
+      type: "string",
+      required: true,
+      search: true,
+      operations: {
+        output: { required: false }
+      }
+    },
+    createdAt: {
+      type: "dateTime",
+      required: true,
+      storage: { writeSerializer: "datetime-utc" },
+      operations: {
+        output: { required: true }
+      }
+    },
+    updatedAt: {
+      type: "dateTime",
+      required: true,
+      storage: { writeSerializer: "datetime-utc" },
+      operations: {
+        output: { required: true }
+      }
+    }
+  },
+  searchSchema: {
+    id: {
+      type: "id",
+      actualField: "id"
+    },
+    q: {
+      type: "string",
+      oneOf: ["name", "email", "username"],
+      filterOperator: "like",
+      splitBy: " ",
+      matchAll: true
+    }
+  },
+  defaultSort: ["name", "email"],
+  autofilter: "public"
+});
+
+export { resource };

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users-workspace/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@app/users-workspace",
+  "version": "0.0.0",
+  "description": "App-local workspace-scoped read-only user administration feature.",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./server/UsersWorkspaceFeature": "./src/server/UsersWorkspaceFeature.js",
+    "./shared": "./src/shared/index.js"
+  },
+  "dependencies": {
+    "@jskit-ai/crud-core": "0.1.189",
+    "@jskit-ai/resource-crud-core": "0.1.120",
+    "@jskit-ai/workspaces-core": "0.1.156"
+  },
+  "jskit": {
+    "kind": "runtime",
+    "capabilities": {
+      "provides": [
+        "app.users-workspace"
+      ],
+      "requires": [
+        "runtime.http",
+        "runtime.json-rest-api",
+        "runtime.actions",
+        "runtime.database"
+      ]
+    },
+    "runtime": {
+      "server": {
+        "providers": [
+          {
+            "entrypoint": "src/server/UsersWorkspaceFeature.js",
+            "export": "UsersWorkspaceFeature"
+          }
+        ]
+      },
+      "client": {
+        "providers": []
+      }
+    }
+  }
+}

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users-workspace/src/server/UsersWorkspaceFeature.js

@@ -0,0 +1,22 @@
+import { defineCrudJsonApiFeature } from "@jskit-ai/crud-core/server/defineCrudJsonApiFeature";
+import { buildWorkspaceInputFromRouteParams } from "@jskit-ai/workspaces-core/server/support/workspaceRouteInput";
+import { workspaceSlugParamsValidator } from "@jskit-ai/workspaces-core/server/validators/routeParamsValidator";
+import { resource } from "../shared/userResource.js";
+
+const UsersWorkspaceFeature = defineCrudJsonApiFeature({
+  resource,
+  id: "app.users-workspace",
+  capability: "app.users-workspace",
+  surface: "admin",
+  ownershipFilter: "workspace",
+  relativePath: "/users",
+  scope: {
+    routeBase: "/w/:workspaceSlug",
+    actionInputValidator: workspaceSlugParamsValidator,
+    routeParamsValidator: workspaceSlugParamsValidator,
+    inputKeys: ["workspaceSlug"],
+    input: (request) => buildWorkspaceInputFromRouteParams(request.input.params)
+  }
+});
+
+export { UsersWorkspaceFeature };

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users-workspace/src/shared/index.js

@@ -0,0 +1 @@
+export { resource } from "./userResource.js";

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users-workspace/src/shared/userResource.js

@@ -0,0 +1,56 @@
+import { defineCrudResource } from "@jskit-ai/resource-crud-core/shared/crudResource";
+
+const resource = defineCrudResource({
+  namespace: "users",
+  tableName: "users",
+  crudOperations: ["list", "view"],
+  schema: {
+    name: {
+      type: "string",
+      required: true,
+      minLength: 1,
+      maxLength: 160,
+      actualField: "display_name",
+      search: true,
+      operations: { output: { required: false } }
+    },
+    email: {
+      type: "string",
+      required: true,
+      search: true,
+      operations: { output: { required: false } }
+    },
+    username: {
+      type: "string",
+      required: true,
+      search: true,
+      operations: { output: { required: false } }
+    },
+    createdAt: {
+      type: "dateTime",
+      required: true,
+      storage: { writeSerializer: "datetime-utc" },
+      operations: { output: { required: true } }
+    },
+    updatedAt: {
+      type: "dateTime",
+      required: true,
+      storage: { writeSerializer: "datetime-utc" },
+      operations: { output: { required: true } }
+    }
+  },
+  searchSchema: {
+    id: { type: "id", actualField: "id" },
+    q: {
+      type: "string",
+      oneOf: ["name", "email", "username"],
+      filterOperator: "like",
+      splitBy: " ",
+      matchAll: true
+    }
+  },
+  defaultSort: ["name", "email"],
+  autofilter: "public"
+});
+
+export { resource };

package/skills/jskit/references/patterns/workspaces/workspace-server/PATTERN.md

@@ -0,0 +1,60 @@
+---
+id: workspaces/workspace-server
+title: Workspace tenancy server composition
+summary: Configure roles, workspace access policy, invitations, and app-owned invitation email rendering around JSKIT workspace runtime APIs.
+keywords: access, invite, membership, multitenancy, policy, role, tenancy, workspace
+requires: @jskit-ai/workspaces-core, @jskit-ai/users-core
+---
+
+# Workspace tenancy server composition
+
+## Use when
+
+Use this pattern when records, routes, or navigation belong to a selected
+workspace and membership or role affects access.
+
+## Do not use when
+
+Do not use workspace tenancy for a genuinely single-owner product or as a
+substitute for a simpler domain ownership column.
+
+## Product decisions
+
+Choose workspace creation policy, roles, invitation policy, expiry, email copy,
+member permissions, personal-workspace behavior, and surface access rules.
+
+## Framework APIs
+
+Use workspace routes, resources, scope helpers, tenancy profiles, and settings
+contracts exported by `@jskit-ai/workspaces-core`.
+
+## Invariants
+
+- Workspace membership and role are checked before scoped application actions.
+- Role ids are stable product vocabulary shared by server and client config.
+- Invitation tokens remain secret; emails receive only the intended link.
+- Workspace scope reaches repository queries, not just route parsing.
+- Package-owned migrations run directly from the installed package graph.
+
+## Example files
+
+`example/config/roles.js` is a concrete role catalogue.
+`example/packages/main/src/server/email/workspaceInviteEmail.js` demonstrates an
+app-owned invitation renderer. Compose both through normal application config.
+
+## Variation points
+
+Change roles, invitation policy and copy, defaults, access policies, surface
+ids, and product-specific workspace settings.
+
+## Verification
+
+Test create/list/select, member and non-member access, each role boundary,
+invitation expiry/redemption, cross-workspace isolation, and email output.
+
+## Avoid
+
+- synthetic membership workarounds
+- authorizing from client navigation state
+- embedding invitation templates or secrets in package metadata
+- source-appending install commands

package/skills/jskit/references/patterns/workspaces/workspace-server/example/config/roles.js

@@ -0,0 +1,27 @@
+export const roleCatalog = {
+  workspace: {
+    defaultInviteRole: "member"
+  },
+  roles: {
+    owner: {
+      assignable: false,
+      permissions: ["*"]
+    },
+    admin: {
+      assignable: true,
+      inherits: "member",
+      permissions: [
+        "workspace.roles.view",
+        "workspace.settings.update",
+        "workspace.members.view",
+        "workspace.members.invite",
+        "workspace.members.manage",
+        "workspace.invites.revoke"
+      ]
+    },
+    member: {
+      assignable: true,
+      permissions: ["workspace.settings.view"]
+    }
+  }
+};

package/skills/jskit/references/patterns/workspaces/workspace-server/example/packages/main/src/server/email/workspaceInviteEmail.js

@@ -0,0 +1,23 @@
+function renderWorkspaceInviteEmail({
+  inviteUrl = "",
+  workspace = {},
+  inviter = null,
+  roleSid = "member",
+  expiresAt = ""
+} = {}) {
+  const workspaceName = String(workspace?.name || workspace?.slug || "the workspace").trim() || "the workspace";
+  const inviterName = String(inviter?.displayName || inviter?.email || "").trim();
+  const roleName = String(roleSid || "member").trim() || "member";
+  const intro = inviterName
+    ? `${inviterName} invited you to join ${workspaceName} as ${roleName}.`
+    : `You have been invited to join ${workspaceName} as ${roleName}.`;
+  const expiryText = expiresAt ? `This invitation expires at ${expiresAt}.` : "";
+
+  return {
+    subject: `You're invited to ${workspaceName}`,
+    text: [intro, expiryText, "Open this link to accept the invitation:", inviteUrl].filter(Boolean).join("\n\n"),
+    html: null
+  };
+}
+
+export { renderWorkspaceInviteEmail };

package/skills/jskit/references/patterns/workspaces/workspace-surfaces/PATTERN.md

@@ -0,0 +1,63 @@
+---
+id: workspaces/workspace-surfaces
+title: Workspace application and administration surfaces
+summary: Compose workspace selection, invitation, member administration, settings, and responsive navigation using JSKIT workspace web APIs.
+keywords: admin, invite, member, navigation, settings, surface, switcher, workspace
+requires: @jskit-ai/workspaces-core, @jskit-ai/workspaces-web, @jskit-ai/shell-web
+---
+
+# Workspace application and administration surfaces
+
+## Use when
+
+Use this pattern when the product has workspace-scoped app and administration
+surfaces, invitations, member management, or workspace switching.
+
+## Do not use when
+
+Do not use this pattern for a single-owner application, or copy its whole
+surface tree when only one workspace widget is needed.
+
+## Product decisions
+
+Choose public invitation routes, application/admin surface ids, workspace
+selector behavior, member-management permissions, settings sections, and the
+empty or not-found experience.
+
+## Framework APIs
+
+Use the workspace client provider, components, and composables exported by
+`@jskit-ai/workspaces-web` together with JSKIT shell placements and routes.
+
+## Invariants
+
+- Route workspace slug, selected workspace, and server scope stay synchronized.
+- Invitation acceptance is public only where the server contract permits it.
+- Administrative UI visibility never substitutes for server authorization.
+- Query and route state hydrate immediately on warm-cache navigation.
+- Loading uses skeletons; mutation failures use toasts without layout movement.
+- Navigation is composed through semantic placements and registered tokens.
+
+## Example files
+
+`example/` contains workspace app/admin roots, starter pages, invitation route,
+member and settings routes, not-found state, app-owned invitation widgets, and
+the components that an application's client provider registers.
+
+## Variation points
+
+Change surfaces, routes, section owners, labels, icons, placement order,
+workspace-not-found copy, member operations, and invitation presentation.
+
+## Verification
+
+Exercise direct workspace URLs, selection and switching, invitations, members,
+settings, not-found state, browser back/forward, forbidden access, and all
+responsive navigation variants.
+
+## Avoid
+
+- defaulting silently to another workspace after an invalid route
+- unscoped queries
+- inline mutation error banners
+- generated placement or source mutation machinery

package/skills/jskit/references/patterns/workspaces/workspace-surfaces/example/packages/main/src/client/components/AccountPendingInvitesCue.vue

@@ -0,0 +1,106 @@
+<script setup>
+import { computed } from "vue";
+import { useRoute } from "vue-router";
+import { mdiEmailAlertOutline } from "@mdi/js";
+import { appendQueryString } from "@jskit-ai/kernel/shared/support";
+import {
+  useWebPlacementContext,
+  resolveSurfaceDefinitionFromPlacementContext,
+  resolveSurfacePathFromPlacementContext,
+  resolveSurfaceNavigationTargetFromPlacementContext
+} from "@jskit-ai/shell-web/client/placement";
+
+const { context: placementContext } = useWebPlacementContext();
+const route = useRoute();
+
+function normalizePendingInvitesCount(value) {
+  const numeric = Number(value);
+  if (!Number.isInteger(numeric) || numeric < 1) {
+    return 0;
+  }
+  return numeric;
+}
+
+function resolveReturnTo() {
+  const fullPath = String(route?.fullPath || "").trim();
+  if (fullPath.startsWith("/") && !fullPath.startsWith("//")) {
+    return fullPath;
+  }
+  const path = String(route?.path || "").trim();
+  if (path.startsWith("/") && !path.startsWith("//")) {
+    return path;
+  }
+  return "/";
+}
+
+function resolveReturnToHref() {
+  if (typeof window === "object" && window?.location?.href) {
+    return String(window.location.href || "").trim() || resolveReturnTo();
+  }
+  return resolveReturnTo();
+}
+
+const authenticated = computed(() => placementContext.value?.auth?.authenticated === true);
+const placementPendingInvitesCount = computed(() =>
+  normalizePendingInvitesCount(placementContext.value?.pendingInvitesCount)
+);
+const pendingInvitesCount = computed(() => placementPendingInvitesCount.value);
+const placementWorkspaceInvitesEnabled = computed(() => placementContext.value?.workspaceInvitesEnabled === true);
+const workspaceInvitesEnabled = computed(() => placementWorkspaceInvitesEnabled.value);
+
+const isVisible = computed(() => {
+  return (
+    authenticated.value &&
+    workspaceInvitesEnabled.value &&
+    pendingInvitesCount.value > 0
+  );
+});
+
+const resolvedTo = computed(() => {
+  const hasAccountSurface = Boolean(resolveSurfaceDefinitionFromPlacementContext(placementContext.value, "account"));
+  const accountSettingsPath = hasAccountSurface
+    ? resolveSurfacePathFromPlacementContext(placementContext.value, "account", "/")
+    : "/account";
+  const accountSettingsNavigation = resolveSurfaceNavigationTargetFromPlacementContext(placementContext.value, {
+    path: accountSettingsPath,
+    surfaceId: "account"
+  });
+
+  const query = new URLSearchParams({
+    section: "invites",
+    returnTo: accountSettingsNavigation.sameOrigin ? resolveReturnTo() : resolveReturnToHref()
+  });
+  return appendQueryString(accountSettingsPath, query.toString());
+});
+
+const resolvedNavigationTarget = computed(() =>
+  resolveSurfaceNavigationTargetFromPlacementContext(placementContext.value, {
+    path: resolvedTo.value,
+    surfaceId: "account"
+  })
+);
+</script>
+
+<template>
+  <v-badge
+    v-if="isVisible"
+    color="error"
+    :content="pendingInvitesCount"
+    :model-value="pendingInvitesCount > 0"
+    bordered
+    offset-x="6"
+    offset-y="8"
+  >
+    <v-btn
+      :to="resolvedNavigationTarget.sameOrigin ? resolvedNavigationTarget.href : undefined"
+      :href="resolvedNavigationTarget.sameOrigin ? undefined : resolvedNavigationTarget.href"
+      variant="tonal"
+      color="warning"
+      :prepend-icon="mdiEmailAlertOutline"
+      size="small"
+      class="text-none"
+    >
+      Invites
+    </v-btn>
+  </v-badge>
+</template>

package/skills/jskit/references/patterns/workspaces/workspace-surfaces/example/packages/main/src/client/components/AccountSettingsInvitesSection.vue

@@ -0,0 +1,7 @@
+<script setup>
+import WorkspacesWebAccountSettingsInvitesSection from "@jskit-ai/workspaces-web/client/components/AccountSettingsInvitesSection";
+</script>
+
+<template>
+  <WorkspacesWebAccountSettingsInvitesSection />
+</template>

package/skills/jskit/references/patterns/workspaces/workspace-surfaces/example/src/components/WorkspaceNotFoundCard.vue

@@ -0,0 +1,53 @@
+<script setup>
+import { mdiAlertCircleOutline } from "@mdi/js";
+import { computed } from "vue";
+
+const props = defineProps({
+  surfaceLabel: {
+    type: String,
+    default: "Workspace"
+  },
+  message: {
+    type: String,
+    default: "Workspace is currently unavailable."
+  }
+});
+
+const normalizedSurfaceLabel = computed(() => String(props.surfaceLabel || "").trim() || "Workspace");
+const normalizedMessage = computed(() => String(props.message || "").trim() || "Workspace is currently unavailable.");
+</script>
+
+<template>
+  <v-sheet rounded="lg" border class="workspace-unavailable-panel">
+    <div class="workspace-unavailable-panel__header">
+      <v-icon :icon="mdiAlertCircleOutline" color="error" />
+      <div>
+        <h1 class="workspace-unavailable-panel__title">Unavailable</h1>
+        <p class="text-body-2 text-medium-emphasis mb-0">{{ normalizedSurfaceLabel }} surface.</p>
+      </div>
+    </div>
+    <p class="text-body-2 text-medium-emphasis mb-0">{{ normalizedMessage }}</p>
+  </v-sheet>
+</template>
+
+<style scoped>
+.workspace-unavailable-panel {
+  display: grid;
+  gap: 1rem;
+  padding: 1rem;
+}
+
+.workspace-unavailable-panel__header {
+  align-items: flex-start;
+  display: flex;
+  gap: 0.75rem;
+}
+
+.workspace-unavailable-panel__title {
+  font-size: clamp(1.35rem, 2vw, 1.85rem);
+  font-weight: 650;
+  letter-spacing: -0.02em;
+  line-height: 1.15;
+  margin: 0 0 0.25rem;
+}
+</style>

package/skills/jskit/references/patterns/workspaces/workspace-surfaces/example/src/composables/useWorkspaceNotFoundState.js

@@ -0,0 +1,41 @@
+import { computed } from "vue";
+import { useRoute } from "vue-router";
+import { normalizeLowerText, normalizeObject } from "@jskit-ai/kernel/shared/support/normalize";
+import { useWebPlacementContext } from "@jskit-ai/shell-web/client/placement";
+
+const STATUS_MESSAGES = {
+  not_found: "The requested workspace was not found.",
+  forbidden: "You do not have access to this workspace.",
+  unauthenticated: "You need to sign in to access this workspace.",
+  error: "Workspace data could not be loaded right now."
+};
+const DEFAULT_WORKSPACE_UNAVAILABLE_MESSAGE = "Workspace is currently unavailable.";
+const RESOLVED_WORKSPACE_STATUS = "resolved";
+
+function useWorkspaceNotFoundState() {
+  const route = useRoute();
+  const { context: placementContext } = useWebPlacementContext();
+
+  const routeWorkspaceSlug = computed(() => normalizeLowerText(route?.params?.workspaceSlug));
+
+  const workspaceBootstrapStatus = computed(() => {
+    const statuses = normalizeObject(placementContext.value?.workspaceBootstrapStatuses);
+    return normalizeLowerText(statuses[routeWorkspaceSlug.value]);
+  });
+
+  const workspaceUnavailable = computed(
+    () => Boolean(workspaceBootstrapStatus.value) && workspaceBootstrapStatus.value !== RESOLVED_WORKSPACE_STATUS
+  );
+  const workspaceUnavailableMessage = computed(
+    () => STATUS_MESSAGES[workspaceBootstrapStatus.value] || DEFAULT_WORKSPACE_UNAVAILABLE_MESSAGE
+  );
+
+  return Object.freeze({
+    routeWorkspaceSlug,
+    workspaceBootstrapStatus,
+    workspaceUnavailable,
+    workspaceUnavailableMessage
+  });
+}
+
+export { useWorkspaceNotFoundState };

package/skills/jskit/references/patterns/workspaces/workspace-surfaces/example/src/pages/admin/members/index.vue

@@ -0,0 +1,7 @@
+<template>
+  <WorkspaceMembersClientElement />
+</template>
+
+<script setup>
+import WorkspaceMembersClientElement from "@jskit-ai/workspaces-web/client/components/WorkspaceMembersClientElement";
+</script>

package/skills/jskit/references/patterns/workspaces/workspace-surfaces/example/src/pages/admin/workspace/settings/index.vue

@@ -0,0 +1,23 @@
+<template>
+  <section class="workspace-settings-landing">
+    <v-sheet rounded="lg" border class="workspace-settings-landing__panel">
+      <h2 class="workspace-settings-landing__title">No settings sections yet</h2>
+      <p class="text-body-2 text-medium-emphasis mb-0">
+        This app has no workspace-level settings configured.
+      </p>
+    </v-sheet>
+  </section>
+</template>
+
+<style scoped>
+.workspace-settings-landing__panel {
+  padding: 1rem;
+}
+
+.workspace-settings-landing__title {
+  font-size: 1rem;
+  font-weight: 650;
+  line-height: 1.2;
+  margin: 0 0 0.25rem;
+}
+</style>