@hexclave/cli 1.0.51 → 1.0.52

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hexclave/cli",
-  "version": "1.0.51",
+  "version": "1.0.52",
   "repository": "https://github.com/hexclave/hexclave",
   "description": "The CLI for Hexclave. https://hexclave.com",
   "main": "dist/index.js",
@@ -25,9 +25,9 @@
     "commander": "^13.1.0",
     "extract-zip": "^2.0.1",
     "jiti": "^2.4.2",
-    "@hexclave/shared-backend": "1.0.51",
-    "@hexclave/js": "1.0.51",
-    "@hexclave/shared": "1.0.51"
+    "@hexclave/shared-backend": "1.0.52",
+    "@hexclave/js": "1.0.52",
+    "@hexclave/shared": "1.0.52"
   },
   "devDependencies": {
     "@types/node": "20.17.6",

package/src/commands/config-file.test.ts

@@ -2,7 +2,7 @@ import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { buildConfigPushSource, resolveConfigFilePathForPull, shouldReplaceConfigFileForPull } from "./config-file.js";
+import { assertConfigPullTarget, buildConfigPushSource, resolveConfigFilePathForPull } from "./config-file.js";
 
 describe("resolveConfigFilePathForPull", () => {
   let tmpDir: string;
@@ -46,7 +46,7 @@ describe("resolveConfigFilePathForPull", () => {
   });
 });
 
-describe("shouldReplaceConfigFileForPull", () => {
+describe("assertConfigPullTarget", () => {
   let tmpDir: string;
 
   beforeEach(() => {
@@ -57,16 +57,26 @@ describe("shouldReplaceConfigFileForPull", () => {
     fs.rmSync(tmpDir, { recursive: true, force: true });
   });
 
-  it("updates an existing config in place unless overwrite is explicit", () => {
+  it("does not throw when the target file does not exist", () => {
+    expect(() => assertConfigPullTarget(path.join(tmpDir, "hexclave.config.ts"), {})).not.toThrow();
+  });
+
+  it("throws when the target file already exists and --overwrite is not set", () => {
     const configPath = path.join(tmpDir, "hexclave.config.ts");
     fs.writeFileSync(configPath, "export const config = {};\n");
+    expect(() => assertConfigPullTarget(configPath, {})).toThrow(/already exists.*--overwrite/s);
+  });
 
-    expect(shouldReplaceConfigFileForPull(configPath, {})).toBe(false);
-    expect(shouldReplaceConfigFileForPull(configPath, { overwrite: true })).toBe(true);
+  it("throws for an existing placeholder/comment-only file without --overwrite", () => {
+    const configPath = path.join(tmpDir, "stack.config.ts");
+    fs.writeFileSync(configPath, "// placeholder so the file exists\n");
+    expect(() => assertConfigPullTarget(configPath, {})).toThrow(/already exists/);
   });
 
-  it("replaces when pull needs to create a new config file", () => {
-    expect(shouldReplaceConfigFileForPull(path.join(tmpDir, "hexclave.config.ts"), {})).toBe(true);
+  it("does not throw when --overwrite is set, even if the file exists", () => {
+    const configPath = path.join(tmpDir, "hexclave.config.ts");
+    fs.writeFileSync(configPath, "export const config = {};\n");
+    expect(() => assertConfigPullTarget(configPath, { overwrite: true })).not.toThrow();
   });
 });
 

package/src/commands/config-file.ts

@@ -1,4 +1,4 @@
-import { replaceConfigObject, updateConfigObject } from "@hexclave/shared-backend";
+import { replaceConfigObject } from "@hexclave/shared-backend";
 import { detectImportPackageFromDir } from "@hexclave/shared/dist/config-eval";
 import { isValidConfig } from "@hexclave/shared/dist/config/format";
 import type { EnvironmentConfigOverrideOverride } from "@hexclave/shared/dist/config/schema";
@@ -217,8 +217,20 @@ export function resolveConfigFilePathForPull(opts: { configFile?: string }, cwd:
   return candidate;
 }
 
-export function shouldReplaceConfigFileForPull(filePath: string, opts: { overwrite?: boolean }): boolean {
-  return opts.overwrite === true || !fs.existsSync(filePath);
+// `config pull` means "download the entire branch config into a fresh local file". It always writes
+// the whole file (via replaceConfigObject) and never edits an existing file in place. In-place,
+// hand-authored-preserving edits are the job of the config *update* flow (e.g. from the RDE), which
+// routes through updateConfigObject's agent-assisted rewrite — that path is intentionally not
+// reachable from `pull`.
+//
+// Because pull writes the whole file, it would clobber whatever is already at the target path. To
+// avoid silently destroying a hand-authored config, we refuse to write over an existing file and
+// require the user to opt in explicitly with --overwrite.
+export function assertConfigPullTarget(filePath: string, opts: { overwrite?: boolean }): void {
+  if (opts.overwrite === true) return;
+  if (fs.existsSync(filePath)) {
+    throw new CliError(`A config file already exists at ${filePath}. Pass --overwrite to replace it with the pulled config, or remove the file first.`);
+  }
 }
 
 export function registerConfigCommand(program: Command) {
@@ -231,30 +243,28 @@ export function registerConfigCommand(program: Command) {
     .description("Pull branch config to a local file")
     .option("--cloud-project-id <id>", "Cloud project ID to pull config from (defaults to the STACK_PROJECT_ID env var)")
     .option("--config-file <path>", "Path to write config file (.ts); defaults to ./hexclave.config.ts in the current directory")
-    .option("--overwrite", "Overwrite an existing config file instead of updating it in place")
+    .option("--overwrite", "Replace the config file if one already exists at the target path")
     .action(async (opts) => {
       const auth = resolveAuth(resolveProjectId(opts.cloudProjectId));
       if (!isProjectAuthWithRefreshToken(auth)) {
         throw new CliError("`hexclave config pull` requires `hexclave login`. Remove STACK_SECRET_SERVER_KEY and try again.");
       }
-      const project = await getAdminProject(auth);
-
-      const configOverride = await project.getConfigOverride("branch");
-      if (!isValidConfig(configOverride)) {
-        throw new CliError("Pulled branch config is not a valid local config object.");
-      }
+      // Resolve and validate the target file before any network work so we fail fast (e.g. when the
+      // target already exists without --overwrite) instead of paying for a wasted round-trip.
       const filePath = resolveConfigFilePathForPull(opts, process.cwd());
       const ext = path.extname(filePath);
-
       if (ext !== ".ts") {
         throw new CliError("Config file must have a .ts extension. Typed config files require TypeScript.");
       }
+      assertConfigPullTarget(filePath, opts);
 
-      if (shouldReplaceConfigFileForPull(filePath, opts)) {
-        await replaceConfigObject(filePath, configOverride);
-      } else {
-        await updateConfigObject(filePath, configOverride);
+      const project = await getAdminProject(auth);
+
+      const configOverride = await project.getConfigOverride("branch");
+      if (!isValidConfig(configOverride)) {
+        throw new CliError("Pulled branch config is not a valid local config object.");
       }
+      await replaceConfigObject(filePath, configOverride);
       console.log(`Config written to ${filePath}`);
     });