@treeseed/core 0.1.2 → 0.3.0

package/README.md

@@ -6,7 +6,7 @@ This repository is the package root. Run package commands from [`core`](./), not
 
 ## Requirements
 
-- Node `>=20`
+- Node `>=22`
 - npm `>=10`
 
 ## Install

package/dist/config.d.ts

@@ -0,0 +1 @@
+export declare function createTreeseedTenantSite(manifestPath?: string): import('astro').AstroUserConfig<never, never, never>;

package/dist/content-config.d.ts

@@ -0,0 +1,10 @@
+export declare function createTreeseedTenantCollections(manifestPath?: string): {
+	pages: any;
+	notes: any;
+	questions: any;
+	objectives: any;
+	people: any;
+	agents: any;
+	books: any;
+	docs: any;
+};

package/dist/content.js

@@ -14,6 +14,7 @@ import {
   PEOPLE_MODEL_DEFAULTS,
   QUESTION_MODEL_DEFAULTS
 } from "./utils/site-config.js";
+import { preprocessAliasedRecord } from "@treeseed/sdk/field-aliases";
 const statusValues = ["live", "in progress", "exploratory", "planned", "speculative"];
 const pageLayoutValues = ["article", "bridge"];
 const questionTypeValues = ["research", "implementation", "strategy", "evaluation"];
