@dench.com/cli 3.6.6-staging.386 → 3.8.0-staging.389

package/lib/environment-source.ts

@@ -0,0 +1,165 @@
+import { constants } from "node:fs";
+import {
+  lstat,
+  mkdir,
+  open,
+  readdir,
+  readFile,
+  realpath,
+  writeFile,
+} from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import {
+  ENVIRONMENT_MANIFEST_FILE,
+  type EnvironmentManifest,
+  type EnvironmentSourceBundle,
+  isForbiddenEnvironmentSourcePath,
+  MAX_ENVIRONMENT_FILES,
+  MAX_ENVIRONMENT_SOURCE_BYTES,
+  parseEnvironmentManifest,
+  validateEnvironmentPath,
+} from "./environment-contract";
+
+function fail(message: string): never {
+  throw new Error(`validation_failed: ${message}`);
+}
+
+async function checkedPath(root: string, relative: string) {
+  validateEnvironmentPath(relative);
+  let at = root;
+  for (const part of relative.split("/")) {
+    at = join(at, part);
+    const stat = await lstat(at);
+    if (stat.isSymbolicLink())
+      fail(`Source symlinks are not supported: ${relative}`);
+  }
+  return at;
+}
+
+export function validateSourceBundle(value: unknown): EnvironmentSourceBundle {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    (value as { version?: unknown }).version !== 1 ||
+    !Array.isArray((value as { files?: unknown }).files)
+  )
+    fail("Invalid environment source bundle.");
+  const input = value as EnvironmentSourceBundle;
+  if (input.files.length > MAX_ENVIRONMENT_FILES)
+    fail("Too many environment source files.");
+  const seen = new Set<string>();
+  for (const file of input.files) {
+    if (
+      !file ||
+      typeof file.path !== "string" ||
+      typeof file.contentBase64 !== "string" ||
+      (file.mode !== 420 && file.mode !== 493)
+    )
+      fail("Invalid source file.");
+    validateEnvironmentPath(file.path);
+    if (seen.has(file.path) || isForbiddenEnvironmentSourcePath(file.path))
+      fail("Duplicate or excluded source path.");
+    if (
+      !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(
+        file.contentBase64,
+      )
+    )
+      fail("Invalid source encoding.");
+    seen.add(file.path);
+  }
+  if (
+    Buffer.byteLength(JSON.stringify(input), "utf8") >
+    MAX_ENVIRONMENT_SOURCE_BYTES
+  )
+    fail("Environment source exceeds 16 MiB.");
+  return input;
+}
+
+export async function collectEnvironmentSource(
+  directory: string,
+  name: string,
+): Promise<{
+  manifest: EnvironmentManifest;
+  bundle: EnvironmentSourceBundle;
+  bytes: Buffer;
+}> {
+  const root = await realpath(resolve(directory));
+  const manifestPath = await checkedPath(root, ENVIRONMENT_MANIFEST_FILE);
+  const manifestStat = await lstat(manifestPath);
+  if (!manifestStat.isFile() || manifestStat.size > 64 * 1024)
+    fail("dench-env.json must be a file of at most 64 KiB.");
+  const manifest = parseEnvironmentManifest(
+    JSON.parse(await readFile(manifestPath, "utf8")),
+  );
+  if (manifest.name !== name)
+    fail("The saved environment name must match dench-env.json.");
+  const files: EnvironmentSourceBundle["files"] = [];
+  const seen = new Set<string>();
+  let sourceBytes = 0;
+  async function visit(relative: string): Promise<void> {
+    if (seen.has(relative)) return;
+    validateEnvironmentPath(relative);
+    if (isForbiddenEnvironmentSourcePath(relative)) return;
+    const absolute = await checkedPath(root, relative);
+    const stat = await lstat(absolute);
+    if (stat.isDirectory()) {
+      for (const child of (await readdir(absolute)).sort())
+        await visit(`${relative}/${child}`);
+      return;
+    }
+    if (!stat.isFile())
+      fail(`Only regular source files can be saved: ${relative}`);
+    if (stat.size > MAX_ENVIRONMENT_SOURCE_BYTES)
+      fail("A source file exceeds 16 MiB.");
+    // NOFOLLOW also closes the final-component symlink race during collection.
+    const handle = await open(
+      absolute,
+      constants.O_RDONLY | constants.O_NOFOLLOW,
+    );
+    let data: Buffer;
+    try {
+      data = await handle.readFile();
+    } finally {
+      await handle.close();
+    }
+    if (/-----BEGIN [A-Z ]*PRIVATE KEY-----/.test(data.toString("utf8")))
+      fail(`Private keys belong in encrypted secrets, not source: ${relative}`);
+    sourceBytes += data.length;
+    if (
+      sourceBytes > MAX_ENVIRONMENT_SOURCE_BYTES ||
+      files.length >= MAX_ENVIRONMENT_FILES
+    )
+      fail("Environment source exceeds the file or byte limit.");
+    seen.add(relative);
+    files.push({
+      path: relative,
+      contentBase64: data.toString("base64"),
+      mode: stat.mode & 0o111 ? 493 : 420,
+    });
+  }
+  for (const path of [ENVIRONMENT_MANIFEST_FILE, "SKILL.md", ...manifest.files])
+    await visit(path);
+  files.sort((a, b) => a.path.localeCompare(b.path));
+  const bundle = validateSourceBundle({ version: 1, files });
+  return {
+    manifest,
+    bundle,
+    bytes: Buffer.from(JSON.stringify(bundle), "utf8"),
+  };
+}
+
+export async function materializeSource(
+  bundle: EnvironmentSourceBundle,
+  directory: string,
+): Promise<void> {
+  validateSourceBundle(bundle);
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  for (const file of bundle.files) {
+    const target = join(directory, file.path);
+    await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+    await writeFile(target, Buffer.from(file.contentBase64, "base64"), {
+      mode: file.mode,
+      flag: "wx",
+    });
+  }
+}

