@treeseed/sdk 0.10.24 → 0.10.25

package/dist/operations/services/template-host-bindings.js

@@ -0,0 +1,400 @@
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import {
+  TEMPLATE_CONFIG_MERGE_STRATEGIES,
+  TEMPLATE_CONFIG_WRITE_TARGETS
+} from "../../sdk-types.js";
+function ensureDir(path) {
+  mkdirSync(path, { recursive: true });
+}
+function readStructuredFile(filePath, target) {
+  if (!existsSync(filePath)) {
+    return target === "src/env.yaml" ? { entries: {} } : {};
+  }
+  const raw = readFileSync(filePath, "utf8");
+  if (!raw.trim()) {
+    return target === "src/env.yaml" ? { entries: {} } : {};
+  }
+  const parsed = target === "package.json" ? JSON.parse(raw) : parseYaml(raw);
+  return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+}
+function writeStructuredFile(filePath, target, value) {
+  ensureDir(dirname(filePath));
+  const body = target === "package.json" ? `${JSON.stringify(value, null, 2)}
+` : stringifyYaml(value);
+  writeFileSync(filePath, body, "utf8");
+}
+function parseStructuredContent(content, target) {
+  if (!content.trim()) {
+    return target === "src/env.yaml" ? { entries: {} } : {};
+  }
+  const parsed = target === "package.json" ? JSON.parse(content) : parseYaml(content);
+  return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+}
+function stringifyStructuredContent(value, target) {
+  return target === "package.json" ? `${JSON.stringify(value, null, 2)}
+` : stringifyYaml(value);
+}
+function assertTarget(target) {
+  if (!TEMPLATE_CONFIG_WRITE_TARGETS.includes(target)) {
+    throw new Error(`Unsupported host binding config write target "${target}".`);
+  }
+}
+function safePathSegments(path) {
+  const segments = path.split(".");
+  if (segments.some((segment) => !segment || segment === "..")) {
+    throw new Error(`Host binding config write path "${path}" must be a safe dot path.`);
+  }
+  for (const segment of segments) {
+    if (!/^[A-Za-z0-9_-]+$/u.test(segment)) {
+      throw new Error(`Host binding config write path "${path}" contains unsafe segment "${segment}".`);
+    }
+    if (segment === "__proto__" || segment === "prototype" || segment === "constructor") {
+      throw new Error(`Host binding config write path "${path}" contains forbidden segment "${segment}".`);
+    }
+  }
+  return segments;
+}
+function getPath(value, path) {
+  let current = value;
+  for (const segment of path.split(".")) {
+    if (!current || typeof current !== "object" || Array.isArray(current)) return void 0;
+    current = current[segment];
+  }
+  return current;
+}
+function hasPath(value, path) {
+  let current = value;
+  for (const segment of path.split(".")) {
+    if (!current || typeof current !== "object" || Array.isArray(current) || !(segment in current)) return false;
+    current = current[segment];
+  }
+  return true;
+}
+function deepMerge(left, right) {
+  if (left && typeof left === "object" && !Array.isArray(left) && right && typeof right === "object" && !Array.isArray(right)) {
+    const result = { ...left };
+    for (const [key, value] of Object.entries(right)) {
+      result[key] = key in result ? deepMerge(result[key], value) : value;
+    }
+    return result;
+  }
+  return right;
+}
+function uniqueArray(left, right) {
+  const current = Array.isArray(left) ? left : [];
+  const incoming = Array.isArray(right) ? right : [right];
+  return [.../* @__PURE__ */ new Set([...current, ...incoming])];
+}
+function setDotPath(target, path, value, strategy) {
+  const segments = safePathSegments(path);
+  let current = target;
+  for (const segment of segments.slice(0, -1)) {
+    if (!current[segment] || typeof current[segment] !== "object" || Array.isArray(current[segment])) {
+      current[segment] = {};
+    }
+    current = current[segment];
+  }
+  const leaf = segments[segments.length - 1];
+  if (strategy === "replace") {
+    current[leaf] = value;
+    return;
+  }
+  if (strategy === "deep-merge") {
+    current[leaf] = deepMerge(current[leaf], value);
+    return;
+  }
+  if (strategy === "append-unique") {
+    current[leaf] = uniqueArray(current[leaf], value);
+    return;
+  }
+  throw new Error(`Unsupported host binding config merge strategy "${strategy}".`);
+}
+function selectedHostValue(binding, selector) {
+  if (selector === "provider") return binding.provider;
+  if (selector === "type") return binding.type;
+  if (selector === "id") return binding.host?.id ?? binding.hostId ?? binding.managedHostKey ?? null;
+  if (selector === "hostId") return binding.hostId ?? binding.host?.id ?? null;
+  if (selector === "managedHostKey") return binding.managedHostKey ?? null;
+  if (selector === "name") return binding.host?.name ?? binding.displayName ?? null;
+  if (selector === "displayName") return binding.displayName;
+  if (selector === "ownership") return binding.host?.ownership ?? null;
+  if (selector === "status") return binding.host?.status ?? null;
+  if (selector === "accountLabel") return binding.host?.accountLabel ?? null;
+  if (selector === "organizationOrOwner") return binding.host?.organizationOrOwner ?? null;
+  if (selector.startsWith("github.")) {
+    const field = selector.slice("github.".length);
+    if (field === "owner") {
+      return binding.host?.organizationOrOwner ?? getPath(binding.configValues, "github.owner") ?? getPath(binding.configValues, "owner") ?? null;
+    }
+    return getPath(binding.configValues, `github.${field}`) ?? null;
+  }
+  if (selector.startsWith("metadata.")) return getPath(binding.host?.metadata, selector.slice("metadata.".length)) ?? null;
+  if (selector.startsWith("configValues.")) return getPath(binding.configValues, selector.slice("configValues.".length)) ?? null;
+  if (selector.startsWith("environmentValues.")) return getPath(binding.environmentValues, selector.slice("environmentValues.".length)) ?? null;
+  if (selector.startsWith("secretRefs.")) return getPath(binding.secretRefs, selector.slice("secretRefs.".length)) ?? null;
+  throw new Error(`Unsupported selectedHost value source "${selector}".`);
+}
+function selectedResourceValue(binding, selector) {
+  if (selector === "provider") return binding.provider;
+  if (selector === "type") return binding.type;
+  if (selector === "id") return binding.host?.id ?? binding.hostId ?? binding.managedHostKey ?? null;
+  if (selector === "resourceId") return binding.hostId ?? binding.host?.id ?? null;
+  if (selector === "managedResourceKey") return binding.managedHostKey ?? null;
+  if (selector === "name") return binding.displayName ?? binding.host?.name ?? null;
+  if (selector === "displayName") return binding.displayName;
+  if (selector.startsWith("metadata.")) return getPath(binding.host?.metadata, selector.slice("metadata.".length)) ?? null;
+  if (selector.startsWith("configValues.")) return getPath(binding.configValues, selector.slice("configValues.".length)) ?? null;
+  if (selector.startsWith("environmentValues.")) return getPath(binding.environmentValues, selector.slice("environmentValues.".length)) ?? null;
+  if (selector.startsWith("secretRefs.")) return getPath(binding.secretRefs, selector.slice("secretRefs.".length)) ?? null;
+  throw new Error(`Unsupported selectedResource value source "${selector}".`);
+}
+function resolveWriteValue(write, binding, options) {
+  const valueFrom = write.valueFrom;
+  if (valueFrom.startsWith("selectedHost.")) {
+    if (!binding) return void 0;
+    return selectedHostValue(binding, valueFrom.slice("selectedHost.".length));
+  }
+  if (valueFrom.startsWith("selectedResource.")) {
+    if (!binding) return void 0;
+    return selectedResourceValue(binding, valueFrom.slice("selectedResource.".length));
+  }
+  if (valueFrom.startsWith("launchInput.domains.")) {
+    return getPath(options.launchInput?.domains, valueFrom.slice("launchInput.domains.".length));
+  }
+  if (valueFrom === "derived.projectSlug") {
+    return options.derived?.projectSlug ?? options.launchInput?.projectSlug ?? null;
+  }
+  if (valueFrom === "derived.projectName") {
+    return options.derived?.projectName ?? options.launchInput?.projectName ?? null;
+  }
+  if (valueFrom === "derived.repositoryName") {
+    return options.derived?.repositoryName ?? options.launchInput?.repoName ?? options.launchInput?.projectSlug ?? null;
+  }
+  if (valueFrom.startsWith("literal.")) {
+    const literal = valueFrom.slice("literal.".length);
+    if (literal === "true") return true;
+    if (literal === "false") return false;
+    if (literal === "null") return null;
+    return literal;
+  }
+  throw new Error(`Unsupported host binding config value source "${valueFrom}".`);
+}
+function shouldWrite(write, binding, value) {
+  if (write.writeWhen === "host-selected") {
+    return Boolean(binding?.host || binding?.hostId || binding?.managedHostKey) && value !== void 0 && value !== null && value !== "";
+  }
+  if (write.writeWhen === "feature-enabled") {
+    return value !== void 0 && value !== null && value !== false && value !== "";
+  }
+  return value !== void 0 && value !== null;
+}
+function summarizeValue(value) {
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
+  if (value === null || value === void 0) return null;
+  if (Array.isArray(value)) return `[${value.length} items]`;
+  return "{...}";
+}
+function normalizeTargets(targets) {
+  return targets.filter((target) => typeof target === "string" && target.length > 0);
+}
+function buildEnvironmentEntry(item, binding) {
+  const sourceHostType = binding?.type ?? (item.requirementKind === "host" ? item.requirementKey : null);
+  const sourceProvider = binding?.provider ?? null;
+  return {
+    label: item.env.replace(/^TREESEED_/u, "").replace(/_/gu, " ").toLowerCase().replace(/\b\w/gu, (letter) => letter.toUpperCase()),
+    group: "launch-hosts",
+    description: `Configuration declared by the ${item.requirementKey} launch requirement.`,
+    howToGet: "Resolve this value from the selected launch host or configured deployment secret manager.",
+    sensitivity: item.sensitivity,
+    targets: normalizeTargets(item.targets),
+    scopes: item.scopes,
+    requirement: item.requirementKind === "secret" ? "required" : "conditional",
+    purposes: ["deploy", "config"],
+    storage: item.sensitivity === "secret" ? "scoped" : "shared",
+    validation: { kind: "nonempty" },
+    sourcePriority: ["machine-config", "process-env"],
+    sourceRequirement: item.requirementKey,
+    sourceHostType,
+    sourceProvider
+  };
+}
+function applyProjectLaunchHostBindingConfig(options) {
+  const configWrites = options.hostBindingPlans?.configWrites ?? [];
+  const secretItems = options.hostBindingPlans?.secretDeployment?.items ?? [];
+  const hostBindings = options.hostBindings ?? {};
+  const documents = /* @__PURE__ */ new Map();
+  const summaries = [];
+  const environmentSummaries = [];
+  for (const write of configWrites) {
+    assertTarget(write.target);
+    const operation = write.mergeStrategy ?? "replace";
+    if (!TEMPLATE_CONFIG_MERGE_STRATEGIES.includes(operation)) {
+      throw new Error(`Unsupported host binding config merge strategy "${operation}".`);
+    }
+    const binding = hostBindings[write.requirementKey];
+    const value = resolveWriteValue(write, binding, options);
+    if (!shouldWrite(write, binding, value)) continue;
+    const document = documents.get(write.target) ?? readStructuredFile(resolve(options.projectRoot, write.target), write.target);
+    documents.set(write.target, document);
+    setDotPath(document, write.path, value, operation);
+    summaries.push({
+      target: write.target,
+      path: write.path,
+      requirementKey: write.requirementKey,
+      requirementKind: write.requirementKind,
+      provider: write.provider,
+      operation,
+      valuePreview: summarizeValue(value)
+    });
+  }
+  if (secretItems.length > 0) {
+    const target = "src/env.yaml";
+    const document = documents.get(target) ?? readStructuredFile(resolve(options.projectRoot, target), target);
+    documents.set(target, document);
+    document.entries = document.entries && typeof document.entries === "object" && !Array.isArray(document.entries) ? document.entries : {};
+    for (const item of secretItems) {
+      const binding = hostBindings[item.requirementKey];
+      document.entries[item.env] = {
+        ...document.entries[item.env] ?? {},
+        ...buildEnvironmentEntry(item, binding)
+      };
+      environmentSummaries.push({
+        env: item.env,
+        requirementKey: item.requirementKey,
+        requirementKind: item.requirementKind,
+        sourceHostType: binding?.type ?? null,
+        sourceProvider: binding?.provider ?? null,
+        sensitivity: item.sensitivity,
+        targets: item.targets,
+        scopes: item.scopes
+      });
+    }
+  }
+  for (const [target, document] of documents) {
+    writeStructuredFile(resolve(options.projectRoot, target), target, document);
+  }
+  return {
+    configWrites: summaries,
+    environmentWrites: environmentSummaries,
+    targets: [...documents.keys()]
+  };
+}
+function compareStatus(diagnostics) {
+  if (diagnostics.some((diagnostic) => diagnostic.status === "blocked")) return "blocked";
+  if (diagnostics.some((diagnostic) => diagnostic.status === "warning")) return "warning";
+  return "ok";
+}
+function auditProjectLaunchHostBindingConfig(options) {
+  const plannedTargets = /* @__PURE__ */ new Set();
+  for (const write of options.hostBindingPlans?.configWrites ?? []) {
+    assertTarget(write.target);
+    plannedTargets.add(write.target);
+  }
+  if ((options.hostBindingPlans?.secretDeployment?.items ?? []).length > 0) {
+    plannedTargets.add("src/env.yaml");
+  }
+  const checkedTargets = [...plannedTargets];
+  const tempRoot = mkdtempSync(join(tmpdir(), "treeseed-host-binding-audit-"));
+  const before = /* @__PURE__ */ new Map();
+  try {
+    for (const target of checkedTargets) {
+      const sourcePath = resolve(options.projectRoot, target);
+      const targetPath = resolve(tempRoot, target);
+      if (existsSync(sourcePath)) {
+        ensureDir(dirname(targetPath));
+        cpSync(sourcePath, targetPath);
+        before.set(target, readFileSync(sourcePath, "utf8"));
+      } else {
+        before.set(target, null);
+      }
+    }
+    const expected = applyProjectLaunchHostBindingConfig({
+      ...options,
+      projectRoot: tempRoot
+    });
+    const diagnostics = [];
+    const changedTargets = [];
+    for (const target of checkedTargets) {
+      const sourcePath = resolve(options.projectRoot, target);
+      const expectedPath = resolve(tempRoot, target);
+      const expectedContent = existsSync(expectedPath) ? readFileSync(expectedPath, "utf8") : null;
+      const actualContent = existsSync(sourcePath) ? readFileSync(sourcePath, "utf8") : null;
+      if (before.get(target) === null && expectedContent !== null) {
+        changedTargets.push(target);
+        diagnostics.push({
+          code: "missing_config_target",
+          status: "warning",
+          target,
+          message: `${target} is missing host-bound configuration.`
+        });
+      } else if (actualContent !== expectedContent) {
+        changedTargets.push(target);
+        diagnostics.push({
+          code: "stale_config_target",
+          status: "warning",
+          target,
+          message: `${target} does not match the current host binding plan.`
+        });
+      }
+    }
+    return {
+      status: compareStatus(diagnostics),
+      checkedTargets,
+      changedTargets,
+      diagnostics,
+      expected
+    };
+  } catch (error) {
+    const target = checkedTargets[0] ?? "treeseed.site.yaml";
+    const diagnostics = [{
+      code: "invalid_config_target",
+      status: "blocked",
+      target,
+      message: error instanceof Error ? error.message : String(error)
+    }];
+    return {
+      status: "blocked",
+      checkedTargets,
+      changedTargets: [],
+      diagnostics,
+      expected: { configWrites: [], environmentWrites: [], targets: [] }
+    };
+  } finally {
+    rmSync(tempRoot, { recursive: true, force: true });
+  }
+}
+function preserveProjectLaunchHostBindingConfigOverlay(options) {
+  assertTarget(options.target);
+  const configWrites = options.hostBindingPlans?.configWrites ?? [];
+  const shouldPreserveConfigWrites = configWrites.some((write) => write.target === options.target);
+  const shouldPreserveEnvironmentEntries = options.target === "src/env.yaml";
+  if (!shouldPreserveConfigWrites && !shouldPreserveEnvironmentEntries) {
+    return options.nextContent;
+  }
+  const currentDocument = parseStructuredContent(options.currentContent, options.target);
+  const nextDocument = parseStructuredContent(options.nextContent, options.target);
+  for (const write of configWrites) {
+    if (write.target !== options.target) continue;
+    safePathSegments(write.path);
+    if (!hasPath(currentDocument, write.path)) continue;
+    setDotPath(nextDocument, write.path, getPath(currentDocument, write.path), "replace");
+  }
+  if (options.target === "src/env.yaml") {
+    const currentEntries = currentDocument.entries && typeof currentDocument.entries === "object" && !Array.isArray(currentDocument.entries) ? currentDocument.entries : {};
+    nextDocument.entries = nextDocument.entries && typeof nextDocument.entries === "object" && !Array.isArray(nextDocument.entries) ? nextDocument.entries : {};
+    for (const [entryId, entry] of Object.entries(currentEntries)) {
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+      if (typeof entry.sourceRequirement !== "string") continue;
+      nextDocument.entries[entryId] = entry;
+    }
+  }
+  return stringifyStructuredContent(nextDocument, options.target);
+}
+export {
+  applyProjectLaunchHostBindingConfig,
+  auditProjectLaunchHostBindingConfig,
+  preserveProjectLaunchHostBindingConfigOverlay
+};

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

