@hadooppei/hwcode 0.2.4 → 1.0.0

package/.pi/extensions/workflows/cloud/runner-tools.ts

@@ -0,0 +1,129 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, relative, resolve } from "node:path";
+
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { CLOUD_RUNTIME_DEFAULTS } from "../../../lib/runtime/defaults.ts";
+import { remoteRunnerPaths, userRuntimePaths } from "../../../lib/runtime/paths.ts";
+import { prepareRemoteRunner } from "../../../lib/workflows/cloud/remote/bootstrap.ts";
+import { connectRemoteTarget } from "../../../lib/workflows/cloud/remote/connect.ts";
+import { remoteTargetSummary, type RemoteTargetProfile } from "../../../lib/workflows/cloud/remote/profiles.ts";
+import { createRemoteRunWorkspace, isTerraformSourceFile, syncRemoteWorkspace } from "../../../lib/workflows/cloud/remote/workspace.ts";
+import { truncateOutput } from "../../../lib/workflows/cloud/process.ts";
+import { assertSafeTerraformSource } from "../../../lib/workflows/cloud/terraform/policy.ts";
+import { saveRemoteTargetProfile, writeCloudVault } from "../../../lib/workflows/cloud/vault.ts";
+import type { TerraformRunState } from "../../../lib/workflows/state.ts";
+import type { CloudExtensionRuntime } from "./runtime.ts";
+import { cloudDetails, remoteTrustInteraction, terraformError, terraformOk } from "./shared.ts";
+
+export function registerCloudRunnerTools(pi: ExtensionAPI, runtime: CloudExtensionRuntime): void {
+  pi.registerTool(defineTool({
+    name: "hwcode_runner_connect", label: "HWCode Runner Connect",
+    description: "Register a newly provisioned or existing SSH host as the Terraform Runner. It uses a local default SSH key and asks before trusting a new host key.",
+    promptSnippet: "Connect the discovered temporary Runner by public address; do not ask the user to name it.",
+    parameters: Type.Object({
+      host: Type.String({ description: "Public IP address or DNS returned by the provider" }),
+      user: Type.Optional(Type.String({ description: "SSH user; defaults to ubuntu" })),
+      port: Type.Optional(Type.Integer({ description: "SSH port; defaults to 22" })),
+      keyPath: Type.Optional(Type.String({ description: "Optional local private-key path; defaults to ~/.ssh/id_ed25519 then id_rsa" })),
+      jumpHost: Type.Optional(Type.String({ description: "Optional SSH bastion host used with ProxyJump" })),
+      jumpUser: Type.Optional(Type.String({ description: "ProxyJump SSH user; defaults to the target SSH user" })),
+      jumpPort: Type.Optional(Type.Integer({ description: "ProxyJump SSH port; defaults to 22" })),
+      identityType: Type.Optional(Type.Union([Type.Literal("instance-role"), Type.Literal("agency"), Type.Literal("ssh-only")], { description: "Cloud workload identity already configured on the target; temporary managed Runners default to instance-role" })),
+    }),
+    executionMode: "sequential",
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      const activeState = runtime.restore(ctx);
+      const details = activeState && cloudDetails(activeState);
+      const blocked = runtime.blocked(activeState);
+      if (!activeState || !details || blocked) return terraformError(blocked ?? "HWCode Cloud is not active.");
+      if (!runtime.activeVault) return terraformError("HWCode Cloud credentials are locked. Run /hwcode-cloud before connecting a Runner.");
+      const home = homedir();
+      const keyPath = params.keyPath || CLOUD_RUNTIME_DEFAULTS.runner.keyCandidates.map((file) => resolve(home, ".ssh", file)).find(existsSync);
+      if (!keyPath || !existsSync(keyPath)) return terraformError("No local SSH private key was found. Pass keyPath explicitly or create ~/.ssh/id_ed25519.");
+      const user = params.user || CLOUD_RUNTIME_DEFAULTS.runner.defaultUser;
+      const port = params.port || CLOUD_RUNTIME_DEFAULTS.runner.defaultPort;
+      let profile: RemoteTargetProfile;
+      try {
+        profile = await connectRemoteTarget({
+          id: `runner-${details.vendor}-${Date.now()}`, name: `${details.vendor}-temporary-runner`, vendor: details.vendor,
+          region: runtime.activeCredentials?.region || "default", host: params.host, port, user, keyPath,
+          knownHostsPath: userRuntimePaths(home).cloudKnownHosts,
+          remoteRoot: remoteRunnerPaths(user).root,
+          identityType: params.identityType || "instance-role",
+          proxyJump: params.jumpHost ? { host: params.jumpHost, port: params.jumpPort || CLOUD_RUNTIME_DEFAULTS.runner.defaultPort, user: params.jumpUser || user } : undefined,
+        }, activeState.root, remoteTrustInteraction(ctx), signal);
+      } catch (error) { return terraformError(error instanceof Error ? error.message : String(error)); }
+      runtime.activeRunner = profile;
+      runtime.activeVault.payload = saveRemoteTargetProfile(runtime.activeVault.payload, profile);
+      writeCloudVault(runtime.activeVault.payload, runtime.activeVault.password, runtime.activeVault.path);
+      runtime.replaceDetails(activeState, { ...details, runner: remoteTargetSummary(profile) }, "connected");
+      return terraformOk(`Terraform Runner connected: ${profile.user}@${profile.host}:${profile.port}`, { runner: remoteTargetSummary(profile) });
+    },
+  }));
+
+  pi.registerTool(defineTool({
+    name: "hwcode_runner_prepare", label: "HWCode Runner",
+    description: "Check the selected remote Terraform Runner without exposing credentials.",
+    promptSnippet: "Prepare the selected remote Terraform Runner.", parameters: Type.Object({}), executionMode: "sequential",
+    async execute(_id, _params, signal, _onUpdate, ctx) {
+      const activeState = runtime.restore(ctx);
+      const blocked = runtime.blocked(activeState);
+      if (!activeState || blocked) return terraformError(blocked ?? "HWCode Cloud is not active.");
+      let runner: RemoteTargetProfile;
+      try { runner = runtime.requireRunner(activeState); } catch (error) { return terraformError(error instanceof Error ? error.message : String(error)); }
+      try {
+        const report = await prepareRemoteRunner(runner, signal);
+        if (!report.ready) {
+          const reason = `Runner is reachable but is missing required capabilities: ${report.missing.join(", ")}. Install them through provider bootstrap/cloud-init, then retry.`;
+          runtime.runnerFailure(activeState, "runner-prepare", reason);
+          return terraformError(reason);
+        }
+        return terraformOk(`Runner ${runner.name} is ready.\n${report.terraformVersion || "Terraform available"}`, { runner: remoteTargetSummary(runner), capabilities: report });
+      } catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        runtime.runnerFailure(activeState, "runner-prepare", reason);
+        return terraformError(`Runner preparation failed:\n${truncateOutput(reason)}`);
+      }
+    },
+  }));
+
+  pi.registerTool(defineTool({
+    name: "hwcode_terraform_sync", label: "HWCode Terraform Sync",
+    description: "Synchronize a project-local Terraform source directory to the selected Runner.",
+    promptSnippet: "Sync Terraform source to the remote Runner.",
+    parameters: Type.Object({ sourcePath: Type.String({ description: "Directory inside the locked project root" }) }), executionMode: "sequential",
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      const activeState = runtime.restore(ctx);
+      const blocked = runtime.blocked(activeState);
+      if (!activeState || blocked) return terraformError(blocked ?? "HWCode Cloud is not active.");
+      let runner: RemoteTargetProfile;
+      try { runner = runtime.requireRunner(activeState); } catch (error) { return terraformError(error instanceof Error ? error.message : String(error)); }
+      const sourcePath = isAbsolute(params.sourcePath) ? resolve(params.sourcePath) : resolve(activeState.root, params.sourcePath);
+      const trustedBundlePath = cloudDetails(activeState)!.terraformSourcePath ? resolve(cloudDetails(activeState)!.terraformSourcePath!) : undefined;
+      const outside = relative(activeState.root, sourcePath).startsWith("..") || isAbsolute(relative(activeState.root, sourcePath));
+      if (outside && sourcePath !== trustedBundlePath) return terraformError("Terraform sourcePath must be inside the locked project root, except for the exact selected local Deployment Template bundle.");
+      if (!existsSync(sourcePath) || !statSync(sourcePath).isDirectory()) return terraformError("Terraform sourcePath must be an existing directory.");
+      let workspace;
+      try { workspace = createRemoteRunWorkspace(sourcePath, runner.remoteRoot); }
+      catch (error) { return terraformError(`Terraform source manifest rejected this bundle:\n${error instanceof Error ? error.message : String(error)}`); }
+      const files = workspace.files.filter((file) => isTerraformSourceFile(file.relativePath)).map((file) => ({ relativePath: file.relativePath, content: readFileSync(resolve(sourcePath, file.relativePath), "utf8") }));
+      try { assertSafeTerraformSource(files, { requireRemoteBackend: true }); }
+      catch (error) { return terraformError(`Terraform source policy rejected this bundle:\n${error instanceof Error ? error.message : String(error)}`); }
+      try { await syncRemoteWorkspace(runner, sourcePath, workspace, signal); }
+      catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        runtime.runnerFailure(activeState, "terraform-runner-sync", reason);
+        return terraformError(`Terraform sync failed:\n${truncateOutput(reason)}`);
+      }
+      const run: TerraformRunState = {
+        runId: workspace.runId, runnerId: runner.id, phase: "synced", sourceDigest: workspace.sourceDigest,
+        sourcePath, remoteWorkspace: workspace.remotePath, startedAt: new Date().toISOString(), updatedAt: new Date().toISOString(),
+      };
+      runtime.replaceDetails(activeState, { ...cloudDetails(activeState)!, terraformRun: run }, "executing");
+      return terraformOk(`Terraform source synced. runId=${run.runId}\nsourceDigest=${run.sourceDigest}\nremoteWorkspace=${run.remoteWorkspace}`, { runId: run.runId, sourceDigest: run.sourceDigest });
+    },
+  }));
+}

