@treeseed/sdk 0.1.2 → 0.3.1

package/dist/platform/environment.js

@@ -0,0 +1,331 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
+import { loadTreeseedDeployConfig } from "./deploy/config.js";
+import { loadTreeseedPlugins } from "./plugins/runtime.js";
+import { loadTreeseedManifest } from "./tenant/config.js";
+const TREESEED_ENVIRONMENT_SCOPES = ["local", "staging", "prod"];
+const TREESEED_ENVIRONMENT_REQUIREMENTS = ["required", "conditional", "optional"];
+const TREESEED_ENVIRONMENT_TARGETS = [
+  "local-file",
+  "wrangler-dev-vars",
+  "github-secret",
+  "github-variable",
+  "cloudflare-secret",
+  "cloudflare-var",
+  "railway-secret",
+  "config-file"
+];
+const TREESEED_ENVIRONMENT_PURPOSES = ["dev", "save", "deploy", "destroy", "config"];
+const TREESEED_ENVIRONMENT_SENSITIVITY = ["secret", "plain", "derived"];
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+const CORE_ENVIRONMENT_PATH = resolve(moduleDir, "env.yaml");
+const TENANT_ENVIRONMENT_OVERLAY_PATH = "src/env.yaml";
+function loadOptionalTenantConfig() {
+  try {
+    return loadTreeseedManifest();
+  } catch {
+    return void 0;
+  }
+}
+function turnstileEnabled(context) {
+  return context.deployConfig.turnstile?.enabled !== false;
+}
+function smtpEnabled(context) {
+  return context.deployConfig.smtp?.enabled === true;
+}
+function railwayManagedEnabled(context) {
+  return Object.values(context.deployConfig.services ?? {}).some(
+    (service) => service && service.enabled !== false && (service.provider ?? "railway") === "railway"
+  );
+}
+function generatedSecret(bytes = 24) {
+  return randomBytes(bytes).toString("hex");
+}
+const VALUE_RESOLVERS = {
+  generatedSecret: () => generatedSecret(),
+  localFormsBypassDefault: () => "true"
+};
+const PREDICATES = {
+  turnstileEnabled: (context) => turnstileEnabled(context),
+  turnstileNonLocal: (context, scope) => turnstileEnabled(context) && scope !== "local",
+  smtpEnabled: (context) => smtpEnabled(context),
+  smtpNonLocal: (context, scope) => smtpEnabled(context) && scope !== "local",
+  railwayManagedEnabled: (context) => railwayManagedEnabled(context)
+};
+function deepMerge(left, right) {
+  if (Array.isArray(left) && Array.isArray(right)) {
+    return [...right];
+  }
+  if (left && typeof left === "object" && !Array.isArray(left) && right && typeof right === "object" && !Array.isArray(right)) {
+    const result = { ...left };
+    for (const [key, value] of Object.entries(right)) {
+      result[key] = key in result ? deepMerge(result[key], value) : value;
+    }
+    return result;
+  }
+  return right;
+}
+function normalizeOverlay(raw, label) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`Invalid Treeseed environment registry overlay from ${label}.`);
+  }
+  const overlay = raw;
+  if (overlay.entries === void 0) {
+    return { entries: {} };
+  }
+  if (!overlay.entries || typeof overlay.entries !== "object" || Array.isArray(overlay.entries)) {
+    throw new Error(`Invalid Treeseed environment registry overlay entries in ${label}.`);
+  }
+  return overlay;
+}
+function readYamlOverlayIfPresent(filePath) {
+  if (!existsSync(filePath)) {
+    return null;
+  }
+  return normalizeOverlay(parseYaml(readFileSync(filePath, "utf8")), filePath);
+}
+function pluginEnvironmentCandidates(baseDir) {
+  const dir = resolve(baseDir);
+  return [
+    resolve(dir, "env.yaml"),
+    resolve(dir, "src/env.yaml"),
+    resolve(dir, "../env.yaml"),
+    resolve(dir, "../src/env.yaml"),
+    resolve(dir, "../../env.yaml"),
+    resolve(dir, "../../src/env.yaml")
+  ];
+}
+function readPluginEnvironmentOverlay(baseDir) {
+  for (const candidate of pluginEnvironmentCandidates(baseDir)) {
+    const overlay = readYamlOverlayIfPresent(candidate);
+    if (overlay) {
+      return { path: candidate, overlay };
+    }
+  }
+  return null;
+}
+function loadTreeseedEnvironmentOverlay(tenantRoot) {
+  const overlayPath = resolve(tenantRoot, TENANT_ENVIRONMENT_OVERLAY_PATH);
+  return {
+    path: overlayPath,
+    overlay: readYamlOverlayIfPresent(overlayPath) ?? { entries: {} }
+  };
+}
+function resolveNamedValueResolver(ref) {
+  if (!ref) return void 0;
+  const resolver = VALUE_RESOLVERS[ref];
+  if (!resolver) {
+    throw new Error(`Unknown Treeseed environment value resolver "${ref}".`);
+  }
+  return resolver;
+}
+function resolveNamedPredicate(ref) {
+  if (!ref) return void 0;
+  const predicate = PREDICATES[ref];
+  if (!predicate) {
+    throw new Error(`Unknown Treeseed environment predicate "${ref}".`);
+  }
+  return predicate;
+}
+function materializeEntry(id, entry) {
+  return {
+    ...entry,
+    id,
+    defaultValue: resolveNamedValueResolver(entry.defaultValueRef),
+    localDefaultValue: resolveNamedValueResolver(entry.localDefaultValueRef),
+    isRelevant: resolveNamedPredicate(entry.relevanceRef),
+    requiredWhen: resolveNamedPredicate(entry.requiredWhenRef)
+  };
+}
+function mergeEntryYaml(baseEntry, id, override) {
+  const merged = baseEntry ? deepMerge(baseEntry, override) : override;
+  if (typeof merged.label !== "string" || typeof merged.group !== "string" || typeof merged.description !== "string" || typeof merged.howToGet !== "string" || !Array.isArray(merged.targets) || !Array.isArray(merged.scopes) || typeof merged.requirement !== "string" || !Array.isArray(merged.purposes) || typeof merged.sensitivity !== "string") {
+    throw new Error(`Treeseed environment registry entry "${id}" is missing required metadata after merge.`);
+  }
+  return merged;
+}
+function collectOverlaySources(context) {
+  const sources = [];
+  const coreOverlay = readYamlOverlayIfPresent(CORE_ENVIRONMENT_PATH);
+  if (!coreOverlay) {
+    throw new Error(`Treeseed core environment registry file was not found at ${CORE_ENVIRONMENT_PATH}.`);
+  }
+  sources.push({ label: CORE_ENVIRONMENT_PATH, overlay: coreOverlay });
+  for (const pluginEntry of context.plugins) {
+    const fileOverlay = readPluginEnvironmentOverlay(pluginEntry.baseDir);
+    if (fileOverlay) {
+      sources.push({ label: fileOverlay.path, overlay: fileOverlay.overlay });
+    }
+    const overlaySource = pluginEntry.plugin.environmentRegistry;
+    if (!overlaySource) {
+      continue;
+    }
+    const pluginContext = {
+      projectRoot: context.tenantRoot,
+      tenantConfig: context.tenantConfig,
+      deployConfig: context.deployConfig,
+      pluginConfig: pluginEntry.config
+    };
+    const overlay = typeof overlaySource === "function" ? overlaySource(pluginContext) : overlaySource;
+    if (overlay) {
+      sources.push({
+        label: `plugin ${pluginEntry.package}`,
+        overlay: normalizeOverlay(overlay, `plugin ${pluginEntry.package}`)
+      });
+    }
+  }
+  const tenantOverlay = loadTreeseedEnvironmentOverlay(context.tenantRoot);
+  sources.push({ label: tenantOverlay.path, overlay: tenantOverlay.overlay });
+  return sources;
+}
+function resolveTreeseedEnvironmentContext(options = {}) {
+  const deployConfig = options.deployConfig ?? loadTreeseedDeployConfig();
+  const tenantConfig = options.tenantConfig ?? loadOptionalTenantConfig();
+  const plugins = options.plugins ?? loadTreeseedPlugins(deployConfig);
+  const tenantRoot = deployConfig.__tenantRoot ?? tenantConfig?.__tenantRoot ?? process.cwd();
+  return {
+    deployConfig,
+    tenantConfig,
+    plugins,
+    tenantRoot
+  };
+}
+function resolveTreeseedEnvironmentRegistry(options = {}) {
+  const context = resolveTreeseedEnvironmentContext(options);
+  const entriesById = /* @__PURE__ */ new Map();
+  const order = [];
+  for (const source of collectOverlaySources(context)) {
+    for (const [id, override] of Object.entries(source.overlay.entries ?? {})) {
+      const current = entriesById.get(id);
+      entriesById.set(id, mergeEntryYaml(current, id, override ?? {}));
+      if (!current) {
+        order.push(id);
+      }
+    }
+  }
+  return {
+    context,
+    entries: order.map((id) => materializeEntry(id, entriesById.get(id)))
+  };
+}
+function isTreeseedEnvironmentEntryRelevant(entry, context, scope, purpose) {
+  if (!entry.scopes.includes(scope)) {
+    return false;
+  }
+  if (purpose && !entry.purposes.includes(purpose)) {
+    return false;
+  }
+  if (entry.isRelevant) {
+    return entry.isRelevant(context, scope, purpose);
+  }
+  return true;
+}
+function isEntryRequired(entry, context, scope, purpose) {
+  if (entry.requirement === "required") {
+    return true;
+  }
+  if (entry.requirement === "conditional") {
+    return entry.requiredWhen ? entry.requiredWhen(context, scope, purpose) : true;
+  }
+  return false;
+}
+function materializeDefaultValue(entry, context, scope) {
+  const source = scope === "local" && entry.localDefaultValue !== void 0 ? entry.localDefaultValue : entry.defaultValue;
+  if (source === void 0) {
+    return void 0;
+  }
+  return typeof source === "function" ? source(context, scope) : source;
+}
+function getTreeseedEnvironmentSuggestedValues(options) {
+  const registry = resolveTreeseedEnvironmentRegistry(options);
+  return Object.fromEntries(
+    registry.entries.filter((entry) => isTreeseedEnvironmentEntryRelevant(entry, registry.context, options.scope, options.purpose)).map((entry) => [entry.id, materializeDefaultValue(entry, registry.context, options.scope)]).filter(([, value]) => value !== void 0)
+  );
+}
+function valuePresent(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function validateValue(entry, value) {
+  if (!entry.validation) {
+    return null;
+  }
+  switch (entry.validation.kind) {
+    case "string":
+    case "nonempty":
+      return valuePresent(value) ? null : `${entry.id} must be a non-empty string.`;
+    case "boolean":
+      return /^(true|false|1|0)$/i.test(value) ? null : `${entry.id} must be true or false.`;
+    case "number":
+      return Number.isFinite(Number(value)) ? null : `${entry.id} must be a number.`;
+    case "url":
+      try {
+        new URL(value);
+        return null;
+      } catch {
+        return `${entry.id} must be a valid URL.`;
+      }
+    case "email":
+      return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value) ? null : `${entry.id} must be a valid email address.`;
+    case "enum":
+      return entry.validation.values.includes(value) ? null : `${entry.id} must be one of: ${entry.validation.values.join(", ")}.`;
+    default:
+      return null;
+  }
+}
+function validateTreeseedEnvironmentValues(options) {
+  const registry = resolveTreeseedEnvironmentRegistry(options);
+  const relevantEntries = registry.entries.filter(
+    (entry) => isTreeseedEnvironmentEntryRelevant(entry, registry.context, options.scope, options.purpose)
+  );
+  const requiredEntries = relevantEntries.filter(
+    (entry) => isEntryRequired(entry, registry.context, options.scope, options.purpose)
+  );
+  const missing = [];
+  const invalid = [];
+  for (const entry of requiredEntries) {
+    const value = options.values[entry.id];
+    if (!valuePresent(value)) {
+      missing.push({
+        id: entry.id,
+        label: entry.label,
+        reason: "missing",
+        message: `${entry.id} is required for ${options.purpose} (${options.scope}). ${entry.howToGet}`,
+        entry
+      });
+      continue;
+    }
+    const validationMessage = validateValue(entry, value);
+    if (validationMessage) {
+      invalid.push({
+        id: entry.id,
+        label: entry.label,
+        reason: "invalid",
+        message: validationMessage,
+        entry
+      });
+    }
+  }
+  return {
+    ok: missing.length === 0 && invalid.length === 0,
+    entries: relevantEntries,
+    required: requiredEntries,
+    missing,
+    invalid
+  };
+}
+export {
+  TREESEED_ENVIRONMENT_PURPOSES,
+  TREESEED_ENVIRONMENT_REQUIREMENTS,
+  TREESEED_ENVIRONMENT_SCOPES,
+  TREESEED_ENVIRONMENT_SENSITIVITY,
+  TREESEED_ENVIRONMENT_TARGETS,
+  getTreeseedEnvironmentSuggestedValues,
+  isTreeseedEnvironmentEntryRelevant,
+  loadTreeseedEnvironmentOverlay,
+  resolveTreeseedEnvironmentContext,
+  resolveTreeseedEnvironmentRegistry,
+  validateTreeseedEnvironmentValues
+};

