@hadooppei/hwcode 0.2.1 → 1.0.0

package/.pi/extensions/workflows/vibe-sdd.ts

@@ -0,0 +1,300 @@
+import type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { isAbsolute, relative, resolve } from "node:path";
+
+import {
+	canonicalizeWorkspaceRoot,
+} from "../../lib/workflow-guard.ts";
+import { getWorkingDirectory } from "../../lib/working-directory.ts";
+import {
+	WORKFLOW_EXTERNAL_AUDIT_TYPE,
+	WORKFLOW_STATE_TYPE,
+	activeWorkflow,
+	createWorkflowState,
+	updateWorkflowState,
+	workflowLabel,
+	type WorkflowMode,
+	type WorkflowState,
+} from "../../lib/workflows/state.ts";
+import { advanceSddProgress, SDD_PHASES } from "../../lib/workflows/sdd.ts";
+import { evaluateToolPathAccess } from "../../lib/workspace/access-policy.ts";
+import { PROJECT_SDD_SPECS_RELATIVE } from "../../lib/runtime/paths.ts";
+
+interface GitState {
+	initialized: boolean;
+	dirty: boolean;
+	status: string;
+}
+
+function modeLabel(mode: WorkflowMode): string {
+	return workflowLabel(mode);
+}
+
+function notify(ctx: ExtensionContext, message: string, level: "info" | "warning" | "error" = "info"): void {
+	if (ctx.hasUI) ctx.ui.notify(message, level);
+}
+
+async function confirmWorkspace(mode: WorkflowMode, root: string, ctx: ExtensionCommandContext): Promise<boolean> {
+	if (!ctx.hasUI) return false;
+	return ctx.ui.confirm(
+		`Start ${modeLabel(mode)}?`,
+		[
+			`Project root: ${root}`,
+			"",
+			"All project work in this session will be limited to this root.",
+			"Paths inside it are allowed silently. Each external-path tool call requires separate approval.",
+		].join("\n"),
+	);
+}
+
+async function inspectOrInitializeGit(
+	pi: ExtensionAPI,
+	root: string,
+	ctx: ExtensionCommandContext,
+): Promise<GitState | undefined> {
+	const gitVersion = await pi.exec("git", ["--version"], { cwd: root });
+	if (gitVersion.code !== 0) {
+		notify(ctx, "HWCode SDD requires Git, but the git executable is unavailable.", "error");
+		return undefined;
+	}
+
+	let initialized = false;
+	let topLevel = await pi.exec("git", ["rev-parse", "--show-toplevel"], { cwd: root });
+	if (topLevel.code !== 0) {
+		if (!ctx.hasUI || !(await ctx.ui.confirm(
+			"Initialize Git repository?",
+			`HWCode SDD requires the current directory to be a Git repository root.\n\nRun git init in:\n${root}`,
+		))) return undefined;
+
+		const init = await pi.exec("git", ["init"], { cwd: root });
+		if (init.code !== 0) {
+			notify(ctx, `Git initialization failed: ${init.stderr.trim() || init.stdout.trim()}`, "error");
+			return undefined;
+		}
+		initialized = true;
+		topLevel = await pi.exec("git", ["rev-parse", "--show-toplevel"], { cwd: root });
+	}
+
+	if (topLevel.code !== 0) {
+		notify(ctx, "Unable to determine the Git repository root.", "error");
+		return undefined;
+	}
+
+	const gitRoot = canonicalizeWorkspaceRoot(topLevel.stdout.trim());
+	if (gitRoot !== root) {
+		notify(
+			ctx,
+			`HWCode SDD must start at the Git repository root. Restart it from: ${gitRoot}`,
+			"error",
+		);
+		return undefined;
+	}
+
+	const statusResult = await pi.exec(
+		"git",
+		["status", "--porcelain=v1", "--untracked-files=all"],
+		{ cwd: root },
+	);
+	if (statusResult.code !== 0) {
+		notify(ctx, `Unable to inspect Git status: ${statusResult.stderr.trim()}`, "error");
+		return undefined;
+	}
+
+	const status = statusResult.stdout.trim();
+	return { initialized, dirty: status.length > 0, status };
+}
+
+function activationPrompt(mode: WorkflowMode, root: string, git: GitState | undefined, request: string): string {
+	const context = [
+		`The ${modeLabel(mode)} workflow has been activated by its project command.`,
+		`Locked project root: ${root}`,
+	];
+	if (git) {
+		context.push(
+			`Git repository: ${git.initialized ? "initialized now" : "already present"}; working tree: ${git.dirty ? "has changes" : "clean"}.`,
+		);
+		if (git.status) context.push(`Current porcelain status:\n${git.status}`);
+	}
+	if (request) context.push(`Initial user request:\n${request}`);
+	return `/skill:hwcode-${mode} ${context.join("\n\n")}`;
+}
+
+function workflowSystemPrompt(state: WorkflowState): string {
+	const common = [
+		`HWCODE WORKFLOW ACTIVE: ${state.mode.toUpperCase()}`,
+		`The sole project root for this session is ${state.root}.`,
+		"Keep all reads, writes, commands, generated files, and project work inside that root by default.",
+		"An external-path approval applies only to the exact tool call that requested it. Never evade the guard through indirection, symlinks, subprocesses, alternate tools, or encoded commands.",
+		"If external storage such as /tmp is genuinely useful, explain why and let the tool-call approval request obtain user consent.",
+	];
+	if (state.mode === "sdd") {
+		common.push(
+			"Follow the SDD phase gates. Do not implement production behavior before requirements, design, test plan, and tasks are complete and explicitly approved.",
+			"Develop tests before implementation with a red-green-refactor loop. Return to specification when expected behavior or a test scenario is uncertain.",
+			"Never create a Git commit unless the user explicitly approves that commit.",
+		);
+	}
+	return common.join("\n");
+}
+
+export function registerVibeSddWorkflows(pi: ExtensionAPI) {
+	let activeState: WorkflowState | undefined;
+
+	async function activate(mode: WorkflowMode, args: string, ctx: ExtensionCommandContext): Promise<void> {
+		if (!ctx.isIdle()) {
+			notify(ctx, `Wait for the current response to finish before starting ${modeLabel(mode)}.`, "warning");
+			return;
+		}
+
+		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;
+		}
+
+		const git = mode === "sdd" ? await inspectOrInitializeGit(pi, root, ctx) : undefined;
+		if (mode === "sdd" && !git) return;
+
+		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 });
+	}
+
+	pi.registerCommand("hwcode-vibe", {
+		description: "Start the directory-locked HWCode Vibe workflow",
+		handler: async (args, ctx) => activate("vibe", args, ctx),
+	});
+
+	pi.registerCommand("hwcode-sdd", {
+		description: "Start the Git-root-locked HWCode spec-driven workflow",
+		handler: async (args, ctx) => activate("sdd", args, ctx),
+	});
+
+	pi.registerTool(defineTool({
+		name: "hwcode_sdd_advance",
+		label: "HWCode SDD Phase Gate",
+		description: "Advance the active SDD workflow by exactly one explicitly approved phase.",
+		promptSnippet: "Use the SDD phase gate after presenting the completed artifact and receiving user approval.",
+		parameters: Type.Object({ nextPhase: Type.Union(SDD_PHASES.slice(1).map((phase) => Type.Literal(phase))), evidence: Type.String({ description: "Concise artifact and approval summary shown to the user" }) }),
+		executionMode: "sequential",
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			const state = activeWorkflow(ctx.sessionManager.getEntries());
+			if (!state || state.mode !== "sdd" || !state.sdd) return { content: [{ type: "text", text: "No active HWCode SDD workflow." }], isError: true, details: {} };
+			const evidence = params.evidence.replace(/[\r\n]+/gu, " ").trim().slice(0, 1_000);
+			let progress;
+			try { progress = advanceSddProgress(state.sdd, params.nextPhase, evidence); }
+			catch (error) { return { content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], isError: true, details: {} }; }
+			if (!ctx.hasUI || !await ctx.ui.confirm(`批准进入 SDD ${params.nextPhase} 阶段？`, evidence)) return { content: [{ type: "text", text: "SDD phase advancement was not approved." }], isError: true, details: {} };
+			const updated = updateWorkflowState(state, {
+				phase: params.nextPhase,
+				sdd: progress,
+			});
+			activeState = updated;
+			pi.appendEntry<WorkflowState>(WORKFLOW_STATE_TYPE, updated);
+			return { content: [{ type: "text", text: `SDD advanced to ${params.nextPhase}.` }], details: { phase: params.nextPhase } };
+		},
+	}));
+
+	pi.on("session_start", async (_event, ctx) => {
+		const restored = activeWorkflow(ctx.sessionManager.getEntries());
+		if (!restored) {
+			activeState = undefined;
+			return;
+		}
+
+		const currentRoot = canonicalizeWorkspaceRoot(getWorkingDirectory(ctx.sessionManager));
+		if (currentRoot !== restored.root) {
+			activeState = undefined;
+			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;
+		}
+
+		activeState = restored;
+		notify(ctx, `${modeLabel(restored.mode)} restored. Root: ${restored.root}`);
+	});
+
+	pi.on("before_agent_start", async (event, ctx) => {
+		activeState = activeWorkflow(ctx.sessionManager.getEntries());
+		if (!activeState) return undefined;
+		const sddPhase = activeState.mode === "sdd" && activeState.sdd ? `\nCurrent enforced SDD phase: ${activeState.sdd.phase}. Use hwcode_sdd_advance for the next user-approved transition; never skip a phase.` : "";
+		return { systemPrompt: `${event.systemPrompt}\n\n${workflowSystemPrompt(activeState)}${sddPhase}` };
+	});
+
+	pi.on("tool_call", async (event, ctx) => {
+		activeState = activeWorkflow(ctx.sessionManager.getEntries());
+		if (!activeState) return undefined;
+
+		const input = event.input as Record<string, unknown>;
+		if (activeState.mode === "sdd" && activeState.sdd && ["write", "edit"].includes(event.toolName) && typeof input.path === "string") {
+			const path = resolve(activeState.root, input.path);
+			const projectRelative = relative(activeState.root, path).split("\\").join("/");
+			const isSpecArtifact = projectRelative.startsWith(`${PROJECT_SDD_SPECS_RELATIVE}/`);
+			const isTestArtifact = /(?:^|\/)(?:test|tests|__tests__)\/|(?:\.test|\.spec)\.[^/]+$/u.test(projectRelative);
+			const phase = activeState.sdd.phase;
+			const allowed = ["implementation", "verification"].includes(phase)
+				|| isSpecArtifact
+				|| phase === "tests" && isTestArtifact;
+			if (!allowed || isAbsolute(projectRelative) || projectRelative.startsWith("..")) {
+				return { block: true, reason: `SDD phase ${phase} does not allow production-file changes. Write approved spec artifacts under ${PROJECT_SDD_SPECS_RELATIVE}; test files become writable in the tests phase.` };
+			}
+		}
+		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");
+		if (!ctx.hasUI) {
+			return {
+				block: true,
+				reason: `External path requires interactive one-call approval:\n${details}`,
+			};
+		}
+
+		const allowed = await ctx.ui.confirm(
+			"Allow external path for this call?",
+			[
+				`${modeLabel(activeState.mode)} is locked to ${activeState.root}.`,
+				"This tool call references paths outside that root:",
+				"",
+				details,
+				"",
+				"Approval applies only to this tool call.",
+			].join("\n"),
+		);
+		if (!allowed) {
+			return { block: true, reason: `User denied external path access:\n${details}` };
+		}
+
+		pi.appendEntry(WORKFLOW_EXTERNAL_AUDIT_TYPE, {
+			mode: activeState.mode,
+			root: activeState.root,
+			toolName: event.toolName,
+			external,
+			approvedAt: new Date().toISOString(),
+		});
+		return undefined;
+	});
+
+	pi.on("session_shutdown", () => {
+		activeState = undefined;
+	});
+}