package/lib/load-dev-env.mjs

@@ -51,7 +51,9 @@ function envFlagEnabled(value) {
 
 function argvOptIn(argv) {
   if (!Array.isArray(argv)) return false;
-  return argv.includes("--dev") || argv.includes("--use-dev-env");
+  const boundary = argv.indexOf("--");
+  const parentArgs = argv.slice(0, boundary < 0 ? undefined : boundary);
+  return parentArgs.includes("--dev") || parentArgs.includes("--use-dev-env");
 }
 
 function configOptIn(env) {

package/lib/load-dev-env.test.mjs

@@ -13,15 +13,32 @@ describe("shouldLoadDevEnv", () => {
   });
 
   it("opts in when --use-dev-env is in argv", () => {
-    expect(
-      shouldLoadDevEnv({ argv: ["apps", "--use-dev-env"], env: {} }),
-    ).toBe("argv");
+    expect(shouldLoadDevEnv({ argv: ["apps", "--use-dev-env"], env: {} })).toBe(
+      "argv",
+    );
+  });
+
+  it("does not load development credentials for a child process flag", () => {
+    for (const flag of ["--dev", "--use-dev-env"]) {
+      expect(
+        shouldLoadDevEnv({
+          argv: ["env", "run", "report", "--", "tool", flag],
+          env: {},
+        }),
+      ).toBe(false);
+      expect(
+        shouldLoadDevEnv({
+          argv: [flag, "env", "run", "report", "--", "tool"],
+          env: {},
+        }),
+      ).toBe("argv");
+    }
   });
 
   it("opts in when DENCH_USE_DEV_ENV is set to a truthy value", () => {
-    expect(shouldLoadDevEnv({ argv: [], env: { DENCH_USE_DEV_ENV: "1" } })).toBe(
-      "env",
-    );
+    expect(
+      shouldLoadDevEnv({ argv: [], env: { DENCH_USE_DEV_ENV: "1" } }),
+    ).toBe("env");
     expect(
       shouldLoadDevEnv({ argv: [], env: { DENCH_USE_DEV_ENV: "true" } }),
     ).toBe("env");
@@ -34,9 +51,9 @@ describe("shouldLoadDevEnv", () => {
     expect(shouldLoadDevEnv({ argv: [], env: { DENCH_USE_DEV_ENV: "" } })).toBe(
       false,
     );
-    expect(shouldLoadDevEnv({ argv: [], env: { DENCH_USE_DEV_ENV: "0" } })).toBe(
-      false,
-    );
+    expect(
+      shouldLoadDevEnv({ argv: [], env: { DENCH_USE_DEV_ENV: "0" } }),
+    ).toBe(false);
     expect(
       shouldLoadDevEnv({ argv: [], env: { DENCH_USE_DEV_ENV: "false" } }),
     ).toBe(false);

package/lib/native-email-wait.ts

@@ -0,0 +1,75 @@
+import { backendErrorText, publicErrorDetails } from "./public-error";
+
+export const NATIVE_EMAIL_WAIT_MS = 10_000;
+const pending = new Set(["pending", "syncing", "synced", "sending"]);
+type Receipt = Record<string, unknown>;
+
+/** Observe one durable receipt. Never resubmit a send after an uncertain read. */
+export async function waitForNativeEmail(
+  initial: unknown,
+  read: (draftId: string, signal: AbortSignal) => Promise<unknown>,
+  waitMs = NATIVE_EMAIL_WAIT_MS,
+): Promise<unknown> {
+  if (!Number.isFinite(waitMs) || waitMs < 0 || waitMs > 60_000)
+    throw new Error(
+      "Email receipt wait must be between 0 and 60000 milliseconds",
+    );
+  if (waitMs === 0 || !initial || typeof initial !== "object") return initial;
+  let receipt = initial as Receipt;
+  const draftId = receipt.draftId;
+  if (typeof draftId !== "string" || !pending.has(String(receipt.syncStatus)))
+    return initial;
+  const controller = new AbortController();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      reject(new Error("Receipt observation timed out"));
+    }, waitMs);
+  });
+  try {
+    return await Promise.race([
+      (async () => {
+        while (!controller.signal.aborted) {
+          const next = await read(draftId, controller.signal);
+          if (
+            !next ||
+            typeof next !== "object" ||
+            (next as Receipt).draftId !== draftId ||
+            typeof (next as Receipt).syncStatus !== "string"
+          ) {
+            throw new Error("Invalid email receipt response");
+          }
+          receipt = next as Receipt;
+          if (!pending.has(String(receipt.syncStatus))) return receipt;
+          await new Promise<void>((resolve) => {
+            const pollTimer = setTimeout(done, 500);
+            function done() {
+              clearTimeout(pollTimer);
+              controller.signal.removeEventListener("abort", done);
+              resolve();
+            }
+            controller.signal.addEventListener("abort", done, { once: true });
+          });
+        }
+        return receipt;
+      })(),
+      deadline,
+    ]);
+  } catch (error) {
+    return {
+      ...receipt,
+      observation: {
+        status: controller.signal.aborted ? "timed_out" : "unavailable",
+        ...publicErrorDetails(error),
+        message: controller.signal.aborted
+          ? "Still awaiting the send result."
+          : backendErrorText(error),
+        nextAction: `dench email draft show ${draftId} --json`,
+      },
+    };
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    controller.abort();
+  }
+}

package/lib/parent-argv.ts

@@ -0,0 +1,20 @@
+/** Parent options accept --flag=value. Tokens after -- belong to the child. */
+export function normalizeParentArgv(input: readonly string[]): {
+  args: string[];
+  runtimeArgs: string[];
+} {
+  const boundary = input.indexOf("--");
+  const runtimeArgs = input
+    .slice(0, boundary < 0 ? undefined : boundary)
+    .flatMap((arg) => {
+      const split = arg.startsWith("--") ? arg.indexOf("=") : -1;
+      return split > 2 ? [arg.slice(0, split), arg.slice(split + 1)] : [arg];
+    });
+  return {
+    runtimeArgs,
+    args:
+      boundary < 0
+        ? [...runtimeArgs]
+        : [...runtimeArgs, ...input.slice(boundary)],
+  };
+}

package/lib/public-error.ts

@@ -1,6 +1,88 @@
 const BACKEND_CALL_PREFIX = /\[CONVEX [^\]]*\]\s*/g;
 const REQUEST_ID_ONLY = /^\[Request ID:\s*([A-Za-z0-9]+)\]\s*Server Error$/i;
 
+/** Preserve actionable public fields without dumping arbitrary backend data. */
+export function publicErrorDetails(error: unknown): Record<string, unknown> {
+  if (!error || typeof error !== "object") return {};
+  let outer = error as Record<string, unknown>;
+  // Domain wrappers can preserve the original RPC error as a cause. Keep the
+  // walk bounded so an accidental cyclic cause never hides the actual failure.
+  for (let depth = 0; depth < 3; depth++) {
+    if (
+      outer.data !== undefined ||
+      outer.payload !== undefined ||
+      typeof outer.code === "string"
+    )
+      break;
+    if (
+      !outer.cause ||
+      typeof outer.cause !== "object" ||
+      outer.cause === outer
+    )
+      break;
+    outer = outer.cause as Record<string, unknown>;
+  }
+  const raw = outer.data ?? outer.payload ?? outer;
+  let data = raw;
+  if (typeof raw === "string") {
+    try {
+      data = JSON.parse(raw);
+    } catch {
+      return {};
+    }
+  }
+  if (!data || typeof data !== "object" || Array.isArray(data)) return {};
+  const value = data as Record<string, unknown>;
+  const result: Record<string, unknown> = {};
+  for (const key of [
+    "code",
+    "requestId",
+    "operationId",
+    "executionStatus",
+    "draftId",
+    "receiptId",
+    "nextAction",
+  ] as const) {
+    if (typeof value[key] === "string") result[key] = value[key];
+  }
+  if (typeof value.retryable === "boolean") result.retryable = value.retryable;
+  const neverRetry = new Set(["uncertain_outcome", "unconfirmed"]);
+  const noAutomaticRetry = new Set([
+    "invalid_arguments",
+    "validation_failed",
+    "missing_connection",
+    "needs_connection",
+    "needs_sender",
+    "permission_denied",
+    "forbidden",
+    "login_required",
+    "canceled",
+    "cancelled",
+    "stale_owner",
+    "provider_failure",
+    "provider_failed",
+    "upstream_failed",
+  ]);
+  if (
+    typeof result.code === "string" &&
+    (neverRetry.has(result.code) ||
+      (result.retryable === undefined && noAutomaticRetry.has(result.code)))
+  )
+    result.retryable = false;
+  if (
+    typeof value.retryAfterMs === "number" &&
+    Number.isFinite(value.retryAfterMs)
+  ) {
+    result.retryAfterMs = value.retryAfterMs;
+  }
+  if (Array.isArray(value.nextActions)) {
+    result.nextActions = value.nextActions.filter(
+      (item) => typeof item === "string",
+    );
+  }
+  return result;
+}
+
 export function publicErrorMessage(message: string): string {
   const cleaned = message
     .replace(BACKEND_CALL_PREFIX, "")