@homespunapps/cli 1.6.63 → 1.6.65

package/dist/argv.js

@@ -76,14 +76,28 @@ export const BOOLEAN_FLAGS = new Set([
     // member directory in its boot/hello payloads.
     "members",
 ]);
+/**
+ * Flags that may be repeated, accumulating one value per occurrence instead
+ * of throwing ArgvError on the second one. Everything not listed here keeps
+ * the default last-flag-wins-is-a-bug behavior (see the "throws on a
+ * repeated value-flag" tests): repetition is opt-in per flag, not a global
+ * relaxation, so a typo'd repeat of an ordinary flag still fails loudly.
+ *
+ * `asset`: `homespun deploy --asset <local>=<app-path>`, once per file
+ * (issue #1028).
+ */
+export const REPEATABLE_FLAGS = new Set(["asset"]);
 /**
  * Parse argv tokens. `booleanFlags` lists flags that never consume a value
  * (e.g. --json, --once, --help); everything else with a `--name` form
- * consumes the next token unless written as `--name=value`.
+ * consumes the next token unless written as `--name=value`. `repeatableFlags`
+ * (default: none) lists flags that accumulate into `repeated` instead of
+ * throwing on a second occurrence.
  *
  * Bails with ArgvError on the first duplicate (`--foo x --foo y` or
  * `--once --once`) so a typo'd repeat doesn't silently overwrite the first
- * value the way a plain `Map.set` would.
+ * value the way a plain `Map.set` would, UNLESS the flag is in
+ * `repeatableFlags`, in which case every occurrence is kept, in order.
  *
  * Does NOT throw on a value-flag with no following value. Instead it
  * records the name in `danglingValueFlags` so `assertKnownFlags` can
@@ -93,11 +107,21 @@ export const BOOLEAN_FLAGS = new Set([
  * a value" while `--bogus something` said "unknown flag(s)" — same root
  * cause, two messages).
  */
