@homespunapps/cli 1.6.44 → 1.6.45

package/dist/argv.js

@@ -65,6 +65,12 @@ export const BOOLEAN_FLAGS = new Set([
     "attest-example-only",
     // `homespun review respond --clear`: clear a publisher response (sends null).
     "clear",
+    // `homespun credentials mint --no-expiry`: the explicit opt-in to NO EXPIRY
+    // (ttl_seconds: null), mutually exclusive with --ttl.
+    "no-expiry",
+    // `homespun credentials mint --members`: opt the credential into the app's
+    // member directory in its boot/hello payloads.
+    "members",
 ]);
 /**
  * Parse argv tokens. `booleanFlags` lists flags that never consume a value

package/dist/commands/apps.js

@@ -63,8 +63,8 @@ async function runList(args) {
     assertKnownFlags(args, ...specFor("apps", "list"));
     const status = args.flags.get("status");
     if (status !== undefined &&
-        !["active", "dormant", "archived", "all"].includes(status)) {
-        fail("--status must be active|dormant|archived|all", "invalid_args");
+        !["active", "dormant", "archived", "suspended", "all"].includes(status)) {
+        fail("--status must be active|dormant|archived|suspended|all", "invalid_args");
     }
     const limitRaw = args.flags.get("limit");
     const limit = limitRaw !== undefined ? Number(limitRaw) : undefined;
@@ -294,6 +294,16 @@ async function runWatch(args) {
         printJsonLine({ type: "_dormant" });
         finish(0);
     };
+    // Operator takedown (issue #1041): the WS path gets an explicit
+    // `_suspended` frame, same as `_dormant`. There is no long-poll-side
+    // equivalent by DESIGN: see `isDormantConflict`'s comment. A suspended
+    // app's long-poll GET throws the "gone" 410, not a 409 conflict, which is
+    // exactly how `archived` already behaves there (no special case), so
+    // `runLongPoll` falls through to `failFromError` unchanged.
+    const emitSuspended = () => {
+        printJsonLine({ type: "_suspended" });
+        finish(0);
+    };
     // Long-poll fallback loop (spec-cli §5) — GET /v1/apps/:id/feed?wait=25.
     // Uses the SAME printFeedEntryLine as the WS entry handler below, so a
     // caller piping `homespun apps watch` output can never tell which transport
@@ -339,6 +349,9 @@ async function runWatch(args) {
         onDormant: () => {
             emitDormant();
         },
+        onSuspended: () => {
+            emitSuspended();
+        },
         onResync: () => {
             printJsonLine({ type: "resync" });
         },

package/dist/commands/connection.js

@@ -0,0 +1,206 @@
+// `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
+// app via a required `--app <idOrSlug>` flag, resolved the same way
+// `homespun grants`/`homespun members`/`homespun data` do (resolveAppId).
+//
+// Auth on the relay side is owner-or-owning-agent; this CLI always
+// authenticates as the owning agent. There is no update verb: change a
+// connection by deleting and recreating it (matching the HTTP API).
+//
+// OAuth2 consent is inherently a human-in-a-browser step: the relay refuses
+// an agent-key caller at `/connections/:name/authorize`. `authorize-url`
+// therefore never makes a network call: it builds the URL locally and hands
+// it back so you can pass it to the signed-in app owner to open.
+import { assertKnownFlags } from "../argv.js";
+import { nounSpec, renderNounHelp, specFor } from "../help-catalog.js";
+import { makeClient } from "../config.js";
+import { fail, failFromError, printJson } from "../output.js";
+import { resolveAppId } from "../resolve-app.js";
+export async function runConnection(args) {
+    const verb = args.positionals[0];
+    if ((verb === undefined || verb === "help") && args.bools.has("help")) {
+        process.stdout.write(renderNounHelp(nounSpec("connections")) + "\n");
+        return;
+    }
+    if (verb === undefined) {
+        fail("missing verb: homespun connections <create|list|delete|authorize-url>", "invalid_args");
+    }
+    const sub = {
+        positionals: args.positionals.slice(1),
+        flags: args.flags,
+        bools: args.bools,
+        ...(args.danglingValueFlags !== undefined
+            ? { danglingValueFlags: args.danglingValueFlags }
+            : {}),
+    };
+    switch (verb) {
+        case "create":
+            return runCreate(sub);
+        case "list":
+            return runList(sub);
+        case "delete":
+            return runDelete(sub);
+        case "authorize-url":
+            return runAuthorizeUrl(sub);
+        default:
+            fail(`unknown verb '${verb}' (homespun connections <create|list|delete|authorize-url>)`, "invalid_args");
+    }
+}
+// Parse a "key=value" list, one per --param flag repetition is not supported
+// by this parser (each flag is single-valued), so extra params travel as a
+// JSON object flag, mirroring `homespun grants mint --pin-where <json>`.
+function parseJsonObjectFlag(raw, flag) {
+    if (raw === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        fail(`${flag} must be a JSON object`, "invalid_args");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        fail(`${flag} must be a JSON object`, "invalid_args");
+    }
+    return parsed;
+}
+// ---------------------------------------------------------------------------
+// create
+// ---------------------------------------------------------------------------
+async function runCreate(args) {
+    assertKnownFlags(args, ...specFor("connections", "create"));
+    const appArg = args.flags.get("app");
+    const name = args.flags.get("name");
+    const allowedHost = args.flags.get("allowed-host");
+    if (!appArg || !name || !allowedHost) {
+        fail("usage: homespun connections create --app <idOrSlug> --name <name> --allowed-host <host> [...]", "invalid_args");
+    }
+    const kind = args.flags.get("kind");
+    if (kind !== undefined && kind !== "static" && kind !== "oauth2") {
+        fail('--kind must be "static" or "oauth2"', "invalid_args");
+    }
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        if ((kind ?? "static") === "oauth2") {
+            const authorizeUrl = args.flags.get("authorize-url");
+            const tokenEndpoint = args.flags.get("token-url");
+            const clientId = args.flags.get("client-id");
+            const clientSecret = args.flags.get("client-secret");
+            if (!authorizeUrl || !tokenEndpoint || !clientId || !clientSecret) {
+                fail("kind=oauth2 requires --authorize-url, --token-url, --client-id and --client-secret", "invalid_args");
+            }
+            printJson(await client.createConnection(appId, {
+                name: name,
+                kind: "oauth2",
+                allowedHost: allowedHost,
+                authorizeUrl: authorizeUrl,
+                tokenEndpoint: tokenEndpoint,
+                clientId: clientId,
+                clientSecret: clientSecret,
+                ...(args.flags.get("provider") !== undefined
+                    ? { provider: args.flags.get("provider") }
+                    : {}),
+                ...(args.flags.get("label") !== undefined
+                    ? { label: args.flags.get("label") }
+                    : {}),
+                ...(args.flags.get("scopes") !== undefined
+                    ? { scopes: args.flags.get("scopes") }
+                    : {}),
+                ...(args.flags.get("auth-scheme") !== undefined
+                    ? { authScheme: args.flags.get("auth-scheme") }
+                    : {}),
+                ...(args.flags.get("instance-field") !== undefined
+                    ? { instanceField: args.flags.get("instance-field") }
+                    : {}),
+                ...(() => {
+                    const v = parseJsonObjectFlag(args.flags.get("auth-params"), "--auth-params");
+                    return v !== undefined ? { authParams: v } : {};
+                })(),
+                ...(() => {
+                    const v = parseJsonObjectFlag(args.flags.get("token-params"), "--token-params");
+                    return v !== undefined ? { tokenParams: v } : {};
+                })(),
+            }));
+            return;
+        }
+        const headerValue = args.flags.get("header-value");
+        if (!headerValue) {
+            fail("--header-value is required for a static connection", "invalid_args");
+        }
+        printJson(await client.createConnection(appId, {
+            name: name,
+            kind: "static",
+            allowedHost: allowedHost,
+            headerValue: headerValue,
+            headerName: args.flags.get("header-name") ?? "Authorization",
+            ...(args.flags.get("provider") !== undefined
+                ? { provider: args.flags.get("provider") }
+                : {}),
+            ...(args.flags.get("label") !== undefined
+                ? { label: args.flags.get("label") }
+                : {}),
+        }));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// list
+// ---------------------------------------------------------------------------
+async function runList(args) {
+    assertKnownFlags(args, ...specFor("connections", "list"));
+    const appArg = args.flags.get("app");
+    if (!appArg) {
+        fail("usage: homespun connections list --app <idOrSlug>", "invalid_args");
+    }
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        printJson(await client.listConnections(appId));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// delete
+// ---------------------------------------------------------------------------
+async function runDelete(args) {
+    assertKnownFlags(args, ...specFor("connections", "delete"));
+    const appArg = args.flags.get("app");
+    const name = args.flags.get("name");
+    if (!appArg || !name) {
+        fail("usage: homespun connections delete --app <idOrSlug> --name <name>", "invalid_args");
+    }
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        await client.deleteConnection(appId, name);
+        printJson({ deleted: true, app_id: appId, name: name });
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// authorize-url
+// ---------------------------------------------------------------------------
+async function runAuthorizeUrl(args) {
+    assertKnownFlags(args, ...specFor("connections", "authorize-url"));
+    const appArg = args.flags.get("app");
+    const name = args.flags.get("name");
+    if (!appArg || !name) {
+        fail("usage: homespun connections authorize-url --app <idOrSlug> --name <name>", "invalid_args");
+    }
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    printJson({
+        app_id: appId,
+        name: name,
+        authorize_url: client.connectionAuthorizeUrl(appId, name),
+    });
+}

package/dist/commands/credential.js

@@ -0,0 +1,220 @@
+// `homespun credentials` (#1354, #1355, #1363) scoped-service-credential
+// management for a v2 app: mint the bearer token an owner points a backend
+// they host themselves at, list an app's credentials, pause/resume one
+// reversibly, rotate one with an overlap window, and revoke one permanently.
+// Every verb targets an app via a required `--app <idOrSlug>` flag, resolved
+// the same way `homespun grants`/`homespun members`/`homespun data` do
+// (resolveAppId).
+//
+// Auth on the relay side is owner-or-owning-agent; this CLI always
+// authenticates as the owning agent, so any verb works for an app the calling
+// agent's owning human owns. A service credential itself can reach none of
+// these routes (the relay's owner-or-agent gate rejects it at the door), so
+// there is no separate authorization check to add here.
+//
+// mint's raw `token` is printed exactly ONCE (only its sha256 is stored, so
+// it is never recoverable afterward); rotate's new token is printed once the
+// same way.
+import { assertKnownFlags } from "../argv.js";
+import { nounSpec, renderNounHelp, specFor } from "../help-catalog.js";
+import { makeClient } from "../config.js";
+import { fail, failFromError, printJson } from "../output.js";
+import { resolveAppId } from "../resolve-app.js";
+export async function runCredential(args) {
+    const verb = args.positionals[0];
+    if ((verb === undefined || verb === "help") && args.bools.has("help")) {
+        process.stdout.write(renderNounHelp(nounSpec("credentials")) + "\n");
+        return;
+    }
+    if (verb === undefined) {
+        fail("missing verb: homespun credentials <mint|list|pause|resume|rotate|revoke>", "invalid_args");
+    }
+    const sub = {
+        positionals: args.positionals.slice(1),
+        flags: args.flags,
+        bools: args.bools,
+        ...(args.danglingValueFlags !== undefined
+            ? { danglingValueFlags: args.danglingValueFlags }
+            : {}),
+    };
+    switch (verb) {
+        case "mint":
+            return runMint(sub);
+        case "list":
+            return runList(sub);
+        case "pause":
+            return runPause(sub);
+        case "resume":
+            return runResume(sub);
+        case "rotate":
+            return runRotate(sub);
+        case "revoke":
+            return runRevoke(sub);
+        default:
+            fail(`unknown verb '${verb}' (homespun credentials <mint|list|pause|resume|rotate|revoke>)`, "invalid_args");
+    }
+}
+function parseNonNegativeInt(raw, flag) {
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 0) {
+        fail(`${flag} must be a non-negative integer`, "invalid_args");
+    }
+    return n;
+}
+function parsePositiveInt(raw, flag) {
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n <= 0) {
+        fail(`${flag} must be a positive integer`, "invalid_args");
+    }
+    return n;
+}
+// ---------------------------------------------------------------------------
+// mint
+// ---------------------------------------------------------------------------
+async function runMint(args) {
+    assertKnownFlags(args, ...specFor("credentials", "mint"));
+    const appArg = args.flags.get("app");
+    if (!appArg) {
+        fail("usage: homespun credentials mint --app <idOrSlug>", "invalid_args");
+    }
+    const mode = args.flags.get("mode");
+    if (mode !== undefined && mode !== "explicit" && mode !== "following") {
+        fail('--mode must be "explicit" or "following"', "invalid_args");
+    }
+    const grantsRaw = args.flags.get("grants");
+    let grants;
+    if (grantsRaw !== undefined) {
+        let parsed;
+        try {
+            parsed = JSON.parse(grantsRaw);
+        }
+        catch {
+            fail('--grants must be a JSON array, e.g. \'[{"collection":"orders","ops":["read","create"]}]\'', "invalid_args");
+        }
+        if (!Array.isArray(parsed)) {
+            fail("--grants must be a JSON array of allowlist entries", "invalid_args");
+        }
+        grants = parsed;
+    }
+    const ttlRaw = args.flags.get("ttl");
+    const noExpiry = args.bools.has("no-expiry");
+    if (ttlRaw !== undefined && noExpiry) {
+        fail("--ttl and --no-expiry are mutually exclusive", "invalid_args");
+    }
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        printJson(await client.mintAppCredential(appId, {
+            ...(mode !== undefined
+                ? { mode: mode }
+                : {}),
+            ...(grants !== undefined ? { grants } : {}),
+            ...(args.bools.has("members") ? { members: true } : {}),
+            ...(args.flags.get("label") !== undefined
+                ? { label: args.flags.get("label") }
+                : {}),
+            ...(noExpiry
+                ? { ttlSeconds: null }
+                : ttlRaw !== undefined
+                    ? { ttlSeconds: parsePositiveInt(ttlRaw, "--ttl") }
+                    : {}),
+        }));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// list
+// ---------------------------------------------------------------------------
+async function runList(args) {
+    assertKnownFlags(args, ...specFor("credentials", "list"));
+    const appArg = args.flags.get("app");
+    if (!appArg) {
+        fail("usage: homespun credentials list --app <idOrSlug>", "invalid_args");
+    }
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        printJson(await client.listAppCredentials(appId));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// pause / resume
+// ---------------------------------------------------------------------------
+function requireCredentialFlags(args, verb) {
+    const appArg = args.flags.get("app");
+    if (!appArg) {
+        fail(`usage: homespun credentials ${verb} --app <idOrSlug> --credential <credentialId>`, "invalid_args");
+    }
+    const credentialId = args.flags.get("credential");
+    if (!credentialId) {
+        fail("--credential is required", "invalid_args");
+    }
+    return { appArg: appArg, credentialId: credentialId };
+}
+async function runPause(args) {
+    assertKnownFlags(args, ...specFor("credentials", "pause"));
+    const { appArg, credentialId } = requireCredentialFlags(args, "pause");
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        await client.pauseAppCredential(appId, credentialId);
+        printJson({ paused: true, app_id: appId, credential_id: credentialId });
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runResume(args) {
+    assertKnownFlags(args, ...specFor("credentials", "resume"));
+    const { appArg, credentialId } = requireCredentialFlags(args, "resume");
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        await client.resumeAppCredential(appId, credentialId);
+        printJson({ resumed: true, app_id: appId, credential_id: credentialId });
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// rotate
+// ---------------------------------------------------------------------------
+async function runRotate(args) {
+    assertKnownFlags(args, ...specFor("credentials", "rotate"));
+    const { appArg, credentialId } = requireCredentialFlags(args, "rotate");
+    const overlapRaw = args.flags.get("overlap");
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        printJson(await client.rotateAppCredential(appId, credentialId, {
+            ...(overlapRaw !== undefined
+                ? { overlapSeconds: parseNonNegativeInt(overlapRaw, "--overlap") }
+                : {}),
+        }));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// revoke
+// ---------------------------------------------------------------------------
+async function runRevoke(args) {
+    assertKnownFlags(args, ...specFor("credentials", "revoke"));
+    const { appArg, credentialId } = requireCredentialFlags(args, "revoke");
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        await client.revokeAppCredential(appId, credentialId);
+        printJson({ revoked: true, app_id: appId, credential_id: credentialId });
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/commands/deploy.js

@@ -1,14 +1,174 @@
 // `homespun deploy` — create or redeploy an App (spec-cli §3.1). This is the
 // create->redeploy loop the v2 vision names: no `--app` creates a new App;
 // `--app <id>` redeploys an existing one (compat-gated unless --force).
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { makeClient } from "../config.js";
 import { assertKnownFlags } from "../argv.js";
 import { specFor } from "../help-catalog.js";
-import { fail, failFromError, printJson } from "../output.js";
+import { fail, failFromError, printJson, warn } from "../output.js";
 import { resolveJson } from "../input.js";
 import { resolveAppId } from "../resolve-app.js";
+// The subdirectory a directory deploy ships as the relay's multi-file `assets[]`
+// bundle (issue #1225). Deliberately an EXPLICIT directory rather than "every
+// file next to index.html": a whole-directory walk would sweep up node_modules,
+// .git, package.json, lockfiles and source, burn the 50-asset cap on them, and
+// publish source to an origin the whole world can read. `assets/` cannot be
+// triggered by accident.
+const ASSET_DIR = "assets";
+// The reference path KEEPS the `assets/` prefix, so a file at
+// `<dir>/assets/fonts/inter.woff2` is referenced by the page as
+// `assets/fonts/inter.woff2`. What is on disk is what the HTML writes; no
+// prefix-stripping to reason about.
+// Client-side mirrors of the relay's deploy caps (MAX_APP_ASSETS,
+// MAX_BLOB_BYTES in the relay's config). Same pattern as the slug/visibility
+// checks below: fail fast with a message naming the offending file rather than
+// base64 the whole bundle and round-trip a request that will be rejected. The
+// relay re-checks both and stays authoritative.
+const MAX_ASSETS = 50;
+const MAX_ASSET_BYTES = 5_000_000;
+// The relay's asset-path charset (core/app-assets.ts ASSET_PATH_CHARSET).
+// Excludes ':' , whitespace, '%', '\' and every control byte.
+const ASSET_PATH_CHARSET = /^[A-Za-z0-9._/-]+$/;
+// Extensions the relay cannot serve as executable subresources. These have no
+// magic bytes, so they sniff to `application/octet-stream`, pass the upload
+// allowlist, and are then served `Content-Disposition: attachment` with
+// `X-Content-Type-Options: nosniff`, so the browser downloads them instead of
+// running them, and `<script src>` / `<link rel=stylesheet>` silently does
+// nothing. Uploading them would reproduce exactly the silent failure this
+// change exists to remove, so refuse them here with an explanation.
+const NON_SERVABLE_EXTENSIONS = new Set([
+    ".js",
+    ".mjs",
+    ".cjs",
+    ".jsx",
+    ".ts",
+    ".tsx",
+    ".css",
+    ".svg",
+    ".html",
+    ".htm",
+    ".xhtml",
+]);
+// Types the relay CANNOT sniff from magic bytes, where a declared `mime` is the
+// only way the asset is stored as itself rather than as octet-stream. For
+// everything else (images, fonts, audio, video, pdf) the mime is omitted
+// deliberately: the relay sniffs the real type, and a declared type that
+// disagrees with the bytes is rejected.
+const DECLARED_MIME_BY_EXTENSION = new Map([
+    [".txt", "text/plain"],
+    [".csv", "text/csv"],
+    [".md", "text/markdown"],
+    [".json", "application/json"],
+    [".zip", "application/zip"],
+    [
+        ".docx",
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ],
+    [
+        ".xlsx",
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ],
+    [
+        ".pptx",
+        "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    ],
+]);
+/** Lowercase extension including the dot, or "" when there is none. */
+function extensionOf(path) {
+    const base = path.slice(path.lastIndexOf("/") + 1);
+    const dot = base.lastIndexOf(".");
+    return dot <= 0 ? "" : base.slice(dot).toLowerCase();
+}
+/**
+ * Every file under `<dir>/assets/`, as paths relative to that directory,
+ * depth-first and sorted so a deploy is byte-identical across machines.
+ *
+ * Dot-prefixed entries are skipped at every level: `.DS_Store`, `.gitkeep` and
+ * editor droppings are never intended as assets, and the relay's path charset
+ * would take them anyway, so skipping is the only way they do not silently
+ * consume the asset budget.
+ */
+function walkAssetDir(assetRoot, rel, out) {
+    const entries = readdirSync(rel === "" ? assetRoot : join(assetRoot, rel), {
+        withFileTypes: true,
+    });
+    for (const entry of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+        if (entry.name.startsWith("."))
+            continue;
+        const childRel = rel === "" ? entry.name : `${rel}/${entry.name}`;
+        if (entry.isDirectory()) {
+            walkAssetDir(assetRoot, childRel, out);
+        }
+        else if (entry.isFile()) {
+            out.push(childRel);
+        }
+        // Anything else (symlink, socket, fifo) is skipped: not a file we can read
+        // bytes from with any confidence about what they are.
+    }
+}
+/**
+ * Read `<source>/assets/**` into the relay's `assets[]` bundle shape.
+ *
+ * Returns `undefined` when there is no `assets/` directory at all, which the
+ * relay reads as "carry the live asset set forward" on a redeploy. That
+ * distinction matters: a directory that never had an `assets/` folder must not
+ * wipe assets an agent uploaded through the MCP `deploy_app` path. An `assets/`
+ * directory that exists but is empty returns `[]`, the relay's explicit
+ * "clear the assets".
+ */
+function readAssets(source) {
+    const assetRoot = join(source, ASSET_DIR);
+    if (!existsSync(assetRoot) || !statSync(assetRoot).isDirectory()) {
+        return undefined;
+    }
+    const relPaths = [];
+    walkAssetDir(assetRoot, "", relPaths);
+    if (relPaths.length > MAX_ASSETS) {
+        fail(`too many assets: ${ASSET_DIR}/ holds ${relPaths.length} files, the limit is ${MAX_ASSETS} per deploy`, "invalid_args");
+    }
+    return relPaths.map((rel) => {
+        // Mirror of the relay's validateAssetPath charset. A space or an accent in
+        // 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");
+        }
+        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");
+        }
+        const mime = DECLARED_MIME_BY_EXTENSION.get(ext);
+        return {
+            path: `${ASSET_DIR}/${rel}`,
+            content_base64: bytes.toString("base64"),
+            ...(mime !== undefined ? { mime } : {}),
+        };
+    });
+}
+/**
+ * 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:
+ * the deploy succeeds, and the app 404s on a file the author can plainly see in
+ * the directory.
+ */
+function warnAboutIgnoredFiles(source) {
+    const ignored = readdirSync(source, { withFileTypes: true })
+        .filter((e) => !e.name.startsWith(".") &&
+        e.name !== "index.html" &&
+        e.name !== "manifest.json" &&
+        !(e.isDirectory() && e.name === ASSET_DIR))
+        .map((e) => (e.isDirectory() ? `${e.name}/` : e.name))
+        .sort();
+    if (ignored.length === 0)
+        return;
+    warn(`not deploying ${ignored.length} entr${ignored.length === 1 ? "y" : "ies"} in ${source}: ${ignored.join(", ")}. A directory deploy ships index.html, manifest.json and everything under ${ASSET_DIR}/. Move files you want served into ${ASSET_DIR}/.`);
+}
 function readBundle(source, manifestFlag, isRedeploy) {
     // No source at all: only a redeploy can do this, and only to change the
     // manifest alone (the live document is inherited).
@@ -39,9 +199,12 @@ function readBundle(source, manifestFlag, isRedeploy) {
         if (missing.length > 0) {
             fail(`directory deploy is missing required file(s): ${missing.join(", ")}`, "invalid_args");
         }
+        warnAboutIgnoredFiles(source);
+        const assets = readAssets(source);
         return {
             html: readFileSync(htmlPath, "utf8"),
             manifest: JSON.parse(readFileSync(manifestPath, "utf8")),
+            ...(assets !== undefined ? { assets } : {}),
         };
     }
     // Single-file escape hatch. A create must pair it with --manifest; a
@@ -81,6 +244,7 @@ export async function runDeploy(args) {
                 ...(id !== undefined ? { app_id: id } : {}),
                 ...(bundle.html !== undefined ? { html: bundle.html } : {}),
                 ...(bundle.manifest !== undefined ? { manifest: bundle.manifest } : {}),
+                ...(bundle.assets !== undefined ? { assets: bundle.assets } : {}),
                 ...(force ? { force } : {}),
             });
             printJson(result);
