@treeseed/sdk 0.10.24 → 0.10.26

package/dist/operations/services/template-secret-sync.js

@@ -0,0 +1,292 @@
+import {
+  syncTreeseedCloudflareEnvironment,
+  syncTreeseedGitHubEnvironment,
+  syncTreeseedRailwayEnvironment
+} from "./config-runtime.js";
+const PROVIDER_TARGETS = {
+  github: ["github-secret", "github-variable"],
+  cloudflare: ["cloudflare-secret", "cloudflare-var"],
+  railway: ["railway-secret", "railway-var"]
+};
+const DEFAULT_SCOPES = ["staging", "prod"];
+const NON_PROVIDER_TARGETS = /* @__PURE__ */ new Set(["local-runtime", "local-cloudflare", "config-file"]);
+const SECRET_TOKEN_PATTERN = /(?:gh[pousr]_[A-Za-z0-9_]{20,}|sk-[A-Za-z0-9_-]{16,}|[A-Za-z0-9+/=]{32,})/gu;
+class ProjectLaunchSecretSyncError extends Error {
+  result;
+  constructor(message, result) {
+    super(message);
+    this.name = "ProjectLaunchSecretSyncError";
+    this.result = result;
+  }
+}
+function stringValue(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : "";
+}
+function normalizeSecretTargets(targets) {
+  const allowed = new Set(Object.values(PROVIDER_TARGETS).flat());
+  return targets.map((target) => String(target ?? "").trim()).filter((target) => allowed.has(target));
+}
+function normalizeScopes(items, requested) {
+  const scopes = new Set(requested?.length ? requested : DEFAULT_SCOPES);
+  for (const item of items) {
+    for (const scope of item.scopes ?? []) {
+      if (scope === "staging" || scope === "prod") {
+        scopes.add(scope);
+      }
+    }
+  }
+  return [...scopes];
+}
+function valueCandidatesForSource(source) {
+  const value = String(source ?? "").trim();
+  if (!value) return [];
+  const [, suffix = ""] = /^(?:selectedHost|host)\.(?:secret|config|environment|env):(.+)$/u.exec(value) ?? [];
+  if (suffix) {
+    return [suffix, suffix.toUpperCase(), `TREESEED_${suffix.toUpperCase()}`];
+  }
+  const [, dotted = ""] = /^(?:selectedHost|host)\.([A-Za-z0-9_]+)$/u.exec(value) ?? [];
+  if (dotted) {
+    return [dotted, dotted.toUpperCase(), `TREESEED_${dotted.toUpperCase()}`];
+  }
+  return [];
+}
+function scopedOverlay(options, scope) {
+  return {
+    ...options.processEnv ?? process.env,
+    ...options.valuesOverlay ?? {},
+    ...options.valuesByScope?.[scope] ?? {}
+  };
+}
+function bindingValue(binding, key) {
+  if (!binding || !key) return "";
+  const record = binding;
+  for (const containerKey of ["environmentValues", "configValues", "secrets", "secretValues", "metadata"]) {
+    const container = record[containerKey];
+    if (container && typeof container === "object") {
+      const value = stringValue(container[key]) || stringValue(container[key.toUpperCase()]);
+      if (value) return value;
+    }
+  }
+  return stringValue(record[key]) || stringValue(record[key.toUpperCase()]);
+}
+function resolvePlanItemValue(item, scope, options) {
+  const values = scopedOverlay(options, scope);
+  const direct = stringValue(values[item.env]);
+  if (direct) return direct;
+  const binding = item.sourceHostId ? options.hostBindings?.[item.requirementKey] : void 0;
+  for (const candidate of valueCandidatesForSource(item.source)) {
+    const overlayValue = stringValue(values[candidate]);
+    if (overlayValue) return overlayValue;
+    const hostValue = bindingValue(binding, candidate);
+    if (hostValue) return hostValue;
+  }
+  return "";
+}
+function providerForTarget(target) {
+  if (target.startsWith("github-")) return "github";
+  if (target.startsWith("cloudflare-")) return "cloudflare";
+  return "railway";
+}
+function redactSecretSyncMessage(message) {
+  return String(message instanceof Error ? message.message : message ?? "Secret sync failed.").replace(SECRET_TOKEN_PATTERN, "[redacted]").replace(/(token|password|secret|key)=([^,\s]+)/giu, "$1=[redacted]");
+}
+function resolveProjectLaunchSecretValueOverlay(options) {
+  const planItems = options.secretDeploymentPlan?.items?.filter(Boolean) ?? [];
+  const scopes = normalizeScopes(planItems, options.scopes);
+  const valuesOverlay = {};
+  const resolvedItems = [];
+  const diagnostics = [];
+  for (const item of planItems) {
+    const targets = normalizeSecretTargets(item.targets ?? []);
+    const itemScopes = (item.scopes ?? []).filter((scope) => scope === "local" || scope === "staging" || scope === "prod");
+    if (targets.length === 0) {
+      if ((item.targets ?? []).every((target) => NON_PROVIDER_TARGETS.has(String(target)))) {
+        continue;
+      }
+      diagnostics.push({
+        code: "unsupported_target",
+        requirementKey: item.requirementKey,
+        requirementKind: item.requirementKind,
+        env: item.env,
+        source: item.source,
+        targets: item.targets ?? [],
+        scopes: itemScopes,
+        message: `Secret deployment target is not supported for ${item.env}.`
+      });
+      continue;
+    }
+    const activeScopes = itemScopes.filter((scope) => scopes.includes(scope));
+    let resolved = false;
+    for (const scope of activeScopes) {
+      const value = resolvePlanItemValue(item, scope, options);
+      if (value) {
+        valuesOverlay[item.env] = value;
+        resolved = true;
+        break;
+      }
+    }
+    if (!resolved) {
+      diagnostics.push({
+        code: "missing_value",
+        requirementKey: item.requirementKey,
+        requirementKind: item.requirementKind,
+        env: item.env,
+        source: item.source,
+        targets,
+        scopes: activeScopes,
+        message: `No launch secret value was available for ${item.env}.`
+      });
+    }
+    resolvedItems.push({
+      requirementKey: item.requirementKey,
+      requirementKind: item.requirementKind,
+      env: item.env,
+      source: item.source,
+      targets,
+      scopes: activeScopes,
+      sensitivity: item.sensitivity,
+      sourceHostId: item.sourceHostId ?? null,
+      resolved
+    });
+  }
+  return { valuesOverlay, items: resolvedItems, diagnostics };
+}
+function itemsForProviderScope(items, provider, scope) {
+  const targets = new Set(PROVIDER_TARGETS[provider]);
+  return items.filter((item) => item.resolved && item.scopes.includes(scope) && item.targets.some((target) => targets.has(target)));
+}
+function summaryItemsFor(items, provider, scope, status, error) {
+  const targets = new Set(PROVIDER_TARGETS[provider]);
+  return items.flatMap((item) => item.targets.filter((target) => targets.has(target)).map((target) => ({
+    provider,
+    scope,
+    target,
+    env: item.env,
+    requirementKey: item.requirementKey,
+    requirementKind: item.requirementKind,
+    sensitivity: item.sensitivity,
+    status,
+    ...error ? { error: { message: redactSecretSyncMessage(error) } } : {}
+  })));
+}
+async function syncProjectLaunchHostBindingSecrets(options) {
+  const planItems = options.secretDeploymentPlan?.items?.filter(Boolean) ?? [];
+  const scopes = normalizeScopes(planItems, options.scopes);
+  const providers = options.providers?.length ? options.providers : Object.keys(PROVIDER_TARGETS);
+  const overlay = resolveProjectLaunchSecretValueOverlay({ ...options, scopes });
+  const relevantDiagnostics = overlay.diagnostics.filter((diagnostic) => diagnostic.scopes.some((scope) => scopes.includes(scope)) && diagnostic.targets.some((target) => providers.includes(providerForTarget(target))));
+  const result = {
+    ok: relevantDiagnostics.length === 0,
+    items: [],
+    providers: [],
+    diagnostics: overlay.diagnostics
+  };
+  if (relevantDiagnostics.length > 0) {
+    for (const diagnostic of relevantDiagnostics) {
+      for (const target of normalizeSecretTargets(diagnostic.targets)) {
+        const provider = providerForTarget(target);
+        for (const scope of diagnostic.scopes.filter((entry) => scopes.includes(entry))) {
+          result.items.push({
+            provider,
+            scope,
+            target,
+            env: diagnostic.env,
+            requirementKey: diagnostic.requirementKey,
+            requirementKind: diagnostic.requirementKind,
+            sensitivity: "secret",
+            status: "failed",
+            error: { message: diagnostic.message }
+          });
+        }
+      }
+    }
+    throw new ProjectLaunchSecretSyncError("Host-bound secret sync could not resolve every required value.", result);
+  }
+  const adapters = {
+    github: options.adapters?.github ?? syncTreeseedGitHubEnvironment,
+    cloudflare: options.adapters?.cloudflare ?? syncTreeseedCloudflareEnvironment,
+    railway: options.adapters?.railway ?? syncTreeseedRailwayEnvironment
+  };
+  for (const provider of providers) {
+    for (const scope of scopes) {
+      if (scope === "local") continue;
+      const scopedItems = itemsForProviderScope(overlay.items, provider, scope);
+      if (scopedItems.length === 0) continue;
+      const entryIds = [...new Set(scopedItems.map((item) => item.env))];
+      await options.onProgress?.({
+        provider,
+        scope,
+        entryIds,
+        status: "running",
+        message: `Syncing ${entryIds.length} host-bound ${provider} entr${entryIds.length === 1 ? "y" : "ies"} for ${scope}.`
+      });
+      try {
+        const valuesOverlay = {
+          ...overlay.valuesOverlay,
+          ...options.valuesByScope?.[scope] ?? {}
+        };
+        if (provider === "github") {
+          await adapters.github({
+            tenantRoot: options.projectRoot,
+            scope,
+            dryRun: options.dryRun,
+            repository: options.repository ?? null,
+            valuesOverlay,
+            entryIds,
+            execution: "sequential"
+          });
+        } else if (provider === "cloudflare") {
+          adapters.cloudflare({
+            tenantRoot: options.projectRoot,
+            scope,
+            dryRun: options.dryRun,
+            valuesOverlay,
+            entryIds
+          });
+        } else {
+          adapters.railway({
+            tenantRoot: options.projectRoot,
+            scope,
+            dryRun: options.dryRun,
+            valuesOverlay,
+            entryIds
+          });
+        }
+        result.items.push(...summaryItemsFor(scopedItems, provider, scope, "synced"));
+        result.providers.push({ provider, scope, entryIds, status: "completed" });
+        await options.onProgress?.({
+          provider,
+          scope,
+          entryIds,
+          status: "completed",
+          message: `Synced host-bound ${provider} entries for ${scope}.`
+        });
+      } catch (error) {
+        result.ok = false;
+        result.items.push(...summaryItemsFor(scopedItems, provider, scope, "failed", error));
+        result.providers.push({
+          provider,
+          scope,
+          entryIds,
+          status: "failed",
+          error: { message: redactSecretSyncMessage(error) }
+        });
+        await options.onProgress?.({
+          provider,
+          scope,
+          entryIds,
+          status: "failed",
+          message: redactSecretSyncMessage(error)
+        });
+        throw new ProjectLaunchSecretSyncError(redactSecretSyncMessage(error), result);
+      }
+    }
+  }
+  result.ok = result.providers.every((provider) => provider.status === "completed") && result.diagnostics.length === 0;
+  return result;
+}
+export {
+  ProjectLaunchSecretSyncError,
+  resolveProjectLaunchSecretValueOverlay,
+  syncProjectLaunchHostBindingSecrets
+};

