@contractspec/lib.contracts 1.61.0 → 1.63.0

package/dist/node/docs/tech/studio/learning-events.docblock.js

@@ -1,190 +0,0 @@
-import { createRequire } from "node:module";
-var __defProp = Object.defineProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __moduleCache = /* @__PURE__ */ new WeakMap;
-var __toCommonJS = (from) => {
-  var entry = __moduleCache.get(from), desc;
-  if (entry)
-    return entry;
-  entry = __defProp({}, "__esModule", { value: true });
-  if (from && typeof from === "object" || typeof from === "function")
-    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
-      get: () => from[key],
-      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-    }));
-  __moduleCache.set(from, entry);
-  return entry;
-};
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, {
-      get: all[name],
-      enumerable: true,
-      configurable: true,
-      set: (newValue) => all[name] = () => newValue
-    });
-};
-var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
-var __require = /* @__PURE__ */ createRequire(import.meta.url);
-
-// src/docs/presentations.ts
-var DEFAULT_TARGETS = [
-  "markdown",
-  "react"
-];
-function normalizeRoute(route) {
-  if (!route.length)
-    return "/";
-  const withLeading = route.startsWith("/") ? route : `/${route}`;
-  return withLeading === "/" ? "/" : withLeading.replace(/\/+$/, "");
-}
-function deriveRoute(block, routePrefix) {
-  if (block.route)
-    return normalizeRoute(block.route);
-  const prefix = routePrefix ?? "/docs";
-  const slug = block.id.replace(/^docs\.?/, "").replace(/\./g, "/").replace(/\/+/g, "/");
-  const path = slug.startsWith("/") ? slug : `${prefix}/${slug}`;
-  return normalizeRoute(path);
-}
-function buildName(block, namespace) {
-  return namespace ? `${namespace}.${block.id}` : block.id;
-}
-function docBlockToPresentationSpec(block, options) {
-  const targets = options?.defaultTargets ?? DEFAULT_TARGETS;
-  const version = block.version ?? options?.defaultVersion ?? "1.0.0";
-  const stability = block.stability ?? options?.defaultStability ?? "stable";
-  return {
-    meta: {
-      key: buildName(block, options?.namespace),
-      title: block.title,
-      version,
-      description: block.summary ?? block.title,
-      tags: block.tags || [],
-      owners: block.owners || [],
-      domain: block.domain || "",
-      stability,
-      goal: `Documentation of: ${block.summary}`,
-      context: `Auto-generated`
-    },
-    policy: block.visibility && block.visibility !== "public" ? { flags: [block.visibility] } : undefined,
-    source: {
-      type: "blocknotejs",
-      docJson: block.body
-    },
-    targets
-  };
-}
-function docBlocksToPresentationRoutes(blocks, options) {
-  return blocks.map((block) => ({
-    block,
-    route: deriveRoute(block, options?.routePrefix),
-    descriptor: docBlockToPresentationSpec(block, options)
-  }));
-}
-function docBlocksToPresentationSpecs(blocks, options) {
-  return blocks.map((block) => docBlockToPresentationSpec(block, options));
-}
-function mapDocRoutes(routes) {
-  return routes.map(({ route, descriptor }) => [route, descriptor]);
-}
-
-// src/docs/registry.ts
-class DocRegistry {
-  routes = new Map;
-  constructor(blocks = [], options) {
-    blocks.forEach((block) => this.register(block, options));
-  }
-  register(block, options) {
-    const [route] = docBlocksToPresentationRoutes([block], options);
-    if (route) {
-      this.routes.set(block.id, route);
-    }
-    return this;
-  }
-  list() {
-    return [...this.routes.values()];
-  }
-  get(id) {
-    return this.routes.get(id);
-  }
-  toRouteTuples() {
-    return this.list().map(({ route, descriptor }) => [route, descriptor]);
-  }
-  toPresentationSpecs(options) {
-    return this.list().map(({ block }) => docBlockToPresentationSpec(block, options));
-  }
-}
-var requiredFields = [
-  "id",
-  "title",
-  "body",
-  "kind",
-  "visibility",
-  "route"
-];
-var defaultDocRegistry = new DocRegistry;
-function registerDocBlocks(blocks) {
-  for (const block of blocks) {
-    for (const field of requiredFields) {
-      if (!block[field]) {
-        throw new Error(`DocBlock ${block.id ?? "<missing id>"} missing field ${String(field)}`);
-      }
-    }
-    defaultDocRegistry.register(block);
-  }
-}
-function listRegisteredDocBlocks() {
-  return defaultDocRegistry.list().map((r) => r.block);
-}
-function docId(id) {
-  const found = defaultDocRegistry.get(id);
-  if (!found)
-    throw new Error(`DocBlock not registered: ${id}`);
-  return id;
-}
-
-// src/docs/tech/studio/learning-events.docblock.ts
-var tech_studio_learning_events_DocBlocks = [
-  {
-    id: "docs.tech.studio.learning-events",
-    title: "Studio Learning Events",
-    summary: "Studio persists learning/activity events to the database; Sandbox keeps learning local-first and unlogged.",
-    kind: "reference",
-    visibility: "public",
-    route: "/docs/tech/studio/learning-events",
-    tags: ["studio", "learning", "events", "analytics", "sandbox"],
-    body: `# Studio Learning Events
-
-Studio emits lightweight **learning/activity events** to support onboarding, ambient coaching, and learning journeys.
-
-## Persistence model
-
-- **Studio**: events are persisted to the database in \`StudioLearningEvent\` and are organization-scoped (optionally project-scoped).
-- **Sandbox**: events remain **local-only** (unlogged); they must never be sent to backend services.
-
-## GraphQL API
-
-- \`recordLearningEvent(input: { name, projectId?, payload? })\`
-- \`myLearningEvents(projectId?, limit?)\`
-- \`myOnboardingTracks(productId?, includeProgress?)\`
-- \`myOnboardingProgress(trackKey)\`
-- \`dismissOnboardingTrack(trackKey)\`
-
-## Common event names (convention)
-
-- \`module.navigated\` — user navigated to a Studio module (payload at minimum: \`{ moduleId }\`).
-- \`studio.template.instantiated\` — created a new Studio project (starter template). Payload commonly includes \`{ templateId, projectSlug }\`.
-- \`spec.changed\` — created or updated a Studio spec. Payload may include \`{ action: 'create' | 'update', specId?, specType? }\`.
-- \`regeneration.completed\` — finished a “regen/deploy” action (currently emitted on successful Studio deploy actions).
-- \`studio.evolution.applied\` — completed an Evolution session (payload commonly includes \`{ evolutionSessionId }\`).
-
-These events are intentionally minimal and must avoid PII/secrets in payloads.
-`
-  }
-];
-registerDocBlocks(tech_studio_learning_events_DocBlocks);
-export {
-  tech_studio_learning_events_DocBlocks
-};