@@ -105,6 +269,7 @@ export async function runDeploy(args) {
                 manifest: bundle.manifest,
                 visibility,
                 slug,
+                ...(bundle.assets !== undefined ? { assets: bundle.assets } : {}),
             });
             printJson(out);
         }
@@ -122,13 +287,17 @@ export async function runDeploy(args) {
     }
     const id = await resolveAppId(client, appId);
     try {
-        // Only what this invocation actually read is sent: an omitted html or
-        // manifest keeps what is live, so `homespun deploy ./index.html --app <id>`
-        // ships the document alone and `--manifest` with no file ships the
-        // manifest alone.
+        // 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.
         const redeployed = await client.redeployApp(id, {
             ...(bundle.html !== undefined ? { html: bundle.html } : {}),
             ...(bundle.manifest !== undefined ? { manifest: bundle.manifest } : {}),
+            ...(bundle.assets !== undefined ? { assets: bundle.assets } : {}),
             force,
         });
         const app = await client.getApp(id);

package/dist/help-catalog.js

@@ -610,6 +610,289 @@ const GRANTS = {
         "revoke is idempotent; a revoked link is rejected on every subsequent request.",
     ],
 };
+const CREDENTIALS = {
+    noun: "credentials",
+    tagline: "scoped service credential management",
+    group: "app",
+    rootSummary: "App service-credential management: mint, list, pause, resume, rotate, revoke. Mint the bearer token an owner points a backend they host themselves at.",
+    verbs: [
+        {
+            verb: "mint",
+            summary: "Mints a scoped service credential and prints its raw token once.",
+            flags: [
+                {
+                    name: "app",
+                    value: "<idOrSlug>",
+                    description: "App to mint the credential for (required)",
+                },
+                {
+                    name: "mode",
+                    value: "<explicit|following>",
+                    description: "explicit (default): an unnamed collection is denied. following: an unnamed collection falls through to the owner's authority and each grant only narrows",
+                },
+                {
+                    name: "grants",
+                    value: "<json>",
+                    description: "The allowlist as a JSON array of {collection, ops, scope?} entries (see notes)",
+                },
+                {
+                    name: "label",
+                    value: "<text>",
+                    description: "Human-readable label for the credential",
+                },
+                {
+                    name: "ttl",
+                    value: "<seconds>",
+                    description: "Lifetime in seconds, default 365 days and clamped to the server max",
+                },
+            ],
+            bools: [
+                {
+                    name: "members",
+                    description: "Opt this credential into the app's member directory (default off)",
+                },
+                {
+                    name: "no-expiry",
+                    description: "NO EXPIRY, an explicit opt-in for a long-running backend. Mutually exclusive with --ttl",
+                },
+            ],
+        },
+        {
+            verb: "list",
+            summary: "Lists the app's service credentials.",
+            flags: [
+                {
+                    name: "app",
+                    value: "<idOrSlug>",
+                    description: "App to list credentials for (required)",
+                },
+            ],
+        },
+        {
+            verb: "pause",
+            summary: "Reversibly stops one credential.",
+            flags: [
+                {
+                    name: "app",
+                    value: "<idOrSlug>",
+                    description: "App the credential belongs to (required)",
+                },
+                {
+                    name: "credential",
+                    value: "<credentialId>",
+                    description: "Credential to pause (required)",
+                },
+            ],
+        },
+        {
+            verb: "resume",
+            summary: "Undoes a pause. Never undoes a revoke, which is permanent.",
+            flags: [
+                {
+                    name: "app",
+                    value: "<idOrSlug>",
+                    description: "App the credential belongs to (required)",
+                },
+                {
+                    name: "credential",
+                    value: "<credentialId>",
+                    description: "Credential to resume (required)",
+                },
+            ],
+        },
+        {
+            verb: "rotate",
+            summary: "Issues a fresh token and keeps the old one live for an overlap window, printing the new token once.",
+            flags: [
+                {
+                    name: "app",
+                    value: "<idOrSlug>",
+                    description: "App the credential belongs to (required)",
+                },
+                {
+                    name: "credential",
+                    value: "<credentialId>",
+                    description: "Credential to rotate (required)",
+                },
+                {
+                    name: "overlap",
+                    value: "<seconds>",
+                    description: "How long the superseded token keeps working (default 1 day, clamped to a server max); 0 kills it immediately",
+                },
+            ],
+        },
+        {
+            verb: "revoke",
+            summary: "Revokes one credential permanently.",
+            flags: [
+                {
+                    name: "app",
+                    value: "<idOrSlug>",
+                    description: "App the credential belongs to (required)",
+                },
+                {
+                    name: "credential",
+                    value: "<credentialId>",
+                    description: "Credential to revoke (required)",
+                },
+            ],
+        },
+    ],
+    notes: [
+        "--app accepts either the app_id or its slug (resolved via GET /v1/apps?slug= when it does not look like a cuid).",
+        "A credential is the bearer token an app owner points a backend they host themselves at. Effective permission is always the intersection of the allowlist and what the app's owner could do, so a credential can only ever narrow, never widen, and it carries no role.",
+        "mint's raw token is shown ONCE in the response and is never recoverable afterward (only its sha256 is stored); if it is lost, rotate or mint a new one. --grants names each collection the credential may reach and which of read/create/update/delete it may attempt there; a collection not named is denied under --mode explicit (the default) and falls through to the owner's own authority under --mode following. An entry may set a `scope` of \"own\" to narrow every row-addressed op to rows the credential itself wrote last.",
+        "pause is reversible; resume undoes it. revoke is permanent and idempotent, and also kills any token a rotation left inside its overlap window. Every verb here is owner-or-owning-agent only: a service credential itself can reach none of these.",
+    ],
+};
+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.",
+    verbs: [
+        {
+            verb: "create",
+            summary: "Creates a static or oauth2 connection.",
+            flags: [
+                {
+                    name: "app",
+                    value: "<idOrSlug>",
+                    description: "App to create the connection on (required)",
+                },
+                {
+                    name: "name",
+                    value: "<name>",
+                    description: "Connection name a manifest webhook rule's `connection` field references (required)",
+                },
+                {
+                    name: "allowed-host",
+                    value: "<host>",
+                    description: "Host-binding: an exact DNS host or a single leftmost '*.' wildcard (required)",
+                },
+                {
+                    name: "kind",
+                    value: "<static|oauth2>",
+                    description: "Defaults to static",
+                },
+                {
+                    name: "provider",
+                    value: "<text>",
+                    description: 'Freeform display label, e.g. "hubspot"',
+                },
+                {
+                    name: "label",
+                    value: "<text>",
+                    description: "Human-readable label for the connection",
+                },
+                {
+                    name: "header-name",
+                    value: "<name>",
+                    description: "static only. Defaults to Authorization",
+                },
+                {
+                    name: "header-value",
+                    value: "<value>",
+                    description: 'static only, required. The header value to send, e.g. "Bearer sk_live_..."',
+                },
+                {
+                    name: "authorize-url",
+                    value: "<url>",
+                    description: "oauth2 only, required. The provider's authorize endpoint",
+                },
+                {
+                    name: "token-url",
+                    value: "<url>",
+                    description: "oauth2 only, required. The provider's token endpoint",
+                },
+                {
+                    name: "client-id",
+                    value: "<id>",
+                    description: "oauth2 only, required. Your OAuth2 app's client id",
+                },
+                {
+                    name: "client-secret",
+                    value: "<secret>",
+                    description: "oauth2 only, required. Your OAuth2 app's client secret",
+                },
+                {
+                    name: "scopes",
+                    value: "<text>",
+                    description: "oauth2 only. Space-delimited scopes for the authorize request",
+                },
+                {
+                    name: "auth-scheme",
+                    value: "<text>",
+                    description: 'oauth2 only. Defaults to "Bearer"',
+                },
+                {
+                    name: "instance-field",
+                    value: "<field>",
+                    description: 'oauth2 only. Token-response JSON field holding the API base URL, e.g. "instance_url"',
+                },
+                {
+                    name: "auth-params",
+                    value: "<json>",
+                    description: "oauth2 only. Extra key/values merged into the authorize redirect",
+                },
+                {
+                    name: "token-params",
+                    value: "<json>",
+                    description: "oauth2 only. Extra key/values merged into the token POST",
+                },
+            ],
+        },
+        {
+            verb: "list",
+            summary: "Lists the app's connections as metadata plus a fingerprint, never a secret.",
+            flags: [
+                {
+                    name: "app",
+                    value: "<idOrSlug>",
+                    description: "App to list connections for (required)",
+                },
+            ],
+        },
+        {
+            verb: "delete",
+            summary: "Deletes a connection, idempotently.",
+            flags: [
+                {
+                    name: "app",
+                    value: "<idOrSlug>",
+                    description: "App the connection belongs to (required)",
+                },
+                {
+                    name: "name",
+                    value: "<name>",
+                    description: "Connection to delete (required)",
+                },
+            ],
+        },
+        {
+            verb: "authorize-url",
+            summary: "Prints the browser URL that completes an oauth2 connection's owner consent. Never fetched by this command.",
+            flags: [
+                {
+                    name: "app",
+                    value: "<idOrSlug>",
+                    description: "App the connection belongs to (required)",
+                },
+                {
+                    name: "name",
+                    value: "<name>",
+                    description: "oauth2 connection to build the URL for (required)",
+                },
+            ],
+        },
+    ],
+    notes: [
+        "--app accepts either the app_id or its slug (resolved via GET /v1/apps?slug= when it does not look like a cuid).",
+        "A connection is the stored credential a manifest webhook rule authenticates its delivery target with, bound to a host so it can never be sent to another one. There is no update verb: change a connection by deleting and recreating it.",
+        "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.",
+    ],
+};
 const KEY = {
     noun: "key",
     tagline: "your agent's API key",
@@ -675,9 +958,9 @@ const TASTE = {
 };
 const FEEDBACK = {
     noun: "feedback",
-    tagline: "feedback to the relay operator",
+    tagline: "report a problem with homespun itself",
     group: "other",
-    rootSummary: "One-shot feedback to the relay operator: create, list. Bug reports, feature requests, and notes.",
+    rootSummary: "Report a problem with homespun itself to the relay operator: create, list. Bug reports, feature requests, and notes.",
     verbs: [
         {
             verb: "create",
@@ -718,8 +1001,12 @@ const FEEDBACK = {
         },
     ],
     notes: [
-        "Feedback is a one-shot bug report, feature request, or note from your agent to whoever runs the relay. Submissions are stored in the relay DB and the operator triages them out of band.",
-        "create does not echo the message back. list prints { items: [...], next_before } so you can pass --before <cursor> from a previous page to fetch the next one.",
+        "Feedback is a one-shot bug report, feature request, or note from your agent to whoever runs the relay. Submissions are stored in the relay DB and the operator triages them out of band. This is the channel that turns a problem you hit into a problem that gets fixed, so file without being asked: nobody will prompt you, and an unreported failure is one the operator cannot see.",
+        "File a report when: a command returns a 5xx or an error code the skill does not describe; documented and observed behaviour disagree; what you need cannot be expressed at all (a missing capability, a self-contradictory schema); a deployed app misbehaves in a way that traces back to the platform rather than to HTML you wrote; or the skill was wrong, ambiguous or silent and you had to guess. An error envelope carrying a `report` field is the CLI telling you the failure was homespun's, not yours.",
+        "Do not file: problems with the human's own task, or bugs in an app you authored; presentation preferences, which belong in 'homespun taste'; the human's own configuration, such as a missing API key or the wrong account; or a 4xx caused by arguments you got wrong, unless the error message itself sent you the wrong way, which is a documentation bug worth --type note.",
+        "Report once, not once per retry. Run 'homespun feedback list' first and skip anything already recorded; one report per distinct failure per session. An agent in a retry loop filing the same row twenty times buries the signal it was trying to send.",
+        "Say enough that it can be fixed without you: the operator sees the row, not your session, so \"deploy failed\" is unactionable. Structure the message as surface (mcp|cli|relay|app-runtime); where (the command or route); versions (cli from 'homespun --version', skill from 'homespun skill version'); expected, one line; observed, one line carrying the exact error code and message; repro, the minimal steps or the arguments you passed. Pipe it in with --message - rather than fighting shell quoting.",
+        "There is no reply channel, so never use feedback for anything you need an answer to. create does not echo the message back. list prints { items: [...], next_before } so you can pass --before <cursor> from a previous page to fetch the next one.",
     ],
 };
 const CONFIG = {
@@ -846,8 +1133,9 @@ const DEPLOY = {
     ],
     notes: [
         "Packaging has one canonical shape and one escape hatch. A directory deploy (homespun deploy ./my-app) reads ./my-app/index.html and ./my-app/manifest.json: fixed filenames, no discovery heuristics, and both files are required. The single-file escape hatch (homespun deploy ./index.html --manifest ./manifest.json) takes the manifest from --manifest, which accepts a file path or inline JSON.",
+        "Files to serve alongside the document go in ./my-app/assets/. Everything under it ships as the deploy's asset bundle and is served on the app's own origin at the same path, so ./my-app/assets/fonts/inter.woff2 is referenced by the page as assets/fonts/inter.woff2. Nested directories are kept, dot-prefixed entries are skipped, and the limits are 50 files at up to 5 MB each. Only assets/ is shipped: anything else sitting next to index.html is reported on stderr and left behind, so a stray node_modules or package.json is never published. Scripts and stylesheets cannot be assets. The relay serves .js, .css and .svg as an inert download, so a browser would refuse to run or apply them; the app CSP allows inline script and style, so put them in index.html.",
         "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. The live asset set is carried forward either way. A create can inherit nothing, so it still needs both halves.",
+        "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.",
     ],
     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.',
@@ -1277,6 +1565,8 @@ const NOUNS = [
     DATA,
     MEMBERS,
     GRANTS,
+    CREDENTIALS,
+    CONNECTIONS,
     INGEST,
     PUBLISHER,
     TEMPLATE,

package/dist/index.js

@@ -38,6 +38,8 @@ import { runApps } from "./commands/apps.js";
 import { runData } from "./commands/data.js";
 import { runMembers } from "./commands/members.js";
 import { runGrant } from "./commands/grant.js";
+import { runCredential } from "./commands/credential.js";
+import { runConnection } from "./commands/connection.js";
 import { runIngest } from "./commands/ingest.js";
 import { runPublisher } from "./commands/publisher.js";
 import { runTemplate } from "./commands/template.js";
@@ -129,6 +131,12 @@ async function main() {
         case "grants":
             await runGrant(args);
             break;
+        case "credentials":
+            await runCredential(args);
+            break;
+        case "connections":
+            await runConnection(args);
+            break;
         case "ingest":
             await runIngest(args);
             break;

package/dist/output.js

@@ -1,12 +1,20 @@
 // stdout/stderr helpers. The CLI is JSON-by-default: machine-readable on
 // stdout, human errors on stderr.
-import { HomespunApiError } from "@homespunapps/core";
+import { HomespunApiError, RELAY_FAILURE_REPORT_HINT, } from "@homespunapps/core";
 import { fileURLToPath } from "node:url";
 import { detectInstallMethod, upgradeCommandFor, formatUpgradeMessage, EXIT_CLI_UPGRADE_REQUIRED, } from "./upgrade.js";
 /** Print a value as pretty JSON to stdout. */
 export function printJson(value) {
     process.stdout.write(JSON.stringify(value, null, 2) + "\n");
 }
+/**
+ * Print a non-fatal advisory to STDERR. Never stdout: stdout carries the JSON
+ * result a caller pipes into `jq`, and a warning mixed into it would make that
+ * output unparseable.
+ */
+export function warn(message) {
+    process.stderr.write(`warning: ${message}\n`);
+}
 /**
  * Print a single compact JSON line to stdout and flush. Used by `homespun watch`
  * so a pipe-reader (e.g. Claude Code's Monitor tool) sees each event
@@ -24,6 +32,8 @@ export function fail(message, code = "error", details, extra) {
         error["retryable"] = extra.retryable;
     if (extra?.docs_url !== undefined)
         error["docs_url"] = extra.docs_url;
+    if (extra?.report !== undefined)
+        error["report"] = extra.report;
     if (details !== undefined)
         error["details"] = details;
     process.stderr.write(JSON.stringify({ error }) + "\n");
@@ -46,6 +56,11 @@ export function failFromError(err) {
             hint: err.hint,
             retryable: err.retryable,
             docs_url: err.docsUrl,
+            // 5xx only: the relay failed, so the agent is the only witness and the
+            // report is worth prompting. A 4xx is normally the caller's own bad
+            // argument, and prompting there would fill the operator's queue with
+            // rows they have to triage and close.
+            ...(err.status >= 500 ? { report: RELAY_FAILURE_REPORT_HINT } : {}),
         });
     }
     fail(err instanceof Error ? err.message : String(err), "internal");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homespunapps/cli",
-  "version": "1.6.44",
+  "version": "1.6.45",
   "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.44",
+    "@homespunapps/core": "^1.6.45",
     "qrcode-terminal": "^0.12.0"
   },
   "devDependencies": {