From ff1b5ab384d90c419c7169d543515ce0e4109c91 Mon Sep 17 00:00:00 2001
From: Codex <codex@noreply.local>
Date: Sat, 16 May 2026 12:39:54 +0000
Subject: [PATCH] fix: make deploy help non-mutating

---
 scripts/src/deploy.ts | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/scripts/src/deploy.ts b/scripts/src/deploy.ts
index 2f87c7f6..c73612df 100644
--- a/scripts/src/deploy.ts
+++ b/scripts/src/deploy.ts
@@ -86,6 +86,36 @@ const nativeK3sInstallVersion = "v1.34.1+k3s1";
 const nativeK3sImage = "rancher/k3s:v1.34.1-k3s1";
 const nativeK3sCtrAddress = "/run/k3s/containerd/containerd.sock";
 
+function isHelpArg(value: string | undefined): boolean {
+  return value === "help" || value === "--help" || value === "-h";
+}
+
+function deployHelp(action: string | undefined = undefined): Record<string, unknown> {
+  const command = action === undefined || isHelpArg(action) ? "deploy check|plan|apply" : `deploy ${action}`;
+  return {
+    ok: true,
+    command,
+    usage: {
+      check: "bun scripts/cli.ts deploy check [--file deploy.json] [--service id]",
+      plan: "bun scripts/cli.ts deploy plan [--file deploy.json] [--service id]",
+      apply: "bun scripts/cli.ts deploy apply [--file deploy.json] [--service id] [--dry-run] [--force] [--timeout-ms N] [--run-now]",
+    },
+    actions: {
+      check: "Validate desired repo+commit state against live service health and commit markers.",
+      plan: "Show desired/live drift without requiring live health to be healthy.",
+      apply: "Start an async target-side reconcile job unless --run-now is explicitly present.",
+    },
+    options: [
+      { name: "--file <path>", default: defaultDeployFile, description: "Desired-state manifest path relative to the repo root." },
+      { name: "--service <id>", description: "Limit reconcile to one service from the manifest." },
+      { name: "--dry-run", description: "Prepare and validate without mutating the target service." },
+      { name: "--force", description: "Redeploy even when the live commit appears up to date." },
+      { name: "--timeout-ms <n>", default: defaultTimeoutMs, description: "Per-step timeout budget where supported." },
+      { name: "--run-now", description: "Run apply in the foreground worker process; omit it for fire-and-forget async job mode." },
+    ],
+  };
+}
+
 function nowIso(): string {
   return new Date().toISOString();
 }
@@ -1166,6 +1196,7 @@ function applyJob(config: UniDeskConfig, args: string[], options: DeployOptions)
 
 export async function runDeployCommand(config: UniDeskConfig, args: string[]): Promise<unknown> {
   const [actionRaw = "check"] = args;
+  if (isHelpArg(actionRaw) || args.slice(1).some(isHelpArg)) return deployHelp(isHelpArg(actionRaw) ? undefined : actionRaw);
   if (!["check", "plan", "apply"].includes(actionRaw)) throw new Error("deploy command must be one of: check, plan, apply");
   const action = actionRaw as DeployAction;
   const options = parseOptions(args.slice(1));