-export function parseArgs(tokens, booleanFlags) {
+export function parseArgs(tokens, booleanFlags, repeatableFlags = new Set()) {
     const positionals = [];
     const flags = new Map();
     const bools = new Set();
     const danglingValueFlags = new Set();
+    const repeated = new Map();
+    const pushRepeated = (key, value) => {
+        const arr = repeated.get(key);
+        if (arr) {
+            arr.push(value);
+        }
+        else {
+            repeated.set(key, [value]);
+        }
+    };
     for (let i = 0; i < tokens.length; i++) {
         const tok = tokens[i];
         if (tok === "-h" || tok === "--help") {
@@ -109,10 +133,15 @@ export function parseArgs(tokens, booleanFlags) {
             const eq = body.indexOf("=");
             if (eq !== -1) {
                 const key = body.slice(0, eq);
+                const value = body.slice(eq + 1);
+                if (repeatableFlags.has(key)) {
+                    pushRepeated(key, value);
+                    continue;
+                }
                 if (flags.has(key)) {
                     throw new ArgvError(`duplicate flag: --${key}`);
                 }
-                flags.set(key, body.slice(eq + 1));
+                flags.set(key, value);
                 continue;
             }
             if (booleanFlags.has(body)) {
@@ -131,6 +160,11 @@ export function parseArgs(tokens, booleanFlags) {
                 danglingValueFlags.add(body);
                 continue;
             }
+            if (repeatableFlags.has(body)) {
+                pushRepeated(body, next);
+                i++;
+                continue;
+            }
             if (flags.has(body)) {
                 throw new ArgvError(`duplicate flag: --${body}`);
             }
@@ -140,7 +174,7 @@ export function parseArgs(tokens, booleanFlags) {
         }
         positionals.push(tok);
     }
-    return { positionals, flags, bools, danglingValueFlags };
+    return { positionals, flags, bools, danglingValueFlags, repeated };
 }
 /**
  * Flags every command accepts. Kept here (not in each command's allow-list)
@@ -192,6 +226,10 @@ export function assertKnownFlags(args, knownFlags, knownBools, helpCommand) {
         if (!flagSet.has(k) && !boolSet.has(k))
             unknown.push(`--${k}`);
     }
+    for (const k of args.repeated?.keys() ?? []) {
+        if (!flagSet.has(k) && !boolSet.has(k))
+            unknown.push(`--${k}`);
+    }
     if (unknown.length > 0) {
         throw new ArgvError(`unknown flag(s): ${unknown.join(", ")}`, `run \`${helpCommand} --help\` for the supported flags`);
     }

package/dist/commands/connection.js

@@ -1,7 +1,9 @@
 // `homespun connections` (#1363) webhook-connection management for a v2 app:
 // create a static or oauth2 connection, list an app's connections (metadata
-// plus a fingerprint, never a secret), delete one, and print the browser URL
-// that completes an oauth2 connection's owner consent. Every verb targets an
+// plus a fingerprint, never a secret), delete one, print the browser URL
+// that completes an oauth2 connection's owner consent, and read or replay the
+// outbound delivery journal (#1720) so an agent can debug its own webhooks
+// without hand-rolling HTTP. Every verb targets an
 // app via a required `--app <idOrSlug>` flag, resolved the same way
 // `homespun grants`/`homespun members`/`homespun data` do (resolveAppId).
 //
@@ -26,7 +28,7 @@ export async function runConnection(args) {
         return;
     }
     if (verb === undefined) {
-        fail("missing verb: homespun connections <create|list|delete|authorize-url>", "invalid_args");
+        fail("missing verb: homespun connections <create|list|delete|authorize-url|deliveries|replay>", "invalid_args");
     }
     const sub = {
         positionals: args.positionals.slice(1),
@@ -45,8 +47,12 @@ export async function runConnection(args) {
             return runDelete(sub);
         case "authorize-url":
             return runAuthorizeUrl(sub);
+        case "deliveries":
+            return runDeliveries(sub);
+        case "replay":
+            return runReplay(sub);
         default:
-            fail(`unknown verb '${verb}' (homespun connections <create|list|delete|authorize-url>)`, "invalid_args");
+            fail(`unknown verb '${verb}' (homespun connections <create|list|delete|authorize-url|deliveries|replay>)`, "invalid_args");
     }
 }
 // Parse a "key=value" list, one per --param flag repetition is not supported
@@ -188,6 +194,55 @@ async function runDelete(args) {
     }
 }
 // ---------------------------------------------------------------------------
+// deliveries
+// ---------------------------------------------------------------------------
+async function runDeliveries(args) {
+    assertKnownFlags(args, ...specFor("connections", "deliveries"));
+    const appArg = args.flags.get("app");
+    if (!appArg) {
+        fail("usage: homespun connections deliveries --app <idOrSlug> [--status <pending|delivered|failed>] [--collection <name>] [--limit <n>]", "invalid_args");
+    }
+    const limitRaw = args.flags.get("limit");
+    // Rejected here rather than passed through, so a typo'd --limit is an
+    // argument error instead of a silent fallback to the server's default.
+    if (limitRaw !== undefined && !/^[0-9]+$/.test(limitRaw)) {
+        fail("--limit must be a whole number", "invalid_args");
+    }
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    const status = args.flags.get("status");
+    const collection = args.flags.get("collection");
+    try {
+        printJson(await client.listWebhookDeliveries(appId, {
+            ...(status !== undefined ? { status } : {}),
+            ...(collection !== undefined ? { collection } : {}),
+            ...(limitRaw !== undefined ? { limit: Number(limitRaw) } : {}),
+        }));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// replay
+// ---------------------------------------------------------------------------
+async function runReplay(args) {
+    assertKnownFlags(args, ...specFor("connections", "replay"));
+    const appArg = args.flags.get("app");
+    const deliveryId = args.flags.get("delivery");
+    if (!appArg || !deliveryId) {
+        fail("usage: homespun connections replay --app <idOrSlug> --delivery <deliveryId>", "invalid_args");
+    }
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        printJson(await client.replayWebhookDelivery(appId, deliveryId));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
 // authorize-url
 // ---------------------------------------------------------------------------
 async function runAuthorizeUrl(args) {

package/dist/commands/data.js

@@ -76,9 +76,6 @@ async function runList(appArg, collection, args) {
     const limit = parseIntFlag(args, "limit", undefined, { min: 1, max: 1000 });
     const where = parseJsonArrayFlag(args, "where");
     const sort = parseJsonArrayFlag(args, "sort");
-    if (since !== undefined && sort !== undefined) {
-        fail("--since (cursor pagination) cannot be combined with --sort", "invalid_args");
-    }
     const client = makeClient(args);
     const appId = await resolveAppId(client, appArg);
     try {

package/dist/commands/deploy.js

@@ -3,6 +3,8 @@
 // `--app <id>` redeploys an existing one (compat-gated unless --force).
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { HomespunApiError, putPresigned, } from "@homespunapps/core";
 import { makeClient } from "../config.js";
 import { assertKnownFlags } from "../argv.js";
 import { specFor } from "../help-catalog.js";
@@ -80,6 +82,24 @@ function extensionOf(path) {
     const dot = base.lastIndexOf(".");
     return dot <= 0 ? "" : base.slice(dot).toLowerCase();
 }
+/**
+ * Path-shape checks shared by every source of a relay asset path: the
+ * relay's charset (ASSET_PATH_CHARSET) and the non-servable-extension
+ * refusal. `readAssets` calls this for a directory-convention path; the
+ * explicit `--asset` flag below calls the SAME function on its app-path half,
+ * so `--asset` cannot smuggle a path shape the directory-convention bundle
+ * would already reject (issue #1028). One definition rather than two that
+ * could quietly drift apart.
+ */
+function checkAssetPathShape(path) {
+    if (!ASSET_PATH_CHARSET.test(path)) {
+        fail(`cannot ship ${path} as an asset: an asset path may only contain A-Za-z0-9._/- , so rename the file (spaces and accented characters are the usual cause)`, "invalid_args");
+    }
+    const ext = extensionOf(path);
+    if (NON_SERVABLE_EXTENSIONS.has(ext)) {
+        fail(`cannot ship ${path} as an asset: the relay serves ${ext} files as an inert download (Content-Disposition: attachment, X-Content-Type-Options: nosniff), so a browser would refuse to execute or apply it. Inline scripts and styles in index.html instead: the app CSP allows them.`, "invalid_args");
+    }
+}
 /**
  * Every file under `<dir>/assets/`, as paths relative to that directory,
  * depth-first and sorted so a deploy is byte-identical across machines.
@@ -132,13 +152,8 @@ function readAssets(source) {
         // a filename is the common case here, and both are ordinary on disk, so
         // catching it locally turns a server round-trip into an immediate message
         // naming the file. The relay re-validates and stays authoritative.
-        if (!ASSET_PATH_CHARSET.test(`${ASSET_DIR}/${rel}`)) {
-            fail(`cannot ship ${ASSET_DIR}/${rel} as an asset: an asset path may only contain A-Za-z0-9._/- , so rename the file (spaces and accented characters are the usual cause)`, "invalid_args");
-        }
+        checkAssetPathShape(`${ASSET_DIR}/${rel}`);
         const ext = extensionOf(rel);
-        if (NON_SERVABLE_EXTENSIONS.has(ext)) {
-            fail(`cannot ship ${ASSET_DIR}/${rel} as an asset: the relay serves ${ext} files as an inert download (Content-Disposition: attachment, X-Content-Type-Options: nosniff), so a browser would refuse to execute or apply it. Inline scripts and styles in index.html instead: the app CSP allows them.`, "invalid_args");
-        }
         const bytes = readFileSync(join(assetRoot, rel));
         if (bytes.byteLength > MAX_ASSET_BYTES) {
             fail(`asset ${ASSET_DIR}/${rel} is ${bytes.byteLength} bytes, over the ${MAX_ASSET_BYTES}-byte per-file limit`, "invalid_args");
@@ -151,6 +166,206 @@ function readAssets(source) {
         };
     });
 }
+// -----------------------------------------------------------------------
+// The explicit `--asset <local>=<app-path>` flag (issue #1028): for a file
+// that does not live under `assets/`, or that is too big to inline.
+//
+//   - small (under ASSET_PRESIGN_THRESHOLD_BYTES): inlined exactly like a
+//     directory-convention asset, base64 in the deploy body.
+//   - large (at or over ASSET_PRESIGN_THRESHOLD_BYTES): shipped by
+//     reference, via presignBlob, a PUT of the bytes straight to storage,
+//     then confirmBlob, so the deploy body never carries them. Falls back to
+//     inlining when the relay's presign route answers not_implemented (the
+//     filesystem backend doesn't ship it), as long as the bytes still fit
+//     the MAX_ASSET_BYTES inline cap; a file over that cap with no working
+//     presign route simply cannot ship, and fails naming it rather than
+//     silently doing nothing.
+//
+// 1 MB is HomespunClient.uploadBlob's own documented cutoff for reaching for
+// presignBlob() + confirmBlob() over the multipart fallback (see the doc
+// comment above uploadBlob in packages/core/src/client.ts). Reusing that
+// number here keeps the CLI's two "when is presign worth it" answers in
+// sync, rather than inventing a second threshold that could drift from it.
+const ASSET_PRESIGN_THRESHOLD_BYTES = 1_000_000;
+/**
+ * Split one `--asset` value into its local and app-path halves. The expected
+ * shape is `<local>=<app-path>`; anything else (no '=', or an empty half)
+ * fails with a message showing the expected form, not a generic parse error.
+ */
+function parseAssetFlagValue(raw) {
+    const eq = raw.indexOf("=");
+    if (eq <= 0 || eq === raw.length - 1) {
+        fail(`malformed --asset value ${JSON.stringify(raw)}: expected the form <local>=<app-path>, for example --asset ./logo.png=logo.png`, "invalid_args");
+    }
+    return { local: raw.slice(0, eq), appPath: raw.slice(eq + 1) };
+}
+/**
+ * Read one `--asset`'s local file. Every failure names the path: the relay
+ * cannot help diagnose this half of a deploy, since it never sees the local
+ * filesystem, so a missing or unreadable file must not surface as an opaque
+ * stack trace or a wasted round trip.
+ */
+function readExplicitAssetBytes(localPath) {
+    if (!existsSync(localPath)) {
+        fail(`--asset local file not found: ${localPath}`, "invalid_args");
+    }
+    let isFile;
+    try {
+        isFile = statSync(localPath).isFile();
+    }
+    catch (e) {
+        fail(`--asset local file is not readable: ${localPath} (${e.message})`, "invalid_args");
+    }
+    if (!isFile) {
+        fail(`--asset local path is not a regular file: ${localPath}`, "invalid_args");
+    }
+    try {
+        return readFileSync(localPath);
+    }
+    catch (e) {
+        fail(`--asset local file is not readable: ${localPath} (${e.message})`, "invalid_args");
+    }
+}
+/**
+ * Parse and validate every `--asset` flag into its final relay path plus
+ * bytes.
+ *
+ * A leading '/' on the app-path half is stripped: `--asset ./logo.png=/logo.png`
+ * and `--asset ./logo.png=logo.png` mean the same app-root file. Every
+ * relay-side asset path is relative (core/app-assets.ts's validateAssetPath
+ * rejects a leading '/' outright), so stripping it here is the only way the
+ * form a caller reaches for first (a URL-shaped root path) doesn't round-trip
+ * to a relay error. What remains is checked with checkAssetPathShape, the
+ * SAME function readAssets uses, so `--asset` cannot smuggle a path shape the
+ * directory-convention bundle would already reject.
+ *
+ * A repeated app-path keeps the LAST occurrence, matching how the merge into
+ * directory assets below treats an explicit path as authoritative.
+ */
+function collectExplicitAssets(rawValues) {
+    const byPath = new Map();
+    for (const raw of rawValues) {
+        const { local, appPath } = parseAssetFlagValue(raw);
+        const path = appPath.startsWith("/") ? appPath.slice(1) : appPath;
+        checkAssetPathShape(path);
+        const bytes = readExplicitAssetBytes(local);
+        byPath.set(path, { path, localPath: local, bytes });
+    }
+    return [...byPath.values()];
+}
+/** The relay's declared mime for a path's extension, or undefined to let the relay sniff it. */
+function declaredMimeFor(path) {
+    return DECLARED_MIME_BY_EXTENSION.get(extensionOf(path));
+}
+/**
+ * Inline an explicit asset exactly like a directory-convention one: base64
+ * in the deploy body. Enforces the same MAX_ASSET_BYTES cap readAssets does,
+ * naming the LOCAL path (what the caller typed) in the error rather than the
+ * relay path.
+ */
+function inlineExplicitAsset(asset) {
+    if (asset.bytes.byteLength > MAX_ASSET_BYTES) {
+        fail(`--asset ${asset.localPath} is ${asset.bytes.byteLength} bytes, over the ${MAX_ASSET_BYTES}-byte inline limit, and this relay has no working presign route to ship it by reference instead`, "invalid_args");
+    }
+    const mime = declaredMimeFor(asset.path);
+    return {
+        path: asset.path,
+        content_base64: asset.bytes.toString("base64"),
+        ...(mime !== undefined ? { mime } : {}),
+    };
+}
+/** Split explicit assets by the presign threshold. A pure size check, no I/O. */
+function partitionExplicitAssets(assets) {
+    const small = [];
+    const large = [];
+    for (const asset of assets) {
+        (asset.bytes.byteLength < ASSET_PRESIGN_THRESHOLD_BYTES
+            ? small
+            : large).push(asset);
+    }
+    return { small, large };
+}
+/**
+ * Resolve one "large" explicit asset to a by-reference AppAssetRef: presign
+ * against `appId`, PUT the bytes straight to storage, then confirm. `appId`
+ * must already be real; see the two-round-trip note on runDeploy for why a
+ * brand-new app cannot presign on its FIRST deploy call, since the id does
+ * not exist yet.
+ *
+ * Falls back to inlining the asset when the relay answers not_implemented
+ * (the filesystem backend has no presign route), provided the bytes still
+ * fit the inline cap; a genuinely large file with no working presign route
+ * fails naming it, rather than silently shrinking the deploy's asset set.
+ * Any other failure (a network error, a rejected PUT, a failed confirm) is
+ * rethrown for the caller's own error handling.
+ */
+async function resolveLargeAsset(client, appId, asset) {
+    const mime = declaredMimeFor(asset.path) ?? "application/octet-stream";
+    const sha256 = createHash("sha256").update(asset.bytes).digest("hex");
+    try {
+        const presign = await client.presignBlob({
+            mime,
+            size: asset.bytes.byteLength,
+            sha256,
+            scope: "app",
+            appId,
+            filename: asset.path.split("/").pop(),
+        });
+        await putPresigned(presign.upload_url, asset.bytes, mime);
+        await client.confirmBlob(presign.attachment_id);
+        return { path: asset.path, attachment_id: presign.attachment_id };
+    }
+    catch (e) {
+        if (e instanceof HomespunApiError && e.code === "not_implemented") {
+            if (asset.bytes.byteLength > MAX_ASSET_BYTES) {
+                fail(`cannot ship --asset ${asset.localPath} (${asset.bytes.byteLength} bytes): it is over the ${MAX_ASSET_BYTES}-byte inline cap, and this relay's presign route is not implemented (${e.message})`, "invalid_args");
+            }
+            warn(`presigned upload is not available on this relay; shipping --asset ${asset.localPath} (${asset.bytes.byteLength} bytes) inline instead`);
+            return inlineExplicitAsset(asset);
+        }
+        throw e;
+    }
+}
+/** Resolve every "large" explicit asset against `appId`, in order. */
+async function resolveLargeAssets(client, appId, assets) {
+    const resolved = [];
+    for (const asset of assets) {
+        resolved.push(await resolveLargeAsset(client, appId, asset));
+    }
+    return resolved;
+}
+/**
+ * Merge an explicit `--asset` list into a base asset array, the explicit
+ * list winning on a path collision. A colliding path keeps its ORIGINAL
+ * position in the merged array, so a directory-convention asset overridden
+ * by `--asset` does not jump to the end; a new path is appended in
+ * `--asset` order.
+ */
+function mergeAssets(base, overrides) {
+    const merged = [...base];
+    const indexByPath = new Map(merged.map((a, i) => [a.path, i]));
+    for (const asset of overrides) {
+        const idx = indexByPath.get(asset.path);
+        if (idx !== undefined) {
+            merged[idx] = asset;
+        }
+        else {
+            indexByPath.set(asset.path, merged.length);
+            merged.push(asset);
+        }
+    }
+    return merged;
+}
+/**
+ * Merge, but preserve "no assets/ directory and no --asset flags" as
+ * `undefined`, the redeploy "keep the live set" signal (issue #1272),
+ * rather than turning it into an empty array.
+ */
+function mergeAssetsMaybe(base, overrides) {
+    if (overrides.length === 0)
+        return base;
+    return mergeAssets(base ?? [], overrides);
+}
 /**
  * Warn about files sitting next to `index.html` that this deploy is NOT
  * shipping. Silently dropping them is the failure mode issue #1225 is about:
@@ -234,17 +449,26 @@ export async function runDeploy(args) {
     const check = args.bools.has("check");
     const bundle = readBundle(source, args.flags.get("manifest"), appId !== undefined);
     const client = makeClient(args);
+    const explicitAssets = collectExplicitAssets(args.repeated?.get("asset") ?? []);
     // Dry run (--check): validate + report what a real deploy would do, persist
     // NOTHING. Runs for both create (no --app) and redeploy (--app), the latter
     // reporting the compat gate. slug/visibility are not part of a dry run.
+    //
+    // Every explicit asset is inlined here regardless of size: presigning is a
+    // real upload (presignBlob reserves storage, PUT writes bytes, confirmBlob
+    // finalises it), and --check's contract is to persist nothing. A file too
+    // big to inline fails the same way inlineExplicitAsset always fails one,
+    // naming it, rather than pretending a dry run validated a transport it
+    // never exercised.
     if (check) {
+        const checkAssets = mergeAssetsMaybe(bundle.assets, explicitAssets.map(inlineExplicitAsset));
         try {
             const id = appId !== undefined ? await resolveAppId(client, appId) : undefined;
             const result = await client.checkDeploy({
                 ...(id !== undefined ? { app_id: id } : {}),
                 ...(bundle.html !== undefined ? { html: bundle.html } : {}),
                 ...(bundle.manifest !== undefined ? { manifest: bundle.manifest } : {}),
-                ...(bundle.assets !== undefined ? { assets: bundle.assets } : {}),
+                ...(checkAssets !== undefined ? { assets: checkAssets } : {}),
                 ...(force ? { force } : {}),
             });
             printJson(result);
@@ -254,12 +478,23 @@ export async function runDeploy(args) {
         }
         return;
     }
+    const { small, large } = partitionExplicitAssets(explicitAssets);
     if (appId === undefined) {
         // Create. Client-side mirror of the relay's slug_not_allowed_for_link —
         // fail fast rather than round-trip a request that will 400 (spec-cli §3.1).
         if (slug !== undefined && visibility === "link") {
             fail("a caller-supplied --slug is not allowed with visibility 'link' (link slugs are always server-generated); drop --visibility link, or omit --slug", "invalid_args");
         }
+        // Any "large" explicit asset needs an app id to presign against (scope:
+        // "app" is bound to a specific app at presign time, and there is no
+        // rescope endpoint), and a brand-new app has no id until the FIRST
+        // deploy call returns one. So a create carrying a large asset is a
+        // two-round-trip: deploy without it, presign + PUT + confirm against the
+        // real id the relay just minted, then redeploy carrying the reference.
+        // An existing app (--app given, below) already has an id, so it stays a
+        // single pass. Adding a rescope endpoint to collapse this to one round
+        // trip was considered and rejected as disproportionate to the problem.
+        const firstPassAssets = mergeAssetsMaybe(bundle.assets, small.map(inlineExplicitAsset));
         try {
             // readBundle guarantees both halves on the create path (a create can
             // inherit nothing), so the non-null assertions are the type system
@@ -269,9 +504,31 @@ export async function runDeploy(args) {
                 manifest: bundle.manifest,
                 visibility,
                 slug,
-                ...(bundle.assets !== undefined ? { assets: bundle.assets } : {}),
+                ...(firstPassAssets !== undefined ? { assets: firstPassAssets } : {}),
+            });
+            if (large.length === 0) {
+                printJson(out);
+                return;
+            }
+            const largeRefs = await resolveLargeAssets(client, out.app_id, large);
+            const finalAssets = mergeAssets(firstPassAssets ?? [], largeRefs);
+            const redeployed = await client.redeployApp(out.app_id, {
+                assets: finalAssets,
+                force: false,
+            });
+            const app = await client.getApp(out.app_id);
+            printJson({
+                app_id: out.app_id,
+                slug: app.slug,
+                url: app.url,
+                version: redeployed.version,
+                visibility: app.visibility,
+                created: true,
+                ...(out.share_url !== undefined ? { share_url: out.share_url } : {}),
+                compat: redeployed.compat,
+                ...(redeployed.breaks ? { breaks: redeployed.breaks } : {}),
+                ...(redeployed.warnings ? { warnings: redeployed.warnings } : {}),
             });
-            printJson(out);
         }
         catch (e) {
             failFromError(e);
@@ -287,17 +544,25 @@ export async function runDeploy(args) {
     }
     const id = await resolveAppId(client, appId);
     try {
+        // The app id already exists, so presigning any "large" explicit asset is
+        // a single pass: resolve every explicit asset up front, merge into the
+        // directory-convention bundle, then redeploy once.
+        const smallInline = small.map(inlineExplicitAsset);
+        const largeRefs = large.length > 0 ? await resolveLargeAssets(client, id, large) : [];
+        const explicitResolved = [...smallInline, ...largeRefs];
         // Only what this invocation actually read is sent: an omitted html,
         // manifest or asset set keeps what is live, so
         // `homespun deploy ./index.html --app <id>` ships the document alone and
         // `--manifest` with no file ships the manifest alone. A directory WITH an
         // `assets/` folder always sends the full computed set, so deleting a file
-        // on disk removes it from the app; a directory WITHOUT one sends nothing,
-        // leaving assets uploaded by another path (MCP `deploy_app`) untouched.
+        // on disk removes it from the app; a directory WITHOUT one, and no
+        // `--asset` flags, sends nothing, leaving assets uploaded by another
+        // path (MCP `deploy_app`) untouched.
+        const finalAssets = mergeAssetsMaybe(bundle.assets, explicitResolved);
         const redeployed = await client.redeployApp(id, {
             ...(bundle.html !== undefined ? { html: bundle.html } : {}),
             ...(bundle.manifest !== undefined ? { manifest: bundle.manifest } : {}),
-            ...(bundle.assets !== undefined ? { assets: bundle.assets } : {}),
+            ...(finalAssets !== undefined ? { assets: finalAssets } : {}),
             force,
         });
         const app = await client.getApp(id);

package/dist/help-catalog.js

@@ -334,7 +334,7 @@ const DATA = {
     ],
     notes: [
         "<app> accepts either the app_id or its slug. upsert is the ONLY create-shaped verb: omit --key to add a new row (the server generates the key); pass --key to ensure a row exists at that key (returns the existing row with deduped:true on a collision). A collision on a row the collection's read list does not reach for you is row_not_found (404) instead of the row, the same answer a get on that key gives, so upsert cannot read past read. Pass --on <field> to upsert on a manifest-declared UNIQUE field instead of the key: the row whose <field> value matches is updated in place (idempotent re-import), else created.",
-        "list --where takes a JSON array of {field, op, value} conditions (ANDed), op one of eq, neq, in, notIn, gt, lt, gte, lte (in and notIn take an array value). --sort takes a JSON array of {field, dir} (dir asc or desc). Filtering is applied AFTER the read permission and author scoping, so a filtered list is always a subset of what you could already read. Comparisons are same-type only (no coercion); dates compare as ISO-8601 strings. A custom --sort cannot be combined with --since.",
+        "list --where takes a JSON array of {field, op, value} conditions (ANDed), op one of eq, neq, in, notIn, gt, lt, gte, lte (in and notIn take an array value). --sort takes a JSON array of {field, dir} (dir asc or desc). Filtering is applied AFTER the read permission and author scoping, so a filtered list is always a subset of what you could already read. Comparisons are same-type only (no coercion); dates compare as ISO-8601 strings. --since paginates a custom --sort too: pass back the same --sort with the next_cursor a page returned, since a cursor is only valid for the exact sort it came from.",
         "delete is RECOVERABLE: it tombstones the row, `deleted` lists what can still be brought back, and `restore` brings one back for 30 days. purge is the permanent one: it removes ONE row by --key even in an append-only collection, scrubs its contents immediately, and cannot be restored. Both are owner and agent only (never members or anyone); purge bypasses append-only and the collection delete list on purpose, and both write an audited delete feed entry.",
         "import reads NDJSON (one JSON object per line) OR a JSON array from --file and bulk-writes it in chunks via the batch API, in ONE process. Each object is a row's data. Pass --key-field to derive the row key from a field: an existing row at that key is LEFT UNCHANGED, so this is create-or-skip-by-id, not overwrite, and re-importing changed data for a known key does not update it. A skipped row is reported as a per-row row_not_found rather than an ok when the collection's read list does not reach that row for you (the row is still left unchanged); list 'agent' in read if you want the skip reported as a success. Import DEFAULTS TO SILENT (it suppresses notify and webhooks, since a bulk import is a migration); pass --emit-effects to fire them. A per-row failure is listed in the summary WITHOUT aborting the import.",
         "retention is an OWNER control: the author declares default retention in the manifest, and this tightens or loosens it per collection at runtime WITHOUT a redeploy. Effective retention is per-axis override-or-author-default: --max-rows/--max-age-days set an axis override, --clear-rows/--clear-age revert an axis to the author default, and with no flag (or --show) it just reads. The response reports the effective bounds, the author default, the override, and wouldPrune (how many live rows the effective bound would prune on the next sweep). The override survives redeploys and effective maxRows is capped at MAX_ROWS_PER_APP.",
@@ -765,7 +765,7 @@ const CONNECTIONS = {
     noun: "connections",
     tagline: "webhook connection management",
     group: "app",
-    rootSummary: "App webhook-connection management: create, list, delete, authorize-url. Store the credential a webhook rule authenticates its target with.",
+    rootSummary: "App webhook-connection management: create, list, delete, authorize-url, deliveries, replay. Store the credential a webhook rule authenticates its target with, and inspect or re-send what went out.",
     verbs: [
         {
             verb: "create",
@@ -885,6 +885,48 @@ const CONNECTIONS = {
                 },
             ],
         },
+        {
+            verb: "deliveries",
+            summary: "Lists the app's outbound webhook deliveries, newest first, with the request body that was sent and the target's response.",
+            flags: [
+                {
+                    name: "app",
+                    value: "<idOrSlug>",
+                    description: "App to read the delivery journal of (required)",
+                },
+                {
+                    name: "status",
+                    value: "<status>",
+                    description: "Only deliveries in this state: pending, delivered or failed",
+                },
+                {
+                    name: "collection",
+                    value: "<name>",
+                    description: "Only deliveries triggered by rows in this collection",
+                },
+                {
+                    name: "limit",
+                    value: "<n>",
+                    description: "How many to return (default 25, capped at 100)",
+                },
+            ],
+        },
+        {
+            verb: "replay",
+            summary: "Re-sends one stored delivery's own rule, url and body as a fresh delivery, now, without waiting out its backoff.",
+            flags: [
+                {
+                    name: "app",
+                    value: "<idOrSlug>",
+                    description: "App the delivery belongs to (required)",
+                },
+                {
+                    name: "delivery",
+                    value: "<deliveryId>",
+                    description: "Delivery to re-send, from `deliveries` (required)",
+                },
+            ],
+        },
         {
             verb: "authorize-url",
             summary: "Prints the browser URL that completes an oauth2 connection's owner consent. Never fetched by this command.",
@@ -908,6 +950,9 @@ const CONNECTIONS = {
         "Every stored secret (a static header value, or an oauth2 client secret and its tokens) is encrypted at rest and never returned by any call; list returns metadata plus a non-reversible fingerprint only.",
         "OAuth2 consent is inherently a human-in-a-browser step: the relay refuses an agent-key caller at the authorize endpoint. authorize-url never makes a network call, it builds the URL locally so you can hand it to the signed-in app owner to open. A newly created oauth2 connection starts in pending_auth until the owner completes it.",
         "--header-value and --client-secret on create take the value straight from argv where it is visible in shell history and to other local users via ps for the life of the process. Prefer '--header-value -' / '--client-secret -' to read the value from stdin, or set HOMESPUN_CONNECTION_HEADER_VALUE / HOMESPUN_CONNECTION_CLIENT_SECRET, both of which never touch argv.",
+        "deliveries returns { deliveries: [{ id, collection, rowKey, op, url, status, attempts, responseStatus, responseBody, payload, payloadTruncated, error, replayOfId, createdAt, deliveredAt, lastAttemptAt }] }. payload is the request body as it was rendered and sent, truncated by the relay; payloadTruncated says whether you are looking at all of it. url is host and path only, never the query string, which can carry a token. The same rows are on the app detail page in the console.",
+        "The journal is a ROLLING window, not the app's whole history: the relay hard-deletes delivered and failed rows past its retention window, and caps how many one app may keep. A delivery you cannot find is more likely aged out than never sent.",
+        "replay re-sends a stored delivery's own rule, url and body verbatim, as a fresh row the normal worker picks up (signing and connection auth apply exactly as they would to any other delivery). Nothing you pass enters the new row. It is NOT idempotent in effect: the target receives the same request a second time, so a target without its own dedupe ends up with a duplicate record. It is refused when the rule that produced the original is no longer in the app's current manifest.",
     ],
 };
 const KEY = {
@@ -1139,6 +1184,11 @@ const DEPLOY = {
                     value: "<private|link|public>",
                     description: "Who can open the new app, on create only",
                 },
+                {
+                    name: "asset",
+                    value: "<local>=<app-path>",
+                    description: "Ship a file that is not under assets/, repeatable, wins over a directory-convention asset at the same app-path",
+                },
             ],
             bools: [
                 { name: "force", description: "Override the redeploy compat gate" },
@@ -1155,6 +1205,7 @@ const DEPLOY = {
         "Create versus redeploy is decided by the presence of --app, not by two verbs. With no --app this creates an app (POST /v1/apps); new apps default to private (owner plus invited members, sign-in gated), --slug is accepted with private or public visibility including the default, and an explicit --visibility link always gets a server-generated slug and rejects --slug. With --app <id> this redeploys (POST /v1/apps/:id/versions), where --slug and --visibility are rejected because the slug is immutable and visibility changes go through 'homespun apps update'.",
         "On redeploy, what you do not send is kept. 'homespun deploy ./index.html --app <id>' ships the document alone and keeps the live manifest; 'homespun deploy --app <id> --manifest ./manifest.json' ships the manifest alone and keeps the live document, with no file argument at all; a directory deploy still ships both. Assets follow the same rule, decided by whether the directory has an assets/ folder: with one, the full set on disk is sent, so deleting a file there removes it from the app; with none, nothing is sent and the live asset set is carried forward untouched. A create can inherit nothing, so it still needs both halves.",
         "--check is a dry run. It runs the full manifest and asset validation (shape and MIME), the redeploy compat gate (with --app), and the schedule-timezone advisory, then prints { ok, warnings, compat, breaks } without creating a version or mutating anything. An invalid manifest fails the same way a real deploy would, and a redeploy the compat gate would refuse reports the break instead of applying it. It resolves omitted fields exactly as a real redeploy would, so it reports on the deploy that would actually run.",
+        "--asset <local>=<app-path> ships one file that is not under assets/, or that assets/ cannot hold because it is too big to inline. Repeatable; the app-path side is validated the same way a directory-convention path is (charset, no .js/.css/.svg/.html), and a leading '/' on it is stripped since every relay-side path is relative. Files under 1 MB are inlined exactly like a directory asset; at or above 1 MB the CLI presigns instead (presignBlob, PUT the bytes straight to storage, confirmBlob), so the deploy body never carries them, up to the 50 MB media ceiling. On a brand-new app (no --app) that needs presigning, this is two round trips: the app does not exist yet to presign against, and scope is fixed at presign time with no rescope endpoint, so the CLI deploys first, presigns against the id the relay just minted, then redeploys carrying the reference. With --app <id> the id already exists, so it is one pass. If the relay's presign route is not implemented (some backends), a file under the 5 MB inline cap is shipped inline instead with a warning on stderr; a file over that cap fails naming it, since there is then no way to ship it. An --asset wins over a directory-convention asset at the same app-path.",
     ],
     outputNote: 'Output is JSON: { app_id, slug, url, version, visibility, created, share_url, compat, breaks, warnings }. share_url is present only when creating a link-visibility app: it carries the app share token in its #k= fragment and is shown ONCE, it is not recoverable later, and it can be rotated with \'homespun apps share-link rotate <app>\'. warnings flags non-fatal issues, for example an app that declares schedules with no timezone set (reminders fire at 08:00 UTC until one is set). Errors go to stderr as {"error":{"code","message"}} with a non-zero exit.',
 };

package/dist/index.js

@@ -9,7 +9,7 @@
 // Multiple environments live as named profiles in
 // $XDG_CONFIG_HOME/homespun/config.json; pick one with --profile or HOMESPUN_PROFILE.
 // Output is JSON by default. Every noun self-documents via --help.
-import { parseArgs, ArgvError, BOOLEAN_FLAGS } from "./argv.js";
+import { parseArgs, ArgvError, BOOLEAN_FLAGS, REPEATABLE_FLAGS, } from "./argv.js";
 import { helpTextFor, nounSpec, renderNounHelp, renderRootHelp, } from "./help-catalog.js";
 /**
  * Translate an ArgvError into the canonical `invalid_args` envelope and exit
@@ -69,7 +69,7 @@ async function main() {
     }
     let args;
     try {
-        args = parseArgs(rest, BOOLEAN_FLAGS);
+        args = parseArgs(rest, BOOLEAN_FLAGS, REPEATABLE_FLAGS);
     }
     catch (e) {
         if (e instanceof ArgvError) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homespunapps/cli",
-  "version": "1.6.63",
+  "version": "1.6.65",
   "description": "Command-line client for the Homespun relay: deploy a real multi-user web app from your agent, then keep reading and writing its data.",
   "license": "MIT",
   "type": "module",
@@ -36,7 +36,7 @@
     "test:unit": "vitest run"
   },
   "dependencies": {
-    "@homespunapps/core": "^1.6.63",
+    "@homespunapps/core": "^1.6.65",
     "qrcode-terminal": "^0.12.0"
   },
   "devDependencies": {