package/dist/node/docs/tech/studio/learning-journeys.docblock.js

@@ -1,227 +0,0 @@
-import { createRequire } from "node:module";
-var __defProp = Object.defineProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __moduleCache = /* @__PURE__ */ new WeakMap;
-var __toCommonJS = (from) => {
-  var entry = __moduleCache.get(from), desc;
-  if (entry)
-    return entry;
-  entry = __defProp({}, "__esModule", { value: true });
-  if (from && typeof from === "object" || typeof from === "function")
-    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
-      get: () => from[key],
-      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-    }));
-  __moduleCache.set(from, entry);
-  return entry;
-};
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, {
-      get: all[name],
-      enumerable: true,
-      configurable: true,
-      set: (newValue) => all[name] = () => newValue
-    });
-};
-var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
-var __require = /* @__PURE__ */ createRequire(import.meta.url);
-
-// src/docs/presentations.ts
-var DEFAULT_TARGETS = [
-  "markdown",
-  "react"
-];
-function normalizeRoute(route) {
-  if (!route.length)
-    return "/";
-  const withLeading = route.startsWith("/") ? route : `/${route}`;
-  return withLeading === "/" ? "/" : withLeading.replace(/\/+$/, "");
-}
-function deriveRoute(block, routePrefix) {
-  if (block.route)
-    return normalizeRoute(block.route);
-  const prefix = routePrefix ?? "/docs";
-  const slug = block.id.replace(/^docs\.?/, "").replace(/\./g, "/").replace(/\/+/g, "/");
-  const path = slug.startsWith("/") ? slug : `${prefix}/${slug}`;
-  return normalizeRoute(path);
-}
-function buildName(block, namespace) {
-  return namespace ? `${namespace}.${block.id}` : block.id;
-}
-function docBlockToPresentationSpec(block, options) {
-  const targets = options?.defaultTargets ?? DEFAULT_TARGETS;
-  const version = block.version ?? options?.defaultVersion ?? "1.0.0";
-  const stability = block.stability ?? options?.defaultStability ?? "stable";
-  return {
-    meta: {
-      key: buildName(block, options?.namespace),
-      title: block.title,
-      version,
-      description: block.summary ?? block.title,
-      tags: block.tags || [],
-      owners: block.owners || [],
-      domain: block.domain || "",
-      stability,
-      goal: `Documentation of: ${block.summary}`,
-      context: `Auto-generated`
-    },
-    policy: block.visibility && block.visibility !== "public" ? { flags: [block.visibility] } : undefined,
-    source: {
-      type: "blocknotejs",
-      docJson: block.body
-    },
-    targets
-  };
-}
-function docBlocksToPresentationRoutes(blocks, options) {
-  return blocks.map((block) => ({
-    block,
-    route: deriveRoute(block, options?.routePrefix),
-    descriptor: docBlockToPresentationSpec(block, options)
-  }));
-}
-function docBlocksToPresentationSpecs(blocks, options) {
-  return blocks.map((block) => docBlockToPresentationSpec(block, options));
-}
-function mapDocRoutes(routes) {
-  return routes.map(({ route, descriptor }) => [route, descriptor]);
-}
-
-// src/docs/registry.ts
-class DocRegistry {
-  routes = new Map;
-  constructor(blocks = [], options) {
-    blocks.forEach((block) => this.register(block, options));
-  }
-  register(block, options) {
-    const [route] = docBlocksToPresentationRoutes([block], options);
-    if (route) {
-      this.routes.set(block.id, route);
-    }
-    return this;
-  }
-  list() {
-    return [...this.routes.values()];
-  }
-  get(id) {
-    return this.routes.get(id);
-  }
-  toRouteTuples() {
-    return this.list().map(({ route, descriptor }) => [route, descriptor]);
-  }
-  toPresentationSpecs(options) {
-    return this.list().map(({ block }) => docBlockToPresentationSpec(block, options));
-  }
-}
-var requiredFields = [
-  "id",
-  "title",
-  "body",
-  "kind",
-  "visibility",
-  "route"
-];
-var defaultDocRegistry = new DocRegistry;
-function registerDocBlocks(blocks) {
-  for (const block of blocks) {
-    for (const field of requiredFields) {
-      if (!block[field]) {
-        throw new Error(`DocBlock ${block.id ?? "<missing id>"} missing field ${String(field)}`);
-      }
-    }
-    defaultDocRegistry.register(block);
-  }
-}
-function listRegisteredDocBlocks() {
-  return defaultDocRegistry.list().map((r) => r.block);
-}
-function docId(id) {
-  const found = defaultDocRegistry.get(id);
-  if (!found)
-    throw new Error(`DocBlock not registered: ${id}`);
-  return id;
-}
-
-// src/docs/tech/studio/learning-journeys.docblock.ts
-var tech_studio_learning_journeys_DocBlocks = [
-  {
-    id: "docs.tech.studio.learning-journeys",
-    title: "Studio learning journeys (onboarding + coach)",
-    summary: "DB-backed learning journeys tracked per organization: seeded tracks/steps, event-driven progress, XP/streaks, and a Studio coach surface.",
-    kind: "reference",
-    visibility: "public",
-    route: "/docs/tech/studio/learning-journeys",
-    tags: [
-      "studio",
-      "learning",
-      "onboarding",
-      "journey",
-      "graphql",
-      "database"
-    ],
-    body: `# Studio learning journeys
-
-Studio supports **DB-backed learning journeys** (onboarding tracks + ambient coach tips) that are advanced by **recorded learning events**.
-
-> See also: \`/docs/tech/studio/learning-events\` for event naming + payload guardrails.
-
-## Scope (multi-tenancy)
-
-- Progress is tracked **per organization** (tenant/workspace), via a \`Learner\` record keyed by \`(userId, organizationId)\`.
-- Learning events are stored as \`StudioLearningEvent\` under the Studio DB schema, scoped to an organization (optionally a project).
-
-## Persistence model (Prisma)
-
-Learning journey progress lives in the \`lssm_learning\` schema:
-
-- \`Learner\` — one per \`(userId, organizationId)\`
-- \`OnboardingTrack\` — seeded track definitions (trackKey, name, metadata)
-- \`OnboardingStep\` — seeded step definitions (stepKey, completionCondition, xpReward, metadata)
-- \`OnboardingProgress\` — learner × track progress (progress %, xpEarned, completedAt, dismissedAt)
-- \`OnboardingStepCompletion\` — append-only completion records (stepKey, status, xpEarned, completedAt)
-
-## Track definition source (spec-first)
-
-- Canonical track specs live in \`@contractspec/example.learning-journey-registry\`.
-- The Studio API seeds/updates the DB definitions via an idempotent “ensure tracks” routine.
-- The DB is kept aligned with track specs (stale steps are removed) to prevent drift and unblock completion.
-
-## Progress advancement (event-driven)
-
-1) UI records an event via GraphQL \`recordLearningEvent\`
-2) Backend creates \`StudioLearningEvent\`
-3) Backend advances onboarding by matching the new event against step completion conditions
-4) Backend persists step completions and recomputes:
-   - \`progress\` percentage
-   - \`xpEarned\` (including streak/completion bonuses when configured)
-   - track completion state (\`completedAt\`)
-
-## GraphQL API (Studio)
-
-- \`myOnboardingTracks(productId?, includeProgress?)\`
-  - returns all tracks + optional progress for the current learner
-- \`myOnboardingProgress(trackKey)\`
-  - returns progress + step completion list for a single track
-- \`dismissOnboardingTrack(trackKey)\`
-  - marks a track dismissed for the learner (prevents auto-coach)
-
-## UI routes/surfaces (web)
-
-- \`/studio/learning\` — learning hub (track list + progress widget)
-- \`/studio/learning/{trackKey}\` — track detail (steps + map)
-- Studio shell mounts a **coach sheet** that can auto-open for incomplete, non-dismissed onboarding.
-
-## Security + data hygiene
-
-- Do not put secrets/PII in \`payload\` fields of learning events.
-- Prefer shallow payload filters (small, stable keys).
-`
-  }
-];
-registerDocBlocks(tech_studio_learning_journeys_DocBlocks);
-export {
-  tech_studio_learning_journeys_DocBlocks
-};

