@jmoyers/harness 0.1.9 → 0.1.11

package/src/cli/default-gateway-pointer.ts

@@ -0,0 +1,193 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { resolveHarnessConfigDirectory } from '../config/config-core.ts';
+import type { GatewayRecord } from './gateway-record.ts';
+
+const DEFAULT_GATEWAY_POINTER_VERSION = 1;
+const DEFAULT_GATEWAY_RECORD_PATH_PATTERN = /[\\/]gateway\.json$/u;
+const NAMED_SESSION_GATEWAY_RECORD_PATH_PATTERN = /[\\/]sessions[\\/][^\\/]+[\\/]gateway\.json$/u;
+
+const DEFAULT_GATEWAY_POINTER_FILE_NAME = 'default-gateway.json';
+
+interface DefaultGatewayPointerRecord {
+  readonly version: number;
+  readonly workspaceRoot: string;
+  readonly workspaceRuntimeRoot: string;
+  readonly gatewayRecordPath: string;
+  readonly gatewayLogPath: string;
+  readonly stateDbPath: string;
+  readonly pid: number;
+  readonly startedAt: string;
+  readonly updatedAt: string;
+  readonly gatewayRunId?: string;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return null;
+  }
+  return value as Record<string, unknown>;
+}
+
+function readNonEmptyString(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function readPositiveInt(value: unknown): number | null {
+  if (typeof value !== 'number' || !Number.isFinite(value) || !Number.isInteger(value)) {
+    return null;
+  }
+  return value > 0 ? value : null;
+}
+
+function isDefaultGatewayRecordPath(recordPath: string): boolean {
+  const normalizedPath = resolve(recordPath);
+  return (
+    DEFAULT_GATEWAY_RECORD_PATH_PATTERN.test(normalizedPath) &&
+    !NAMED_SESSION_GATEWAY_RECORD_PATH_PATTERN.test(normalizedPath)
+  );
+}
+
+export function resolveDefaultGatewayPointerPath(
+  invocationDirectory: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  return resolve(
+    resolveHarnessConfigDirectory(invocationDirectory, env),
+    DEFAULT_GATEWAY_POINTER_FILE_NAME,
+  );
+}
+
+export function parseDefaultGatewayPointerText(text: string): DefaultGatewayPointerRecord | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  const record = asRecord(parsed);
+  if (record === null) {
+    return null;
+  }
+  if (record['version'] !== DEFAULT_GATEWAY_POINTER_VERSION) {
+    return null;
+  }
+  const workspaceRoot = readNonEmptyString(record['workspaceRoot']);
+  const workspaceRuntimeRoot = readNonEmptyString(record['workspaceRuntimeRoot']);
+  const gatewayRecordPath = readNonEmptyString(record['gatewayRecordPath']);
+  const gatewayLogPath = readNonEmptyString(record['gatewayLogPath']);
+  const stateDbPath = readNonEmptyString(record['stateDbPath']);
+  const startedAt = readNonEmptyString(record['startedAt']);
+  const updatedAt = readNonEmptyString(record['updatedAt']);
+  const pid = readPositiveInt(record['pid']);
+  const gatewayRunIdRaw = record['gatewayRunId'];
+  const gatewayRunId =
+    gatewayRunIdRaw === undefined ? undefined : readNonEmptyString(gatewayRunIdRaw);
+
+  if (
+    workspaceRoot === null ||
+    workspaceRuntimeRoot === null ||
+    gatewayRecordPath === null ||
+    gatewayLogPath === null ||
+    stateDbPath === null ||
+    startedAt === null ||
+    updatedAt === null ||
+    pid === null ||
+    (gatewayRunIdRaw !== undefined && gatewayRunId === null)
+  ) {
+    return null;
+  }
+  const parsedGatewayRunId = gatewayRunId === null ? undefined : gatewayRunId;
+
+  return {
+    version: DEFAULT_GATEWAY_POINTER_VERSION,
+    workspaceRoot,
+    workspaceRuntimeRoot,
+    gatewayRecordPath,
+    gatewayLogPath,
+    stateDbPath,
+    pid,
+    startedAt,
+    updatedAt,
+    ...(parsedGatewayRunId === undefined ? {} : { gatewayRunId: parsedGatewayRunId }),
+  };
+}
+
+export function readDefaultGatewayPointer(
+  invocationDirectory: string,
+  env: NodeJS.ProcessEnv = process.env,
+): DefaultGatewayPointerRecord | null {
+  const pointerPath = resolveDefaultGatewayPointerPath(invocationDirectory, env);
+  if (!existsSync(pointerPath)) {
+    return null;
+  }
+  try {
+    return parseDefaultGatewayPointerText(readFileSync(pointerPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function writeDefaultGatewayPointerFromGatewayRecord(
+  recordPath: string,
+  record: GatewayRecord,
+  env: NodeJS.ProcessEnv = process.env,
+): void {
+  if (!isDefaultGatewayRecordPath(recordPath)) {
+    return;
+  }
+  const normalizedRecordPath = resolve(recordPath);
+  const pointerPath = resolveDefaultGatewayPointerPath(record.workspaceRoot, env);
+  const payload: DefaultGatewayPointerRecord = {
+    version: DEFAULT_GATEWAY_POINTER_VERSION,
+    workspaceRoot: record.workspaceRoot,
+    workspaceRuntimeRoot: dirname(normalizedRecordPath),
+    gatewayRecordPath: normalizedRecordPath,
+    gatewayLogPath: resolve(dirname(normalizedRecordPath), 'gateway.log'),
+    stateDbPath: record.stateDbPath,
+    pid: record.pid,
+    startedAt: record.startedAt,
+    updatedAt: new Date().toISOString(),
+    ...(record.gatewayRunId == null ? {} : { gatewayRunId: record.gatewayRunId }),
+  };
+  mkdirSync(dirname(pointerPath), { recursive: true });
+  writeFileSync(pointerPath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+}
+
+export function clearDefaultGatewayPointerForRecordPath(
+  recordPath: string,
+  invocationDirectory: string = process.cwd(),
+  env: NodeJS.ProcessEnv = process.env,
+): void {
+  if (!isDefaultGatewayRecordPath(recordPath)) {
+    return;
+  }
+  const pointerPath = resolveDefaultGatewayPointerPath(invocationDirectory, env);
+  if (!existsSync(pointerPath)) {
+    return;
+  }
+  let pointer: DefaultGatewayPointerRecord | null = null;
+  try {
+    pointer = parseDefaultGatewayPointerText(readFileSync(pointerPath, 'utf8'));
+  } catch {
+    pointer = null;
+  }
+  if (pointer === null) {
+    return;
+  }
+  if (resolve(pointer.gatewayRecordPath) !== resolve(recordPath)) {
+    return;
+  }
+  try {
+    unlinkSync(pointerPath);
+  } catch (error: unknown) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code !== 'ENOENT') {
+      throw error;
+    }
+  }
+}

package/src/cli/gateway-record.ts

@@ -6,6 +6,7 @@ export const DEFAULT_GATEWAY_PORT = 7777;
 export const DEFAULT_GATEWAY_DB_PATH = '.harness/control-plane.sqlite';
 export const DEFAULT_GATEWAY_RECORD_PATH = '.harness/gateway.json';
 export const DEFAULT_GATEWAY_LOG_PATH = '.harness/gateway.log';
+export const DEFAULT_GATEWAY_LOCK_PATH = '.harness/gateway.lock';
 
 export interface GatewayRecord {
   readonly version: number;
@@ -16,6 +17,7 @@ export interface GatewayRecord {
   readonly stateDbPath: string;
   readonly startedAt: string;
   readonly workspaceRoot: string;
+  readonly gatewayRunId?: string;
 }
 
 function asRecord(value: unknown): Record<string, unknown> | null {
@@ -74,6 +76,13 @@ export function resolveGatewayLogPath(
   return resolveHarnessRuntimePath(workspaceRoot, DEFAULT_GATEWAY_LOG_PATH, env);
 }
 
+export function resolveGatewayLockPath(
+  workspaceRoot: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  return resolveHarnessRuntimePath(workspaceRoot, DEFAULT_GATEWAY_LOCK_PATH, env);
+}
+
 export function normalizeGatewayHost(
   input: string | null | undefined,
   fallback = DEFAULT_GATEWAY_HOST,
@@ -149,6 +158,9 @@ export function parseGatewayRecordText(text: string): GatewayRecord | null {
   const workspaceRoot = readNonEmptyString(record['workspaceRoot']);
   const authTokenRaw = record['authToken'];
   const authToken = authTokenRaw === null ? null : readNonEmptyString(authTokenRaw);
+  const gatewayRunIdRaw = record['gatewayRunId'];
+  const gatewayRunId =
+    gatewayRunIdRaw === undefined ? undefined : readNonEmptyString(gatewayRunIdRaw);
 
   if (
     pid === null ||
@@ -157,10 +169,12 @@ export function parseGatewayRecordText(text: string): GatewayRecord | null {
     stateDbPath === null ||
     startedAt === null ||
     workspaceRoot === null ||
-    (authToken === null && authTokenRaw !== null)
+    (authToken === null && authTokenRaw !== null) ||
+    (gatewayRunIdRaw !== undefined && gatewayRunId === null)
   ) {
     return null;
   }
+  const parsedGatewayRunId = gatewayRunId === null ? undefined : gatewayRunId;
 
   return {
     version,
@@ -171,6 +185,7 @@ export function parseGatewayRecordText(text: string): GatewayRecord | null {
     stateDbPath,
     startedAt,
     workspaceRoot,
+    ...(parsedGatewayRunId === undefined ? {} : { gatewayRunId: parsedGatewayRunId }),
   };
 }
 

package/src/config/config-core.ts

@@ -7,6 +7,7 @@ import {
   unlinkSync,
   writeFileSync,
 } from 'node:fs';
+import { homedir } from 'node:os';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -1435,14 +1436,24 @@ export function resolveHarnessConfigDirectory(
   env: NodeJS.ProcessEnv = process.env,
 ): string {
   const xdgConfigHome = readNonEmptyEnvPath(env.XDG_CONFIG_HOME);
+  const homeDirectory = readNonEmptyEnvPath(env.HOME) ?? readNonEmptyEnvPath(homedir());
+  return resolveHarnessConfigDirectoryFromRoots(cwd, xdgConfigHome, homeDirectory);
+}
+
+export function resolveHarnessConfigDirectoryFromRoots(
+  cwd: string,
+  xdgConfigHome: string | null,
+  homeDirectory: string | null,
+): string {
   if (xdgConfigHome !== null) {
     return resolve(xdgConfigHome, HARNESS_CONFIG_XDG_DIRECTORY_NAME);
   }
-  const homeDirectory = readNonEmptyEnvPath(env.HOME);
   if (homeDirectory !== null) {
     return resolve(homeDirectory, HARNESS_CONFIG_HOME_DIRECTORY_NAME);
   }
-  return resolve(cwd, HARNESS_CONFIG_HOME_DIRECTORY_NAME);
+  throw new Error(
+    `unable to resolve harness config directory: HOME and XDG_CONFIG_HOME are unset (cwd=${cwd})`,
+  );
 }
 
 export function resolveHarnessConfigPath(

package/src/config/harness-paths.ts

@@ -39,11 +39,7 @@ export function resolveHarnessWorkspaceDirectory(
   invocationDirectory: string,
   env: NodeJS.ProcessEnv = process.env,
 ): string {
-  const legacyWorkspaceDirectory = resolveLegacyHarnessDirectory(invocationDirectory);
   const configDirectory = resolveHarnessConfigDirectory(invocationDirectory, env);
-  if (resolve(configDirectory) === legacyWorkspaceDirectory) {
-    return legacyWorkspaceDirectory;
-  }
   return resolve(
     configDirectory,
     HARNESS_WORKSPACES_DIRECTORY,
@@ -74,13 +70,14 @@ export function resolveHarnessRuntimePath(
   pathValue: string,
   env: NodeJS.ProcessEnv = process.env,
 ): string {
+  const workspaceRuntimeDirectory = resolveHarnessWorkspaceDirectory(invocationDirectory, env);
   const normalizedPath = pathValue.trim();
   if (normalizedPath.length === 0 || normalizedPath === HARNESS_LEGACY_RELATIVE_ROOT) {
-    return resolveHarnessWorkspaceDirectory(invocationDirectory, env);
+    return workspaceRuntimeDirectory;
   }
   if (normalizedPath.startsWith(`${HARNESS_LEGACY_RELATIVE_ROOT}/`)) {
     return resolve(
-      resolveHarnessWorkspaceDirectory(invocationDirectory, env),
+      workspaceRuntimeDirectory,
       normalizedPath.slice(`${HARNESS_LEGACY_RELATIVE_ROOT}/`.length),
     );
   }
@@ -88,5 +85,5 @@ export function resolveHarnessRuntimePath(
   if (expandedHomePath !== null) {
     return expandedHomePath;
   }
-  return resolve(invocationDirectory, normalizedPath);
+  return resolve(workspaceRuntimeDirectory, normalizedPath);
 }

package/src/config/harness-runtime-migration.ts

@@ -1,6 +1,20 @@
-import { copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
+import {
+  copyFileSync,
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
 import { dirname, resolve } from 'node:path';
-import { HARNESS_CONFIG_FILE_NAME, resolveHarnessConfigDirectory } from './config-core.ts';
+import {
+  DEFAULT_HARNESS_CONFIG,
+  HARNESS_CONFIG_FILE_NAME,
+  parseHarnessConfigText,
+  resolveHarnessConfigDirectory,
+} from './config-core.ts';
 import {
   resolveHarnessWorkspaceDirectory,
   resolveLegacyHarnessDirectory,
@@ -8,6 +22,7 @@ import {
 
 const LEGACY_SECRETS_FILE_NAME = 'secrets.env';
 const MIGRATION_MARKER_FILE_NAME = '.legacy-layout-migration-v1';
+const MIGRATION_CONFIG_BACKUP_FILE_NAME = `${HARNESS_CONFIG_FILE_NAME}.pre-migration.bak`;
 const LEGACY_RUNTIME_EXCLUDE_NAMES = new Set([
   HARNESS_CONFIG_FILE_NAME,
   LEGACY_SECRETS_FILE_NAME,
@@ -18,9 +33,18 @@ interface HarnessLegacyLayoutMigrationResult {
   readonly migrated: boolean;
   readonly migratedEntries: number;
   readonly configCopied: boolean;
+  readonly configReplacedExisting: boolean;
+  readonly configBackupPath: string | null;
   readonly secretsCopied: boolean;
   readonly skipped: boolean;
   readonly markerPath: string;
+  readonly legacyRootRemoved: boolean;
+}
+
+interface ConfigCopyResult {
+  readonly copied: boolean;
+  readonly replacedExisting: boolean;
+  readonly backupPath: string | null;
 }
 
 function copyFileIfMissing(sourcePath: string, targetPath: string): boolean {
@@ -46,11 +70,96 @@ function copyEntryIfMissing(sourcePath: string, targetPath: string): boolean {
   return !targetExisted;
 }
 
+function configEqualsDefaultConfig(text: string): boolean {
+  try {
+    const parsed = parseHarnessConfigText(text);
+    return JSON.stringify(parsed) === JSON.stringify(DEFAULT_HARNESS_CONFIG);
+  } catch {
+    return false;
+  }
+}
+
+function copyConfigIfGlobalUninitialized(sourcePath: string, targetPath: string): ConfigCopyResult {
+  if (!existsSync(sourcePath)) {
+    return {
+      copied: false,
+      replacedExisting: false,
+      backupPath: null,
+    };
+  }
+  if (!existsSync(targetPath)) {
+    mkdirSync(dirname(targetPath), { recursive: true });
+    copyFileSync(sourcePath, targetPath);
+    return {
+      copied: true,
+      replacedExisting: false,
+      backupPath: null,
+    };
+  }
+
+  const targetText = readFileSync(targetPath, 'utf8');
+  const targetUninitialized =
+    targetText.trim().length === 0 || configEqualsDefaultConfig(targetText);
+  if (!targetUninitialized) {
+    return {
+      copied: false,
+      replacedExisting: false,
+      backupPath: null,
+    };
+  }
+
+  const backupPath = resolve(dirname(targetPath), MIGRATION_CONFIG_BACKUP_FILE_NAME);
+  if (!existsSync(backupPath)) {
+    copyFileSync(targetPath, backupPath);
+  }
+  copyFileSync(sourcePath, targetPath);
+  return {
+    copied: true,
+    replacedExisting: true,
+    backupPath,
+  };
+}
+
 function writeMigrationMarker(markerPath: string): void {
   mkdirSync(dirname(markerPath), { recursive: true });
   writeFileSync(markerPath, `${new Date().toISOString()}\n`, 'utf8');
 }
 
+function removeLegacyRootIfSafe(
+  legacyRoot: string,
+  configDirectory: string,
+  workspaceDirectory: string,
+): boolean {
+  if (!existsSync(legacyRoot) || resolve(configDirectory) === legacyRoot) {
+    return false;
+  }
+
+  const legacyEntries = readdirSync(legacyRoot, { withFileTypes: true }).map((entry) => entry.name);
+  for (const entryName of legacyEntries) {
+    if (entryName === HARNESS_CONFIG_FILE_NAME) {
+      if (!existsSync(resolve(configDirectory, HARNESS_CONFIG_FILE_NAME))) {
+        return false;
+      }
+      continue;
+    }
+    if (entryName === LEGACY_SECRETS_FILE_NAME) {
+      if (!existsSync(resolve(configDirectory, LEGACY_SECRETS_FILE_NAME))) {
+        return false;
+      }
+      continue;
+    }
+    if (entryName === 'workspaces') {
+      continue;
+    }
+    if (!existsSync(resolve(workspaceDirectory, entryName))) {
+      return false;
+    }
+  }
+
+  rmSync(legacyRoot, { recursive: true, force: true });
+  return !existsSync(legacyRoot);
+}
+
 export function migrateLegacyHarnessLayout(
   invocationDirectory: string,
   env: NodeJS.ProcessEnv = process.env,
@@ -60,7 +169,7 @@ export function migrateLegacyHarnessLayout(
   const workspaceDirectory = resolveHarnessWorkspaceDirectory(invocationDirectory, env);
   const markerPath = resolve(workspaceDirectory, MIGRATION_MARKER_FILE_NAME);
 
-  const configCopied = copyFileIfMissing(
+  const configCopy = copyConfigIfGlobalUninitialized(
     resolve(legacyRoot, HARNESS_CONFIG_FILE_NAME),
     resolve(configDirectory, HARNESS_CONFIG_FILE_NAME),
   );
@@ -68,38 +177,50 @@ export function migrateLegacyHarnessLayout(
     resolve(legacyRoot, LEGACY_SECRETS_FILE_NAME),
     resolve(configDirectory, LEGACY_SECRETS_FILE_NAME),
   );
+  const withCleanupResult = (
+    result: Omit<HarnessLegacyLayoutMigrationResult, 'legacyRootRemoved'>,
+  ): HarnessLegacyLayoutMigrationResult => ({
+    ...result,
+    legacyRootRemoved: removeLegacyRootIfSafe(legacyRoot, configDirectory, workspaceDirectory),
+  });
 
   if (resolve(configDirectory) === legacyRoot) {
-    return {
-      migrated: configCopied || secretsCopied,
+    return withCleanupResult({
+      migrated: configCopy.copied || secretsCopied,
       migratedEntries: 0,
-      configCopied,
+      configCopied: configCopy.copied,
+      configReplacedExisting: configCopy.replacedExisting,
+      configBackupPath: configCopy.backupPath,
       secretsCopied,
       skipped: true,
       markerPath,
-    };
+    });
   }
 
   if (!existsSync(legacyRoot)) {
-    return {
-      migrated: configCopied || secretsCopied,
+    return withCleanupResult({
+      migrated: configCopy.copied || secretsCopied,
       migratedEntries: 0,
-      configCopied,
+      configCopied: configCopy.copied,
+      configReplacedExisting: configCopy.replacedExisting,
+      configBackupPath: configCopy.backupPath,
       secretsCopied,
       skipped: true,
       markerPath,
-    };
+    });
   }
 
   if (existsSync(markerPath)) {
-    return {
-      migrated: configCopied || secretsCopied,
+    return withCleanupResult({
+      migrated: configCopy.copied || secretsCopied,
       migratedEntries: 0,
-      configCopied,
+      configCopied: configCopy.copied,
+      configReplacedExisting: configCopy.replacedExisting,
+      configBackupPath: configCopy.backupPath,
       secretsCopied,
       skipped: true,
       markerPath,
-    };
+    });
   }
 
   const legacyEntries = readdirSync(legacyRoot, { withFileTypes: true })
@@ -119,12 +240,14 @@ export function migrateLegacyHarnessLayout(
     writeMigrationMarker(markerPath);
   }
 
-  return {
-    migrated: configCopied || secretsCopied || migratedEntries > 0,
+  return withCleanupResult({
+    migrated: configCopy.copied || secretsCopied || migratedEntries > 0,
     migratedEntries,
-    configCopied,
+    configCopied: configCopy.copied,
+    configReplacedExisting: configCopy.replacedExisting,
+    configBackupPath: configCopy.backupPath,
     secretsCopied,
     skipped: false,
     markerPath,
-  };
+  });
 }

package/src/config/secrets-core.ts

@@ -1,9 +1,7 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
 import { resolveHarnessConfigDirectory } from './config-core.ts';
 
-export const HARNESS_SECRETS_FILE_PATH = '.harness/secrets.env';
-
 interface HarnessSecretEntry {
   readonly key: string;
   readonly value: string;
@@ -23,6 +21,20 @@ interface LoadedHarnessSecrets {
   readonly skippedKeys: readonly string[];
 }
 
+interface UpsertHarnessSecretOptions {
+  readonly key: string;
+  readonly value: string;
+  readonly cwd?: string;
+  readonly filePath?: string;
+  readonly env?: NodeJS.ProcessEnv;
+}
+
+interface UpsertHarnessSecretResult {
+  readonly filePath: string;
+  readonly createdFile: boolean;
+  readonly replacedExisting: boolean;
+}
+
 function isValidSecretKey(value: string): boolean {
   return /^[A-Za-z_][A-Za-z0-9_]*$/u.test(value);
 }
@@ -107,6 +119,38 @@ function parseLineValue(rawValue: string, lineNumber: number): string {
   return rawValue.replace(/\s+#.*$/u, '').trim();
 }
 
+function parseSecretLineKey(line: string): string | null {
+  const trimmed = line.trim();
+  if (trimmed.length === 0 || trimmed.startsWith('#')) {
+    return null;
+  }
+  const withoutExport = trimmed.startsWith('export ')
+    ? trimmed.slice('export '.length).trimStart()
+    : trimmed;
+  const equalIndex = withoutExport.indexOf('=');
+  if (equalIndex <= 0) {
+    return null;
+  }
+  const key = withoutExport.slice(0, equalIndex).trim();
+  return isValidSecretKey(key) ? key : null;
+}
+
+function encodeSecretValue(value: string): string {
+  if (value.length === 0) {
+    return '""';
+  }
+  if (/^[A-Za-z0-9._:@/+,-]+$/u.test(value)) {
+    return value;
+  }
+  const escaped = value
+    .replaceAll('\\', '\\\\')
+    .replaceAll('"', '\\"')
+    .replaceAll('\n', '\\n')
+    .replaceAll('\r', '\\r')
+    .replaceAll('\t', '\\t');
+  return `"${escaped}"`;
+}
+
 function parseHarnessSecretLine(line: string, lineNumber: number): HarnessSecretEntry | null {
   const trimmed = line.trim();
   if (trimmed.length === 0 || trimmed.startsWith('#')) {
@@ -186,3 +230,47 @@ export function loadHarnessSecrets(options: LoadHarnessSecretsOptions = {}): Loa
     skippedKeys,
   };
 }
+
+export function upsertHarnessSecret(
+  options: UpsertHarnessSecretOptions,
+): UpsertHarnessSecretResult {
+  const key = options.key.trim();
+  if (!isValidSecretKey(key)) {
+    throw new Error(`invalid secret key: ${options.key}`);
+  }
+  const cwd = options.cwd ?? process.cwd();
+  const env = options.env ?? process.env;
+  const filePath = resolveHarnessSecretsPath(cwd, options.filePath, env);
+  const hadFile = existsSync(filePath);
+  const existingText = hadFile ? readFileSync(filePath, 'utf8') : '';
+  const sourceLines = existingText.split(/\r?\n/u);
+  if (sourceLines[sourceLines.length - 1] === '') {
+    sourceLines.pop();
+  }
+  const nextLines: string[] = [];
+  const encoded = encodeSecretValue(options.value);
+  let replacedExisting = false;
+  for (const line of sourceLines) {
+    const lineKey = parseSecretLineKey(line);
+    if (lineKey !== key) {
+      nextLines.push(line);
+      continue;
+    }
+    if (!replacedExisting) {
+      nextLines.push(`${key}=${encoded}`);
+      replacedExisting = true;
+    }
+  }
+  if (!replacedExisting) {
+    nextLines.push(`${key}=${encoded}`);
+  }
+  mkdirSync(dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.tmp.${String(process.pid)}`;
+  writeFileSync(tempPath, `${nextLines.join('\n')}\n`, 'utf8');
+  renameSync(tempPath, filePath);
+  return {
+    filePath,
+    createdFile: !hadFile,
+    replacedExisting,
+  };
+}