package/dist/platform/plugin.d.ts

@@ -0,0 +1,2 @@
+export { defineTreeseedPlugin } from './plugins/plugin.ts';
+export type * from './plugins/plugin.ts';

package/dist/platform/plugin.js

@@ -0,0 +1,4 @@
+import { defineTreeseedPlugin } from "./plugins/plugin.js";
+export {
+  defineTreeseedPlugin
+};

package/dist/platform/plugins/constants.d.ts

@@ -0,0 +1,22 @@
+export declare const TREESEED_DEFAULT_PLUGIN_PACKAGE = "@treeseed/core/plugin-default";
+export declare const TREESEED_DEFAULT_PROVIDER_SELECTIONS: {
+    forms: string;
+    operations: string;
+    agents: {
+        execution: string;
+        mutation: string;
+        repository: string;
+        verification: string;
+        notification: string;
+        research: string;
+    };
+    deploy: string;
+    content: {
+        docs: string;
+    };
+    site: string;
+};
+export declare const TREESEED_DEFAULT_PLUGIN_REFERENCES: {
+    package: string;
+    enabled: boolean;
+}[];

package/dist/platform/plugins/constants.js

@@ -0,0 +1,29 @@
+const TREESEED_DEFAULT_PLUGIN_PACKAGE = "@treeseed/core/plugin-default";
+const TREESEED_DEFAULT_PROVIDER_SELECTIONS = {
+  forms: "store_only",
+  operations: "default",
+  agents: {
+    execution: "stub",
+    mutation: "local_branch",
+    repository: "stub",
+    verification: "stub",
+    notification: "stub",
+    research: "stub"
+  },
+  deploy: "cloudflare",
+  content: {
+    docs: "default"
+  },
+  site: "default"
+};
+const TREESEED_DEFAULT_PLUGIN_REFERENCES = [
+  {
+    package: TREESEED_DEFAULT_PLUGIN_PACKAGE,
+    enabled: true
+  }
+];
+export {
+  TREESEED_DEFAULT_PLUGIN_PACKAGE,
+  TREESEED_DEFAULT_PLUGIN_REFERENCES,
+  TREESEED_DEFAULT_PROVIDER_SELECTIONS
+};

