@hadooppei/hwcode 0.2.1 → 1.0.0

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

@@ -0,0 +1,256 @@
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+
+import { getCloudProvider, isCloudVendorId, type CloudVendorId } from "./providers.ts";
+import type { CloudTemplateSource, WorkflowState } from "../state.ts";
+import { legacyUserCloudTemplatePaths, userRuntimePaths } from "../../runtime/paths.ts";
+import { CLOUD_RUNTIME_DEFAULTS } from "../../runtime/defaults.ts";
+
+export interface CloudPromptTemplate {
+  id: string;
+  name: string;
+  description: string;
+  createdAt: string;
+  updatedAt: string;
+  vendor: CloudVendorId;
+  deployCurrentProject: boolean;
+  objective: string;
+  notes: string;
+  body: string;
+  path: string;
+}
+
+export function cloudPromptTemplateSource(template: CloudPromptTemplate): CloudTemplateSource {
+  return {
+    id: template.id,
+    name: template.name,
+    createdAt: template.createdAt,
+    updatedAt: template.updatedAt,
+    kind: "prompt",
+  };
+}
+
+export function defaultCloudPromptDirectory(home = homedir()): string {
+  return userRuntimePaths(home).cloudPromptTemplates;
+}
+
+function slugify(value: string): string {
+  const slug = value
+    .normalize("NFKD")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/gu, "-")
+    .replace(/^-+|-+$/gu, "")
+    .slice(0, CLOUD_RUNTIME_DEFAULTS.templates.slugMaxLength);
+  return slug || `task-${new Date().toISOString().slice(0, 10)}`;
+}
+
+function frontmatterValue(text: string, key: string): string | undefined {
+  const line = text.match(new RegExp(`^${key}:\\s*(.+)$`, "mu"))?.[1]?.trim();
+  if (!line) return undefined;
+  try {
+    const value = JSON.parse(line) as unknown;
+    return typeof value === "string" ? value : String(value);
+  } catch {
+    return line.replace(/^['"]|['"]$/gu, "");
+  }
+}
+
+function normalizeTimestamp(value: string | undefined, fallback: string): string {
+  if (!value) return fallback;
+  const date = new Date(value);
+  return Number.isNaN(date.valueOf()) ? fallback : date.toISOString();
+}
+
+function legacyTemplateName(id: string): string {
+  const words = id.replace(/^hwcloud-/u, "").split("-").filter(Boolean);
+  if (words.length === 0) return "Legacy Cloud Template";
+  return words.map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+
+function cleanTemplateName(value: string): string {
+  return value.replace(/[\r\n]+/gu, " ").replace(/\s+/gu, " ").trim().slice(0, CLOUD_RUNTIME_DEFAULTS.templates.nameMaxLength);
+}
+
+export function parseCloudPromptTemplate(path: string): CloudPromptTemplate | undefined {
+  const text = readFileSync(path, "utf8");
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/u);
+  if (!match) return undefined;
+  const metadata = match[1];
+  const vendorValue = frontmatterValue(metadata, "hwcode-cloud-vendor");
+  if (!vendorValue || !isCloudVendorId(vendorValue)) return undefined;
+  const id = basename(path, ".md");
+  const stats = statSync(path);
+  const modifiedAt = stats.mtime.toISOString();
+  const bornAt = stats.birthtimeMs > 0 ? stats.birthtime.toISOString() : modifiedAt;
+  const name = cleanTemplateName(frontmatterValue(metadata, "hwcode-cloud-name") ?? "") || legacyTemplateName(id);
+  return {
+    id,
+    name,
+    description: frontmatterValue(metadata, "description") ?? name,
+    createdAt: normalizeTimestamp(frontmatterValue(metadata, "hwcode-cloud-created-at"), bornAt),
+    updatedAt: normalizeTimestamp(frontmatterValue(metadata, "hwcode-cloud-updated-at"), modifiedAt),
+    vendor: vendorValue,
+    deployCurrentProject: frontmatterValue(metadata, "hwcode-cloud-deploy") === "true",
+    objective: frontmatterValue(metadata, "hwcode-cloud-objective") ?? "",
+    notes: frontmatterValue(metadata, "hwcode-cloud-notes") ?? "",
+    body: match[2].trim(),
+    path,
+  };
+}
+
+export function listCloudPromptTemplates(
+  directory?: string,
+  home = homedir(),
+): CloudPromptTemplate[] {
+  const directories = directory
+    ? [directory]
+    : [...new Set([defaultCloudPromptDirectory(home), legacyUserCloudTemplatePaths(home).prompts])];
+  return directories
+    .filter(existsSync)
+    .flatMap((path) => readdirSync(path, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+      .map((entry) => parseCloudPromptTemplate(join(path, entry.name))))
+    .filter((template): template is CloudPromptTemplate => Boolean(template))
+    .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt) || left.name.localeCompare(right.name));
+}
+
+export function expandCloudPromptTemplate(template: CloudPromptTemplate, argumentsText: string): string {
+  const value = argumentsText.trim();
+  return template.body.replace(/\$\{@:-([^}]*)\}/gu, (_match, fallback: string) => value || fallback);
+}
+
+function inlineCode(value: string): string {
+  return value.replace(/[\r\n]+/gu, " ").replaceAll("`", "\\`");
+}
+
+function singleLine(value: string): string {
+  return value.replace(/[\r\n]+/gu, " ").replace(/\s+/gu, " ").trim();
+}
+
+export function renderCloudPromptTemplate(state: WorkflowState, notes = ""): string {
+  if (state.mode !== "cloud" || !state.details) throw new Error("Cloud workflow state is required");
+  const details = state.details;
+  if (details.successfulSteps.length === 0) {
+    throw new Error("No successful Cloud execution steps are available to summarize");
+  }
+  const provider = getCloudProvider(details.vendor);
+  const steps = details.successfulSteps.map((step, index) => (
+    `${index + 1}. [${step.operation}] ${singleLine(step.intent)}\n`
+      + `   - Validated approach: ${singleLine(step.approach)}\n`
+      + `   - Known-good command and path: \`${inlineCode([step.command, ...step.args].join(" "))}\``
+  )).join("\n");
+  const failedPaths = details.failedApproaches.length > 0
+    ? details.failedApproaches.map((failure, index) => (
+      `${index + 1}. **DO NOT RETRY:** ${singleLine(failure.approach)}\n`
+        + `   - Recorded failure: ${singleLine(failure.reason)}`
+    )).join("\n")
+    : "No failed execution paths were recorded for this run.";
+  return [
+    "Execute this HWCode Cloud task from a layered record of a previously successful run.",
+    "",
+    "## Layer 1 — Stable intent and boundaries",
+    "",
+    `Preferred provider: ${provider.label}`,
+    `Deploy current project: ${details.deployCurrentProject ? "yes" : "no"}`,
+    `Objective pattern: ${details.request}`,
+    "",
+    "Preserve the objective, provider boundary, credential isolation, resource approvals, and deletion confirmations. Adapt only environment-specific values.",
+    "",
+    "## Layer 2 — Preconditions and operator knowledge",
+    "",
+    "Start with read-only discovery. Re-check the active account, region, project, resource state, tool versions, and workspace paths before making changes.",
+    ...(notes ? ["", "Validated prerequisites, lessons, and expensive pitfalls:", notes] : []),
+    "",
+    "## Layer 3 — Preferred validated execution path",
+    "",
+    "Use this path first and preserve its order unless read-only evidence requires an adaptation. The commands and paths below are the known-good reference; do not replace them with speculative alternatives.",
+    "",
+    steps,
+    "",
+    "## Layer 4 — Expensive failed paths to avoid",
+    "",
+    "Do not retry any path below, including renamed or parameter-only variants. Reconsider one only when the user explicitly directs it after reviewing the recorded failure.",
+    "",
+    failedPaths,
+    "",
+    "## Layer 5 — Execution contract",
+    "",
+    "Present the adapted plan and obtain all normal HWCode Cloud approvals. Never copy credentials, assume old resources still exist, or skip current-state verification.",
+    "If HWCode Cloud is not active, do not run cloud commands directly; ask the user to start this template through /hwcode-cloud-template.",
+    "",
+    "Additional instructions: ${@:-Use the objective and successful sequence above.}",
+  ].join("\n");
+}
+
+function renderTemplateFile(
+  name: string,
+  state: WorkflowState,
+  notes: string,
+  createdAt: string,
+  updatedAt: string,
+): string {
+  if (state.mode !== "cloud" || !state.details) throw new Error("Cloud workflow state is required");
+  const body = renderCloudPromptTemplate(state, notes);
+  return [
+    "---",
+    `description: ${JSON.stringify(name)}`,
+    'argument-hint: "[additional instructions]"',
+    `hwcode-cloud-name: ${JSON.stringify(name)}`,
+    `hwcode-cloud-created-at: ${JSON.stringify(createdAt)}`,
+    `hwcode-cloud-updated-at: ${JSON.stringify(updatedAt)}`,
+    `hwcode-cloud-vendor: ${JSON.stringify(state.details.vendor)}`,
+    `hwcode-cloud-deploy: ${state.details.deployCurrentProject}`,
+    `hwcode-cloud-objective: ${JSON.stringify(state.details.request)}`,
+    `hwcode-cloud-notes: ${JSON.stringify(notes)}`,
+    "---",
+    body,
+    "",
+  ].join("\n");
+}
+
+function writeTemplateFile(path: string, content: string): void {
+  const directory = dirname(path);
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  chmodSync(directory, 0o700);
+  const temporaryPath = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporaryPath, content, { encoding: "utf8", mode: 0o600 });
+  chmodSync(temporaryPath, 0o600);
+  renameSync(temporaryPath, path);
+  chmodSync(path, 0o600);
+}
+
+export function saveCloudPromptTemplate(
+  requestedName: string,
+  state: WorkflowState,
+  directory = defaultCloudPromptDirectory(),
+  notes = "",
+  savedAt = new Date(),
+): CloudPromptTemplate {
+  if (state.mode !== "cloud" || !state.details) throw new Error("Cloud workflow state is required");
+  const name = cleanTemplateName(requestedName);
+  if (!name) throw new Error("Cloud Prompt Template name is required");
+  const idBase = `hwcloud-${slugify(name)}`;
+  const timestamp = savedAt.toISOString();
+  const content = renderTemplateFile(name, state, notes, timestamp, timestamp);
+  let id = idBase;
+  let path = join(directory, `${id}.md`);
+  for (let suffix = 2; existsSync(path); suffix++) {
+    id = `${idBase}-${suffix}`;
+    path = join(directory, `${id}.md`);
+  }
+  writeTemplateFile(path, content);
+  return parseCloudPromptTemplate(path)!;
+}
+
+export function updateCloudPromptTemplate(
+  template: CloudPromptTemplate,
+  state: WorkflowState,
+  notes = template.notes,
+  updatedAt = new Date(),
+): CloudPromptTemplate {
+  const timestamp = updatedAt.toISOString();
+  const content = renderTemplateFile(template.name, state, notes, template.createdAt, timestamp);
+  writeTemplateFile(template.path, content);
+  return parseCloudPromptTemplate(template.path)!;
+}

