@homespunapps/cli 1.0.0 → 1.4.2

package/dist/commands/feedback.js

@@ -1,48 +1,7 @@
 import { assertKnownFlags } from "../argv.js";
+import { specFor } from "../help-catalog.js";
 import { makeClient } from "../config.js";
 import { printJson, fail, failFromError } from "../output.js";
-const CREATE_FLAGS = ["type", "message", "app-id"];
-const LIST_FLAGS = ["limit", "before"];
-const NO_BOOLS = [];
-export const feedbackHelp = `homespun feedback — submit / list feedback to the relay operator
-
-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; the
-operator triages out of band.
-
-Usage:
-  homespun feedback <subcommand> [options]
-
-Subcommands:
-  create     Submit one feedback row. Requires --type and --message.
-             Prints { id, type, created_at } — the message is not echoed back.
-
-  list       List YOUR agent's own submissions, newest first. Prints
-             { items: [...], next_before?: <cursor> }. Pass --before <cursor>
-             from a previous page to fetch the next page.
-
-Options for 'create':
-  --type <bug|feature|note>   Feedback category. Required.
-  --message <text|->          Message body. Pass '-' to read from stdin.
-                              1..4000 chars after trim.
-  --app-id <id>               Optional App this feedback relates to;
-                              must be owned by YOUR agent's human.
-
-Options for 'list':
-  --limit <N>                 Page size (default 50, max 100).
-  --before <cursor>           Opaque cursor from a previous page's next_before.
-
-Global:
-  --url <url>                 Relay base URL (overrides HOMESPUN_URL).
-  --api-key <key>             Agent API key (overrides HOMESPUN_API_KEY).
-  -h, --help                  Show this help.
-
-Examples:
-  homespun feedback create --type bug --message "watch hangs on empty app"
-  echo "long-form note..." | homespun feedback create --type note --message -
-  homespun feedback list --limit 20
-
-Output: stdout is machine-readable JSON.`;
 const FEEDBACK_TYPES = ["bug", "feature", "note"];
 async function readStdin() {
     const chunks = [];
@@ -52,7 +11,7 @@ async function readStdin() {
     return Buffer.concat(chunks).toString("utf8");
 }
 async function runFeedbackCreate(args) {
-    assertKnownFlags(args, CREATE_FLAGS, NO_BOOLS, "homespun feedback create");
+    assertKnownFlags(args, ...specFor("feedback", "create"));
     const type = args.flags.get("type");
     const rawMessage = args.flags.get("message");
     const appId = args.flags.get("app-id");
@@ -92,7 +51,7 @@ async function runFeedbackCreate(args) {
     }
 }
 async function runFeedbackList(args) {
-    assertKnownFlags(args, LIST_FLAGS, NO_BOOLS, "homespun feedback list");
+    assertKnownFlags(args, ...specFor("feedback", "list"));
     const limitRaw = args.flags.get("limit");
     const before = args.flags.get("before");
     let limit;

package/dist/commands/grant.js

@@ -0,0 +1,158 @@
+// `homespun grants` (M5) grant-link management for a v2 app: mint a
+// capability URL that confers a DECLARED custom role on a stable, per-holder
+// anonymous identity, list an app's grant links, and revoke one. Every verb
+// targets an app via a required `--app <idOrSlug>` flag, resolved the same way
+// `homespun members`/`homespun data` do (resolveAppId).
+//
+// Auth on the relay side is owner-or-agent; this CLI always authenticates as
+// the owning agent, so any verb works for an app the calling agent's owning
+// human owns.
+//
+// A grant link NEVER escalates: --role must be a DECLARED custom role
+// (x-homespun-manifest.roles), never a built-in role (owner/member/agent). The
+// minted grant_url carries the raw token in its #g= fragment and is printed
+// ONCE (it is never recoverable afterward).
+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 runGrant(args) {
+    const verb = args.positionals[0];
+    if ((verb === undefined || verb === "help") && args.bools.has("help")) {
+        process.stdout.write(renderNounHelp(nounSpec("grants")) + "\n");
+        return;
+    }
+    if (verb === undefined) {
+        fail("missing verb: homespun grants <mint|list|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 "revoke":
+            return runRevoke(sub);
+        default:
+            fail(`unknown verb '${verb}' (homespun grants <mint|list|revoke>)`, "invalid_args");
+    }
+}
+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("grants", "mint"));
+    const appArg = args.flags.get("app");
+    if (!appArg) {
+        fail("usage: homespun grants mint --app <idOrSlug> --role <customRole>", "invalid_args");
+    }
+    const role = args.flags.get("role");
+    if (!role) {
+        fail("--role is required", "invalid_args");
+    }
+    const mode = args.flags.get("mode");
+    if (mode !== undefined && mode !== "once" && mode !== "multi") {
+        fail('--mode must be "once" or "multi"', "invalid_args");
+    }
+    const pinRow = args.flags.get("pin-row");
+    const pinWhereRaw = args.flags.get("pin-where");
+    if (pinRow !== undefined && pinWhereRaw !== undefined) {
+        fail("--pin-row and --pin-where are mutually exclusive", "invalid_args");
+    }
+    let pin;
+    if (pinRow !== undefined) {
+        pin = { rowKey: pinRow };
+    }
+    else if (pinWhereRaw !== undefined) {
+        let parsed;
+        try {
+            parsed = JSON.parse(pinWhereRaw);
+        }
+        catch {
+            fail("--pin-where must be a JSON array of conditions", "invalid_args");
+        }
+        if (!Array.isArray(parsed)) {
+            fail("--pin-where must be a JSON array of conditions", "invalid_args");
+        }
+        pin = { where: parsed };
+    }
+    const maxUsesRaw = args.flags.get("max-uses");
+    const ttlRaw = args.flags.get("ttl");
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        printJson(await client.mintAppGrant(appId, {
+            role: role,
+            ...(mode !== undefined ? { mode: mode } : {}),
+            ...(maxUsesRaw !== undefined
+                ? { maxUses: parsePositiveInt(maxUsesRaw, "--max-uses") }
+                : {}),
+            ...(args.flags.get("label") !== undefined
+                ? { label: args.flags.get("label") }
+                : {}),
+            ...(ttlRaw !== undefined
+                ? { ttlSeconds: parsePositiveInt(ttlRaw, "--ttl") }
+                : {}),
+            ...(pin !== undefined ? { pin } : {}),
+        }));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// list
+// ---------------------------------------------------------------------------
+async function runList(args) {
+    assertKnownFlags(args, ...specFor("grants", "list"));
+    const appArg = args.flags.get("app");
+    if (!appArg) {
+        fail("usage: homespun grants list --app <idOrSlug>", "invalid_args");
+    }
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        printJson(await client.listAppGrants(appId));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// revoke
+// ---------------------------------------------------------------------------
+async function runRevoke(args) {
+    assertKnownFlags(args, ...specFor("grants", "revoke"));
+    const appArg = args.flags.get("app");
+    if (!appArg) {
+        fail("usage: homespun grants revoke --app <idOrSlug> --grant <grantId>", "invalid_args");
+    }
+    const grantId = args.flags.get("grant");
+    if (!grantId) {
+        fail("--grant is required", "invalid_args");
+    }
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        await client.revokeAppGrant(appId, grantId);
+        printJson({ revoked: true, app_id: appId, grant_id: grantId });
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/commands/ingest.js

@@ -0,0 +1,85 @@
+// `homespun ingest`: inbound catch-hook read surface for an app (inbound-webhooks
+// PR 3). List the app's declared hooks with their full secret URL, and rotate a
+// hook's secret. Every verb targets an app via a required `--app <idOrSlug>`,
+// resolved the same way `homespun members`/`homespun data` do (resolveAppId).
+//
+// This is the smallest surface an agent needs during app setup: after deploying
+// a manifest that declares an `ingest` hook, the agent runs `homespun ingest list`
+// to read back the exact URL and tells its owner to paste it into Stripe/Zapier/
+// Home Assistant/etc. Hooks are manifest-declared, so there is no create/delete
+// here; `rotate` re-keys a leaked URL without a redeploy.
+//
+// Auth on the relay side is owner-or-agent (the owning agent's API key OR the
+// owner human's login cookie); this CLI always authenticates as the agent, so
+// both verbs work for an app the calling agent's owning human owns.
+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 runIngest(args) {
+    const verb = args.positionals[0];
+    if ((verb === undefined || verb === "help") && args.bools.has("help")) {
+        process.stdout.write(renderNounHelp(nounSpec("ingest")) + "\n");
+        return;
+    }
+    if (verb === undefined) {
+        fail("missing verb (homespun ingest <list|rotate>)", "invalid_args");
+    }
+    const sub = {
+        positionals: args.positionals.slice(1),
+        flags: args.flags,
+        bools: args.bools,
+        ...(args.danglingValueFlags !== undefined
+            ? { danglingValueFlags: args.danglingValueFlags }
+            : {}),
+    };
+    switch (verb) {
+        case "list":
+            return runList(sub);
+        case "rotate":
+            return runRotate(sub);
+        default:
+            fail(`unknown verb '${verb}' (homespun ingest <list|rotate>)`, "invalid_args");
+    }
+}
+// ---------------------------------------------------------------------------
+// list
+// ---------------------------------------------------------------------------
+async function runList(args) {
+    assertKnownFlags(args, ...specFor("ingest", "list"));
+    const appArg = args.flags.get("app");
+    if (!appArg) {
+        fail("usage: homespun ingest list --app <idOrSlug>", "invalid_args");
+    }
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        printJson(await client.listIngestHooks(appId));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
+// rotate
+// ---------------------------------------------------------------------------
+async function runRotate(args) {
+    assertKnownFlags(args, ...specFor("ingest", "rotate"));
+    const appArg = args.flags.get("app");
+    if (!appArg) {
+        fail("usage: homespun ingest rotate --app <idOrSlug> --name <hookName>", "invalid_args");
+    }
+    const name = args.flags.get("name");
+    if (!name) {
+        fail("--name is required", "invalid_args");
+    }
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        printJson(await client.rotateIngestHook(appId, name));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}

package/dist/commands/key.js

@@ -5,37 +5,11 @@
 // authenticated agent, so there is exactly one key — the caller's own. Both
 // verbs therefore act ONLY on the caller's own key.
 import { assertKnownFlags } from "../argv.js";
+import { specFor } from "../help-catalog.js";
 import { makeClient } from "../config.js";
 import { printJson, fail, failFromError } from "../output.js";
-const NO_FLAGS = [];
-const NO_BOOLS = [];
-const REVOKE_BOOLS = ["yes"];
-export const keyHelp = `homespun key — inspect or revoke YOUR agent's API key
-
-Usage:
-  homespun key <verb> [options]
-
-Verbs:
-  list       Show YOUR agent's key info. The relay scopes keys to the
-             authenticated agent — there is exactly one key per agent, your
-             own. Prints { agent_id, name, key_prefix, created_at,
-             last_used_at, revoked_at }.
-
-  revoke     Revoke YOUR OWN API key — a self-destruct. The key stops working
-             IMMEDIATELY; every subsequent command fails until you run
-             'homespun agent register' again to provision a new key. The relay only
-             allows revoking your own key. Requires --yes to confirm.
-             Prints { revoked: true, agent_id }.
-
-Options:
-  --yes               Confirm 'key revoke' (required — it is irreversible).
-  --url <url>         Relay base URL (overrides HOMESPUN_URL).
-  --api-key <key>     Agent API key (overrides HOMESPUN_API_KEY).
-  -h, --help          Show this help.
-
-Output: stdout is machine-readable JSON.`;
 async function runKeyList(args) {
-    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "homespun key list");
+    assertKnownFlags(args, ...specFor("key", "list"));
     const client = makeClient(args);
     try {
         const info = await client.listKeys();
@@ -45,8 +19,20 @@ async function runKeyList(args) {
         failFromError(e);
     }
 }
+async function runKeyMint(args) {
+    assertKnownFlags(args, ...specFor("key", "mint"));
+    const client = makeClient(args);
+    try {
+        // The raw key is in this response ONCE and never again, so print it verbatim.
+        const minted = await client.mintKey();
+        printJson(minted);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
 async function runKeyRevoke(args) {
-    assertKnownFlags(args, NO_FLAGS, REVOKE_BOOLS, "homespun key revoke");
+    assertKnownFlags(args, ...specFor("key", "revoke"));
     if (!args.bools.has("yes")) {
         fail("'homespun key revoke' revokes YOUR OWN API key — it stops working " +
             "immediately and is irreversible. Pass --yes to confirm.", "confirmation_required");
@@ -70,13 +56,16 @@ export async function runKey(args) {
         case "list":
             await runKeyList(args);
             break;
+        case "mint":
+            await runKeyMint(args);
+            break;
         case "revoke":
             await runKeyRevoke(args);
             break;
         case undefined:
-            fail("missing verb — usage: homespun key <list|revoke> (run 'homespun key --help')", "invalid_args");
+            fail("missing verb; usage: homespun key <list|mint|revoke> (run 'homespun key --help')", "invalid_args");
             break;
         default:
-            fail(`unknown key verb '${sub}' — expected list|revoke (run 'homespun key --help')`, "invalid_args");
+            fail(`unknown key verb '${sub}', expected list|mint|revoke (run 'homespun key --help')`, "invalid_args");
     }
 }

package/dist/commands/logout.js

@@ -1,36 +1,10 @@
 // `homespun agent logout` — clear one (or all) saved profile(s).
 import { assertKnownFlags } from "../argv.js";
+import { specFor } from "../help-catalog.js";
 import { clearStore, readStore, removeProfile, resolveProfile, } from "../store.js";
 import { printJson, fail } from "../output.js";
-const NO_FLAGS = [];
-const KNOWN_BOOLS = ["all"];
-export const logoutHelp = `homespun agent logout — clear a saved profile (or all of them)
-
-Usage:
-  homespun agent logout [options]
-
-By default this clears the ACTIVE profile only (the one selected by --profile
-/ HOMESPUN_PROFILE / the store's current_profile). The on-disk file keeps the
-other profiles, and 'current_profile' is unset so the next command falls back
-to env / default URL until another profile is selected.
-
-Pass --all to delete the whole config file (the pre-profile behaviour) — this
-wipes every profile, not just the active one. Idempotent — no error if there
-is nothing to clear.
-
-This only clears the LOCAL config. It does NOT revoke the key on the relay —
-keys keep working until revoked. To revoke a key server-side, use
-'homespun key revoke'.
-
-Options:
-  --profile <name>    Target this profile instead of the active one.
-  --all               Delete every profile (the whole config file).
-  -h, --help          Show this help.
-
-Output (stdout, JSON):
-  { cleared: true, profile, path }   (profile=null when --all)`;
 export async function runLogout(args) {
-    assertKnownFlags(args, NO_FLAGS, KNOWN_BOOLS, "homespun agent logout");
+    assertKnownFlags(args, ...specFor("agent", "logout"));
     if (args.bools.has("all")) {
         // Nuke everything — file gone, both legacy and new shape covered.
         const path = clearStore();

package/dist/commands/members.js

@@ -14,43 +14,18 @@
 // authorizable — was removed in PR 2c-1 along with the rest of the v1
 // Template subsystem.)
 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 const membersHelp = `homespun members — app membership management
-
-Usage:
-  homespun members add    --app <idOrSlug> --email <email> [--role member]
-  homespun members list   --app <idOrSlug>
-  homespun members remove --app <idOrSlug> --human <humanId>
-
---app accepts either the app_id or its slug (resolved via GET /v1/apps?slug=
-when it doesn't look like a cuid).
-
-add: if a Human already exists for --email, the member row is attached
-immediately and the response is { member: { humanId, email, role,
-createdAt } }. Otherwise the relay mints a signed invite and emails a magic
-link, responding { ok: true, invited, expires_at }. Only "member" is a valid
---role (the default); ownership transfer is not available here. Fails with
-a relay error (503 auth_provider_unavailable) if the relay has no email
-provider configured.
-
-list: returns { members: [{ humanId, email, role, createdAt }] } — the
-app's owner plus every attached member.
-
-remove: idempotent; also revokes the human's live sessions on this app. The
-app owner cannot be removed (the relay refuses with a 409 conflict).
-
-Output (JSON). Errors on stderr:
-{"error":{"code","message"}} with non-zero exit.`;
 export async function runMembers(args) {
     const verb = args.positionals[0];
     if ((verb === undefined || verb === "help") && args.bools.has("help")) {
-        process.stdout.write(membersHelp + "\n");
+        process.stdout.write(renderNounHelp(nounSpec("members")) + "\n");
         return;
     }
     if (verb === undefined) {
-        fail("missing verb — homespun members <add|list|remove>", "invalid_args");
+        fail("missing verb — homespun members <add|list|set-role|remove|roles>", "invalid_args");
     }
     const sub = {
         positionals: args.positionals.slice(1),
@@ -65,17 +40,21 @@ export async function runMembers(args) {
             return runAdd(sub);
         case "list":
             return runList(sub);
+        case "set-role":
+            return runSetRole(sub);
         case "remove":
             return runRemove(sub);
+        case "roles":
+            return runRoles(sub);
         default:
-            fail(`unknown verb '${verb}' — homespun members <add|list|remove>`, "invalid_args");
+            fail(`unknown verb '${verb}' — homespun members <add|list|set-role|remove|roles>`, "invalid_args");
     }
 }
 // ---------------------------------------------------------------------------
 // add
 // ---------------------------------------------------------------------------
 async function runAdd(args) {
-    assertKnownFlags(args, ["app", "email", "role", "url", "api-key"], ["help"], "homespun members add");
+    assertKnownFlags(args, ...specFor("members", "add"));
     const appArg = args.flags.get("app");
     if (!appArg) {
         fail("usage: homespun members add --app <idOrSlug> --email <email> [--role member]", "invalid_args");
@@ -104,7 +83,7 @@ async function runAdd(args) {
 // list
 // ---------------------------------------------------------------------------
 async function runList(args) {
-    assertKnownFlags(args, ["app", "url", "api-key"], ["help"], "homespun members list");
+    assertKnownFlags(args, ...specFor("members", "list"));
     const appArg = args.flags.get("app");
     if (!appArg) {
         fail("usage: homespun members list --app <idOrSlug>", "invalid_args");
@@ -119,10 +98,45 @@ async function runList(args) {
     }
 }
 // ---------------------------------------------------------------------------
+// set-role
+// ---------------------------------------------------------------------------
+async function runSetRole(args) {
+    assertKnownFlags(args, ...specFor("members", "set-role"));
+    const appArg = args.flags.get("app");
+    if (!appArg) {
+        fail("usage: homespun members set-role --app <idOrSlug> --human <humanId> (--custom-role <name> | --clear-role)", "invalid_args");
+    }
+    const humanId = args.flags.get("human");
+    if (!humanId) {
+        fail("--human is required", "invalid_args");
+    }
+    // Clearing a role is a real instruction, so it gets its own explicit flag
+    // rather than being spelled as an omitted or empty --custom-role: an omitted
+    // value must never silently wipe someone's role.
+    const customRole = args.flags.get("custom-role");
+    const clear = args.bools.has("clear-role");
+    if (clear && customRole !== undefined) {
+        fail("--custom-role and --clear-role are mutually exclusive", "invalid_args");
+    }
+    if (!clear && customRole === undefined) {
+        fail("one of --custom-role <name> or --clear-role is required", "invalid_args");
+    }
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        printJson(await client.setAppMemberRole(appId, humanId, {
+            customRole: clear ? null : customRole,
+        }));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+// ---------------------------------------------------------------------------
 // remove
 // ---------------------------------------------------------------------------
 async function runRemove(args) {
-    assertKnownFlags(args, ["app", "human", "url", "api-key"], ["help"], "homespun members remove");
+    assertKnownFlags(args, ...specFor("members", "remove"));
     const appArg = args.flags.get("app");
     if (!appArg) {
         fail("usage: homespun members remove --app <idOrSlug> --human <humanId>", "invalid_args");
@@ -141,3 +155,21 @@ async function runRemove(args) {
         failFromError(e);
     }
 }
+// ---------------------------------------------------------------------------
+// roles
+// ---------------------------------------------------------------------------
+async function runRoles(args) {
+    assertKnownFlags(args, ...specFor("members", "roles"));
+    const appArg = args.flags.get("app");
+    if (!appArg) {
+        fail("usage: homespun members roles --app <idOrSlug>", "invalid_args");
+    }
+    const client = makeClient(args);
+    const appId = await resolveAppId(client, appArg);
+    try {
+        printJson(await client.listAppRoles(appId));
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}