package/dist/platform/plugins/plugin.d.ts

@@ -0,0 +1,51 @@
+import type { TreeseedDeployConfig, TreeseedTenantConfig } from '../contracts.ts';
+import type { TreeseedEnvironmentRegistryOverlay } from '../environment.ts';
+import type { SdkGraphRankingProvider } from '../../sdk-types.ts';
+export type TreeseedSiteLayerDefinition = {
+    root: string;
+    kinds?: Array<'pages' | 'styles' | 'components'>;
+};
+export type TreeseedSiteRouteContribution = {
+    pattern: string;
+    entrypoint?: string;
+    resourcePath?: string;
+};
+export type TreeseedSiteExtensionContribution = {
+    routes?: TreeseedSiteRouteContribution[];
+    starlightComponents?: Record<string, string>;
+    customCss?: string[];
+    remarkPlugins?: unknown[];
+    rehypePlugins?: unknown[];
+    envSchema?: Record<string, unknown>;
+    vitePlugins?: unknown[];
+    integrations?: unknown[];
+    routeMiddleware?: unknown[];
+};
+export type TreeseedPluginSiteContext = {
+    projectRoot: string;
+    tenantConfig: TreeseedTenantConfig;
+    siteConfig?: unknown;
+    deployConfig?: TreeseedDeployConfig;
+    pluginConfig: Record<string, unknown>;
+};
+export type TreeseedPluginEnvironmentContext = {
+    projectRoot: string;
+    tenantConfig?: TreeseedTenantConfig;
+    deployConfig?: TreeseedDeployConfig;
+    pluginConfig: Record<string, unknown>;
+};
+export type TreeseedGraphRankingProviderContribution = SdkGraphRankingProvider | ((context: TreeseedPluginEnvironmentContext) => SdkGraphRankingProvider | undefined);
+export interface TreeseedPlugin {
+    id?: string;
+    provides?: Record<string, any> & {
+        operations?: string[];
+    };
+    operationProviders?: Record<string, unknown>;
+    siteProviders?: Record<string, TreeseedSiteExtensionContribution | ((context: TreeseedPluginSiteContext) => TreeseedSiteExtensionContribution)>;
+    siteHooks?: TreeseedSiteExtensionContribution | ((context: TreeseedPluginSiteContext) => TreeseedSiteExtensionContribution);
+    siteLayers?: TreeseedSiteLayerDefinition[] | ((context: TreeseedPluginSiteContext) => TreeseedSiteLayerDefinition[] | undefined);
+    environmentRegistry?: TreeseedEnvironmentRegistryOverlay | ((context: TreeseedPluginEnvironmentContext) => TreeseedEnvironmentRegistryOverlay | undefined);
+    graphRankingProviders?: Record<string, TreeseedGraphRankingProviderContribution>;
+    [key: string]: unknown;
+}
+export declare function defineTreeseedPlugin<T extends TreeseedPlugin>(plugin: T): T;