package/.pi/lib/workflows/cloud/terraform/plan.ts

@@ -0,0 +1,109 @@
+export type TerraformPlanAction = "no-op" | "read" | "create" | "update" | "delete" | "replace";
+
+export interface TerraformResourceChange {
+  address: string;
+  providerName?: string;
+  actions: TerraformPlanAction[];
+  sensitive: boolean;
+}
+
+export interface TerraformPlanSummary {
+  create: number;
+  update: number;
+  delete: number;
+  replace: number;
+  read: number;
+  noOp: number;
+  sensitiveChangesHidden: number;
+  resources: TerraformResourceChange[];
+}
+
+function classifyActions(actions: readonly string[]): TerraformPlanAction {
+  if (actions.includes("delete") && actions.includes("create")) return "replace";
+  if (actions.includes("create")) return "create";
+  if (actions.includes("update")) return "update";
+  if (actions.includes("delete")) return "delete";
+  if (actions.includes("read")) return "read";
+  return "no-op";
+}
+
+export function classifyTerraformPlan(value: unknown): TerraformPlanSummary {
+  if (!value || typeof value !== "object") throw new Error("invalid Terraform plan JSON");
+  const data = value as Record<string, unknown>;
+  if (!Array.isArray(data.resource_changes)) throw new Error("Terraform plan JSON has no resource_changes");
+  const resources: TerraformResourceChange[] = [];
+  for (const entry of data.resource_changes) {
+    if (!entry || typeof entry !== "object") continue;
+    const resource = entry as Record<string, unknown>;
+    if (typeof resource.address !== "string" || !resource.change || typeof resource.change !== "object") continue;
+    const change = resource.change as Record<string, unknown>;
+    if (!Array.isArray(change.actions) || change.actions.some((action) => typeof action !== "string")) continue;
+    const action = classifyActions(change.actions as string[]);
+    const sensitive = Boolean(change.after_sensitive) || Boolean(change.before_sensitive);
+    resources.push({
+      address: resource.address,
+      providerName: typeof resource.provider_name === "string" ? resource.provider_name : undefined,
+      actions: [action],
+      sensitive,
+    });
+  }
+  const summary: TerraformPlanSummary = {
+    create: resources.filter((resource) => resource.actions.includes("create") && !resource.actions.includes("replace")).length,
+    update: resources.filter((resource) => resource.actions.includes("update")).length,
+    delete: resources.filter((resource) => resource.actions.includes("delete")).length,
+    replace: resources.filter((resource) => resource.actions.includes("replace")).length,
+    read: resources.filter((resource) => resource.actions.includes("read")).length,
+    noOp: resources.filter((resource) => resource.actions.includes("no-op")).length,
+    sensitiveChangesHidden: resources.filter((resource) => resource.sensitive && !resource.actions.includes("no-op")).length,
+    resources,
+  };
+  return summary;
+}
+
+export function terraformPlanRequiresApproval(summary: TerraformPlanSummary): boolean {
+  return summary.create > 0 || summary.update > 0 || summary.delete > 0 || summary.replace > 0;
+}
+
+export function terraformPlanHasDeletion(summary: TerraformPlanSummary): boolean {
+  return summary.delete > 0 || summary.replace > 0;
+}
+
+export function terraformPlanSummaryText(summary: TerraformPlanSummary): string {
+  return [
+    `create=${summary.create}`,
+    `update=${summary.update}`,
+    `delete=${summary.delete}`,
+    `replace=${summary.replace}`,
+    `read=${summary.read}`,
+    `sensitive-hidden=${summary.sensitiveChangesHidden}`,
+  ].join(", ");
+}
+
+export interface TerraformStateSummary {
+  resourceCount: number;
+  resourceTypes: Record<string, number>;
+}
+
+export function summarizeTerraformState(value: unknown): TerraformStateSummary {
+  if (!value || typeof value !== "object") throw new Error("invalid Terraform state JSON");
+  const root = (value as Record<string, unknown>).values;
+  const rootModule = root && typeof root === "object" ? (root as Record<string, unknown>).root_module : undefined;
+  const resourceTypes: Record<string, number> = {};
+  let resourceCount = 0;
+  const visit = (module: unknown): void => {
+    if (!module || typeof module !== "object") return;
+    const data = module as Record<string, unknown>;
+    if (Array.isArray(data.resources)) {
+      for (const resource of data.resources) {
+        if (!resource || typeof resource !== "object") continue;
+        const type = (resource as Record<string, unknown>).type;
+        if (typeof type !== "string") continue;
+        resourceCount += 1;
+        resourceTypes[type] = (resourceTypes[type] ?? 0) + 1;
+      }
+    }
+    if (Array.isArray(data.child_modules)) for (const child of data.child_modules) visit(child);
+  };
+  visit(rootModule);
+  return { resourceCount, resourceTypes };
+}