package/.pi/extensions/workflows.ts

@@ -1,256 +1,9 @@
-import type {
-	ExtensionAPI,
-	ExtensionCommandContext,
-	ExtensionContext,
-} from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-import {
-	canonicalizeWorkspaceRoot,
-} from "../lib/workflow-guard.ts";
-import { getWorkingDirectory } from "../lib/working-directory.ts";
-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";
+import { registerCloudWorkflow } from "./workflows/cloud/index.ts";
+import { registerVibeSddWorkflows } from "./workflows/vibe-sdd.ts";
 
-interface GitState {
-	initialized: boolean;
-	dirty: boolean;
-	status: string;
-}
-
-function modeLabel(mode: WorkflowMode): string {
-	return workflowLabel(mode);
-}
-
-function notify(ctx: ExtensionContext, message: string, level: "info" | "warning" | "error" = "info"): void {
-	if (ctx.hasUI) ctx.ui.notify(message, level);
-}
-
-async function confirmWorkspace(mode: WorkflowMode, root: string, ctx: ExtensionCommandContext): Promise<boolean> {
-	if (!ctx.hasUI) return false;
-	return ctx.ui.confirm(
-		`Start ${modeLabel(mode)}?`,
-		[
-			`Project root: ${root}`,
-			"",
-			"All project work in this session will be limited to this root.",
-			"Paths inside it are allowed silently. Each external-path tool call requires separate approval.",
-		].join("\n"),
-	);
-}
-
-async function inspectOrInitializeGit(
-	pi: ExtensionAPI,
-	root: string,
-	ctx: ExtensionCommandContext,
-): Promise<GitState | undefined> {
-	const gitVersion = await pi.exec("git", ["--version"], { cwd: root });
-	if (gitVersion.code !== 0) {
-		notify(ctx, "HWCode SDD requires Git, but the git executable is unavailable.", "error");
-		return undefined;
-	}
-
-	let initialized = false;
-	let topLevel = await pi.exec("git", ["rev-parse", "--show-toplevel"], { cwd: root });
-	if (topLevel.code !== 0) {
-		if (!ctx.hasUI || !(await ctx.ui.confirm(
-			"Initialize Git repository?",
-			`HWCode SDD requires the current directory to be a Git repository root.\n\nRun git init in:\n${root}`,
-		))) return undefined;
-
-		const init = await pi.exec("git", ["init"], { cwd: root });
-		if (init.code !== 0) {
-			notify(ctx, `Git initialization failed: ${init.stderr.trim() || init.stdout.trim()}`, "error");
-			return undefined;
-		}
-		initialized = true;
-		topLevel = await pi.exec("git", ["rev-parse", "--show-toplevel"], { cwd: root });
-	}
-
-	if (topLevel.code !== 0) {
-		notify(ctx, "Unable to determine the Git repository root.", "error");
-		return undefined;
-	}
-
-	const gitRoot = canonicalizeWorkspaceRoot(topLevel.stdout.trim());
-	if (gitRoot !== root) {
-		notify(
-			ctx,
-			`HWCode SDD must start at the Git repository root. Restart it from: ${gitRoot}`,
-			"error",
-		);
-		return undefined;
-	}
-
-	const statusResult = await pi.exec(
-		"git",
-		["status", "--porcelain=v1", "--untracked-files=all"],
-		{ cwd: root },
-	);
-	if (statusResult.code !== 0) {
-		notify(ctx, `Unable to inspect Git status: ${statusResult.stderr.trim()}`, "error");
-		return undefined;
-	}
-
-	const status = statusResult.stdout.trim();
-	return { initialized, dirty: status.length > 0, status };
-}
-
-function activationPrompt(mode: WorkflowMode, root: string, git: GitState | undefined, request: string): string {
-	const context = [
-		`The ${modeLabel(mode)} workflow has been activated by its project command.`,
-		`Locked project root: ${root}`,
-	];
-	if (git) {
-		context.push(
-			`Git repository: ${git.initialized ? "initialized now" : "already present"}; working tree: ${git.dirty ? "has changes" : "clean"}.`,
-		);
-		if (git.status) context.push(`Current porcelain status:\n${git.status}`);
-	}
-	if (request) context.push(`Initial user request:\n${request}`);
-	return `/skill:hwcode-${mode} ${context.join("\n\n")}`;
-}
-
-function workflowSystemPrompt(state: WorkflowState): string {
-	const common = [
-		`HWCODE WORKFLOW ACTIVE: ${state.mode.toUpperCase()}`,
-		`The sole project root for this session is ${state.root}.`,
-		"Keep all reads, writes, commands, generated files, and project work inside that root by default.",
-		"An external-path approval applies only to the exact tool call that requested it. Never evade the guard through indirection, symlinks, subprocesses, alternate tools, or encoded commands.",
-		"If external storage such as /tmp is genuinely useful, explain why and let the tool-call approval request obtain user consent.",
-	];
-	if (state.mode === "sdd") {
-		common.push(
-			"Follow the SDD phase gates. Do not implement production behavior before requirements, design, test plan, and tasks are complete and explicitly approved.",
-			"Develop tests before implementation with a red-green-refactor loop. Return to specification when expected behavior or a test scenario is uncertain.",
-			"Never create a Git commit unless the user explicitly approves that commit.",
-		);
-	}
-	return common.join("\n");
-}
-
-export default function (pi: ExtensionAPI) {
-	let activeState: WorkflowState | undefined;
-
-	async function activate(mode: WorkflowMode, args: string, ctx: ExtensionCommandContext): Promise<void> {
-		if (!ctx.isIdle()) {
-			notify(ctx, `Wait for the current response to finish before starting ${modeLabel(mode)}.`, "warning");
-			return;
-		}
-
-		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;
-		}
-
-		const git = mode === "sdd" ? await inspectOrInitializeGit(pi, root, ctx) : undefined;
-		if (mode === "sdd" && !git) return;
-
-		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 });
-	}
-
-	pi.registerCommand("hwcode-vibe", {
-		description: "Start the directory-locked HWCode Vibe workflow",
-		handler: async (args, ctx) => activate("vibe", args, ctx),
-	});
-
-	pi.registerCommand("hwcode-sdd", {
-		description: "Start the Git-root-locked HWCode spec-driven workflow",
-		handler: async (args, ctx) => activate("sdd", args, ctx),
-	});
-
-	pi.on("session_start", async (_event, ctx) => {
-		const restored = activeWorkflow(ctx.sessionManager.getEntries());
-		if (!restored) {
-			activeState = undefined;
-			return;
-		}
-
-		const currentRoot = canonicalizeWorkspaceRoot(getWorkingDirectory(ctx.sessionManager));
-		if (currentRoot !== restored.root) {
-			activeState = undefined;
-			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;
-		}
-
-		activeState = restored;
-		notify(ctx, `${modeLabel(restored.mode)} restored. Root: ${restored.root}`);
-	});
-
-	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>;
-		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");
-		if (!ctx.hasUI) {
-			return {
-				block: true,
-				reason: `External path requires interactive one-call approval:\n${details}`,
-			};
-		}
-
-		const allowed = await ctx.ui.confirm(
-			"Allow external path for this call?",
-			[
-				`${modeLabel(activeState.mode)} is locked to ${activeState.root}.`,
-				"This tool call references paths outside that root:",
-				"",
-				details,
-				"",
-				"Approval applies only to this tool call.",
-			].join("\n"),
-		);
-		if (!allowed) {
-			return { block: true, reason: `User denied external path access:\n${details}` };
-		}
-
-		pi.appendEntry(WORKFLOW_EXTERNAL_AUDIT_TYPE, {
-			mode: activeState.mode,
-			root: activeState.root,
-			toolName: event.toolName,
-			external,
-			approvedAt: new Date().toISOString(),
-		});
-		return undefined;
-	});
-
-	pi.on("session_shutdown", () => {
-		activeState = undefined;
-	});
+export default function registerWorkflows(pi: ExtensionAPI): void {
+  registerVibeSddWorkflows(pi);
+  registerCloudWorkflow(pi);
 }

