@treeseed/sdk 0.1.1 → 0.3.0

package/dist/operations-types.d.ts

@@ -0,0 +1,71 @@
+export type TreeseedOperationGroup = 'Workflow' | 'Local Development' | 'Validation' | 'Release Utilities' | 'Utilities' | 'Passthrough';
+export type TreeseedOperationId = 'workspace.status' | 'workspace.doctor' | 'branch.tasks' | 'branch.switch' | 'branch.save' | 'branch.close' | 'branch.stage' | 'deploy.release' | 'deploy.rollback' | 'deploy.destroy' | 'template.list' | 'template.show' | 'template.validate' | 'template.sync' | 'project.init' | 'project.config' | 'local.dev' | 'local.devWatch' | 'local.build' | 'local.check' | 'local.preview' | 'local.lint' | 'local.test' | 'validation.testUnit' | 'validation.preflight' | 'validation.authCheck' | 'auth.login' | 'auth.logout' | 'auth.whoami' | 'release.testE2e' | 'release.testE2eLocal' | 'release.testE2eStaging' | 'release.testE2eFull' | 'release.testFast' | 'release.verify' | 'release.publishChanged' | 'services.mailpitUp' | 'services.mailpitDown' | 'services.mailpitLogs' | 'data.d1MigrateLocal' | 'content.cleanupMarkdown' | 'content.cleanupMarkdownCheck' | 'tools.astro' | 'tools.syncDevvars' | 'tools.starlightPatch' | 'agents.run';
+export type TreeseedOperationProviderId = 'default';
+export type TreeseedOperationMetadata = {
+    id: TreeseedOperationId;
+    name: string;
+    aliases: string[];
+    group: TreeseedOperationGroup;
+    summary: string;
+    description: string;
+    provider: TreeseedOperationProviderId;
+    related?: string[];
+};
+export type TreeseedOperationRequest = {
+    operationName: string;
+    input?: Record<string, unknown>;
+};
+export type TreeseedOperationResult<TPayload = Record<string, unknown>> = {
+    operation: TreeseedOperationId;
+    ok: boolean;
+    payload?: TPayload | null;
+    meta?: Record<string, unknown>;
+    nextSteps?: Array<{
+        operation: string;
+        reason?: string;
+        input?: Record<string, unknown>;
+    }>;
+    exitCode?: number;
+    stdout?: string[];
+    stderr?: string[];
+};
+export type TreeseedOperationWriter = (output: string, stream?: 'stdout' | 'stderr') => void;
+export type TreeseedOperationPrompt = (message: string) => Promise<string> | string;
+export type TreeseedOperationConfirm = (message: string, expected: string) => Promise<boolean> | boolean;
+export type TreeseedOperationSpawn = (command: string, args: string[], options: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    stdio?: 'inherit';
+}) => {
+    status?: number | null;
+};
+export type TreeseedOperationContext = {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    write?: TreeseedOperationWriter;
+    spawn?: TreeseedOperationSpawn;
+    outputFormat?: 'human' | 'json';
+    prompt?: TreeseedOperationPrompt;
+    confirm?: TreeseedOperationConfirm;
+    transport?: 'sdk' | 'cli' | 'api';
+};
+export type TreeseedOperationFailureCode = 'validation_failed' | 'merge_conflict' | 'missing_runtime_auth' | 'deployment_timeout' | 'confirmation_required' | 'unsupported_transport' | 'unsupported_state' | 'provider_resolution_failed';
+export declare class TreeseedOperationError extends Error {
+    code: TreeseedOperationFailureCode;
+    operation: string;
+    details?: Record<string, unknown>;
+    exitCode?: number;
+    constructor(operation: string, code: TreeseedOperationFailureCode, message: string, options?: {
+        details?: Record<string, unknown>;
+        exitCode?: number;
+    });
+}
+export interface TreeseedOperationImplementation<TInput extends Record<string, unknown> = Record<string, unknown>, TPayload = Record<string, unknown>> {
+    readonly metadata: TreeseedOperationMetadata;
+    execute(input: TInput, context: TreeseedOperationContext): Promise<TreeseedOperationResult<TPayload>>;
+}
+export interface TreeseedOperationProvider {
+    readonly id: TreeseedOperationProviderId | string;
+    listOperations(): TreeseedOperationImplementation[];
+    findOperation(name: string | null | undefined): TreeseedOperationImplementation | null;
+}

