@hadooppei/hwcode 0.1.0 → 0.2.0

package/.pi/extensions/workflows.ts

@@ -1,5 +1,3 @@
-import { homedir, tmpdir } from "node:os";
-
 import type {
 	ExtensionAPI,
 	ExtensionCommandContext,
@@ -8,33 +6,19 @@ import type {
 
 import {
 	canonicalizeWorkspaceRoot,
-	findExternalPathReferences,
-	isPathInsideRoot,
-	resolveToolPath,
 } from "../lib/workflow-guard.ts";
 import { getWorkingDirectory } from "../lib/working-directory.ts";
-
-const STATE_TYPE = "hwcode-workflow-state";
-const AUDIT_TYPE = "hwcode-workflow-external-approval";
-const FILE_PATH_TOOLS = new Set(["read", "write", "edit", "grep", "find", "ls"]);
-
-type WorkflowMode = "vibe" | "sdd";
-
-interface ActiveWorkflowState {
-	version: 1;
-	active: true;
-	mode: WorkflowMode;
-	root: string;
-	activatedAt: string;
-}
-
-interface InactiveWorkflowState {
-	version: 1;
-	active: false;
-	deactivatedAt: string;
-}
-
-type WorkflowState = ActiveWorkflowState | InactiveWorkflowState;
+import {
+	WORKFLOW_EXTERNAL_AUDIT_TYPE,
+	WORKFLOW_STATE_TYPE,
+	activeWorkflow,
+	createWorkflowState,
+	updateWorkflowState,
+	workflowLabel,
+	type WorkflowMode,
+	type WorkflowState,
+} from "../lib/workflows/state.ts";
+import { evaluateToolPathAccess } from "../lib/workspace/access-policy.ts";
 
 interface GitState {
 	initialized: boolean;
@@ -42,28 +26,8 @@ interface GitState {
 	status: string;
 }
 
-function isWorkflowState(value: unknown): value is WorkflowState {
-	if (!value || typeof value !== "object") return false;
-	const data = value as Record<string, unknown>;
-	if (data.version !== 1 || typeof data.active !== "boolean") return false;
-	if (data.active) {
-		return (data.mode === "vibe" || data.mode === "sdd")
-			&& typeof data.root === "string"
-			&& typeof data.activatedAt === "string";
-	}
-	return typeof data.deactivatedAt === "string";
-}
-
-function restoreState(ctx: ExtensionContext): WorkflowState | undefined {
-	for (const entry of [...ctx.sessionManager.getEntries()].reverse()) {
-		if (entry.type !== "custom" || entry.customType !== STATE_TYPE || !isWorkflowState(entry.data)) continue;
-		return entry.data;
-	}
-	return undefined;
-}
-
 function modeLabel(mode: WorkflowMode): string {
-	return mode === "vibe" ? "HWCode Vibe" : "HWCode SDD";
+	return workflowLabel(mode);
 }
 
 function notify(ctx: ExtensionContext, message: string, level: "info" | "warning" | "error" = "info"): void {
@@ -155,7 +119,7 @@ function activationPrompt(mode: WorkflowMode, root: string, git: GitState | unde
 	return `/skill:hwcode-${mode} ${context.join("\n\n")}`;
 }
 
-function workflowSystemPrompt(state: ActiveWorkflowState): string {
+function workflowSystemPrompt(state: WorkflowState): string {
 	const common = [
 		`HWCODE WORKFLOW ACTIVE: ${state.mode.toUpperCase()}`,
 		`The sole project root for this session is ${state.root}.`,
@@ -174,7 +138,7 @@ function workflowSystemPrompt(state: ActiveWorkflowState): string {
 }
 
 export default function (pi: ExtensionAPI) {
-	let activeState: ActiveWorkflowState | undefined;
+	let activeState: WorkflowState | undefined;
 
 	async function activate(mode: WorkflowMode, args: string, ctx: ExtensionCommandContext): Promise<void> {
 		if (!ctx.isIdle()) {
@@ -183,6 +147,15 @@ export default function (pi: ExtensionAPI) {
 		}
 
 		const root = canonicalizeWorkspaceRoot(getWorkingDirectory(ctx.sessionManager));
+		const existing = activeWorkflow(ctx.sessionManager.getEntries());
+		if (existing) {
+			notify(
+				ctx,
+				`${workflowLabel(existing.mode)} is already active for ${existing.root}. Start a new session before activating another workflow.`,
+				"warning",
+			);
+			return;
+		}
 		if (!(await confirmWorkspace(mode, root, ctx))) {
 			notify(ctx, `${modeLabel(mode)} was not started.`, "warning");
 			return;
@@ -191,14 +164,8 @@ export default function (pi: ExtensionAPI) {
 		const git = mode === "sdd" ? await inspectOrInitializeGit(pi, root, ctx) : undefined;
 		if (mode === "sdd" && !git) return;
 
-		activeState = {
-			version: 1,
-			active: true,
-			mode,
-			root,
-			activatedAt: new Date().toISOString(),
-		};
-		pi.appendEntry<WorkflowState>(STATE_TYPE, activeState);
+		activeState = createWorkflowState(mode as "vibe" | "sdd", root);
+		pi.appendEntry<WorkflowState>(WORKFLOW_STATE_TYPE, activeState);
 		notify(ctx, `${modeLabel(mode)} activated. Project root locked to ${root}.`);
 		pi.sendUserMessage(activationPrompt(mode, root, git, args.trim()), { expandPromptTemplates: true });
 	}
@@ -214,8 +181,8 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.on("session_start", async (_event, ctx) => {
-		const restored = restoreState(ctx);
-		if (!restored?.active) {
+		const restored = activeWorkflow(ctx.sessionManager.getEntries());
+		if (!restored) {
 			activeState = undefined;
 			return;
 		}
@@ -223,11 +190,11 @@ export default function (pi: ExtensionAPI) {
 		const currentRoot = canonicalizeWorkspaceRoot(getWorkingDirectory(ctx.sessionManager));
 		if (currentRoot !== restored.root) {
 			activeState = undefined;
-			pi.appendEntry<WorkflowState>(STATE_TYPE, {
-				version: 1,
-				active: false,
-				deactivatedAt: new Date().toISOString(),
-			});
+			pi.appendEntry<WorkflowState>(WORKFLOW_STATE_TYPE, updateWorkflowState(restored, {
+				status: "failed",
+				phase: "invalid-root",
+				reason: "Stored workflow root no longer matches the current execution directory.",
+			}));
 			notify(ctx, "Stored HWCode workflow disabled because the current directory changed.", "warning");
 			return;
 		}
@@ -236,25 +203,18 @@ export default function (pi: ExtensionAPI) {
 		notify(ctx, `${modeLabel(restored.mode)} restored. Root: ${restored.root}`);
 	});
 
-	pi.on("before_agent_start", async (event) => {
+	pi.on("before_agent_start", async (event, ctx) => {
+		activeState = activeWorkflow(ctx.sessionManager.getEntries());
 		if (!activeState) return undefined;
 		return { systemPrompt: `${event.systemPrompt}\n\n${workflowSystemPrompt(activeState)}` };
 	});
 
 	pi.on("tool_call", async (event, ctx) => {
+		activeState = activeWorkflow(ctx.sessionManager.getEntries());
 		if (!activeState) return undefined;
 
 		const input = event.input as Record<string, unknown>;
-		let external: Array<{ raw: string; resolved: string }> = [];
-		if (FILE_PATH_TOOLS.has(event.toolName) && typeof input.path === "string") {
-			const resolved = resolveToolPath(activeState.root, input.path, homedir());
-			if (!isPathInsideRoot(activeState.root, resolved)) external = [{ raw: input.path, resolved }];
-		} else if (event.toolName === "bash" && typeof input.command === "string") {
-			external = findExternalPathReferences(input.command, activeState.root, {
-				home: homedir(),
-				tmpdir: tmpdir(),
-			});
-		}
+		const external = evaluateToolPathAccess({ toolName: event.toolName, input }, activeState.root);
 
 		if (external.length === 0) return undefined;
 		const details = external.map((entry) => `• ${entry.raw} → ${entry.resolved}`).join("\n");
@@ -280,7 +240,7 @@ export default function (pi: ExtensionAPI) {
 			return { block: true, reason: `User denied external path access:\n${details}` };
 		}
 
-		pi.appendEntry(AUDIT_TYPE, {
+		pi.appendEntry(WORKFLOW_EXTERNAL_AUDIT_TYPE, {
 			mode: activeState.mode,
 			root: activeState.root,
 			toolName: event.toolName,
@@ -289,4 +249,8 @@ export default function (pi: ExtensionAPI) {
 		});
 		return undefined;
 	});
+
+	pi.on("session_shutdown", () => {
+		activeState = undefined;
+	});
 }

package/.pi/lib/cloud/adapters.ts

@@ -0,0 +1,234 @@
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+  cloudEnvironment,
+  getCloudProvider,
+  redactCredentialValues,
+  type CloudCredentials,
+  type CloudProvider,
+  type CloudVendorId,
+} from "../cloud-providers.ts";
+import { runProcess, truncateOutput, type ProcessResult } from "./process.ts";
+
+export interface TemporaryCredentialStore {
+  createDirectory(prefix: string): string;
+  cleanupDirectory(directory: string): void;
+}
+
+export interface AdapterContext {
+  root: string;
+  credentials: CloudCredentials;
+  temporaryStore: TemporaryCredentialStore;
+  signal?: AbortSignal;
+}
+
+export interface PreparedCloudExecution {
+  args: string[];
+  env: Record<string, string>;
+  cleanup?: () => void;
+  error?: string;
+}
+
+export interface CloudProviderAdapter {
+  provider: CloudProvider;
+  validate(context: AdapterContext): Promise<ProcessResult>;
+  prepare(command: string, args: string[], context: AdapterContext): Promise<PreparedCloudExecution>;
+}
+
+function validationFailure(result: ProcessResult, credentials: CloudCredentials): string {
+  const raw = result.stderr.trim() || result.stdout.trim() || `command exited with code ${result.code}`;
+  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,
+  validationArgs: string[],
+): CloudProviderAdapter {
+  return {
+    provider: getCloudProvider(vendor),
+    validate: ({ root, credentials, signal }) => runProcess(validationCommand, validationArgs, {
+      cwd: root,
+      env: cloudEnvironment(vendor, credentials),
+      signal,
+      timeoutMs: 30_000,
+    }),
+    prepare: async (_command, args, { credentials }) => ({
+      args,
+      env: cloudEnvironment(vendor, credentials),
+    }),
+  };
+}
+
+async function validateAzure(context: AdapterContext): Promise<ProcessResult> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 30_000);
+  const abort = () => controller.abort();
+  context.signal?.addEventListener("abort", abort, { once: true });
+  try {
+    const form = new URLSearchParams({
+      client_id: context.credentials.clientId,
+      client_secret: context.credentials.clientSecret,
+      grant_type: "client_credentials",
+      scope: "https://management.azure.com/.default",
+    });
+    const tokenResponse = await fetch(
+      `https://login.microsoftonline.com/${encodeURIComponent(context.credentials.tenantId)}/oauth2/v2.0/token`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: form,
+        signal: controller.signal,
+      },
+    );
+    const tokenBody = await tokenResponse.json() as Record<string, unknown>;
+    if (!tokenResponse.ok || typeof tokenBody.access_token !== "string") {
+      return { stdout: "", stderr: `Azure token request failed (${tokenResponse.status}).`, code: 1, killed: false };
+    }
+    const subscriptionResponse = await fetch(
+      `https://management.azure.com/subscriptions/${encodeURIComponent(context.credentials.subscriptionId)}?api-version=2022-12-01`,
+      { headers: { authorization: `Bearer ${tokenBody.access_token}` }, signal: controller.signal },
+    );
+    if (!subscriptionResponse.ok) {
+      return { stdout: "", stderr: `Azure subscription check failed (${subscriptionResponse.status}).`, code: 1, killed: false };
+    }
+    const subscription = await subscriptionResponse.json() as Record<string, unknown>;
+    return {
+      stdout: JSON.stringify({ subscriptionId: subscription.subscriptionId, displayName: subscription.displayName }),
+      stderr: "",
+      code: 0,
+      killed: false,
+    };
+  } catch (error) {
+    return { stdout: "", stderr: error instanceof Error ? error.message : String(error), code: 1, killed: false };
+  } finally {
+    clearTimeout(timeout);
+    context.signal?.removeEventListener("abort", abort);
+  }
+}
+
+const adapters: Record<CloudVendorId, CloudProviderAdapter> = {
+  aws: basicAdapter("aws", "aws", ["sts", "get-caller-identity", "--output", "json"]),
+  alibaba: basicAdapter("alibaba", "aliyun", ["sts", "get-caller-identity"]),
+  tencent: basicAdapter("tencent", "tccli", ["sts", "GetCallerIdentity", "--output", "json"]),
+  huawei: {
+    provider: getCloudProvider("huawei"),
+    validate: ({ root, credentials, signal }) => runProcess(
+      "hcloud",
+      ["IAM", "KeystoneListProjects", ...huaweiAuthenticationArgs(credentials)],
+      { cwd: root, env: cloudEnvironment("huawei", credentials), signal, timeoutMs: 30_000 },
+    ),
+    prepare: async (command, args, { credentials }) => ({
+      args: command === "hcloud" ? [...args, ...huaweiAuthenticationArgs(credentials)] : args,
+      env: cloudEnvironment("huawei", credentials),
+    }),
+  },
+  gcp: {
+    provider: getCloudProvider("gcp"),
+    validate: async (context) => {
+      const directory = context.temporaryStore.createDirectory("hwcode-cloud-gcp-");
+      const path = join(directory, "credential.json");
+      writeFileSync(path, context.credentials.serviceAccountJson, { encoding: "utf8", mode: 0o600 });
+      try {
+        return await runProcess("gcloud", ["projects", "describe", context.credentials.projectId, "--format=json"], {
+          cwd: context.root,
+          env: {
+            ...cloudEnvironment("gcp", context.credentials),
+            GOOGLE_APPLICATION_CREDENTIALS: path,
+            CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE: path,
+          },
+          signal: context.signal,
+          timeoutMs: 30_000,
+        });
+      } finally {
+        context.temporaryStore.cleanupDirectory(directory);
+      }
+    },
+    prepare: async (_command, args, context) => {
+      const directory = context.temporaryStore.createDirectory("hwcode-cloud-gcp-");
+      const path = join(directory, "credential.json");
+      writeFileSync(path, context.credentials.serviceAccountJson, { encoding: "utf8", mode: 0o600 });
+      return {
+        args,
+        env: {
+          ...cloudEnvironment("gcp", context.credentials),
+          GOOGLE_APPLICATION_CREDENTIALS: path,
+          CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE: path,
+        },
+        cleanup: () => context.temporaryStore.cleanupDirectory(directory),
+      };
+    },
+  },
+  azure: {
+    provider: getCloudProvider("azure"),
+    validate: validateAzure,
+    prepare: async (command, args, context) => {
+      const env = cloudEnvironment("azure", context.credentials);
+      if (command !== "az") return { args, env };
+      const directory = context.temporaryStore.createDirectory("hwcode-cloud-azure-");
+      const cleanup = () => context.temporaryStore.cleanupDirectory(directory);
+      const azureEnv = { ...env, AZURE_CONFIG_DIR: directory };
+      const login = await runProcess("az", [
+        "login", "--service-principal",
+        "--username", context.credentials.clientId,
+        "--password", context.credentials.clientSecret,
+        "--tenant", context.credentials.tenantId,
+        "--output", "none",
+      ], { cwd: context.root, env: azureEnv, signal: context.signal, timeoutMs: 60_000 });
+      if (login.code !== 0) {
+        return { args, env: azureEnv, cleanup, error: validationFailure(login, context.credentials) };
+      }
+      const selection = await runProcess(
+        "az",
+        ["account", "set", "--subscription", context.credentials.subscriptionId],
+        { cwd: context.root, env: azureEnv, signal: context.signal, timeoutMs: 30_000 },
+      );
+      if (selection.code !== 0) {
+        return { args, env: azureEnv, cleanup, error: validationFailure(selection, context.credentials) };
+      }
+      return { args, env: azureEnv, cleanup };
+    },
+  },
+};
+
+export function getCloudAdapter(vendor: CloudVendorId): CloudProviderAdapter {
+  return adapters[vendor];
+}
+
+export function validateCloudCredentials(
+  vendor: CloudVendorId,
+  context: AdapterContext,
+): Promise<ProcessResult> {
+  return getCloudAdapter(vendor).validate(context);
+}
+
+export function prepareCloudExecution(
+  vendor: CloudVendorId,
+  command: string,
+  args: string[],
+  context: AdapterContext,
+): Promise<PreparedCloudExecution> {
+  return getCloudAdapter(vendor).prepare(command, args, context);
+}
+
+export function formatValidationFailure(result: ProcessResult, credentials: CloudCredentials): string {
+  return validationFailure(result, credentials);
+}
+
+export function checkProviderCli(vendor: CloudVendorId, root: string): Promise<ProcessResult> {
+  const provider = getCloudProvider(vendor);
+  return runProcess(provider.cli, provider.versionArgs, { cwd: root, timeoutMs: 10_000 });
+}

package/.pi/lib/cloud/process.ts

@@ -0,0 +1,91 @@
+import { spawn } from "node:child_process";
+
+export const MAX_CLOUD_OUTPUT_BYTES = 50_000;
+const MAX_CAPTURE_BYTES = MAX_CLOUD_OUTPUT_BYTES * 2;
+const CLOUD_ENV_PREFIXES = [
+  "AWS_", "AZURE_", "ARM_", "GOOGLE_", "CLOUDSDK_", "HW_", "HUAWEI",
+  "ALIBABA_CLOUD_", "TENCENTCLOUD_",
+];
+
+export interface ProcessResult {
+  stdout: string;
+  stderr: string;
+  code: number;
+  killed: boolean;
+  timedOut?: boolean;
+  spawnErrorCode?: string;
+}
+
+function captureOutput(current: string, chunk: Buffer): string {
+  if (Buffer.byteLength(current, "utf8") >= MAX_CAPTURE_BYTES) return current;
+  const remaining = MAX_CAPTURE_BYTES - Buffer.byteLength(current, "utf8");
+  return `${current}${chunk.subarray(0, remaining).toString("utf8")}`;
+}
+
+export function isolatedCloudEnvironment(extra: Record<string, string> = {}): NodeJS.ProcessEnv {
+  const inherited = Object.fromEntries(Object.entries(process.env).filter(([key]) => (
+    !CLOUD_ENV_PREFIXES.some((prefix) => key.startsWith(prefix))
+  )));
+  return { ...inherited, ...extra };
+}
+
+export function runProcess(
+  command: string,
+  args: readonly string[],
+  options: {
+    cwd: string;
+    env?: Record<string, string>;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+  },
+): Promise<ProcessResult> {
+  return new Promise((finish) => {
+    let stdout = "";
+    let stderr = "";
+    let killed = false;
+    let timedOut = false;
+    let settled = false;
+    let forceKillTimer: ReturnType<typeof setTimeout> | undefined;
+    const child = spawn(command, [...args], {
+      cwd: options.cwd,
+      env: isolatedCloudEnvironment(options.env),
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: false,
+    });
+    const complete = (result: ProcessResult) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeoutTimer);
+      if (forceKillTimer) clearTimeout(forceKillTimer);
+      options.signal?.removeEventListener("abort", abort);
+      finish(result);
+    };
+    const terminate = (timeout: boolean) => {
+      killed = true;
+      timedOut ||= timeout;
+      child.kill("SIGTERM");
+      forceKillTimer ??= setTimeout(() => child.kill("SIGKILL"), 2_000);
+    };
+    const abort = () => terminate(false);
+    const timeoutTimer = setTimeout(() => terminate(true), options.timeoutMs ?? 120_000);
+    if (options.signal?.aborted) abort();
+    else options.signal?.addEventListener("abort", abort, { once: true });
+    child.stdout.on("data", (chunk: Buffer) => { stdout = captureOutput(stdout, chunk); });
+    child.stderr.on("data", (chunk: Buffer) => { stderr = captureOutput(stderr, chunk); });
+    child.on("error", (error) => complete({
+      stdout,
+      stderr: `${stderr}${error.message}`,
+      code: 127,
+      killed,
+      timedOut,
+      spawnErrorCode: (error as NodeJS.ErrnoException).code,
+    }));
+    child.on("close", (code) => complete({ stdout, stderr, code: code ?? 1, killed, timedOut }));
+  });
+}
+
+export function truncateOutput(text: string): string {
+  const bytes = Buffer.from(text, "utf8");
+  if (bytes.length <= MAX_CLOUD_OUTPUT_BYTES) return text;
+  return `${bytes.subarray(0, MAX_CLOUD_OUTPUT_BYTES).toString("utf8")}\n\n[HWCode truncated cloud command output]`;
+}

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

@@ -0,0 +1,148 @@
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+
+import { getCloudProvider, isCloudVendorId, type CloudVendorId } from "../cloud-providers.ts";
+import type { WorkflowState } from "../workflows/state.ts";
+
+export interface CloudPromptTemplate {
+  id: string;
+  description: string;
+  vendor: CloudVendorId;
+  deployCurrentProject: boolean;
+  objective: string;
+  body: string;
+  path: string;
+}
+
+export function defaultCloudPromptDirectory(home = homedir()): string {
+  return join(home, ".hwcode", "cloud", "prompts");
+}
+
+function slugify(value: string): string {
+  const slug = value
+    .normalize("NFKD")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/gu, "-")
+    .replace(/^-+|-+$/gu, "")
+    .slice(0, 48);
+  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, "");
+  }
+}
+
+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");
+  return {
+    id,
+    description: frontmatterValue(metadata, "description") ?? id,
+    vendor: vendorValue,
+    deployCurrentProject: frontmatterValue(metadata, "hwcode-cloud-deploy") === "true",
+    objective: frontmatterValue(metadata, "hwcode-cloud-objective") ?? "",
+    body: match[2].trim(),
+    path,
+  };
+}
+
+export function listCloudPromptTemplates(
+  directory = defaultCloudPromptDirectory(),
+): CloudPromptTemplate[] {
+  if (!existsSync(directory)) return [];
+  return readdirSync(directory, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+    .map((entry) => parseCloudPromptTemplate(join(directory, entry.name)))
+    .filter((template): template is CloudPromptTemplate => Boolean(template))
+    .sort((left, right) => left.description.localeCompare(right.description));
+}
+
+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("`", "\\`");
+}
+
+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}] ${step.intent}\n`
+      + `   - Approach: ${step.approach}\n`
+      + `   - Reference command: \`${inlineCode([step.command, ...step.args].join(" "))}\``
+  )).join("\n");
+  return [
+    "Execute a reusable HWCode Cloud task based on a previously successful run.",
+    "",
+    `Preferred provider: ${provider.label}`,
+    `Deploy current project: ${details.deployCurrentProject ? "yes" : "no"}`,
+    `Objective pattern: ${details.request}`,
+    "",
+    "Known successful execution sequence (reference only; re-check current account state before reuse):",
+    steps,
+    "",
+    ...(notes ? ["Validated-run notes and pitfalls:", notes, ""] : []),
+    "Start with read-only discovery and adapt account, region, project, resource names, versions, and paths to the current environment. Present the plan and obtain all normal HWCode Cloud approvals. Never copy credentials or assume resources from the previous run still exist.",
+    "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");
+}
+
+export function saveCloudPromptTemplate(
+  requestedName: string,
+  state: WorkflowState,
+  directory = defaultCloudPromptDirectory(),
+  notes = "",
+): CloudPromptTemplate {
+  if (state.mode !== "cloud" || !state.details) throw new Error("Cloud workflow state is required");
+  const idBase = `hwcloud-${slugify(requestedName || state.details.request)}`;
+  const body = renderCloudPromptTemplate(state, notes);
+  const description = `Reuse successful ${getCloudProvider(state.details.vendor).label} workflow: ${state.details.request.slice(0, 80)}`;
+  const content = [
+    "---",
+    `description: ${JSON.stringify(description)}`,
+    'argument-hint: "[additional instructions]"',
+    `hwcode-cloud-vendor: ${JSON.stringify(state.details.vendor)}`,
+    `hwcode-cloud-deploy: ${state.details.deployCurrentProject}`,
+    `hwcode-cloud-objective: ${JSON.stringify(state.details.request)}`,
+    "---",
+    body,
+    "",
+  ].join("\n");
+
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  chmodSync(directory, 0o700);
+  let id = idBase;
+  let path = join(directory, `${id}.md`);
+  for (let suffix = 2; existsSync(path); suffix++) {
+    id = `${idBase}-${suffix}`;
+    path = join(directory, `${id}.md`);
+  }
+  const temporaryPath = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporaryPath, content, { encoding: "utf8", mode: 0o600 });
+  chmodSync(temporaryPath, 0o600);
+  renameSync(temporaryPath, path);
+  chmodSync(path, 0o600);
+  return parseCloudPromptTemplate(path)!;
+}