@hadooppei/hwcode 0.2.4 → 1.0.1

package/.pi/lib/runtime/session-state.ts

@@ -4,11 +4,6 @@ export interface CustomSessionEntry {
   data?: unknown;
 }
 
-export interface SessionEntrySource {
-  getEntries(): readonly CustomSessionEntry[];
-  getSessionId(): string;
-}
-
 export interface StateCodec<T> {
   customType: string;
   decode(value: unknown): T | undefined;
@@ -30,32 +25,3 @@ export function findLatestState<T>(
   }
   return { found: false };
 }
-
-export class SessionStateCache<T> {
-  private readonly values = new Map<string, T | undefined>();
-  private readonly codec: StateCodec<T>;
-
-  constructor(codec: StateCodec<T>) {
-    this.codec = codec;
-  }
-
-  restore(source: SessionEntrySource): T | undefined {
-    const lookup = findLatestState(source.getEntries(), this.codec);
-    const value = lookup.value;
-    this.values.set(source.getSessionId(), value);
-    return value;
-  }
-
-  get(source: SessionEntrySource): T | undefined {
-    if (!this.values.has(source.getSessionId())) return this.restore(source);
-    return this.values.get(source.getSessionId());
-  }
-
-  set(source: SessionEntrySource, value: T | undefined): void {
-    this.values.set(source.getSessionId(), value);
-  }
-
-  clear(sessionId: string): void {
-    this.values.delete(sessionId);
-  }
-}

package/.pi/lib/{cloud → workflows/cloud}/adapters.ts

@@ -8,8 +8,9 @@ import {
   type CloudCredentials,
   type CloudProvider,
   type CloudVendorId,
-} from "../cloud-providers.ts";
+} from "./providers.ts";
 import { runProcess, truncateOutput, type ProcessResult } from "./process.ts";
+import { CLOUD_RUNTIME_DEFAULTS } from "../../runtime/defaults.ts";
 
 export interface TemporaryCredentialStore {
   createDirectory(prefix: string): string;
@@ -41,18 +42,6 @@ function validationFailure(result: ProcessResult, credentials: CloudCredentials)
   return truncateOutput(redactCredentialValues(raw, credentials));
 }
 