package/.pi/extensions/workflows/cloud/runtime.ts

@@ -0,0 +1,97 @@
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type { TemporaryCredentialStore } from "../../../lib/workflows/cloud/adapters.ts";
+import { cloudExecutionBlockReason, recordStrategyFailure } from "../../../lib/workflows/cloud/execution.ts";
+import type { CloudCredentials, CloudOperation } from "../../../lib/workflows/cloud/providers.ts";
+import type { RemoteTargetProfile } from "../../../lib/workflows/cloud/remote/profiles.ts";
+import { createEmptyVault } from "../../../lib/workflows/cloud/vault.ts";
+import { CLOUD_RUNTIME_DEFAULTS } from "../../../lib/runtime/defaults.ts";
+import { updateWorkflowState, type CloudWorkflowDetails, type TerraformRunState, type WorkflowState } from "../../../lib/workflows/state.ts";
+import { appendWorkflowState, cloudDetails, restoreCloudWorkflow } from "./shared.ts";
+
+export interface ActiveCloudVault {
+  password: string;
+  payload: ReturnType<typeof createEmptyVault>;
+  path: string;
+}
+
+export class CloudExtensionRuntime {
+  readonly pi: ExtensionAPI;
+  activeState?: WorkflowState;
+  activeCredentials?: CloudCredentials;
+  activeRunner?: RemoteTargetProfile;
+  activeVault?: ActiveCloudVault;
+  readonly temporaryStore: TemporaryCredentialStore;
+  private readonly credentialDirectories = new Set<string>();
+
+  constructor(pi: ExtensionAPI) {
+    this.pi = pi;
+    this.temporaryStore = {
+      createDirectory: (prefix) => {
+        const directory = mkdtempSync(`${tmpdir()}/${prefix}`);
+        this.credentialDirectories.add(directory);
+        return directory;
+      },
+      cleanupDirectory: (directory) => {
+        if (existsSync(directory)) rmSync(directory, { recursive: true, force: true });
+        this.credentialDirectories.delete(directory);
+      },
+    };
+  }
+
+  restore(ctx: ExtensionContext): WorkflowState | undefined {
+    this.activeState = restoreCloudWorkflow(ctx);
+    return this.activeState;
+  }
+
+  cleanupCredentialDirectories(): void {
+    for (const directory of [...this.credentialDirectories]) this.temporaryStore.cleanupDirectory(directory);
+  }
+
+  clearSecrets(): void {
+    this.activeCredentials = undefined;
+    this.activeRunner = undefined;
+    this.activeVault = undefined;
+    this.cleanupCredentialDirectories();
+  }
+
+  replaceDetails(state: WorkflowState, details: CloudWorkflowDetails, phase = state.phase): WorkflowState {
+    const updated = updateWorkflowState(state, { details, phase });
+    this.activeState = updated;
+    appendWorkflowState(this.pi, updated);
+    return updated;
+  }
+
+  terraformRun(state: WorkflowState): TerraformRunState | undefined {
+    return cloudDetails(state)?.terraformRun;
+  }
+
+  recordTerraformSuccess(state: WorkflowState, args: string[], operation: CloudOperation, intent: string, approach: string): WorkflowState {
+    const details = cloudDetails(state)!;
+    const successfulSteps = [...details.successfulSteps, {
+      command: "terraform", args, operation, intent, approach, completedAt: new Date().toISOString(),
+    }].slice(-CLOUD_RUNTIME_DEFAULTS.workflow.maxSuccessfulSteps);
+    return this.replaceDetails(state, { ...details, successfulSteps }, "executing");
+  }
+
+  runnerFailure(state: WorkflowState, stage: string, reason: string): void {
+    const details = cloudDetails(state);
+    if (!details) return;
+    const failed = recordStrategyFailure(details, "terraform-runner", stage, reason, CLOUD_RUNTIME_DEFAULTS.workflow.maxFailedApproaches);
+    const terraformRun = details.terraformRun ? { ...details.terraformRun, phase: "failed" as const, updatedAt: new Date().toISOString() } : undefined;
+    this.replaceDetails(state, { ...failed, ...(terraformRun ? { terraformRun } : {}) }, failed.terminalFailure ? "failed" : "executing");
+  }
+
+  blocked(state: WorkflowState | undefined): string | undefined {
+    return cloudExecutionBlockReason(state);
+  }
+
+  requireRunner(state: WorkflowState): RemoteTargetProfile {
+    if (!this.activeRunner) throw new Error("No Terraform Runner is connected yet. Provision the temporary Runner for this workflow, then register its SSH endpoint before Terraform execution.");
+    if (this.activeRunner.id !== cloudDetails(state)?.runner?.id) throw new Error("The selected Terraform Runner does not match this Cloud workflow.");
+    return this.activeRunner;
+  }
+}