package/dist/operations-types.js

@@ -0,0 +1,17 @@
+class TreeseedOperationError extends Error {
+  code;
+  operation;
+  details;
+  exitCode;
+  constructor(operation, code, message, options = {}) {
+    super(message);
+    this.name = "TreeseedOperationError";
+    this.operation = operation;
+    this.code = code;
+    this.details = options.details;
+    this.exitCode = options.exitCode;
+  }
+}
+export {
+  TreeseedOperationError
+};

package/dist/operations.d.ts

@@ -0,0 +1,6 @@
+export { TRESEED_OPERATION_SPECS, findTreeseedOperation, listTreeseedOperationNames, } from './operations-registry.ts';
+export { TreeseedOperationsSdk } from './operations/runtime.ts';
+export type { TreeseedOperationContext, TreeseedOperationImplementation, TreeseedOperationId, TreeseedOperationMetadata, TreeseedOperationProvider, TreeseedOperationProviderId, TreeseedOperationRequest, TreeseedOperationResult, TreeseedOperationGroup, } from './operations-types.ts';
+export { TreeseedOperationError } from './operations-types.ts';
+export { TreeseedWorkflowSdk } from './workflow.ts';
+export type * from './workflow.ts';

package/dist/operations.js

@@ -0,0 +1,16 @@
+import {
+  TRESEED_OPERATION_SPECS,
+  findTreeseedOperation,
+  listTreeseedOperationNames
+} from "./operations-registry.js";
+import { TreeseedOperationsSdk } from "./operations/runtime.js";
+import { TreeseedOperationError } from "./operations-types.js";
+import { TreeseedWorkflowSdk } from "./workflow.js";
+export {
+  TRESEED_OPERATION_SPECS,
+  TreeseedOperationError,
+  TreeseedOperationsSdk,
+  TreeseedWorkflowSdk,
+  findTreeseedOperation,
+  listTreeseedOperationNames
+};

package/dist/platform/books-data.d.ts

@@ -0,0 +1 @@
+export * from './utils/books-data.ts';

package/dist/platform/books-data.js

@@ -0,0 +1 @@
+export * from "./utils/books-data.js";

package/dist/platform/contracts.d.ts