package/dist/platform/plugins/plugin.js

@@ -0,0 +1,6 @@
+function defineTreeseedPlugin(plugin) {
+  return plugin;
+}
+export {
+  defineTreeseedPlugin
+};

package/dist/platform/plugins/runtime.d.ts

@@ -0,0 +1,35 @@
+import type { TreeseedDeployConfig } from '../contracts.ts';
+import type { TreeseedPluginEnvironmentContext } from './plugin.ts';
+import type { SdkGraphRankingProvider } from '../../sdk-types.ts';
+type LoadedPluginEntry = {
+    package: string;
+    config: Record<string, unknown>;
+    baseDir: string;
+    plugin: Record<string, any>;
+};
+export type LoadedTreeseedPluginEntry = LoadedPluginEntry;
+export declare function loadTreeseedPlugins(config?: TreeseedDeployConfig): LoadedPluginEntry[];
+export declare function loadTreeseedPluginRuntime(config?: TreeseedDeployConfig): {
+    config: TreeseedDeployConfig;
+    plugins: LoadedPluginEntry[];
+    provided: {
+        forms: Set<string>;
+        operations: Set<string>;
+        agents: {
+            execution: Set<string>;
+            mutation: Set<string>;
+            repository: Set<string>;
+            verification: Set<string>;
+            notification: Set<string>;
+            research: Set<string>;
+            handlers: Set<string>;
+        };
+        deploy: Set<string>;
+        content: {
+            docs: Set<string>;
+        };
+        site: Set<string>;
+    };
+};
+export declare function resolveTreeseedGraphRankingProvider(plugins: LoadedPluginEntry[], context: Omit<TreeseedPluginEnvironmentContext, 'pluginConfig'>): SdkGraphRankingProvider | null;
+export {};

