@treeseed/sdk 0.1.2 → 0.3.1

package/dist/operations/services/runtime-tools.js

@@ -0,0 +1,358 @@
+import { readFileSync, existsSync } from "node:fs";
+import { dirname, extname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn, spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { parse as parseYaml } from "yaml";
+const require2 = createRequire(import.meta.url);
+const scriptRoot = dirname(fileURLToPath(import.meta.url));
+const packageRootFromSource = resolve(scriptRoot, "..", "..", "..");
+const treeseedRuntimeRoot = resolve(packageRootFromSource, "src", "treeseed");
+const TREESEED_DEFAULT_PLUGIN_REFERENCES = [
+  {
+    package: "@treeseed/core/plugin-default",
+    enabled: true
+  }
+];
+const TREESEED_DEFAULT_PROVIDER_SELECTIONS = {
+  forms: "store_only",
+  agents: {
+    execution: "stub",
+    mutation: "local_branch",
+    repository: "stub",
+    verification: "stub",
+    notification: "stub",
+    research: "stub"
+  },
+  deploy: "cloudflare",
+  content: {
+    docs: "default"
+  },
+  site: "default"
+};
+const TRESEED_MANAGED_SERVICE_KEYS = ["api", "agents", "gateway", "manager", "worker", "workdayStart", "workdayReport"];
+const TRESEED_WORKSPACE_PACKAGE_DIRS = ["sdk", "core", "cli", "agent", "api"];
+const CLOUDFLARE_ACCOUNT_ID_PLACEHOLDER = "replace-with-cloudflare-account-id";
+function parseServiceEnvironmentConfig(value) {
+  const record = optionalRecord(value, "service environment") ?? {};
+  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 cloudflare = optionalRecord(record.cloudflare, `${label}.cloudflare`) ?? {};
+  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),
+    cloudflare: {
+      workerName: optionalString(cloudflare.workerName)
+    },
+    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),
+      staging: parseServiceEnvironmentConfig(environments.staging),
+      prod: parseServiceEnvironmentConfig(environments.prod)
+    }
+  };
+}
+function parseManagedServicesConfig(value) {
+  const record = optionalRecord(value, "services");
+  if (!record) {
+    return void 0;
+  }
+  return Object.fromEntries(
+    TRESEED_MANAGED_SERVICE_KEYS.map((serviceKey) => [
+      serviceKey,
+      parseManagedServiceConfig(record[serviceKey], `services.${serviceKey}`)
+    ])
+  );
+}
+const packageRoot = packageRootFromSource;
+const packageScriptRoot = resolve(packageRoot, "scripts");
+const runtimeRoot = treeseedRuntimeRoot;
+function resolvePackageBinary(packageName, binName = packageName) {
+  const packageJsonPath = require2.resolve(`${packageName}/package.json`);
+  const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+  const binField = packageJson.bin;
+  const relativePath = typeof binField === "string" ? binField : binField?.[binName];
+  if (!relativePath) {
+    throw new Error(`Unable to resolve binary "${binName}" from package "${packageName}".`);
+  }
+  return resolve(dirname(packageJsonPath), relativePath);
+}
+function treeseedWorkspacePackageCheckoutState(root = resolve(packageRoot, "..")) {
+  const packages = TRESEED_WORKSPACE_PACKAGE_DIRS.map((dirName) => {
+    const dir = resolve(root, dirName);
+    return {
+      dirName,
+      dir,
+      present: existsSync(resolve(dir, "package.json"))
+    };
+  });
+  const present = packages.filter((entry) => entry.present);
+  return {
+    mode: present.length === 0 ? "registry" : present.length === packages.length ? "workspace" : "partial",
+    packages,
+    missing: packages.filter((entry) => !entry.present)
+  };
+}
+function assertUsableTreeseedPackageCheckout(fallbackDirName) {
+  if (!fallbackDirName) {
+    return;
+  }
+  const state = treeseedWorkspacePackageCheckoutState();
+  const rootHasTreeseedSubmodules = existsSync(resolve(packageRoot, "..", "..", ".gitmodules"));
+  if (state.mode !== "partial" || !rootHasTreeseedSubmodules) {
+    return;
+  }
+  const missing = state.missing.map((entry) => `packages/${entry.dirName}`).join(", ");
+  throw new Error(
+    `Partial Treeseed package checkout detected. Missing package manifests: ${missing}. Run \`git submodule update --init --recursive\` to use workspace mode, or remove the partial checkout to use registry mode.`
+  );
+}
+function resolveTreeseedPackageRoot(packageName, exportPath, fallbackDirName) {
+  assertUsableTreeseedPackageCheckout(fallbackDirName);
+  if (fallbackDirName) {
+    const localRoot = resolve(packageRoot, "..", fallbackDirName);
+    if (existsSync(resolve(localRoot, "package.json"))) {
+      return localRoot;
+    }
+  }
+  try {
+    const resolvedEntry = require2.resolve(exportPath ?? packageName);
+    if ((exportPath ?? packageName).endsWith("/package.json")) {
+      return dirname(resolvedEntry);
+    }
+    return resolve(dirname(resolvedEntry), "..");
+  } catch {
+    if (!fallbackDirName) {
+      throw new Error(`Unable to resolve package root for "${packageName}".`);
+    }
+    return resolve(packageRoot, "..", fallbackDirName);
+  }
+}
+function resolveAstroBin() {
+  return resolvePackageBinary("astro", "astro");
+}
+function resolveWranglerBin() {
+  return resolvePackageBinary("wrangler", "wrangler");
+}
+const corePackageRoot = resolveTreeseedPackageRoot("@treeseed/core", "@treeseed/core/config", "core");
+const sdkPackageRoot = resolveTreeseedPackageRoot("@treeseed/sdk", "@treeseed/sdk", "sdk");
+const agentPackageRoot = resolveTreeseedPackageRoot("@treeseed/agent", "@treeseed/agent", "agent");
+function loadPackageJson(root = process.cwd()) {
+  const packageJsonPath = resolve(root, "package.json");
+  if (!existsSync(packageJsonPath)) {
+    return null;
+  }
+  return JSON.parse(readFileSync(packageJsonPath, "utf8"));
+}
+function isWorkspaceRoot(root = process.cwd()) {
+  const packageJson = loadPackageJson(root);
+  const workspaces = Array.isArray(packageJson?.workspaces) ? packageJson.workspaces : Array.isArray(packageJson?.workspaces?.packages) ? packageJson.workspaces.packages : [];
+  return workspaces.length > 0;
+}
+function createProductionBuildEnv(extraEnv = {}) {
+  return {
+    TREESEED_LOCAL_DEV_MODE: "cloudflare",
+    TREESEED_PUBLIC_FORMS_LOCAL_BYPASS_TURNSTILE: "",
+    TREESEED_FORMS_LOCAL_BYPASS_TURNSTILE: "",
+    TREESEED_FORMS_LOCAL_BYPASS_CLOUDFLARE_GUARDS: "",
+    TREESEED_PUBLIC_DEV_WATCH_RELOAD: "",
+    ...extraEnv
+  };
+}
+function packageScriptPath(scriptName) {
+  if (extname(scriptName)) {
+    return resolve(packageScriptRoot, scriptName);
+  }
+  for (const extension of [".js", ".ts", ".mjs"]) {
+    const candidate = resolve(packageScriptRoot, `${scriptName}${extension}`);
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  throw new Error(`Unable to resolve package script "${scriptName}".`);
+}
+function withProcessCwd(cwd, action) {
+  const previous = process.cwd();
+  if (previous === cwd) {
+    return action();
+  }
+  process.chdir(cwd);
+  try {
+    return action();
+  } finally {
+    process.chdir(previous);
+  }
+}
+function expectString(value, label) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`Invalid deploy config: expected ${label} to be a non-empty string.`);
+  }
+  return value.trim();
+}
+function optionalString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
+}
+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 parseFallbackDeployConfig(configPath) {
+  const parsed = parseYaml(readFileSync(configPath, "utf8")) ?? {};
+  const record = optionalRecord(parsed, "root") ?? {};
+  const cloudflare = optionalRecord(record.cloudflare, "cloudflare") ?? {};
+  const smtp = optionalRecord(record.smtp, "smtp") ?? {};
+  const turnstile = optionalRecord(record.turnstile, "turnstile") ?? {};
+  const agentProviders = optionalRecord(optionalRecord(record.providers, "providers")?.agents, "providers.agents") ?? {};
+  const contentProviders = optionalRecord(optionalRecord(record.providers, "providers")?.content, "providers.content") ?? {};
+  const deployConfig = {
+    name: expectString(record.name, "name"),
+    slug: expectString(record.slug, "slug"),
+    siteUrl: expectString(record.siteUrl, "siteUrl"),
+    contactEmail: expectString(record.contactEmail, "contactEmail"),
+    cloudflare: {
+      accountId: optionalCloudflareAccountId(cloudflare.accountId) ?? optionalCloudflareAccountId(process.env.CLOUDFLARE_ACCOUNT_ID) ?? CLOUDFLARE_ACCOUNT_ID_PLACEHOLDER,
+      workerName: optionalString(cloudflare.workerName),
+      gatewayWorkerName: optionalString(cloudflare.gatewayWorkerName),
+      queueName: optionalString(cloudflare.queueName),
+      dlqName: optionalString(cloudflare.dlqName),
+      d1Binding: optionalString(cloudflare.d1Binding),
+      queueBinding: optionalString(cloudflare.queueBinding)
+    },
+    plugins: parsePluginReferences(record.plugins),
+    providers: {
+      forms: expectString(record.providers?.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.providers?.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.providers?.site ?? TREESEED_DEFAULT_PROVIDER_SELECTIONS.site, "providers.site")
+    },
+    services: parseManagedServicesConfig(record.services),
+    smtp: {
+      enabled: optionalBoolean(smtp.enabled, "smtp.enabled")
+    },
+    turnstile: {
+      enabled: optionalBoolean(turnstile.enabled, "turnstile.enabled") ?? true
+    }
+  };
+  Object.defineProperty(deployConfig, "__tenantRoot", {
+    value: dirname(configPath),
+    enumerable: false
+  });
+  Object.defineProperty(deployConfig, "__configPath", {
+    value: configPath,
+    enumerable: false
+  });
+  return deployConfig;
+}
+function loadCliDeployConfig(tenantRoot) {
+  const configPath = resolve(tenantRoot, "treeseed.site.yaml");
+  if (!existsSync(configPath)) {
+    throw new Error(`Unable to resolve Treeseed deploy config at "${configPath}".`);
+  }
+  return parseFallbackDeployConfig(configPath);
+}
+function runNodeBinary(binPath, args, options = {}) {
+  const result = spawnSync(process.execPath, [binPath, ...args], {
+    stdio: options.stdio ?? "inherit",
+    cwd: options.cwd ?? process.cwd(),
+    env: { ...process.env, ...options.env ?? {} }
+  });
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
+function runNodeScript(scriptPath, args = [], options = {}) {
+  return runNodeBinary(scriptPath, args, options);
+}
+function spawnNodeBinary(binPath, args, options = {}) {
+  return spawn(process.execPath, [binPath, ...args], {
+    stdio: options.stdio ?? "inherit",
+    cwd: options.cwd ?? process.cwd(),
+    env: { ...process.env, ...options.env ?? {} },
+    detached: options.detached ?? false
+  });
+}
+export {
+  agentPackageRoot,
+  corePackageRoot,
+  createProductionBuildEnv,
+  isWorkspaceRoot,
+  loadCliDeployConfig,
+  loadPackageJson,
+  packageRoot,
+  packageScriptPath,
+  packageScriptRoot,
+  resolveAstroBin,
+  resolveWranglerBin,
+  runNodeBinary,
+  runNodeScript,
+  runtimeRoot,
+  sdkPackageRoot,
+  spawnNodeBinary,
+  treeseedWorkspacePackageCheckoutState,
+  withProcessCwd
+};

package/dist/operations/services/save-deploy-preflight.d.ts

@@ -0,0 +1,34 @@
+export declare function validateSaveAutomationPrerequisites({ cwd }: {
+    cwd: any;
+}): {
+    ok: boolean;
+    mode: string;
+    missingEnv: never[];
+    preflight: null;
+} | {
+    ok: boolean;
+    mode: string;
+    missingEnv: never[];
+    preflight: {
+        ok: boolean;
+        requireAuth: boolean;
+        missingCommands: string[];
+        failingAuth: string[];
+        checks: {
+            commands: {
+                [k: string]: {
+                    installed: boolean;
+                    path: string | null;
+                };
+            };
+            auth: {};
+        };
+    };
+};
+export declare function runWorkspaceSavePreflight({ cwd }: {
+    cwd: any;
+}): void;
+export declare function runTenantDeployPreflight({ cwd, scope }: {
+    cwd: any;
+    scope?: string | undefined;
+}): void;

package/dist/operations/services/save-deploy-preflight.js

@@ -0,0 +1,76 @@
+import { spawnSync } from "node:child_process";
+import { packageScriptPath } from "./runtime-tools.js";
+import { applyTreeseedEnvironmentToProcess, assertTreeseedCommandEnvironment } from "./config-runtime.js";
+import { collectCliPreflight } from "./workspace-preflight.js";
+import { getGitHubAutomationMode, requiredGitHubEnvironment } from "./github-automation.js";
+function runStep(label, scriptName, { cwd, env } = {}) {
+  const result = spawnSync(process.execPath, [packageScriptPath(scriptName)], {
+    cwd,
+    env: { ...process.env, ...env ?? {} },
+    stdio: "inherit"
+  });
+  if (result.status !== 0) {
+    const error = new Error(`${label} failed.`);
+    error.kind = `${label}_failed`;
+    error.exitCode = result.status ?? 1;
+    throw error;
+  }
+}
+function missingRequiredEnv(requiredKeys) {
+  return requiredKeys.filter((key) => {
+    const value = process.env[key];
+    return typeof value !== "string" || value.length === 0;
+  });
+}
+function validateSaveAutomationPrerequisites({ cwd }) {
+  applyTreeseedEnvironmentToProcess({ tenantRoot: cwd, scope: "prod", override: true });
+  assertTreeseedCommandEnvironment({ tenantRoot: cwd, scope: "prod", purpose: "save" });
+  if (getGitHubAutomationMode() !== "real") {
+    return {
+      ok: true,
+      mode: "stub",
+      missingEnv: [],
+      preflight: null
+    };
+  }
+  const preflight = collectCliPreflight({ cwd, requireAuth: true });
+  if (!preflight.ok) {
+    const error = new Error("Treeseed save prerequisites failed: required GitHub, Cloudflare, or Railway tokens are missing.");
+    error.kind = "auth_failed";
+    error.details = preflight;
+    throw error;
+  }
+  const required = requiredGitHubEnvironment(cwd, { scope: "prod", purpose: "save" });
+  const missingEnv = missingRequiredEnv([...required.secrets, ...required.variables]);
+  if (missingEnv.length > 0) {
+    const error = new Error(
+      `Treeseed save is missing required environment variables: ${missingEnv.join(", ")}.`
+    );
+    error.kind = "missing_required_env";
+    error.missingEnv = missingEnv;
+    throw error;
+  }
+  return {
+    ok: true,
+    mode: "real",
+    missingEnv: [],
+    preflight
+  };
+}
+function runWorkspaceSavePreflight({ cwd }) {
+  runStep("lint", "workspace-lint", { cwd });
+  runStep("test", "workspace-test", { cwd });
+  runStep("build", "tenant-build", { cwd });
+}
+function runTenantDeployPreflight({ cwd, scope = "prod" }) {
+  applyTreeseedEnvironmentToProcess({ tenantRoot: cwd, scope, override: true });
+  assertTreeseedCommandEnvironment({ tenantRoot: cwd, scope, purpose: "deploy" });
+  runStep("lint", "tenant-lint", { cwd });
+  runStep("test", "tenant-test", { cwd });
+  runStep("build", "tenant-build", { cwd });
+}
+export {
+  runTenantDeployPreflight,
+  runWorkspaceSavePreflight,
+  validateSaveAutomationPrerequisites
+};

package/dist/operations/services/template-registry.d.ts

@@ -0,0 +1,88 @@
+import { type SdkTemplateCatalogEntry } from '@treeseed/sdk';
+export declare const TEMPLATE_CATEGORIES: readonly ["starter", "example", "fixture", "reference-app"];
+export type TemplateCategory = (typeof TEMPLATE_CATEGORIES)[number];
+export interface TemplateVariableDefinition {
+    name: string;
+    token: string;
+    deriveFrom?: string;
+    required?: boolean;
+    default?: string;
+}
+export interface TemplateManifest {
+    schemaVersion?: number;
+    id: string;
+    displayName: string;
+    description: string;
+    category: TemplateCategory;
+    tags: string[];
+    templateVersion?: string;
+    templateApiVersion: number;
+    minCliVersion: string;
+    minCoreVersion?: string;
+    variables: TemplateVariableDefinition[];
+    actions?: string[];
+    postCreate?: string[];
+    managedSurface?: {
+        coreManaged?: string[];
+        validatedOnly?: string[];
+        tenantManaged?: string[];
+    };
+    testing: {
+        smokeCommand?: string;
+        buildCommand?: string;
+    };
+}
+export interface TemplateProductDefinition extends SdkTemplateCatalogEntry {
+    contentPath: string;
+    artifactRoot: string;
+    artifactManifestPath: string;
+    templateRoot: string;
+}
+export interface ResolvedTemplateDefinition {
+    product: TemplateProductDefinition;
+    manifestPath: string;
+    templateRoot: string;
+    manifest: TemplateManifest;
+}
+export interface StarterResolutionInput {
+    target: string;
+    name?: string | null;
+    slug?: string | null;
+    siteUrl?: string | null;
+    contactEmail?: string | null;
+    repositoryUrl?: string | null;
+    discordUrl?: string | null;
+}
+interface TemplateCatalogOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    writeWarning?: (message: string) => void;
+}
+export declare function listTemplateProducts(options?: TemplateCatalogOptions): Promise<TemplateProductDefinition[]>;
+export declare function resolveTemplateProduct(id: string, options?: TemplateCatalogOptions): Promise<TemplateProductDefinition>;
+export declare function resolveTemplateDefinition(id: string, options?: TemplateCatalogOptions, category?: TemplateCategory): Promise<ResolvedTemplateDefinition>;
+export declare function validateTemplateProduct(product: Pick<TemplateProductDefinition, 'id'>, options?: TemplateCatalogOptions): Promise<ResolvedTemplateDefinition>;
+export declare function validateAllTemplateDefinitions(options?: TemplateCatalogOptions): Promise<ResolvedTemplateDefinition[]>;
+export declare function buildTemplateReplacements(manifest: TemplateManifest, input: StarterResolutionInput): Record<string, string>;
+export declare function scaffoldTemplateProject(templateId: string, targetRoot: string, input: StarterResolutionInput, options?: TemplateCatalogOptions): Promise<TemplateProductDefinition>;
+export declare function syncTemplateProject(siteRoot: string, options?: TemplateCatalogOptions & {
+    check?: boolean;
+}): Promise<string[]>;
+export declare function serializeTemplateRegistryEntry(product: Pick<TemplateProductDefinition, 'id' | 'displayName' | 'description' | 'summary' | 'status' | 'featured' | 'category' | 'tags' | 'publisher' | 'templateVersion' | 'templateApiVersion' | 'minCliVersion' | 'minCoreVersion' | 'fulfillment'>): {
+    id: string;
+    displayName: string;
+    description: string;
+    summary: string;
+    status: import("../../sdk-types.ts").SdkTemplateCatalogStatus;
+    featured: boolean;
+    category: import("../../sdk-types.ts").SdkTemplateCategory;
+    tags: string[];
+    publisher: import("@treeseed/sdk").SdkTemplateCatalogPublisher;
+    templateVersion: string;
+    templateApiVersion: number;
+    minCliVersion: string;
+    minCoreVersion: string | undefined;
+    source: import("@treeseed/sdk").SdkTemplateCatalogSource;
+};
+export declare function exportTemplateCatalogYaml(options?: TemplateCatalogOptions): Promise<string>;
+export {};