@stigmer/cli 3.0.8

package/src/resources/run/attachments.ts

@@ -0,0 +1,261 @@
+// Attachment processing for agent execution.
+//
+// Ports the Go CLI's run_attachments.go + run_attachments_zip.go. Each `--attach`
+// path is either recorded as a workspace-relative reference (when it lives inside
+// a local workspace root — no upload, the agent reads it directly) or uploaded
+// via the UploadAttachment RPC and returned as an Attachment proto. Directories
+// are zipped (hidden entries and symlinks skipped) and capped at 10 MB to match
+// the server's gRPC receive limit.
+
+import { readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { extname, join, relative, resolve, sep } from "node:path";
+import { create } from "@bufbuild/protobuf";
+import { zipSync } from "fflate";
+import { type Attachment, AttachmentSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+import {
+  type UploadAttachmentRequest,
+  UploadAttachmentRequestSchema,
+  type UploadAttachmentResponse,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { UsageError } from "../../errors/index.js";
+
+// Must match the server's grpc.MaxRecvMsgSize (Go: maxAttachmentSize).
+const MAX_ATTACHMENT_SIZE = 10 * 1024 * 1024; // 10 MB
+
+/** A sink for human progress/warning lines (attachments are not byte-parity output). */
+export type ProgressSink = (line: string) => void;
+
+/** The minimal UploadAttachment RPC surface, injectable for testing. */
+export interface AttachmentUploader {
+  uploadAttachment(req: UploadAttachmentRequest): Promise<UploadAttachmentResponse>;
+}
+
+/**
+ * The split result of processing `--attach` paths. Mirrors Go's
+ * AttachmentResult: in-workspace files become relative references, everything
+ * else becomes an uploaded Attachment.
+ */
+export interface AttachmentResult {
+  readonly attachments: Attachment[];
+  readonly workspaceFileRefs: string[];
+}
+
+/**
+ * Process `--attach` paths against the local workspace roots. The first root a
+ * path falls inside wins and yields a workspace-relative reference; otherwise
+ * the path is uploaded. Mirrors Go's AttachmentProcessor.ProcessFiles.
+ */
+export async function processAttachments(
+  uploader: AttachmentUploader,
+  paths: readonly string[],
+  workspaceRoots: readonly string[],
+  progress?: ProgressSink,
+): Promise<AttachmentResult> {
+  const attachments: Attachment[] = [];
+  const workspaceFileRefs: string[] = [];
+  if (paths.length === 0) return { attachments, workspaceFileRefs };
+
+  for (const path of paths) {
+    const rel = matchWorkspaceRoot(path, workspaceRoots);
+    if (rel !== null) {
+      progress?.(`Referencing workspace file: ${rel}`);
+      workspaceFileRefs.push(rel);
+      continue;
+    }
+    attachments.push(await processFile(uploader, path, progress));
+  }
+
+  return { attachments, workspaceFileRefs };
+}
+
+// Returns the workspace-relative path if `path` is inside any root (first match
+// wins), else null. Mirrors Go's matchWorkspaceRoot + workspaceRelativePath:
+// both sides are resolved through realpath to prevent symlink escapes.
+function matchWorkspaceRoot(path: string, roots: readonly string[]): string | null {
+  for (const root of roots) {
+    let evalFile: string;
+    let evalRoot: string;
+    try {
+      evalFile = realpathSync(resolve(path));
+      evalRoot = realpathSync(root);
+    } catch {
+      continue; // unresolvable path is treated as outside this root
+    }
+    if (evalFile === evalRoot || evalFile.startsWith(evalRoot + sep)) {
+      return toSlash(relative(evalRoot, evalFile));
+    }
+  }
+  return null;
+}
+
+// Stat the path, then upload a file or zip+upload a directory. Mirrors Go's
+// processFile.
+async function processFile(uploader: AttachmentUploader, path: string, progress?: ProgressSink): Promise<Attachment> {
+  let stat: ReturnType<typeof statSync>;
+  try {
+    stat = statSync(path);
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException;
+    if (e.code === "ENOENT") throw new UsageError(`file not found: ${path}`);
+    throw new UsageError(`failed to stat attachment "${path}": ${e.message}`);
+  }
+
+  if (stat.isDirectory()) return processDirectory(uploader, path, progress);
+
+  const absPath = resolve(path);
+  const filename = basenameOf(path);
+  const contentType = detectContentType(filename);
+  progress?.(`Uploading ${filename} (${formatFileSize(stat.size)})...`);
+  const attachment = await uploadBytes(uploader, readFileSync(path), filename, contentType, progress);
+  attachment.localPath = absPath;
+  return attachment;
+}
+
+// Zip a directory (extract=true so the runner unpacks it at mount_path) and
+// upload it as one archive. Mirrors Go's processDirectory.
+async function processDirectory(uploader: AttachmentUploader, path: string, progress?: ProgressSink): Promise<Attachment> {
+  const absPath = resolve(path);
+  const dirname = basenameOf(absPath);
+
+  const { bytes, fileCount, originalSize } = zipDirectory(absPath, progress);
+  const zipSize = bytes.byteLength;
+  progress?.(
+    `Zipping directory: ${dirname}/ (${fileCount} files, ` +
+      `${formatFileSize(originalSize)} -> ${formatFileSize(zipSize)} compressed)`,
+  );
+  if (zipSize > MAX_ATTACHMENT_SIZE) {
+    throw new UsageError(
+      `zipped directory too large (${formatFileSize(zipSize)}). ` +
+        `Maximum attachment size is ${formatFileSize(MAX_ATTACHMENT_SIZE)}`,
+    );
+  }
+
+  const attachment = await uploadBytes(uploader, bytes, `${dirname}.zip`, "application/zip", progress);
+  attachment.extract = true;
+  attachment.mountPath = `inputs/${dirname}/`;
+  attachment.localPath = absPath;
+  return attachment;
+}
+
+// Upload raw bytes via the RPC and build an Attachment. Mirrors Go's uploadBytes.
+async function uploadBytes(
+  uploader: AttachmentUploader,
+  content: Uint8Array,
+  filename: string,
+  contentType: string,
+  progress?: ProgressSink,
+): Promise<Attachment> {
+  const req = create(UploadAttachmentRequestSchema, { filename, content, contentType });
+  let resp: UploadAttachmentResponse;
+  try {
+    resp = await uploader.uploadAttachment(req);
+  } catch (err) {
+    throw new UsageError(`failed to upload attachment "${filename}": ${(err as Error).message}`);
+  }
+  progress?.(`Uploaded ${filename}`);
+  return create(AttachmentSchema, { filename, storageKey: resp.storageKey, contentType });
+}
+
+interface ZipResult {
+  readonly bytes: Uint8Array;
+  readonly fileCount: number;
+  readonly originalSize: number;
+}
+
+// Build a zip of dirPath's contents, skipping hidden entries (and their
+// subtrees) and symlinks. Mirrors Go's zipDirectory.
+function zipDirectory(dirPath: string, progress?: ProgressSink): ZipResult {
+  const files: Record<string, Uint8Array> = {};
+  let fileCount = 0;
+  let originalSize = 0;
+
+  const walk = (current: string, prefix: string): void => {
+    const entries = readdirSync(current, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) continue; // hidden entry (and subtree if dir)
+      const rel = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+      const full = join(current, entry.name);
+      if (entry.isSymbolicLink()) {
+        progress?.(`Skipping symlink: ${full}`);
+        continue;
+      }
+      if (entry.isDirectory()) {
+        walk(full, rel);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const content = new Uint8Array(readFileSync(full));
+      files[rel] = content;
+      fileCount++;
+      originalSize += content.byteLength;
+    }
+  };
+  walk(dirPath, "");
+
+  if (fileCount === 0) {
+    throw new UsageError(`directory contains no attachable files: ${dirPath}`);
+  }
+
+  return { bytes: zipSync(files, { level: 6 }), fileCount, originalSize };
+}
+
+// MIME by extension. Go consults the OS mime DB first (non-deterministic across
+// hosts) and falls back to a fixed switch; we use a curated table so the result
+// is deterministic. content_type is advisory — the server re-guesses from the
+// filename when absent — so exact parity with Go's OS DB is not required.
+const MIME_BY_EXT: Readonly<Record<string, string>> = {
+  ".md": "text/markdown",
+  ".markdown": "text/markdown",
+  ".yaml": "application/x-yaml",
+  ".yml": "application/x-yaml",
+  ".toml": "application/toml",
+  ".csv": "text/csv",
+  ".tsv": "text/tab-separated-values",
+  ".log": "text/plain",
+  ".sql": "application/sql",
+  ".parquet": "application/vnd.apache.parquet",
+  ".avro": "application/avro",
+  ".json": "application/json",
+  ".txt": "text/plain",
+  ".pdf": "application/pdf",
+  ".html": "text/html",
+  ".htm": "text/html",
+  ".xml": "text/xml",
+  ".zip": "application/zip",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".js": "text/javascript",
+  ".ts": "text/plain",
+};
+
+function detectContentType(filename: string): string {
+  const ext = extname(filename).toLowerCase();
+  if (ext === "") return "application/octet-stream";
+  return MIME_BY_EXT[ext] ?? "application/octet-stream";
+}
+
+// Human-readable byte size. Mirrors Go's formatFileSize (1024-based, one decimal).
+function formatFileSize(bytes: number): string {
+  const KB = 1024;
+  const MB = KB * 1024;
+  const GB = MB * 1024;
+  if (bytes >= GB) return `${(bytes / GB).toFixed(1)} GB`;
+  if (bytes >= MB) return `${(bytes / MB).toFixed(1)} MB`;
+  if (bytes >= KB) return `${(bytes / KB).toFixed(1)} KB`;
+  return `${bytes} B`;
+}
+
+// path.basename, but resilient to trailing slashes (matches Go filepath.Base
+// semantics closely enough for display/name derivation).
+function basenameOf(p: string): string {
+  const cleaned = p.replace(/[/\\]+$/, "");
+  const idx = Math.max(cleaned.lastIndexOf("/"), cleaned.lastIndexOf("\\"));
+  return idx === -1 ? cleaned : cleaned.slice(idx + 1);
+}
+
+function toSlash(p: string): string {
+  return p.split(sep).join("/");
+}

package/src/resources/run/create.test.ts

@@ -0,0 +1,119 @@
+// Unit tests for run-path resource creation: full-proto field mapping, the
+// message default, ExecutionConfig presence/contents, runtime-env conversion,
+// and session/workflow shapes. The controller is faked to capture the exact
+// proto sent to the RPC.
+
+import { describe, expect, it } from "vitest";
+import { InteractionMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import {
+  type ControllerFn,
+  createAgentExecution,
+  createSessionForAgent,
+  createWorkflowExecution,
+} from "./create.js";
+
+// Returns a controller whose every RPC echoes the request back, and records the
+// last message sent. `create` is the only RPC the run path calls.
+function fakeController(): { fn: ControllerFn; last: () => unknown } {
+  let captured: unknown;
+  const fn = (() =>
+    ({
+      create: async (msg: unknown) => {
+        captured = msg;
+        return msg;
+      },
+    })) as unknown as ControllerFn;
+  return { fn, last: () => captured };
+}
+
+describe("createAgentExecution", () => {
+  it("maps the full spec and defaults an empty message to 'execute'", async () => {
+    const { fn } = fakeController();
+    const exec = await createAgentExecution(fn, {
+      agentId: "agt_1",
+      orgId: "acme",
+      message: "",
+      runtimeEnv: { FOO: { value: "bar", isSecret: false }, TOKEN: { value: "s", isSecret: true } },
+      attachments: [],
+      workspaceFileRefs: ["src/a.ts"],
+      model: "claude",
+      mode: "plan",
+      autoApproveAll: true,
+    });
+
+    expect(exec.kind).toBe("AgentExecution");
+    expect(exec.metadata?.org).toBe("acme");
+    expect(exec.spec?.message).toBe("execute");
+    expect(exec.spec?.agentId).toBe("agt_1");
+    expect(exec.spec?.autoApproveAll).toBe(true);
+    expect(exec.spec?.workspaceFileRefs).toEqual(["src/a.ts"]);
+    expect(exec.spec?.runtimeEnv.FOO).toMatchObject({ value: "bar", isSecret: false });
+    expect(exec.spec?.runtimeEnv.TOKEN).toMatchObject({ value: "s", isSecret: true });
+    expect(exec.spec?.executionConfig?.modelName).toBe("claude");
+    expect(exec.spec?.executionConfig?.interactionMode).toBe(InteractionMode.PLAN);
+  });
+
+  it("omits ExecutionConfig when neither model nor mode is set", async () => {
+    const { fn } = fakeController();
+    const exec = await createAgentExecution(fn, {
+      agentId: "agt_1",
+      orgId: "acme",
+      message: "hi",
+      runtimeEnv: {},
+      attachments: [],
+      workspaceFileRefs: [],
+      model: "",
+      mode: "",
+      autoApproveAll: false,
+    });
+    expect(exec.spec?.message).toBe("hi");
+    expect(exec.spec?.executionConfig).toBeUndefined();
+  });
+
+  it("leaves InteractionMode unspecified for agent mode", async () => {
+    const { fn } = fakeController();
+    const exec = await createAgentExecution(fn, {
+      sessionId: "ses_1",
+      orgId: "acme",
+      message: "x",
+      runtimeEnv: {},
+      attachments: [],
+      workspaceFileRefs: [],
+      model: "m",
+      mode: "agent",
+      autoApproveAll: false,
+    });
+    expect(exec.spec?.sessionId).toBe("ses_1");
+    expect(exec.spec?.executionConfig?.interactionMode).toBe(InteractionMode.UNSPECIFIED);
+  });
+});
+
+describe("createSessionForAgent", () => {
+  it("builds a session with the auto-created subject and instance id", async () => {
+    const { fn } = fakeController();
+    const session = await createSessionForAgent(fn, {
+      agentInstanceId: "ain_1",
+      orgId: "acme",
+      workspaceEntries: [],
+    });
+    expect(session.kind).toBe("Session");
+    expect(session.spec?.agentInstanceId).toBe("ain_1");
+    expect(session.spec?.subject).toBe("Auto-created session");
+  });
+});
+
+describe("createWorkflowExecution", () => {
+  it("builds a workflow execution with the trigger message", async () => {
+    const { fn } = fakeController();
+    const exec = await createWorkflowExecution(fn, {
+      workflowId: "wfl_1",
+      orgId: "acme",
+      message: "",
+      runtimeEnv: { K: { value: "v", isSecret: false } },
+    });
+    expect(exec.kind).toBe("WorkflowExecution");
+    expect(exec.spec?.workflowId).toBe("wfl_1");
+    expect(exec.spec?.triggerMessage).toBe("execute");
+    expect(exec.spec?.runtimeEnv.K).toMatchObject({ value: "v", isSecret: false });
+  });
+});

package/src/resources/run/create.ts

@@ -0,0 +1,165 @@
+// Resource creation for the run path: AgentExecution, the workspace Session it
+// may need, and WorkflowExecution.
+//
+// Ports the Go CLI's run_create.go. We build the full proto messages and drive
+// the generated command controllers directly — the Wave-2 fidelity rule (see
+// resources/apply/handlers.ts): the SDK's typed `create(input)` wrappers model a
+// subset of fields, and our attachments/workspace entries are already proto
+// messages, so a round-trip through the input types would be lossy and pointless.
+
+import type { Client } from "@connectrpc/connect";
+import { create, type DescService } from "@bufbuild/protobuf";
+import { type AgentExecution, AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { AgentExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/command_pb";
+import { InteractionMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { Attachment } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+import {
+  AgentExecutionSpecSchema,
+  type ExecutionConfig,
+  ExecutionConfigSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+import type { ExecutionValue } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/spec_pb";
+import { type Session, SessionSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import { SessionCommandController } from "@stigmer/protos/ai/stigmer/agentic/session/v1/command_pb";
+import { SessionSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/spec_pb";
+import type { WorkspaceEntry } from "@stigmer/protos/ai/stigmer/agentic/session/v1/workspace_pb";
+import {
+  type WorkflowExecution,
+  WorkflowExecutionSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { WorkflowExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/command_pb";
+import { WorkflowExecutionSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/spec_pb";
+import { ExecutionValueSchema } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/spec_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import type { RuntimeEnv } from "./env.js";
+import type { RunMode } from "./prepare.js";
+
+const API_VERSION = "agentic.stigmer.ai/v1";
+
+// Accessor for a raw Connect client over a generated controller — the same seam
+// the BackendClient exposes (client.ts) and apply uses (handlers.ts).
+export type ControllerFn = <Desc extends DescService>(service: Desc) => Client<Desc>;
+
+/**
+ * Inputs for creating an agent execution. At least one of agentId/sessionId
+ * must be set: agentId-only starts a new backend-managed session, sessionId
+ * threads a follow-up, both pins the agent within an existing session.
+ */
+export interface CreateAgentExecutionInput {
+  readonly agentId?: string;
+  readonly sessionId?: string;
+  readonly orgId: string;
+  readonly message: string;
+  readonly runtimeEnv: RuntimeEnv;
+  readonly attachments: readonly Attachment[];
+  readonly workspaceFileRefs: readonly string[];
+  readonly model: string;
+  readonly mode: RunMode;
+  readonly autoApproveAll: boolean;
+}
+
+/** Create an agent execution. Mirrors Go's createAgentExecution. */
+export async function createAgentExecution(
+  controller: ControllerFn,
+  input: CreateAgentExecutionInput,
+): Promise<AgentExecution> {
+  const execution = create(AgentExecutionSchema, {
+    apiVersion: API_VERSION,
+    kind: "AgentExecution",
+    metadata: create(ApiResourceMetadataSchema, { name: executionName(), org: input.orgId }),
+    spec: create(AgentExecutionSpecSchema, {
+      message: input.message === "" ? "execute" : input.message,
+      runtimeEnv: toExecutionValues(input.runtimeEnv),
+      attachments: [...input.attachments],
+      workspaceFileRefs: [...input.workspaceFileRefs],
+      autoApproveAll: input.autoApproveAll,
+      sessionId: input.sessionId ?? "",
+      agentId: input.agentId ?? "",
+      executionConfig: buildExecutionConfig(input.model, input.mode),
+    }),
+  });
+  return controller(AgentExecutionCommandController).create(execution);
+}
+
+/** Inputs for creating a workspace-bearing session. */
+export interface CreateSessionInput {
+  readonly agentInstanceId: string;
+  readonly orgId: string;
+  readonly workspaceEntries: readonly WorkspaceEntry[];
+}
+
+/**
+ * Create a session with explicit workspace entries. Mirrors Go's
+ * createSessionForAgent: the backend's auto-create flow has no workspace
+ * passthrough, so the CLI creates the session itself. The "Auto-created session"
+ * subject matches the backend sentinel, so the async title activity replaces it.
+ */
+export async function createSessionForAgent(controller: ControllerFn, input: CreateSessionInput): Promise<Session> {
+  const session = create(SessionSchema, {
+    apiVersion: API_VERSION,
+    kind: "Session",
+    metadata: create(ApiResourceMetadataSchema, { name: `session-${Date.now()}`, org: input.orgId }),
+    spec: create(SessionSpecSchema, {
+      agentInstanceId: input.agentInstanceId,
+      subject: "Auto-created session",
+      workspaceEntries: [...input.workspaceEntries],
+    }),
+  });
+  return controller(SessionCommandController).create(session);
+}
+
+/** Inputs for creating a workflow execution. */
+export interface CreateWorkflowExecutionInput {
+  readonly workflowId: string;
+  readonly orgId: string;
+  readonly message: string;
+  readonly runtimeEnv: RuntimeEnv;
+}
+
+/**
+ * Create a workflow execution. Mirrors Go's createWorkflowExecution. The caller
+ * either detaches (prints IDs) or streams the execution live over the canonical
+ * event stream (resources/run/workflow-stream.ts).
+ */
+export async function createWorkflowExecution(
+  controller: ControllerFn,
+  input: CreateWorkflowExecutionInput,
+): Promise<WorkflowExecution> {
+  const execution = create(WorkflowExecutionSchema, {
+    apiVersion: API_VERSION,
+    kind: "WorkflowExecution",
+    metadata: create(ApiResourceMetadataSchema, { name: executionName(), org: input.orgId }),
+    spec: create(WorkflowExecutionSpecSchema, {
+      workflowId: input.workflowId,
+      triggerMessage: input.message === "" ? "execute" : input.message,
+      runtimeEnv: toExecutionValues(input.runtimeEnv),
+    }),
+  });
+  return controller(WorkflowExecutionCommandController).create(execution);
+}
+
+// Build ExecutionConfig, or undefined when neither flag is set so the backend
+// applies its defaults. Mirrors Go's buildExecutionConfig (only "plan" maps to a
+// non-default InteractionMode; "agent"/"" leave it unspecified).
+function buildExecutionConfig(model: string, mode: RunMode): ExecutionConfig | undefined {
+  if (model === "" && mode === "") return undefined;
+  const cfg = create(ExecutionConfigSchema);
+  if (model !== "") cfg.modelName = model;
+  if (mode === "plan") cfg.interactionMode = InteractionMode.PLAN;
+  return cfg;
+}
+
+// Convert the merged runtime env to the proto map of ExecutionValue.
+function toExecutionValues(env: RuntimeEnv): Record<string, ExecutionValue> {
+  const out: Record<string, ExecutionValue> = {};
+  for (const [key, value] of Object.entries(env)) {
+    out[key] = create(ExecutionValueSchema, { value: value.value, isSecret: value.isSecret ?? false });
+  }
+  return out;
+}
+
+// Unique-enough placeholder name; the backend owns final identity. Mirrors Go's
+// fmt.Sprintf("execution-%d", time.Now().UnixMicro()).
+function executionName(): string {
+  return `execution-${Date.now() * 1000}`;
+}

package/src/resources/run/env.test.ts

@@ -0,0 +1,131 @@
+// Unit tests for runtime-env assembly: dotenv parsing, flag parsing, precedence,
+// and quote/escape handling. The precedence ordering is a wire-parity contract
+// with the Go CLI, so it gets dedicated coverage.
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { loadAndMergeEnv } from "./env.js";
+
+let dir: string;
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "env-test-"));
+});
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+function writeFile(name: string, contents: string): string {
+  const path = join(dir, name);
+  writeFileSync(path, contents);
+  return path;
+}
+
+const NONE = { envFlags: [], secretFlags: [], envFiles: [], secretFiles: [] };
+
+describe("loadAndMergeEnv flags", () => {
+  it("parses plain KEY=VALUE env flags as non-secrets", () => {
+    expect(loadAndMergeEnv({ ...NONE, envFlags: ["FOO=bar", "BAZ=qux"] })).toEqual({
+      FOO: { value: "bar", isSecret: false },
+      BAZ: { value: "qux", isSecret: false },
+    });
+  });
+
+  it("parses secret flags as secrets", () => {
+    expect(loadAndMergeEnv({ ...NONE, secretFlags: ["TOKEN=abc"] })).toEqual({
+      TOKEN: { value: "abc", isSecret: true },
+    });
+  });
+
+  it("rejects a flag without '='", () => {
+    expect(() => loadAndMergeEnv({ ...NONE, envFlags: ["NOEQUALS"] })).toThrow(/missing '=' separator/);
+  });
+
+  it("rejects an invalid key", () => {
+    expect(() => loadAndMergeEnv({ ...NONE, envFlags: ["1BAD=x"] })).toThrow(/invalid key/);
+  });
+
+  it("keeps everything after the first '=' as the value", () => {
+    expect(loadAndMergeEnv({ ...NONE, envFlags: ["URL=https://a.b/c?d=e"] })).toEqual({
+      URL: { value: "https://a.b/c?d=e", isSecret: false },
+    });
+  });
+});
+
+describe("loadAndMergeEnv files", () => {
+  it("parses comments, blanks, export prefix, and quoted values", () => {
+    const path = writeFile(
+      ".env",
+      ["# comment", "", "export FOO=bar", 'QUOTED="hello world"', "SINGLE='single'"].join("\n"),
+    );
+    expect(loadAndMergeEnv({ ...NONE, envFiles: [path] })).toEqual({
+      FOO: { value: "bar", isSecret: false },
+      QUOTED: { value: "hello world", isSecret: false },
+      SINGLE: { value: "single", isSecret: false },
+    });
+  });
+
+  it("treats secret files as all-secret", () => {
+    const path = writeFile("secrets.env", "API_KEY=xyz\n");
+    expect(loadAndMergeEnv({ ...NONE, secretFiles: [path] })).toEqual({
+      API_KEY: { value: "xyz", isSecret: true },
+    });
+  });
+
+  it("reports the file and line on a parse error", () => {
+    const path = writeFile(".env", "GOOD=1\nBADLINE\n");
+    expect(() => loadAndMergeEnv({ ...NONE, envFiles: [path] })).toThrow(/:2:/);
+  });
+
+  it("errors clearly when a file is missing", () => {
+    expect(() => loadAndMergeEnv({ ...NONE, envFiles: [join(dir, "nope.env")] })).toThrow(
+      /failed to open environment file/,
+    );
+  });
+});
+
+describe("loadAndMergeEnv precedence (later wins)", () => {
+  it("layers env-files < secret-files < --env < --secret", () => {
+    const envFile = writeFile("a.env", "K=from-env-file\n");
+    const secretFile = writeFile("b.env", "K=from-secret-file\n");
+    // secret-file beats env-file:
+    expect(loadAndMergeEnv({ ...NONE, envFiles: [envFile], secretFiles: [secretFile] })).toEqual({
+      K: { value: "from-secret-file", isSecret: true },
+    });
+    // --env beats secret-file:
+    expect(
+      loadAndMergeEnv({ ...NONE, secretFiles: [secretFile], envFlags: ["K=from-env-flag"] }),
+    ).toEqual({ K: { value: "from-env-flag", isSecret: false } });
+    // --secret beats --env:
+    expect(loadAndMergeEnv({ ...NONE, envFlags: ["K=from-env"], secretFlags: ["K=from-secret"] })).toEqual({
+      K: { value: "from-secret", isSecret: true },
+    });
+  });
+
+  it("applies later files within the same tier last", () => {
+    const first = writeFile("first.env", "K=first\n");
+    const second = writeFile("second.env", "K=second\n");
+    expect(loadAndMergeEnv({ ...NONE, envFiles: [first, second] })).toEqual({
+      K: { value: "second", isSecret: false },
+    });
+  });
+});
+
+describe("escape handling matches Go's single-pass replacer", () => {
+  it("does not double-process a literal backslash-n", () => {
+    // "\\n" in the file is backslash + backslash + n; Go yields backslash + n,
+    // NOT a newline. A naive chained replace would wrongly produce a newline.
+    const path = writeFile(".env", 'K="\\\\n"\n');
+    expect(loadAndMergeEnv({ ...NONE, envFiles: [path] })).toEqual({
+      K: { value: "\\n", isSecret: false },
+    });
+  });
+
+  it("unescapes real escape sequences", () => {
+    const path = writeFile(".env", 'K="a\\tb\\nc"\n');
+    expect(loadAndMergeEnv({ ...NONE, envFiles: [path] })).toEqual({
+      K: { value: "a\tb\nc", isSecret: false },
+    });
+  });
+});