package/dist/platform/plugins/runtime.js

@@ -0,0 +1,161 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadTreeseedDeployConfig } from "../deploy/config.js";
+import { TREESEED_DEFAULT_PLUGIN_PACKAGE } from "./constants.js";
+const require2 = createRequire(import.meta.url);
+const runtimeDir = path.dirname(fileURLToPath(import.meta.url));
+function normalizeLoadedPlugin(moduleExports, packageName) {
+  const plugin = moduleExports?.default ?? moduleExports;
+  if (!plugin || typeof plugin !== "object") {
+    throw new Error(`Treeseed plugin "${packageName}" did not export a plugin object.`);
+  }
+  return plugin;
+}
+function isPathLikePluginReference(packageName) {
+  return packageName.startsWith(".") || packageName.startsWith("/") || packageName.startsWith("file:");
+}
+function resolveLocalDefaultPluginPath() {
+  const candidates = [
+    path.resolve(runtimeDir, "../../../../core/dist/plugin-default.js")
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+function resolveInstalledPluginPath(packageName, tenantRoot) {
+  return require2.resolve(packageName, {
+    paths: [tenantRoot, process.cwd()]
+  });
+}
+function loadPluginModule(packageName, tenantRoot) {
+  if (packageName === TREESEED_DEFAULT_PLUGIN_PACKAGE) {
+    const localDefaultPluginPath = resolveLocalDefaultPluginPath();
+    const resolvedPath2 = localDefaultPluginPath ?? resolveInstalledPluginPath(packageName, tenantRoot);
+    return {
+      moduleExports: require2(resolvedPath2),
+      baseDir: path.dirname(resolvedPath2)
+    };
+  }
+  if (isPathLikePluginReference(packageName)) {
+    const resolvedPath2 = packageName.startsWith("file:") ? fileURLToPath(packageName) : path.resolve(tenantRoot, packageName);
+    return {
+      moduleExports: require2(resolvedPath2),
+      baseDir: path.dirname(resolvedPath2)
+    };
+  }
+  const resolvedPath = resolveInstalledPluginPath(packageName, tenantRoot);
+  return {
+    moduleExports: require2(resolvedPath),
+    baseDir: path.dirname(resolvedPath)
+  };
+}
+function loadTreeseedPlugins(config = loadTreeseedDeployConfig()) {
+  const tenantRoot = config.__tenantRoot ?? process.cwd();
+  const plugins = [];
+  for (const pluginRef of config.plugins ?? []) {
+    if (pluginRef?.enabled === false) {
+      continue;
+    }
+    const loaded = loadPluginModule(pluginRef.package, tenantRoot);
+    const plugin = normalizeLoadedPlugin(loaded.moduleExports, pluginRef.package);
+    plugins.push({
+      package: pluginRef.package,
+      config: pluginRef.config ?? {},
+      baseDir: loaded.baseDir,
+      plugin
+    });
+  }
+  return plugins;
+}
+function collectProvidedIds(plugins) {
+  const provided = {
+    forms: /* @__PURE__ */ new Set(),
+    operations: /* @__PURE__ */ new Set(),
+    agents: {
+      execution: /* @__PURE__ */ new Set(),
+      mutation: /* @__PURE__ */ new Set(),
+      repository: /* @__PURE__ */ new Set(),
+      verification: /* @__PURE__ */ new Set(),
+      notification: /* @__PURE__ */ new Set(),
+      research: /* @__PURE__ */ new Set(),
+      handlers: /* @__PURE__ */ new Set()
+    },
+    deploy: /* @__PURE__ */ new Set(),
+    content: {
+      docs: /* @__PURE__ */ new Set()
+    },
+    site: /* @__PURE__ */ new Set()
+  };
+  for (const { plugin } of plugins) {
+    for (const id of plugin.provides?.forms ?? []) provided.forms.add(id);
+    for (const id of plugin.provides?.operations ?? []) provided.operations.add(id);
+    for (const id of plugin.provides?.agents?.execution ?? []) provided.agents.execution.add(id);
+    for (const id of plugin.provides?.agents?.mutation ?? []) provided.agents.mutation.add(id);
+    for (const id of plugin.provides?.agents?.repository ?? []) provided.agents.repository.add(id);
+    for (const id of plugin.provides?.agents?.verification ?? []) provided.agents.verification.add(id);
+    for (const id of plugin.provides?.agents?.notification ?? []) provided.agents.notification.add(id);
+    for (const id of plugin.provides?.agents?.research ?? []) provided.agents.research.add(id);
+    for (const id of plugin.provides?.agents?.handlers ?? []) provided.agents.handlers.add(id);
+    for (const id of plugin.provides?.deploy ?? []) provided.deploy.add(id);
+    for (const id of plugin.provides?.content?.docs ?? []) provided.content.docs.add(id);
+    for (const id of plugin.provides?.site ?? []) provided.site.add(id);
+  }
+  return provided;
+}
+function assertSelectedProvider(provided, label, id) {
+  if (!id) {
+    throw new Error(`Treeseed plugin runtime is missing selected provider id for ${label}.`);
+  }
+  if (!provided.has(id)) {
+    throw new Error(`Treeseed plugin runtime could not resolve ${label} provider "${id}".`);
+  }
+}
+function loadTreeseedPluginRuntime(config = loadTreeseedDeployConfig()) {
+  const plugins = loadTreeseedPlugins(config);
+  const provided = collectProvidedIds(plugins);
+  const providers = config.providers;
+  assertSelectedProvider(provided.forms, "forms", providers.forms);
+  assertSelectedProvider(provided.operations, "operations", providers.operations);
+  assertSelectedProvider(provided.agents.execution, "agents.execution", providers.agents.execution);
+  assertSelectedProvider(provided.agents.mutation, "agents.mutation", providers.agents.mutation);
+  assertSelectedProvider(provided.agents.repository, "agents.repository", providers.agents.repository);
+  assertSelectedProvider(provided.agents.verification, "agents.verification", providers.agents.verification);
+  assertSelectedProvider(provided.agents.notification, "agents.notification", providers.agents.notification);
+  assertSelectedProvider(provided.agents.research, "agents.research", providers.agents.research);
+  assertSelectedProvider(provided.deploy, "deploy", providers.deploy);
+  assertSelectedProvider(provided.content.docs, "content.docs", providers.content?.docs);
+  assertSelectedProvider(provided.site, "site", providers.site);
+  return {
+    config,
+    plugins,
+    provided
+  };
+}
+function resolveTreeseedGraphRankingProvider(plugins, context) {
+  for (const entry of plugins) {
+    const contributions = entry.plugin.graphRankingProviders;
+    if (!contributions || typeof contributions !== "object") {
+      continue;
+    }
+    for (const contribution of Object.values(contributions)) {
+      if (!contribution) {
+        continue;
+      }
+      const provider = typeof contribution === "function" ? contribution({ ...context, pluginConfig: entry.config ?? {} }) : contribution;
+      if (provider) {
+        return provider;
+      }
+    }
+  }
+  return null;
+}
+export {
+  loadTreeseedPluginRuntime,
+  loadTreeseedPlugins,
+  resolveTreeseedGraphRankingProvider
+};

package/dist/platform/plugins.d.ts

@@ -0,0 +1,6 @@
+export { TREESEED_DEFAULT_PLUGIN_PACKAGE, TREESEED_DEFAULT_PLUGIN_REFERENCES, TREESEED_DEFAULT_PROVIDER_SELECTIONS, } from './plugins/constants.ts';
+export { getTreeseedAgentProviderSelections, getTreeseedDeployConfig, getTreeseedDeployProvider, getTreeseedDocsProvider, getTreeseedFormsProvider, getTreeseedOperationsProvider, getTreeseedSiteProvider, isTreeseedSmtpEnabled, isTreeseedTurnstileEnabled, resetTreeseedDeployConfigForTests, } from './deploy-runtime.ts';
+export { defineTreeseedPlugin } from './plugins/plugin.ts';
+export type * from './plugins/plugin.ts';
+export { loadTreeseedPluginRuntime, loadTreeseedPlugins, resolveTreeseedGraphRankingProvider } from './plugins/runtime.ts';
+export type { LoadedTreeseedPluginEntry } from './plugins/runtime.ts';