package/.pi/lib/workflows/cloud/terraform/policy.ts

@@ -0,0 +1,36 @@
+export interface TerraformPolicyViolation {
+  code: "provisioner" | "external-data" | "unlocked-module" | "plain-secret" | "unsafe-backend";
+  file: string;
+  detail: string;
+}
+
+export interface TerraformPolicyOptions { requireRemoteBackend?: boolean }
+
+const PROVISIONER_PATTERN = /\bprovisioner\s+"(?:local-exec|remote-exec|file)"/u;
+const EXTERNAL_DATA_PATTERN = /data\s+"external"/u;
+const PLAIN_SECRET_PATTERN = /(?:access[_-]?key|secret[_-]?key|password|token)\s*=\s*"[^"$]+"/iu;
+const UNLOCKED_MODULE_PATTERN = /module\s+"[^"]+"\s*\{[\s\S]*?source\s*=\s*"(?![^"?]+\?ref=|[^"/]+\/[^"/]+\/[^"/]+\/v?\d)[^"}]+"/u;
+
+export function scanTerraformSource(files: readonly { relativePath: string; content: string }[], options: TerraformPolicyOptions = {}): TerraformPolicyViolation[] {
+  const violations: TerraformPolicyViolation[] = [];
+  for (const file of files) {
+    if (!file.relativePath.endsWith(".tf") && !file.relativePath.endsWith(".tf.json")) continue;
+    if (PROVISIONER_PATTERN.test(file.content)) violations.push({ code: "provisioner", file: file.relativePath, detail: "Terraform provisioners are disabled; use cloud-init or provider resources." });
+    if (EXTERNAL_DATA_PATTERN.test(file.content)) violations.push({ code: "external-data", file: file.relativePath, detail: "external data sources can execute arbitrary programs." });
+    if (PLAIN_SECRET_PATTERN.test(file.content)) violations.push({ code: "plain-secret", file: file.relativePath, detail: "credential-like literal detected in Terraform source." });
+    if (UNLOCKED_MODULE_PATTERN.test(file.content)) violations.push({ code: "unlocked-module", file: file.relativePath, detail: "module source must be version or commit pinned." });
+  }
+  if (options.requireRemoteBackend) {
+    const terraform = files.filter((file) => file.relativePath.endsWith(".tf") || file.relativePath.endsWith(".tf.json"));
+    const source = terraform.map((file) => file.content).join("\n");
+    const hasRemoteBackend = /backend\s+"(?!local")[^"]+"\s*\{/u.test(source)
+      || /"backend"\s*:\s*\{\s*"(?!local")[^"]+"\s*:/u.test(source);
+    if (!hasRemoteBackend) violations.push({ code: "unsafe-backend", file: "<terraform>", detail: "remote Runner execution requires an explicit non-local Terraform backend." });
+  }
+  return violations;
+}
+
+export function assertSafeTerraformSource(files: readonly { relativePath: string; content: string }[], options: TerraformPolicyOptions = {}): void {
+  const violations = scanTerraformSource(files, options);
+  if (violations.length > 0) throw new Error(violations.map((violation) => `${violation.file}: ${violation.detail}`).join("\n"));
+}

package/.pi/lib/workflows/cloud/terraform/runner.ts

@@ -0,0 +1,64 @@
+import { createHash } from "node:crypto";
+
+import type { RemoteTargetProfile } from "../remote/profiles.ts";
+import { runSsh, type SshRunResult } from "../remote/ssh-transport.ts";
+import { CLOUD_RUNTIME_DEFAULTS } from "../../../runtime/defaults.ts";
+
+export type TerraformRunnerAction = "fmt" | "init" | "validate" | "test" | "plan" | "show-plan" | "show-state" | "apply";
+
+export interface TerraformRunnerRequest {
+  action: TerraformRunnerAction;
+  workspace: string;
+  terraformPath?: string;
+  planPath?: string;
+  mode?: "normal" | "destroy" | "refresh-only";
+}
+
+const ACTIONS: Record<TerraformRunnerAction, readonly string[]> = {
+  fmt: ["fmt", "-check", "-no-color"],
+  init: ["init", "-input=false", "-no-color"],
+  validate: ["validate", "-no-color"],
+  test: ["test", "-no-color"],
+  plan: ["plan", "-input=false", "-no-color"],
+  "show-plan": ["show", "-json", "-no-color"],
+  "show-state": ["show", "-json", "-no-color"],
+  apply: ["apply", "-input=false", "-no-color"],
+};
+
+function assertWorkspace(workspace: string): void {
+  if (!workspace.startsWith("/") || workspace === "/" || workspace.includes("..")) {
+    throw new Error("invalid Terraform workspace path");
+  }
+}
+
+export function buildTerraformRunnerArgs(request: TerraformRunnerRequest): string[] {
+  assertWorkspace(request.workspace);
+  const executable = request.terraformPath?.trim() || CLOUD_RUNTIME_DEFAULTS.terraform.executable;
+  if (!executable || executable.includes(" ") || executable.includes(";")) throw new Error("invalid Terraform executable");
+  const args = [...ACTIONS[request.action]];
+  if (request.action === "plan") {
+    if (request.mode === "destroy") args.push("-destroy");
+    if (request.mode === "refresh-only") args.push("-refresh-only");
+    args.push(`-out=${CLOUD_RUNTIME_DEFAULTS.terraform.planFile}`);
+  }
+  if (request.action === "show-plan" || request.action === "apply") {
+    if (!request.planPath || request.planPath.includes("..") || !request.planPath.endsWith(".tfplan")) {
+      throw new Error("a managed Terraform plan path is required");
+    }
+    args.push(request.planPath);
+  }
+  return [executable, ...args];
+}
+
+export async function executeTerraformRunner(
+  profile: RemoteTargetProfile,
+  request: TerraformRunnerRequest,
+  options: { signal?: AbortSignal; timeoutMs?: number; onOutput?: (chunk: string, stream: "stdout" | "stderr") => void } = {},
+): Promise<SshRunResult> {
+  const [command, ...args] = buildTerraformRunnerArgs({ ...request, terraformPath: request.terraformPath ?? profile.terraformPath });
+  return runSsh(profile, command, args, { ...options, remoteCwd: request.workspace });
+}
+
+export function digestTerraformPlan(planJson: string): string {
+  return createHash("sha256").update(planJson, "utf8").digest("hex");
+}

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

@@ -14,9 +14,11 @@ import {
 	writeFileSync,
 } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname } from "node:path";
 
-import { isCloudVendorId, type CloudCredentials, type CloudVendorId } from "./cloud-providers.ts";
+import { isCloudVendorId, type CloudCredentials, type CloudVendorId } from "./providers.ts";
+import { validateRemoteTargetProfile, type RemoteTargetProfile } from "./remote/profiles.ts";
+import { userRuntimePaths } from "../../runtime/paths.ts";
 
 const AAD = Buffer.from("hwcode-cloud-credentials-v1", "utf8");
 const KEY_LENGTH = 32;
@@ -30,8 +32,9 @@ export interface CloudCredentialProfile {
 }
 
 export interface VaultPayload {
-	version: 2;
-	providers: Partial<Record<CloudVendorId, CloudCredentialProfile[]>>;
+  version: 2;
+  providers: Partial<Record<CloudVendorId, CloudCredentialProfile[]>>;
+  runners?: RemoteTargetProfile[];
 }
 
 interface EncryptedVault {
@@ -45,7 +48,7 @@ interface EncryptedVault {
 }
 
 export function defaultCloudVaultPath(home = homedir()): string {
-	return join(home, ".hwcode", "cloud", "credentials.enc");
+	return userRuntimePaths(home).cloudVault;
 }
 
 export function cloudVaultExists(path = defaultCloudVaultPath()): boolean {
@@ -69,7 +72,7 @@ export function normalizeCloudVaultPayload(value: unknown): VaultPayload {
 	if (!payload.providers || typeof payload.providers !== "object" || Array.isArray(payload.providers)) {
 		throw new Error("invalid vault payload");
 	}
-	const providers: VaultPayload["providers"] = {};
+  const providers: VaultPayload["providers"] = {};
 	for (const [vendor, stored] of Object.entries(payload.providers)) {
 		if (!isCloudVendorId(vendor)) throw new Error("unsupported cloud provider in vault");
 		if (payload.version === 1) {
@@ -96,7 +99,10 @@ export function normalizeCloudVaultPayload(value: unknown): VaultPayload {
 		});
 	}
 	if (payload.version !== 1 && payload.version !== 2) throw new Error("unsupported vault payload");
-	return { version: 2, providers };
+  const runners = payload.runners === undefined
+    ? undefined
+    : Array.isArray(payload.runners) ? payload.runners.map(validateRemoteTargetProfile) : (() => { throw new Error("invalid remote runner profiles"); })();
+  return { version: 2, providers, ...(runners ? { runners } : {}) };
 }
 
 export function readCloudVault(password: string, path = defaultCloudVaultPath()): VaultPayload {
@@ -151,23 +157,6 @@ export function writeCloudVault(payload: VaultPayload, password: string, path =
 	chmodSync(path, 0o600);
 }
 
-export function setCloudCredentials(
-	payload: VaultPayload,
-	vendor: CloudVendorId,
-	credentials: CloudCredentials,
-): VaultPayload {
-	const first = payload.providers[vendor]?.[0];
-	return saveCloudCredentialProfile(payload, vendor, credentials, first?.id);
-}
-
-export function getCloudCredentials(
-	payload: VaultPayload,
-	vendor: CloudVendorId,
-): CloudCredentials | undefined {
-	const credentials = payload.providers[vendor]?.[0]?.credentials;
-	return credentials ? { ...credentials } : undefined;
-}
-
 export function listCloudCredentialProfiles(
 	payload: VaultPayload,
 	vendor: CloudVendorId,
@@ -207,3 +196,16 @@ export function cloudCredentialProfileLabel(
 	const region = profile.credentials.region?.trim() || "未配置";
 	return `使用已有凭据${number} · Region: ${region}`;
 }
+
+export function listRemoteTargetProfiles(payload: VaultPayload): RemoteTargetProfile[] {
+  return (payload.runners ?? []).map((profile) => ({ ...profile }));
+}
+
+export function saveRemoteTargetProfile(payload: VaultPayload, profile: RemoteTargetProfile): VaultPayload {
+  const validated = validateRemoteTargetProfile(profile);
+  const profiles = listRemoteTargetProfiles(payload);
+  const existingIndex = profiles.findIndex((entry) => entry.id === validated.id);
+  if (existingIndex >= 0) profiles[existingIndex] = validated;
+  else profiles.push(validated);
+  return { version: 2, providers: { ...payload.providers }, runners: profiles };
+}

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

@@ -0,0 +1,37 @@
+import { mkdirSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { isAbsolute, join, relative, resolve } from "node:path";
+
+import { PROJECT_CLOUD_RUNS_RELATIVE, projectRuntimePaths } from "../../runtime/paths.ts";
+
+export interface CloudRunWorkspace {
+  runId: string;
+  path: string;
+  discoveryPath: string;
+  terraformPath: string;
+  chartsPath: string;
+  reportsPath: string;
+}
+
+export function createCloudRunWorkspace(root: string, runId = randomUUID()): CloudRunWorkspace {
+  const path = join(projectRuntimePaths(root).cloudRuns, runId);
+  const workspace: CloudRunWorkspace = {
+    runId, path,
+    discoveryPath: join(path, "discovery"),
+    terraformPath: join(path, "terraform"),
+    chartsPath: join(path, "charts"),
+    reportsPath: join(path, "reports"),
+  };
+  for (const directory of [workspace.discoveryPath, workspace.terraformPath, workspace.chartsPath, workspace.reportsPath]) {
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+  }
+  return workspace;
+}
+
+export function isCloudRunWorkspace(root: string, path: string): boolean {
+  const resolvedRoot = resolve(root);
+  const resolvedPath = resolve(path);
+  const remainder = relative(resolvedRoot, resolvedPath);
+  return !isAbsolute(remainder) && !remainder.startsWith("..")
+    && remainder.split(/[\\/]/u).slice(0, 3).join("/") === PROJECT_CLOUD_RUNS_RELATIVE;
+}

package/.pi/lib/workflows/sdd.ts

@@ -0,0 +1,11 @@
+import type { SddPhase, SddWorkflowProgress } from "./state.ts";
+
+export const SDD_PHASES: readonly SddPhase[] = ["discovery", "requirements", "design", "test-plan", "tasks", "tests", "implementation", "verification"];
+
+export function advanceSddProgress(progress: SddWorkflowProgress, nextPhase: SddPhase, evidence: string, approvedAt = new Date()): SddWorkflowProgress {
+  const currentIndex = SDD_PHASES.indexOf(progress.phase);
+  if (SDD_PHASES[currentIndex + 1] !== nextPhase) throw new Error(`Invalid SDD transition ${progress.phase} → ${nextPhase}. Complete phases in order.`);
+  const normalizedEvidence = evidence.replace(/[\r\n]+/gu, " ").trim().slice(0, 1_000);
+  if (!normalizedEvidence) throw new Error("SDD phase approval evidence is required");
+  return { phase: nextPhase, approvals: [...progress.approvals, { phase: nextPhase, evidence: normalizedEvidence, approvedAt: approvedAt.toISOString() }] };
+}