@@ -0,0 +1,158 @@
+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 TreeseedManagedServiceEnvironmentConfig {
+    baseUrl?: string;
+    domain?: string;
+    railwayEnvironment?: string;
+}
+export interface TreeseedManagedServiceRailwayConfig {
+    projectId?: string;
+    projectName?: string;
+    serviceId?: string;
+    serviceName?: string;
+    rootDir?: string;
+    buildCommand?: string;
+    startCommand?: string;
+}
+export interface TreeseedManagedServiceConfig {
+    enabled?: boolean;
+    provider?: string;
+    rootDir?: string;
+    publicBaseUrl?: string;
+    railway?: TreeseedManagedServiceRailwayConfig;
+    environments?: Partial<Record<'local' | 'staging' | 'prod', TreeseedManagedServiceEnvironmentConfig>>;
+}
+export interface TreeseedManagedServicesConfig {
+    api?: TreeseedManagedServiceConfig;
+    agents?: TreeseedManagedServiceConfig;
+}
+export interface TreeseedProviderSelections {
+    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 interface TreeseedDeployConfig {
+    name: string;
+    slug: string;
+    siteUrl: string;
+    contactEmail: string;
+    cloudflare: {
+        accountId: string;
+        workerName?: string;
+    };
+    plugins: TreeseedPluginReference[];
+    providers: TreeseedProviderSelections;
+    services?: TreeseedManagedServicesConfig;
+    smtp?: {
+        enabled?: boolean;
+    };
+    turnstile?: {
+        enabled?: boolean;
+    };
+}
+export interface TreeseedTenantConfig {
+    id: string;
+    siteConfigPath: string;
+    content: TreeseedContentMap;
+    features: TreeseedFeatureModules;
+    overrides?: {
+        pagesRoot?: string;
+        stylesRoot?: string;
+        componentsRoot?: string;
+    };
+}

package/dist/platform/deploy/config.d.ts

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

package/dist/platform/deploy/config.js

@@ -0,0 +1,222 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { normalizeAliasedRecord } from "../../field-aliases.js";
+import { resolveTreeseedTenantRoot } from "../tenant/config.js";
+import {
+  TREESEED_DEFAULT_PLUGIN_REFERENCES,
+  TREESEED_DEFAULT_PROVIDER_SELECTIONS
+} from "../plugins/constants.js";
+const deployConfigFieldAliases = {
+  siteUrl: { key: "siteUrl", aliases: ["site_url"] },
+  contactEmail: { key: "contactEmail", aliases: ["contact_email"] }
+};
+const cloudflareFieldAliases = {
+  accountId: { key: "accountId", aliases: ["account_id"] },
+  workerName: { key: "workerName", aliases: ["worker_name"] }
+};
+const CLOUDFLARE_ACCOUNT_ID_PLACEHOLDER = "replace-with-cloudflare-account-id";
+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 optionalCloudflareAccountId(value) {
+  const accountId = optionalString(value);
+  return accountId === CLOUDFLARE_ACCOUNT_ID_PLACEHOLDER ? void 0 : accountId;
+}
+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"),
+    operations: expectString(record.operations ?? TREESEED_DEFAULT_PROVIDER_SELECTIONS.operations, "providers.operations"),
+    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 parseServiceEnvironmentConfig(value, label) {
+  const record = optionalRecord(value, label) ?? {};
+  return {
+    baseUrl: optionalString(record.baseUrl),
+    domain: optionalString(record.domain),
+    railwayEnvironment: optionalString(record.railwayEnvironment)
+  };
+}
+function parseManagedServiceConfig(value, label) {
+  const record = optionalRecord(value, label);
+  if (!record) {
+    return void 0;
+  }
+  const railway = optionalRecord(record.railway, `${label}.railway`) ?? {};
+  const environments = optionalRecord(record.environments, `${label}.environments`) ?? {};
+  return {
+    enabled: record.enabled === void 0 ? void 0 : optionalBoolean(record.enabled, `${label}.enabled`),
+    provider: optionalString(record.provider),
+    rootDir: optionalString(record.rootDir),
+    publicBaseUrl: optionalString(record.publicBaseUrl),
+    railway: {
+      projectId: optionalString(railway.projectId),
+      projectName: optionalString(railway.projectName),
+      serviceId: optionalString(railway.serviceId),
+      serviceName: optionalString(railway.serviceName),
+      rootDir: optionalString(railway.rootDir),
+      buildCommand: optionalString(railway.buildCommand),
+      startCommand: optionalString(railway.startCommand)
+    },
+    environments: {
+      local: parseServiceEnvironmentConfig(environments.local, `${label}.environments.local`),
+      staging: parseServiceEnvironmentConfig(environments.staging, `${label}.environments.staging`),
+      prod: parseServiceEnvironmentConfig(environments.prod, `${label}.environments.prod`)
+    }
+  };
+}
+function parseManagedServicesConfig(value) {
+  const record = optionalRecord(value, "services");
+  if (!record) {
+    return void 0;
+  }
+  return {
+    api: parseManagedServiceConfig(record.api, "services.api"),
+    agents: parseManagedServiceConfig(record.agents, "services.agents")
+  };
+}
+function parseDeployConfig(raw) {
+  const parsed = normalizeAliasedRecord(
+    deployConfigFieldAliases,
+    parseYaml(raw) ?? {}
+  );
+  const cloudflare = normalizeAliasedRecord(
+    cloudflareFieldAliases,
+    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: optionalCloudflareAccountId(cloudflare.accountId) ?? optionalCloudflareAccountId(process.env.CLOUDFLARE_ACCOUNT_ID) ?? CLOUDFLARE_ACCOUNT_ID_PLACEHOLDER,
+      workerName: optionalString(cloudflare.workerName)
+    },
+    plugins: parsePluginReferences(parsed.plugins),
+    providers: parseProviderSelections(parsed.providers),
+    services: parseManagedServicesConfig(parsed.services),
+    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;
+}
+export {
+  deriveCloudflareWorkerName,
+  loadTreeseedDeployConfig,
+  resolveTreeseedDeployConfigPath
+};

package/dist/platform/deploy-config.d.ts

@@ -0,0 +1 @@
+export * from './deploy/config.ts';

package/dist/platform/deploy-config.js

@@ -0,0 +1 @@
+export * from "./deploy/config.js";