package/.pi/extensions/workflows/cloud/shared.ts

@@ -0,0 +1,213 @@
+import { readFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { CURSOR_MARKER, Input, type Component, type TUI } from "@earendil-works/pi-tui";
+
+import { isCloudRunWorkspace } from "../../../lib/workflows/cloud/workspace.ts";
+import { type RemoteTrustInteraction } from "../../../lib/workflows/cloud/remote/connect.ts";
+import { getCloudProvider, CLOUD_PROVIDERS, redactCredentialValues, type CloudCredentials, type CloudOperation, type CloudVendorId } from "../../../lib/workflows/cloud/providers.ts";
+import {
+  cloudVaultExists, createEmptyVault, defaultCloudVaultPath, readCloudVault,
+} from "../../../lib/workflows/cloud/vault.ts";
+import { WORKFLOW_STATE_TYPE, activeWorkflow, type CloudWorkflowDetails, type WorkflowState } from "../../../lib/workflows/state.ts";
+
+export const CLOUD_AUDIT_TYPE = "hwcode-cloud-audit";
+export const ORCHESTRATION_COMMANDS = new Set(["terraform", "tofu", "pulumi", "kubectl", "helm"]);
+export const SENSITIVE_ARGUMENT = /^--?(?:access[-_]?key|secret(?:[-_]?(?:access|key))?|client[-_]?secret|password|credential|token)(?:=|$)/iu;
+const LEGACY_CLOUD_STATE_TYPE = "hwcode-cloud-state";
+
+interface LegacyCloudWorkflowState {
+  version: 1;
+  active: true;
+  root: string;
+  vendor: CloudVendorId;
+  deployCurrentProject: boolean;
+  request: string;
+  allowNonDeleteChanges: boolean;
+  failedApproaches: CloudWorkflowDetails["failedApproaches"];
+  terminalFailure: boolean;
+  activatedAt: string;
+}
+
+class MaskedInput implements Component {
+  private readonly input = new Input();
+  private _focused = true;
+  private readonly tui: TUI;
+  private readonly theme: Theme;
+  private readonly title: string;
+
+  constructor(
+    tui: TUI,
+    theme: Theme,
+    title: string,
+    done: (value: string | undefined) => void,
+  ) {
+    this.tui = tui;
+    this.theme = theme;
+    this.title = title;
+    this.input.onSubmit = (value) => done(value);
+    this.input.onEscape = () => done(undefined);
+    this.input.focused = true;
+  }
+
+  get focused(): boolean { return this._focused; }
+  set focused(value: boolean) { this._focused = value; this.input.focused = value; }
+  handleInput(data: string): void { this.input.handleInput(data); this.tui.requestRender(); }
+  invalidate(): void { this.input.invalidate(); }
+  render(width: number): string[] {
+    const masked = "•".repeat(Math.min(Array.from(this.input.getValue()).length, Math.max(1, width - 1)));
+    return [this.theme.fg("accent", this.title), `${masked}${CURSOR_MARKER}`, this.theme.fg("dim", "Enter 确认 · Esc 取消 · 输入内容不会显示")];
+  }
+}
+
+export function notify(ctx: ExtensionContext, message: string, level: "info" | "warning" | "error" = "info"): void {
+  if (ctx.hasUI) ctx.ui.notify(message, level);
+}
+
+export function cloudDetails(state: WorkflowState): CloudWorkflowDetails | undefined {
+  return state.mode === "cloud" ? state.details : undefined;
+}
+
+export function cloudArtifactDirectory(state: WorkflowState): string {
+  const path = cloudDetails(state)?.artifactDirectory;
+  return path && isCloudRunWorkspace(state.root, path) ? path : state.root;
+}
+
+export function formatTemplateTime(value: string): string {
+  const date = new Date(value);
+  if (Number.isNaN(date.valueOf())) return value;
+  const pad = (part: number) => String(part).padStart(2, "0");
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}
+
+export function restoreCloudWorkflow(ctx: ExtensionContext): WorkflowState | undefined {
+  const state = activeWorkflow(ctx.sessionManager.getEntries());
+  return state?.mode === "cloud" && state.details ? state : undefined;
+}
+
+function decodeLegacyCloudState(value: unknown): LegacyCloudWorkflowState | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const data = value as Record<string, unknown>;
+  if (data.version !== 1 || data.active !== true || typeof data.root !== "string"
+    || typeof data.vendor !== "string" || !CLOUD_PROVIDERS.some((provider) => provider.id === data.vendor)
+    || typeof data.deployCurrentProject !== "boolean" || typeof data.request !== "string"
+    || typeof data.allowNonDeleteChanges !== "boolean" || !Array.isArray(data.failedApproaches)
+    || typeof data.terminalFailure !== "boolean" || typeof data.activatedAt !== "string") return undefined;
+  return data as unknown as LegacyCloudWorkflowState;
+}
+
+export function restoreLegacyCloudWorkflow(ctx: ExtensionContext): WorkflowState | undefined {
+  for (const entry of [...ctx.sessionManager.getEntries()].reverse()) {
+    if (entry.type !== "custom" || entry.customType !== LEGACY_CLOUD_STATE_TYPE) continue;
+    const legacy = decodeLegacyCloudState(entry.data);
+    if (!legacy) return undefined;
+    return {
+      version: 2, status: "active", mode: "cloud", root: legacy.root,
+      phase: legacy.terminalFailure ? "failed" : "connected",
+      activatedAt: legacy.activatedAt, updatedAt: legacy.activatedAt,
+      details: {
+        vendor: legacy.vendor, deployCurrentProject: legacy.deployCurrentProject,
+        request: legacy.request, allowNonDeleteChanges: legacy.allowNonDeleteChanges,
+        failedApproaches: legacy.failedApproaches, successfulSteps: [], terminalFailure: legacy.terminalFailure,
+      },
+    };
+  }
+  return undefined;
+}
+
+export function appendWorkflowState(pi: ExtensionAPI, state: WorkflowState): void {
+  pi.appendEntry<WorkflowState>(WORKFLOW_STATE_TYPE, state);
+}
+
+async function secretInput(ctx: ExtensionContext, title: string): Promise<string | undefined> {
+  if (ctx.mode !== "tui") return undefined;
+  return ctx.ui.custom<string | undefined>((tui, theme, _keybindings, done) => new MaskedInput(tui, theme, title, done));
+}
+
+export async function unlockVault(ctx: ExtensionCommandContext): Promise<{ password: string; payload: ReturnType<typeof createEmptyVault> } | undefined> {
+  const vaultPath = defaultCloudVaultPath();
+  if (!cloudVaultExists(vaultPath)) {
+    while (true) {
+      const password = await secretInput(ctx, "创建云凭据主密码（至少 8 个字符）");
+      if (password === undefined) return undefined;
+      if (password.length < 8) { notify(ctx, "主密码至少需要 8 个字符。", "warning"); continue; }
+      const confirmation = await secretInput(ctx, "再次输入主密码");
+      if (confirmation === undefined) return undefined;
+      if (confirmation !== password) { notify(ctx, "两次输入的主密码不一致。", "warning"); continue; }
+      return { password, payload: createEmptyVault() };
+    }
+  }
+  while (true) {
+    const password = await secretInput(ctx, "输入云凭据主密码以解锁");
+    if (password === undefined) return undefined;
+    try { return { password, payload: readCloudVault(password, vaultPath) }; }
+    catch (error) {
+      notify(ctx, error instanceof Error ? error.message : String(error), "error");
+      if (!(await ctx.ui.confirm("重新输入主密码？", "凭据未解锁，HWCode Cloud 尚未启动。"))) return undefined;
+    }
+  }
+}
+
+export async function collectCredentials(vendor: CloudVendorId, root: string, ctx: ExtensionCommandContext): Promise<CloudCredentials | undefined> {
+  const credentials: CloudCredentials = {};
+  for (const field of getCloudProvider(vendor).credentialFields) {
+    let value = field.secret ? await secretInput(ctx, field.label) : await ctx.ui.input(field.label, field.placeholder);
+    if (value === undefined) return undefined;
+    value = value.trim();
+    if (!value && !field.optional) { notify(ctx, `${field.label} 不能为空。`, "warning"); return collectCredentials(vendor, root, ctx); }
+    if (!value) continue;
+    if (field.fileContents) {
+      const path = isAbsolute(value) ? value : resolve(root, value);
+      try { const contents = readFileSync(path, "utf8"); JSON.parse(contents); credentials[field.key] = contents; }
+      catch (error) {
+        notify(ctx, `无法读取有效的 JSON 凭据文件 ${path}: ${error instanceof Error ? error.message : String(error)}`, "error");
+        return collectCredentials(vendor, root, ctx);
+      }
+    } else credentials[field.key] = value;
+  }
+  if (vendor === "gcp") {
+    const account = JSON.parse(credentials.serviceAccountJson) as Record<string, unknown>;
+    credentials.projectId ||= typeof account.project_id === "string" ? account.project_id : "";
+    if (!credentials.projectId) { notify(ctx, "Service Account JSON 中没有 project_id，请重新输入。", "error"); return collectCredentials(vendor, root, ctx); }
+  }
+  return credentials;
+}
+
+export function activationPrompt(state: WorkflowState): string {
+  const details = cloudDetails(state)!;
+  const guidance = details.templateGuidance
+    ? `\n\nReusable template guidance (${details.sourceTemplate?.name ?? "saved template"}):\n${details.templateGuidance}`
+    : "";
+  const runner = details.runner?.name ?? (details.runnerPreference === "automatic" ? "automatic temporary Runner requested" : "not selected");
+  return `/skill:hwcode-cloud HWCode Cloud workflow activated.\n\nLocked project root: ${state.root}\nTask artifact workspace: ${cloudArtifactDirectory(state)}\nCloud provider: ${getCloudProvider(details.vendor).label}\nTerraform Runner: ${runner}\nDeploy current project: ${details.deployCurrentProject ? "yes" : "no"}\nUser objective:\n${details.request}${guidance}\n\nCredentials were validated and remain outside model context. Use hwcode_cloud_exec for provider CLI operations. If no Runner is selected and Terraform is required, first present the temporary Runner architecture and obtain approval to create its billable cloud resources; then use the configured Runner tools for Terraform execution.`;
+}
+
+export async function approveOperation(operation: CloudOperation, params: { command: string; args: string[]; intent: string }, state: WorkflowState, ctx: ExtensionContext): Promise<"allow" | "allow-session" | "deny"> {
+  if (operation === "read") return "allow";
+  if (!ctx.hasUI) return "deny";
+  const details = cloudDetails(state)!;
+  const command = `${params.command} ${params.args.join(" ")}`;
+  if (operation === "delete") return await ctx.ui.confirm("确认删除云资源？", `目标：${params.intent}\n命令：${command}\n\n删除操作始终逐次确认。`) ? "allow" : "deny";
+  if (details.allowNonDeleteChanges) return "allow";
+  const choice = await ctx.ui.select("允许修改云账号内资源？", ["仅允许本次", "允许本会话后续非删除变更，不再询问", "拒绝"]);
+  if (choice === "仅允许本次") return "allow";
+  if (choice === "允许本会话后续非删除变更，不再询问") return "allow-session";
+  return "deny";
+}
+
+export function remoteTrustInteraction(ctx: ExtensionContext): RemoteTrustInteraction {
+  return {
+    confirm: async (host, port, keys, role) => ctx.hasUI && ctx.ui.confirm(
+      role === "jump" ? "信任 SSH 跳板机主机密钥？" : "信任 Terraform Runner 主机密钥？",
+      `主机：${host}:${port}\n${keys.map((key) => `${key.algorithm} ${key.fingerprint}`).join("\n")}\n\n请仅在指纹与云控制台或可信运维记录一致时确认。`,
+    ),
+  };
+}
+
+export function safeStepText(value: string, credentials: CloudCredentials): string {
+  return redactCredentialValues(value.replace(/[\r\n]+/gu, " ").slice(0, 2_000), credentials);
+}
+
+export const terraformError = (message: string) => ({ content: [{ type: "text" as const, text: message }], isError: true, details: {} });
+export const terraformOk = (message: string, details: Record<string, unknown> = {}) => ({ content: [{ type: "text" as const, text: message }], details });