-function huaweiAuthenticationArgs(credentials: CloudCredentials): string[] {
-  return [
-    `--cli-access-key=${credentials.accessKey}`,
-    `--cli-secret-key=${credentials.secretKey}`,
-    `--cli-region=${credentials.region}`,
-    ...(credentials.securityToken ? [`--cli-security-token=${credentials.securityToken}`] : []),
-    ...(credentials.projectId ? [`--cli-project-id=${credentials.projectId}`] : []),
-    ...(credentials.domainId ? [`--cli-domain-id=${credentials.domainId}`] : []),
-    "--cli-output=json",
-  ];
-}
-
 function basicAdapter(
   vendor: CloudVendorId,
   validationCommand: string,
@@ -64,7 +53,7 @@ function basicAdapter(
       cwd: root,
       env: cloudEnvironment(vendor, credentials),
       signal,
-      timeoutMs: 30_000,
+      timeoutMs: CLOUD_RUNTIME_DEFAULTS.process.providerValidationTimeoutMs,
     }),
     prepare: async (_command, args, { credentials }) => ({
       args,
@@ -75,7 +64,7 @@ function basicAdapter(
 
 async function validateAzure(context: AdapterContext): Promise<ProcessResult> {
   const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), 30_000);
+  const timeout = setTimeout(() => controller.abort(), CLOUD_RUNTIME_DEFAULTS.process.providerValidationTimeoutMs);
   const abort = () => controller.abort();
   context.signal?.addEventListener("abort", abort, { once: true });
   try {
@@ -128,11 +117,11 @@ const adapters: Record<CloudVendorId, CloudProviderAdapter> = {
     provider: getCloudProvider("huawei"),
     validate: ({ root, credentials, signal }) => runProcess(
       "hcloud",
-      ["IAM", "KeystoneListProjects", ...huaweiAuthenticationArgs(credentials)],
-      { cwd: root, env: cloudEnvironment("huawei", credentials), signal, timeoutMs: 30_000 },
+      ["IAM", "KeystoneListProjects", ...mergeHuaweiArgs([], credentials)],
+      { cwd: root, env: cloudEnvironment("huawei", credentials), signal, timeoutMs: CLOUD_RUNTIME_DEFAULTS.process.providerValidationTimeoutMs },
     ),
     prepare: async (command, args, { credentials }) => ({
-      args: command === "hcloud" ? [...args, ...huaweiAuthenticationArgs(credentials)] : args,
+      args: command === "hcloud" ? mergeHuaweiArgs(args, credentials) : args,
       env: cloudEnvironment("huawei", credentials),
     }),
   },
@@ -151,7 +140,7 @@ const adapters: Record<CloudVendorId, CloudProviderAdapter> = {
             CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE: path,
           },
           signal: context.signal,
-          timeoutMs: 30_000,
+          timeoutMs: CLOUD_RUNTIME_DEFAULTS.process.providerValidationTimeoutMs,
         });
       } finally {
         context.temporaryStore.cleanupDirectory(directory);
@@ -194,7 +183,7 @@ const adapters: Record<CloudVendorId, CloudProviderAdapter> = {
       const selection = await runProcess(
         "az",
         ["account", "set", "--subscription", context.credentials.subscriptionId],
-        { cwd: context.root, env: azureEnv, signal: context.signal, timeoutMs: 30_000 },
+        { cwd: context.root, env: azureEnv, signal: context.signal, timeoutMs: CLOUD_RUNTIME_DEFAULTS.process.providerValidationTimeoutMs },
       );
       if (selection.code !== 0) {
         return { args, env: azureEnv, cleanup, error: validationFailure(selection, context.credentials) };
@@ -232,3 +221,32 @@ export function checkProviderCli(vendor: CloudVendorId, root: string): Promise<P
   const provider = getCloudProvider(vendor);
   return runProcess(provider.cli, provider.versionArgs, { cwd: root, timeoutMs: 10_000 });
 }
+
+function mergeHuaweiArgs(args: readonly string[], credentials: CloudCredentials): string[] {
+  const result = [...args];
+  const hasArg = (prefix: string) => result.some((arg) => arg.startsWith(prefix));
+  if (!hasArg("--cli-access-key=")) {
+    result.push(`--cli-access-key=${credentials.accessKey}`);
+  }
+  if (!hasArg("--cli-secret-key=")) {
+    result.push(`--cli-secret-key=${credentials.secretKey}`);
+  }
+  if (!hasArg("--cli-region=")) {
+    if (credentials.region?.trim()) {
+      result.push(`--cli-region=${credentials.region.trim()}`);
+    }
+  }
+  if (credentials.securityToken && !hasArg("--cli-security-token=")) {
+    result.push(`--cli-security-token=${credentials.securityToken}`);
+  }
+  if (credentials.projectId && !hasArg("--cli-project-id=")) {
+    result.push(`--cli-project-id=${credentials.projectId}`);
+  }
+  if (credentials.domainId && !hasArg("--cli-domain-id=")) {
+    result.push(`--cli-domain-id=${credentials.domainId}`);
+  }
+  if (!hasArg("--cli-output=")) {
+    result.push("--cli-output=json");
+  }
+  return result;
+}

package/.pi/lib/workflows/cloud/bundles.ts

@@ -0,0 +1,358 @@
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { dirname, extname, isAbsolute, join, relative, sep } from "node:path";
+
+import { isCloudVendorId, type CloudVendorId } from "./providers.ts";
+import type { WorkflowState } from "../state.ts";
+import { legacyUserCloudTemplatePaths, userRuntimePaths } from "../../runtime/paths.ts";
+import { CLOUD_RUNTIME_DEFAULTS } from "../../runtime/defaults.ts";
+import { renderCloudPromptTemplate } from "./templates.ts";
+
+export interface TerraformTemplateManifest {
+  schemaVersion: 2;
+  id: string;
+  name: string;
+  vendor: CloudVendorId;
+  createdAt: string;
+  updatedAt: string;
+  sourceDigest: string;
+  contentDigest: string;
+  metadataDigest?: string;
+  migratedFrom?: 1;
+  failedApproaches: Array<{ approach: string; reason: string }>;
+  artifacts: {
+    terraform: boolean;
+    charts: boolean;
+    discovery: string[];
+    reports: string[];
+    verification: boolean;
+    excluded: Array<{ path: string; reason: string }>;
+  };
+}
+
+export interface CloudDeploymentTemplate {
+  manifest: TerraformTemplateManifest;
+  path: string;
+  terraformPath: string;
+  chartsPath: string;
+  discoveryPath: string;
+  summaryPath: string;
+  verificationPath: string;
+}
+
+export function cloudDeploymentTemplateSource(template: CloudDeploymentTemplate): {
+  id: string; name: string; createdAt: string; updatedAt: string; kind: "terraform";
+} {
+  return { id: template.manifest.id, name: template.manifest.name, createdAt: template.manifest.createdAt, updatedAt: template.manifest.updatedAt, kind: "terraform" };
+}
+
+export function defaultCloudBundleDirectory(home = homedir()): string {
+  return userRuntimePaths(home).cloudDeploymentTemplates;
+}
+
+function excluded(name: string): boolean {
+  return name === ".terraform"
+    || name === "terraform.tfstate"
+    || name === "terraform.tfstate.backup"
+    || name.endsWith(".tfplan")
+    || name.endsWith(".tfstate")
+    || name.endsWith(".tfvars")
+    || name.endsWith(".tfvars.json");
+}
+
+function credentialLikeContent(content: string): boolean {
+  return /(?:access[_-]?key|secret(?:[_-]?key)?|password|token)\s*["'=:\s]+[A-Za-z0-9+/=_-]{8,}/iu.test(content);
+}
+
+interface CopyReport { copied: string[]; excluded: Array<{ path: string; reason: string }> }
+
+function copySafeDirectory(source: string, destination: string, include: (path: string, name: string) => boolean, category = "artifact"): CopyReport {
+  const copied: string[] = [];
+  const skipped: Array<{ path: string; reason: string }> = [];
+  const visit = (from: string, to: string) => {
+    mkdirSync(to, { recursive: true, mode: 0o700 });
+    for (const entry of readdirSync(from, { withFileTypes: true })) {
+      if (excluded(entry.name)) {
+        skipped.push({ path: `${category}/${relative(source, join(from, entry.name)).split(sep).join("/")}`, reason: "runtime-or-sensitive-Terraform-file" });
+        continue;
+      }
+      const sourcePath = join(from, entry.name);
+      const destinationPath = join(to, entry.name);
+      if (entry.isDirectory()) visit(sourcePath, destinationPath);
+      else if (entry.isFile()) {
+        if (!include(sourcePath, entry.name)) {
+          skipped.push({ path: `${category}/${relative(source, sourcePath).split(sep).join("/")}`, reason: "unsupported-or-sensitive-content" });
+          continue;
+        }
+        copyFileSync(sourcePath, destinationPath);
+        chmodSync(destinationPath, 0o600);
+        copied.push(destinationPath);
+      }
+    }
+  };
+  if (existsSync(source)) visit(source, destination);
+  return { copied, excluded: skipped };
+}
+
+function digestDirectory(root: string): string {
+  const entries: string[] = [];
+  const visit = (directory: string) => {
+    for (const entry of readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (excluded(entry.name)) continue;
+      const path = join(directory, entry.name);
+      if (entry.isDirectory()) visit(path);
+      else if (entry.isFile()) entries.push(`${relative(root, path).split(sep).join("/")}\0${createHash("sha256").update(readFileSync(path)).digest("hex")}`);
+    }
+  };
+  visit(root);
+  return createHash("sha256").update(entries.join("\n")).digest("hex");
+}
+
+function copyTerraformDirectory(source: string, destination: string): CopyReport {
+  return copySafeDirectory(source, destination, (path) => !credentialLikeContent(readFileSync(path, "utf8")), "terraform");
+}
+
+function copyChartsDirectory(source: string, destination: string): CopyReport {
+  return copySafeDirectory(source, destination, (path, name) => (
+    name !== "Chart.lock" || !credentialLikeContent(readFileSync(path, "utf8"))
+  ) && !name.endsWith(".tgz") && [".yaml", ".yml", ".tpl", ".json", ".md", ".txt"].includes(extname(name).toLowerCase()), "charts");
+}
+
+function sanitizeDiscovery(value: unknown, key = ""): unknown {
+  if (/(?:secret|password|token|credential|access[_-]?key)/iu.test(key)) return "<redacted>";
+  if (/(?:^|_)(?:id|ip|address|endpoint|url)$/iu.test(key) && (typeof value === "string" || typeof value === "number")) return "<runtime-value>";
+  if (Array.isArray(value)) return value.map((item) => sanitizeDiscovery(item, key));
+  if (value && typeof value === "object") return Object.fromEntries(Object.entries(value as Record<string, unknown>).map(([childKey, child]) => [childKey, sanitizeDiscovery(child, childKey)]));
+  return value;
+}
+
+function copyDiscoveryDirectory(source: string, destination: string): CopyReport {
+  const report = copySafeDirectory(source, destination, (path, name) => extname(name).toLowerCase() === ".json" && !credentialLikeContent(readFileSync(path, "utf8")), "discovery");
+  for (const path of report.copied) {
+    try { writeFileSync(path, `${JSON.stringify(sanitizeDiscovery(JSON.parse(readFileSync(path, "utf8"))), null, 2)}\n`, { encoding: "utf8", mode: 0o600 }); }
+    catch {
+      rmSync(path, { force: true });
+      report.excluded.push({ path: `discovery/${relative(destination, path).split(sep).join("/")}`, reason: "invalid-json" });
+    }
+  }
+  report.copied = report.copied.filter(existsSync);
+  return report;
+}
+
+function sanitizeReports(report: CopyReport, destination: string): CopyReport {
+  for (const path of report.copied) {
+    const extension = extname(path).toLowerCase();
+    if (extension === ".json") {
+      try { writeFileSync(path, `${JSON.stringify(sanitizeDiscovery(JSON.parse(readFileSync(path, "utf8"))), null, 2)}\n`, { encoding: "utf8", mode: 0o600 }); }
+      catch {
+        rmSync(path, { force: true });
+        report.excluded.push({ path: `reports/${relative(destination, path).split(sep).join("/")}`, reason: "invalid-json" });
+      }
+      continue;
+    }
+    const sanitized = readFileSync(path, "utf8")
+      .replace(/\b(?:\d{1,3}\.){3}\d{1,3}\b/gu, "<runtime-ip>")
+      .replace(/\b[0-9a-f]{8}-[0-9a-f-]{27,}\b/giu, "<runtime-id>")
+      .replace(/https?:\/\/[^\s)`]+/giu, "<runtime-endpoint>");
+    writeFileSync(path, sanitized, { encoding: "utf8", mode: 0o600 });
+  }
+  report.copied = report.copied.filter(existsSync);
+  return report;
+}
+
+function writeAtomic(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  writeFileSync(temporary, content, { encoding: "utf8", mode: 0o600 });
+  renameSync(temporary, path);
+  chmodSync(path, 0o600);
+}
+
+function buildManifest(
+  state: WorkflowState,
+  name: string,
+  sourceDigest: string,
+  createdAt: string,
+  updatedAt: string,
+  artifacts: TerraformTemplateManifest["artifacts"],
+  contentDigest: string,
+): TerraformTemplateManifest {
+  return {
+    schemaVersion: 2, id: `hwcloud-${name.toLowerCase().replace(/[^a-z0-9]+/gu, "-").replace(/^-+|-+$/gu, "").slice(0, CLOUD_RUNTIME_DEFAULTS.templates.slugMaxLength) || randomUUID()}`,
+    name, vendor: state.details!.vendor, createdAt, updatedAt, sourceDigest, contentDigest,
+    failedApproaches: state.details!.failedApproaches.map(({ approach, reason }) => ({ approach, reason })),
+    artifacts,
+  };
+}
+
+function digestManifestMetadata(manifest: TerraformTemplateManifest): string {
+  const { metadataDigest: _metadataDigest, ...metadata } = manifest;
+  return createHash("sha256").update(JSON.stringify(metadata)).digest("hex");
+}
+
+function sealManifest(manifest: TerraformTemplateManifest): TerraformTemplateManifest {
+  return { ...manifest, metadataDigest: digestManifestMetadata(manifest) };
+}
+
+function renderVerification(state: WorkflowState): string {
+  const steps = state.details!.successfulSteps
+    .map((step) => `- [${step.operation}] ${step.intent} (${step.approach})`)
+    .join("\n");
+  return `# Verification path\n\n${steps || "No successful verification steps were recorded."}\n`;
+}
+
+function writeBundleArtifacts(
+  destination: string,
+  terraformSource: string,
+  artifactWorkspace: string | undefined,
+  state: WorkflowState,
+): TerraformTemplateManifest["artifacts"] {
+  const terraform = copyTerraformDirectory(terraformSource, join(destination, "terraform"));
+  const charts = artifactWorkspace ? copyChartsDirectory(join(artifactWorkspace, "charts"), join(destination, "charts")) : { copied: [], excluded: [] };
+  const discovery = artifactWorkspace ? copyDiscoveryDirectory(join(artifactWorkspace, "discovery"), join(destination, "discovery")) : { copied: [], excluded: [] };
+  const reportsDestination = join(destination, "reports");
+  const reports = artifactWorkspace ? sanitizeReports(copySafeDirectory(join(artifactWorkspace, "reports"), reportsDestination, (path, name) => !credentialLikeContent(readFileSync(path, "utf8")) && [".md", ".json", ".txt"].includes(extname(name).toLowerCase()), "reports"), reportsDestination) : { copied: [], excluded: [] };
+  writeAtomic(join(destination, "verification.md"), renderVerification(state));
+  return {
+    terraform: terraform.copied.length > 0,
+    charts: charts.copied.length > 0,
+    discovery: discovery.copied.map((path) => relative(join(destination, "discovery"), path).split(sep).join("/")),
+    reports: reports.copied.map((path) => relative(join(destination, "reports"), path).split(sep).join("/")),
+    verification: true,
+    excluded: [...terraform.excluded, ...charts.excluded, ...discovery.excluded, ...reports.excluded],
+  };
+}
+
+function digestBundleContent(path: string): string {
+  const parts: string[] = [];
+  for (const name of ["terraform", "charts", "discovery", "reports"]) {
+    const directory = join(path, name);
+    if (existsSync(directory)) parts.push(`${name}\0${digestDirectory(directory)}`);
+  }
+  for (const name of ["summary.md", "verification.md"]) {
+    const file = join(path, name);
+    if (existsSync(file)) parts.push(`${name}\0${createHash("sha256").update(readFileSync(file)).digest("hex")}`);
+  }
+  return createHash("sha256").update(parts.join("\n")).digest("hex");
+}
+
+export function saveCloudDeploymentTemplate(
+  requestedName: string,
+  terraformSource: string,
+  state: WorkflowState,
+  directory = defaultCloudBundleDirectory(),
+  savedAt = new Date(),
+  artifactWorkspace?: string,
+): CloudDeploymentTemplate {
+  if (state.mode !== "cloud" || !state.details) throw new Error("Cloud workflow state is required");
+  if (!isAbsolute(terraformSource) || !existsSync(terraformSource) || !statSync(terraformSource).isDirectory()) throw new Error("Terraform source directory is required");
+  const name = requestedName.replace(/[\r\n]+/gu, " ").replace(/\s+/gu, " ").trim().slice(0, CLOUD_RUNTIME_DEFAULTS.templates.nameMaxLength);
+  if (!name) throw new Error("Cloud Deployment Template name is required");
+  const temporary = `${directory}/.${process.pid}.${randomUUID()}.tmp`;
+  const artifacts = writeBundleArtifacts(temporary, terraformSource, artifactWorkspace, state);
+  writeAtomic(join(temporary, "summary.md"), `${renderCloudPromptTemplate(state)}\n`);
+  const sourceDigest = digestDirectory(join(temporary, "terraform"));
+  const manifest = sealManifest(buildManifest(state, name, sourceDigest, savedAt.toISOString(), savedAt.toISOString(), artifacts, digestBundleContent(temporary)));
+  const path = join(directory, manifest.id);
+  if (existsSync(path)) {
+    rmSync(temporary, { recursive: true, force: true });
+    throw new Error(`Cloud Deployment Template already exists: ${manifest.id}`);
+  }
+  try {
+    writeAtomic(join(temporary, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    renameSync(temporary, path);
+  } catch (error) {
+    if (existsSync(temporary)) rmSync(temporary, { recursive: true, force: true });
+    throw error;
+  }
+  return {
+    manifest,
+    path,
+    terraformPath: join(path, "terraform"),
+    chartsPath: join(path, "charts"),
+    discoveryPath: join(path, "discovery"),
+    summaryPath: join(path, "summary.md"),
+    verificationPath: join(path, "verification.md"),
+  };
+}
+
+export function updateCloudDeploymentTemplate(
+  template: CloudDeploymentTemplate,
+  terraformSource: string,
+  state: WorkflowState,
+  savedAt = new Date(),
+  artifactWorkspace?: string,
+): CloudDeploymentTemplate {
+  if (state.mode !== "cloud" || !state.details) throw new Error("Cloud workflow state is required");
+  if (!isAbsolute(terraformSource) || !existsSync(terraformSource) || !statSync(terraformSource).isDirectory()) throw new Error("Terraform source directory is required");
+  const temporary = `${template.path}.${process.pid}.${randomUUID()}.tmp`;
+  const backup = `${template.path}.${process.pid}.${randomUUID()}.bak`;
+  let manifest: TerraformTemplateManifest;
+  try {
+    const artifacts = writeBundleArtifacts(temporary, terraformSource, artifactWorkspace, state);
+    writeAtomic(join(temporary, "summary.md"), `${renderCloudPromptTemplate(state)}\n`);
+    manifest = sealManifest({
+      ...buildManifest(state, template.manifest.name, digestDirectory(join(temporary, "terraform")), template.manifest.createdAt, savedAt.toISOString(), artifacts, digestBundleContent(temporary)),
+      id: template.manifest.id,
+    });
+    writeAtomic(join(temporary, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+    renameSync(template.path, backup);
+    renameSync(temporary, template.path);
+    rmSync(backup, { recursive: true, force: true });
+  } catch (error) {
+    if (existsSync(temporary)) rmSync(temporary, { recursive: true, force: true });
+    if (existsSync(backup) && !existsSync(template.path)) renameSync(backup, template.path);
+    throw error;
+  }
+  return { manifest: manifest!, path: template.path, terraformPath: join(template.path, "terraform"), chartsPath: join(template.path, "charts"), discoveryPath: join(template.path, "discovery"), summaryPath: join(template.path, "summary.md"), verificationPath: join(template.path, "verification.md") };
+}
+
+export function parseCloudDeploymentTemplate(path: string): CloudDeploymentTemplate | undefined {
+  const manifestPath = join(path, "manifest.json");
+  if (!existsSync(manifestPath)) return undefined;
+  const raw = JSON.parse(readFileSync(manifestPath, "utf8")) as Record<string, unknown>;
+  if (![1, 2].includes(raw.schemaVersion as number) || typeof raw.id !== "string" || typeof raw.name !== "string"
+    || typeof raw.vendor !== "string" || !isCloudVendorId(raw.vendor)
+    || typeof raw.createdAt !== "string" || typeof raw.updatedAt !== "string"
+    || typeof raw.sourceDigest !== "string" || !existsSync(join(path, "terraform"))) return undefined;
+  const oldArtifacts = (raw.artifacts && typeof raw.artifacts === "object" ? raw.artifacts : {}) as TerraformTemplateManifest["artifacts"];
+  let manifest = raw.schemaVersion === 2 ? raw as unknown as TerraformTemplateManifest : ({
+    ...raw,
+    schemaVersion: 2,
+    migratedFrom: 1,
+    contentDigest: digestBundleContent(path),
+    artifacts: { ...oldArtifacts, reports: [], excluded: [] },
+  } as unknown as TerraformTemplateManifest);
+  if (typeof manifest.contentDigest !== "string") return undefined;
+  if (manifest.metadataDigest && manifest.metadataDigest !== digestManifestMetadata(manifest)) return undefined;
+  if (!manifest.metadataDigest) manifest = sealManifest(manifest);
+  return { manifest, path, terraformPath: join(path, "terraform"), chartsPath: join(path, "charts"), discoveryPath: join(path, "discovery"), summaryPath: join(path, "summary.md"), verificationPath: join(path, "verification.md") };
+}
+
+export function listCloudDeploymentTemplates(directory?: string, home = homedir()): CloudDeploymentTemplate[] {
+  const directories = directory
+    ? [directory]
+    : [...new Set([defaultCloudBundleDirectory(home), legacyUserCloudTemplatePaths(home).deployments])];
+  return directories
+    .filter(existsSync)
+    .flatMap((path) => readdirSync(path, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => parseCloudDeploymentTemplate(join(path, entry.name))))
+    .filter((template): template is CloudDeploymentTemplate => Boolean(template))
+    .sort((left, right) => right.manifest.updatedAt.localeCompare(left.manifest.updatedAt) || left.manifest.name.localeCompare(right.manifest.name));
+}
+
+export function materializeCloudDeploymentTemplate(template: CloudDeploymentTemplate, workspace: string): { terraformPath: string } {
+  if (!isAbsolute(workspace)) throw new Error("Cloud artifact workspace must be absolute");
+  const actualDigest = digestBundleContent(template.path);
+  if (actualDigest !== template.manifest.contentDigest) throw new Error("Cloud Deployment Template content digest mismatch; reuse is blocked");
+  if (template.manifest.metadataDigest !== digestManifestMetadata(template.manifest)) throw new Error("Cloud Deployment Template metadata digest mismatch; reuse is blocked");
+  for (const name of ["terraform", "charts", "discovery", "reports"]) {
+    const source = join(template.path, name);
+    if (!existsSync(source)) continue;
+    copySafeDirectory(source, join(workspace, name), () => true, name);
+  }
+  return { terraformPath: join(workspace, "terraform") };
+}

package/.pi/lib/workflows/cloud/execution.ts

@@ -0,0 +1,28 @@
+import type { CloudWorkflowDetails, WorkflowState } from "../state.ts";
+
+export function cloudExecutionBlockReason(state: WorkflowState | undefined, options: { allowAfterTerminalFailure?: boolean } = {}): string | undefined {
+  if (!state || state.mode !== "cloud" || !state.details) return "HWCode Cloud is not active.";
+  if (state.status !== "active") return `HWCode Cloud is ${state.status}.`;
+  if (state.details.terminalFailure && !options.allowAfterTerminalFailure) return "Cloud workflow reached its failure budget; only read-only inspection, cleanup deletion, or workflow completion is allowed.";
+  return undefined;
+}
+
+export function recordStrategyFailure(
+  details: CloudWorkflowDetails,
+  strategy: string,
+  stage: string,
+  reason: string,
+  maxStrategies: number,
+): CloudWorkflowDetails {
+  const normalized = strategy.trim().toLowerCase().replace(/\s+/gu, " ").slice(0, 160);
+  if (!normalized) return details;
+  const index = details.failedApproaches.findIndex((item) => item.approach.trim().toLowerCase().replace(/\s+/gu, " ") === normalized);
+  const failedApproaches = [...details.failedApproaches];
+  if (index >= 0) {
+    const current = failedApproaches[index]!;
+    failedApproaches[index] = { ...current, reason: reason.slice(0, 1_000), stage, attempts: (current.attempts ?? 1) + 1, failedAt: new Date().toISOString() };
+  } else {
+    failedApproaches.push({ approach: strategy.trim().slice(0, 160), reason: reason.slice(0, 1_000), stage, attempts: 1, failedAt: new Date().toISOString() });
+  }
+  return { ...details, failedApproaches, terminalFailure: failedApproaches.length >= maxStrategies };
+}

package/.pi/lib/{cloud → workflows/cloud}/process.ts

@@ -1,6 +1,8 @@
 import { spawn } from "node:child_process";
 
-export const MAX_CLOUD_OUTPUT_BYTES = 50_000;
+import { CLOUD_RUNTIME_DEFAULTS } from "../../runtime/defaults.ts";
+
+export const MAX_CLOUD_OUTPUT_BYTES = CLOUD_RUNTIME_DEFAULTS.process.maxOutputBytes;
 const MAX_CAPTURE_BYTES = MAX_CLOUD_OUTPUT_BYTES * 2;
 const CLOUD_ENV_PREFIXES = [
   "AWS_", "AZURE_", "ARM_", "GOOGLE_", "CLOUDSDK_", "HW_", "HUAWEI",
@@ -64,10 +66,10 @@ export function runProcess(
       killed = true;
       timedOut ||= timeout;
       child.kill("SIGTERM");
-      forceKillTimer ??= setTimeout(() => child.kill("SIGKILL"), 2_000);
+      forceKillTimer ??= setTimeout(() => child.kill("SIGKILL"), CLOUD_RUNTIME_DEFAULTS.process.forceKillGraceMs);
     };
     const abort = () => terminate(false);
-    const timeoutTimer = setTimeout(() => terminate(true), options.timeoutMs ?? 120_000);
+    const timeoutTimer = setTimeout(() => terminate(true), options.timeoutMs ?? CLOUD_RUNTIME_DEFAULTS.process.commandTimeoutMs);
     if (options.signal?.aborted) abort();
     else options.signal?.addEventListener("abort", abort, { once: true });
     child.stdout.on("data", (chunk: Buffer) => { stdout = captureOutput(stdout, chunk); });

package/.pi/lib/{cloud-providers.ts → workflows/cloud/providers.ts}

@@ -30,7 +30,7 @@ export const CLOUD_PROVIDERS: readonly CloudProvider[] = [
 			{ key: "accessKeyId", label: "Access Key ID" },
 			{ key: "secretAccessKey", label: "Secret Access Key", secret: true },
 			{ key: "sessionToken", label: "Session Token（临时凭据可选）", secret: true, optional: true },
-			{ key: "region", label: "默认 Region", placeholder: "us-east-1" },
+			{ key: "region", label: "默认 Region", placeholder: "请输入目标 Region（必填）" },
 		],
 	},
 	{
@@ -64,7 +64,7 @@ export const CLOUD_PROVIDERS: readonly CloudProvider[] = [
 			{ key: "accessKey", label: "Access Key (AK)" },
 			{ key: "secretKey", label: "Secret Access Key (SK)", secret: true },
 			{ key: "securityToken", label: "Security Token（临时凭据可选）", secret: true, optional: true },
-			{ key: "region", label: "Region", placeholder: "cn-north-4" },
+			{ key: "region", label: "Region", placeholder: "请输入目标 Region（必填）" },
 			{ key: "projectId", label: "Project ID（可选）", optional: true },
 			{ key: "domainId", label: "Domain ID（全局服务可选）", optional: true },
 		],
@@ -78,7 +78,7 @@ export const CLOUD_PROVIDERS: readonly CloudProvider[] = [
 			{ key: "accessKeyId", label: "AccessKey ID" },
 			{ key: "accessKeySecret", label: "AccessKey Secret", secret: true },
 			{ key: "securityToken", label: "STS Security Token（可选）", secret: true, optional: true },
-			{ key: "region", label: "默认 Region", placeholder: "cn-hangzhou" },
+			{ key: "region", label: "默认 Region", placeholder: "请输入目标 Region（必填）" },
 		],
 	},
 	{
@@ -90,7 +90,7 @@ export const CLOUD_PROVIDERS: readonly CloudProvider[] = [
 			{ key: "secretId", label: "SecretId" },
 			{ key: "secretKey", label: "SecretKey", secret: true },
 			{ key: "token", label: "临时凭据 Token（可选）", secret: true, optional: true },
-			{ key: "region", label: "默认 Region", placeholder: "ap-guangzhou" },
+			{ key: "region", label: "默认 Region", placeholder: "请输入目标 Region（必填）" },
 		],
 	},
 ] as const;

package/.pi/lib/workflows/cloud/remote/bootstrap.ts

@@ -0,0 +1,23 @@
+import type { RemoteTargetProfile } from "./profiles.ts";
+import { runSsh } from "./ssh-transport.ts";
+import { existsSync, readFileSync } from "node:fs";
+import { parseSshKeyscan } from "./host-key.ts";
+
+export interface RunnerCapabilityReport {
+  ready: boolean;
+  terraformVersion?: string;
+  missing: string[];
+}
+
+export async function prepareRemoteRunner(profile: RemoteTargetProfile, signal?: AbortSignal): Promise<RunnerCapabilityReport> {
+  if (!existsSync(profile.knownHostsPath) || !parseSshKeyscan(readFileSync(profile.knownHostsPath, "utf8")).some((key) => key.fingerprint === profile.hostKeyFingerprint)) {
+    throw new Error("Runner host fingerprint is not present in the pinned known_hosts file; reconnect and verify the host key");
+  }
+  const created = await runSsh(profile, "mkdir", ["-p", profile.remoteRoot, `${profile.remoteRoot}/runs`], { signal, remoteCwd: "" });
+  if (created.code !== 0) throw new Error(created.stderr.trim() || "cannot create the managed Runner directory");
+  const tar = await runSsh(profile, "tar", ["--version"], { signal, remoteCwd: "" });
+  const sha256 = await runSsh(profile, "sha256sum", ["--version"], { signal, remoteCwd: "" });
+  const terraform = await runSsh(profile, profile.terraformPath || "terraform", ["version"], { signal, remoteCwd: profile.remoteRoot });
+  const missing = [tar.code === 0 ? undefined : "tar", sha256.code === 0 ? undefined : "sha256sum", terraform.code === 0 ? undefined : "terraform", profile.identityType === "ssh-only" ? "cloud workload identity" : undefined].filter((item): item is string => Boolean(item));
+  return { ready: missing.length === 0, terraformVersion: terraform.code === 0 ? terraform.stdout.split(/\r?\n/u)[0]?.trim() : undefined, missing };
+}