@@ -1,4 +1,5 @@
-import { type SdkTemplateCatalogEntry } from '../../sdk-types.ts';
+import { type SdkTemplateCatalogEntry, type TemplateLaunchRequirements } from '../../sdk-types.ts';
+import { type ProjectLaunchConfigWritePlanItem, type ProjectLaunchLocalHostBindingSummary, type ProjectLaunchResolvedHostBinding, type ProjectLaunchSecretDeploymentPlanItem } from '../../template-launch-requirements.ts';
 export declare const TEMPLATE_CATEGORIES: readonly ["starter", "example", "fixture", "reference-app"];
 export type TemplateCategory = (typeof TEMPLATE_CATEGORIES)[number];
 export interface TemplateVariableDefinition {
@@ -27,6 +28,7 @@ export interface TemplateManifest {
         validatedOnly?: string[];
         tenantManaged?: string[];
     };
+    launchRequirements?: TemplateLaunchRequirements;
     testing: {
         smokeCommand?: string;
         buildCommand?: string;
@@ -53,6 +55,22 @@ export interface StarterResolutionInput {
     contactEmail?: string | null;
     repositoryUrl?: string | null;
     discordUrl?: string | null;
+    hostBindingState?: StarterHostBindingState | null;
+}
+export interface StarterHostBindingState {
+    hostBindings: Record<string, ProjectLaunchResolvedHostBinding>;
+    hostBindingPlans: {
+        configWrites: ProjectLaunchConfigWritePlanItem[];
+        secretDeployment: {
+            items: ProjectLaunchSecretDeploymentPlanItem[];
+        };
+    };
+    hostBindingSummaries?: ProjectLaunchLocalHostBindingSummary[];
+    hostBindingConfig?: {
+        configWrites?: unknown[];
+        environmentWrites?: unknown[];
+        targets?: string[];
+    } | null;
 }
 interface TemplateCatalogOptions {
     cwd?: string;
@@ -66,10 +84,11 @@ export declare function validateTemplateProduct(product: Pick<TemplateProductDef
 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 recordTemplateHostBindingState(siteRoot: string, hostBindingState: StarterHostBindingState): void;
 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'>): {
+export declare function serializeTemplateRegistryEntry(product: Pick<TemplateProductDefinition, 'id' | 'displayName' | 'description' | 'summary' | 'status' | 'featured' | 'category' | 'tags' | 'publisher' | 'templateVersion' | 'templateApiVersion' | 'minCliVersion' | 'minCoreVersion' | 'fulfillment' | 'launchRequirements'>): {
     id: string;
     displayName: string;
     description: string;
@@ -85,6 +104,7 @@ export declare function serializeTemplateRegistryEntry(product: Pick<TemplatePro
     minCoreVersion: string | undefined;
     fulfillmentMode: "r2" | "git" | "packaged";
     source: import("../../sdk-types.ts").SdkTemplateCatalogSource;
+    launchRequirements: TemplateLaunchRequirements | undefined;
 };
 export declare function exportTemplateCatalogYaml(options?: TemplateCatalogOptions): Promise<string>;
 export {};

package/dist/operations/services/template-registry.js

@@ -2,6 +2,10 @@ import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, write
 import { spawnSync } from "node:child_process";
 import { basename, dirname, relative, resolve } from "node:path";
 import { RemoteTemplateCatalogClient } from "../../template-catalog.js";
+import {
+  normalizeTemplateLaunchRequirements
+} from "../../template-launch-requirements.js";
+import { preserveProjectLaunchHostBindingConfigOverlay } from "./template-host-bindings.js";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 import {
   resolveTreeseedTemplateCatalogCachePath,
@@ -98,6 +102,7 @@ function validateTemplateManifest(definition) {
   if (!existsSync(templateRoot)) {
     throw new Error(`Template ${manifest.id} is missing template/ at ${templateRoot}.`);
   }
+  manifest.launchRequirements = normalizeTemplateLaunchRequirements(manifest.launchRequirements, `${manifestPath}: launchRequirements`);
   validateTemplatePlaceholders(definition);
 }
 function validateTemplatePlaceholders(definition) {
@@ -426,10 +431,52 @@ async function scaffoldTemplateProject(templateId, targetRoot, input, options =
     sourceRef: definition.product.fulfillment.source.ref,
     installedAt: (/* @__PURE__ */ new Date()).toISOString(),
     lastSyncedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    replacements
+    replacements,
+    ...input.hostBindingState ? {
+      hostBindings: input.hostBindingState.hostBindings,
+      hostBindingPlans: input.hostBindingState.hostBindingPlans,
+      hostBindingSummaries: input.hostBindingState.hostBindingSummaries,
+      hostBindingConfig: input.hostBindingState.hostBindingConfig
+    } : {}
   });
   return definition.product;
 }
+function recordTemplateHostBindingState(siteRoot, hostBindingState) {
+  const state = loadTemplateState(siteRoot);
+  writeTemplateState(siteRoot, {
+    ...state,
+    hostBindings: hostBindingState.hostBindings,
+    hostBindingPlans: hostBindingState.hostBindingPlans,
+    hostBindingSummaries: hostBindingState.hostBindingSummaries,
+    hostBindingConfig: hostBindingState.hostBindingConfig
+  });
+}
+function preserveHostBindingOverlayIfNeeded(relativePath, currentContent, nextContent, state) {
+  if (!state.hostBindingPlans) {
+    return nextContent;
+  }
+  if (relativePath !== "treeseed.site.yaml" && relativePath !== "src/env.yaml" && relativePath !== "src/manifest.yaml" && relativePath !== "package.json") {
+    return nextContent;
+  }
+  return preserveProjectLaunchHostBindingConfigOverlay({
+    target: relativePath,
+    currentContent,
+    nextContent,
+    hostBindingPlans: state.hostBindingPlans
+  });
+}
+function structuredTemplateContentMatches(relativePath, currentContent, nextContent) {
+  if (relativePath !== "treeseed.site.yaml" && relativePath !== "src/env.yaml" && relativePath !== "src/manifest.yaml" && relativePath !== "package.json") {
+    return false;
+  }
+  try {
+    const current = relativePath === "package.json" ? JSON.parse(currentContent || "{}") : parseYaml(currentContent || "{}");
+    const next = relativePath === "package.json" ? JSON.parse(nextContent || "{}") : parseYaml(nextContent || "{}");
+    return JSON.stringify(current) === JSON.stringify(next);
+  } catch {
+    return false;
+  }
+}
 async function syncTemplateProject(siteRoot, options = {}) {
   const check = options.check === true;
   const state = loadTemplateState(siteRoot);
@@ -448,11 +495,19 @@ async function syncTemplateProject(siteRoot, options = {}) {
       }
       continue;
     }
-    const nextContent = renderTemplateFile(sourcePath, state.replacements);
     const currentContent = existsSync(targetPath) ? readFileSync(targetPath, "utf8") : "";
+    const nextContent = preserveHostBindingOverlayIfNeeded(
+      relativePath,
+      currentContent,
+      renderTemplateFile(sourcePath, state.replacements),
+      state
+    );
     if (currentContent === nextContent) {
       continue;
     }
+    if (state.hostBindingPlans && structuredTemplateContentMatches(relativePath, currentContent, nextContent)) {
+      continue;
+    }
     if (!check) {
       ensureDir(targetPath);
       writeFileSync(targetPath, nextContent, "utf8");
@@ -492,7 +547,8 @@ function serializeTemplateRegistryEntry(product) {
     minCliVersion: product.minCliVersion,
     minCoreVersion: product.minCoreVersion,
     fulfillmentMode: product.fulfillment.mode ?? "packaged",
-    source: product.fulfillment.source
+    source: product.fulfillment.source,
+    launchRequirements: product.launchRequirements
   };
 }
 async function exportTemplateCatalogYaml(options = {}) {
@@ -503,6 +559,7 @@ export {
   buildTemplateReplacements,
   exportTemplateCatalogYaml,
   listTemplateProducts,
+  recordTemplateHostBindingState,
   resolveTemplateDefinition,
   resolveTemplateProduct,
   scaffoldTemplateProject,

package/dist/operations/services/template-secret-sync.d.ts

@@ -0,0 +1,97 @@
+import { syncTreeseedCloudflareEnvironment, syncTreeseedGitHubEnvironment, syncTreeseedRailwayEnvironment, type TreeseedConfigScope } from './config-runtime.ts';
+import type { ProjectLaunchResolvedHostBinding, ProjectLaunchSecretDeploymentPlanItem } from '../../template-launch-requirements.ts';
+import type { ProjectLaunchRequirementKind } from '../../sdk-types.ts';
+export type ProjectLaunchSecretSyncProvider = 'github' | 'cloudflare' | 'railway';
+export type ProjectLaunchSecretSyncStatus = 'synced' | 'skipped' | 'failed';
+export type ProjectLaunchSecretSyncProviderStatus = 'running' | 'completed' | 'failed';
+export type ProjectLaunchSecretSyncTargetKind = 'github-secret' | 'github-variable' | 'cloudflare-secret' | 'cloudflare-var' | 'railway-secret' | 'railway-var';
+export interface ProjectLaunchSecretValueDiagnostic {
+    code: 'missing_value' | 'unsupported_target';
+    requirementKey: string;
+    requirementKind: ProjectLaunchRequirementKind;
+    env: string;
+    source: string;
+    targets: string[];
+    scopes: TreeseedConfigScope[];
+    message: string;
+}
+export interface ProjectLaunchResolvedSecretValueItem {
+    requirementKey: string;
+    requirementKind: ProjectLaunchRequirementKind;
+    env: string;
+    source: string;
+    targets: ProjectLaunchSecretSyncTargetKind[];
+    scopes: TreeseedConfigScope[];
+    sensitivity: string;
+    sourceHostId?: string | null;
+    resolved: boolean;
+}
+export interface ProjectLaunchSecretValueOverlayResult {
+    valuesOverlay: Record<string, string>;
+    items: ProjectLaunchResolvedSecretValueItem[];
+    diagnostics: ProjectLaunchSecretValueDiagnostic[];
+}
+export interface ProjectLaunchSecretSyncSummaryItem {
+    provider: ProjectLaunchSecretSyncProvider;
+    scope: TreeseedConfigScope;
+    target: ProjectLaunchSecretSyncTargetKind;
+    env: string;
+    requirementKey: string;
+    requirementKind: ProjectLaunchRequirementKind;
+    sensitivity: string;
+    status: ProjectLaunchSecretSyncStatus;
+    error?: {
+        message: string;
+    };
+}
+export interface ProjectLaunchSecretSyncProviderSummary {
+    provider: ProjectLaunchSecretSyncProvider;
+    scope: TreeseedConfigScope;
+    entryIds: string[];
+    status: Exclude<ProjectLaunchSecretSyncProviderStatus, 'running'>;
+    error?: {
+        message: string;
+    };
+}
+export interface ProjectLaunchSecretSyncProgressEvent {
+    provider: ProjectLaunchSecretSyncProvider;
+    scope: TreeseedConfigScope;
+    status: ProjectLaunchSecretSyncProviderStatus;
+    entryIds: string[];
+    message: string;
+}
+export interface ProjectLaunchSecretSyncResult {
+    ok: boolean;
+    items: ProjectLaunchSecretSyncSummaryItem[];
+    providers: ProjectLaunchSecretSyncProviderSummary[];
+    diagnostics: ProjectLaunchSecretValueDiagnostic[];
+}
+export interface ProjectLaunchSecretSyncAdapters {
+    github?: typeof syncTreeseedGitHubEnvironment;
+    cloudflare?: typeof syncTreeseedCloudflareEnvironment;
+    railway?: typeof syncTreeseedRailwayEnvironment;
+}
+export interface ResolveProjectLaunchSecretValueOverlayOptions {
+    hostBindings?: Record<string, ProjectLaunchResolvedHostBinding> | null;
+    secretDeploymentPlan?: {
+        items?: ProjectLaunchSecretDeploymentPlanItem[] | null;
+    } | null;
+    valuesOverlay?: Record<string, string | undefined> | null;
+    valuesByScope?: Partial<Record<TreeseedConfigScope, Record<string, string | undefined> | null>> | null;
+    processEnv?: Record<string, string | undefined>;
+    scopes?: TreeseedConfigScope[];
+}
+export interface SyncProjectLaunchHostBindingSecretsOptions extends ResolveProjectLaunchSecretValueOverlayOptions {
+    projectRoot: string;
+    repository?: string | null;
+    dryRun?: boolean;
+    providers?: ProjectLaunchSecretSyncProvider[];
+    onProgress?: (event: ProjectLaunchSecretSyncProgressEvent) => void | Promise<void>;
+    adapters?: ProjectLaunchSecretSyncAdapters;
+}
+export declare class ProjectLaunchSecretSyncError extends Error {
+    readonly result: ProjectLaunchSecretSyncResult;
+    constructor(message: string, result: ProjectLaunchSecretSyncResult);
+}
+export declare function resolveProjectLaunchSecretValueOverlay(options: ResolveProjectLaunchSecretValueOverlayOptions): ProjectLaunchSecretValueOverlayResult;
+export declare function syncProjectLaunchHostBindingSecrets(options: SyncProjectLaunchHostBindingSecretsOptions): Promise<ProjectLaunchSecretSyncResult>;