package/dist/node/docs/tech/studio/platform-admin-panel.docblock.js

@@ -1,226 +0,0 @@
-import { createRequire } from "node:module";
-var __defProp = Object.defineProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __moduleCache = /* @__PURE__ */ new WeakMap;
-var __toCommonJS = (from) => {
-  var entry = __moduleCache.get(from), desc;
-  if (entry)
-    return entry;
-  entry = __defProp({}, "__esModule", { value: true });
-  if (from && typeof from === "object" || typeof from === "function")
-    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
-      get: () => from[key],
-      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-    }));
-  __moduleCache.set(from, entry);
-  return entry;
-};
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, {
-      get: all[name],
-      enumerable: true,
-      configurable: true,
-      set: (newValue) => all[name] = () => newValue
-    });
-};
-var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
-var __require = /* @__PURE__ */ createRequire(import.meta.url);
-
-// src/docs/presentations.ts
-var DEFAULT_TARGETS = [
-  "markdown",
-  "react"
-];
-function normalizeRoute(route) {
-  if (!route.length)
-    return "/";
-  const withLeading = route.startsWith("/") ? route : `/${route}`;
-  return withLeading === "/" ? "/" : withLeading.replace(/\/+$/, "");
-}
-function deriveRoute(block, routePrefix) {
-  if (block.route)
-    return normalizeRoute(block.route);
-  const prefix = routePrefix ?? "/docs";
-  const slug = block.id.replace(/^docs\.?/, "").replace(/\./g, "/").replace(/\/+/g, "/");
-  const path = slug.startsWith("/") ? slug : `${prefix}/${slug}`;
-  return normalizeRoute(path);
-}
-function buildName(block, namespace) {
-  return namespace ? `${namespace}.${block.id}` : block.id;
-}
-function docBlockToPresentationSpec(block, options) {
-  const targets = options?.defaultTargets ?? DEFAULT_TARGETS;
-  const version = block.version ?? options?.defaultVersion ?? "1.0.0";
-  const stability = block.stability ?? options?.defaultStability ?? "stable";
-  return {
-    meta: {
-      key: buildName(block, options?.namespace),
-      title: block.title,
-      version,
-      description: block.summary ?? block.title,
-      tags: block.tags || [],
-      owners: block.owners || [],
-      domain: block.domain || "",
-      stability,
-      goal: `Documentation of: ${block.summary}`,
-      context: `Auto-generated`
-    },
-    policy: block.visibility && block.visibility !== "public" ? { flags: [block.visibility] } : undefined,
-    source: {
-      type: "blocknotejs",
-      docJson: block.body
-    },
-    targets
-  };
-}
-function docBlocksToPresentationRoutes(blocks, options) {
-  return blocks.map((block) => ({
-    block,
-    route: deriveRoute(block, options?.routePrefix),
-    descriptor: docBlockToPresentationSpec(block, options)
-  }));
-}
-function docBlocksToPresentationSpecs(blocks, options) {
-  return blocks.map((block) => docBlockToPresentationSpec(block, options));
-}
-function mapDocRoutes(routes) {
-  return routes.map(({ route, descriptor }) => [route, descriptor]);
-}
-
-// src/docs/registry.ts
-class DocRegistry {
-  routes = new Map;
-  constructor(blocks = [], options) {
-    blocks.forEach((block) => this.register(block, options));
-  }
-  register(block, options) {
-    const [route] = docBlocksToPresentationRoutes([block], options);
-    if (route) {
-      this.routes.set(block.id, route);
-    }
-    return this;
-  }
-  list() {
-    return [...this.routes.values()];
-  }
-  get(id) {
-    return this.routes.get(id);
-  }
-  toRouteTuples() {
-    return this.list().map(({ route, descriptor }) => [route, descriptor]);
-  }
-  toPresentationSpecs(options) {
-    return this.list().map(({ block }) => docBlockToPresentationSpec(block, options));
-  }
-}
-var requiredFields = [
-  "id",
-  "title",
-  "body",
-  "kind",
-  "visibility",
-  "route"
-];
-var defaultDocRegistry = new DocRegistry;
-function registerDocBlocks(blocks) {
-  for (const block of blocks) {
-    for (const field of requiredFields) {
-      if (!block[field]) {
-        throw new Error(`DocBlock ${block.id ?? "<missing id>"} missing field ${String(field)}`);
-      }
-    }
-    defaultDocRegistry.register(block);
-  }
-}
-function listRegisteredDocBlocks() {
-  return defaultDocRegistry.list().map((r) => r.block);
-}
-function docId(id) {
-  const found = defaultDocRegistry.get(id);
-  if (!found)
-    throw new Error(`DocBlock not registered: ${id}`);
-  return id;
-}
-
-// src/docs/tech/studio/platform-admin-panel.docblock.ts
-var tech_studio_platform_admin_panel_DocBlocks = [
-  {
-    id: "docs.tech.studio.platform-admin-panel",
-    title: "Studio Platform Admin Panel",
-    summary: "How PLATFORM_ADMIN organizations manage tenant orgs and integration connections without session switching.",
-    kind: "reference",
-    visibility: "public",
-    route: "/docs/tech/studio/platform-admin-panel",
-    tags: ["studio", "admin", "multi-tenancy", "integrations", "better-auth"],
-    body: `# Studio Platform Admin Panel
-
-ContractSpec Studio exposes a dedicated **Platform Admin Panel** for users whose **active organization** has:
-
-- \`Organization.type = PLATFORM_ADMIN\`
-
-The UI route is:
-
-- \`/studio/admin\`
-
-## Authorization model (no org switching)
-
-Platform admins **remain in their own organization**. Cross-tenant actions are always explicit and scoped:
-
-- Admin operations require an explicit \`targetOrganizationId\`.
-- No session / activeOrganizationId switching is performed as part of admin operations.
-
-## Integrations management
-
-The admin panel manages the full ContractSpec Integrations system:
-
-- Lists all shipped \`IntegrationSpec\` entries (registry built via \`createDefaultIntegrationSpecRegistry()\`).
-- CRUD \`IntegrationConnection\` records for a selected tenant org.
-
-### Secrets (reference-only + write-only)
-
-The admin UI supports two modes:
-
-- **Reference-only (BYOK)**: store only \`secretProvider\` + \`secretRef\`.
-- **Write-only provisioning/rotation**: paste a raw secret payload; server writes to the selected backend and stores the resulting reference. The secret value is **never returned or displayed**.
-
-Supported backends:
-
-- Env overrides (\`env://...\`)
-- Google Cloud Secret Manager (\`gcp://...\`)
-- AWS Secrets Manager (\`aws://secretsmanager/...\`)
-- Scaleway Secret Manager (\`scw://secret-manager/...\`)
-
-## Better Auth Admin plugin
-
-The panel uses the Better Auth **Admin plugin** for user operations (list users, impersonation):
-
-- Client calls use \`authClient.admin.*\`.
-- Server-side, ContractSpec enforces that users in a PLATFORM_ADMIN active org have \`User.role\` containing \`admin\` so Better Auth Admin endpoints authorize.
-
-## GraphQL surface
-
-The platform-admin GraphQL operations are guarded by the active org type and include:
-
-- \`platformAdminOrganizations(search, limit, offset)\`
-- \`platformAdminIntegrationSpecs\`
-- \`platformAdminIntegrationConnections(input: { targetOrganizationId, category?, status? })\`
-- \`platformAdminIntegrationConnectionCreate(input)\`
-- \`platformAdminIntegrationConnectionUpdate(input)\`
-- \`platformAdminIntegrationConnectionDelete(targetOrganizationId, connectionId)\`
-
-## Key implementation files
-
-- Auth + role enforcement: \`packages/bundles/contractspec-studio/src/application/services/auth.ts\`
-- Admin GraphQL module: \`packages/bundles/contractspec-studio/src/infrastructure/graphql/modules/platform-admin.ts\`
-- Integrations admin service: \`packages/bundles/contractspec-studio/src/modules/platform-integrations/index.ts\`
-- Web route: \`packages/apps/web-landing/src/app/(app-customer)/studio/admin/*\`
-`
-  }
-];
-registerDocBlocks(tech_studio_platform_admin_panel_DocBlocks);
-export {
-  tech_studio_platform_admin_panel_DocBlocks
-};