@homespunapps/cli 1.4.3 → 1.5.1

package/dist/commands/ingest.js

@@ -24,7 +24,7 @@ export async function runIngest(args) {
         return;
     }
     if (verb === undefined) {
-        fail("missing verb (homespun ingest <list|rotate>)", "invalid_args");
+        fail("missing verb (homespun ingest <list|rotate|signing-secret>)", "invalid_args");
     }
     const sub = {
         positionals: args.positionals.slice(1),
@@ -39,8 +39,10 @@ export async function runIngest(args) {
             return runList(sub);
         case "rotate":
             return runRotate(sub);
+        case "signing-secret":
+            return runSigningSecret(sub);
         default:
-            fail(`unknown verb '${verb}' (homespun ingest <list|rotate>)`, "invalid_args");
+            fail(`unknown verb '${verb}' (homespun ingest <list|rotate|signing-secret>)`, "invalid_args");
     }
 }
 // ---------------------------------------------------------------------------
@@ -83,3 +85,79 @@ async function runRotate(args) {
         failFromError(e);
     }
 }
+// ---------------------------------------------------------------------------
+// signing-secret set|clear
+// ---------------------------------------------------------------------------
+//
+// The SIGNING secret is separate from the URL secret above (opt-in webhook
+// signature verification, issue #935, shipped dark: nothing verifies a
+// signature yet). `set` without --secret MINTS one and prints it ONCE (the
+// GitHub path); `set --secret <val>` stores a provider-generated value verbatim
+// (the Stripe path) and never echoes it; `clear` removes it.
+async function runSigningSecret(args) {
+    const action = args.positionals[0];
+    const sub = {
+        positionals: args.positionals.slice(1),
+        flags: args.flags,
+        bools: args.bools,
+        ...(args.danglingValueFlags !== undefined
+            ? { danglingValueFlags: args.danglingValueFlags }
+            : {}),
+    };
+    switch (action) {
+        case "set":
+            return runSigningSecretSet(sub);
+        case "clear":
+            return runSigningSecretClear(sub);
+        default:
+            fail("usage: homespun ingest signing-secret <set|clear> --app <idOrSlug> --name <hookName>", "invalid_args");
+    }
+}
+async function runSigningSecretSet(args) {
+    assertKnownFlags(args, ...specFor("ingest", "signing-secret"));
+    const appArg = args.flags.get("app");
+    const name = args.flags.get("name");
+    if (!appArg || !name) {
+        fail("usage: homespun ingest signing-secret set --app <idOrSlug> --name <hookName> [--secret <value>] [--grace-seconds <n>]", "invalid_args");
+    }
+    const secret = args.flags.get("secret");
+    const graceRaw = args.flags.get("grace-seconds");
+    let graceSeconds;
+    if (graceRaw !== undefined) {
+        graceSeconds = Number(graceRaw);
+        if (!Number.isFinite(graceSeconds)) {
+            fail("--grace-seconds must be a number", "invalid_args");
+        }
+    }
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        const res = await client.setIngestSigningSecret(appId, name, {
+            ...(secret !== undefined ? { secret } : {}),
+            ...(graceSeconds !== undefined ? { graceSeconds } : {}),
+        });
+        printJson(res);
+        if (res.secret !== undefined) {
+            process.stderr.write("Store this signing secret now: it will not be shown again. Paste it into the provider's webhook settings.\n");
+        }
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runSigningSecretClear(args) {
+    assertKnownFlags(args, ...specFor("ingest", "signing-secret"));
+    const appArg = args.flags.get("app");
+    const name = args.flags.get("name");
+    if (!appArg || !name) {
+        fail("usage: homespun ingest signing-secret clear --app <idOrSlug> --name <hookName>", "invalid_args");
+    }
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        printJson(await client.clearIngestSigningSecret(appId, name));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/help-catalog.js

@@ -129,10 +129,15 @@ const DATA = {
     tagline: "collection row CRUD for an app",
     group: "app",
     rootSummary: "Collection row CRUD for an app: list, get, upsert, update, delete, purge, import.",
+    // The data parser is verb-LAST: `homespun data <app> <collection> <verb>`
+    // (see commands/data.ts, which reads the verb from positionals[2]). Every
+    // other noun is verb-first. Each verb below carries only the positionals that
+    // FOLLOW the verb; <app> <collection> come before it, via commonPositionals.
+    verbLast: true,
+    commonPositionals: "<app> <collection>",
     verbs: [
         {
             verb: "list",
-            positionals: "<app> <collection>",
             summary: "Lists rows in a collection.",
             flags: [
                 {
@@ -155,12 +160,11 @@ const DATA = {
         },
         {
             verb: "get",
-            positionals: "<app> <collection> <key>",
+            positionals: "<key>",
             summary: "Shows one row by key.",
         },
         {
             verb: "upsert",
-            positionals: "<app> <collection>",
             summary: "Creates a row, or ensures one exists at a key or unique field.",
             flags: [
                 {
@@ -182,7 +186,7 @@ const DATA = {
         },
         {
             verb: "update",
-            positionals: "<app> <collection> <key>",
+            positionals: "<key>",
             summary: "Replaces an existing row's data.",
             flags: [
                 {
@@ -199,7 +203,7 @@ const DATA = {
         },
         {
             verb: "delete",
-            positionals: "<app> <collection> <key>",
+            positionals: "<key>",
             summary: "Deletes one row by key.",
             flags: [
                 {
@@ -212,7 +216,6 @@ const DATA = {
         },
         {
             verb: "purge",
-            positionals: "<app> <collection>",
             summary: "Removes one row even from an append-only collection.",
             flags: [
                 {
@@ -225,7 +228,6 @@ const DATA = {
         },
         {
             verb: "import",
-            positionals: "<app> <collection>",
             summary: "Bulk-writes rows from a file in chunks via the batch API.",
             flags: [
                 {
@@ -370,7 +372,7 @@ const INGEST = {
     noun: "ingest",
     tagline: "inbound catch-hook read surface",
     group: "app",
-    rootSummary: "Inbound catch-hook management: list, rotate. Read back an app's declared inbound hooks with their full secret URL so you can tell the owner where an external system posts, or rotate a leaked secret. Hooks themselves are declared in the app manifest (x-homespun-manifest.ingest).",
+    rootSummary: "Inbound catch-hook management: list, rotate, signing-secret. Read back an app's declared inbound hooks with their full secret URL so you can tell the owner where an external system posts, rotate a leaked URL secret, or manage a hook's opt-in signing secret. Hooks themselves are declared in the app manifest (x-homespun-manifest.ingest).",
     verbs: [
         {
             verb: "list",
@@ -399,11 +401,39 @@ const INGEST = {
                 },
             ],
         },
+        {
+            verb: "signing-secret",
+            positionals: "<set|clear>",
+            summary: "Sets, rotates, or clears a hook's opt-in signing secret (webhook signature verification).",
+            flags: [
+                {
+                    name: "app",
+                    value: "<idOrSlug>",
+                    description: "App the hook belongs to (required)",
+                },
+                {
+                    name: "name",
+                    value: "<hookName>",
+                    description: "Name of the manifest ingest hook (required)",
+                },
+                {
+                    name: "secret",
+                    value: "<value>",
+                    description: "set only: a provider-generated signing secret to store verbatim; omit to have the relay mint one (shown once)",
+                },
+                {
+                    name: "grace-seconds",
+                    value: "<n>",
+                    description: "set only: how long the previous secret stays valid on a rotation (default 3600, max 86400)",
+                },
+            ],
+        },
     ],
     notes: [
         "--app accepts either the app_id or its slug (resolved via GET /v1/apps?slug= when it does not look like a cuid).",
         "list returns { hooks: [{ name, url, collection, mode, wake, handshake, disabledAt, createdAt, deliveries: { accepted, failed, dropped_duplicate } }] }. The url is the full secret POST URL an external system posts JSON to; hand it to the app owner to paste into Stripe, Zapier, Make, Home Assistant, or any system that can POST a webhook. A hook whose rule left the manifest has disabledAt set and null rule fields.",
         "rotate mints a fresh secret for the named hook and returns { hook: { name, url } } with the NEW url once. The old url stops working immediately; no redeploy is needed. Use it when a url leaks.",
+        "signing-secret manages a hook's OPT-IN signing secret, distinct from the URL secret above: it is what a provider (GitHub, Stripe, ...) HMACs the request body with. `set` without --secret mints one and returns { secret, fingerprint, setAt } with the value shown ONCE; `set --secret <value>` stores a provider-generated value verbatim and returns { fingerprint, setAt } without echoing it; `clear` removes it. A rotation keeps the previous secret valid for --grace-seconds so deliveries verify while you update the provider. A hook that declares `verify` in its manifest rule (GitHub scheme in v1) requires a valid signature over the raw body and stays fail-closed (401) until this secret is set; the fingerprint (a plaintext-derived id) lets you confirm which secret is set without the relay ever showing it.",
         "Hooks are declared in the app manifest (x-homespun-manifest.ingest) and materialized at deploy, so there is no create or delete verb here: add or remove a hook by editing the manifest and redeploying.",
     ],
 };
@@ -938,13 +968,28 @@ export function specFor(noun, verb = "") {
         ["homespun", noun, verb].filter(Boolean).join(" "),
     ];
 }
-/** "homespun apps watch <app> [--since <cursor>] [--once]" */
+/**
+ * "homespun apps watch <app> [--since <cursor>] [--once]", and for a verbLast
+ * noun "homespun data <app> <collection> get <key>".
+ */
 export function usageLine(noun, v) {
     const parts = ["homespun", noun.noun];
-    if (v.verb)
-        parts.push(v.verb);
-    if (v.positionals)
-        parts.push(v.positionals);
+    if (noun.verbLast) {
+        // Common positionals precede the verb, per the parser's grammar; the verb's
+        // own positionals (if any) follow it.
+        if (noun.commonPositionals)
+            parts.push(noun.commonPositionals);
+        if (v.verb)
+            parts.push(v.verb);
+        if (v.positionals)
+            parts.push(v.positionals);
+    }
+    else {
+        if (v.verb)
+            parts.push(v.verb);
+        if (v.positionals)
+            parts.push(v.positionals);
+    }
     for (const f of v.flags ?? []) {
         parts.push(f.value ? `[--${f.name} ${f.value}]` : `[--${f.name}]`);
     }
@@ -1070,7 +1115,15 @@ export function renderNounHelp(noun) {
         ]);
         const col = Math.min(34, all.reduce((w, f) => Math.max(w, spelled(f).length), 0) + 2);
         for (const v of flagged) {
-            out.push(`  ${["homespun", noun.noun, v.verb].filter(Boolean).join(" ")}`);
+            // Verb-last nouns (data) must show <app> <collection> before the verb
+            // here too, matching the Usage block and the parser. A bare
+            // "homespun data list" header is the exact verb-first shape #907 fixed.
+            const header = noun.verbLast
+                ? ["homespun", noun.noun, noun.commonPositionals, v.verb]
+                    .filter(Boolean)
+                    .join(" ")
+                : ["homespun", noun.noun, v.verb].filter(Boolean).join(" ");
+            out.push(`  ${header}`);
             for (const f of [...(v.flags ?? []), ...(v.bools ?? [])]) {
                 const left = `    ${spelled(f)}`;
                 const pad = Math.max(1, col + 4 - left.length);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homespunapps/cli",
-  "version": "1.4.3",
+  "version": "1.5.1",
   "description": "Command-line client for the Homespun relay: create apps, inspect state, send and watch events.",
   "license": "MIT",
   "type": "module",
@@ -36,7 +36,7 @@
     "test:unit": "vitest run"
   },
   "dependencies": {
-    "@homespunapps/core": "^1.4.3",
+    "@homespunapps/core": "^1.5.1",
     "qrcode-terminal": "^0.12.0"
   },
   "devDependencies": {