package/.pi/extensions/workflows/cloud/terraform-tools.ts

@@ -0,0 +1,126 @@
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { CLOUD_RUNTIME_DEFAULTS } from "../../../lib/runtime/defaults.ts";
+import type { CloudOperation } from "../../../lib/workflows/cloud/providers.ts";
+import type { RemoteTargetProfile } from "../../../lib/workflows/cloud/remote/profiles.ts";
+import {
+  classifyTerraformPlan, summarizeTerraformState, terraformPlanHasDeletion,
+  terraformPlanRequiresApproval, terraformPlanSummaryText,
+} from "../../../lib/workflows/cloud/terraform/plan.ts";
+import { digestTerraformPlan, executeTerraformRunner } from "../../../lib/workflows/cloud/terraform/runner.ts";
+import { cloudExecutionBlockReason } from "../../../lib/workflows/cloud/execution.ts";
+import { truncateOutput } from "../../../lib/workflows/cloud/process.ts";
+import type { CloudExtensionRuntime } from "./runtime.ts";
+import { approveOperation, cloudDetails, terraformError, terraformOk } from "./shared.ts";
+
+const PLAN_FILE = CLOUD_RUNTIME_DEFAULTS.terraform.planFile;
+
+export function registerCloudTerraformTools(pi: ExtensionAPI, runtime: CloudExtensionRuntime): void {
+  pi.registerTool(defineTool({
+    name: "hwcode_terraform_validate", label: "HWCode Terraform Validate",
+    description: "Run fmt, init, validate, and test on the remote Terraform Runner.",
+    promptSnippet: "Validate the synchronized Terraform bundle remotely.",
+    parameters: Type.Object({ runId: Type.String() }), executionMode: "sequential",
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      const activeState = runtime.restore(ctx);
+      const blocked = runtime.blocked(activeState);
+      if (!activeState || blocked) return terraformError(blocked ?? "HWCode Cloud is not active.");
+      const run = runtime.terraformRun(activeState);
+      if (!run || run.runId !== params.runId || run.phase !== "synced") return terraformError("Terraform validate requires a newly synced run.");
+      let runner: RemoteTargetProfile;
+      try { runner = runtime.requireRunner(activeState); } catch (error) { return terraformError(error instanceof Error ? error.message : String(error)); }
+      for (const action of ["fmt", "init", "validate", "test"] as const) {
+        const result = await executeTerraformRunner(runner, { action, workspace: run.remoteWorkspace }, { signal });
+        if (result.code !== 0) {
+          runtime.runnerFailure(activeState, `terraform-${action}`, result.stderr || result.stdout || `exit code ${result.code}`);
+          return terraformError(`terraform ${action} failed:\n${truncateOutput(result.stderr || result.stdout)}`);
+        }
+      }
+      runtime.replaceDetails(activeState, { ...cloudDetails(activeState)!, terraformRun: { ...run, phase: "validated", updatedAt: new Date().toISOString() } }, "executing");
+      runtime.recordTerraformSuccess(runtime.activeState!, ["fmt", "init", "validate", "test"], "read", "Validate Terraform source and tests", "terraform-runner");
+      return terraformOk("Terraform fmt/init/validate/test completed successfully.", { runId: run.runId });
+    },
+  }));
+
+  pi.registerTool(defineTool({
+    name: "hwcode_terraform_plan", label: "HWCode Terraform Plan",
+    description: "Create and inspect a JSON Terraform plan on the remote Runner.",
+    promptSnippet: "Create a Terraform plan and report exact resource changes.",
+    parameters: Type.Object({ runId: Type.String(), mode: Type.Union([Type.Literal("normal"), Type.Literal("destroy"), Type.Literal("refresh-only")]) }), executionMode: "sequential",
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      const activeState = runtime.restore(ctx);
+      const blocked = runtime.blocked(activeState);
+      if (!activeState || blocked) return terraformError(blocked ?? "HWCode Cloud is not active.");
+      const run = runtime.terraformRun(activeState);
+      if (!run || run.runId !== params.runId || run.phase !== "validated") return terraformError("Terraform plan requires a validated run.");
+      let runner: RemoteTargetProfile;
+      try { runner = runtime.requireRunner(activeState); } catch (error) { return terraformError(error instanceof Error ? error.message : String(error)); }
+      const planned = await executeTerraformRunner(runner, { action: "plan", workspace: run.remoteWorkspace, mode: params.mode }, { signal });
+      if (planned.code !== 0) { runtime.runnerFailure(activeState, `terraform-plan-${params.mode}`, planned.stderr || planned.stdout || `exit code ${planned.code}`); return terraformError(`terraform plan failed:\n${truncateOutput(planned.stderr || planned.stdout)}`); }
+      const inspected = await executeTerraformRunner(runner, { action: "show-plan", workspace: run.remoteWorkspace, planPath: PLAN_FILE }, { signal });
+      if (inspected.code !== 0) { runtime.runnerFailure(activeState, "terraform-show-plan", inspected.stderr || inspected.stdout); return terraformError(`terraform show plan failed:\n${truncateOutput(inspected.stderr || inspected.stdout)}`); }
+      let summary;
+      try { summary = classifyTerraformPlan(JSON.parse(inspected.stdout)); }
+      catch (error) { const reason = error instanceof Error ? error.message : String(error); runtime.runnerFailure(activeState, "terraform-parse-plan", reason); return terraformError(`Unable to parse Terraform plan JSON: ${reason}`); }
+      const planDigest = digestTerraformPlan(inspected.stdout);
+      runtime.replaceDetails(activeState, { ...cloudDetails(activeState)!, terraformRun: { ...run, phase: "planned", planDigest, planSummary: summary, updatedAt: new Date().toISOString() } }, "executing");
+      runtime.recordTerraformSuccess(runtime.activeState!, ["plan", params.mode], "read", `Create reviewed Terraform ${params.mode} plan`, "terraform-runner");
+      return terraformOk(`${terraformPlanSummaryText(summary)}\nplanDigest=${planDigest}`, { runId: run.runId, planDigest, requiresApproval: terraformPlanRequiresApproval(summary), hasDeletion: terraformPlanHasDeletion(summary), summary });
+    },
+  }));
+
+  pi.registerTool(defineTool({
+    name: "hwcode_terraform_apply", label: "HWCode Terraform Apply",
+    description: "Apply only the exact approved Terraform plan on the remote Runner.",
+    promptSnippet: "Apply the reviewed Terraform plan after approval.",
+    parameters: Type.Object({ runId: Type.String(), planDigest: Type.String(), intent: Type.String() }), executionMode: "sequential",
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      let activeState = runtime.restore(ctx);
+      const blocked = runtime.blocked(activeState);
+      if (!activeState || blocked) return terraformError(blocked ?? "HWCode Cloud is not active.");
+      const run = runtime.terraformRun(activeState);
+      if (!run || run.runId !== params.runId || run.phase !== "planned" || run.planDigest !== params.planDigest) return terraformError("Plan digest mismatch or no planned run is ready. Re-plan before apply.");
+      let runner: RemoteTargetProfile;
+      try { runner = runtime.requireRunner(activeState); } catch (error) { return terraformError(error instanceof Error ? error.message : String(error)); }
+      const currentPlan = await executeTerraformRunner(runner, { action: "show-plan", workspace: run.remoteWorkspace, planPath: PLAN_FILE }, { signal });
+      if (currentPlan.code !== 0) { runtime.runnerFailure(activeState, "terraform-reverify-plan", currentPlan.stderr || currentPlan.stdout); return terraformError(`Unable to re-verify the managed Terraform plan:\n${truncateOutput(currentPlan.stderr || currentPlan.stdout)}`); }
+      const currentDigest = digestTerraformPlan(currentPlan.stdout);
+      if (currentDigest !== run.planDigest || currentDigest !== params.planDigest) { runtime.runnerFailure(activeState, "terraform-plan-integrity", "remote plan digest changed after review"); return terraformError("The remote Terraform plan changed after review. Apply is blocked; create and review a new plan."); }
+      let currentSummary;
+      try { currentSummary = classifyTerraformPlan(JSON.parse(currentPlan.stdout)); }
+      catch (error) { const reason = error instanceof Error ? error.message : String(error); runtime.runnerFailure(activeState, "terraform-parse-current-plan", reason); return terraformError(`Unable to parse the current Terraform plan: ${reason}`); }
+      const operation: CloudOperation = terraformPlanHasDeletion(currentSummary) ? "delete" : terraformPlanRequiresApproval(currentSummary) ? "change" : "read";
+      const approval = await approveOperation(operation, { command: "terraform", args: ["apply", PLAN_FILE], intent: params.intent }, activeState, ctx);
+      if (approval === "deny") return terraformError("User denied Terraform apply.");
+      if (approval === "allow-session") activeState = runtime.replaceDetails(activeState, { ...cloudDetails(activeState)!, allowNonDeleteChanges: true });
+      const result = await executeTerraformRunner(runner, { action: "apply", workspace: run.remoteWorkspace, planPath: PLAN_FILE }, { signal });
+      if (result.code !== 0) { runtime.runnerFailure(activeState, "terraform-apply", result.stderr || result.stdout || `exit code ${result.code}`); return terraformError(`terraform apply failed:\n${truncateOutput(result.stderr || result.stdout)}`); }
+      runtime.replaceDetails(activeState, { ...cloudDetails(activeState)!, terraformRun: { ...run, phase: "applied", planSummary: currentSummary, updatedAt: new Date().toISOString() } }, "executing");
+      runtime.recordTerraformSuccess(runtime.activeState!, ["apply", PLAN_FILE], operation, params.intent, "terraform-runner");
+      return terraformOk(`Terraform apply completed.\n${truncateOutput(result.stdout).trim()}`, { runId: run.runId, planDigest: params.planDigest });
+    },
+  }));
+
+  pi.registerTool(defineTool({
+    name: "hwcode_terraform_status", label: "HWCode Terraform Status",
+    description: "Read remote Terraform state for the active managed run.",
+    promptSnippet: "Inspect the current remote Terraform state.",
+    parameters: Type.Object({ runId: Type.String() }), executionMode: "sequential",
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      const activeState = runtime.restore(ctx);
+      const blocked = cloudExecutionBlockReason(activeState, { allowAfterTerminalFailure: true });
+      if (!activeState || blocked) return terraformError(blocked ?? "HWCode Cloud is not active.");
+      const run = runtime.terraformRun(activeState);
+      if (!run || run.runId !== params.runId || !["planned", "applied"].includes(run.phase)) return terraformError("Terraform status requires a planned or applied run.");
+      let runner: RemoteTargetProfile;
+      try { runner = runtime.requireRunner(activeState); } catch (error) { return terraformError(error instanceof Error ? error.message : String(error)); }
+      const result = await executeTerraformRunner(runner, { action: "show-state", workspace: run.remoteWorkspace }, { signal });
+      if (result.code !== 0) { runtime.runnerFailure(activeState, "terraform-state", result.stderr || result.stdout); return terraformError(`terraform state inspection failed:\n${truncateOutput(result.stderr || result.stdout)}`); }
+      let summary;
+      try { summary = summarizeTerraformState(JSON.parse(result.stdout)); }
+      catch (error) { return terraformError(`Unable to summarize Terraform state safely: ${error instanceof Error ? error.message : String(error)}`); }
+      return terraformOk(`Terraform state contains ${summary.resourceCount} managed resources.\n${Object.entries(summary.resourceTypes).map(([type, count]) => `${type}: ${count}`).join("\n") || "No managed resources."}`, { runId: run.runId, summary });
+    },
+  }));
+}