package/dist/platform/environment.d.ts

@@ -86,6 +86,9 @@ export type TreeseedEnvironmentEntry = {
     localDefaultValue?: TreeseedEnvironmentValueResolver;
     isRelevant?: (context: TreeseedEnvironmentContext, scope: TreeseedEnvironmentScope, purpose?: TreeseedEnvironmentPurpose) => boolean;
     requiredWhen?: (context: TreeseedEnvironmentContext, scope: TreeseedEnvironmentScope, purpose?: TreeseedEnvironmentPurpose) => boolean;
+    sourceRequirement?: string;
+    sourceHostType?: string | null;
+    sourceProvider?: string | null;
 };
 export type TreeseedEnvironmentEntryYaml = Omit<TreeseedEnvironmentEntry, 'id' | 'defaultValue' | 'localDefaultValue' | 'isRelevant' | 'requiredWhen'> & {
     cluster?: string;

package/dist/project-workflow.d.ts

@@ -1,4 +1,4 @@
-import type { ProjectConnection, RemoteJobStatus } from './sdk-types.ts';
+import type { ProjectConnection, ProjectLaunchHostBindingInput, RemoteJobStatus } from './sdk-types.ts';
 export declare const PROJECT_TEAM_CAPABILITIES: readonly ["launch_projects", "edit_direct", "manage_workstreams", "stage_releases", "publish_releases", "publish_market_listings", "manage_products", "manage_billing", "approve_remote_execution"];
 export declare const PROJECT_JOB_STATUSES: readonly ["queued", "running", "waiting_for_approval", "failed", "completed", "rolled_back", "cancelled"];
 export declare const WORKSTREAM_STATES: readonly ["drafting", "active_local", "verifying", "saved_remote", "in_staging", "archived"];
@@ -201,9 +201,15 @@ export interface LaunchProjectRequest {
     sourceKind: 'blank' | 'template' | 'knowledge_pack';
     sourceRef?: string | null;
     hostingMode: 'managed' | 'hybrid' | 'self_hosted';
+    repositoryHostId?: string | null;
+    repositoryHostConfig?: Record<string, unknown> | null;
     cloudflareHostId?: string | null;
     cloudflareHostMode?: 'team_owned' | 'treeseed_managed' | null;
     cloudflareHostConfig?: Record<string, unknown> | null;
+    emailHostId?: string | null;
+    emailHostMode?: 'team_owned' | 'treeseed_managed' | null;
+    emailHostConfig?: Record<string, unknown> | null;
+    hostBindings?: Record<string, ProjectLaunchHostBindingInput>;
     targetEnvironments?: Array<'local' | 'staging' | 'prod'>;
     publicSite?: boolean;
     repoProvider?: 'github';

package/dist/scripts/scaffold-site.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 import { resolve } from 'node:path';
 import { scaffoldTemplateProject } from '../operations/services/template-registry.js';
+import { TREESEED_DEFAULT_STARTER_TEMPLATE_ID } from '../sdk-types.js';
 function parseArgs(argv) {
     const args = {
         target: null,
-        template: 'starter-basic',
+        template: TREESEED_DEFAULT_STARTER_TEMPLATE_ID,
         name: null,
         slug: null,
         siteUrl: null,
@@ -59,7 +60,7 @@ console.log(`Created Treeseed tenant from ${definition.id} at ${targetRoot}`);
 console.log('Next steps:');
 console.log(`  cd ${options.target}`);
 console.log('  npm install');
-console.log('  treeseed template show starter-basic');
+console.log(`  treeseed template show ${options.template}`);
 console.log('  treeseed sync --check');
 console.log('  treeseed config --environment local');
 console.log('  treeseed dev');

package/dist/scripts/test-scaffold.js

@@ -5,6 +5,7 @@ import { dirname, join, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { corePackageRoot, packageRoot, packageScriptPath, sdkPackageRoot } from '../operations/services/runtime-tools.js';
 import { listTemplateProducts, validateTemplateProduct } from '../operations/services/template-registry.js';
+import { TREESEED_DEFAULT_STARTER_TEMPLATE_ID } from '../sdk-types.js';
 const npmCacheDir = process.env.TREESEED_SCAFFOLD_NPM_CACHE_DIR
     ? resolve(process.env.TREESEED_SCAFFOLD_NPM_CACHE_DIR)
     : resolve(tmpdir(), 'treeseed-npm-cache');
@@ -204,7 +205,7 @@ async function scaffoldSite(siteRoot) {
     for (const definition of await listTemplateProducts({ writeWarning: (message) => console.warn(message) })) {
         await validateTemplateProduct(definition, { writeWarning: (message) => console.warn(message) });
     }
-    runStep(process.execPath, [packageScriptPath('scaffold-site'), siteRoot, '--template', 'starter-basic', '--name', 'Smoke Site', '--site-url', 'https://smoke.example.com', '--contact-email', 'hello@example.com']);
+    runStep(process.execPath, [packageScriptPath('scaffold-site'), siteRoot, '--template', TREESEED_DEFAULT_STARTER_TEMPLATE_ID, '--name', 'Smoke Site', '--site-url', 'https://smoke.example.com', '--contact-email', 'hello@example.com']);
 }
 function installScaffold(siteRoot, { coreTarballPath, sdkTarballPath, cliTarballPath }) {
     if (coreTarballPath && sdkTarballPath && cliTarballPath) {

package/dist/sdk-types.d.ts

@@ -21,6 +21,16 @@ export declare const PROJECT_DEPLOYMENT_STATUSES: readonly ["pending", "queued",
 export declare const PROJECT_INFRA_RESOURCE_PROVIDERS: readonly ["cloudflare", "railway", "github", "market"];
 export declare const PROJECT_INFRA_RESOURCE_KINDS: readonly ["pages", "worker", "kv", "turnstile-widget", "r2", "d1", "queue", "dlq", "railway_project", "railway_service", "railway_schedule"];
 export declare const AGENT_POOL_STATUSES: readonly ["pending", "active", "degraded", "offline"];
+export declare const TREESEED_DEFAULT_STARTER_TEMPLATE_ID: "starter-research";
+export declare const TEMPLATE_HOST_REQUIREMENT_TYPES: readonly ["repository", "web", "email", "ai"];
+export declare const TEMPLATE_RESOURCE_REQUIREMENT_TYPES: readonly ["service", "database", "object-storage", "queue", "dns-zone"];
+export declare const TEMPLATE_SECRET_SENSITIVITIES: readonly ["secret", "plain", "derived"];
+export declare const TEMPLATE_SECRET_TARGETS: readonly ["github-secret", "github-variable", "cloudflare-secret", "cloudflare-var", "railway-secret", "railway-var", "config-file", "local-runtime"];
+export declare const TEMPLATE_SECRET_SOURCES: readonly ["generated", "selected-host", "user-input", "derived"];
+export declare const TEMPLATE_CONFIG_WRITE_TARGETS: readonly ["treeseed.site.yaml", "src/env.yaml", "src/manifest.yaml", "package.json"];
+export declare const TEMPLATE_CONFIG_WRITE_WHEN: readonly ["always", "host-selected", "feature-enabled"];
+export declare const TEMPLATE_CONFIG_MERGE_STRATEGIES: readonly ["replace", "deep-merge", "append-unique"];
+export declare const PROJECT_LAUNCH_REQUIREMENT_KINDS: readonly ["host", "resource", "secret"];
 export type SdkBuiltinModelName = (typeof SDK_MODEL_NAMES)[number];
 export type SdkModelName = SdkBuiltinModelName | (string & {});
 export type SdkOperation = (typeof SDK_OPERATIONS)[number];
@@ -49,6 +59,82 @@ export type ProjectInfrastructureResourceProvider = (typeof PROJECT_INFRA_RESOUR
 export type ProjectInfrastructureResourceKind = (typeof PROJECT_INFRA_RESOURCE_KINDS)[number];
 export type AgentPoolStatus = (typeof AGENT_POOL_STATUSES)[number];
 export type RemoteJobRequestedByType = 'user' | 'team_api_key' | 'service' | 'runner' | 'system';
+export type TemplateHostRequirementType = (typeof TEMPLATE_HOST_REQUIREMENT_TYPES)[number];
+export type TemplateResourceRequirementType = (typeof TEMPLATE_RESOURCE_REQUIREMENT_TYPES)[number];
+export type TemplateSecretSensitivity = (typeof TEMPLATE_SECRET_SENSITIVITIES)[number];
+export type TemplateSecretTarget = (typeof TEMPLATE_SECRET_TARGETS)[number];
+export type TemplateSecretSource = (typeof TEMPLATE_SECRET_SOURCES)[number];
+export type TemplateConfigWriteTarget = (typeof TEMPLATE_CONFIG_WRITE_TARGETS)[number];
+export type TemplateConfigWriteWhen = (typeof TEMPLATE_CONFIG_WRITE_WHEN)[number];
+export type TemplateConfigMergeStrategy = (typeof TEMPLATE_CONFIG_MERGE_STRATEGIES)[number];
+export type ProjectLaunchRequirementKind = (typeof PROJECT_LAUNCH_REQUIREMENT_KINDS)[number];
+export interface TemplateConfigWrite {
+    target: TemplateConfigWriteTarget;
+    path: string;
+    valueFrom: string;
+    writeWhen?: TemplateConfigWriteWhen;
+    mergeStrategy?: TemplateConfigMergeStrategy;
+}
+export interface TemplateEnvironmentWrite {
+    env: string;
+    valueFrom: string;
+    targets?: TemplateSecretTarget[];
+    scopes?: ProjectEnvironmentName[];
+    sensitivity?: TemplateSecretSensitivity;
+}
+export interface TemplateHostRequirement {
+    kind: 'host';
+    key: string;
+    type: TemplateHostRequirementType;
+    required: boolean;
+    compatibleProviders?: string[];
+    displayName: string;
+    purpose: string;
+    defaultSelection?: 'team-default' | 'managed' | 'none';
+    configWrites: TemplateConfigWrite[];
+    environmentWrites?: TemplateEnvironmentWrite[];
+}
+export interface TemplateResourceRequirement {
+    kind: 'resource';
+    key: string;
+    type: TemplateResourceRequirementType;
+    required: boolean;
+    compatibleProviders?: string[];
+    displayName: string;
+    purpose: string;
+    configWrites: TemplateConfigWrite[];
+    environmentWrites?: TemplateEnvironmentWrite[];
+}
+export interface TemplateSecretRequirement {
+    kind: 'secret';
+    key: string;
+    env: string;
+    required: boolean;
+    sensitivity: TemplateSecretSensitivity;
+    targets: TemplateSecretTarget[];
+    source: TemplateSecretSource;
+}
+export interface TemplateLaunchRequirements {
+    version?: number;
+    hosts?: TemplateHostRequirement[];
+    resources?: TemplateResourceRequirement[];
+    secrets?: TemplateSecretRequirement[];
+}
+export interface ProjectLaunchHostBindingInput {
+    requirementKey: string;
+    requirementKind: ProjectLaunchRequirementKind;
+    type: string;
+    provider: string;
+    hostId?: string | null;
+    managedHostKey?: string | null;
+    mode?: string | null;
+    displayName?: string;
+    environmentScopes?: ProjectEnvironmentName[];
+    configValues?: Record<string, unknown>;
+    environmentValues?: Record<string, string>;
+    secretRefs?: Record<string, string>;
+    selectedBy?: 'user' | 'team-default' | 'managed-default' | 'template-default';
+}
 export declare function projectConnectionModeFromHosting(kind: TreeseedHostingKind, registration?: TreeseedHostingRegistration): ProjectConnectionMode;
 export interface SdkDispatchCapability {
     namespace: SdkDispatchNamespace;
@@ -2536,6 +2622,7 @@ export interface SdkTemplateCatalogEntry {
     relatedBooks?: string[];
     relatedKnowledge?: string[];
     relatedObjectives?: string[];
+    launchRequirements?: TemplateLaunchRequirements;
 }
 export interface SdkTemplateCatalogResponse {
     items: SdkTemplateCatalogEntry[];

package/dist/sdk-types.js

@@ -59,6 +59,25 @@ const PROJECT_INFRA_RESOURCE_KINDS = [
   "railway_schedule"
 ];
 const AGENT_POOL_STATUSES = ["pending", "active", "degraded", "offline"];
+const TREESEED_DEFAULT_STARTER_TEMPLATE_ID = "starter-research";
+const TEMPLATE_HOST_REQUIREMENT_TYPES = ["repository", "web", "email", "ai"];
+const TEMPLATE_RESOURCE_REQUIREMENT_TYPES = ["service", "database", "object-storage", "queue", "dns-zone"];
+const TEMPLATE_SECRET_SENSITIVITIES = ["secret", "plain", "derived"];
+const TEMPLATE_SECRET_TARGETS = [
+  "github-secret",
+  "github-variable",
+  "cloudflare-secret",
+  "cloudflare-var",
+  "railway-secret",
+  "railway-var",
+  "config-file",
+  "local-runtime"
+];
+const TEMPLATE_SECRET_SOURCES = ["generated", "selected-host", "user-input", "derived"];
+const TEMPLATE_CONFIG_WRITE_TARGETS = ["treeseed.site.yaml", "src/env.yaml", "src/manifest.yaml", "package.json"];
+const TEMPLATE_CONFIG_WRITE_WHEN = ["always", "host-selected", "feature-enabled"];
+const TEMPLATE_CONFIG_MERGE_STRATEGIES = ["replace", "deep-merge", "append-unique"];
+const PROJECT_LAUNCH_REQUIREMENT_KINDS = ["host", "resource", "secret"];
 function projectConnectionModeFromHosting(kind, registration = "none") {
   if (kind === "hosted_project") {
     return "hosted";
@@ -78,6 +97,7 @@ export {
   PROJECT_EXECUTION_OWNERS,
   PROJECT_INFRA_RESOURCE_KINDS,
   PROJECT_INFRA_RESOURCE_PROVIDERS,
+  PROJECT_LAUNCH_REQUIREMENT_KINDS,
   PROJECT_RUNNER_REGISTRATION_STATES,
   PROJECT_WEB_DEPLOYMENT_ACTIONS,
   REMOTE_JOB_STATUSES,
@@ -89,6 +109,15 @@ export {
   SDK_OPERATIONS,
   SDK_PICK_STRATEGIES,
   SDK_STORAGE_BACKENDS,
+  TEMPLATE_CONFIG_MERGE_STRATEGIES,
+  TEMPLATE_CONFIG_WRITE_TARGETS,
+  TEMPLATE_CONFIG_WRITE_WHEN,
+  TEMPLATE_HOST_REQUIREMENT_TYPES,
+  TEMPLATE_RESOURCE_REQUIREMENT_TYPES,
+  TEMPLATE_SECRET_SENSITIVITIES,
+  TEMPLATE_SECRET_SOURCES,
+  TEMPLATE_SECRET_TARGETS,
+  TREESEED_DEFAULT_STARTER_TEMPLATE_ID,
   TREESEED_HOSTING_KINDS,
   TREESEED_HOSTING_REGISTRATIONS,
   projectConnectionModeFromHosting

package/dist/template-catalog.js

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { normalizeTemplateLaunchRequirements } from "./template-launch-requirements.js";
 function expectRecord(value, label) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw new Error(`Invalid template catalog response: expected ${label} to be an object.`);
@@ -91,7 +92,8 @@ function normalizeTemplateCatalogEntry(value) {
     } : void 0,
     relatedBooks: optionalStringArray(record.relatedBooks, "relatedBooks") ?? [],
     relatedKnowledge: optionalStringArray(record.relatedKnowledge, "relatedKnowledge") ?? [],
-    relatedObjectives: optionalStringArray(record.relatedObjectives, "relatedObjectives") ?? []
+    relatedObjectives: optionalStringArray(record.relatedObjectives, "relatedObjectives") ?? [],
+    launchRequirements: normalizeTemplateLaunchRequirements(record.launchRequirements, "launchRequirements")
   };
 }
 function parseTemplateCatalogResponse(payload) {

package/dist/template-launch-requirements.d.ts

@@ -0,0 +1,118 @@
+import { type ProjectEnvironmentName, type ProjectLaunchHostBindingInput, type ProjectLaunchRequirementKind, type TemplateConfigWrite, type TemplateLaunchRequirements } from './sdk-types.ts';
+type Mutable<T> = {
+    -readonly [P in keyof T]: T[P];
+};
+export type { TemplateLaunchRequirements } from './sdk-types.ts';
+export interface ProjectLaunchHostInventoryRecord {
+    id: string;
+    type?: string | null;
+    provider: string;
+    ownership?: string | null;
+    name?: string | null;
+    accountLabel?: string | null;
+    organizationOrOwner?: string | null;
+    allowedEnvironments?: ProjectEnvironmentName[];
+    status?: string | null;
+    metadata?: Record<string, unknown>;
+}
+export interface ProjectLaunchResolvedHostBinding {
+    requirementKey: string;
+    requirementKind: ProjectLaunchRequirementKind;
+    type: string;
+    provider: string;
+    hostId?: string | null;
+    managedHostKey?: string | null;
+    displayName: string;
+    environmentScopes: ProjectEnvironmentName[];
+    configValues: Record<string, unknown>;
+    environmentValues: Record<string, string>;
+    secretRefs: Record<string, string>;
+    provenance: {
+        selectedBy: NonNullable<ProjectLaunchHostBindingInput['selectedBy']>;
+        selectedAt: string;
+    };
+    host: {
+        id: string;
+        name: string | null;
+        ownership: string | null;
+        status: string | null;
+        accountLabel?: string | null;
+        organizationOrOwner?: string | null;
+        metadata?: Record<string, unknown>;
+    } | null;
+}
+export interface ProjectLaunchConfigWritePlanItem extends TemplateConfigWrite {
+    requirementKey: string;
+    requirementKind: ProjectLaunchRequirementKind;
+    requirementType: string;
+    provider: string;
+}
+export interface ProjectLaunchSecretDeploymentPlanItem {
+    requirementKey: string;
+    requirementKind: ProjectLaunchRequirementKind;
+    env: string;
+    sensitivity: string;
+    source: string;
+    targets: string[];
+    scopes: ProjectEnvironmentName[];
+    sourceHostId?: string | null;
+}
+export interface ResolveProjectLaunchHostBindingsOptions {
+    hostBindings?: Record<string, ProjectLaunchHostBindingInput>;
+    launchRequirements?: TemplateLaunchRequirements | null;
+    repositoryHosts?: ProjectLaunchHostInventoryRecord[];
+    teamHosts?: ProjectLaunchHostInventoryRecord[];
+    managedHosts?: ProjectLaunchHostInventoryRecord[];
+    defaultHosts?: Record<string, unknown> | null;
+    domains?: Record<string, unknown> | null;
+    projectSlug?: string | null;
+    projectName?: string | null;
+    standardProjectLaunch?: boolean;
+    selectedAt?: string;
+}
+export interface ResolveProjectLaunchHostBindingsResult {
+    hostBindings: Record<string, ProjectLaunchResolvedHostBinding>;
+    compatibility: {
+        repositoryHostId?: string | null;
+        cloudflareHostMode?: 'team_owned' | 'treeseed_managed' | null;
+        cloudflareHostId?: string | null;
+        emailHostMode?: 'team_owned' | 'treeseed_managed' | null;
+        emailHostId?: string | null;
+    };
+    configWritePlan: ProjectLaunchConfigWritePlanItem[];
+    secretDeploymentPlan: {
+        items: ProjectLaunchSecretDeploymentPlanItem[];
+    };
+    diagnostics: Array<{
+        code: string;
+        message: string;
+        requirementKey?: string;
+    }>;
+}
+export interface ProjectLaunchLocalHostBindingSummary {
+    requirementKey: string;
+    requirementKind: ProjectLaunchRequirementKind;
+    type: string;
+    provider: string | null;
+    alias: string | null;
+    mode: 'team_owned' | 'treeseed_managed' | 'none';
+    displayName: string;
+}
+export interface ParseProjectLaunchHostBindingSpecsOptions {
+    specs?: string | string[] | null;
+    launchRequirements?: TemplateLaunchRequirements | null;
+    selectedAt?: string;
+}
+export interface ParseProjectLaunchHostBindingSpecsResult {
+    hostBindings: Record<string, ProjectLaunchHostBindingInput>;
+    repositoryHosts: ProjectLaunchHostInventoryRecord[];
+    teamHosts: ProjectLaunchHostInventoryRecord[];
+    managedHosts: ProjectLaunchHostInventoryRecord[];
+    summaries: ProjectLaunchLocalHostBindingSummary[];
+    omitted: ProjectLaunchLocalHostBindingSummary[];
+}
+export declare function normalizeTemplateLaunchRequirements(value: unknown, label?: string): TemplateLaunchRequirements | undefined;
+export declare function validateTemplateLaunchRequirements(value: unknown, label?: string): void;
+export declare function normalizeProjectLaunchHostBindings(input: unknown): Mutable<Record<string, ProjectLaunchHostBindingInput>>;
+export declare function parseProjectLaunchHostBindingSpecs(options: ParseProjectLaunchHostBindingSpecsOptions): ParseProjectLaunchHostBindingSpecsResult;
+export declare function resolveProjectLaunchHostBindings(options: ResolveProjectLaunchHostBindingsOptions): ResolveProjectLaunchHostBindingsResult;