@treeseed/sdk 0.11.0 → 0.12.5

package/dist/operations/services/package-adapters.js

@@ -1,8 +1,22 @@
-import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { relative, resolve } from "node:path";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
 import { parse as parseYaml } from "yaml";
 import { workspacePackages, workspaceRoot } from "./workspace-tools.js";
+import { runTreeseedGit } from "./git-runner.js";
+import { resolveTreeseedLaunchEnvironment } from "./config-runtime.js";
+import { resolveGitHubCredentialForRepository } from "./github-credentials.js";
+import {
+  createGitHubApiClient,
+  getLatestGitHubWorkflowRun
+} from "./github-api.js";
+import { resolveTreeseedDockerhubToken, resolveTreeseedDockerhubUsername } from "../../service-credentials.js";
+import { inspectTreeseedContentStructure } from "../../platform/content-runtime-source.js";
+import {
+  SEED_CONTENT_PUBLISH_TARGETS,
+  SEED_CONTENT_RUNTIME_SOURCES,
+  SEED_LOCAL_CONTENT_MATERIALIZATIONS,
+  SEED_PROJECT_TOPOLOGIES
+} from "../../seeds/types.js";
 function readJsonFile(filePath) {
   try {
     return JSON.parse(readFileSync(filePath, "utf8"));
@@ -42,6 +56,49 @@ function commandFromScript(dir, script, label) {
   }
   return { label, command: "bash", args: ["-lc", trimmed], cwd: dir };
 }
+function normalizePackageSlug(id) {
+  const raw = id.startsWith("@treeseed/") ? id.slice("@treeseed/".length) : id;
+  return raw.toLowerCase().replace(/^treeseed-/u, "").replace(/[^a-z0-9]+/gu, "-").replace(/^-+|-+$/gu, "") || "package";
+}
+function enumValue(value, allowed, fallback) {
+  return typeof value === "string" && allowed.includes(value) ? value : fallback;
+}
+function normalizeTreeseedPackageProjectArchitecture(value, packageId) {
+  const record = stringRecord(value);
+  if (Object.keys(record).length === 0) return null;
+  const publishTarget = stringRecord(record.contentPublishTarget);
+  const packageSlug = normalizePackageSlug(packageId);
+  const targetKind = enumValue(publishTarget.kind, SEED_CONTENT_PUBLISH_TARGETS, "cloudflare_r2");
+  return {
+    topology: enumValue(record.topology, SEED_PROJECT_TOPOLOGIES, "single_repository_site"),
+    rootPath: stringValue(record.rootPath) ?? ".",
+    sitePath: stringValue(record.sitePath) ?? "docs",
+    contentPath: stringValue(record.contentPath) ?? "docs",
+    contentRuntimeSource: enumValue(record.contentRuntimeSource, SEED_CONTENT_RUNTIME_SOURCES, "r2_published_manifest"),
+    localContentMaterialization: enumValue(record.localContentMaterialization, SEED_LOCAL_CONTENT_MATERIALIZATIONS, "none"),
+    contentPublishTarget: {
+      kind: targetKind,
+      ...stringValue(publishTarget.bucket) ? { bucket: stringValue(publishTarget.bucket) } : {},
+      prefix: stringValue(publishTarget.prefix) ?? `packages/${packageSlug}`,
+      ...stringValue(publishTarget.manifestPath) ? { manifestPath: stringValue(publishTarget.manifestPath) } : {}
+    }
+  };
+}
+function docsSiteReadiness(dir, architecture) {
+  if (!architecture) return null;
+  const diagnostic = inspectTreeseedContentStructure({ projectRoot: dir, architecture });
+  const readiness = diagnostic.status === "ready" ? "ready" : diagnostic.status === "unsupported_structure" ? "unsupported_structure" : "site_not_prepared";
+  return {
+    status: readiness,
+    diagnostic
+  };
+}
+function deploymentSourceModeForBranch(metadata, branch) {
+  const source = stringRecord(metadata.deploymentSource);
+  const normalizedBranch = branch === "prod" || branch === "production" || branch === "main" ? "prod" : branch === "staging" ? "staging" : "local";
+  const configured = stringValue(source[normalizedBranch]);
+  return configured === "git" || configured === "image" ? configured : normalizedBranch === "prod" ? "image" : stringValue(source.staging) === "git" ? "git" : null;
+}
 function nodeTypeScriptAdapter(pkg) {
   const manifest = readTreeseedPackageManifest(pkg.dir);
   const scripts = pkg.packageJson?.scripts && typeof pkg.packageJson.scripts === "object" && !Array.isArray(pkg.packageJson.scripts) ? pkg.packageJson.scripts : {};
@@ -49,8 +106,15 @@ function nodeTypeScriptAdapter(pkg) {
   const repository = stringValue(manifest?.repository) ?? normalizeGitHubRepositorySlug(pkg.packageJson?.repository);
   const id = stringValue(manifest?.id) ?? String(pkg.name);
   const name = stringValue(manifest?.name) ?? String(pkg.name);
-  const publishTarget = stringValue(manifest?.publishTarget) ?? "npm";
-  const hostedVerifyWorkflow = stringValue(stringRecord(manifest?.releaseGate).workflow) ?? (existsSync(resolve(pkg.dir, ".github/workflows/deploy.yml")) ? "deploy.yml" : null);
+  const dockerArtifacts = manifestDockerArtifacts(manifest?.artifacts);
+  const dockerImages = stringRecord(manifest?.dockerImages);
+  const dockerImageReleaseWorkflow = stringValue(dockerImages.releaseWorkflow);
+  const dockerImageArchitectures = stringArray(dockerImages.architectures);
+  const publishTargetRaw = stringValue(manifest?.publishTarget);
+  const publishTarget = dockerArtifacts.length > 0 && publishTargetRaw === "docker" ? dockerArtifacts[0].name : publishTargetRaw ?? "npm";
+  const hostedVerifyWorkflow = stringValue(manifest?.hostedVerifyWorkflow) ?? stringValue(stringRecord(manifest?.releaseGate).workflow) ?? (existsSync(resolve(pkg.dir, ".github/workflows/deploy.yml")) ? "deploy.yml" : null);
+  const projectArchitecture = normalizeTreeseedPackageProjectArchitecture(manifest?.projectArchitecture, id);
+  const docsReadiness = docsSiteReadiness(pkg.dir, projectArchitecture);
   const verifyLocal = typeof scripts["verify:local"] === "string" ? "verify:local" : typeof scripts.verify === "string" ? "verify" : typeof scripts["verify:action"] === "string" ? "verify:action" : null;
   return {
     id,
@@ -67,13 +131,40 @@ function nodeTypeScriptAdapter(pkg) {
       local: commandFromScript(pkg.dir, manifestVerify.local, "local") ?? (verifyLocal ? { label: verifyLocal, command: "npm", args: ["run", verifyLocal], cwd: pkg.dir } : null),
       release: commandFromScript(pkg.dir, manifestVerify.release, "release") ?? (typeof scripts["release:publish"] === "string" ? { label: "release:publish", command: "npm", args: ["run", "release:publish"], cwd: pkg.dir } : null)
     },
-    artifacts: [{ provider: "npm", name: String(pkg.name) }],
+    artifacts: dockerArtifacts.length > 0 ? dockerArtifacts.map((artifact) => ({
+      provider: "docker",
+      name: artifact.name,
+      dockerfile: artifact.dockerfile,
+      context: artifact.context,
+      target: artifact.target,
+      role: artifact.role,
+      architectures: artifact.architectures
+    })) : [{ provider: "npm", name: String(pkg.name) }],
     releaseChecks: [
-      { kind: "github-workflow", name: "publish workflow", detail: ".github/workflows/publish.yml" },
-      { kind: "npm-pack-dry-run", name: "npm pack", detail: "npm pack --dry-run" }
+      { kind: "github-workflow", name: "publish workflow", detail: dockerImageReleaseWorkflow ? `.github/workflows/${dockerImageReleaseWorkflow}` : ".github/workflows/publish.yml" },
+      ...dockerArtifacts.length > 0 ? dockerArtifacts.map((artifact) => ({ kind: "docker-manifest", name: `${artifact.name} Docker image manifest`, detail: `${artifact.name}:<version>` })) : [{ kind: "npm-pack-dry-run", name: "npm pack", detail: "npm pack --dry-run" }]
     ],
     metadata: {
       ...repository ? { repository } : {},
+      deploymentSource: stringRecord(manifest?.deploymentSource),
+      ...dockerArtifacts.length > 0 ? {
+        dockerArtifacts,
+        dockerImageReleaseWorkflow: dockerImageReleaseWorkflow ? `.github/workflows/${dockerImageReleaseWorkflow}` : ".github/workflows/publish.yml",
+        dockerImageArchitectures,
+        imageHosting: stringRecord(dockerImages.hosting)
+      } : {},
+      type: stringValue(manifest?.type) ?? null,
+      githubEnvironments: stringArray(manifest?.githubEnvironments),
+      requiredSecrets: stringArray(manifest?.requiredSecrets),
+      requiredVariables: stringArray(manifest?.requiredVariables),
+      workflowTemplateVersion: stringValue(manifest?.workflowTemplateVersion) ?? null,
+      localDev: stringRecord(manifest?.localDev),
+      capacityProvider: stringRecord(manifest?.capacityProvider),
+      ...projectArchitecture ? {
+        projectArchitecture,
+        docsSiteReadiness: docsReadiness?.status ?? "site_not_prepared",
+        docsSiteDiagnostic: docsReadiness?.diagnostic ?? null
+      } : {},
       ...hostedVerifyWorkflow ? {
         hostedVerifyWorkflow: hostedVerifyWorkflow.startsWith(".github/workflows/") ? hostedVerifyWorkflow : `.github/workflows/${hostedVerifyWorkflow}`
       } : {},
@@ -101,6 +192,24 @@ function stringValue(value) {
 function stringArray(value) {
   return Array.isArray(value) ? value.map((entry) => stringValue(entry)).filter((entry) => Boolean(entry)) : [];
 }
+function manifestDockerArtifacts(value) {
+  if (!Array.isArray(value)) return [];
+  return value.map((entry) => {
+    const record = stringRecord(entry);
+    if (stringValue(record.provider) !== "docker") return null;
+    const name = stringValue(record.name);
+    if (!name) return null;
+    return {
+      provider: "docker",
+      name,
+      dockerfile: stringValue(record.dockerfile),
+      context: stringValue(record.context),
+      target: stringValue(record.target),
+      role: stringValue(record.role),
+      architectures: stringArray(record.architectures)
+    };
+  }).filter((entry) => Boolean(entry));
+}
 function beamPackageAdapter(root, dir) {
   const manifest = readTreeseedPackageManifest(dir);
   const hasMixProject = existsSync(resolve(dir, "apps/api/mix.exs")) || existsSync(resolve(dir, "mix.exs"));
@@ -113,18 +222,13 @@ function beamPackageAdapter(root, dir) {
   const versionSource = resolve(dir, versionSourceRel);
   const image = typeof manifest?.image === "string" && manifest.image.trim() ? manifest.image.trim() : id === "treedx" ? "treeseed/treedx" : null;
   const repository = stringValue(manifest?.repository) ?? (id === "treedx" ? "treeseed-ai/treedx" : null);
-  const developmentImages = stringRecord(manifest?.developmentImages);
-  const developmentImageHosting = stringRecord(developmentImages.hosting);
-  const developmentImageWorkflow = image ? stringValue(developmentImages.workflow) ?? (id === "treedx" ? "dev-image.yml" : null) : null;
-  const hostedVerifyWorkflow = stringValue(stringRecord(manifest?.releaseGate).workflow) ?? (existsSync(resolve(dir, ".github/workflows/release-gate.yml")) ? "release-gate.yml" : null);
-  const developmentImageDefaultBranch = stringValue(developmentImages.defaultBranch) ?? "staging";
-  const developmentImageTagPrefix = stringValue(developmentImages.tagPrefix) ?? "dev";
-  const developmentImageMovingTag = developmentImages.movingTag === false ? false : true;
-  const developmentImageArchitectures = stringArray(developmentImages.architectures);
+  const hostedVerifyWorkflow = stringValue(manifest?.hostedVerifyWorkflow) ?? stringValue(stringRecord(manifest?.releaseGate).workflow) ?? (existsSync(resolve(dir, ".github/workflows/release-gate.yml")) ? "release-gate.yml" : null);
+  const projectArchitecture = normalizeTreeseedPackageProjectArchitecture(manifest?.projectArchitecture, id);
+  const docsReadiness = docsSiteReadiness(dir, projectArchitecture);
   const verify = manifest?.verify && typeof manifest.verify === "object" && !Array.isArray(manifest.verify) ? manifest.verify : {};
   const fast = verify.fast ?? (existsSync(resolve(dir, "scripts/test-treedx-fast.sh")) ? "scripts/test-treedx-fast.sh" : null);
   const local = verify.local ?? (existsSync(resolve(dir, "scripts/test-all.sh")) ? "scripts/test-all.sh" : null);
-  const releaseGate = manifest?.releaseGate ?? verify.release ?? (existsSync(resolve(dir, "scripts/release-gate.sh")) ? "scripts/release-gate.sh" : null);
+  const releaseGate = stringValue(manifest?.releaseGate) ?? verify.release ?? (existsSync(resolve(dir, "scripts/release-gate.sh")) ? "scripts/release-gate.sh" : null);
   const version = readMixProjectVersion(versionSource);
   const shaTag = "sha-<short-sha>";
   return {
@@ -142,37 +246,57 @@ function beamPackageAdapter(root, dir) {
       local: commandFromScript(dir, local, "local"),
       release: commandFromScript(dir, releaseGate, "release")
     },
-    artifacts: image ? [{ provider: "docker", name: image, tags: version ? [version, shaTag] : [shaTag] }] : [],
+    artifacts: image ? [{
+      provider: "docker",
+      name: image,
+      tags: version ? [version, shaTag] : [shaTag],
+      dockerfile: "Dockerfile",
+      context: ".",
+      target: null,
+      role: id,
+      architectures: stringArray(stringRecord(manifest?.dockerImages).architectures)
+    }] : [],
     releaseChecks: image ? [{ kind: "docker-manifest", name: "Docker image manifest", detail: `${image}:${version ?? "<version>"}` }] : [],
     metadata: {
       hasCargo: existsSync(resolve(dir, "Cargo.toml")),
       hasDockerfile: existsSync(resolve(dir, "Dockerfile")),
       repository,
+      deploymentSource: stringRecord(manifest?.deploymentSource),
+      imageHosting: stringRecord(stringRecord(manifest?.dockerImages).hosting),
       versionSource: versionSourceRel,
-      ...developmentImageWorkflow ? {
-        developmentImageWorkflow: developmentImageWorkflow.startsWith(".github/workflows/") ? developmentImageWorkflow : `.github/workflows/${developmentImageWorkflow}`,
-        developmentImageDefaultBranch,
-        developmentImageTagPrefix,
-        developmentImageMovingTag,
-        developmentImageArchitectures,
-        developmentImageTagPattern: `${image}:${developmentImageTagPrefix}-<branch-slug>-<short-sha>`,
-        developmentImageMovingTagPattern: developmentImageMovingTag ? `${image}:${developmentImageTagPrefix}-<branch-slug>` : null,
-        developmentImageHosting: Object.keys(developmentImageHosting).length > 0 ? developmentImageHosting : null
-      } : {},
       ...hostedVerifyWorkflow ? {
         hostedVerifyWorkflow: hostedVerifyWorkflow.startsWith(".github/workflows/") ? hostedVerifyWorkflow : `.github/workflows/${hostedVerifyWorkflow}`
+      } : {},
+      type: stringValue(manifest?.type) ?? null,
+      githubEnvironments: stringArray(manifest?.githubEnvironments),
+      requiredSecrets: stringArray(manifest?.requiredSecrets),
+      requiredVariables: stringArray(manifest?.requiredVariables),
+      workflowTemplateVersion: stringValue(manifest?.workflowTemplateVersion) ?? null,
+      ...projectArchitecture ? {
+        projectArchitecture,
+        docsSiteReadiness: docsReadiness?.status ?? "site_not_prepared",
+        docsSiteDiagnostic: docsReadiness?.diagnostic ?? null
       } : {}
     }
   };
 }
 function gitOutput(cwd, args) {
-  const result = spawnSync("git", args, { cwd, encoding: "utf8", stdio: "pipe" });
-  if (result.status !== 0) {
-    const stderr = typeof result.stderr === "string" ? result.stderr.trim() : "";
-    throw new Error(stderr || `git ${args.join(" ")} failed in ${cwd}.`);
-  }
+  const result = runTreeseedGit(args, { cwd, mode: "read" });
   return result.stdout.trim();
 }
+function gitRevisionSha(cwd, revision) {
+  try {
+    return gitOutput(cwd, ["rev-parse", revision]);
+  } catch (error) {
+    if (/^[A-Za-z0-9._/-]+$/u.test(revision) && !revision.startsWith("origin/")) {
+      try {
+        return gitOutput(cwd, ["rev-parse", `origin/${revision}`]);
+      } catch {
+      }
+    }
+    throw error;
+  }
+}
 function branchSlug(value) {
   const normalized = value.toLowerCase().replace(/[^a-z0-9]+/gu, "-").replace(/^-+|-+$/gu, "").slice(0, 40);
   return normalized || "branch";
@@ -182,30 +306,58 @@ function planTreeseedPackageDevelopmentImage(root = workspaceRoot(), idOrName, {
   if (!adapter) {
     throw new Error(`Treeseed package adapter ${idOrName} was not discovered.`);
   }
-  const imageName = typeof adapter.publishTarget === "string" && adapter.publishTarget.trim() ? adapter.publishTarget.trim() : null;
+  const firstDockerArtifact = adapter.artifacts.find((artifact) => artifact.provider === "docker") ?? null;
+  const imageName = typeof adapter.publishTarget === "string" && adapter.publishTarget.trim() ? adapter.publishTarget.trim() : firstDockerArtifact?.name ?? null;
   if (!imageName) {
     throw new Error(`${adapter.id} does not declare a publish image target.`);
   }
   const metadata = adapter.metadata;
-  const workflow = stringValue(metadata.developmentImageWorkflow)?.replace(/^\.github\/workflows\//u, "") ?? null;
-  if (!workflow) {
-    throw new Error(`${adapter.id} does not declare a development image workflow.`);
-  }
-  const selectedBranch = branch ?? stringValue(metadata.developmentImageDefaultBranch) ?? "staging";
-  const sha = gitOutput(adapter.dir, ["rev-parse", selectedBranch]);
-  const slug = branchSlug(selectedBranch);
+  const selectedBranch = branch ?? "staging";
+  const deploymentSourceMode = deploymentSourceModeForBranch(metadata, selectedBranch);
+  const sha = gitRevisionSha(adapter.dir, selectedBranch);
   const shortSha = sha.slice(0, 12);
-  const tagPrefix = stringValue(metadata.developmentImageTagPrefix) ?? "dev";
-  const immutableTag = `${tagPrefix}-${slug}-${shortSha}`;
-  const movingTag = metadata.developmentImageMovingTag === false ? null : `${tagPrefix}-${slug}`;
-  const architectures = stringArray(metadata.developmentImageArchitectures);
-  const hosting = stringRecord(metadata.developmentImageHosting);
-  const app = stringValue(hosting.app);
-  const environment = stringValue(hosting.environment) ?? selectedBranch;
-  const overrideEnvVar = stringValue(hosting.envVar);
-  const imageRef = `${imageName}:${immutableTag}`;
-  const movingImageRef = movingTag ? `${imageName}:${movingTag}` : null;
+  const deploymentEnvironment = selectedBranch === "main" ? "prod" : selectedBranch;
+  const imagePublicationRequired = (deploymentSourceMode ?? "image") === "image";
+  if (deploymentEnvironment !== "prod" && imagePublicationRequired) {
+    throw new Error(`${adapter.id} non-production package image planning is tagless and must use deploymentSource git.`);
+  }
+  const workflow = imagePublicationRequired ? stringValue(metadata.dockerImageReleaseWorkflow)?.replace(/^\.github\/workflows\//u, "") ?? "publish.yml" : "source-build";
+  const productionImageTag = deploymentEnvironment === "prod" ? adapter.version : null;
+  if (deploymentEnvironment === "prod" && (!productionImageTag || !/^\d+\.\d+\.\d+$/u.test(productionImageTag))) {
+    throw new Error(`${adapter.id} production image publication requires a stable semantic package version.`);
+  }
+  const immutableTag = productionImageTag;
+  const movingTag = null;
+  const architectures = stringArray(metadata.dockerImageArchitectures);
+  const dockerArtifacts = Array.isArray(metadata.dockerArtifacts) ? metadata.dockerArtifacts.map((entry) => {
+    const record = stringRecord(entry);
+    const artifactImageName = stringValue(record.name);
+    if (!artifactImageName) return null;
+    return {
+      role: stringValue(record.role) ?? artifactImageName.split("/").at(-1)?.replace(/^agent-/u, "") ?? artifactImageName,
+      imageName: artifactImageName,
+      target: stringValue(record.target),
+      architectures: stringArray(record.architectures)
+    };
+  }).filter((entry) => Boolean(entry)) : [];
+  const imageHosting = stringRecord(metadata.imageHosting);
+  const app = stringValue(imageHosting.app);
+  const overrideEnvVar = stringValue(imageHosting.envVar);
+  const environment = deploymentEnvironment === "prod" ? "prod" : stringValue(imageHosting.environment) ?? selectedBranch;
+  const imageRef = immutableTag ? `${imageName}:${immutableTag}` : null;
+  const movingImageRef = null;
   const hostingImageRef = movingImageRef ?? imageRef;
+  const roleImages = dockerArtifacts.length > 0 ? dockerArtifacts.map((artifact) => {
+    const artifactArchitectures = artifact.architectures.length > 0 ? artifact.architectures : architectures;
+    return {
+      role: artifact.role,
+      imageName: artifact.imageName,
+      target: artifact.target,
+      immutableRef: immutableTag ? `${artifact.imageName}:${immutableTag}` : null,
+      movingRef: null,
+      archImageRefs: immutableTag ? artifactArchitectures.map((arch) => `${artifact.imageName}:${immutableTag}-${arch}`) : []
+    };
+  }) : void 0;
   return {
     package: {
       id: adapter.id,
@@ -222,16 +374,24 @@ function planTreeseedPackageDevelopmentImage(root = workspaceRoot(), idOrName, {
     refs: {
       imageName,
       branch: selectedBranch,
-      branchSlug: slug,
+      branchSlug: branchSlug(selectedBranch),
       sha,
       shortSha,
       immutableTag,
       movingTag,
       imageRef,
       movingImageRef,
-      archImageRefs: architectures.map((arch) => `${imageName}:${immutableTag}-${arch}`)
+      archImageRefs: immutableTag ? architectures.map((arch) => `${imageName}:${immutableTag}-${arch}`) : [],
+      ...roleImages ? { roleImages } : {}
+    },
+    deploymentSource: {
+      environment: deploymentEnvironment,
+      mode: deploymentSourceMode ?? "image",
+      repository: stringValue(metadata.repository) ?? `${adapter.id}`,
+      commitSha: sha,
+      imagePublicationRequired
     },
-    hosting: app && overrideEnvVar ? {
+    hosting: imagePublicationRequired && app && overrideEnvVar && hostingImageRef ? {
       app,
       environment,
       overrideEnvVar,
@@ -260,7 +420,13 @@ function discoverTreeseedPackageAdapters(root = workspaceRoot()) {
   });
 }
 function findTreeseedPackageAdapter(root, idOrName) {
-  return discoverTreeseedPackageAdapters(root).find((adapter) => adapter.id === idOrName || adapter.name === idOrName) ?? null;
+  const normalized = idOrName.trim();
+  return discoverTreeseedPackageAdapters(root).find((adapter) => {
+    const scopedId = adapter.id.startsWith("@treeseed/") ? adapter.id.slice("@treeseed/".length) : null;
+    const scopedName = adapter.name.startsWith("@treeseed/") ? adapter.name.slice("@treeseed/".length) : null;
+    const directoryName = adapter.relativeDir.split("/").at(-1);
+    return adapter.id === normalized || adapter.name === normalized || scopedId === normalized || scopedName === normalized || directoryName === normalized;
+  }) ?? null;
 }
 function packageAdapterPlanSummary(root = workspaceRoot()) {
   return discoverTreeseedPackageAdapters(root).map((adapter) => ({
@@ -279,10 +445,417 @@ function packageAdapterPlanSummary(root = workspaceRoot()) {
     metadata: adapter.metadata
   }));
 }
+async function runTreeseedPackageImageWorkflow(options) {
+  const root = options.root ?? workspaceRoot();
+  const branch = options.branch ?? "staging";
+  const imagePlan = planTreeseedPackageDevelopmentImage(root, options.packageId, { branch });
+  const selectedWorkflow = options.workflow ?? imagePlan.workflow;
+  const execute = options.execute === true;
+  const syncConfig = options.syncConfig === true;
+  const configEnv = resolveTreeseedLaunchEnvironment({
+    tenantRoot: root,
+    scope: "staging",
+    baseEnv: options.env ?? process.env
+  });
+  const dockerHubUsername = resolveTreeseedDockerhubUsername(configEnv);
+  const dockerHubToken = resolveTreeseedDockerhubToken(configEnv);
+  const dockerHub = {
+    usernameConfigured: Boolean(dockerHubUsername),
+    tokenConfigured: Boolean(dockerHubToken),
+    requiredSecrets: imagePlan.deploymentSource?.imagePublicationRequired === false ? [] : ["TREESEED_DOCKERHUB_TOKEN"],
+    requiredVariables: imagePlan.deploymentSource?.imagePublicationRequired === false ? [] : ["TREESEED_DOCKERHUB_USERNAME"]
+  };
+  const credential = resolveGitHubCredentialForRepository(imagePlan.repository, { values: configEnv, env: options.env ?? process.env });
+  const githubClientEnv = credential.token ? { ...configEnv, TREESEED_GITHUB_TOKEN: credential.token, GH_TOKEN: credential.token, GITHUB_TOKEN: credential.token } : configEnv;
+  const report = {
+    ok: true,
+    action: execute ? "dispatch" : "plan",
+    package: imagePlan.package,
+    repository: imagePlan.repository,
+    workflow: selectedWorkflow,
+    branch: imagePlan.branch,
+    refs: imagePlan.refs,
+    deploymentSource: imagePlan.deploymentSource,
+    credential: {
+      repository: credential.repository,
+      envName: credential.envName,
+      configured: credential.configured,
+      source: credential.source,
+      fallbackUsed: credential.fallbackUsed
+    },
+    dockerHub,
+    hosting: imagePlan.hosting,
+    reconcile: {
+      lifecycle: syncConfig || execute ? ["refresh", "diff", "plan", "validate", "apply", "refresh", "verify", "persist"] : ["refresh", "diff", "plan"],
+      resources: [
+        `package-workflow:${imagePlan.package.id}`,
+        ...imagePlan.deploymentSource?.imagePublicationRequired === false ? [`source-build:${imagePlan.repository}#${imagePlan.deploymentSource.commitSha}`] : imagePlan.refs.roleImages ? imagePlan.refs.roleImages.map((entry) => `package-image:${entry.imageName}`) : [`package-image:${imagePlan.refs.imageName}`]
+      ]
+    }
+  };
+  if (syncConfig) {
+    const environment = imagePlan.hosting?.environment ?? "staging";
+    report.syncedConfig = {
+      environment,
+      blocked: true,
+      reason: imagePlan.deploymentSource?.imagePublicationRequired === false ? "Staging source-build policy does not sync Docker image credentials or image override variables." : "Package image config sync is reconciler-owned. Use trsd package image --sync-config so github-secret-binding and github-variable-binding resources apply through adapters.",
+      secrets: dockerHubToken ? [{ name: "TREESEED_DOCKERHUB_TOKEN", existed: null }] : [],
+      variables: dockerHubUsername ? [{ name: "TREESEED_DOCKERHUB_USERNAME", existed: null }] : []
+    };
+  }
+  if (execute) {
+    const client = createGitHubApiClient({ env: githubClientEnv });
+    report.dispatch = {
+      blocked: true,
+      reason: imagePlan.deploymentSource?.imagePublicationRequired === false ? "Staging deployment source is GitHub source build; routine development Docker image publication is disabled." : "Package image workflow dispatch is reconciler-owned. Use trsd package image --execute so github-workflow-dispatch/package-image resources apply through adapters."
+    };
+    if (imagePlan.deploymentSource?.imagePublicationRequired !== false) {
+      report.latestWorkflowRun = await getLatestGitHubWorkflowRun(imagePlan.repository, {
+        client,
+        workflow: selectedWorkflow,
+        branch: imagePlan.branch
+      });
+    }
+  }
+  return { imagePlan, selectedWorkflow, dockerHub, credential, report };
+}
+function validateTreeseedPackageManifests(root = workspaceRoot()) {
+  return discoverTreeseedPackageAdapters(root).map((adapter) => {
+    const errors = [];
+    const warnings = [];
+    if (!adapter.manifestPath || adapter.manifestPath.endsWith("package.json")) {
+      errors.push("missing treeseed.package.yaml");
+    }
+    if (!adapter.id.trim()) errors.push("missing package id");
+    if (!adapter.name.trim()) errors.push("missing package name");
+    if (!["node-typescript", "beam-elixir-rust"].includes(adapter.kind)) {
+      errors.push(`unsupported package kind ${adapter.kind}`);
+    }
+    if (adapter.verifyCommands.local == null) {
+      errors.push("missing local verification command");
+    }
+    if (!adapter.metadata.projectArchitecture) {
+      warnings.push("package does not declare projectArchitecture metadata");
+    }
+    if (adapter.releaseChecks.length === 0) {
+      warnings.push("package declares no release checks");
+    }
+    const hasDockerArtifact = adapter.artifacts.some((artifact) => artifact.provider === "docker");
+    if (hasDockerArtifact) {
+      const deploymentSource = stringRecord(adapter.metadata.deploymentSource);
+      if (stringValue(deploymentSource.staging) !== "git") {
+        errors.push("docker package must declare deploymentSource.staging: git");
+      }
+      if (stringValue(deploymentSource.prod) !== "image") {
+        errors.push("docker package must declare deploymentSource.prod: image");
+      }
+      const architectures = stringArray(adapter.metadata.dockerImageArchitectures);
+      if (!architectures.includes("amd64") || !architectures.includes("arm64")) {
+        errors.push("docker package must declare amd64 and arm64 architectures");
+      }
+    }
+    for (const artifact of adapter.artifacts) {
+      if (artifact.provider === "docker" && !artifact.name.startsWith("treeseed/")) {
+        errors.push(`docker artifact ${artifact.name} must publish under treeseed/*`);
+      }
+    }
+    return {
+      packageId: adapter.id,
+      path: adapter.relativeDir,
+      manifestPath: adapter.manifestPath,
+      ok: errors.length === 0,
+      errors,
+      warnings
+    };
+  });
+}
+function deriveTreeseedPackageProjectResources(root = workspaceRoot(), options = {}) {
+  const team = options.team ?? "team:treeseed";
+  return discoverTreeseedPackageAdapters(root).map((adapter) => {
+    const architecture = adapter.metadata.projectArchitecture;
+    const repository = stringValue(adapter.metadata.repository);
+    if (!architecture || !repository) return null;
+    const [owner, name] = repository.split("/");
+    if (!owner || !name) return null;
+    const slug = normalizePackageSlug(adapter.id);
+    return {
+      key: `project:treeseed/${slug}`,
+      team,
+      slug,
+      name: adapter.name,
+      description: `${adapter.name} first-party package project.`,
+      kind: "package",
+      repository: {
+        role: "primary",
+        provider: "github",
+        owner,
+        name,
+        gitUrl: `https://github.com/${owner}/${name}.git`,
+        defaultBranch: "main",
+        checkoutPath: adapter.relativeDir
+      },
+      architecture,
+      metadata: {
+        packageId: adapter.id,
+        packagePath: adapter.relativeDir,
+        visibility: "public",
+        docsSiteReadiness: stringValue(adapter.metadata.docsSiteReadiness) ?? "site_not_prepared",
+        releaseOwnership: "treeseed.package.yaml"
+      }
+    };
+  }).filter((entry) => Boolean(entry));
+}
+function workflowNameForTemplate(adapter, template) {
+  const publishWorkflow = "publish.yml";
+  const configuredReleaseGate = stringValue(adapter.metadata.hostedVerifyWorkflow)?.replace(/^\.github\/workflows\//u, "") ?? "verify.yml";
+  if (template === "docker-image") return publishWorkflow;
+  if (template === "release-gate") {
+    return configuredReleaseGate === publishWorkflow ? "release-gate.yml" : configuredReleaseGate;
+  }
+  return publishWorkflow;
+}
+function renderTreeseedPackageWorkflow(adapter, template) {
+  const verifyCommand = template === "release-gate" ? adapter.verifyCommands.release ?? adapter.verifyCommands.local : adapter.verifyCommands.local;
+  const verify = verifyCommand ? formatWorkflowRunCommand(verifyCommand.command, verifyCommand.args) : "npm run verify:local";
+  const setup = resolveWorkflowSetupCommand(adapter);
+  const dockerArtifacts = adapter.artifacts.filter((artifact) => artifact.provider === "docker");
+  if (template === "npm-publish") {
+    return `name: Publish ${adapter.name}
+
+on:
+  push:
+    tags:
+      - "*.*.*"
+  workflow_dispatch:
+
+jobs:
+  publish:
+    if: startsWith(github.ref, 'refs/tags/') && !contains(github.ref_name, '-')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    environment: production
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+      - run: ${setup}
+      - run: ${verify}
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: \${{ secrets.NPM_TOKEN }}
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+        run: gh release create "\${GITHUB_REF_NAME}" --generate-notes --verify-tag
+`;
+  }
+  if (template === "docker-image") {
+    const environment = "production";
+    const imageSetup = adapter.kind === "node-typescript" ? resolveDockerImageWorkflowSetupCommand() : null;
+    const anyTarget = dockerArtifacts.some((artifact) => typeof artifact.target === "string" && artifact.target.trim().length > 0);
+    const dockerContextPrepareCommand = isRecord(adapter.metadata.scripts) && typeof adapter.metadata.scripts["capacity-provider:build"] === "string" ? "npm run capacity-provider:build -- --prepare-only" : null;
+    const trigger = `    tags:
+      - "*.*.*"`;
+    const jobCondition = "startsWith(github.ref, 'refs/tags/') && !contains(github.ref_name, '-')";
+    const computeTagsStep = `      - name: Compute image tags
+        id: tags
+        run: |
+          version="\${GITHUB_REF_NAME#v}"
+          echo "base=\${version}" >> "$GITHUB_OUTPUT"
+          echo "moving=" >> "$GITHUB_OUTPUT"
+`;
+    const releaseStep = `  release:
+    needs: manifest
+    if: ${jobCondition}
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+        run: gh release create "\${GITHUB_REF_NAME}" --generate-notes --verify-tag
+`;
+    return `name: Publish Image ${adapter.name}
+
+on:
+  workflow_dispatch:
+  push:
+${trigger}
+
+jobs:
+  build:
+    if: ${jobCondition}
+    runs-on: \${{ matrix.runner }}
+    permissions:
+      contents: write
+      packages: write
+    environment: ${environment}
+    strategy:
+      matrix:
+        include:
+${dockerArtifacts.flatMap((artifact) => [
+      `          - image: ${artifact.name}${anyTarget ? `
+            target: ${artifact.target ?? ""}` : ""}
+            arch: amd64
+            platform: linux/amd64
+            runner: ubuntu-24.04`,
+      `          - image: ${artifact.name}${anyTarget ? `
+            target: ${artifact.target ?? ""}` : ""}
+            arch: arm64
+            platform: linux/arm64
+            runner: ubuntu-24.04-arm`
+    ]).join("\n") || `          - image: treeseed/unknown
+            arch: amd64
+            platform: linux/amd64
+            runner: ubuntu-24.04`}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+${imageSetup ? `      - run: ${imageSetup}
+` : ""}${dockerContextPrepareCommand ? `      - run: ${dockerContextPrepareCommand}
+` : ""}${computeTagsStep}      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          username: \${{ vars.TREESEED_DOCKERHUB_USERNAME }}
+          password: \${{ secrets.TREESEED_DOCKERHUB_TOKEN }}
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+${anyTarget ? "          target: ${{ matrix.target }}\n" : ""}          platforms: \${{ matrix.platform }}
+          push: true
+          tags: \${{ matrix.image }}:\${{ steps.tags.outputs.base }}-\${{ matrix.arch }}
+
+  manifest:
+    needs: build
+    if: ${jobCondition}
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+      packages: write
+    environment: ${environment}
+    strategy:
+      matrix:
+        include:
+${dockerArtifacts.map((artifact) => `          - image: ${artifact.name}`).join("\n") || "          - image: treeseed/unknown"}
+    steps:
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          username: \${{ vars.TREESEED_DOCKERHUB_USERNAME }}
+          password: \${{ secrets.TREESEED_DOCKERHUB_TOKEN }}
+${computeTagsStep}      - name: Publish multi-architecture manifest
+        run: |
+          docker buildx imagetools create \\
+            -t "\${{ matrix.image }}:\${{ steps.tags.outputs.base }}" \\
+            "\${{ matrix.image }}:\${{ steps.tags.outputs.base }}-amd64" \\
+            "\${{ matrix.image }}:\${{ steps.tags.outputs.base }}-arm64"
+${releaseStep}`;
+  }
+  const needsNodeSetup = adapter.kind === "node-typescript";
+  const needsBeamSetup = adapter.kind === "beam-elixir-rust";
+  return `name: Verify ${adapter.name}
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+${needsNodeSetup ? `      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: ${setup}
+` : ""}${needsBeamSetup ? `      - uses: erlef/setup-beam@v1
+        with:
+          otp-version: "27"
+          elixir-version: "1.17.3"
+      - run: mix local.hex --force && mix local.rebar --force
+` : ""}      - run: ${verify}
+`;
+}
+function resolveWorkflowSetupCommand(adapter) {
+  const scripts = adapter.metadata.scripts;
+  if (isRecord(scripts) && typeof scripts["release:setup"] === "string") {
+    return 'npm run release:setup || (echo "dependency install failed; retrying" && npm run release:setup)';
+  }
+  return 'npm ci || (echo "dependency install failed; retrying" && npm ci)';
+}
+function resolveDockerImageWorkflowSetupCommand() {
+  return 'npm ci --ignore-scripts || (echo "dependency install failed; retrying" && npm ci --ignore-scripts)';
+}
+function isRecord(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+function formatWorkflowRunCommand(command, args) {
+  return [command, ...args].map(shellQuoteWorkflowArg).join(" ");
+}
+function shellQuoteWorkflowArg(value) {
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/u.test(value)) return value;
+  return `'${value.replace(/'/gu, `'\\''`)}'`;
+}
+function workflowTemplatesForAdapter(adapter) {
+  const hasDocker = adapter.artifacts.some((artifact) => artifact.provider === "docker");
+  const hasNpm = adapter.artifacts.some((artifact) => artifact.provider === "npm");
+  return [
+    ...hasNpm ? ["npm-publish"] : [],
+    ...hasDocker ? ["docker-image"] : [],
+    "release-gate"
+  ];
+}
+function syncTreeseedPackageWorkflows({
+  root = workspaceRoot(),
+  packageId,
+  execute = false
+} = {}) {
+  const adapters = packageId && packageId !== "all" ? [findTreeseedPackageAdapter(root, packageId)].filter((entry) => Boolean(entry)) : discoverTreeseedPackageAdapters(root);
+  const results = [];
+  for (const adapter of adapters) {
+    for (const template of workflowTemplatesForAdapter(adapter)) {
+      const workflow = workflowNameForTemplate(adapter, template);
+      const path = resolve(adapter.dir, ".github", "workflows", workflow);
+      const rendered = renderTreeseedPackageWorkflow(adapter, template);
+      const current = existsSync(path) ? readFileSync(path, "utf8") : null;
+      const changed = current !== rendered;
+      if (execute && changed) {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, rendered, "utf8");
+      }
+      results.push({
+        packageId: adapter.id,
+        path,
+        workflow,
+        template,
+        exists: current != null,
+        changed,
+        written: execute && changed
+      });
+    }
+  }
+  return results;
+}
 export {
+  deriveTreeseedPackageProjectResources,
   discoverTreeseedPackageAdapters,
   findTreeseedPackageAdapter,
   packageAdapterPlanSummary,
   planTreeseedPackageDevelopmentImage,
-  readMixProjectVersion
+  readMixProjectVersion,
+  renderTreeseedPackageWorkflow,
+  runTreeseedPackageImageWorkflow,
+  syncTreeseedPackageWorkflows,
+  validateTreeseedPackageManifests
 };