run402 1.69.6 → 1.69.7

package/lib/blob.mjs

@@ -24,6 +24,7 @@ import {
   readFileSync,
   writeFileSync,
   mkdirSync,
+  chmodSync,
   existsSync,
   unlinkSync,
   readdirSync,
@@ -61,7 +62,7 @@ Options:
   --json              NDJSON progress events (for agent consumption)
   --prefix <p>        Prefix filter (ls only)
   --limit <n>         Max results (ls only; default 100, max 1000)
-  --ttl <seconds>     Signed-URL TTL (sign only; default 3600, max 604800)
+  --ttl <seconds>     Signed-URL TTL (sign only; default 3600, min 60, max 604800)
 
 Examples:
   run402 blob put ./artifact.tgz --project prj_abc123
@@ -151,7 +152,7 @@ Arguments:
 
 Options:
   --project <id>      Project ID (defaults to active project)
-  --ttl <seconds>     Signed-URL TTL (default 3600, max 604800)
+  --ttl <seconds>     Signed-URL TTL (default 3600, min 60, max 604800)
 
 Examples:
   run402 blob sign reports/2025-q4.pdf --project prj_abc123 --ttl 600
@@ -184,7 +185,9 @@ Examples:
 `,
 };
 
-const UPLOAD_STATE_DIR = join(homedir(), ".run402", "uploads");
+function uploadStateDir() {
+  return join(homedir(), ".run402", "uploads");
+}
 
 function die(msg, exit_code = 1) {
   fail({ code: "BAD_USAGE", message: msg, exit_code });
@@ -226,7 +229,7 @@ function parseArgs(rawArgs) {
     else if (a === "--prefix") out.prefix = args[++i];
     else if (a === "--limit") out.limit = parseIntegerFlag("--limit", args[++i], { min: 1, max: 1000 });
     else if (a === "--output" || a === "-o") out.output = args[++i];
-    else if (a === "--ttl") out.ttl = parseIntegerFlag("--ttl", args[++i], { min: 1, max: 604800 });
+    else if (a === "--ttl") out.ttl = parseIntegerFlag("--ttl", args[++i], { min: 60, max: 604800 });
     else if (!a.startsWith("--")) out.positional.push(a);
   }
   return out;
@@ -259,30 +262,71 @@ async function sha256File(filePath) {
   return h.digest("hex");
 }
 
+function sha256BufferHexAndBase64(body) {
+  const digest = createHash("sha256").update(body).digest();
+  return {
+    hex: digest.toString("hex"),
+    base64: digest.toString("base64"),
+  };
+}
+
+function checksumHeadersForPresignedUrl(url, checksumBase64) {
+  let urlHasChecksum = false;
+  try {
+    urlHasChecksum = new URL(url).searchParams.has("x-amz-checksum-sha256");
+  } catch {
+    urlHasChecksum = false;
+  }
+  return urlHasChecksum ? {} : { "x-amz-checksum-sha256": checksumBase64 };
+}
+
 function loadState(uploadId) {
-  const path = join(UPLOAD_STATE_DIR, `${uploadId}.json`);
+  const path = join(uploadStateDir(), `${uploadId}.json`);
   if (!existsSync(path)) return null;
   try { return JSON.parse(readFileSync(path, "utf8")); }
   catch { return null; }
 }
 
 function saveState(state) {
-  mkdirSync(UPLOAD_STATE_DIR, { recursive: true });
-  writeFileSync(join(UPLOAD_STATE_DIR, `${state.upload_id}.json`), JSON.stringify(state, null, 2));
+  const dir = uploadStateDir();
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  chmodSync(dir, 0o700);
+  const diskState = { ...state };
+  delete diskState.parts;
+  const path = join(dir, `${state.upload_id}.json`);
+  writeFileSync(path, JSON.stringify(diskState, null, 2), { mode: 0o600 });
+  chmodSync(path, 0o600);
 }
 
 function removeState(uploadId) {
-  const path = join(UPLOAD_STATE_DIR, `${uploadId}.json`);
+  const path = join(uploadStateDir(), `${uploadId}.json`);
   if (existsSync(path)) unlinkSync(path);
 }
 
-function findResumableStateForFile(projectId, localPath, key) {
-  if (!existsSync(UPLOAD_STATE_DIR)) return null;
-  for (const f of readdirSync(UPLOAD_STATE_DIR)) {
+function fileFingerprint(stat) {
+  return {
+    file_size: stat.size,
+    file_mtime_ms: stat.mtimeMs,
+  };
+}
+
+function stateMatchesFile(state, fingerprint) {
+  return state.file_size === fingerprint.file_size &&
+    typeof state.file_mtime_ms === "number" &&
+    state.file_mtime_ms === fingerprint.file_mtime_ms;
+}
+
+function findResumableStateForFile(projectId, localPath, key, fingerprint) {
+  const dir = uploadStateDir();
+  if (!existsSync(dir)) return null;
+  for (const f of readdirSync(dir)) {
     if (!f.endsWith(".json")) continue;
     try {
-      const s = JSON.parse(readFileSync(join(UPLOAD_STATE_DIR, f), "utf8"));
-      if (s.project_id === projectId && s.local_path === localPath && s.key === key) return s;
+      const s = JSON.parse(readFileSync(join(dir, f), "utf8"));
+      if (s.project_id === projectId && s.local_path === localPath && s.key === key) {
+        if (stateMatchesFile(s, fingerprint)) return s;
+        removeState(s.upload_id);
+      }
     } catch { /* ignore */ }
   }
   return null;
@@ -295,16 +339,15 @@ function findResumableStateForFile(projectId, localPath, key) {
 async function putOne(projectId, filePath, opts) {
   const stat = statSync(filePath);
   const size = stat.size;
+  const fingerprint = fileFingerprint(stat);
   const destKey = computeDestKey(filePath, opts.key);
   const absLocal = resolvePath(filePath);
 
-  // Compute sha256 for immutable uploads up front; otherwise lazy.
-  const needSha = opts.immutable;
-  const sha256 = needSha ? await sha256File(filePath) : undefined;
+  const sha256 = await sha256File(filePath);
 
   // Attempt to resume
   let state = opts.resume
-    ? findResumableStateForFile(projectId, absLocal, destKey)
+    ? findResumableStateForFile(projectId, absLocal, destKey, fingerprint)
     : null;
   let initRes;
   if (state) {
@@ -315,7 +358,7 @@ async function putOne(projectId, filePath, opts) {
       initRes = {
         upload_id: state.upload_id,
         mode: poll.mode ?? state.mode,
-        parts: poll.parts ?? state.parts,
+        parts: poll.parts ?? state.parts ?? [],
         part_count: poll.part_count ?? state.part_count,
         part_size_bytes: poll.part_size_bytes ?? state.part_size_bytes,
       };
@@ -345,6 +388,7 @@ async function putOne(projectId, filePath, opts) {
       parts: initRes.parts,
       parts_done: {},
       sha256,
+      ...fingerprint,
       started_at: new Date().toISOString(),
     };
     if (opts.resume) saveState(state);
@@ -360,22 +404,18 @@ async function putOne(projectId, filePath, opts) {
     etags[parseInt(pn, 10) - 1] = typeof pd === "string" ? { etag: pd, sha256: undefined } : pd;
   }
 
-  // Presigned URLs are signed WITHOUT ChecksumAlgorithm (see gateway
-  // s3-presign.ts). The client-asserted sha256 declared at init is the
-  // integrity attestation — no x-amz-checksum-sha256 header on PUTs, and
-  // the gateway trusts the declared value at complete when S3 has none.
   const todo = initRes.parts.filter((p) => !(state.parts_done || {})[String(p.part_number)]);
   await withConcurrency(todo, opts.concurrency, async (part) => {
-    const { etag } = await putPart(filePath, part);
-    etags[part.part_number - 1] = { etag };
-    state.parts_done[String(part.part_number)] = { etag };
+    const { etag, sha256: partSha256 } = await putPart(filePath, part);
+    etags[part.part_number - 1] = { etag, sha256: partSha256 };
+    state.parts_done[String(part.part_number)] = { etag, sha256: partSha256 };
     if (opts.resume) saveState(state);
-    log(opts, { event: "part", upload_id: state.upload_id, part_number: part.part_number, etag });
+    log(opts, { event: "part", upload_id: state.upload_id, part_number: part.part_number, etag, sha256: partSha256 });
   });
 
   // Complete
   const body = initRes.mode === "multipart"
-    ? { parts: etags.map((e, i) => ({ part_number: i + 1, etag: e.etag })) }
+    ? { parts: etags.map((e, i) => ({ part_number: i + 1, etag: e.etag, sha256: e.sha256 })) }
     : {};
   const result = await getSdk().blobs.completeUploadSession(projectId, state.upload_id, body, {
     contentType: opts.contentType ?? guessContentType(destKey),
@@ -399,37 +439,31 @@ async function putPart(filePath, part) {
   const chunks = [];
   for await (const c of stream) chunks.push(c);
   const body = Buffer.concat(chunks);
+  const checksum = sha256BufferHexAndBase64(body);
 
-  const res = await fetch(part.url, { method: "PUT", body });
+  const res = await fetch(part.url, {
+    method: "PUT",
+    headers: checksumHeadersForPresignedUrl(part.url, checksum.base64),
+    body,
+  });
   if (!res.ok) {
     const errBody = await res.text().catch(() => "");
     throw new Error(`Part ${part.part_number} PUT failed: ${res.status} ${res.statusText}${errBody ? " — " + errBody.slice(0, 200) : ""}`);
   }
   const etag = res.headers.get("etag") ?? "";
-  return { etag };
+  return { etag, sha256: checksum.hex };
 }
 
 async function withConcurrency(items, limit, worker) {
-  const running = [];
-  for (const item of items) {
-    const p = Promise.resolve().then(() => worker(item));
-    running.push(p);
-    if (running.length >= limit) {
-      await Promise.race(running.map((r) => r.catch(() => {})));
-      for (let i = running.length - 1; i >= 0; i--) {
-        if (isSettled(running[i])) running.splice(i, 1);
-      }
+  let index = 0;
+  const workerCount = Math.min(limit, items.length);
+  async function runWorker() {
+    while (index < items.length) {
+      const item = items[index++];
+      await worker(item);
     }
   }
-  await Promise.all(running);
-}
-
-function isSettled(p) {
-  const marker = {};
-  return Promise.race([p, marker]).then(
-    (v) => v !== marker,
-    () => true,
-  );
+  await Promise.all(Array.from({ length: workerCount }, runWorker));
 }
 
 async function put(projectId, argv) {
@@ -464,6 +498,7 @@ async function get(projectId, argv) {
   opts.project = opts.project || projectId;
   const resolvedId = resolveProjectId(opts.project);
   if (opts.positional.length === 0) die("Key required");
+  if (opts.positional.length > 1) die("blob get expects exactly one key");
   if (!opts.output) die("--output <file> required");
   const key = opts.positional[0];
 
@@ -510,6 +545,7 @@ async function rm(projectId, argv) {
   opts.project = opts.project || projectId;
   const resolvedId = resolveProjectId(opts.project);
   if (opts.positional.length === 0) die("Key required");
+  if (opts.positional.length > 1) die("blob rm expects exactly one key");
   const key = opts.positional[0];
 
   try {
@@ -529,6 +565,7 @@ async function diagnose(projectId, argv) {
   opts.project = opts.project || projectId;
   const resolvedId = resolveProjectId(opts.project);
   if (opts.positional.length === 0) die("URL required");
+  if (opts.positional.length > 1) die("blob diagnose expects exactly one URL");
   const url = opts.positional[0];
 
   try {
@@ -556,6 +593,7 @@ async function sign(projectId, argv) {
   opts.project = opts.project || projectId;
   const resolvedId = resolveProjectId(opts.project);
   if (opts.positional.length === 0) die("Key required");
+  if (opts.positional.length > 1) die("blob sign expects exactly one key");
   const key = opts.positional[0];
 
   try {

package/lib/deploy-v2.mjs

@@ -32,6 +32,7 @@ import {
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { API, allowanceAuthHeaders, getActiveProjectId, resolveProjectId } from "./config.mjs";
+import { normalizeArgv } from "./argparse.mjs";
 
 const APPLY_HELP = `run402 deploy apply — Unified deploy primitive (v1.34+)
 
@@ -778,19 +779,18 @@ function rejectLegacySecretManifest(spec, details) {
 }
 
 async function resumeCmd(args) {
-  const opts = { operationId: null, quiet: false };
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--help" || args[i] === "-h") { console.log(RESUME_HELP); process.exit(0); }
-    if (args[i] === "--quiet") { opts.quiet = true; continue; }
-    if (!args[i].startsWith("-") && !opts.operationId) opts.operationId = args[i];
-  }
-  if (!opts.operationId) {
-    fail({
-      code: "BAD_USAGE",
-      message: "Missing <operation_id>.",
-      hint: "run402 deploy resume <operation_id>",
-    });
-  }
+  const parsed = parseDeploySubcommandArgs(args, {
+    command: "deploy resume",
+    help: RESUME_HELP,
+    booleanFlags: ["--quiet"],
+  });
+  const [operationId] = expectPositionals(parsed.positionals, {
+    command: "run402 deploy resume <operation_id>",
+    min: 1,
+    max: 1,
+    missing: "Missing <operation_id>.",
+  });
+  const opts = { operationId, quiet: Boolean(parsed.flags["--quiet"]) };
 
   allowanceAuthHeaders("/deploy/v2/operations");
 
@@ -805,12 +805,19 @@ async function resumeCmd(args) {
 }
 
 async function listCmd(args) {
-  const opts = { project: null, limit: null };
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--help" || args[i] === "-h") { console.log(LIST_HELP); process.exit(0); }
-    if (args[i] === "--project" && args[i + 1]) { opts.project = args[++i]; continue; }
-    if (args[i] === "--limit") { opts.limit = parsePositiveInt(args[++i], "--limit"); continue; }
-  }
+  const parsed = parseDeploySubcommandArgs(args, {
+    command: "deploy list",
+    help: LIST_HELP,
+    valueFlags: ["--project", "--limit"],
+  });
+  expectPositionals(parsed.positionals, {
+    command: "run402 deploy list [--project <id>] [--limit <n>]",
+    max: 0,
+  });
+  const opts = {
+    project: parsed.flags["--project"] ?? null,
+    limit: parsed.flags["--limit"] === undefined ? null : parsePositiveInt(parsed.flags["--limit"], "--limit"),
+  };
 
   const project = resolveProjectId(opts.project);
   allowanceAuthHeaders("/deploy/v2/operations");
@@ -826,19 +833,18 @@ async function listCmd(args) {
 }
 
 async function eventsCmd(args) {
-  const opts = { operationId: null, project: null };
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--help" || args[i] === "-h") { console.log(EVENTS_HELP); process.exit(0); }
-    if (args[i] === "--project" && args[i + 1]) { opts.project = args[++i]; continue; }
-    if (!args[i].startsWith("-") && !opts.operationId) opts.operationId = args[i];
-  }
-  if (!opts.operationId) {
-    fail({
-      code: "BAD_USAGE",
-      message: "Missing <operation_id>.",
-      hint: "run402 deploy events <operation_id>",
-    });
-  }
+  const parsed = parseDeploySubcommandArgs(args, {
+    command: "deploy events",
+    help: EVENTS_HELP,
+    valueFlags: ["--project"],
+  });
+  const [operationId] = expectPositionals(parsed.positionals, {
+    command: "run402 deploy events <operation_id>",
+    min: 1,
+    max: 1,
+    missing: "Missing <operation_id>.",
+  });
+  const opts = { operationId, project: parsed.flags["--project"] ?? null };
 
   const project = resolveProjectId(opts.project);
   allowanceAuthHeaders("/deploy/v2/operations");
@@ -868,20 +874,24 @@ async function releaseCmd(args) {
 }
 
 async function releaseGetCmd(args) {
-  const opts = { releaseId: null, project: null, siteLimit: null };
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--help" || args[i] === "-h") { console.log(RELEASE_GET_HELP); process.exit(0); }
-    if (args[i] === "--project" && args[i + 1]) { opts.project = args[++i]; continue; }
-    if (args[i] === "--site-limit" && args[i + 1]) { opts.siteLimit = parsePositiveInt(args[++i], "--site-limit"); continue; }
-    if (!args[i].startsWith("-") && !opts.releaseId) opts.releaseId = args[i];
-  }
-  if (!opts.releaseId) {
-    fail({
-      code: "BAD_USAGE",
-      message: "Missing <release_id>.",
-      hint: "run402 deploy release get <release_id>",
-    });
-  }
+  const parsed = parseDeploySubcommandArgs(args, {
+    command: "deploy release get",
+    help: RELEASE_GET_HELP,
+    valueFlags: ["--project", "--site-limit"],
+  });
+  const [releaseId] = expectPositionals(parsed.positionals, {
+    command: "run402 deploy release get <release_id>",
+    min: 1,
+    max: 1,
+    missing: "Missing <release_id>.",
+  });
+  const opts = {
+    releaseId,
+    project: parsed.flags["--project"] ?? null,
+    siteLimit: parsed.flags["--site-limit"] === undefined
+      ? null
+      : parsePositiveInt(parsed.flags["--site-limit"], "--site-limit"),
+  };
 
   const project = resolveProjectId(opts.project);
 
@@ -896,12 +906,21 @@ async function releaseGetCmd(args) {
 }
 
 async function releaseActiveCmd(args) {
-  const opts = { project: null, siteLimit: null };
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--help" || args[i] === "-h") { console.log(RELEASE_ACTIVE_HELP); process.exit(0); }
-    if (args[i] === "--project" && args[i + 1]) { opts.project = args[++i]; continue; }
-    if (args[i] === "--site-limit" && args[i + 1]) { opts.siteLimit = parsePositiveInt(args[++i], "--site-limit"); continue; }
-  }
+  const parsed = parseDeploySubcommandArgs(args, {
+    command: "deploy release active",
+    help: RELEASE_ACTIVE_HELP,
+    valueFlags: ["--project", "--site-limit"],
+  });
+  expectPositionals(parsed.positionals, {
+    command: "run402 deploy release active [--project <id>] [--site-limit <n>]",
+    max: 0,
+  });
+  const opts = {
+    project: parsed.flags["--project"] ?? null,
+    siteLimit: parsed.flags["--site-limit"] === undefined
+      ? null
+      : parsePositiveInt(parsed.flags["--site-limit"], "--site-limit"),
+  };
 
   const project = resolveProjectId(opts.project);
 
@@ -916,14 +935,21 @@ async function releaseActiveCmd(args) {
 }
 
 async function releaseDiffCmd(args) {
-  const opts = { project: null, from: null, to: null, limit: null };
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--help" || args[i] === "-h") { console.log(RELEASE_DIFF_HELP); process.exit(0); }
-    if (args[i] === "--project" && args[i + 1]) { opts.project = args[++i]; continue; }
-    if (args[i] === "--from" && args[i + 1]) { opts.from = args[++i]; continue; }
-    if (args[i] === "--to" && args[i + 1]) { opts.to = args[++i]; continue; }
-    if (args[i] === "--limit" && args[i + 1]) { opts.limit = parsePositiveInt(args[++i], "--limit"); continue; }
-  }
+  const parsed = parseDeploySubcommandArgs(args, {
+    command: "deploy release diff",
+    help: RELEASE_DIFF_HELP,
+    valueFlags: ["--project", "--from", "--to", "--limit"],
+  });
+  expectPositionals(parsed.positionals, {
+    command: "run402 deploy release diff --from <target> --to <target>",
+    max: 0,
+  });
+  const opts = {
+    project: parsed.flags["--project"] ?? null,
+    from: parsed.flags["--from"] ?? null,
+    to: parsed.flags["--to"] ?? null,
+    limit: parsed.flags["--limit"] === undefined ? null : parsePositiveInt(parsed.flags["--limit"], "--limit"),
+  };
   if (!opts.from || !opts.to) {
     fail({
       code: "BAD_USAGE",
@@ -1076,9 +1102,80 @@ function redactResolveInput(input) {
   return copy;
 }
 
+function parseDeploySubcommandArgs(rawArgs, { command, help, valueFlags = [], booleanFlags = [] }) {
+  const args = normalizeArgv(rawArgs);
+  const valueFlagSet = new Set(valueFlags);
+  const booleanFlagSet = new Set(booleanFlags);
+  const numericFlagSet = new Set(["--limit", "--site-limit"]);
+  const allowedFlags = new Set([...valueFlags, ...booleanFlags, "--help", "-h"]);
+  const flags = {};
+  const positionals = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--help" || arg === "-h") {
+      console.log(help);
+      process.exit(0);
+    }
+    if (valueFlagSet.has(arg)) {
+      const value = args[i + 1];
+      if (value === undefined || (typeof value === "string" && value.startsWith("--"))) {
+        if (numericFlagSet.has(arg)) parsePositiveInt(value, arg);
+        fail({
+          code: "BAD_USAGE",
+          message: `${arg} requires a value`,
+          details: { flag: arg },
+        });
+      }
+      flags[arg] = value;
+      i += 1;
+      continue;
+    }
+    if (booleanFlagSet.has(arg)) {
+      flags[arg] = true;
+      continue;
+    }
+    if (typeof arg === "string" && arg.startsWith("-")) {
+      fail({
+        code: "BAD_USAGE",
+        message: `Unknown flag for ${command}: ${arg}`,
+        details: { flag: arg, allowed_flags: [...allowedFlags] },
+      });
+    }
+    positionals.push(arg);
+  }
+
+  return { flags, positionals };
+}
+
+function expectPositionals(positionals, { command, min = 0, max = min, missing = "Missing required argument." }) {
+  if (positionals.length < min) {
+    fail({
+      code: "BAD_USAGE",
+      message: missing,
+      hint: command,
+    });
+  }
+  if (positionals.length > max) {
+    fail({
+      code: "BAD_USAGE",
+      message: `Unexpected argument for ${command}: ${positionals[max]}`,
+      hint: `Use \`${command}\`.`,
+    });
+  }
+  return positionals;
+}
+
 function parsePositiveInt(value, flag) {
-  const parsed = Number(value);
-  if (!Number.isInteger(parsed) || parsed < 1) {
+  if (typeof value !== "string" || !/^\d+$/.test(value)) {
+    fail({
+      code: "BAD_USAGE",
+      message: `${flag} must be a positive integer.`,
+      details: { flag, value },
+    });
+  }
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isSafeInteger(parsed) || parsed < 1) {
     fail({
       code: "BAD_USAGE",
       message: `${flag} must be a positive integer.`,

package/lib/functions.mjs

@@ -5,6 +5,7 @@ import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { assertKnownFlags, hasHelp, normalizeArgv, parseIntegerFlag, validateRegularFile } from "./argparse.mjs";
 
 const FUNCTION_LOG_REQUEST_ID_RE = /^req_[A-Za-z0-9_-]{4,128}$/;
+const FUNCTION_LOG_TAIL_MAX = 1000;
 
 const HELP = `run402 functions — Manage serverless functions
 
@@ -180,7 +181,7 @@ async function deploy(projectId, name, args) {
     if (args[i] === "--file" && args[i + 1]) opts.file = args[++i];
     if (args[i] === "--timeout") opts.timeout = parseIntegerFlag("--timeout", args[++i], { min: 1 });
     if (args[i] === "--memory") opts.memory = parseIntegerFlag("--memory", args[++i], { min: 1 });
-    if (args[i] === "--deps" && args[i + 1]) opts.deps = args[++i].split(",");
+    if (args[i] === "--deps" && args[i + 1]) opts.deps = parseDepsFlag(args[++i]);
     if (args[i] === "--schedule" && i + 1 < args.length) opts.schedule = args[++i];
   }
   if (!opts.file) {
@@ -239,7 +240,7 @@ async function logs(projectId, name, args) {
   let requestId = undefined;
   let follow = false;
   for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--tail") tail = parseIntegerFlag("--tail", args[++i], { min: 1 });
+    if (args[i] === "--tail") tail = parseIntegerFlag("--tail", args[++i], { min: 1, max: FUNCTION_LOG_TAIL_MAX });
     if (args[i] === "--since" && args[i + 1]) since = args[++i];
     if (args[i] === "--request-id" && args[i + 1]) requestId = args[++i];
     if (args[i] === "--follow") follow = true;
@@ -360,6 +361,13 @@ async function update(projectId, name, args) {
     if (args[i] === "--timeout") timeout = parseIntegerFlag("--timeout", args[++i], { min: 1 });
     if (args[i] === "--memory") memory = parseIntegerFlag("--memory", args[++i], { min: 1 });
   }
+  if (scheduleRemove && schedule !== undefined) {
+    fail({
+      code: "BAD_USAGE",
+      message: "--schedule and --schedule-remove are mutually exclusive",
+      details: { flags: ["--schedule", "--schedule-remove"] },
+    });
+  }
 
   const updateOpts = {};
   if (scheduleRemove || schedule === "") {
@@ -385,8 +393,10 @@ async function update(projectId, name, args) {
   }
 }
 
-async function list(projectId) {
+async function list(projectId, args = []) {
   assertRequiredProject(projectId, "run402 functions list <project_id>");
+  assertKnownFlags(args, ["--help", "-h"]);
+  assertNoExtraPositionals(args, "run402 functions list <project_id>");
   try {
     const data = await getSdk().functions.list(projectId);
     console.log(JSON.stringify(data, null, 2));
@@ -395,8 +405,10 @@ async function list(projectId) {
   }
 }
 
-async function deleteFunction(projectId, name) {
+async function deleteFunction(projectId, name, args = []) {
   assertRequiredProjectAndName(projectId, name, "run402 functions delete <project_id> <name>");
+  assertKnownFlags(args, ["--help", "-h"]);
+  assertNoExtraPositionals(args, "run402 functions delete <project_id> <name>");
   try {
     await getSdk().functions.delete(projectId, name);
     console.log(JSON.stringify({ status: "ok", message: `Function '${name}' deleted.` }));
@@ -417,8 +429,8 @@ export async function run(sub, args) {
     case "invoke": await invoke(args[0], args[1], args.slice(2)); break;
     case "logs":   await logs(args[0], args[1], args.slice(2)); break;
     case "update": await update(args[0], args[1], args.slice(2)); break;
-    case "list":   await list(args[0]); break;
-    case "delete": await deleteFunction(args[0], args[1]); break;
+    case "list":   await list(args[0], args.slice(1)); break;
+    case "delete": await deleteFunction(args[0], args[1], args.slice(2)); break;
     default:
       console.error(`Unknown subcommand: ${sub}\n`);
       console.log(HELP);
@@ -426,6 +438,30 @@ export async function run(sub, args) {
   }
 }
 
+function parseDepsFlag(value) {
+  const raw = String(value);
+  const deps = raw.split(",").map((entry) => entry.trim());
+  if (deps.some((entry) => entry === "")) {
+    fail({
+      code: "BAD_USAGE",
+      message: "--deps must be a comma-separated list of non-empty package specs",
+      details: { flag: "--deps", value: raw },
+    });
+  }
+  return deps;
+}
+
+function assertNoExtraPositionals(args, usage) {
+  if (args.length > 0) {
+    fail({
+      code: "BAD_USAGE",
+      message: `Unexpected argument: ${args[0]}`,
+      hint: usage,
+      details: { argument: args[0] },
+    });
+  }
+}
+
 function assertRequiredProject(projectId, usage) {
   if (!projectId || String(projectId).startsWith("-")) {
     fail({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "1.69.6",
+  "version": "1.69.7",
   "description": "CLI for Run402 — provision Postgres databases, deploy static sites, generate images, and manage wallets via x402 and MPP micropayments.",
   "type": "module",
   "bin": {

package/sdk/dist/namespaces/blobs.d.ts

@@ -16,8 +16,9 @@ export declare class Blobs {
      * presigned S3 URLs — they do NOT pass through the gateway, so uploads
      * are not double-billed as API calls and large files stream efficiently.
      *
-     * Pass `immutable: true` to produce a content-addressed URL (the server
-     * computes no hash — the SDK does it locally and attests via `sha256`).
+     * Pass `immutable: true` to produce a content-addressed URL. The SDK always
+     * computes the SHA-256 digest required by the upload API; `immutable` only
+     * controls URL/cache semantics.
      *
      * @throws {ProjectNotFound} if `projectId` is not in the provider.
      */