@@ -63,6 +64,39 @@ function resolveDocsCollectionProvider(tenantConfig, dependencies) {
   throw new Error(`Treeseed docs provider "${selectedId}" is not registered.`);
 }
 function createTreeseedCollections(tenantConfig, { docsLoader, docsSchema }) {
+  const pageFieldAliases = {
+    pageLayout: { key: "pageLayout", aliases: ["page_layout"] },
+    seoTitle: { key: "seoTitle", aliases: ["seo_title"] },
+    seoDescription: { key: "seoDescription", aliases: ["seo_description"] }
+  };
+  const questionFieldAliases = {
+    questionType: { key: "questionType", aliases: ["question_type"] },
+    primaryContributor: { key: "primaryContributor", aliases: ["primary_contributor"] },
+    relatedObjectives: { key: "relatedObjectives", aliases: ["related_objectives"] },
+    relatedBooks: { key: "relatedBooks", aliases: ["related_books"] }
+  };
+  const objectiveFieldAliases = {
+    timeHorizon: { key: "timeHorizon", aliases: ["time_horizon"] },
+    primaryContributor: { key: "primaryContributor", aliases: ["primary_contributor"] },
+    relatedQuestions: { key: "relatedQuestions", aliases: ["related_questions"] },
+    relatedBooks: { key: "relatedBooks", aliases: ["related_books"] }
+  };
+  const agentFieldAliases = {
+    runtimeStatus: { key: "runtimeStatus", aliases: ["runtime_status"] },
+    systemPrompt: { key: "systemPrompt", aliases: ["system_prompt"] },
+    triggerPolicy: { key: "triggerPolicy", aliases: ["trigger_policy"] }
+  };
+  const bookFieldAliases = {
+    sectionLabel: { key: "sectionLabel", aliases: ["section_label"] },
+    basePath: { key: "basePath", aliases: ["base_path"] },
+    landingPath: { key: "landingPath", aliases: ["landing_path"] },
+    outlinePath: { key: "outlinePath", aliases: ["outline_path"] },
+    downloadFileName: { key: "downloadFileName", aliases: ["download_file_name"] },
+    downloadHref: { key: "downloadHref", aliases: ["download_href"] },
+    downloadTitle: { key: "downloadTitle", aliases: ["download_title"] },
+    exportRoots: { key: "exportRoots", aliases: ["export_roots"] },
+    sidebarItems: { key: "sidebarItems", aliases: ["sidebar_items"] }
+  };
   const contributorReference = z.union([reference("people"), reference("agents")]);
   const sidebarItemSchema = z.lazy(
     () => z.object({
@@ -72,7 +106,7 @@ function createTreeseedCollections(tenantConfig, { docsLoader, docsSchema }) {
       items: z.array(sidebarItemSchema).optional()
     })
   );
-  const pageSchema = z.object({
+  const pageSchema = z.preprocess((value) => preprocessAliasedRecord(pageFieldAliases, value), z.object({
     title: z.string(),
     description: z.string(),
     slug: z.string(),
@@ -84,7 +118,7 @@ function createTreeseedCollections(tenantConfig, { docsLoader, docsSchema }) {
     updated: z.coerce.date(),
     seoTitle: z.string().optional(),
     seoDescription: z.string().optional()
-  });
+  }));
   const noteSchema = z.object({
     title: z.string(),
     description: z.string(),
@@ -96,7 +130,7 @@ function createTreeseedCollections(tenantConfig, { docsLoader, docsSchema }) {
     draft: z.boolean().default(NOTE_MODEL_DEFAULTS.draft ?? false),
     canonicalRoute: z.string().optional()
   });
-  const questionSchema = z.object({
+  const questionSchema = z.preprocess((value) => preprocessAliasedRecord(questionFieldAliases, value), z.object({
     title: z.string(),
     description: z.string(),
     date: z.coerce.date(),
@@ -109,8 +143,8 @@ function createTreeseedCollections(tenantConfig, { docsLoader, docsSchema }) {
     primaryContributor: contributorReference,
     relatedObjectives: z.array(reference("objectives")).default([]),
     relatedBooks: z.array(reference("books")).default([])
-  });
-  const objectiveSchema = z.object({
+  }));
+  const objectiveSchema = z.preprocess((value) => preprocessAliasedRecord(objectiveFieldAliases, value), z.object({
     title: z.string(),
     description: z.string(),
     date: z.coerce.date(),
@@ -123,7 +157,7 @@ function createTreeseedCollections(tenantConfig, { docsLoader, docsSchema }) {
     primaryContributor: contributorReference,
     relatedQuestions: z.array(reference("questions")).default([]),
     relatedBooks: z.array(reference("books")).default([])
-  });
+  }));
   const profileLinkSchema = z.object({ label: z.string(), href: z.string() });
   const agentCliSchema = z.object({
     model: z.string().optional(),
@@ -170,7 +204,7 @@ function createTreeseedCollections(tenantConfig, { docsLoader, docsSchema }) {
     relatedQuestions: z.array(reference("questions")).default([]),
     relatedObjectives: z.array(reference("objectives")).default([])
   });
-  const agentSchema = z.object({
+  const agentSchema = z.preprocess((value) => preprocessAliasedRecord(agentFieldAliases, value), z.object({
     name: z.string(),
     slug: z.string(),
     handler: z.string(),
@@ -192,8 +226,8 @@ function createTreeseedCollections(tenantConfig, { docsLoader, docsSchema }) {
     permissions: z.array(agentPermissionSchema).min(1),
     execution: agentExecutionSchema.default({}),
     outputs: agentOutputSchema.default({})
-  });
-  const bookSchema = z.object({
+  }));
+  const bookSchema = z.preprocess((value) => preprocessAliasedRecord(bookFieldAliases, value), z.object({
     order: z.number().int().nonnegative(),
     slug: z.string(),
     title: z.string(),
@@ -209,7 +243,7 @@ function createTreeseedCollections(tenantConfig, { docsLoader, docsSchema }) {
     exportRoots: z.array(z.string()).min(1).optional(),
     sidebarItems: z.array(sidebarItemSchema).min(1),
     tags: z.array(z.string()).default(BOOK_MODEL_DEFAULTS.tags ?? [])
-  });
+  }));
   const docsCollectionProvider = resolveDocsCollectionProvider(tenantConfig, { docsLoader, docsSchema });
   return {
     pages: defineCollection({ loader: glob({ pattern: "**/*.{md,mdx}", base: tenantConfig.content.pages }), schema: pageSchema }),

package/dist/contracts.d.ts

@@ -1,130 +1 @@
-export type TreeseedFeatureName = 'docs' | 'books' | 'notes' | 'questions' | 'objectives' | 'agents' | 'forms';
-export type TreeseedContentCollection = 'pages' | 'notes' | 'questions' | 'objectives' | 'people' | 'agents' | 'books' | 'docs';
-export interface TreeseedFeatureModules {
-    docs?: boolean;
-    books?: boolean;
-    notes?: boolean;
-    questions?: boolean;
-    objectives?: boolean;
-    agents?: boolean;
-    forms?: boolean;
-    [key: string]: boolean | undefined;
-}
-export interface TreeseedContentMap {
-    pages: string;
-    notes: string;
-    questions: string;
-    objectives: string;
-    people: string;
-    agents: string;
-    books: string;
-    docs: string;
-}
-export interface TreeseedBookDefinition {
-    order: number;
-    slug: string;
-    title: string;
-    description: string;
-    summary: string;
-    sectionLabel: string;
-    basePath: string;
-    landingPath: string;
-    outlinePath?: string;
-    downloadFileName: string;
-    downloadHref: string;
-    downloadTitle: string;
-    exportRoots?: string[];
-    sidebarItems: Array<{
-        label: string;
-        link?: string;
-        autogenerate?: {
-            directory: string;
-        };
-        items?: TreeseedBookDefinition['sidebarItems'];
-    }>;
-    tags?: string[];
-    id?: string;
-}
-export interface TreeseedThemeConfig {
-    surfaces?: {
-        background?: string;
-        backgroundElevated?: string;
-        backgroundSoft?: string;
-        panel?: string;
-        panelStrong?: string;
-    };
-    text?: {
-        body?: string;
-        muted?: string;
-        soft?: string;
-    };
-    border?: {
-        base?: string;
-        strong?: string;
-        grid?: string;
-    };
-    accent?: {
-        base?: string;
-        strong?: string;
-        soft?: string;
-    };
-    info?: {
-        base?: string;
-        strong?: string;
-        soft?: string;
-    };
-    warm?: {
-        base?: string;
-        strong?: string;
-    };
-}
-export interface TreeseedPluginReference {
-    package: string;
-    enabled?: boolean;
-    config?: Record<string, unknown>;
-}
-export interface TreeseedProviderSelections {
-    forms: string;
-    agents: {
-        execution: string;
-        mutation: string;
-        repository: string;
-        verification: string;
-        notification: string;
-        research: string;
-    };
-    deploy: string;
-    content?: {
-        docs: string;
-    };
-    site?: string;
-}
-export interface TreeseedDeployConfig {
-    name: string;
-    slug: string;
-    siteUrl: string;
-    contactEmail: string;
-    cloudflare: {
-        accountId: string;
-        workerName?: string;
-    };
-    plugins: TreeseedPluginReference[];
-    providers: TreeseedProviderSelections;
-    smtp?: {
-        enabled?: boolean;
-    };
-    turnstile?: {
-        enabled?: boolean;
-    };
-}
-export interface TreeseedTenantConfig {
-    id: string;
-    siteConfigPath: string;
-    content: TreeseedContentMap;
-    features: TreeseedFeatureModules;
-    overrides?: {
-        pagesRoot?: string;
-        stylesRoot?: string;
-        componentsRoot?: string;
-    };
-}
+export type { TreeseedBookDefinition, TreeseedContentCollection, TreeseedContentMap, TreeseedDeployConfig, TreeseedFeatureModules, TreeseedFeatureName, TreeseedManagedServiceConfig, TreeseedManagedServiceEnvironmentConfig, TreeseedManagedServiceRailwayConfig, TreeseedManagedServicesConfig, TreeseedPluginReference, TreeseedProviderSelections, TreeseedTenantConfig, TreeseedThemeConfig, } from '@treeseed/sdk/platform/contracts';

package/dist/deploy/config.d.ts

@@ -1,4 +1 @@
-import type { TreeseedDeployConfig } from '../contracts';
-export declare function resolveTreeseedDeployConfigPath(configPath?: string): string;
-export declare function deriveCloudflareWorkerName(config: TreeseedDeployConfig): string;
-export declare function loadTreeseedDeployConfig(configPath?: string): TreeseedDeployConfig;
+export { deriveCloudflareWorkerName, loadTreeseedDeployConfig, resolveTreeseedDeployConfigPath, } from '@treeseed/sdk/platform/deploy-config';

package/dist/deploy/config.js

@@ -1,152 +1,8 @@
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
-import { parse as parseYaml } from "yaml";
-import { resolveTreeseedTenantRoot } from "../tenant/config.js";
 import {
-  TREESEED_DEFAULT_PLUGIN_REFERENCES,
-  TREESEED_DEFAULT_PROVIDER_SELECTIONS
-} from "../plugins/constants.js";
-function expectString(value, label) {
-  if (typeof value !== "string" || !value.trim()) {
-    throw new Error(`Invalid deploy config: expected ${label} to be a non-empty string.`);
-  }
-  return value.trim();
-}
-function optionalString(value) {
-  if (typeof value !== "string" || !value.trim()) {
-    return void 0;
-  }
-  return value.trim();
-}
-function optionalBoolean(value, label) {
-  if (value === void 0) {
-    return void 0;
-  }
-  if (typeof value !== "boolean") {
-    throw new Error(`Invalid deploy config: expected ${label} to be a boolean when provided.`);
-  }
-  return value;
-}
-function optionalRecord(value, label) {
-  if (value === void 0 || value === null) {
-    return void 0;
-  }
-  if (typeof value !== "object" || Array.isArray(value)) {
-    throw new Error(`Invalid deploy config: expected ${label} to be an object when provided.`);
-  }
-  return value;
-}
-function parsePluginReferences(value) {
-  if (value === void 0) {
-    return [...TREESEED_DEFAULT_PLUGIN_REFERENCES];
-  }
-  if (!Array.isArray(value)) {
-    throw new Error("Invalid deploy config: expected plugins to be an array.");
-  }
-  return value.map((entry, index) => {
-    const record = optionalRecord(entry, `plugins[${index}]`);
-    return {
-      package: expectString(record?.package, `plugins[${index}].package`),
-      enabled: record?.enabled === void 0 ? true : optionalBoolean(record.enabled, `plugins[${index}].enabled`),
-      config: record?.config === void 0 ? {} : optionalRecord(record.config, `plugins[${index}].config`)
-    };
-  });
-}
-function parseProviderSelections(value) {
-  const record = optionalRecord(value, "providers");
-  if (!record) {
-    return structuredClone(TREESEED_DEFAULT_PROVIDER_SELECTIONS);
-  }
-  const agentProviders = optionalRecord(record.agents, "providers.agents") ?? {};
-  const contentProviders = optionalRecord(record.content, "providers.content") ?? {};
-  return {
-    forms: expectString(record.forms ?? TREESEED_DEFAULT_PROVIDER_SELECTIONS.forms, "providers.forms"),
-    agents: {
-      execution: expectString(
-        agentProviders.execution ?? TREESEED_DEFAULT_PROVIDER_SELECTIONS.agents.execution,
-        "providers.agents.execution"
-      ),
-      mutation: expectString(
-        agentProviders.mutation ?? TREESEED_DEFAULT_PROVIDER_SELECTIONS.agents.mutation,
-        "providers.agents.mutation"
-      ),
-      repository: expectString(
-        agentProviders.repository ?? TREESEED_DEFAULT_PROVIDER_SELECTIONS.agents.repository,
-        "providers.agents.repository"
-      ),
-      verification: expectString(
-        agentProviders.verification ?? TREESEED_DEFAULT_PROVIDER_SELECTIONS.agents.verification,
-        "providers.agents.verification"
-      ),
-      notification: expectString(
-        agentProviders.notification ?? TREESEED_DEFAULT_PROVIDER_SELECTIONS.agents.notification,
-        "providers.agents.notification"
-      ),
-      research: expectString(
-        agentProviders.research ?? TREESEED_DEFAULT_PROVIDER_SELECTIONS.agents.research,
-        "providers.agents.research"
-      )
-    },
-    deploy: expectString(record.deploy ?? TREESEED_DEFAULT_PROVIDER_SELECTIONS.deploy, "providers.deploy"),
-    content: {
-      docs: expectString(
-        contentProviders.docs ?? TREESEED_DEFAULT_PROVIDER_SELECTIONS.content.docs,
-        "providers.content.docs"
-      )
-    },
-    site: expectString(record.site ?? TREESEED_DEFAULT_PROVIDER_SELECTIONS.site, "providers.site")
-  };
-}
-function parseDeployConfig(raw) {
-  const parsed = parseYaml(raw) ?? {};
-  const cloudflare = optionalRecord(parsed.cloudflare, "cloudflare") ?? {};
-  const smtp = optionalRecord(parsed.smtp, "smtp") ?? {};
-  const turnstile = optionalRecord(parsed.turnstile, "turnstile") ?? {};
-  optionalBoolean(turnstile.enabled, "turnstile.enabled");
-  return {
-    name: expectString(parsed.name, "name"),
-    slug: expectString(parsed.slug, "slug"),
-    siteUrl: expectString(parsed.siteUrl, "siteUrl"),
-    contactEmail: expectString(parsed.contactEmail, "contactEmail"),
-    cloudflare: {
-      accountId: optionalString(cloudflare.accountId) ?? optionalString(process.env.CLOUDFLARE_ACCOUNT_ID) ?? "replace-with-cloudflare-account-id",
-      workerName: optionalString(cloudflare.workerName)
-    },
-    plugins: parsePluginReferences(parsed.plugins),
-    providers: parseProviderSelections(parsed.providers),
-    smtp: {
-      enabled: optionalBoolean(smtp.enabled, "smtp.enabled")
-    },
-    turnstile: {
-      enabled: true
-    }
-  };
-}
-function resolveTreeseedDeployConfigPath(configPath = "treeseed.site.yaml") {
-  const tenantRoot = resolveTreeseedTenantRoot();
-  const candidate = resolve(tenantRoot, configPath);
-  if (!existsSync(candidate)) {
-    throw new Error(`Unable to resolve Treeseed deploy config at "${candidate}".`);
-  }
-  return candidate;
-}
-function deriveCloudflareWorkerName(config) {
-  return config.cloudflare.workerName?.trim() || config.slug;
-}
-function loadTreeseedDeployConfig(configPath = "treeseed.site.yaml") {
-  const resolvedConfigPath = resolveTreeseedDeployConfigPath(configPath);
-  const tenantRoot = dirname(resolvedConfigPath);
-  const parsed = parseDeployConfig(readFileSync(resolvedConfigPath, "utf8"));
-  Object.defineProperty(parsed, "__tenantRoot", {
-    value: tenantRoot,
-    enumerable: false
-  });
-  Object.defineProperty(parsed, "__configPath", {
-    value: resolvedConfigPath,
-    enumerable: false
-  });
-  return parsed;
-}
+  deriveCloudflareWorkerName,
+  loadTreeseedDeployConfig,
+  resolveTreeseedDeployConfigPath
+} from "@treeseed/sdk/platform/deploy-config";
 export {
   deriveCloudflareWorkerName,
   loadTreeseedDeployConfig,

package/dist/deploy/runtime.js

@@ -46,6 +46,9 @@ function resetTreeseedDeployConfigForTests() {
 function getTreeseedFormsProvider() {
   return getTreeseedDeployConfig().providers?.forms ?? TREESEED_DEFAULT_PROVIDER_SELECTIONS.forms;
 }
+function getTreeseedOperationsProvider() {
+  return getTreeseedDeployConfig().providers?.operations ?? TREESEED_DEFAULT_PROVIDER_SELECTIONS.operations;
+}
 function getTreeseedAgentProviderSelections() {
   return getTreeseedDeployConfig().providers?.agents ?? TREESEED_DEFAULT_PROVIDER_SELECTIONS.agents;
 }
@@ -70,6 +73,7 @@ export {
   getTreeseedDeployProvider,
   getTreeseedDocsProvider,
   getTreeseedFormsProvider,
+  getTreeseedOperationsProvider,
   getTreeseedSiteProvider,
   isTreeseedSmtpEnabled,
   isTreeseedTurnstileEnabled,

package/dist/env.yaml

@@ -1,38 +1,109 @@
 entries:
-  CLOUDFLARE_ACCOUNT_ID:
-    label: Cloudflare account ID
-    group: cloudflare
-    description: Identifies the Cloudflare account Treeseed should provision and deploy into.
-    howToGet: In the Cloudflare dashboard, open Workers & Pages or Account Home and copy the account ID.
-    sensitivity: plain
+  GH_TOKEN:
+    label: GitHub access token
+    group: auth
+    description: Personal access token used by Treeseed for GitHub CLI automation, repository setup, CI secret sync, and GitHub Copilot SDK-backed workflows.
+    howToGet: "Create a GitHub fine-grained personal access token scoped to the TreeSeed repository. Required repository permissions: Contents read/write, Environments read/write, Secrets and variables read/write, Actions and workflows read/write, Pull requests read/write, Issues read/write. Then paste it here as GH_TOKEN."
+    sensitivity: secret
     targets:
       - local-file
-      - github-variable
-      - config-file
+      - railway-secret
     scopes:
+      - local
       - staging
       - prod
     requirement: required
     purposes:
       - save
-      - deploy
-      - destroy
       - config
     validation:
       kind: nonempty
     sourcePriority:
       - machine-config
       - process-env
-      - treeseed.site.yaml
   CLOUDFLARE_API_TOKEN:
     label: Cloudflare API token
-    group: cloudflare
-    description: Allows Wrangler and CI to create resources, upload secrets, and publish the Worker.
-    howToGet: Create an API token in the Cloudflare dashboard with Workers and D1 permissions for this account.
+    group: auth
+    description: Account-level Cloudflare API token used by Wrangler and CI to manage Pages, Workers, Workers KV, D1, Queues, DNS, secrets, and deploys.
+    howToGet: "Create a Cloudflare account-level API token scoped to the target domain and account. Required permissions: Account Cloudflare Pages edit, Account Workers Scripts edit, Account Workers KV Storage edit, Account D1 edit, Account Queues edit, Zone DNS edit. Then paste it here as CLOUDFLARE_API_TOKEN."
     sensitivity: secret
     targets:
       - local-file
       - github-secret
+    scopes:
+      - local
+      - staging
+      - prod
+    requirement: required
+    purposes:
+      - save
+      - deploy
+      - destroy
+      - config
+    validation:
+      kind: nonempty
+    sourcePriority:
+      - machine-config
+      - process-env
+  RAILWAY_API_TOKEN:
+    label: Railway API token
+    group: auth
+    description: Primary Railway token for user or workspace scoped access, including project creation and most Treeseed-managed Railway flows.
+    howToGet: In Railway, create a user or workspace API token that can create and manage the target project, then paste it here as RAILWAY_API_TOKEN.
+    sensitivity: secret
+    targets:
+      - local-file
+      - railway-secret
+    scopes:
+      - local
+      - staging
+      - prod
+    requirement: conditional
+    purposes:
+      - deploy
+      - destroy
+      - config
+    validation:
+      kind: nonempty
+    sourcePriority:
+      - machine-config
+      - process-env
+    relevanceRef: railwayManagedEnabled
+    requiredWhenRef: railwayManagedEnabled
+  RAILWAY_TOKEN:
+    label: Railway project token
+    group: auth
+    description: Optional Railway token for project-scoped resource management after a project already exists.
+    howToGet: In Railway, generate a project-scoped token only if you need project resource management separate from the primary API token, then paste it here as RAILWAY_TOKEN.
+    sensitivity: secret
+    targets:
+      - local-file
+      - railway-secret
+    scopes:
+      - local
+      - staging
+      - prod
+    requirement: optional
+    purposes:
+      - deploy
+      - destroy
+      - config
+    validation:
+      kind: nonempty
+    sourcePriority:
+      - machine-config
+      - process-env
+    relevanceRef: railwayManagedEnabled
+  CLOUDFLARE_ACCOUNT_ID:
+    label: Cloudflare account ID
+    group: cloudflare
+    description: Identifies the Cloudflare account Treeseed should provision and deploy into.
+    howToGet: In the Cloudflare dashboard, open Workers & Pages or Account Home and copy the account ID.
+    sensitivity: plain
+    targets:
+      - local-file
+      - github-variable
+      - config-file
     scopes:
       - staging
       - prod
@@ -47,6 +118,7 @@ entries:
     sourcePriority:
       - machine-config
       - process-env
+      - treeseed.site.yaml
   TREESEED_FORM_TOKEN_SECRET:
     label: Forms token secret
     group: forms