package/.pi/lib/runtime/config.ts

@@ -1,5 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { resolve } from "node:path";
+
+import { profileResourcePath } from "./paths.ts";
 
 export type JsonObject = Record<string, unknown>;
 
@@ -23,12 +25,6 @@ export function deepMerge<T extends JsonObject>(base: T, override: JsonObject):
   return merged as T;
 }
 
-export function profileResourcePath(fileName: string): string | undefined {
-  return process.env.HWCODE_PROFILE_DIR
-    ? join(process.env.HWCODE_PROFILE_DIR, fileName)
-    : undefined;
-}
-
 export function configLocations(cwd: string, fileName: string): ConfigLocations {
   return {
     profile: profileResourcePath(fileName),

package/.pi/lib/runtime/defaults.ts

@@ -0,0 +1,20 @@
+/** Internal product defaults and safety limits. User-overridable settings stay in settings.json. */
+export const CLOUD_RUNTIME_DEFAULTS = Object.freeze({
+  workflow: Object.freeze({ maxFailedApproaches: 3, maxSuccessfulSteps: 100 }),
+  process: Object.freeze({
+    commandTimeoutMs: 120_000,
+    providerValidationTimeoutMs: 30_000,
+    forceKillGraceMs: 2_000,
+    maxOutputBytes: 50_000,
+  }),
+  runner: Object.freeze({
+    defaultUser: "ubuntu",
+    defaultPort: 22,
+    keyCandidates: Object.freeze(["id_ed25519", "id_rsa"]),
+    hostKeyScanTimeoutMs: 15_000,
+    connectTimeoutSeconds: 15,
+    commandTimeoutMs: 120_000,
+  }),
+  templates: Object.freeze({ slugMaxLength: 48, nameMaxLength: 80 }),
+  terraform: Object.freeze({ executable: "terraform", planFile: "hwcode.tfplan" }),
+});

package/.pi/lib/runtime/paths.ts

@@ -0,0 +1,68 @@
+import { homedir } from "node:os";
+import { join, posix, resolve } from "node:path";
+
+export const HWCODE_DATA_DIRECTORY = ".hwcode";
+export const PROJECT_SDD_SPECS_RELATIVE = `${HWCODE_DATA_DIRECTORY}/specs`;
+export const PROJECT_CLOUD_RUNS_RELATIVE = `${HWCODE_DATA_DIRECTORY}/cloud/runs`;
+
+export interface ProjectRuntimePaths {
+  root: string;
+  hwcode: string;
+  specs: string;
+  cloud: string;
+  cloudRuns: string;
+}
+
+export interface UserRuntimePaths {
+  root: string;
+  cloud: string;
+  cloudVault: string;
+  cloudKnownHosts: string;
+  cloudPromptTemplates: string;
+  cloudDeploymentTemplates: string;
+}
+
+export function projectRuntimePaths(projectRoot: string): ProjectRuntimePaths {
+  const root = resolve(projectRoot);
+  const hwcode = join(root, HWCODE_DATA_DIRECTORY);
+  const cloud = join(hwcode, "cloud");
+  return {
+    root,
+    hwcode,
+    specs: join(hwcode, "specs"),
+    cloud,
+    cloudRuns: join(cloud, "runs"),
+  };
+}
+
+export function userRuntimePaths(home = homedir()): UserRuntimePaths {
+  const root = join(home, HWCODE_DATA_DIRECTORY);
+  const cloud = join(root, "cloud");
+  return {
+    root,
+    cloud,
+    cloudVault: join(cloud, "credentials.enc"),
+    cloudKnownHosts: join(cloud, "known_hosts"),
+    cloudPromptTemplates: join(cloud, "templates", "prompts"),
+    cloudDeploymentTemplates: join(cloud, "templates", "deployments"),
+  };
+}
+
+export function legacyUserCloudTemplatePaths(home = homedir()): {
+  prompts: string;
+  deployments: string;
+} {
+  const cloud = join(home, HWCODE_DATA_DIRECTORY, "cloud");
+  return { prompts: join(cloud, "prompts"), deployments: join(cloud, "templates") };
+}
+
+export function remoteRunnerPaths(user: string): { root: string; runs: string } {
+  const root = posix.join("/home", user, HWCODE_DATA_DIRECTORY);
+  return { root, runs: posix.join(root, "runs") };
+}
+
+export function profileResourcePath(fileName: string): string | undefined {
+  return process.env.HWCODE_PROFILE_DIR
+    ? join(process.env.HWCODE_PROFILE_DIR, fileName)
+    : undefined;
+}